aicr

func (*Client) AdoptRecipe ¶

func (c *Client) AdoptRecipe(ctx context.Context, rec *recipe.RecipeResult) (*RecipeResult, error)

AdoptRecipe wraps a raw pkg/recipe.RecipeResult — typically decoded from an external source such as a REST /v1/bundle POST body — into a Client-owned *RecipeResult ready for MakeBundle. The returned RecipeResult is bound to this Client's DataProvider and owner-stamped, so it passes MakeBundle's ownership and provider-isolation checks exactly as a LoadRecipe result does.

Use this when the caller already holds a fully-hydrated RecipeResult (not a criteria request or a file path) and needs to bundle it through the facade. In-process consumers that resolve via ResolveRecipe / LoadRecipe should use those results directly; AdoptRecipe is for the decode-then-bundle boundary.

func (*Client) BundleComponents ¶

func (c *Client) BundleComponents(ctx context.Context, r *RecipeResult) ([]ComponentBundle, error)

BundleComponents resolves Helm values and rendered manifests for each component in a previously-resolved RecipeResult. The returned slice mirrors r.Components 1:1 — same order, same length — so callers correlate by index.

When to call ¶

Call AFTER ResolveRecipe; pass that call's *RecipeResult unchanged. BundleComponents reads the internal pkg/recipe.RecipeResult that ResolveRecipe attached to the facade RecipeResult — it does NOT re-resolve from criteria. A RecipeResult constructed by the caller (rather than returned from ResolveRecipe) has a nil internal field and BundleComponents returns ErrCodeInvalidRequest.

Per-Client DataProvider isolation ¶

Both values-file reads (Helm components) and manifest-file reads (Helm supplemental + Kustomize) are bound to this Client's own DataProvider via the WithProvider variants on the recipe package (recipe.RecipeResult.GetValuesForComponentWithProvider, recipe.GetManifestContentWithProvider). Two Clients constructed from different recipe sources can BundleComponents concurrently without contaminating each other's bundle output.

History: pre-v0.2 the values and manifest paths short-circuited through recipe.GetDataProvider() — the process-global DataProvider singleton. With two Clients A and B pointing at different sources, an eviction+repopulate sequence on A's cache followed by a B BundleComponents call could return values or manifests resolved against A's recipe source. That gap is closed; the metadata store and component registry were already per-Client at the time and stayed correct throughout, so ResolveRecipe results never drifted.

Read-once value coherence ¶

Each component's effective Helm values are resolved exactly once per call, and that same snapshot feeds the accounting check, the registry-declared component validations (including the gpu-operator driver-ownership coherence gate), and the returned ComponentBundle. A DataProvider need not be stable — LayeredDataProvider re-reads external --data files on every call — so a gate that resolved values independently could validate one set of values while a different set was returned. Pinning the snapshot removes that window: what the gates examined is what you get back (issue #1873 item A).

Synchronization ¶

Read-locks Client.mu so a concurrent Close can't race the values load. The lock is held only across the snapshot of c.builder and c.dp; the values and manifest reads themselves run unlocked (consistent with ResolveRecipe's pattern). The DataProvider snapshot is the per-Client provider this Client owns — the same one its Builder is bound to via recipe.WithDataProvider.

func (*Client) Close ¶

func (c *Client) Close() error

Close releases this Client's cached metadata store, component registry, and criteria registry from the recipe package's internal caches. Call when a Client is no longer needed (cache eviction in a higher-level memoiser, controller shutdown) to prevent unbounded memory growth — the recipe package keys its caches on DataProvider identity and does not auto-evict, so a process that observes many distinct recipe sources over time would otherwise grow memory monotonically.

Safe to call on a nil receiver and safe to call concurrently or multiple times. Every non-nil caller waits for the same teardown and receives the same cached cleanup result. OCI-backed Clients remove only the private child workspace they own; a removal failure is returned with its structured code.

func (*Client) CollectSnapshot ¶

func (c *Client) CollectSnapshot(ctx context.Context, cfg *AgentConfig) (*Snapshot, error)

CollectSnapshot deploys the snapshotter Job to the cluster identified by cfg.Kubeconfig and returns the captured Snapshot.

This is the single Job-mode collection path in the tree: `aicr snapshot` and `aicr validate` both run it, so the facade AgentConfig mirror is exercised on every snapshot AICR takes.

CollectSnapshot does NOT consult the Client's recipe data provider — the Client is required only to keep the facade surface uniform (every public operation goes through a Client) and to leave room for future per-Client telemetry hooks or cluster-connection caching without breaking signatures. CollectSnapshot is therefore safe even on a Client whose recipe source is unrelated to the target cluster.

cfg.Kubeconfig is the path (or empty for in-cluster).

Required and defaulted fields ¶

cfg.Namespace is the only field you must set: it is where the Job, its RBAC, and the result ConfigMap are created, and deploying a privileged cluster-reading Job into an unstated namespace is not a safe default. An empty one is rejected with ErrCodeInvalidRequest before any cluster access.

cfg.Image is defaulted when empty to the tag matching this Client's WithVersion (a Client with no version, like a development build, gets :latest). Set it explicitly to pin a different agent generation or a mirrored registry.

cfg.JobName and cfg.ServiceAccountName are optional naming PREFIXES, not exact names. Leaving them empty is fine: cfg.NameBase (default defaults.AgentName) supplies the prefix instead. cfg.RunID is appended to whichever prefix applies, so two callers that both omit these names still get distinct objects rather than shared ones — see Concurrency. Other fields fall back to the defaults documented on snapshotter.AgentConfig.

One exception to the prefix rule, because it is the point of the mode: a cfg.ServiceAccountName that names a ServiceAccount already present in cfg.Namespace is used VERBATIM, and this call then creates and deletes no RBAC at all. That is how a caller runs the agent under an IRSA or Workload Identity account, whose cloud trust is pinned to the account name and so cannot survive a run-scoped rename. It waives per-run permission isolation: concurrent runs sharing that account share its grants.

Output and delivery ¶

