For environments without internet access, NVIDIA Config Manager provides a comprehensive airgapped deployment workflow that bundles everything needed for offline installation.
You might need to deploy Config Manager in an airgapped environment in situations such as:
Follow the instructions on this page to deploy a self-contained bundle for an airgapped environment. The bundle includes the Helm chart, container image tarballs, dependency charts and manifests, operator version pins, image loader manifests, an OCI registry upload helper, and the offline installer package.
This process is different from Nautobot’s Load Bootstrap Data job which seeds initial data into Nautobot. This tool uses deployment bundles for offline Kubernetes environments.
The instructions on this page assume you have a pre-built deployment bundle available, from NVIDIA or another source. If you do not have a deployment bundle, follow the instructions in Appendix: Developer Details to create your own.
The following components are assumed to be pre-installed and configured by your platform team:
ZTP and DHCP IP Addresses. The deploy script requires the IP addresses for the ZTP and DHCP load balancer services. To find available IPs for ZTP and DHCP services, query the existing MetalLB IP address pool:
List configured IP address pools:
View pool details including address ranges:
The output of the second command will be similar to the following example. In this case, the output shows a pool of available IP addresses from 10.0.100.200 through 10.0.100.210:
From the output of the second command, select two unused IP addresses for ZTP and DHCP services.
You will use these with the --ztp-lb-ip and --dhcp-lb-ip flags when deploying Config Manager.
Set the --lb-allowed-prefixes flag for the deploy script to the OOB (out-of-band) management network CIDR(s) from which devices will reach these services.
Transfer the bundle to the target host by using a storage medium or another approved transfer method.
The extracted bundle has the following layout:
Stage any site-specific content that the installer will reference, such as custom Nautobot jobs, template plugins, and OS images for ZTP, on storage that is reachable from the target host.
Before deployment, Config Manager images must either be reachable from an OCI registry inside the airgapped environment, or preloaded onto the target cluster nodes.
If the target cluster can pull from an internal registry, push the bundled image archives and packaged chart to an OCI-compliant registry that the cluster can reach.
The helper writes image-map.tsv with source and target image references. Use that map when configuring the container image registry and prefix values in install.yaml.
Use these options when they apply:
--include-dependency-charts mirrors dependency chart tarballs under charts/.--plain-http allows Helm chart upload to local HTTP registries used in test environments.If the target environment does not have an internal registry, preload the image tarballs before deploying.
For Kind or single-node test clusters, load images directly from the bundle:
For multi-node clusters with shared storage, copy images/ to the shared path and run the loader as a DaemonSet:
For SSH-based loading, provide the shared image path and node access details:
After preloading images, configure install.yaml with image references that match the images loaded into the node container runtimes.
Install the bundled installer package on the target host and verify the TUI is available.
The bootstrap script creates a local virtual environment from bundled wheels and does not require internet access on the target host.
Launch the TUI and save a repeatable installer configuration.
At minimum, confirm the following sections before deploying:
For more information about the configuration options, see the TUI Wizard Reference.
Treat install.yaml as sensitive. Depending on the choices you make in the TUI, it can include secret values or references to secret material.
Config Manager provides pre-configured resource profiles through the TUI Size field.
The requirements for the large profile are cumulative across all nodes. For example, a three-node cluster can satisfy the profile with 32 vCPUs and 86 GB RAM per node.
Deploy from the extracted bundle after install.yaml is complete and images are either reachable from the configured registry or preloaded on the cluster nodes.
When cluster.airgapped is true, the installer resolves operator manifests and dependency charts from the local bundle instead of the network.
If you preloaded images instead of uploading them to a registry, keep cluster.airgapped enabled and make sure the container image values in install.yaml match the references loaded into the node container runtimes.
To learn more about the installer and configuration screens, see the main installer documentation.
For common failure modes and recovery steps, see the Troubleshooting page.
After deployment, verify that pods are running, services are present, and the gateway is available. The commands below use the default nv-config-manager namespace; replace it if install.yaml uses a different namespace.
Configure DNS or /etc/hosts for the selected base hostname and service subdomains. In the example below, replace GATEWAY_IP with the gateway address from your deployment.
After pods are running and DNS is configured, open the Nautobot UI in your browser, for example https://nautobot.config-manager.example.com, and log in with the admin credentials.
Deploying Config Manager with the installer, including any post-deploy Nautobot jobs, is the only step required for day-0 bring-up.
Devices enter Config Manager through Nautobot. You can create them manually, through the Nautobot API, or with a post-deploy job such as a Nautobot Design Builder topology loader. The local SuperPOD profile includes a mock topology Design Builder job in development/mock_topology that you can use as a model before building your own offline context or job bundle. See Design Builder Data Loading for the job structure.
ZTP is initiated by the device, not by Config Manager. As soon as Config Manager has sufficient Nautobot data, it serves DHCP on the configured network. When a device is cabled and powered on, it gets an IP address and boot file from DHCP, then retrieves its configuration and firmware from the ZTP service. Devices that successfully complete ZTP show a status of Provisioned in Nautobot.
Validation or runtime errors from post-deploy jobs appear in the installer deploy output. Fix the job code, Design Builder design files, or context data and re-run the deployment with the same content.run_after_deploy configuration.
Open the Config Store UI, such as https://config-manager.example.com/configs, and confirm that intended configs are present for every device that should be rendered. If renders are missing, check the render service logs.
The commands below use the default nv-config-manager namespace; replace it if your deployment uses a different namespace.
Search log output for RenderException, Error processing event, or Python tracebacks to identify the failing device and cause.
To verify that devices have DHCP reservations, call the DHCP config endpoint, usually https://dhcp.config-manager.example.com/config?ip_version=4, and search for the device by hostname, IP address, or device UUID.
To verify that DHCP has sufficient data from Nautobot, check the logs of the config-refresh-v4 container in the DHCP refresh pods.
You do not need to redeploy from scratch when you change data, add images, update templates, or upgrade versions. Treat install.yaml as the source of truth: re-open it with ./installer/nv-config-manager-installer init install.yaml, adjust the configuration, and deploy again.
The deployer detects existing releases and restarts services only when relevant staged content changes.
To change topology, devices, or other data managed by a post-deploy job, edit that job’s context data or design files and re-run the deployment with the same post-deploy job configuration.
You can also make changes in the Nautobot UI. For subsequent deployments, remove the job configuration if you do not want the job to overwrite UI changes.
With file-backed OS image storage, add or update image entries in the OS Images section and re-run deployment. The installer updates the PVC layout and manifest, including checksums.
If the PVC is backed by NFS, you can also copy images into the expected path and update the manifest manually. Some environments support the ZTP upload endpoint, which can upload images without re-running deployment. See Upload Images to the ZTP Server for the full procedure.
Set the intended firmware version on the device or in a Config Context that applies to the device, such as by platform. You do not need a new Config Context for every image version.
For a new OS version, add a version-specific entry point in the templates repository, such as a 5.15.0 directory under the platform and role path. Templates are versioned so syntax changes can be tested per OS version.
install.yaml, add the job and context data, and deploy again.install.yaml with new image or template settings, or stage files on NFS where appropriate, then deploy again.To completely remove the Config Manager platform deployment:
Operators such as Envoy Gateway, cert-manager, and CloudNativePG are cluster-level dependencies. Remove them only if they are not shared with other applications.
Build the airgapped bundle on a host with internet access and permission to pull Config Manager images.
First, clone the Config Manager platform repository.
Next, build the bundle.
The script writes the bundle to deploy/airgapped/output/.
Add --include-skopeo to copy a local Skopeo binary into the bundle. When bundled Skopeo is present, the registry upload helper uses it automatically. Missing images fail the bundle build by default. Use --allow-missing-images only for diagnostics, because a bundle with missing images might not install offline.
Pre-release E2E test workflows can use --local-image-fallback after tagging local images to the same source references that the chart renders.
Before transferring a self-built bundle, validate the archive, expected files, installer bootstrap, and registry upload path.
Start with the checksum and bundle contents on the build host:
Verify the offline installer can bootstrap from the bundled wheels:
After you create an install.yaml, validate the installer config and generated Helm values against the bundled chart:
For a full functional validation, upload the extracted bundle to a disposable internal registry and deploy into a test cluster using the same registry override path planned for production:
Validation passes when the upload helper writes image-map.tsv, the installer deploys with cluster.airgapped: true, workloads do not enter ImagePullBackOff, operator installs use bundled manifests/ and charts/, and no workload tries to pull from public source registries.