> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/aicr/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/aicr/_mcp/server.

# AI Cluster Runtime (AICR)

NVIDIA AI Cluster Runtime (AICR) generates validated, reproducible
configuration artifacts for GPU-accelerated Kubernetes clusters.
Given a description of your environment — cloud, accelerator, OS,
intent — AICR emits the Helm, Argo CD, Flux, or Helmfile artifacts
your deployment tool consumes. The output is hardware-aware,
version-locked, and backed by SLSA Build Level 3 image provenance.

For the project pitch, supported environments, and a feature
overview, see the [repository README](https://github.com/NVIDIA/aicr).

## Find Your Path

| If you are a... | Start here |
|-----------------|-----------|
| **User** — operator deploying AICR to provision or validate a cluster | [User Guide](user/index.md) |
| **Integrator** — engineer embedding AICR in a CI/CD pipeline, GitOps flow, or larger platform | [Integrator Guide](/aicr/integrator-guide/automation) |
| **Contributor** — developer extending AICR or shipping recipes | [Contributor Guide](/aicr/contributor-guide/architecture-overview) |

### User Guide

For operators running `aicr` against real clusters.

| Topic | Doc |
|-------|-----|
| Install the CLI | [Installation](/aicr/user-guide/installation) |
| Full workflow, start to finish | [End-to-End Tutorial](user/tutorial.md) |
| Every command and flag | [CLI Reference](/aicr/user-guide/cli-reference) |
| Render a recipe into deployment artifacts | [Generating Bundles](user/bundling.md) |
| REST API for `aicrd` | [API Reference](/aicr/user-guide/api-reference) |
| Run the snapshot agent in-cluster | [Agent Deployment](/aicr/user-guide/agent-deployment) |
| Validate a recipe against a live cluster | [Validation](/aicr/user-guide/validation) |
| Components that can appear in a recipe | [Component Catalog](/aicr/user-guide/component-catalog) |
| Air-gapped mirroring | [Air-Gap Mirror](/aicr/user-guide/air-gapped-mirroring) |

### Integrator Guide

For pipelines and platforms that call AICR programmatically or host
`aicrd`.

| Topic | Doc |
|-------|-----|
| CI/CD integration patterns | [Automation](/aicr/integrator-guide/automation) |
| Self-host `aicrd` on Kubernetes | [Kubernetes Deployment](/aicr/integrator-guide/kubernetes-deployment) |
| Add or modify recipe metadata | [Recipe Development](/aicr/integrator-guide/recipe-development) |
| Verify artifacts (SLSA, SBOM, attestations) | [Supply Chain Verification](/aicr/integrator-guide/supply-chain-verification) |
| Ship custom validators via `--data` | [Validator Extension](/aicr/integrator-guide/validator-extension) |
| Cloud-specific GPU setup | [AKS](/aicr/integrator-guide/aks-gpu-setup), [EKS networking](/aicr/integrator-guide/eks-dynamo-networking), [GKE networking](/aicr/integrator-guide/gke-tcpxo-networking), [Talos](/aicr/integrator-guide/talos-integration) |

### Contributor Guide

For developers working on AICR itself.

| Topic | Doc |
|-------|-----|
| Architecture, boundaries, package map | [Architecture Overview](/aicr/contributor-guide/architecture-overview) |
| Recipes, overlays, mixins | [Recipes](/aicr/contributor-guide/recipes-overlays-and-mixins) |
| Adding a component | [Components](/aicr/contributor-guide/components) |
| Adding a snapshot collector | [Collectors](/aicr/contributor-guide/collectors) |
| All four validation surfaces | [Validators](/aicr/contributor-guide/validators) |
| CLI internals | [CLI](/aicr/contributor-guide/cli) |
| API server internals | [API Server](/aicr/contributor-guide/api-server) |
| Testing surfaces and the `make qualify` gate | [Testing](/aicr/contributor-guide/testing) |
| Release runbook | [Maintaining AICR](/aicr/contributor-guide/maintaining-aicr) |

## The Four-Stage Workflow

```text
┌──────────┐    ┌────────┐    ┌──────────┐    ┌────────┐
│ Snapshot │───▶│ Recipe │───▶│ Validate │───▶│ Bundle │
└──────────┘    └────────┘    └──────────┘    └────────┘
   capture       generate       check          emit
   cluster       optimized      constraints    deployment
   state         config         vs. actual     artifacts
```

Each stage produces a serializable artifact and is independently
invocable. Stages can be chained or run standalone, and inputs and
outputs flow through files, stdout, or Kubernetes ConfigMaps
(`cm://namespace/name`). For the CLI walkthrough see
[CLI Reference](/aicr/user-guide/cli-reference); for the architecture see
[/aicr/contributor-guide/architecture-overview](contributor/index.md).

## Glossary

Reference for the terms used across the docs site.

| Term | Definition |
|------|------------|
| **Snapshot** | Captured state of a target system (OS, kernel, Kubernetes, GPU, SystemD). Produced by `aicr snapshot` or the in-cluster snapshot Job. |
| **Recipe** | Resolved configuration spec — component refs, constraints, deployment order — produced by `aicr recipe` from criteria or from a snapshot. |
| **Criteria** | Query parameters that select a recipe: `service`, `accelerator`, `intent`, `os`, `platform`, `nodes`. |
| **Overlay** | A recipe metadata file (`kind: RecipeMetadata`) under `recipes/overlays/` matched by criteria. Composes via single-parent inheritance (`spec.base`). |
| **Mixin** | A composable fragment (`kind: RecipeMixin`) under `recipes/mixins/` carrying only `constraints` and `componentRefs`, referenced via `spec.mixins`. |
| **Bundle** | Deployment artifacts emitted by `aicr bundle`: Helm values, manifests, install scripts, checksums. |
| **Bundler** | A per-component generator that emits the bundle inputs (e.g., GPU Operator bundler). |
| **Deployer** | An output adapter that serializes a bundle in a tool-specific format: `helm`, `helmfile`, `argocd`, `argocd-helm`, `flux`. |
| **Component** | A deployable software package (e.g., GPU Operator, Network Operator). Lives in `recipes/registry.yaml`. |
| **ComponentRef** | A reference to a component inside a recipe — version, source, values file, dependencies. |
| **Constraint** | A declarative validation rule on a recipe (e.g., `K8s.server.version >= 1.32.4`). |
| **Validation Phase** | A stage of `aicr validate`: readiness (always implicit), deployment, performance, conformance. |
| **Measurement** | A snapshot data point keyed by type (K8s, OS, GPU, SystemD, NodeTopology, NetworkTopology), subtype, and reading. |
| **Specificity** | A score counting non-`any` criteria fields. More-specific overlays merge later. |
| **Asymmetric matching** | Criteria-matching rule: recipe `any` is a wildcard; query `any` does not match a specific recipe. |
| **ConfigMap URI** | `cm://namespace/name` — read or write snapshots and recipes directly to Kubernetes ConfigMaps. |
| **SLSA / SBOM** | Supply-chain Levels for Software Artifacts (release images reach Build Level 3) and Software Bill of Materials shipped with binaries and images. |

## Links

- [GitHub](https://github.com/NVIDIA/aicr) · [Releases](https://github.com/NVIDIA/aicr/releases) · [Issues](https://github.com/NVIDIA/aicr/issues)
- [Contributing](https://github.com/NVIDIA/aicr/blob/main/CONTRIBUTING.md) · [Security](https://github.com/NVIDIA/aicr/blob/main/SECURITY.md) · [Roadmap](https://github.com/NVIDIA/aicr/blob/main/ROADMAP.md)
- Slack: [#aicr](https://kubernetes.slack.com/archives/C0AQMPP1BK7) on Kubernetes Slack