The returned Snapshot carries both the parsed form and, in Snapshot.Raw, the exact bytes the agent emitted. CollectSnapshot does not write them anywhere except when cfg.Output names a ConfigMap (cm://namespace/name), which the Job writes directly. Persisting to a file, stdout, or a Go template is the caller's step — pass Snapshot.Raw to snapshotter.DeliverSnapshot, as `aicr snapshot` does. Delivering Raw rather than re-serializing the parsed snapshot is what keeps the output byte-identical to the agent's when a newer agent image emits fields this binary does not model.

Fail-before-mutate ¶

Inputs that can be rejected without contacting the cluster are checked before the Kubernetes client is built, so a rejection never leaves RBAC or a Job behind (with cfg.Cleanup false — the zero value — they would persist). That covers a malformed cfg.Output ConfigMap URI and a non-empty cfg.ClusterConfigPath, both ErrCodeInvalidRequest.

Deliberately outside this method ¶

Two snapshot capabilities are NOT reachable through CollectSnapshot, by design, because neither deploys a Job:

• Local (in-pod) collection — the mode the agent container itself runs under AICR_AGENT_MODE=true, and the dev bypass of the same name. It runs collectors in-process against the local node instead of deploying an agent, so it needs a collector.Factory and a serializer.Serializer, types the semver-stable facade deliberately does not expose. Use snapshotter.NodeSnapshotter directly, as pkg/cli/snapshot.go does. It takes no AgentConfig, so leaving it out costs no coverage of the field mirror: every deployed Job still projects through this method.
• cfg.ClusterConfigPath — an l8k cluster-config.yaml ingested by the in-pod network collector. The path must resolve inside the pod and the Job does not mount it, so Job mode rejects a non-empty value with ErrCodeInvalidRequest. Use cfg.DiscoverNetwork for live discovery from a Job, or the local mode above to read a host file.

Timeout ¶

The operation is bounded by cfg.Timeout + defaults.SnapshotOperationGrace (or defaults.SnapshotOperationTimeout + grace when cfg.Timeout is unset), so a caller passing context.Background() still gets a bounded run. The grace exists because cfg.Timeout budgets Job completion only — deployment and result retrieval sit outside it, and a bare cap would silently shrink the completion budget. A tighter caller deadline always wins.

Errors:

• ErrCodeInvalidRequest when the Client is nil, cfg is nil, or the Client has been Closed.
• All snapshotter errors propagate unwrapped — they already carry the appropriate pkg/errors codes (ErrCodeInternal for deployment failures, ErrCodeTimeout for context expiry, etc.).

Concurrency ¶

Concurrent CollectSnapshot calls are safe, at the Client level and against the same cluster. Each call gets its own RunID (cfg.RunID when set, otherwise generated) and, from it, its own Job, ServiceAccount, Role, RoleBinding, ClusterRole, ClusterRoleBinding and — when cfg.Output does not name one — its own staging ConfigMap. Every object is deleted under a UID precondition recorded when this run created it, so no run can delete something another run owns. This replaces the earlier one-at-a-time constraint (#2120).

Two effects remain shared, both by design:

• Two calls that set cfg.Output to the SAME explicit cm://namespace/name URI write to that one caller-named ConfigMap and overwrite each other. Output identifies a caller-owned destination, not a run-scoped one, so RunID does not disambiguate it.
• Two calls naming the same existing cfg.ServiceAccountName run under that one identity and share its grants, since neither creates RBAC.

package main

import (
	"context"
	"log"
	"os"

	aicr "github.com/NVIDIA/aicr/pkg/client/v1"
)

func main() {
	ctx := context.Background()

	client, err := aicr.NewClient(aicr.WithRecipeSource(aicr.EmbeddedSource()))
	if err != nil {
		log.Print(err)
		return
	}
	defer func() { _ = client.Close() }()

	snap, err := client.CollectSnapshot(ctx, &aicr.AgentConfig{
		Namespace:          "aicr-system",
		Image:              "ghcr.io/nvidia/aicr:v0.19.0",
		JobName:            "aicr",
		ServiceAccountName: "aicr",
		Cleanup:            true,
	})
	if err != nil {
		log.Print(err)
		return
	}

	// Persist Raw rather than re-serializing: a newer agent image can emit
	// fields this binary's Snapshot type does not model, and a typed round
	// trip silently drops them.
	if err = os.WriteFile("snapshot.yaml", snap.Raw, 0o600); err != nil {
		log.Print(err)
		return
	}
}

Output:

func (*Client) ComputeHealth ¶ added in v0.15.0

func (c *Client) ComputeHealth(ctx context.Context, filter *Criteria) (*health.Report, error)

ComputeHealth scores the structural health of every leaf recipe in this Client's catalog and returns a deterministic *health.Report, optionally narrowed by filter. Computation is delegated wholesale to pkg/health.Compute; this facade only binds the Client's own DataProvider and version so health is scored against the same catalog (including any --data overlays) the Client resolves with — never the process-global embedded catalog.

filter narrows enumeration to leaf overlays carrying every explicitly set criteria dimension; nil scores all leaf combos. Empty/"any" filter dimensions place no constraint.

health.Compute applies its own catalog-wide timeout (defaults.HealthComputeTimeout), so this method does not impose the shorter per-operation timeout the resolve methods use.

Returns ErrCodeInvalidRequest on a nil/closed Client or nil context, and propagates the underlying structured code (or ErrCodeInternal) if health computation fails.

func (*Client) CriteriaFromSnapshot ¶ added in v0.21.0

func (c *Client) CriteriaFromSnapshot(snap *Snapshot) (*Criteria, error)

CriteriaFromSnapshot derives recipe criteria from a snapshot's measurements.

This is the snapshot-to-recipe entry point. Without it the workflow could not be completed through pkg/client/v1 alone: the CLI reached into pkg/fingerprint and pkg/recipe to do this, and the integrator guide had to document that escape hatch, which contradicts this package's promise to be the whole integration surface (#2437, #2016).

Criteria are parsed against this Client's provider-scoped registry, so an external --data catalog that registers its own accelerator or service values resolves them the same way the Client will when it resolves the recipe. A package-level helper could not do that.

The returned criteria are a starting point, not a verdict: callers layer config and flag overrides on top before resolving. Every dimension the snapshot could not determine is left as the "any" wildcard rather than guessed.

Returns ErrCodeInvalidRequest for a nil snapshot, since a caller asking for criteria from nothing has a bug rather than an empty result.

package main

import (
	"context"
	"fmt"
	"log"

	aicr "github.com/NVIDIA/aicr/pkg/client/v1"
)

func main() {
	ctx := context.Background()

	client, err := aicr.NewClient(aicr.WithRecipeSource(aicr.EmbeddedSource()))
	if err != nil {
		log.Print(err)
		return
	}
	defer func() { _ = client.Close() }()

	snap, err := client.LoadSnapshot(ctx, "snapshot.yaml", "")
	if err != nil {
		log.Print(err)
		return
	}

	// Every dimension the snapshot could not determine stays "any"; nothing is
	// guessed. Layer your own stated values on top before resolving.
	criteria, err := client.CriteriaFromSnapshot(snap)
	if err != nil {
		log.Print(err)
		return
	}
	criteria.Intent = "training"

	result, err := client.ResolveRecipeFromCriteria(ctx, criteria)
	if err != nil {
		log.Print(err)
		return
	}
	fmt.Printf("resolved %d components\n", len(result.Components))
}

Output:

func (*Client) CriteriaRegistry ¶

func (c *Client) CriteriaRegistry() *CriteriaRegistry

CriteriaRegistry returns the per-DataProvider criteria registry for THIS Client. CLI/library callers use it to parse criteria values (so --data overlay contributions validate) and to apply strict mode against the same provider the Client resolves with. Call LoadCatalog first so the registry is seeded from the provider's overlays before parsing.

Returns the registry for this Client's provider via recipe.GetCriteriaRegistryFor. On a nil or closed Client this returns a fresh ephemeral registry so callers can defensively call without nil-checking, matching the existing lenient accessor behavior.

func (*Client) DiffSnapshots ¶ added in v0.20.0

func (c *Client) DiffSnapshots(
	ctx context.Context,
	baseline, target *Snapshot,
	opts SnapshotDiffOptions,
) (*SnapshotDiff, error)

DiffSnapshots compares two facade snapshots in memory.

Both snapshots must carry a usable measurement payload from LoadSnapshot, CollectSnapshot, or WrapSnapshot. A hand-constructed Snapshot has no such payload; a wrapped payload containing no typed measurement is equally unusable. Both are rejected rather than being reported as a false no-drift result. Source labels in opts are copied to the result for JSON, YAML, and table consumers; they do not influence comparison semantics.

The operation performs no cluster, filesystem, or recipe-catalog I/O and adds no facade timeout. The caller's context governs unchanged.

package main

import (
	"context"
	"fmt"
	"log"

	aicr "github.com/NVIDIA/aicr/pkg/client/v1"
)

func main() {
	ctx := context.Background()

	client, err := aicr.NewClient(aicr.WithRecipeSource(aicr.EmbeddedSource()))
	if err != nil {
		log.Print(err)
		return
	}
	defer func() { _ = client.Close() }()

	baseline, err := client.LoadSnapshot(ctx, "before.yaml", "")
	if err != nil {
		log.Print(err)
		return
	}
	target, err := client.LoadSnapshot(ctx, "after.yaml", "")
	if err != nil {
		log.Print(err)
		return
	}

	result, err := client.DiffSnapshots(ctx, baseline, target, aicr.SnapshotDiffOptions{
		BaselineSource: "before.yaml",
		TargetSource:   "after.yaml",
	})
	if err != nil {
		log.Print(err)
		return
	}
	if result.HasDrift() {
		fmt.Printf("detected %d change(s)\n", result.Summary.Total)
	}
}

Output:

func (*Client) EmitRecipeEvidence ¶ added in v0.16.0

func (c *Client) EmitRecipeEvidence(
	ctx context.Context,
	rec *RecipeResult,
	snap *Snapshot,
	results []*PhaseResult,
	opts EvidenceOptions,
) error

EmitRecipeEvidence builds (and optionally pushes) a recipe-evidence attestation bundle from a completed validation run — predicateType v1 for unprofiled recipes, v2 when the recipe carries a configuration profile (metadata.selectedProfile). It is the facade counterpart to the logic the CLI previously assembled inline: it converts the facade PhaseResults back to the internal shape, loads the validator catalog against THIS Client's data source and version, and delegates to the evidence attestation package.

Interactive keyless-signing disclosure is intentionally NOT performed here — that is a UI concern the caller handles (the CLI prompts before calling). This method does no prompting and can run unattended from a server/library.

func (*Client) ListCatalog ¶ added in v0.15.0

func (c *Client) ListCatalog(ctx context.Context, filter *Criteria) ([]CatalogEntry, error)

ListCatalog returns catalog entries for all overlays known to this Client, optionally narrowed by the filter criteria. Call LoadCatalog first so the catalog is fully populated before calling this.

Each entry carries the overlay name, its criteria, whether it is a leaf (IsLeaf=true means no other overlay inherits from it), its data provenance ("embedded" or "external"), and its effective configuration profile — the declaration reachable from that overlay after inheritance and co-match resolution, nil when the overlay reaches none. Entries are returned in ascending name order for deterministic output.

When filter is non-nil, only overlays whose criteria carry the exact values specified in each non-empty/non-"any" filter dimension are returned. Setting a filter dimension to "" or "any" places no constraint on that dimension.

Returns ErrCodeInvalidRequest on a nil or closed Client, or when an overlay reachable from the filtered set declares an invalid profile — profile declarations are validated during projection, so a malformed declaration fails the whole call rather than yielding a partial catalog. Returns ErrCodeTimeout if ctx is canceled during projection, and propagates ErrCodeInternal if the underlying metadata store cannot be loaded.

func (*Client) LoadCatalog ¶

func (c *Client) LoadCatalog(ctx context.Context) error

LoadCatalog eagerly loads (and caches) this Client's metadata store, which has the side effect of seeding THIS Client's per-provider criteria registry from every overlay's spec.criteria. Call it before parsing criteria through CriteriaRegistry so values contributed by a FilesystemSource --data overlay are admitted by the registry's lookups.

This mirrors the pre-facade eager recipe.LoadCatalog the CLI ran after SetDataProvider, but seeds the Client's OWN provider registry rather than the process-global one — so two Clients built from different sources keep isolated criteria registries.

Errors propagate with their structured codes preserved (a malformed overlay surfaces as ErrCodeInvalidRequest, not masked as ErrCodeInternal) via PropagateOrWrap.

The same guards as the resolve methods apply: nil receiver and nil context are rejected with ErrCodeInvalidRequest, and a closed Client is rejected.

func (*Client) LoadRecipe ¶

func (c *Client) LoadRecipe(ctx context.Context, path, kubeconfig string) (*RecipeResult, error)

LoadRecipe loads a recipe from a file path (or cm:// ConfigMap URI, honoring kubeconfig) through THIS Client's data provider, and returns it as a Client-owned *RecipeResult ready for ValidateState / BundleComponents. Overlay inputs (kind: RecipeMetadata) are hydrated against the Client's provider, so an external --data overlay resolves against the same recipe source the Client was constructed with rather than the package global. An already-hydrated RecipeResult file is returned with its provider bound to the Client's provider.

The returned RecipeResult is owner-stamped with this Client, so it passes ValidateState / BundleComponents' assertOwns check — same as a RecipeResult produced by ResolveRecipe.

Errors:

• ErrCodeInvalidRequest when the Client is nil, ctx is nil, path is empty, or the Client has been Closed.
• All loader errors propagate with their structured codes (e.g., ErrCodeInvalidRequest for an overlay without criteria, ErrCodeInternal for a read or parse failure).

package main

import (
	"context"
	"fmt"
	"log"

	aicr "github.com/NVIDIA/aicr/pkg/client/v1"
)

func main() {
	ctx := context.Background()

	client, err := aicr.NewClient(aicr.WithRecipeSource(aicr.EmbeddedSource()))
	if err != nil {
		log.Print(err)
		return
	}
	defer func() { _ = client.Close() }()

	// A local file path, an HTTP(S) URL, or a cm://namespace/name ConfigMap
	// URI. The kubeconfig argument is consulted only for the cm:// form.
	result, err := client.LoadRecipe(ctx, "recipe.yaml", "")
	if err != nil {
		log.Print(err)
		return
	}
	fmt.Println(result.Name)
}

Output:

func (*Client) LoadSnapshot ¶ added in v0.20.0

func (c *Client) LoadSnapshot(ctx context.Context, path, kubeconfig string) (*Snapshot, error)

LoadSnapshot reads a previously captured snapshot and returns it in the facade shape, ready to hand to ValidateState, ResolveRecipeFromSnapshot, or EmitRecipeEvidence.

It is the counterpart to CollectSnapshot for the case an integrator hits far more often: the snapshot already exists. A pipeline captures cluster state in one stage and resolves or validates against it in another, or the snapshot is committed to a repository and replayed.

path accepts the same forms the CLI does — a local file, an HTTP(S) URL, or a cm://namespace/name ConfigMap URI. kubeconfig resolves the cm:// form; empty uses the standard KUBECONFIG, ~/.kube/config, then in-cluster discovery chain, and is ignored entirely for the other two.

Cluster access is therefore source-dependent: a local file or an HTTP(S) URL needs none, while a cm:// URI reads a ConfigMap through the Kubernetes API and needs working credentials for that cluster. Only CollectSnapshot needs a cluster unconditionally, since it deploys an agent Job.

The loader FAILS CLOSED on a document that is not a snapshot this build can consume: a wrong kind (an AICRConfig, say), or an apiVersion this binary does not understand. That matters because snapshot deserialization is non-strict — any YAML mapping would otherwise decode into a zero-value Snapshot, derive criteria(any), and silently produce a fallback recipe with exit 0. Empty kind and apiVersion are tolerated for snapshots that predate those fields.

Raw is not populated ¶

Snapshot.Raw carries the exact bytes a collection agent emitted and is set only by CollectSnapshot. A loaded snapshot leaves it empty, because the source is already the durable artifact — re-exposing its bytes here would invite callers to round-trip a stored snapshot through the parsed type, which is what Raw exists to discourage.

A caller needing the bytes can read the source again, but note what that does and does not give you: re-reading returns the source's CURRENT contents, which for a URL or a ConfigMap (and for a file someone rewrote) need not be the bytes this call parsed. If byte-for-byte identity with the loaded snapshot matters — hashing what you validated, say — capture the source contents yourself and load from that capture, rather than reading the source a second time afterwards.

This method does not touch the Client's recipe catalog, so any open Client will do; it hangs off Client to keep the surface uniform and to give config-driven loading a home.

func (*Client) MakeBundle ¶

func (c *Client) MakeBundle(ctx context.Context, recipe *RecipeResult, opts BundleOptions) (BundleArtifact, error)

MakeBundle generates the full deployer-mode bundle for a previously resolved or loaded RecipeResult, writing the bundle files under opts.OutputDir and returning a BundleArtifact summary. Unlike BundleComponents (which returns per-component Helm values + manifests in memory), MakeBundle produces the SAME complete artifact the CLI bundle command emits — README, deploy.sh, per-component directories, checksums — in the deployer layout selected by opts.Config.Deployer() (helm, argocd, argocd-helm, flux, helmfile).

When to call ¶

Call AFTER Client.ResolveRecipe or Client.LoadRecipe; pass that call's *RecipeResult unchanged. MakeBundle bundles from recipe.Resolved() (the full pkg/recipe.RecipeResult), which carries this Client's own DataProvider — so provider-scoped lookups (values files, manifest files) resolve against the Client's recipe source rather than the package global.

Allowlist enforcement ¶

When the Client was constructed WithAllowLists, MakeBundle validates the recipe's criteria against the allowlist before bundling — same fencing the resolve path and the REST /v1/bundle handler apply. A recipe whose criteria fall outside the allowlist is rejected with the allowlist's structured error. A recipe with nil Criteria (a loaded, already-hydrated or bare RecipeResult file) skips the check, matching the handler's `recipeResult.Criteria != nil` guard.

Synchronization ¶

Read-locks Client.mu so a concurrent Close can't race the bundle, and registers in the inflight WaitGroup so Close drains before evicting caches — the same protocol as BundleComponents. A facade-level timeout is opt-in via opts.Timeout: when set (> 0) it bounds the run by the smaller of opts.Timeout and any tighter caller deadline; when unset (0) MakeBundle runs under the caller's context with NO added cap. The REST /v1/bundle handler sets opts.Timeout = defaults.BundleHandlerTimeout to keep its 60s request boundary; the CLI bundle command leaves it 0 so large bundles, --vendor-charts, and attestation/signing are uncapped.

Errors:

• ErrCodeInvalidRequest when the Client, ctx, or recipe is nil, when recipe lacks internal state (constructed outside Resolve/Load), when the recipe was produced by a different Client, or when the Client has been Closed.
• Allowlist and bundler errors propagate with their structured codes.

func (*Client) MergeReports ¶ added in v0.16.0

func (c *Client) MergeReports(results []*PhaseResult) *ctrf.Report

MergeReports merges the per-phase CTRF reports from a ValidateState run into a single combined report, stamped with the tool name "aicr" and this Client's version. Library and server callers use it to produce the same combined CTRF document the CLI writes, without reaching into pkg/validator/ctrf merge internals. Nil results and phases with a nil Report contribute nothing.

func (*Client) MirrorInventory ¶ added in v0.21.0

func (c *Client) MirrorInventory(
	ctx context.Context,
	rec *RecipeResult,
	opts ...MirrorInventoryOption,
) (*MirrorInventory, error)

MirrorInventory discovers every container image and Helm chart a recipe references, by rendering its charts and scanning the resulting manifests.

This performs real work: it renders every component's chart. Callers should pass a context with a deadline appropriate to the recipe's size.

package main

import (
	"context"
	"fmt"
	"log"

	aicr "github.com/NVIDIA/aicr/pkg/client/v1"
)

func main() {
	ctx := context.Background()

	client, err := aicr.NewClient(aicr.WithRecipeSource(aicr.EmbeddedSource()))
	if err != nil {
		log.Print(err)
		return
	}
	defer func() { _ = client.Close() }()

	result, err := client.ResolveRecipeFromCriteria(ctx, &aicr.Criteria{
		Service:     "eks",
		Accelerator: "h100",
		Intent:      "training",
	})
	if err != nil {
		log.Print(err)
		return
	}

	// Pass the same overrides you will bundle with. Disabling a sub-component
	// removes its images, so mirroring without them stages the wrong set.
	disabled := "false"
	inventory, err := client.MirrorInventory(ctx, result,
		aicr.WithMirrorValueOverrides([]aicr.MirrorValueOverride{
			{Component: "gpuoperator", Path: "driver.enabled", Value: &disabled},
		}))
	if err != nil {
		log.Print(err)
		return
	}

	for _, image := range inventory.Images {
		fmt.Println(image)
	}
	for _, chart := range inventory.Charts {
		fmt.Printf("%s %s from %s\n", chart.Chart, chart.Version, chart.Repository)
	}
}

Output:

func (*Client) PublishEvidence ¶ added in v0.20.0

func (c *Client) PublishEvidence(ctx context.Context, opts EvidencePublishOptions) error

PublishEvidence signs and pushes an already-emitted on-disk evidence bundle, then writes pointer.yaml beside it.

It is the off-network second leg of the workflow whose first leg is an evidence-emitting validation run that did not push: that step produces the unsigned on-disk bundle this one consumes. Splitting them lets the cluster-bound step run where the cluster is reachable and the Sigstore-bound step run where Fulcio and Rekor are. The result is content-identical to the one-shot path, because the predicate signed here is read verbatim from the bundle's statement.intoto.json.

Interactive keyless-signing disclosure is intentionally NOT performed here, matching EmitRecipeEvidence: prompting is a UI concern the caller owns, and this method must be able to run unattended from a server or library.

package main

import (
	"context"
	"log"

	aicr "github.com/NVIDIA/aicr/pkg/client/v1"
)

func main() {
	ctx := context.Background()

	client, err := aicr.NewClient(aicr.WithRecipeSource(aicr.EmbeddedSource()))
	if err != nil {
		log.Print(err)
		return
	}
	defer func() { _ = client.Close() }()

	if err = client.PublishEvidence(ctx, aicr.EvidencePublishOptions{
		BundleDir: "./evidence",
		Push:      "ghcr.io/example/aicr-evidence:v1",
	}); err != nil {
		log.Print(err)
		return
	}
}

Output:

func (*Client) RecipeDigest ¶ added in v0.20.0

func (c *Client) RecipeDigest(ctx context.Context, opts RecipeDigestOptions) (string, error)

RecipeDigest returns the canonical digest of a resolved recipe — the lowercase hex SHA-256 of its canonical YAML, byte-for-byte the value stored in predicate.recipe.digest by an evidence-emitting validation run.

It is the producer-side companion to VerifyEvidence: a CI gate verifies a committed evidence pointer, reads predicate.recipe.digest out of the verified bundle, and compares it against RecipeDigest of the recipe on the branch to detect evidence that has gone stale.

Hydration resolves against THIS Client's DataProvider, so the digest reflects the same catalog the Client would resolve and validate with.

package main

import (
	"context"
	"fmt"
	"log"

	aicr "github.com/NVIDIA/aicr/pkg/client/v1"
)

func main() {
	ctx := context.Background()

	client, err := aicr.NewClient(aicr.WithRecipeSource(aicr.EmbeddedSource()))
	if err != nil {
		log.Print(err)
		return
	}
	defer func() { _ = client.Close() }()

	digest, err := client.RecipeDigest(ctx, aicr.RecipeDigestOptions{
		Path: "recipe.yaml",
	})
	if err != nil {
		log.Print(err)
		return
	}
	fmt.Println(digest)
}

Output:

func (*Client) ResolveRecipe ¶

func (c *Client) ResolveRecipe(ctx context.Context, req RecipeRequest) (*RecipeResult, error)

ResolveRecipe maps a RecipeRequest to a concrete validated recipe. It wraps pkg/recipe.Builder.BuildFromCriteria with a stable external request shape so AICR's internal Criteria type can evolve without breaking consumers.

Pinned recipe references (req.PinnedName / req.PinnedVersion) are not yet supported by the facade and return ErrCodeUnavailable. The field is reserved so callers can adopt it without API churn when the underlying builder gains pinning support.

func (*Client) ResolveRecipeFromCriteria ¶

func (c *Client) ResolveRecipeFromCriteria(ctx context.Context, criteria *Criteria) (*RecipeResult, error)

ResolveRecipeFromCriteria resolves a facade Criteria into a facade RecipeResult. The Components projection mirrors ResolveRecipe; callers needing the full upstream recipe (constraints, deployment order, metadata) access it via the returned result's Resolved() helper.

Use this when the caller already speaks the facade Criteria type (e.g., a REST handler that parsed criteria from an HTTP request and translated via WrapCriteria) rather than the RecipeRequest shape ResolveRecipe takes.

Allowlist enforcement (WithAllowLists) applies here just as it does on the shared resolve path: criteria outside the configured allowlist are rejected before the recipe is built.

The same guards and synchronization as ResolveRecipe apply: nil receiver, nil context, and nil criteria are rejected with ErrCodeInvalidRequest; a closed Client is rejected; a facade-level timeout bounds the resolve.

func (*Client) ResolveRecipeFromCriteriaWithOptions ¶ added in v0.19.0

func (c *Client) ResolveRecipeFromCriteriaWithOptions(
	ctx context.Context,
	criteria *Criteria,
	opts ...RecipeResolveOption,
) (*RecipeResult, error)

ResolveRecipeFromCriteriaWithOptions is ResolveRecipeFromCriteria with optional per-resolution behavior such as profile selection and Slurm accounting ownership.

func (*Client) ResolveRecipeFromCriteriaWithProfile ¶ added in v0.19.0

func (c *Client) ResolveRecipeFromCriteriaWithProfile(
	ctx context.Context,
	criteria *Criteria,
	profile string,
) (*RecipeResult, error)

ResolveRecipeFromCriteriaWithProfile resolves criteria with an optional name=value profile selection.

func (*Client) ResolveRecipeFromSnapshot ¶

func (c *Client) ResolveRecipeFromSnapshot(ctx context.Context, criteria *Criteria, snap *Snapshot) (*RecipeResult, error)

ResolveRecipeFromSnapshot resolves a recipe from explicit Criteria and evaluates its constraints against an observed cluster Snapshot, mirroring `aicr recipe --snapshot`. It returns the facade RecipeResult; callers needing the upstream recipe (ComponentRefs, deployment order, per- constraint evaluation results) access it via Resolved().

Unlike ResolveRecipeFromCriteria — which builds the recipe without observing the cluster — this variant threads a constraint evaluator that runs each resolution constraint against snap via pkg/constraints.Evaluate. The CLI's `recipe --snapshot` path does the same: it derives criteria from the snapshot fingerprint, then calls BuildFromCriteriaWithEvaluator so the resolved recipe records whether each constraint passed against the observed state.

Allowlist enforcement (WithAllowLists) applies here just as it does on the shared resolve path: criteria outside the configured allowlist are rejected before the recipe is built.

The criteria-coverage post-condition (issue #1542) is STRICT by default here: every stated criteria dimension must be honored by an applied overlay or resolution fails with ErrCodeInvalidRequest carrying details.uncovered.

To reproduce `aicr recipe --snapshot`, which additionally relaxes dimensions derived from the snapshot fingerprint and retries once, pass WithSnapshotCriteriaRelaxation and name the dimensions you received explicitly:

result, err := client.ResolveRecipeFromSnapshotWithOptions(ctx, criteria, snap,
    aicr.WithSnapshotCriteriaRelaxation(aicr.DimensionIntent))

Only the caller knows which dimensions a user stated versus which it derived, so the facade cannot infer that — but it does accept it as a parameter and applies the policy itself. Dimensions actually cleared are reported in RecipeResult.RelaxedDimensions.

The same guards and synchronization as ResolveRecipeFromCriteria apply: nil receiver, nil context, nil criteria, and nil snapshot are rejected with ErrCodeInvalidRequest; a closed Client is rejected; a facade-level timeout bounds the resolve. Builder errors propagate as-is (they already carry the appropriate pkg/errors code) rather than being re-wrapped.

func (*Client) ResolveRecipeFromSnapshotWithOptions ¶ added in v0.19.0

func (c *Client) ResolveRecipeFromSnapshotWithOptions(
	ctx context.Context,
	criteria *Criteria,
	snap *Snapshot,
	opts ...RecipeResolveOption,
) (*RecipeResult, error)

ResolveRecipeFromSnapshotWithOptions is ResolveRecipeFromSnapshot with optional per-resolution behavior such as profile selection and Slurm accounting ownership.

func (*Client) ResolveRecipeFromSnapshotWithProfile ¶ added in v0.19.0

func (c *Client) ResolveRecipeFromSnapshotWithProfile(
	ctx context.Context,
	criteria *Criteria,
	snap *Snapshot,
	profile string,
) (*RecipeResult, error)

ResolveRecipeFromSnapshotWithProfile is the snapshot-filtered profile resolution path.

func (*Client) SignCatalog ¶ added in v0.20.0

func (c *Client) SignCatalog(ctx context.Context, opts CatalogSignOptions) (*CatalogSignResult, error)

SignCatalog computes the deterministic digest over this Client's recipe catalog (registry.yaml plus validators/catalog.yaml), signs it via Sigstore keyless OIDC, and optionally writes the resulting bundle to opts.Output. VerifyCatalog is its counterpart.

As with VerifyCatalog, the digest is computed over THIS Client's DataProvider, so what gets signed is the catalog the Client resolves with.

Signing modes are constrained to what VerifyCatalog can verify ¶

VerifyCatalog verifies against the public-good Sigstore root, requires a transparency-log entry, and pins the certificate to the GitHub Actions OIDC issuer. It exposes no key, no trust-root, and no offline option, because the recipe catalog is a release artifact NVIDIA signs — not something a consumer re-signs privately.

SignCatalog therefore REJECTS the four OIDCResolve settings that would produce a signature its own counterpart could not check:

• SigningKey — a key-signed catalog has no verification path at all.
• FulcioURL — a certificate from a private CA does not chain to the public-good root.
• RekorURL — an entry in a private transparency log cannot be verified against the public-good root either. The flag can name a public-good v1 URL as well, which would verify, but the two are indistinguishable from the URL alone, so this fails closed.
• DisableTLogUpload — verification requires a transparency-log entry.

Each is rejected with ErrCodeInvalidRequest before any signing work runs, so the failure is immediate and explains itself rather than surfacing later as an unverifiable artifact.

SigningConfigPath is checked rather than rejected. It passes through because the release path requires it — naming the public-good Rekor v2 target is its normal use — but a signing config can itself name a private Fulcio or Rekor, which would otherwise make the four rejections above bypassable by moving the same endpoints into a file. Every Fulcio, Rekor, OIDC-provider, and timestamp-authority URL in it must therefore be HTTPS under the sigstore.dev domain, matched on a label boundary so a lookalike host is rejected.

The config that passes that check is the config signed with: the parsed value is handed to the signing path rather than re-read from the path, so the file cannot change between the check and the use.

If private catalog signing is ever needed, both halves have to move together — widening this without widening VerifyCatalog is what this guard exists to prevent.

A signature that yields no bundle is treated as a failure rather than a silent success: it means the attester could not obtain an OIDC token.

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	aicr "github.com/NVIDIA/aicr/pkg/client/v1"
)

func main() {
	ctx := context.Background()

	client, err := aicr.NewClient(aicr.WithRecipeSource(aicr.FilesystemSource("/etc/aicr/recipes")))
	if err != nil {
		log.Print(err)
		return
	}
	defer func() { _ = client.Close() }()

	signed, err := client.SignCatalog(ctx, aicr.CatalogSignOptions{
		Output: "recipe-catalog.sigstore.json",
		OIDCResolve: aicr.OIDCResolveOptions{
			// Ambient workload credentials. Both must be set, or resolution
			// falls through to the browser flow described above.
			AmbientURL:   os.Getenv("ACTIONS_ID_TOKEN_REQUEST_URL"),
			AmbientToken: os.Getenv("ACTIONS_ID_TOKEN_REQUEST_TOKEN"),
		},
	})
	if err != nil {
		log.Print(err)
		return
	}
	fmt.Printf("signed catalog digest %s (%d bytes)\n", signed.Digest, len(signed.BundleJSON))
}

Output:

func (*Client) ValidateState ¶

func (c *Client) ValidateState(
	ctx context.Context,
	recipe *RecipeResult,
	snap *Snapshot,
	opts ...ValidateOption,
) ([]*PhaseResult, error)

ValidateState evaluates a resolved recipe against an observed cluster snapshot, runs the selected validation phases (by default PhaseDeployment, PhaseConformance, PhasePerformance) in order, and returns one PhaseResult per phase run. Pass WithValidationPhases to restrict the run to a subset.

recipe must come from a prior Client.ResolveRecipe call on this Client — it carries the unexported internal recipe state needed to drive constraint evaluation. Passing a RecipeResult constructed by the caller (or one produced by a different Client whose internal has since been evicted) returns ErrCodeInvalidRequest.

snap is the Snapshot returned by Client.CollectSnapshot or by any other snapshotter source.

opts configure the validator run. Pass WithValidationNoCluster(true) from unit tests so no Kubernetes resources are created and every check reports as "skipped". WithValidationNamespace, WithValidationRunID, WithValidationCleanup, WithValidationTolerations, WithValidationNodeSelector, WithValidationKubeconfig, and WithValidationPhases cover the production-controller knobs. The validator catalog loads through this Client's own DataProvider, so a Client built from FilesystemSource validates against that recipe source rather than the package global.

Errors:

• ErrCodeInvalidRequest when the Client, recipe, or snap is nil, when recipe lacks internal state, or when the Client has been Closed.
• All validator errors propagate unwrapped — readiness-check failures surface as ErrCodeInvalidRequest, infrastructure failures as ErrCodeInternal.

All phases run by default and produce results regardless of earlier failures. Pass WithValidationFailFast(true) to stop after the first failed phase (useful for skipping expensive checks like inference-perf when deployment already failed). Callers wanting per-phase control can reach into pkg/validator.ValidatePhase directly.

package main

import (
	"context"
	"fmt"
	"log"

	aicr "github.com/NVIDIA/aicr/pkg/client/v1"
)

func main() {
	ctx := context.Background()

	client, err := aicr.NewClient(aicr.WithRecipeSource(aicr.EmbeddedSource()))
	if err != nil {
		log.Print(err)
		return
	}
	defer func() { _ = client.Close() }()

	recipe, err := client.LoadRecipe(ctx, "recipe.yaml", "")
	if err != nil {
		log.Print(err)
		return
	}
	snap, err := client.LoadSnapshot(ctx, "snapshot.yaml", "")
	if err != nil {
		log.Print(err)
		return
	}

	phases, err := client.ValidateState(ctx, recipe, snap,
		aicr.WithValidationNoCluster(true),
		aicr.WithValidationPhases(aicr.PhaseDeployment, aicr.PhaseConformance),
	)
	if err != nil {
		log.Print(err)
		return
	}
	for _, p := range phases {
		fmt.Printf("%s: %d passed, %d failed\n", p.Phase, p.Summary.Passed, p.Summary.Failed)
	}
}

Output:

func (*Client) VerifyBundle ¶ added in v0.20.0

func (c *Client) VerifyBundle(ctx context.Context, bundleDir string, opts BundleVerifyOptions) (*BundleVerification, error)

VerifyBundle verifies a deployment bundle's checksums and attestation chain, then evaluates the policy assertions carried in opts.

Verification is offline: the checksum and attestation chain resolve against the locally cached or embedded Sigstore trusted root. The one network path is a KMS URI in opts.Key, which makes a live GetPublicKey call to resolve the key.

A non-nil error means verification could not be performed — bad options, a missing or unreadable bundle directory, a malformed trust root. A bundle that verified but failed is reported through the returned value: Report.Errors for verification failures and PolicyFailure for policy ones.

This method does not touch the Client's recipe catalog. It hangs off Client so that a single configured Client is the one object a consumer needs, and so config-driven verification has a home. Any open Client will do — a hot-path caller can construct one against EmbeddedSource and reuse it, rather than building one per verification.

func (*Client) VerifyCatalog ¶ added in v0.20.0

func (c *Client) VerifyCatalog(ctx context.Context, bundlePath string, opts CatalogVerifyOptions) (*CatalogVerification, error)

VerifyCatalog recomputes the deterministic digest over this Client's recipe catalog (registry.yaml plus validators/catalog.yaml) and verifies it against the Sigstore bundle at bundlePath, pinning to NVIDIA CI identity. The bundle ships as the recipe-catalog.sigstore.json release asset alongside each tagged aicr binary.

The digest is computed over THIS Client's DataProvider, not the process-wide embedded catalog — the same binding ComputeHealth uses. A Client built on an EmbeddedSource verifies the catalog NVIDIA signed. A Client whose source layers external data over the embedded tree is verifying different content, so verification will not match the released signature; that is the correct answer to "is the catalog I am resolving against the signed one", not a bug.

A verification failure is returned as an error, not as a report: unlike bundle and evidence verification there is no partial verdict to render.

package main

import (
	"context"
	"fmt"
	"log"

	aicr "github.com/NVIDIA/aicr/pkg/client/v1"
)

func main() {
	ctx := context.Background()

	client, err := aicr.NewClient(aicr.WithRecipeSource(aicr.FilesystemSource("/etc/aicr/recipes")))
	if err != nil {
		log.Print(err)
		return
	}
	defer func() { _ = client.Close() }()

	verification, err := client.VerifyCatalog(ctx, "recipe-catalog.sigstore.json", aicr.CatalogVerifyOptions{})
	if err != nil {
		log.Print(err)
		return
	}
	fmt.Printf("signed by %s over %s\n", verification.Identity, verification.Digest)
}

Output:

func (*Client) VerifyEvidence ¶ added in v0.20.0

func (c *Client) VerifyEvidence(ctx context.Context, opts EvidenceVerifyOptions) (*EvidenceVerification, error)

VerifyEvidence verifies a recipe-evidence bundle's signature (when present) and manifest hash chain, and surfaces the predicate it recovered.

A non-nil error means verification could not be attempted (bad options, closed Client). Everything else — including "this bundle is invalid" — comes back as a verdict on the returned value; read EvidenceVerification.Exit and compare against the EvidenceExit* constants.

Unlike bundle verification this can reach the network: a pointer or OCI input pulls the artifact from its registry.

That makes one interaction worth knowing. By default the call is capped by defaults.VerifyOperationTimeout, so a slow registry can trip it even when the caller's own context allowed longer. A cap breach returns an ERROR, not EvidenceExitIncomplete — so a gate that distinguishes "could not check this" from "checked it and it failed" must treat a context-deadline error as the former, alongside the Incomplete verdict.

Set EvidenceVerifyOptions.Timeout to a pointer to 0 to remove the facade cap and let the caller's context govern, which is the fix for a registry that is simply slow rather than broken. The caller's own deadline still applies; the option can only relax the facade's ceiling, never extend the context it was given.

The Client's recipe catalog is not consulted, so any open Client will do — including one a hot-path caller keeps around and reuses.

package main

import (
	"context"
	"fmt"
	"log"

	aicr "github.com/NVIDIA/aicr/pkg/client/v1"
)

func main() {
	ctx := context.Background()

	client, err := aicr.NewClient(aicr.WithRecipeSource(aicr.EmbeddedSource()))
	if err != nil {
		log.Print(err)
		return
	}
	defer func() { _ = client.Close() }()

	verification, err := client.VerifyEvidence(ctx, aicr.EvidenceVerifyOptions{
		Input: "evidence.json",
	})
	if err != nil {
		log.Print(err)
		return
	}

	switch verification.Exit {
	case aicr.EvidenceExitValidPassed:
		fmt.Println("valid, all phases passed")
	case aicr.EvidenceExitValidPhaseFailures:
		fmt.Println("valid, but phases failed")
	case aicr.EvidenceExitInvalid:
		fmt.Println("invalid")
	case aicr.EvidenceExitIncomplete:
		fmt.Println("incomplete")
	}

	fmt.Println(aicr.RenderEvidenceMarkdown(verification))
}

Output:

func (*Config) BundleInputOptions ¶ added in v0.21.0

func (c *Config) BundleInputOptions() (BundleInputOptions, error)

BundleInputOptions derives the caller-side spec.bundle settings: which recipe to bundle, which image-refs file to write to, where to push the finished bundle, and how to reach that registry. None of these reach MakeBundle — BundleOptions carries what the bundler itself reads.

Returns the zero value for a nil Config or an absent spec.bundle, and an error when the section is present but malformed.

func (*Config) BundleOptions ¶ added in v0.21.0

func (c *Config) BundleOptions() (BundleOptions, error)

BundleOptions derives Client.MakeBundle options from spec.bundle, as plain fields rather than a built *BundleConfig — so a caller (the CLI in particular) can read and override individual settings with its own flag precedence instead of reaching into an opaque built config.

Eighteen flat fields project the bundler settings the section configures — deployment (deployer, repo, value overrides, dynamic values, vendoring, app name), scheduling (system/accelerated selectors and tolerations, DRA eviction label, workload gate and selector, node count, storage classes), and the two attestation flags the bundler itself reads (attest, certificate identity regexp). OIDCResolve carries what reaches the attester rather than the bundler: the Attest gate, DeviceFlow, FulcioURL, RekorURL, SigningKey, and the derived UseTUFSigningConfig.

What is deliberately NOT projected here ¶

RecipeInput, OutputTarget, OutputTargetRaw, ImageRefs, InsecureTLS and PlainHTTP are CALLER-side settings — which recipe to bundle, where to push the result, and how to reach that registry — not bundler settings, so they have no home on BundleOptions. BundleInputOptions carries them.

Zero values ¶

PromptWriter is also left nil, because config cannot carry an io.Writer. A nil writer is treated as io.Discard, so a derived DeviceFlow discards the verification URL and user code and the lazy attester then blocks until the context deadline on first Attest(). That fails closed — no wrong signature — but the caller must set OIDCResolve.PromptWriter to use device flow at all. Erroring here instead would break derive-don't-apply: a caller may well supply their own Attester and never reach the device flow.

Attester, BinaryAttestation, OutputDir and Timeout are left at their zero values. None has a spec.bundle counterpart, and defaulting them here would hide which layer chose. A caller sets them after deriving, which is the same precedence the CLI applies to an explicitly-set flag.

Returns an error when spec.bundle is present but malformed.

func (*Config) BundleVerifyOptions ¶ added in v0.20.0

func (c *Config) BundleVerifyOptions() (BundleVerifyOptions, error)

BundleVerifyOptions derives Client.VerifyBundle options from spec.verify.

The mapping is one-to-one: spec.verify.trust supplies CertificateIdentityRegexp, Key, and TrustRoot, and spec.verify.policy supplies MinTrustLevel, RequireCreator, and CLIVersionConstraint. That alignment is not a coincidence — BundleVerifyOptions was shaped to mirror VerifySpec so this stayed a copy rather than a translation table.

IgnoreTLog has no config counterpart and is left false. It weakens the trust floor by dropping the transparency-log requirement, and keeping it command-line-only means a checked-in file can never silently disable that check.

An empty MinTrustLevel is preserved rather than defaulted here, so VerifyBundle applies its own "max" default. Setting it in this layer would hide which of the two chose the floor.

Returns an error when spec.verify is present but malformed.

func (*Config) CNCFEvidenceOptions ¶ added in v0.21.0

func (c *Config) CNCFEvidenceOptions() (CNCFEvidenceOptions, error)

CNCFEvidenceOptions derives spec.validate.evidence.cncf.

Returns the zero value (never an error for an absent section) when the document has no spec.validate or no evidence.cncf block, and an error when spec.validate is present but malformed.

func (*Config) EvidenceAttestationOptions ¶ added in v0.21.0

func (c *Config) EvidenceAttestationOptions() (EvidenceOptions, bool, error)

EvidenceAttestationOptions derives Client.EmitRecipeEvidence's options from spec.validate.evidence.attestation, and reports whether the document asked for a recipe-evidence bundle at all.

Out is the enable gate, matching the spec field's own contract: an empty out leaves the path off even when bom/push/plainHTTP/insecureTLS are populated, so a half-filled section does not start emitting evidence. False therefore means "not configured", not "misconfigured" — a malformed section is an error instead. That is why this returns a bool rather than a zero-value EvidenceOptions: EmitRecipeEvidence rejects an empty OutDir with ErrCodeInvalidRequest, so a zero value alone could not tell a caller whether the document declined the bundle or fumbled it.

Five fields project (out, bom, push, plainHTTP, insecureTLS). The rest of EvidenceOptions is deliberately caller-owned:

• Commit has no spec counterpart. It selects the validator catalog the bundle's BOM is built against, and it is a property of the running binary rather than of the document. Set it after deriving.
• OIDCResolve is excluded by the spec itself: a keyless-signing identity token is a short-lived secret and must not live in a version-controlled file. The caller resolves it at sign time.
• NoSign and Full are command-line-only, for the same reason FailOnError and IgnoreTLog are. Both weaken the ARTIFACT: NoSign pushes an unsigned bundle, Full ships unredacted payloads. A checked-in file that can quietly turn off signing is a supply-chain downgrade no reviewer would see in a diff, so adding spec fields for them would close a "gap" that is actually a control.

Why plainHTTP and insecureTLS project anyway ¶

They weaken a run too, so the NoSign rule above is not "config may never weaken anything" — stated that broadly it would be contradicted by the two fields three lines into the return below. The line is the ARTIFACT versus the HOP.

PlainHTTP and InsecureTLS configure the transport to a registry the same document already names in push. A document trusted to choose the push destination is trusted to describe how to reach it, which is why EvidenceOptions and SignOptions carry these at all while the bundler's own options do not — MakeBundle never reaches a registry.

Neither field changes what the bundle attests or whether it is signed, and that is structural rather than a promise: both reach only the OCI transport, never SignStatement's Fulcio/Rekor call and never predicate or redaction construction.

How the subject digest is pinned differs by path, and neither path reads it back from the weakened hop. Emit-and-push binds the digest computed locally while packaging, before any push begins. Signing an already-pushed artifact resolves the digest at pull time instead, but the pull is content-addressed and the materialized digest is checked for equality against the value the original packaging run recorded, failing closed on mismatch.

So a tampered hop can corrupt or break the transfer; it cannot make the signature vouch for content that was never packaged.

That is a narrower claim than "harmless". A committed plainHTTP or insecureTLS does weaken that hop, and it widens the threat model rather than just restating it: redirecting push needs a malicious document, whereas downgrading TLS on a destination the operator believes is protected only needs someone on the network path. It is accepted here because the destination is already the document's call. Treat it as a reviewable transport decision, not as evidence that excluding NoSign and Full is arbitrary.

spec.validate.evidence.cncf is projected separately ¶

The evidence section carries two kinds; this method covers one. CNCFEvidenceOptions covers the other — it is a separate method, not folded in here, because the two target different consumers: this one feeds Client.EmitRecipeEvidence, while CNCF AI Conformance markdown has no Client.Emit* counterpart and is consumed directly by the caller (the CLI's validateFlagCombinations, cncf.New and runCNCFSubmission). Reading that half through Unwrap() is no longer necessary.

Returns (zero, false, nil) for a nil Config, an absent spec.validate, or an absent evidence.attestation. An empty out also returns ok=false, but unlike those three absent cases the other four fields (BOMPath, Push, PlainHTTP, InsecureTLS) still populate from the section — only OutDir stays empty. That split matters because out can come from elsewhere: the CLI's --emit-attestation flag can supply out itself while bom/push are configured (buildRecipeEvidenceConfig reads att.BOMPath/att.Push independently of att.OutDir). Zeroing the whole struct whenever out is empty would silently drop that half of the configuration on every run where out arrives some other way. Returns an error when the section is present but malformed.

func (*Config) IsCriteriaStrict ¶ added in v0.20.0

func (c *Config) IsCriteriaStrict() bool

IsCriteriaStrict reports spec.recipe.criteriaStrict, which rejects criteria values outside the embedded catalog — hiding registry entries contributed by a --data overlay.

Exposed as a plain read rather than applied inside RecipeCriteria on purpose: strictness is a property of the CriteriaRegistry, which is shared per-DataProvider, so a derivation method that set it would mutate state the caller shares with every other operation on that Client. The caller applies it deliberately, or not at all.

func (*Config) RecipeAccountingMode ¶ added in v0.20.0

func (c *Config) RecipeAccountingMode() (string, bool, error)

RecipeAccountingMode returns the Slurm accounting mode from spec.recipe.configuration.slurm.accounting.mode, and reports whether the document set one. Same raw-accessor rationale as RecipeProfile.

Returns an error when the configured value is not a valid accounting mode.

func (*Config) RecipeCriteria ¶ added in v0.20.0

func (c *Config) RecipeCriteria(reg *CriteriaRegistry) (*Criteria, error)

RecipeCriteria derives resolve criteria from spec.recipe.criteria, parsed against the supplied registry so a value contributed by a --data overlay validates against the same DataProvider the Client resolves with. Pass Client.CriteriaRegistry(); a nil registry falls back to the embedded catalog.

Returns an empty (non-nil) Criteria when the document states none, so the result is always safe to hand to a resolve call or to overwrite field by field.

func (*Config) RecipeOutputOptions ¶ added in v0.21.0

func (c *Config) RecipeOutputOptions() RecipeOutputOptions

RecipeOutputOptions derives spec.recipe.output. Returns the zero value for a nil Config or an absent section — never an error, because the underlying accessors are nil-safe and perform no parsing.

func (*Config) RecipeProfile ¶ added in v0.20.0

func (c *Config) RecipeProfile() string

RecipeProfile returns spec.recipe.profile, the configuration-profile selection in name=value form. Empty when unset.

RecipeResolveOptions already folds this into a ready-to-use option; this raw accessor exists for callers that must apply their own precedence first, which is exactly what the CLI does when overlaying an explicitly-set --profile flag. Reach for the options form unless you need the raw value.

func (*Config) RecipeResolveOptions ¶ added in v0.20.0

func (c *Config) RecipeResolveOptions() ([]RecipeResolveOption, error)

RecipeResolveOptions derives the resolve options spec.recipe carries: the configuration profile selection (spec.recipe.profile) and the Slurm accounting mode (spec.recipe.configuration.slurm.accounting.mode).

Returns a nil slice when the document sets neither, so it can be appended to a caller's own options unconditionally:

opts, err := cfg.RecipeResolveOptions()
opts = append(opts, aicr.WithProfile(flagProfile))  // caller wins: later option overwrites

func (*Config) RecipeRuntimeInventoryMode ¶ added in v0.20.0

func (c *Config) RecipeRuntimeInventoryMode() (string, bool, error)

RecipeRuntimeInventoryMode returns spec.recipe.configuration.runtimeInventory.mode and whether the document set one. Same raw-accessor rationale as RecipeAccountingMode.

Returns an error when the configured value is not a valid mode.

func (*Config) RecipeSource ¶ added in v0.20.0

func (c *Config) RecipeSource() (RecipeSourceOption, bool)

RecipeSource derives the Client recipe source from spec.recipe.data, and reports whether the document configured one.

This is the piece that lets a committed config stand up a Client at all: a non-empty data directory yields a FilesystemSource layered over the embedded recipe data, matching `aicr recipe --data`. When false is returned the caller supplies its own source, normally EmbeddedSource.

Deliberately NOT folded into a Client option. Recipe source is fixed at construction — a Client owns its DataProvider for its whole lifetime — so this belongs in the NewClient call rather than in a per-operation options value.

func (*Config) SnapshotAgentConfig ¶ added in v0.21.0

func (c *Config) SnapshotAgentConfig() (*AgentConfig, bool, error)

SnapshotAgentConfig derives Client.CollectSnapshot's AgentConfig from spec.snapshot.

These settings map onto the agent Job: namespace, image, image pull secrets, job name, service account, node selector, tolerations, require-GPU, runtime class, OS, max nodes per entry, resource requests and limits, timeout, cleanup and privileged.

OS is parsed through the criteria registry rather than copied, matching what the CLI does with --os. That keeps undocumented values from reaching the agent, and it matters for exact matches: an unparsed "Talos" misses the agent's "talos" check and selects incompatible host mounts.

AgentConfig's fields are exported, so a caller overrides any of them after deriving — the same derive-don't-apply precedence the other methods use, but without needing an options slice, because the type is a plain struct.

Three mappings that are not pass-throughs ¶

NoCleanup is INVERTED against Cleanup, the same shape spec.validate has.

Privileged defaults to TRUE when config says nothing. The resolved field is a pointer precisely so "unset" stays distinct from an explicit false, and the CLI applies derefBoolOr(resolved.Privileged, true). Dereferencing a nil pointer to false here would silently drop privileges the collector needs, and the failure would surface as missing data rather than an error.

Requests and Limits resolve as raw "name=quantity,..." strings — Resolve deliberately does not parse them — so they are parsed here and a malformed value is an error rather than a silently empty ResourceList.

What is deliberately NOT projected ¶

The whole spec.snapshot.output section is un-projected, and that is not an omission. Output describes DELIVERY; AgentConfig describes the collection Job, and the two are different concerns:

• output.format is applied at delivery. The Job always stages YAML in a ConfigMap, so a format routed through AgentConfig would be silently ignored (#2398).
• output.path and output.template are not AgentConfig.Output and .TemplatePath. Per AgentConfig.Output's own godoc, any value that is not a cm:// URI stages to an internal ConfigMap and delivery becomes the caller's job. Projecting a file path there would look configured and write nothing.

Callers deliver with snapshotter.DeliverSnapshot, passing Snapshot.Raw.

Kubeconfig, Debug, ClusterConfigPath, AKSGPUPoolsPath, DiscoverNetwork, RunID and NameBase are left at their zero values. None has a spec.snapshot counterpart — they are per-invocation or caller-owned. NameBase in particular carries the "aicr" default prefix that lets an unset job name stay empty while deployed objects keep their released names, which is a decision the caller makes, not the document.

Returns a zero-value AgentConfig (never nil) when the document has no spec.snapshot, and an error when the section is present but malformed.

A zero value is not a working configuration: Privileged is false, which the collector generally needs true. That is deliberate. Defaults apply when the section EXISTS and is silent about a field; a document with no spec.snapshot at all made no snapshot decisions, so the facade does not invent them. A caller in that position supplies its own defaults, as the CLI does from its flag defaults.

The bool ¶

The second return reports whether spec.snapshot is present — true when the section exists (even if silent about every field), false for a nil Config, a nil internal document, or a document that omits the section. It exists for the same reason EvidenceAttestationOptions returns one: a caller deriving unconditionally (before it knows whether --config was even given) otherwise cannot tell "the document made no snapshot decisions, supply your own defaults" from "the document decided every field, apply them as-is" — both produce a populated *AgentConfig, and only one of them is safe to treat as-is. A caller that skips this bool and always applies the returned value silently drops privileges: an absent section returns Privileged: false, which the collector generally needs true.

func (*Config) SnapshotOutputOptions ¶ added in v0.21.0

func (c *Config) SnapshotOutputOptions() (SnapshotOutputOptions, error)

SnapshotOutputOptions derives snapshot DELIVERY settings from spec.snapshot.output.

Deliberately separate from SnapshotAgentConfig. That method describes the collection Job and projects nothing from spec.snapshot.output, because output describes delivery and the Job always stages YAML in a ConfigMap — a format routed through AgentConfig would be silently ignored (#2398). These three fields are what a caller needs AFTER CollectSnapshot returns, to write the snapshot where the document asked.

Returns the zero value (never an error for an absent section) when the document has no spec.snapshot or no output block.

func (*Config) SnapshotPath ¶ added in v0.20.0

func (c *Config) SnapshotPath() string

SnapshotPath returns spec.recipe.input.snapshot, the snapshot a committed config resolves against. Empty when unset; hand a non-empty value to Client.LoadSnapshot.

func (*Config) Unwrap ¶ added in v0.20.0

func (c *Config) Unwrap() *appconfig.AICRConfig

Unwrap returns the underlying AICRConfig, for callers that need a spec field this facade does not project. Returns nil for a nil Config.

Reaching for this is a signal worth acting on: it means the facade is missing a derivation someone needs. Prefer opening an issue over building on the raw document, since pkg/config carries no stability guarantee.

func (*Config) ValidateInputOptions ¶ added in v0.21.0

func (c *Config) ValidateInputOptions() (ValidateInputOptions, error)

ValidateInputOptions derives spec.validate.input and spec.validate.execution.failOnError — the three spec.validate fields a caller (not the validator) consumes, so a caller applying its own flag-over-config precedence does not need Unwrap() to read them.

Returns the zero value for a nil Config or an absent spec.validate, and an error when the section is present but malformed.

func (*Config) ValidateSettings ¶ added in v0.21.0

func (c *Config) ValidateSettings() (ValidateSettings, bool, error)

ValidateSettings derives settings from both spec.validate.agent and spec.validate.execution, as a plain value rather than an opaque option slice — so a caller (the CLI, in particular) can read and override individual fields with its own flag precedence instead of replaying a built option list.

Thirteen settings project: namespace, image, image pull secrets, job name, service account name, node selector, tolerations, require-GPU, phases, no-cluster, cleanup, fail-fast and timeout. Only nine of them reach Client.ValidateState — image, job name, service account name and require-GPU have no WithValidation* counterpart and are carried purely for the caller's own agent/Job construction. See the ValidateSettings type godoc for which is which.

Where the rest of spec.validate goes ¶

The section is not served by this method alone, which the per-section table in docs/integrator/go-library.md records:

• FailOnError, RecipePath and SnapshotPath are consumed by the CALLER, not by ValidateState, so a caller still needs them projected to apply its own flag-over-config precedence — just not on this type. ValidateInputOptions carries them.
• EvidenceAttestation configures the recipe-evidence bundle. EvidenceAttestationOptions derives it; it is not folded in here because it targets Client.EmitRecipeEvidence rather than ValidateState.
• EvidenceCNCF configures the CNCF AI Conformance markdown path, which has no facade emission method to receive it. See EvidenceAttestationOptions for why that half stays un-projected.

Two mappings that are not pass-throughs ¶

NoCleanup is INVERTED: the config field says "do not clean up", the field says "clean up". Passing it straight through would delete artifacts a post-mortem asked to keep, silently and in either direction.

Phases are cast, not re-parsed, because Validation().Resolve() already rejects an unknown entry and names the spec field — on the WrapConfig path too, since that check lives in Resolve rather than in the loader.

A zero value is not a safe default ¶

Cleanup: false is the opposite of the CLI's own default (clean up). A caller that cannot distinguish "no spec.validate at all" from "spec.validate is present but silent about cleanup" and always applies the returned value as-is will leave the cluster-admin ClusterRoleBinding and validator Jobs active on the plain, no-config invocation — silently, since nothing errors. This is the same hazard SnapshotAgentConfig documents for Privileged; see "# The bool" below for the signal that resolves it.

The bool ¶

The second return reports whether spec.validate is present — true when the section exists (even if silent about every field), false for a nil Config, a nil internal document, or a document that omits the section — mirroring SnapshotAgentConfig's bool exactly, including why it exists: a caller deriving unconditionally (before it knows whether --config was even given) otherwise cannot tell "the document made no validate decisions, supply your own defaults" from "the document decided every field, apply them as-is", and only one of those is safe to treat as-is.

Returns an error when spec.validate is present but malformed.

func (*RecipeResult) Resolved ¶

func (r *RecipeResult) Resolved() *recipe.RecipeResult

Resolved returns the complete underlying recipe (the full pkg/recipe.RecipeResult) that this result wraps. The facade RecipeResult exposes only Name/Version/TranslatedAt/Components/SelectedProfile; callers that need constraints, validation config, deployment order, or metadata (e.g. evidence emission) use this. Returns nil if the result was not produced by the Client.

Lifetime: the returned pointer is borrowed from the facade RecipeResult. Do not mutate; do not retain past the facade RecipeResult's lifetime. Marshal/serialize first if persistence is needed.

func (*Snapshot) Unwrap ¶ added in v0.19.0

func (s *Snapshot) Unwrap() *snapshotter.Snapshot

Unwrap returns the underlying pkg/snapshotter.Snapshot — the inverse of WrapSnapshot, and the analog of RecipeResult.Resolved(). In-tree callers (the CLI's validate path) use it to reach measurement-level detail the facade's public fields intentionally do not project.

A Snapshot constructed outside the facade (no internal payload) yields a minimal pkg/snapshotter.Snapshot rebuilt from the public fields, so callers never have to nil-check the result of a non-nil receiver. Returns nil for a nil receiver. The returned pointer is the facade's own — treat it as read-only.

func (*SnapshotDiff) HasDrift ¶ added in v0.20.0

func (r *SnapshotDiff) HasDrift() bool

HasDrift reports whether the diff contains any field-level changes.