CLI Configuration File | NVIDIA AI Cluster Runtime

AICRConfig is a Kubernetes-style YAML/JSON document that captures the inputs to the four workflow commands — aicr snapshot, aicr recipe, aicr bundle, and aicr validate — so an end-to-end run version-controls as a single file instead of a shell script full of flags. Each command accepts it through the same --config flag:

$ aicr snapshot --config aicr-config.yaml
$ aicr recipe   --config aicr-config.yaml
$ aicr bundle   --config aicr-config.yaml
$ aicr validate --config aicr-config.yaml

This page documents the complete document schema in one place. The CLI Reference shows per-command usage in its Snapshot, Recipe, Validate, and Bundle config-file-mode sections. The schema’s source of truth is pkg/config.

Document Envelope

1 kind: AICRConfig               # required, exactly this value
2 apiVersion: aicr.run/v1alpha2  # required, exactly this value
3 metadata:
4   name: gke-h100-training      # optional, identifying only
5 spec:
6   snapshot: {}                 # each section optional —
7   recipe: {}                   # at least ONE must be present
8   bundle: {}
9   validate: {}

Each spec.* section is optional and each command reads only its own section, so a file may carry just one section or any combination. A document with none of the four sections is rejected.

Loading, Precedence, and Secrets

Sources. --config accepts a local file path or an HTTP/HTTPS URL (format detected from the extension; fetches are timeout- and size-bounded). ConfigMap cm:// URIs are intentionally rejected — extract the data with kubectl and pass the resulting file.

Precedence. A CLI flag always wins over the matching config field. For slice and map fields (tolerations, selectors, --set), a flag given on the command line replaces the file’s value; it does not append.

Nil vs. empty. For agent selectors and tolerations, omitting the field entirely (nil) inherits the compiled-in defaults (tolerations defaults to tolerate all taints), while an explicit empty value ({} / []) clears the default. Several booleans are tri-state for the same reason: absent means “inherit the CLI default”, an explicit false is an opt-out (spec.validate.execution.failOnError, failFast, spec.snapshot.execution.privileged, spec.recipe.criteriaStrict, spec.validate.evidence.*).

Secrets are never part of the schema. The cosign OIDC identity token used by attestation and evidence push is deliberately absent — supply it via the COSIGN_IDENTITY_TOKEN environment variable or the --identity-token flag.

Complete Example

1 kind: AICRConfig
2 apiVersion: aicr.run/v1alpha2
3 metadata:
4   name: eks-h100-training
5 spec:
6   snapshot:
7     output:
8       path: snapshot.yaml            # same shape as -o
9       format: yaml                   # yaml | json | table
10       template: ""                   # optional Go template path
11     agent:                           # in-cluster snapshot Job pod
12       namespace: aicr-validation
13       image: ""                      # default: ghcr.io/nvidia/aicr:latest
14       imagePullSecrets: []
15       jobName: aicr
16       serviceAccountName: aicr
17       nodeSelector:
18         nodeGroup: gpu-worker
19       tolerations:
20         - dedicated=gpu-workload:NoSchedule
21       requireGpu: false
22       runtimeClassName: ""           # mutually exclusive with requireGpu
23       os: ""                         # ubuntu | rhel | cos | amazonlinux | ol | talos
24       requests: ""                   # "cpu=500m,memory=1Gi"
25       limits: ""
26     execution:
27       timeout: 5m
28       noCleanup: false
29       privileged: true               # false for PSS-restricted namespaces
30       maxNodesPerEntry: 0            # 0 = unlimited topology entries
31 
32   recipe:
33     criteria:                        # mutually exclusive with input.snapshot
34       service: eks
35       accelerator: h100
36       intent: training
37       os: ubuntu
38       platform: kubeflow
39       nodes: 2
40     # input:
41     #   snapshot: snapshot.yaml      # derive criteria from a snapshot instead
42     output:
43       path: recipe.yaml
44       format: yaml                   # yaml | json | table
45     data: ""                         # optional data-overlay dir/archive
46     criteriaStrict: false            # reject criteria outside the embedded catalog
47 
48   bundle:
49     input:
50       recipe: recipe.yaml            # must match recipe.output.path when both set
51     output:
52       target: ./bundles              # local dir or oci:// URI
53       imageRefs: ""                  # image-refs output path
54     deployment:
55       deployer: helmfile             # helm | helmfile | argocd | argocd-helm | flux | ...
56       repo: ""
57       set: []                        # value overrides, "key:path=value"
58       dynamic: []
59       vendorCharts: false
60       appName: ""                    # argocd parent Application name override
61     scheduling:
62       systemNodeSelector: {}
63       systemNodeTolerations: []
64       acceleratedNodeSelector:
65         nodeGroup: gpu-worker
66       acceleratedNodeTolerations:
67         - nvidia.com/gpu=present:NoSchedule
68       workloadGate: ""
69       workloadSelector: {}
70       nodes: 2
71       storageClass: ""
72     attestation:
73       enabled: false
74       certificateIdentityRegexp: ""
75       oidcDeviceFlow: false
76       fulcioURL: ""                  # private Sigstore overrides; empty = public good
77       rekorURL: ""
78     registry:                        # OCI transport for oci:// push
79       insecureTLS: false
80       plainHTTP: false
81 
82   validate:
83     input:
84       recipe: recipe.yaml
85       snapshot: snapshot.yaml
86     agent:                           # same nil-vs-empty semantics as snapshot.agent
87       namespace: aicr-validation
88       image: ""
89       imagePullSecrets: []
90       jobName: aicr
91       serviceAccountName: aicr
92       nodeSelector:
93         nodeGroup: gpu-worker
94       tolerations:
95         - nvidia.com/gpu=present:NoSchedule
96       requireGpu: false
97     execution:
98       phases: [deployment, conformance, performance]
99       failOnError: true              # tri-state; absent = CLI default (true)
100       failFast: false
101       noCluster: false
102       noCleanup: false
103       timeout: 40m
104     evidence:
105       cncf:                          # CNCF AI Conformance markdown
106         dir: ./evidence
107         cncfSubmission: false        # requires dir
108         features: []                 # empty = all features
109       attestation:                   # recipe-evidence v1 bundle (ADR-007)
110         out: evidence-result.json    # setting this enables the path
111         bom: ""
112         push: ""                     # OCI ref to push the signed bundle
113         plainHTTP: false
114         insecureTLS: false

