Running Argo CD in an air-gapped cluster: what the work covers
Argo CD can run offline when every image, Git source, Helm chart, OCI artifact and identity call it makes is served from inside your network. Teams usually reach this pattern when they must deliver to clusters with no outbound internet access, such as isolated production segments, classified or regulated environments, or operational networks where change has to cross a controlled boundary before it reaches a cluster. Argo CD is licensed under Apache-2.0 and the project offers no paid edition, so the work here is about mirroring, configuration and evidence rather than licensing. Nothing in the software itself requires a public connection once its dependencies are placed inside the boundary.
The work covers five dependency paths: the Argo CD container images and the images of the components it deploys, the internal Git server that holds your manifests, the Helm and OCI registries that hold charts and packaged artifacts, the identity provider used for SSO, and the patch process that brings new Argo CD releases across the boundary. For the registry side, the decisions are whether to replicate images into a private registry or pull them through a proxy cache inside the network, and how each artifact is verified before it is admitted. For SSO, the question is which connector or OIDC endpoint can be reached without outbound calls, since bundled Dex connectors that depend on external services need an internal alternative. The page also addresses how to patch Argo CD on the project's current supported minor releases without pulling from public sources.
Before you commit to a plan, confirm three things with your own environment: which network path your clusters and build hosts have to any internal mirror, which Argo CD version you will pin and where its image digests will be recorded, and who owns the transfer of new releases across the boundary. Ask any partner to show the exact list of hosts the running installation contacts, because a single missed call, such as a Dex metadata fetch or a Helm repository lookup, will fail only at the moment someone tries to sync. The sections that follow take each path in turn, so your team can decide which parts to build in-house and which to scope as a fixed deliverable.
Which Argo CD dependencies must resolve inside your network
An air-gapped Argo CD install reaches out to more places than its own pods. Each of the six dependencies below must resolve inside your network, or a specific operation fails. Argo CD keeps its state in Kubernetes objects and treats Redis as a disposable cache, so the replication work centers on images, Git, registries, identity and bootstrap sources rather than on a database.
Argo CD component container images
Every Argo CD workload pulls its own image: the API server, repo server, application controller, and the bundled Dex and Redis components if you use them. Mirror each image at the exact tag you deploy, then point the manifests or Helm values at your internal registry. If a pod cannot pull, that component never starts, and the rest of the install stalls. Ask your platform team who approves new tags and how mirrored digests are recorded in change control.
Git repositories Applications read from
Argo CD reads desired state from Git, and the repo server clones on every refresh. Your internal Git host must hold both the configuration repositories and any Helm or Kustomize sources your Applications reference, because a sync cannot succeed against content it cannot fetch. Decide whether the mirror is a read-only replica or the primary, and confirm which branches and tags are replicated. The repo-server also runs Helm and Kustomize on repository content, so mirrored repositories should be reviewed before they are trusted.
Helm chart and OCI registries
Applications that deploy from Helm repositories or OCI chart references need those artifacts available internally. Mirror the charts and any chart dependencies they pull, including subcharts, since a missing dependency fails the render rather than the pull. Harbor can host OCI Helm charts and replicate them from upstream sources in a controlled batch. Confirm with your application owners which charts are in scope and who signs off on each new version.
Dex connectors that call identity providers
Bundled Dex reaches out to its upstream connectors, and OIDC integrations contact the provider's discovery and token endpoints. Connectors such as GitHub or a hosted SaaS identity service need outbound calls that an isolated network does not allow. Plan the identity source as an internal service, such as LDAP, SAML or a self-hosted OIDC provider, and confirm each connector's endpoints before cutover. Admin access depends on this path working, so test a login path that does not require the public internet.
Redis and cluster bootstrap images
Redis, the Kubernetes control plane and the networking, DNS and ingress add-ons used during cluster build all pull images at bootstrap time. Redis is a disposable cache, so losing it causes a refresh rebuild rather than data loss, but the pod still needs its image to start. Kubernetes supports pre-pulling control plane images with kubeadm and pointing the installer at a private registry. Ask your cluster team which bootstrap images are mirrored and whether they match the Argo CD manifest versions.
CRD and manifest sources
Argo CD installs its custom resource definitions and core manifests from a release artifact or a Helm chart, and that source must be copied into your network before the install. Store the exact manifest files in your Git host and record their checksums. Upgrades depend on the same copy, so a new release needs a new reviewed mirror. Keep the install and upgrade manifests under the same change control as the workloads they create.
How to get images and charts across the boundary
A self-hosted registry gives the platform team one place to hold Argo CD images, Helm charts and any other OCI artifacts the cluster pulls. Harbor is licensed under Apache-2.0 according to its GitHub repository, and it stores container images and Helm charts as OCI artifacts, so one registry can serve both. In a common pattern, a staging Harbor on a connected network pulls from upstream sources, and a Harbor inside the isolated network receives approved content through replication. Replication rules can run push-based or pull-based, filter by repository name, tag, label and resource type, and trigger manually, on a cron schedule or on push and retag events. Proxy cache projects serve a cached copy when the upstream is unreachable, which helps during outages but does not replace an approved, versioned copy.
- Who runs it: the platform team owns the replication rules, and the security team approves which repositories and tags are allowed across the boundary.
- How often: scheduled runs suit routine patch intake, while manual triggers suit an approved release that must cross on a specific day.
- Integrity checks: pin images by digest in manifests, record digests in the change ticket and confirm signatures or scan results before a rule replicates into the isolated side.
- Bandwidth and scope: a per-task bandwidth limit and tight filters keep transfers predictable and stop unrelated repositories from crossing.
- Proxy cache caveats: cache projects are read-only for pushes and carry a default 7-day retention policy, so confirm retention settings before relying on them for audit evidence.
Confirm version-specific behavior, supported endpoints and replication options with the Harbor documentation for the release you deploy, since these features change between releases.
Some teams skip a registry on the isolated side and use scripts to pull, retag and push artifacts from a staging network into an internal registry, or into a Git server that serves the manifests and charts. This approach needs little infrastructure, but it moves the reliability burden into code the team must write, test and maintain. The script becomes a controlled change: it defines the exact list of images, chart versions and Git refs, and it should fail loudly when something is missing rather than skipping it. Because the script is the process, its logs and inputs are the evidence auditors will ask for.
- Who runs it: a named platform engineer owns the script, and a second engineer reviews changes to the artifact list.
- How often: run it on a fixed cadence tied to Argo CD patch releases, and run it again for any out-of-band fix.
- Manifest of inputs: keep a version-controlled list of every Argo CD image, Redis image, Dex image and chart version, with digests.
- Integrity checks: compare digests and checksums on both sides of the transfer, and store the checksum file next to the artifacts.
- Failure handling: treat any missing artifact or digest mismatch as a stop condition and record the run result in the change record.
Before relying on a script, confirm the complete image list for your Argo CD version with the upgrade notes and release artifacts, because a missing component often shows up only during a failed sync.
Where no network path exists at all, artifacts travel on approved removable media. The bundle is built on the connected side, scanned, signed or checksummed, and carried across by a controlled process. This method suits low-change environments and sites with strict media rules, but it is slow to refresh and easy to get wrong when the bundle is incomplete. A bundle should be a complete, self-describing set: images as archives, chart packages, manifests, a file listing every artifact with its digest, and the exact version of each component. Anything missing from the bundle becomes a failed sync on the isolated side.
- Who runs it: the security team usually approves and logs media transfers, while the platform team builds the bundle.
- How often: bundles follow the patch release cadence the team has chosen, plus any emergency fix that has been approved.
- Integrity checks: generate a checksum manifest on the connected side, verify it again after media is loaded, and keep a record of who handled the media.
- Scanning: run malware and vulnerability scanning on the bundle before it enters the boundary, following the site's media policy.
- Completeness: test each bundle on a staging cluster that has no internet access before it is used in production.
Confirm your site's media handling and transfer rules with your security team, since these requirements vary by sector and authority.
Configuration choices and when each fits
This table compares the main choices for feeding images, charts, Git content and identity into an air-gapped Argo CD install. Read each row for what it changes in the cluster, when it fits your boundary, and what it costs you to operate later. Most teams combine a mirrored registry with an internal Git host and then tighten the admin account once SSO works.
| Option | What it changes | When it fits | Trade-off |
|---|---|---|---|
| Harbor proxy cache | Pulls upstream images on first request and keeps a local copy, so clusters pull from one internal address | Connected staging can reach public registries while production cannot, and you want on-demand pulls | Cached copies expire under the default 7-day retention policy, and first pulls still need upstream access |
| Harbor replication rules | Copies selected repositories and tags into the isolated Harbor on a schedule, on push events or manually | You know the exact image set Argo CD and its add-ons need and want a reviewed, pinned inventory | You must maintain the filter list, and new image versions do not appear until a rule copies them |
| Internal Git hosting | Argo CD syncs from a Git server inside the boundary that your team controls | Change approvals and commit history must stay in your environment | You own backups, access control and patching of the Git service itself |
| Read-only Git mirror | Content is pushed one way from a connected zone into an internal repository that Argo CD only reads | Source code stays in an external host but the cluster must not reach it directly | Each transfer adds a review step, and commits can lag the source until the next sync |
| Helm charts from an OCI registry | Charts are stored as OCI artifacts in Harbor and referenced by registry path and version | Chart versions must be pinned, scanned and promoted like images | Charts that reference public images or remote dependencies still need those artifacts mirrored |
| Vendored manifests in Git | Rendered YAML is committed to your repository and Argo CD applies plain files | The cluster has no Helm or registry dependency and reviewers must read every change | Upgrades mean re-rendering and reviewing large diffs, and drift from upstream is easy to miss |
| Disable the admin user (admin.enabled set to false) | Turns off the built-in admin login after SSO or local users work, removing a shared password | SSO through Dex or direct OIDC is confirmed working and at least one other administrator can log in | Break-glass access depends on a recovery path you must test before disabling |
| Keep the admin user enabled | Local admin login stays available independent of the identity provider | Initial setup, or an identity provider outage would otherwise lock every operator out | A shared credential remains a standing risk that auditors will ask you to explain |
Which Dex connectors fail without outbound calls
Connectors that call a public service will fail on an isolated network. Argo CD bundles Dex, which offers SAML, LDAP and GitHub connectors, and teams can also point Argo CD straight at an existing OIDC provider such as Okta, Auth0, Microsoft, Keycloak or Google Workspace. The GitHub connector depends on GitHub's public endpoints, so it will not complete sign-in from a network with no outbound path. Before you build the air-gapped cluster, list every identity source your users need and check whether each one is reachable from inside the isolated network. A provider you host inside your own boundary, an LDAP directory or a SAML identity provider that your network routes internally can work, provided the Dex or Argo CD pods can resolve and reach those addresses and trust their certificates. Confirm the routing and the certificate chain in a test cluster before cutover, not during the first outage.
Keep the built-in admin user until SSO is proven, then disable it. The user management documentation recommends using the admin account only for initial setup and disabling it with admin.enabled set to false once local users or SSO are configured. In an air-gapped environment, that account is often the only way back in if the identity path breaks, so record how you will recover access before you turn it off and test that path. Also check the RBAC mapping during offline setup. Argo CD 3.0 changed Dex-based RBAC to use the federated_claims.user_id claim, so role bindings written against earlier claim values may stop matching users after an upgrade. Decode a real token from your provider in the offline environment and confirm the claim your policy expects is present.
Mirror what the login flow depends on, not only the container images. Dex and the Argo CD API server need their configuration, certificates and any connector libraries to be present on the cluster before the first login attempt. Plan a change record that lists each connector, its internal endpoint, the certificate authority it trusts and the claim used for role mapping. Ask your SSO and platform teams to confirm which of these endpoints live inside your network and which need an approved exception. Any connector that still requires an outside call should be treated as an open decision for your security review rather than an assumption to be fixed later.
How to build the offline Argo CD install in sequence
This sequence takes an Argo CD installation from a connected staging area to a cluster with no route to public sources, with a check at each step so the team can confirm the install works offline before relying on it.
Inventory every image and manifest
Start by listing everything the chosen Argo CD release needs: the install manifests or Helm chart version, each container image those manifests reference (API server, repo server, application controller, Redis, Dex if used), and any CRDs. Record the exact tags, not floating labels. Confirm the release you choose is one of the minor lines still receiving patch releases, since the release process only supports the three most recent minor versions. Also list the Helm charts, Kustomize bases and plugin images your Applications will pull. The output is a versioned bill of materials that your platform team signs off. Check: every image reference in the rendered manifests appears on the list, and nothing is pulled from a tag that is not recorded.
Stand up internal registry and Git services
Provision an internal container registry, an OCI-capable Helm chart store and an internal Git server inside the isolated network. Harbor is one option: it is Apache-2.0 licensed, stores images and Helm charts as OCI artifacts, and can act as a proxy cache or replication target. Your platform team should confirm the registry and Git product versions, storage sizing, TLS certificates and the trust chain that Kubernetes nodes and the repo server will use. Plan backups for these services, because Argo CD will depend on them for every sync. Check: from a node in the air-gapped network, you can push and pull a test image and clone a test repository over the internal names.
Mirror and verify images and charts
Transfer the inventoried artifacts across the boundary using your approved media process, then push them into the internal registry under the same tags. Verify each artifact before it is admitted: compare digests against the vendor-published values, scan images with your chosen scanner and keep the results with the change record. Your supply chain procurement process should define how software integrity and authenticity are checked for anything carried across the isolated boundary. Check: a digest comparison report shows every mirrored image matches its source digest, and the scanner results are stored with the release record.
Define repositories as Kubernetes Secrets
Register each internal Git repository and Helm or OCI source as a Kubernetes Secret labeled for Argo CD, not in the argocd-cm ConfigMap, because repository configuration in argocd-cm is no longer supported from Argo CD 3.0. Use the internal host names and the credentials your Git server issues, and store the Secret manifests in your own bootstrap process rather than typing them into the UI. Check: Argo CD lists each repository with a successful connection status, and the credentials are not visible in API responses or logs.
Point Argo CD at internal sources
Update the Argo CD install values or manifests so every image reference resolves to the internal registry, and set the image pull secrets for the nodes. Make sure the Helm chart or Kustomize base references your internal registry rather than public defaults. If you use a Helm chart, confirm the chart version matches the image versions you mirrored. Check: the rendered manifests contain no references to public registries, and all Argo CD pods reach Running state.
Configure Dex or direct OIDC against internal endpoints
Configure single sign-on so every identity endpoint is internal. If you use the bundled Dex, confirm that the connector you chose, such as LDAP or SAML against your directory, does not need an outbound call to a public service, since some connectors do. If you use a direct OIDC provider, host it internally and confirm its discovery and token endpoints resolve inside the network. Keep the built-in admin user for initial setup only and disable it with admin.enabled set to false once SSO works. Check: a test user signs in through the internal identity provider, the group claim maps to the expected Argo CD role, and the admin account is disabled.
Run a sync test with no public route
Create a small test Application that points at the internal Git repository and deploys a known manifest to a non-production namespace. Confirm the sync completes and the resource reaches a healthy state. Then verify isolation from the cluster side: from a pod or node, attempt to reach public registries and public Git hosts and confirm the connections fail. Record the results. Check: the sync succeeds, the Application reports Synced and Healthy, and every outbound attempt to public sources is blocked.
Rehearse a patch release
Before the first production upgrade, run a patch rehearsal on a staging cluster built the same way. Pick the next patch release for your minor line, mirror it through the same verified process, update the internal references and perform the upgrade. Confirm the Argo CD components restart cleanly, sync tests still pass and rollback steps work. Document the steps and the evidence so the production change repeats the same path. Check: the staging upgrade completes with no outbound calls, and the runbook records each artifact, digest and test result.
How patching works when public sources are off limits
Plan every Argo CD patch around a release cadence that never stops. The Argo CD release process ships a minor release four times a year, roughly once every three months, and only the three most recent minor versions receive patch releases. In an air-gapped cluster, that means a minor version you have running will age out of patch coverage on a schedule you do not control, so the upgrade calendar has to be owned by your team. Track the Argo CD release process and cadence and the patch releases on the argoproj/argo-cd GitHub releases page, then decide in advance which minor line you will stay on and how long you accept a gap before moving forward.
Each new patch release should enter the enclave through the same verified path as the original images, manifests and chart versions: mirrored into your internal registry, checked for integrity and authenticity under your own supply chain procedure, then promoted into a staging enclave where the same Application sets sync and the SSO login, RBAC policies and repository secrets are exercised. Harbor is often the staging point for images and OCI artifacts, and its release notes deserve the same attention. Back up the Harbor database before any upgrade, as the v2.15.2 release notes recommend, and be ready to run a reindexdb pass if index problems appear. The v2.15.3 release introduced a breaking change in which webhooks to internal network addresses are blocked by default, so confirm that any internal notification or pipeline endpoint still receives events before promoting.
Minor version jumps carry their own checks. The Argo CD 2.14 to 3.0 upgrade notes describe three changes to handle before you move: update and delete RBAC now apply only to the application itself, logs access requires an explicit logs, get permission, and annotation-based resource tracking is the default. Repositories must also be defined as Kubernetes Secrets rather than in argocd-cm, and Dex RBAC keys on federated_claims.user_id. Export and review your current policy.csv and repository definitions in staging, because a patch that changes access behavior can lock out operators in a cluster that has no internet fallback.
Security risks specific to an isolated Argo CD
An air-gapped Argo CD still executes repository content, trusts internal certificates and holds cluster credentials, and the isolation changes who checks each of those inputs. The cards below cover the risks the security documentation names and the controls an isolated install needs around them.
Repo-server executes repository content
The repo-server runs Helm and Kustomize against repository content to render manifests. In an isolated network, that content usually comes from internal Git and OCI registries, so the question is who can merge to them. Only internal, reviewed repositories should be trusted as inputs, and out-of-tree file access should be planned as a risk to control. Check which teams can write to each repository Argo CD reads from.
Internal certificates need an owner
Argo CD authenticates API requests only with JSON Web Tokens and uses TLS for traffic, including between its own components. Without public certificate authorities, every certificate chain must come from an internal CA that your team issues, renews and rotates. Name the owner of that CA and its renewal process before installation, because an expired internal certificate can stop the UI, the CLI and component communication at the same time.
Credentials stored as Kubernetes Secrets
Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs, but redaction does not protect them at rest. Since Argo CD 3.0, repositories must be defined as Kubernetes Secrets, so access to those Secrets in the Argo CD namespace is access to your Git credentials. Restrict Secret read permissions, and confirm how encryption at rest is handled in the cluster before the isolated install goes live.
Supply chain verification at the boundary
Every image, chart, manifest bundle and binary carried across the air gap is software you must verify before it runs. NERC CIP-013-2 requires supply chain procurement processes to address verification of software integrity and authenticity, which is the control behind checking each package at the boundary. Where that standard applies, record the checksum or signature check for every import and keep it with the transfer record. Organizations outside its scope can apply the same practice as a matter of policy.
Audit trails for every import
An isolated environment has no external service to show what was pulled, when and by whom. Build an audit trail for each import into the enclave, covering the artifact, its source, its verification result, the approver and the date it reached the cluster. Confirm which Argo CD and Kubernetes audit events are retained inside the network, where they are stored and how long they are kept, since those answers depend on your logging stack.
Questions buyers ask about air-gapped Argo CD
What drives the cost of running Argo CD in an air-gapped cluster?
The cost follows the number of artifacts you must mirror, the number of internal sources Argo CD must reach, and how many clusters carry the same process. The main components are design work on the mirror and sync process, building the internal registry, Git and chart endpoints, wiring identity without outbound calls, and writing the runbook your team will follow later. Most of that is one-time work. Recurring costs are the mirror refresh for each Argo CD patch release, the review of each imported package, and support time. Ask any quote to split these items, name who performs each one, and list the Argo CD version and clusters in scope.
How long does an air-gapped Argo CD project take?
Duration depends on how many images and charts must be carried across the boundary, how many internal Git and registry services already exist, and how complex the identity setup is. A single cluster with an existing internal registry and an identity provider reachable from inside the network takes far less time than a fleet with a new registry, custom Dex connectors and several Argo CD instances. Dex connectors that need outbound calls, such as those reaching a public identity source, add design and testing time because they must be replaced or routed internally. Ask for a timeline tied to a written list of components, owners and approval gates, rather than a single number.
What do we need from our own teams for an air-gapped Argo CD build?
The work needs four groups of people to commit time. The registry owner provides a private registry, such as Harbor, and decides how images and charts are imported. The Git owner hosts the manifests and Helm or Kustomize sources inside the boundary. The identity owner confirms which SSO path works without outbound calls, and the network owner approves the transfer process, firewall rules and the path for media or one-way data flows. Each group also reviews the content it approves. Ask the vendor to name the inputs each group must provide and the dates by which they are needed.
Can our internal platform team run air-gapped Argo CD without a partner?
Yes, a platform team can do this alone if it already runs Kubernetes, a private registry and an internal Git server, and it has someone who can write and test the mirror process. The harder parts are the ones that have no public fallback: verifying every package crossing the boundary, handling Dex connectors and keeping the runbook current. A partner is useful when the team has never built an offline install, or when audit evidence must be prepared alongside the build. Ask for a written scope that lists what you will keep and what the partner delivers, so you can compare the two options on the same basis.
How does patching Argo CD differ when the cluster has no internet access?
Patching offline is a transfer and verification process rather than a pull. The Argo CD release process ships patch releases only for the three most recent minor versions, so your mirror must track those lines and you must choose a supported version before each cycle. Each release needs its images and any chart versions downloaded from a connected staging point, checked for integrity and authenticity, imported into the internal registry, and then deployed through a change record. Plan for a regular review of the release notes, a test in a non-production cluster, and a rollback path that uses the previous mirrored images. Confirm the cadence with your own change board before the first cycle.
Which controls should an air-gapped Argo CD build include for audit evidence?
An offline build should keep a record of every artifact that crossed the boundary, including its source, version, checksum and approver. That record supports the software integrity and supply chain expectations found in NERC CIP-013-2 for utility environments, and similar vendor-verification questions in other frameworks. Argo CD's Git-based change flow, projects and RBAC also produce evidence of who changed what. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors issue any audit report or certification. Confirm with your assessor which artifacts they expect before the build begins.
How does DeployOpen scope an air-gapped Argo CD engagement in writing?
DeployOpen works from a written scope before any build starts. Most engagements are fixed-scope, so the agreement names the clusters, Argo CD version, registry and Git endpoints, identity path, mirror process, deliverables and the acceptance tests. It also lists what the client's teams must provide and what happens to changes in scope. Ongoing patch cycles, upgrades and testing can be added as retainers. DeployOpen does not publish a price list, so a quote follows from that written scope. Ask for the scope document to state the assumptions behind the size of the mirror and the identity setup.
How DeployOpen works on this
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure, including air-gapped networks. For Argo CD in air-gapped Kubernetes clusters, we start with a written inventory of what must cross the boundary, then build and test the mirrored image, chart, Git and registry path before anything is handed over.
How we scope
- Inventory every Argo CD image, Helm chart, Git repository and OCI artifact the cluster needs, with its source and approval owner.
- Confirm which Dex connectors, if any, need outbound calls and decide whether each one is removed, replaced or reached through an internal endpoint.
- Agree the written, fixed scope, including deliverables, timelines and acceptance tests, before any work starts. Ongoing support is available as a retainer.
How we build
- Set up internal Git, Helm and OCI registries and mirror the Argo CD images with checksums recorded for each transfer.
- Point Argo CD manifests, Helm values and repository Secrets at internal sources, then test syncs from a cluster with no internet route.
- Test the patch path end to end, including how a newer patch release is verified, imported and rolled out from an internal source.
How we hand over
- Document the transfer procedure, mirror inventory, version pins and the owner for each internal source of truth.
- Provide runbooks for importing a new Argo CD patch release and for handling a failed mirror sync or expired credentials.
- Walk your platform and security teams through the working system and the evidence they need for change and configuration reviews.
How we support
- Support can be scheduled as a retainer covering patch imports, upgrade planning and changes to the mirror inventory.
- Track the Argo CD minor release cadence and the three most recent minor versions that receive patch releases, so your patch plan stays current.
- Confirm with the Argo CD project and your own environment before each upgrade, since major upgrades carry breaking changes.
