AI Cluster Runtime (AICR)
June 30, 2026 · View on GitHub
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.
Find Your Path
| If you are a... | Start here |
|---|---|
| User — operator deploying AICR to provision or validate a cluster | User Guide |
| Integrator — engineer embedding AICR in a CI/CD pipeline, GitOps flow, or larger platform | Integrator Guide |
| Contributor — developer extending AICR or shipping recipes | Contributor Guide |
User Guide
For operators running aicr against real clusters.
| Topic | Doc |
|---|---|
| Install the CLI | Installation |
| Full workflow, start to finish | End-to-End Tutorial |
| Every command and flag | CLI Reference |
| Render a recipe into deployment artifacts | Generating Bundles |
REST API for aicrd | API Reference |
| Run the snapshot agent in-cluster | Agent Deployment |
| Validate a recipe against a live cluster | Validation |
| Components that can appear in a recipe | Component Catalog |
| Air-gapped mirroring | Air-Gap Mirror |
Integrator Guide
For pipelines and platforms that call AICR programmatically or host
aicrd.
| Topic | Doc |
|---|---|
| CI/CD integration patterns | Automation |
Self-host aicrd on Kubernetes | Kubernetes Deployment |
| Add or modify recipe metadata | Recipe Development |
| Verify artifacts (SLSA, SBOM, attestations) | Supply Chain Verification |
Ship custom validators via --data | Validator Extension |
| Cloud-specific GPU setup | AKS, EKS networking, GKE networking, Talos |
Contributor Guide
For developers working on AICR itself.
| Topic | Doc |
|---|---|
| Architecture, boundaries, package map | Architecture Overview |
| Recipes, overlays, mixins | Recipes |
| Adding a component | Components |
| Adding a snapshot collector | Collectors |
| All four validation surfaces | Validators |
| CLI internals | CLI |
| API server internals | API Server |
Testing surfaces and the make qualify gate | Testing |
| Release runbook | Maintaining AICR |
The Four-Stage Workflow
┌──────────┐ ┌────────┐ ┌──────────┐ ┌────────┐
│ 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; for the architecture see
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. |