Field Reference

spec.snapshot

Inputs to aicr snapshot. There is no input section — the snapshot is produced from the live cluster.

Field	Type	Notes
`output.path`	string	Output file path (same as `-o`)
`output.format`	string	`yaml` \| `json` \| `table`
`output.template`	string	Optional Go template path
`agent.*`	object	In-cluster capture Job pod: `namespace`, `image`, `imagePullSecrets`, `jobName`, `serviceAccountName`, `nodeSelector`, `tolerations`, `requireGpu`, `runtimeClassName` (mutually exclusive with `requireGpu`), `os`, `requests`, `limits`. Mirrors `spec.validate.agent` so one file pins matching placement for both
`execution.timeout`	duration string	e.g. `5m`
`execution.noCleanup`	bool	Keep the capture Job after completion
`execution.privileged`	bool (tri-state)	Set `false` for PSS-restricted namespaces
`execution.maxNodesPerEntry`	int	`0` = unlimited topology entries

spec.recipe

Inputs to aicr recipe. criteria and input.snapshot are mutually exclusive — query by criteria or derive from a snapshot, not both.

Field	Type	Notes
`criteria.service` / `.accelerator` / `.intent` / `.os` / `.platform`	string	Same names and values as the CLI flags
`criteria.nodes`	int	Target GPU node count
`input.snapshot`	string	Snapshot path to derive the recipe from
`output.path`	string	Recipe output path
`output.format`	string	`yaml` \| `json` \| `table`
`data`	string	Data-overlay directory/archive (same as `--data`)
`criteriaStrict`	bool (tri-state)	Reject criteria values outside the embedded catalog; mirrors `--criteria-strict` / `AICR_CRITERIA_STRICT` (any of the three enables it)

spec.bundle

Inputs to aicr bundle.

Field	Type	Notes
`input.recipe`	string	Recipe to bundle
`output.target`	string	Local directory or `oci://` URI
`output.imageRefs`	string	Image-refs output path
`deployment.deployer`	string	Deployer choice (same values as `--deployer`)
`deployment.repo`	string	GitOps repo for repo-shaped deployers
`deployment.set` / `.dynamic`	[]string	Value overrides, `key:path=value`
`deployment.vendorCharts`	bool	Vendor charts into the bundle
`deployment.appName`	string	Argo CD parent `Application` name override (multi-bundle installs sharing a namespace)
`scheduling.*`	object	`systemNodeSelector`/`Tolerations`, `acceleratedNodeSelector`/`Tolerations`, `workloadGate`, `workloadSelector`, `nodes`, `storageClass`. Selectors are YAML maps; tolerations use the CLI’s `key=value:effect` strings
`attestation.enabled`	bool	Keyless-sign the bundle
`attestation.certificateIdentityRegexp`	string	Expected signer identity
`attestation.oidcDeviceFlow`	bool	Device-code flow for headless signing
`attestation.fulcioURL` / `.rekorURL`	string	Private Sigstore endpoints; empty = public-good defaults
`registry.insecureTLS` / `.plainHTTP`	bool	OCI transport options for push

spec.validate

Inputs to aicr validate.

Field	Type	Notes
`input.recipe` / `.snapshot`	string	Recipe + snapshot to validate
`agent.*`	object	In-cluster validation Job pod; same fields and nil-vs-empty semantics as `spec.snapshot.agent` (minus `runtimeClassName`/`os`/`requests`/`limits`)
`execution.phases`	[]string	e.g. `[deployment, conformance, performance]`
`execution.failOnError`	bool (tri-state)	Absent = CLI default (`true`); explicit `false` opts out
`execution.failFast`	bool (tri-state)	Stop after the first failed phase
`execution.noCluster`	bool	Test mode: no cluster access, constraints evaluated inline
`execution.noCleanup`	bool	Keep validation Jobs after completion
`execution.timeout`	duration string	e.g. `40m`
`evidence.cncf.dir`	string	CNCF AI Conformance evidence directory (`--evidence-dir`)
`evidence.cncf.cncfSubmission`	bool (tri-state)	Emit submission layout; requires `dir`
`evidence.cncf.features`	[]string	Empty = all features; honored only with `cncfSubmission`
`evidence.attestation.out`	string	Recipe-evidence v1 result path — setting it enables the attestation path
`evidence.attestation.bom` / `.push`	string	BOM input; OCI ref for the signed bundle push
`evidence.attestation.plainHTTP` / `.insecureTLS`	bool (tri-state)	Push transport options

Cross-Section Rules

At least one of the four spec.* sections must be present.
spec.recipe.criteria and spec.recipe.input.snapshot are mutually exclusive.
When both spec.recipe.output.path and spec.bundle.input.recipe are set, they must reference the same file (compared after filepath.Clean; mixing absolute and relative forms is rejected). Mismatched paths in a workflow file are almost always a typo, so the loader fails up-front.
Enum-valued fields (criteria.*, output formats, phases) are validated with the same parsers the CLI flags use, so error messages match the CLI’s.

CLI Configuration File (AICRConfig)