How to install Apache Airflow in an air-gapped network
Airflow can run in an enclave with no internet route, but only when every container image, PyPI package, constraint file and DAG source is staged inside the boundary before the first install. Nothing in the install path can reach out to fetch a missing dependency, so the staging list is the real project plan. Airflow is an Apache Software Foundation project released under the Apache License 2.0 (SPDX: Apache-2.0), and the project itself offers no paid edition, so the cost of this pattern is the engineering and operations work of mirroring and maintaining the artifacts, not a license fee. Teams usually need this pattern when pipelines move regulated or classified data inside a network that cannot reach public registries or package indexes, and the scheduler has to keep running there.
Start by listing every input the install touches: the Airflow and provider packages, the constraint file for the exact Airflow release and Python version, the base and provider container images, the database and Redis images if you use them, and the Helm chart if you deploy to Kubernetes. The constraint file is the item most often missed. The *PyPI installation guide* explains that constraints apply only to the pip command they are used with, so you should freeze and host your own constraints file on an internal server and point every install step at it. Confirm the exact constraint URL pattern and supported Python versions against the supported versions and prerequisites pages for the release you select, because those values change between releases and should not be copied from older notes.
Then decide how the enclave receives updates. Patches and provider upgrades should pass through a staging zone where you pull new packages, scan them, rebuild the internal mirror and test the DAGs against the new versions before the production enclave sees them. Ask your team to confirm which DAG source will sit inside the boundary, since the Helm chart documentation says DAGs must come from a single Git repository, and to confirm whether any secrets backend the DAGs read from is reachable from inside the enclave. Plan the mirror, the staging zone and the internal Git server as operated services with owners, because a stale mirror is the most common reason an air-gapped Airflow falls behind its supported release line.
Which install path fits an enclave: images, PyPI or Kubernetes
This table compares three ways to install Airflow 3.3.2 inside an enclave: container images on Kubernetes, PyPI on virtual machines, and a single-host setup. Read each row as a question to answer for your environment, since the artifacts you must mirror and the skills you need follow directly from the path you choose. The main takeaway is that every path needs the same mirrored Python, database and provider inputs, and the path mostly changes how many components you must move and operate.
| Factor | Kubernetes with container images | PyPI on virtual machines | Single-host setup |
|---|---|---|---|
| Artifacts to carry in | Airflow image, Helm chart, provider and base images, plus Kubernetes control plane images | Python packages, constraints file, OS packages for providers, and Python 3.10 to 3.14 interpreter | Python packages or a single image, plus the metadata database packages |
| Components to mirror | Container registry, Helm repository, image pull path and cluster add-ons | Package index mirror, constraints host and interpreter installers | Package mirror and database software only |
| Metadata database | PostgreSQL 14 to 18 or MySQL 8.0, 8.4 or Innovation release, external to the cluster | PostgreSQL 14 to 18 or MySQL 8.0, 8.4 or Innovation release, external to the hosts | SQLite is not for production; plan PostgreSQL or MySQL even on one host |
| Kubernetes version | Kubernetes 1.30 to 1.35 for Airflow 3.3.2, confirmed against your mirrored cluster images | Not required | Not required |
| Required operational skills | Kubernetes administration, registry operations, Helm release management and image rebuilds | Linux service management, Python packaging and separate service units for each Airflow component | Linux administration and manual upgrades with limited recovery options |
| Airflow 3 components to run | API server, scheduler, DAG processor and triggerer as separate workloads | API server, scheduler, DAG processor and triggerer as separate services | Same four components on one host, which raises shared-failure risk |
| Database engines to avoid | MariaDB is unsupported; confirm the database image you mirror | MariaDB is unsupported; confirm the database packages you mirror | MariaDB is unsupported and SQLite should not be used in production |
| Ask your team to confirm | Whether your cluster and registry meet the supported Kubernetes range before mirroring | Whether your interpreter and OS packages are mirrored for the providers you need | Whether a single host meets your availability and recovery expectations |
What must be mirrored before the cut-off
Once the network is isolated, Airflow cannot fetch anything it needs at install or run time. Each item below must be copied across the boundary before the cut-off, and each has a producer, a verification point and a failure mode if it is missing.
Airflow and provider container images
Mirror the Airflow image you build from, plus any base image your build uses, into your internal registry under a fixed tag. Your team or the image build pipeline produces these, and the registry scan step is where you verify digests and vulnerability results before anything is promoted. If an image is missing, pods fail to pull and the cluster stays on the previous release, so a patch cycle stalls on the first unmirrored layer. Confirm which tags your Helm values reference before the cut-off.
Python packages and provider wheels
Mirror the Airflow core package and every provider you use into an internal PyPI index, installed in the separate provider step pinned to the Airflow version. Your build team produces the mirror from an approved staging zone, and the verification step is a clean install inside the enclave. A missing wheel fails the pip resolve, and a partial mirror tends to surface only when a new provider is added. Record hashes for every file you carry across.
Internal constraint files
Download the constraints file for your exact Airflow version and Python version, then host it on an internal server and point your install commands at that copy. Your platform team owns the file, and it should be checked into version control with a change record. Constraints apply only to the pip command they are used with, so every install step must reference the internal copy. If the file is missing or stale, pip resolves newer transitive versions and the install can silently become unusable.
Helm chart package
If you deploy with the official Helm chart, carry the chart archive into the enclave together with the image tags it pins. Your platform team produces the copy from a reviewed release, and verification is a template render against your internal values files. Without it, the release cannot be installed or upgraded, and any values file that pulls a public chart source will fail. Confirm that the chart version matches the Airflow image version you mirrored.
DAG Git repository
Mirror the DAG repository onto your internal Git server, including full history and the branches your promotion process uses. Your data engineering team owns the content, and the security team should confirm which commits crossed the boundary. The chart's git-sync setup expects a single repository, so a missing or partial mirror leaves the scheduler without DAGs and stops new runs from being parsed. Confirm the sync credentials and the known-hosts entry point at the internal server.
OS packages for providers
Some providers need system libraries, such as client libraries for databases or drivers, that are installed through the operating system package manager. Your platform team produces an internal package repository or local mirror for those packages, and verification is a build of the custom image with no outbound access. Missing packages surface as build failures or as import errors at task runtime, which can be harder to trace than a failed install. List each provider's system dependencies before the cut-off.
How constraint files keep an offline Airflow installable
Airflow publishes a constraints file for each release and Python version, and an offline installation depends on it more than a connected one does. A plain pip install apache-airflow resolves Airflow's many dependencies to whatever versions are current at the time of the run, which can produce an installation that imports incorrectly or breaks in ways that are hard to trace. The constraints file records a tested set of dependency versions for one Airflow release and one Python version, so the same pins can be reproduced later from a mirror. Before you mirror anything, confirm that your Python version appears in the release's constraints file, because the file is generated per Python version and a mismatch is a common cause of failed offline builds. The Installing from PyPI guide explains the URL pattern and the install commands.
Providers are installed in a separate step, pinned to the Airflow version, rather than in the same command as Airflow itself. This keeps the core install predictable and lets you add only the provider packages your DAGs need. In an air-gapped network, every provider you plan to use must already be in the internal package mirror before the install runs, so the provider list belongs in the same change record as the Airflow version. Your team should freeze its own constraints file, copy the upstream file for the chosen release and Python version, and add or adjust pins only after a test install passes. Host that file on an internal web server or artifact repository, and reference it with the constraint option in every install command, such as pip install --constraint pointing at the internal URL.
The most common failure in this setup is assuming that a constraints file applies everywhere. Constraints apply only to the pip command they are used with. A later pip install for a new package, or an upgrade run from a build pipeline that omits the constraint option, can silently pull in versions that the frozen set was meant to exclude. Build tooling should therefore hard-code the internal constraints URL in every install step, and the team should rebuild the full environment from scratch on each Airflow patch release rather than adding packages to an existing one. Ask the platform owner to confirm which Python versions your mirror will carry, and record the constraints file hash with each approved build so an auditor or reviewer can trace which dependency set ran.
How DAGs reach an enclave from an internal Git server
DAG files are copied into the Airflow image at build time, so every DAG change produces a new image that the enclave registry must store. The scheduler reads DAGs from its own filesystem, which means a change reaches it only after the Helm release points at the new image tag and the pods restart. Rollback means redeploying the previous image tag, which is quick only if the earlier image is still in the internal registry.
- Change path: commit the DAG, build the image inside the enclave, push it to the internal registry, then upgrade the release with the new tag.
- Rollback: set the image tag back to the last known good build, and keep prior tags in the registry until your rollback window closes.
- Git server role: the build pipeline reads the DAG repository, so the server must be reachable from build runners inside the enclave, with no outbound path needed.
- Coupling: every DAG edit becomes a full image rollout, which ties DAG releases to image builds and to any dependency changes baked into the image.
- Single repository: the build copies one repository's contents, so DAGs kept in several repositories need a merge step before the build starts.
Check that your registry retains old tags and that the build pipeline runs without access to public package indexes.
A git-sync sidecar runs alongside Airflow and keeps a checkout of the DAG repository up to date. With persistence disabled, each pod clones the repository into temporary storage when it starts. With persistence enabled, the checkout lives on a volume and survives pod restarts. In both cases the sidecar polls the internal repository, updates the files, and the scheduler parses the changed DAGs from the shared directory.
- Change path: merge to the watched branch, the sidecar pulls the commit on its next sync, and the scheduler parses the new files.
- Without persistence: a restarted pod clones whatever sits at the branch head, so a bad commit can reach a pod that was previously healthy.
- With persistence: the checkout survives restarts, but the volume needs its own backup and recovery plan.
- Rollback: revert the commit on the watched branch or move the watched reference to a tagged release, and avoid rewriting history the cluster has already pulled.
- Git server requirements: serve the repository over an internal HTTPS or SSH path, provide a read-only deploy credential, and trust the internal certificate authority. For SSH, supply known hosts entries.
Confirm your chart version and whether its git-sync settings support pinning to a specific reference. The Helm chart DAG file guidance explains the recommended layout.
An externally populated PersistentVolumeClaim is mounted by Airflow pods, but a process outside the Helm release fills it with DAG files. A common pattern is a scheduled or event-driven job that clones the approved commit from the internal Git server and writes the DAG folder to the volume. Airflow pods never talk to Git, so the repository credential stays with the populating job.
- Change path: the job writes the approved commit to the volume, and the scheduler picks up changed files without a pod restart.
- Rollback: the job redeploys an earlier commit. Unless you keep versioned directories, a bad write replaces the only live copy.
- Storage access: confirm the volume's access mode lets every component that reads DAGs mount it at the same time.
- Partial writes: a sync that fails midway can leave a mixed DAG folder, so write to a new directory and switch over in one step if your storage allows it.
- Single repository: the job maps one repository to the DAG folder, so combining repositories must happen before the write.
Ask the team that owns the storage class how it handles concurrent readers and whether snapshots can serve as a rollback point before you adopt this option.
Setup sequence for an air-gapped Airflow install
This sequence takes an Airflow release from a version decision on the outside network to a running, internally sourced installation with DAGs and secrets working inside the enclave. Each step closes with a check that the next step depends on.
Choose the Airflow and Python versions
The platform owner and the Airflow lead pick one Airflow 3 patch release and one Python version from the supported range in the prerequisites, then confirm the metadata database engine and Kubernetes version if you run on a cluster. Check the version life cycle table so the release is in a supported phase for the planned life of the enclave. The output is a written version record covering Airflow, Python, PostgreSQL or MySQL, and every provider you expect to need. Confirm the current patch release with the project before you commit, because the table changes over time.
Build the outside staging mirror
On the connected staging network, the build team pulls the chosen Airflow image, its base layers, Python packages and any OS packages the providers need, then mirrors them into an internal registry and package index that the enclave can reach. Record the source and digest of each artifact in a manifest. The check is that every artifact in the manifest resolves from the staging mirror and that the mirror lists the full dependency set, not only the direct requirements.
Produce and freeze the constraints file
The build team downloads the official constraints file for the chosen Airflow release and Python version, installs Airflow and each provider in separate pinned steps on the staging network, and then freezes the resolved set into an internal constraints file. This file is hosted on the internal server and becomes the only source of versions for enclave installs. The check is a clean resolution from the frozen file with no network access, and a dependency diff that the security team has reviewed and signed off.
Transfer and verify artifacts across the boundary
The approved transfer process moves the image archives, package bundle, constraints file and manifest across the isolation boundary under your media and change controls. Inside the enclave, the security team recomputes checksums and verifies signatures where the publisher provides them, and compares each item against the manifest. Records of who approved each transfer are kept with the manifest. The check is that every item matches its recorded checksum and that nothing is imported that is absent from the manifest.
Deploy the metadata database and Airflow components
The platform team deploys PostgreSQL or MySQL inside the enclave, runs the database initialization from the internal image, then starts the API server, scheduler, DAG processor and triggerer as separate services or pods. SQLite is not an option for production, and MariaDB is not supported. The check is that each component starts from the internal image, that the scheduler and API server connect to the metadata database, and that the components show healthy status with no outbound connection attempts in the firewall logs.
Connect internal Git for DAG delivery
The data platform team points the DAG processor at the internal Git server, or delivers DAGs through a pinned image or populated volume if your delivery model uses one. Each DAG source is reviewed in the internal repository before it is synced. The check is a confirmed DAG parse from the internal repository, with the expected DAG IDs visible in the API server and no import errors in the DAG processor output.
Wire the internal secrets backend
The security team configures the secrets backend that is reachable inside the enclave, such as an internal vault, and sets the connection and variable lookups to use it. Credentials are removed from configuration files and environment variables where they were used for testing. The check is a test task that reads a secret from the internal backend and succeeds, while a confirmed test shows the same task fails when the backend is unreachable, so no fallback to an external source exists.
Run the no-outbound-calls acceptance test
Before go-live, the platform and security teams run a clean install from the internal mirror on a fresh host, then run a sample DAG end to end and watch egress from every component. Confirm the result against your enclave's own network controls and retain the output as evidence. The check is a clean install from the internal mirror with no outbound calls, a DAG run that completes, and a recorded sign-off from the owners of the platform and the boundary.
How provider updates pass through a staging zone
Provider and patch updates arrive on a recurring cycle, and each cycle runs in the staging zone before anything crosses the boundary. In the staging zone, the team mirrors the new Airflow patch release, the matching provider packages and the container images they depend on, then regenerates the internal constraints file for each Python version in use. The regenerated constraints are then tested against the DAG code and the internal Git server, using a build that mirrors the enclave's configuration: the same metadata database engine, the same secrets backend and the same executors. Only after those tests pass and the package set has been checked for integrity and provenance does the transfer package move through the approved one-way or controlled channel into the enclave, where the internal mirrors are updated and the production upgrade is scheduled.
The Airflow support policy sets the timing of this cycle. Limited-maintenance versions receive only security and critical bug fixes, and end-of-life versions receive no fixes at all. Airflow 2 reached end of life on April 22, 2026, so any enclave still running it has no upstream patches to carry across, and the Airflow 3 upgrade path must be planned on its own schedule. Confirm the current support status of the Airflow line you run against the Airflow version life cycle page at the start of each cycle, because a release that enters limited maintenance shortens the time you have to bring a patch through staging.
Build the cycle backward from your slowest step. Ask your team and any delivery partner to confirm how long your transfer approvals take, how often your change board meets, and how many full test passes a constraints change requires, because those intervals, not Airflow's release dates, usually decide whether a security fix reaches the enclave in time. Keep a dated record of each transfer, including the package hashes, the constraints file version and the test results, so the evidence trail for the boundary crossing exists when an auditor or a control owner asks for it.
Security controls for an offline Airflow
An air-gapped Airflow is only as trustworthy as what crosses into the enclave and who can change it once inside. The five controls below work together: they decide what gets in, how it is verified, where credentials live, how data and DAGs are protected, and how every transfer and change is recorded.
Verify every package and image
Every container image, wheel, provider package and constraints file carried across the boundary should be checked against a hash or signature recorded at the source before it enters the enclave. Keep the verification output with the transfer record. NERC CIP-013-2 asks energy sector organizations to address verification of software integrity and authenticity in procurement, so this step is the control auditors will ask to see. Confirm with your security team which hash or signature method your transfer process uses and who signs off on each import.
Keep secrets in an enclave secrets backend
Connections, the Fernet key and API secrets should be served from a secrets backend that runs inside the enclave, not from a cloud service the network cannot reach. Confirm that the backend and its own dependencies are mirrored and that no DAG depends on an external lookup. Decide early whether variables live in the backend or in Kubernetes Secrets, because switching later means rotating credentials for every connection.
Protect the metadata database and backups
The metadata database holds run history, connections and variables, so it needs the same protection as the rest of the platform. Use PostgreSQL or MySQL, since the Airflow production guide warns that SQLite can lose data in production. Store backups inside the enclave, encrypt them, and test restores on a schedule. Confirm who can read backup media and how long copies are retained.
Restrict who can publish DAGs
DAG code runs with the permissions of the workers that execute it, so publishing rights are a privilege escalation path. Limit merges to the internal Git server to reviewed changes, require a separate approver for production branches, and keep the DAG source to a single repository. Confirm which team owns the approval path and how emergency changes are reviewed after the fact.
Log transfers and changes
Keep an audit trail covering who requested each transfer, what was imported, the verification result, and which DAG commits or configuration changes followed. Ship Airflow task and API logs to a store inside the enclave so they survive pod or worker loss. Confirm retention periods with your compliance team, since they set how long this evidence must remain available.
What an air-gapped Airflow install costs and needs from you
What drives the cost of an air-gapped Airflow installation?
The biggest cost drivers are the number of network zones, how many components you run, and how much of the supply chain you need to carry across the isolation boundary. Cost usually rises with the number of Airflow components (API server, scheduler, DAG processor, triggerer, workers), the number of providers you need, the database and secrets backends that must be reachable inside the enclave, and how often you expect to update. Ask any partner for a written scope that lists each component, each provider, each internal service and each transfer path, because those items set the work. Your own staff time for approvals and change windows is a cost too, even when no vendor is involved.
Which parts of an air-gapped Airflow install are one-time and which recur?
The one-time work covers designing the mirror and transfer process, building the internal registry and PyPI mirror, hosting the constraints file, connecting the internal Git server for DAGs, wiring the secrets backend, and documenting the procedure. The recurring work covers each Airflow patch and provider update, which must pass through your staging zone, plus rescanning transferred packages and images, rotating credentials and reviewing access. Airflow 2 reached end of life on April 22, 2026, so any supported version you choose will need recurring upgrades on the project's own release cycle. Ask for the split between one-time and recurring effort in the quote, with each recurring task named.
What must our team provide before an air-gapped Airflow install starts?
Your team needs to provide the network design and approved transfer path, plus the systems that will sit inside the enclave. In practice this means:
- An internal container registry and a PyPI mirror reachable from the enclave
- An internal Git server that holds DAG code, with an owner for reviews and merges
- A PostgreSQL or MySQL metadata database, since SQLite is not suitable for production and MariaDB is not supported
- A secrets backend reachable inside the enclave, plus key material for the Fernet key and API secret
- A staging zone where packages and images are checked before they cross into production
- Named approvers for each transfer, and a change process your auditors will accept
Confirm each item with your network, security and platform teams before the scope is signed.
Can our internal team install Airflow in an air-gapped network without outside help?
Yes, a capable platform team can do this alone if it has the skills and time, and the project is open source under the Apache License 2.0 so there is no license fee to pay. The hard parts are not the install commands but the supply chain: building a complete offline mirror, pinning versions with a constraints file, validating every transfer, and running provider updates without breaking DAGs. Check whether your team has experience with Airflow 3 specifics, such as the separate DAG processor and the Task SDK, and with Kubernetes or virtual machine operations. If those skills are thin, a fixed-scope engagement can reduce the ramp-up risk, and you can still own the result.
How long does an air-gapped Airflow installation take?
Duration depends on scope, not on a fixed template, so no general figure applies. The main variables are how many environments you need (development, staging and production), how many providers and images you must mirror, how quickly your change and approval processes move, and whether the database and secrets backend already exist. Upgrade paths also matter: Airflow 3 requires moving from Airflow 2.7 or later, and the upgrade guide recommends moving to the latest 2.x first, so a migration from an older release adds planning time. Ask for a timeline in the written quote that lists each approval gate and any dependency your team owns.
What changes the duration of an air-gapped Airflow project?
The largest schedule risks are approval cycles for each transfer into the enclave, late delivery of internal services such as the registry, PyPI mirror, Git server or database, and DAG code that depends on Airflow 2 features removed in Airflow 3. Other factors include the number of providers that need system libraries, the need to validate every package against your integrity controls, and how many people must review each change. Ask the partner to name these dependencies in the plan and to state which ones are outside their control.
Which compliance controls should the air-gapped design account for?
Two controls frequently apply to isolated networks. NERC CIP-013-2 addresses supply chain procurement, including verification of software integrity and authenticity of vendor software and patches, which applies to what you carry across an isolated boundary. NERC CIP-005-7 covers electronic security perimeters and remote access to high and medium impact systems. Whether either applies depends on your sector and classification, so confirm applicability with your compliance team. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports or certifications; independent auditors and certification bodies do that work.
Limits to confirm in your environment
An air-gapped Airflow install is only as good as the version set you can actually carry across the boundary. The five items below connect the version matrix, the transfer policy, the services inside the enclave and the platform underneath, so each should be confirmed before any bundle is built.
Airflow, provider and Python versions
Confirm the exact Airflow release, the provider packages you need and the Python version your enclave can carry before anything is mirrored. Each Airflow release publishes a constraints file per Python version, so the mirror has to match one combination. Ask whether your transfer policy allows a specific Python minor version and whether provider updates will move through a staging zone on their own schedule. Plan the mirror around that set, not around the latest release.
Registry and PyPI mirror tooling
Confirm that the tools you use to mirror container images and PyPI packages meet your organization's transfer and scanning policy. Many teams need an audit record for every package crossing the boundary, along with a way to verify integrity before import. Ask your security team which mirroring product is approved, who signs off on each transfer, and whether the scanned and approved bundle is the exact artifact that enters the enclave.
Secrets backend and identity reachability
Confirm that the secrets backend and identity provider Airflow will use are hosted inside the enclave and answer on the network paths you have defined. A connection that depends on an external endpoint will fail silently at runtime. Check certificate authority trust, DNS resolution and whether the identity provider supports the protocols your auth manager needs. Test each path from the scheduler, workers and API server, not only from an admin workstation.
Metadata database version support
Confirm that the PostgreSQL or MySQL version your enclave runs is on the supported list for the Airflow release you chose. MariaDB and SQLite are not supported for production metadata, so a database standard built around MariaDB needs a decision before installation. Ask who patches the database inside the enclave, how quickly that can happen, and whether the restore procedure has been tested with an offline backup.
Kubernetes version and image source
If the deployment runs on Kubernetes, confirm that the cluster version falls in the range Airflow supports and that the control plane and node images can be pulled from your private registry. Ask whether the cluster build process can run without internet access and which image repository the cluster will reference. A cluster outside the supported range should be upgraded or replaced before Airflow is installed, not after.
How DeployOpen scopes and delivers an air-gapped Airflow install
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including air-gapped networks. For Airflow, that means agreeing the mirror, constraints, DAG delivery, provider update path and secrets design in writing before any build begins, then handing over a system your team can run and reproduce.
How we scope
- Inventory the Airflow release line, Python version and database engine your enclave must support before choosing artifacts.
- Map every image, PyPI package and constraints file that must cross the boundary, and who approves each transfer.
- Agree in writing which secrets backends, Git servers and identity sources are reachable inside the enclave, and which are not.
How we build
- Set up an internal image registry and package mirror, then pin the constraints file that matches your Airflow release and Python version.
- Configure DAG delivery from an internal Git server and test that the scheduler and workers pick up changes without internet access.
- Run the install through a staging zone so provider updates are tested, checksummed and documented before they reach production.
How we hand over
- Deliver runbooks for mirror refresh, constraint regeneration, provider promotion and rollback, written for your own operators.
- Document the metadata database, logging and secrets configuration, along with the controls your evidence trail depends on.
- Provide test results and an install record showing what was transferred, from where, and when it was verified.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover, scoped in writing.
- Confirm with us which Airflow security releases and end-of-life dates apply to your version, and plan each upgrade through the staging zone.
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts and a quote following from that scope.
