Air-Gapped Image Mirroring

Discover every container image and Helm chart a recipe needs, then mirror them into a private registry for air-gapped deployment. For the per-flag reference, see CLI reference: aicr mirror list. For the static image inventory across all registered components, see Container Image Inventory.

Overview

aicr mirror list renders each component’s Helm chart with recipe-resolved values, scans referenced manifests, and produces a deduplicated list of container images and chart references. Manifest reads honor the recipe’s data source — when the recipe was built with --data <dir>, an overlay manifest shadowing an embedded path is used in place of the embedded copy. The output is available in four formats — two general-purpose (YAML, JSON) and two tool-specific (Hauler, Zarf).

Trust boundary: Discovery shells out to helm template, which executes the full Go template engine (tpl, include, lookup). AICR recipes reference trusted, pinned charts from known repositories. Do not run mirror list against untrusted or unvetted recipe files — doing so executes arbitrary template code from those charts.

                      ┌────────────────────-──┐
  aicr recipe ───────▶│  aicr mirror list     │
  (or query params)   │  --format hauler|zarf │
                      └──────────┬──────-─────┘
                                 │
              ┌──────────────────┼──────────────────┐
              ▼                                     ▼
     ┌────────────────┐                   ┌─────────--────────┐
     │  hauler store  │                   │  zarf package     │
     │  sync → copy   │                   │  create → mirror  │
     └───────┬────────┘                   └────────┬──────--──┘
             │                                     │
             ▼                                     ▼
     ┌────────────────────────────────────────────────────┐
     │              Private Registry                      │
     └────────────────────────────────────────────────────┘

How this relates to chart vendoring: aicr bundle --vendor-charts embeds Helm chart tarballs into a bundle so helm install needs no registry egress. aicr mirror list discovers the container images those charts reference plus the chart coordinates themselves. For a fully air-gapped deployment, use both: mirror images and charts into your private registry, then deploy the vendored bundle.

Prerequisites

• aicr CLI installed (see Installation)
• A recipe file (aicr recipe --output recipe.yaml) or query parameters
• helm v3+ on $PATH (required for chart rendering during discovery)
• For the Hauler workflow: hauler CLI
• For the Zarf workflow: zarf CLI
• YAML/JSON output works without any additional tools

Output Formats

Quick Start

Discover Images

From an existing recipe file:

$
aicr mirror list --recipe recipe.yaml

Or resolve a recipe from query parameters:

$
aicr mirror list --service eks --accelerator h100 --intent training --os ubuntu

Save to File

$
aicr mirror list --recipe recipe.yaml --format hauler --output hauler-manifest.yaml

Hauler Workflow

Hauler syncs container images and Helm charts into a local store, then copies them to a target registry.

1. Generate the Hauler manifest

$
aicr mirror list --recipe recipe.yaml --format hauler --output manifest.yaml

The output is a multi-document YAML with an Images document (and optionally a Charts document):

1
apiVersion: content.hauler.cattle.io/v1
2
kind: Images
3
metadata:
4
  name: aicr-images
5
spec:
6
  images:
7
    - name: nvcr.io/nvidia/cloud-native/gpu-operator:v25.3.0
8
    - name: registry.k8s.io/nfd/node-feature-discovery:v0.17.2
9
    # ...
10
---
11
apiVersion: content.hauler.cattle.io/v1
12
kind: Charts
13
metadata:
14
  name: aicr-charts
15
spec:
16
  charts:
17
    - name: gpu-operator
18
      repoURL: oci://ghcr.io/nvidia
19
      version: v25.3.0
20
    # ...

2. Sync into the Hauler store

$
hauler store sync \
>
  --store ./hauler-store \
>
  --filename manifest.yaml

To pull only a single platform (reduces download size):

$
hauler store sync \
>
  --store ./hauler-store \
>
  --platform linux/amd64 \
>
  --filename manifest.yaml

3. Copy to your private registry

$
hauler store copy \
>
  --store ./hauler-store \
>
  registry://my-registry.example.com:5000

For registries using plain HTTP (e.g., local test registries):

$
hauler store copy \
>
  --store ./hauler-store \
>
  --plain-http \
>
  registry://localhost:5001

Zarf Workflow

Zarf packages container images into a single distributable tarball that can be carried to an air-gapped environment and mirrored into a registry.

1. Generate the Zarf package config

$
aicr mirror list --recipe recipe.yaml --format zarf --output zarf.yaml

The output is a ZarfPackageConfig:

1
apiVersion: zarf.dev/v1alpha1
2
kind: ZarfPackageConfig
3
metadata:
4
  name: aicr
5
  description: Container images and Helm charts for AICR recipe deployment
6
  version: 0.0.1
7
components:
8
  - name: aicr-images
9
    required: true
10
    images:
11
      - nvcr.io/nvidia/cloud-native/gpu-operator:v25.3.0
12
      - registry.k8s.io/nfd/node-feature-discovery:v0.17.2
13
      # ...
14
    charts:
15
      - name: gpu-operator
16
        url: oci://ghcr.io/nvidia/gpu-operator
17
        version: v25.3.0
18
        namespace: gpu-operator
19
      # ...

2. Create the Zarf package

Place zarf.yaml in its own directory and create the package:

$
mkdir -p zarf-pkg && cp zarf.yaml zarf-pkg/
$
cd zarf-pkg
$
zarf package create . --confirm

This pulls every listed image and produces a zarf-package-*.tar.zst file.

3. Mirror to your private registry

Transfer the tarball to the air-gapped environment, then mirror:

$
zarf package mirror-resources zarf-package-aicr-*.tar.zst \
>
  --registry-url my-registry.example.com:5000 \
>
  --confirm

For registries using plain HTTP:

$
zarf package mirror-resources zarf-package-aicr-*.tar.zst \
>
  --registry-url localhost:5001 \
>
  --plain-http \
>
  --confirm

Overriding Component Values

The --set flag overrides Helm values at discovery time, changing which images appear in the output. This is useful when you know certain sub-components will be disabled in your deployment and want to exclude their images from the mirror list.

$
# Exclude GPU driver images (pre-installed driver scenario)
$
aicr mirror list --recipe recipe.yaml \
>
  --set gpuoperator:driver.enabled=false
$
$
# Pin a specific driver version
$
aicr mirror list --recipe recipe.yaml \
>
  --set gpuoperator:driver.version=570.86.16

The override key format is component:path.to.field=value, where the component name matches either the component name in the recipe or its valueOverrideKeys alias from the registry (e.g., gpuoperator for gpu-operator).

Relationship to Container Image Inventory

The Container Image Inventory is a static reference generated from recipes/registry.yaml with default values. It lists every image across all registered components regardless of recipe.

aicr mirror list is recipe-specific: it renders charts with the actual resolved values for your target configuration (service, accelerator, intent, OS). The resulting image list is typically a subset of the full inventory, limited to the components and sub-components your recipe enables.

Use the inventory for security audit and compliance. Use mirror list to generate the exact manifest for a specific deployment.