Integrator Guide

Public API Surface

View as Markdown

AICR is both a CLI and a Go library. This page documents the stability contract for every exported Go package. External consumers should prefer the github.com/NVIDIA/aicr/pkg/client/v1 facade described in the Go library integration guide.

Stability tiers

TierMeaning
Public (stable)Covered by semver; breaking changes only in major bumps.
Public (evolving)Exported today but may change in minor bumps. Pin and audit on upgrade.
InternalTreated as implementation detail. May change without notice.

Package matrix

PackageTierPurpose
github.com/NVIDIA/aicr/pkg/client/v1Public (stable)Facade: Client, NewClient, request/result types, source constructors.
pkg/recipePublic (evolving)Recipe resolution, criteria, overlay system, component registry.
pkg/bundlerPublic (evolving)Per-component Helm/Kustomize bundle generation.
pkg/validatorPublic (evolving)Constraint evaluation, three-phase validation (executed in order: Deployment, Conformance, Performance).
pkg/collectorPublic (evolving)Observed state collection from clusters.
pkg/measurementPublic (evolving)Typed measurement model used by collectors and validators.
pkg/versionPublic (evolving)Semver constraint evaluation.
pkg/errorsPublic (evolving)Structured errors with error codes. Consumed at API boundaries.
pkg/defaultsPublic (evolving)Shared timeout and limit constants.
pkg/componentInternalBundler utilities and test helpers.
pkg/constraintsInternalConstraint type definitions.
pkg/bomInternalBill-of-materials / image inventory generation.
pkg/configInternalConfig-file loading and flag/spec resolution.
pkg/corroborateInternalCross-source corroboration of observed state.
pkg/diffInternalStructural diff between two snapshots.
pkg/fingerprintInternalCluster/provider fingerprint detection.
pkg/healthInternalHealth-check orchestration.
pkg/helmInternalHelm chart rendering helpers.
pkg/mirrorInternalChart/image mirroring to air-gapped registries.
pkg/netutilInternalNetworking utilities.
pkg/snapshotterPublic (evolving)Snapshot orchestration. The facade exposes its own Snapshot and AgentConfig types; pkg/snapshotter is the underlying implementation.
pkg/serializerInternalYAML/JSON serialization helpers.
pkg/manifestInternalHelm-compatible manifest rendering.
pkg/evidenceInternalConformance evidence capture.
pkg/trustInternalSigstore / provenance integration.
pkg/k8sInternalKubernetes client utilities.
pkg/ociInternalOCI registry helpers.
pkg/loggingInternalLogging setup.
pkg/headerInternalHTTP header helpers.
pkg/buildInternalBuild-time metadata.
pkg/serverInternalaicrd HTTP server: middleware chain and REST handlers (thin adapters over pkg/client/v1). Consumers use the HTTP API, not the Go types.
pkg/cliInternalCLI command implementations.

Facade type ownership

The github.com/NVIDIA/aicr/pkg/client/v1 package is Public (stable). Types reachable from this surface are either facade-owned structs or transparent aliases — the table below documents which.

Facade symbolTranslates to/fromNotes
aicr.Snapshotpkg/snapshotter.SnapshotFacade-owned struct. Public fields are identifying metadata; full measurement payload is preserved in an unexported field for round-trip through ValidateState. Use aicr.WrapSnapshot to lift a *snapshotter.Snapshot loaded externally.
aicr.AgentConfigpkg/snapshotter.AgentConfigFacade-owned struct covering the deployment-time agent fields. Tolerations keeps k8s.io/api/core/v1.Toleration since k8s.io is itself a stable contract. It does not mirror every pkg/snapshotter.AgentConfig field — the network-collector fields ClusterConfigPath and DiscoverNetwork are not surfaced on the facade type.
aicr.PhaseResultpkg/validator.PhaseResultFacade-owned struct. Exposes Summary (CTRF counts) and RawReport (CTRF JSON bytes); Report *ctrf.Report is retained for in-tree consumers that merge per-phase reports.
aicr.Phase, aicr.PhaseDeployment / PhasePerformance / PhaseConformancestring constsFacade-owned. Values match pkg/validator/v1 constants verbatim for byte-identical wire round-trip.
aicr.ReportSummarypkg/validator/ctrf.SummaryFacade-owned struct with the CTRF count fields.
aicr.ValidateOptionpkg/validator.OptionFacade-owned functional-option type that captures into an internal struct and translates at call time.
aicr.RecipeResultpkg/recipe.RecipeResultFacade-owned struct exposing Name, Version, TranslatedAt, and Components. Call Resolved() for the full upstream *pkg/recipe.RecipeResult (constraints, deployment order, validation config, metadata). The previous aicr.Recipe alias was removed in #1115; ResolveRecipeFromCriteria and ResolveRecipeFromSnapshot now return *RecipeResult.
aicr.AllowListspkg/recipe.AllowListsFacade-owned struct with []string fields (Accelerators / Services / Intents / OSTypes). Use aicr.WrapAllowLists to lift a *pkg/recipe.AllowLists.
aicr.Criteriapkg/recipe.CriteriaFacade-owned struct whose enum-typed fields (Service / Accelerator / Intent / OS / Platform) project to plain strings; Nodes stays an int per the facade’s string/int contract. Use aicr.WrapCriteria to lift a *pkg/recipe.Criteria.
aicr.CriteriaRegistrypkg/recipe.CriteriaRegistryDocumented transparent alias. Kept as an alias intentionally because the registry is behavior-rich (ParseService, SetStrict, Values, …) and carries mutable per-DataProvider state — wrapping would either break the per-Client identity coupling (copy) or add no isolation win over the alias (pointer).
  1. Use github.com/NVIDIA/aicr/pkg/client/v1 for all library integration by default.
  2. If the facade does not yet expose a feature you need, open an issue against NVIDIA/aicr describing the missing capability — we’d rather extend the facade than have external consumers hard-couple to evolving subpackages.
  3. If you must import a Public (evolving) subpackage, pin AICR to a patch version and audit diffs when upgrading.
  4. Never import a package marked Internal — upgrades will break you.

See also