Why installing Apache APISIX in an air-gapped network needs a plan before the first pull
In a regulated or restricted enclave, APISIX can run fully offline if every package, image, chart and dependency is mirrored inside the enclave and every external call is redirected to a reachable internal address. Nothing in the installation has to reach the public internet, but nothing installs by default without that preparation either. The APISIX installation guide lists Docker Compose for evaluation, Helm for Kubernetes, RPM or DEB packages for supported Linux distributions and source builds, so each of those paths pulls from a different set of sources that must be copied across the boundary. The project is licensed under the Apache License 2.0, which is a useful fact for your software review, but the license says nothing about how to move artifacts through your transfer process. Confirm with the project whether it publishes an offline bundle for your chosen install path before you assume one exists.
The deployment mode you choose decides how much of the enclave build depends on etcd. APISIX supports traditional mode (data and control plane together), decoupled mode (separate data plane and control plane sharing one etcd cluster) and standalone mode (no etcd, with configuration from a YAML or JSON file or the Admin API). Traditional and decoupled modes require you to build, patch and back up an internal etcd cluster inside the enclave, which adds an image set, certificates and an operating procedure. Standalone mode removes that dependency, but it changes how configuration reaches each gateway, so the change path for routes and plugins must be designed before the first install. Decide the mode early, because it determines the artifact list you will ask your transfer process to verify.
Before the first pull, write down three things: the full artifact inventory for the chosen install path, the owner who verifies each artifact's integrity and authenticity before it crosses the boundary, and the list of external endpoints that plugins or discovery features will call. Tie the verification step to your supply chain control for vendor software, since the NERC CIP-013-2 requirement on verifying software integrity and authenticity is a useful reference if you operate under that standard. For identity, the openid-connect plugin needs the identity provider's discovery document inside the enclave, and recent releases tighten how bearer introspection behaves when that document is unavailable, so test that path explicitly. Ask your team to confirm the exact version set against the APISIX downloads page and the changelog before any transfer begins.
Which deployment mode fits an enclave with no internet access
In traditional mode, the data plane and control plane run together on the same APISIX nodes, and each node talks to an etcd cluster for its configuration. Everything the gateway needs must sit inside the enclave: the APISIX nodes, an etcd cluster, and a route for administrators to reach the Admin API. Client traffic arrives on port 9080, and the Admin API listens on port 9180, so both must be reachable only from the networks that need them.
- Hosted inside the enclave: APISIX nodes, a supported etcd release and the internal image or package repository used to install both.
- How configuration arrives: Administrators or pipelines write routes and plugins through the Admin API on port
9180, and etcd stores them for every node. - Where it fits: Teams with a small, stable set of gateways who want the familiar Admin API workflow and can operate an etcd cluster.
- Trade-off: etcd becomes one more stateful system to back up, patch and monitor inside the enclave, with no internet fallback.
- Admin API exposure: Restrict port
9180to administrator workstations and automation runners, not to application networks.
Confirm the supported etcd release with the installation guide before mirroring anything, and check that your internal repositories carry every dependency for the chosen install method.
In decoupled mode, the control plane and data plane run as separate APISIX deployments that share one etcd cluster. Administrators work against the control plane, and data plane nodes only serve traffic. This split suits enclaves that run many gateways in several zones, because the data plane nodes can be scaled or placed closer to protected services without exposing the Admin API to each of them.
- Hosted inside the enclave: Control plane nodes, data plane nodes, one shared etcd cluster and the internal mirrors for packages and images.
- How configuration arrives: The control plane writes configuration to the shared etcd cluster, and every data plane node reads from it.
- Where it fits: Multi-zone or multi-site enclaves where data plane nodes sit in different network segments from the administrative plane.
- Trade-off: The shared etcd cluster becomes a single dependency for every data plane node, so its placement and backups matter more than in traditional mode.
- Network paths: Confirm which segments need a route to etcd and to the Admin API, and keep those paths internal only.
Ask your team to document which node roles can reach etcd, since that access is the most sensitive path in this design.
Standalone mode removes etcd entirely. APISIX reads its configuration from a YAML or JSON file, or receives it through the Admin API, and each node holds that configuration in memory. For an enclave, this removes a stateful cluster from the design, but it moves the control problem into the configuration files or API traffic, which must still be mirrored, reviewed and governed.
- Hosted inside the enclave: APISIX nodes and the internal mirrors. No etcd cluster is required in file-driven standalone mode.
- How configuration arrives: APISIX checks
conf/apisix.yamlorconf/apisix.jsonfor changes every second and hot-reloads without a restart. Alternatively, the API can push configuration. - Where it fits: Small or fixed gateway estates where configuration changes rarely and a Git-based review and signing process already exists inside the enclave.
- Trade-off: Configuration files must be delivered, verified and rolled back by your own process, and the file becomes the single source of truth for each node.
- Secrets and sessions: Settings that etcd would normally hold, such as admin keys and session data, need a separate handling plan.
Confirm with the standalone documentation how each node receives and validates its file, and whether your change process can deliver a file to every node without internet access.
Mirroring packages, images and Helm charts for the enclave
This sequence produces a verified internal copy of every APISIX artifact the chosen install method needs, so a node inside the enclave can install the gateway without reaching the public internet. Each step leaves a recorded version, digest or checksum that the next step depends on.
Choose the install method and list its artifacts
The platform team picks one method for each environment, such as Helm for Kubernetes, RPM or DEB packages for virtual machines, or Docker images for container hosts, and reads the APISIX installation guide for that method. They write an inventory that lists every item the install pulls: the gateway package or image, the etcd release if the chosen mode uses etcd, the APISIX Ingress Controller if Kubernetes is in scope, the Helm chart and its sub-charts, and any base images or OS dependencies. The inventory is complete when each line names its source, its exact version and the host that will consume it.
Pull artifacts on a connected staging host
Someone with access to the public sources runs the download on a staging host that is kept separate from the enclave. For Helm, they add the chart repository and fetch the chart archive at a pinned version. For Docker, they pull each image by tag and record the digest. For RPM or DEB, they download the packages for each supported distribution release used in the enclave, including dependencies that the package manager would otherwise fetch. The step is done when every inventory line has a local file or image and nothing is left to resolve at install time.
Verify checksums and digests before the transfer
Before anything crosses the boundary, the staging host compares each downloaded file against the checksum or signature published by its source, and records the image digest in the inventory. Signed RPM and DEB packages are checked against the signing keys that the security team has approved, and those keys are copied into the enclave with the packages. This check supports the software integrity and authenticity control in NERC CIP-013-2, which applies to utilities, and is a useful pattern for other regulated sectors. The step is complete when each artifact has a recorded hash and a signature result, and any mismatch stops the transfer.
Import into internal repositories and registries
The platform team loads the verified artifacts into the enclave's own services: a private container registry for images, an internal Helm chart repository or an OCI registry for the chart, and an internal package mirror for RPM or DEB. Image references in the chart values are rewritten to point at the internal registry, and the package repository definition on each node points only at the internal mirror. The result is an internal copy whose contents match the staging inventory, which the team confirms by listing each repository and comparing digests against the record.
Record the bill of materials for the release
The team writes a release record that lists each artifact with its name, version, source URL, checksum or digest, signing key identifier, transfer date and the person who approved the import. The record also notes the APISIX version and the etcd version that are paired in the enclave. Operations staff use it to answer audit questions and to plan later upgrades, because the same record drives the next offline update. The step is complete when the record is stored in the team's change system and matches the internal repositories.
Prove a clean node installs from internal sources only
The team provisions a node with no route to the public internet, configures it to use only the internal package mirror, and runs the install with the internal chart or image references. Network egress is blocked at the firewall during the test, so a missing artifact fails the install instead of quietly reaching outside. The test passes when the gateway starts, the admin and client listeners respond on the configured ports, and the node logs and package manager output show no requests to external hosts. The team keeps the logs with the release record as evidence.
Confirm the image and chart are used by the cluster
For Kubernetes deployments, the team checks that every pod in the APISIX namespace pulls images from the internal registry, using the pod specs and the image digests in the release record. They confirm that the Helm release values reference internal sources only, and that no init containers or sidecars default to public registries. Any remaining external reference is listed as a defect and fixed before sign-off. The step is complete when a scan of the running workloads shows only internal image sources and the list of exceptions is empty.
Running an internal etcd and keeping configuration inside the enclave
Every etcd-backed mode needs an etcd cluster that lives inside the enclave, so the first decision is where that cluster runs and who operates it. The APISIX installation guide asks for a supported etcd release in those modes, which means you must confirm the exact etcd version against the APISIX release you are installing before any images or packages cross the boundary. Treat etcd as a stateful system of record for routes, consumers and plugin settings: it needs its own backups, TLS between members and clients, and sizing based on your route count and write rate. Ask whoever runs the cluster to demonstrate a restore into a scratch environment inside the enclave before go-live, because a gateway that cannot recover its configuration is a single point of failure. The detailed cluster design, mTLS setup and upgrade sequence belong to the dedicated etcd operations topic, so this section only fixes the boundary decisions.
The Admin API key is the credential that can change every route and plugin on the gateway, so it must never ship as the default value in the sample configuration. Set it through the process environment or a secrets store your enclave already runs, and confirm that the value is absent from images, Helm values committed to Git and the mirrored repositories. Restrict network access to the Admin API port (9180 in traditional mode) to the administrators and automation that need it, and keep the Control API port private. Make the same rule apply to any dashboard or configuration tool you carry in, since each one needs its own credential and audit trail.
In standalone mode there is no etcd, so the YAML or JSON configuration file becomes the authoritative source, and APISIX reloads it when the file changes. That makes the file itself the change-control point. Deliver it through the same controlled path as packages and images: signed or checksummed, reviewed, stored in an internal Git repository and promoted by a pipeline that runs inside the enclave. Confirm who can write to the file location on each gateway host, and alert on unexpected modifications, because a one-second reload check means a bad edit takes effect almost immediately. Whichever mode you choose, document the single path by which configuration enters the enclave so auditors can trace every production change back to an approved source.
How OpenID Connect discovery works without internet access
Can the APISIX openid-connect plugin work if the identity provider is inside the enclave?
Yes, provided the identity provider, its discovery document, its JWKS endpoint and its token endpoint are all reachable from the APISIX nodes on internal addresses. The openid-connect plugin works with providers such as Keycloak and Microsoft Entra ID, and nothing in its normal flow needs a public address. The work is in making every URL the plugin fetches resolve inside the enclave, using internal DNS or host entries, and confirming that the metadata the provider publishes points to internal hostnames. Confirm the exact endpoints each flow calls in the openid-connect plugin documentation before you test the design.
Why do discovery, JWKS and token endpoints need internal addresses?
The plugin reads the discovery document to learn where to fetch signing keys and where to send token requests. If the provider publishes public hostnames in that document, APISIX will try to reach addresses that cannot be resolved or routed from an isolated network. Common failures are a discovery URL that resolves but an issuer or JWKS URL that points outside the enclave, and split-horizon DNS that returns different answers on different networks. Plan the provider's externally visible host names, the internal names used by APISIX, and the issuer value they must share before you cut over.
Does APISIX need internal CA certificates for OpenID Connect?
Usually yes. When the identity provider uses TLS signed by an internal certificate authority, APISIX must trust that CA for every outbound call the plugin makes: discovery, JWKS retrieval, token exchange and introspection. Add the root and any intermediate certificates to the trust store used by the APISIX nodes, and test each endpoint with the same trust chain. Do not disable certificate verification to get past a failure, because that removes the protection the token flow depends on. Your security team should own the CA distribution and rotation process, and the plan should say how a renewed certificate reaches every gateway node.
What happens in APISIX 3.18.0 if the discovery document is unavailable?
APISIX 3.18.0 makes openid-connect bearer introspection fail closed when the discovery document cannot be retrieved. Requests that depend on that path are rejected rather than accepted without verification. The same release also enforces audience, issuer and required scope checks during introspection. For an air-gapped site this matters because a lost connection to the identity provider stops authentication instead of allowing traffic through, so availability of the identity provider and its discovery endpoint becomes part of the gateway's availability design. Confirm the behavior of your chosen version against the APISIX changelog.
What does the iss check in APISIX 3.19.0 change for an enclave?
APISIX 3.19.0 rejects introspection responses whose iss value does not match the configured valid_issuers. This protects against a token or response that names an issuer the gateway was not configured to trust. In an enclave the issuer string is often an internal hostname, so the value in valid_issuers must match exactly what the provider places in tokens, including scheme, host, port and any path. A mismatch after a hostname or certificate change will reject valid traffic, so record the issuer value during build and include it in every upgrade test.
Why plan an offline discovery cache or pinned metadata?
A discovery document and its keys are fetched from the provider, so a gateway that starts or recovers while the identity provider is down may have nothing to validate tokens against. Planning a known-good copy of the metadata, whether a cache maintained by the platform or pinned values reviewed as part of change control, removes that dependency for planned restarts. Pinned values also reduce the chance that a changed key or endpoint is accepted without review. The trade-off is that a pinned key must be rotated deliberately, so the process for updating it is part of the design. Test a gateway restart with the identity provider stopped, and test a key rotation, before go-live.
What should be tested before an air-gapped OIDC setup goes live?
Test the full path from a clean gateway node with no outbound access, not from a machine that already has cached data. The checks are:
- Resolve every discovery, JWKS, token and introspection host from the APISIX network namespace.
- Confirm the trust chain for each endpoint.
- Verify that the issuer string matches
valid_issuers. - Stop the identity provider and confirm the fail-closed behavior.
- Rotate a signing key and confirm the gateway picks up or rejects it as your process intends.
Record the results with the APISIX and identity provider versions so the same tests can run again after each upgrade. Your own environment decides the exact commands and hosts.
Plugins that call external services and how to redirect them
Several APISIX plugins make outbound calls at request time, to an identity provider, a directory, an authorization service or a log collector. In an enclave each of those calls must resolve to a host you run, or the plugin fails in ways that can look like an upstream outage.
Identity and token introspection
The openid-connect plugin fetches the discovery document from the identity provider and, for bearer tokens, calls the introspection endpoint. Inside the enclave, the identity provider (for example Keycloak or another self-hosted OIDC server) must be reachable at its internal address, and its discovery document must advertise endpoints that resolve inside the enclave, not public hostnames. Confirm the discovery URL, the issuer value and the valid_issuers list for your chosen APISIX version. In 3.18.0 and later, bearer introspection fails closed when discovery is unavailable, so an unreachable identity service blocks API traffic.
LDAP directory binds
The ldap-auth plugin validates credentials by binding to a directory server on each authenticated request. Your enclave must host an LDAP or Active Directory endpoint that the gateway can reach on the configured port, with TLS settings matching your certificate authority. Confirm the ldap_uri, the bind DN pattern and whether your directory accepts the TLS mode you configure. Plan the directory's own availability, since every login depends on it, and remember that failed binds may be counted by the directory's lockout policy.
Forward-auth authorization services
The forward-auth plugin sends each request's headers to an external authorization service and allows or denies the request based on its answer. That service is usually a policy engine or an in-house token service, so it must run inside the enclave with its own high availability plan. Confirm the uri, which request headers are forwarded, and which upstream headers the service may return to the client. Treat the response headers as trusted input only from this service, because the gateway passes them on.
External logging and observability sinks
Logging plugins such as http-logger, tcp-logger, kafka-logger and the observability exporters push data to collectors that the gateway does not run itself. In the enclave, point each sink at a collector you host, such as Graylog, OpenSearch, Kafka or an OpenTelemetry Collector, and confirm that the plugin's batch and retry settings suit that collector's capacity. Test what happens when the sink is down, because a blocked log queue can grow in gateway memory. Confirm exact plugin names and options in your version before writing the configuration.
AI and third-party service plugins
Plugins that call AI providers, content moderation APIs or other third-party services cannot work in an enclave unless the target is a model or service you host. Map each such plugin to an internal endpoint, such as a self-hosted model server with an OpenAI-compatible API, and document which requests leave the boundary. Confirm whether the plugin validates certificates for private authorities and whether it accepts a custom base URL in your version. Remove any plugin whose vendor cannot be reached, rather than leaving it configured and failing silently.
Egress inventory before go-live
Once the plugins are configured, list every outbound hostname the gateway resolves and every port it opens. Compare that list against the enclave's firewall rules and DNS zone, and run each route's auth path with the external network disabled. This review is what catches a plugin that still reaches a public endpoint through a default setting. Keep the inventory with the change record so auditors can see that the gateway's outbound paths were approved.
Installation methods and what each needs from the enclave
This table compares the four installation methods the APISIX installation guide lists: Docker Compose, Helm on Kubernetes, RPM or DEB packages and source builds. For each one it shows what must be mirrored from outside the enclave, what runs inside it and whether the method suits production. The main takeaway is that Docker Compose is for evaluation only, so a production enclave should plan around Helm or Linux packages.
| Method | Artifacts to mirror | What runs inside the enclave | Fit for production |
|---|---|---|---|
| Docker Compose | APISIX image, etcd image and any Compose or dashboard images used, pinned by digest | Containers on a single host with a local etcd container | Evaluation only, per the installation guide |
| Helm on Kubernetes | APISIX chart, APISIX and Ingress Controller images, etcd chart and image, and cluster base images | Private registry, internal Helm repository and an etcd deployment in the cluster | Supported path for production on Kubernetes; confirm chart versions with the vendor |
| RPM or DEB packages | APISIX and etcd packages for each supported distribution, plus OS dependency packages and their repositories | Package repository mirror, etcd service and the APISIX service under systemd | Linux is the supported production platform; confirm the distribution matrix before mirroring |
| Source builds | Source archive, verified signatures, and all build toolchain and Lua or OpenResty dependencies | Build host with compilers, a local dependency cache and an internal artifact store | Possible but adds build and patch ownership; confirm support expectations before choosing it |
Setup sequence for an offline APISIX install
This sequence moves APISIX from a connected staging zone into an enclave with no outbound route, leaving a gateway that starts from internal sources, serves traffic on its client and Admin ports, and fails safely when an external call is attempted. Each step ends with a check you can record as evidence.
Stage every artifact in the connected zone
In the connected zone, your team collects the APISIX release you intend to run, the matching APISIX Ingress Controller release if you use Kubernetes, the etcd release APISIX requires for etcd-backed modes, and the container images and Helm chart for each. Follow the installation guide for the package types you plan to use (Docker, Helm, RPM or DEB, or source builds), and record the exact versions, digests and checksums in a manifest. Verify each checksum against the publisher's values before the transfer. Done means the manifest lists every artifact with its version and hash, and the verification output is saved with the change record.
Transfer and import artifacts into the enclave
Move the staged files across the boundary using your approved media or transfer process, then import them into internal repositories: a private container registry, an internal Helm repository, an internal Linux package mirror and a file share for source archives. The platform or security team performs the import and re-checks every hash inside the enclave. Done means each internal location serves the artifacts, and a second hash comparison against the manifest matches on every item.
Choose and deploy the configuration store
Decide between an internal etcd cluster (traditional or decoupled mode) and file-driven standalone mode, based on how you want changes controlled and who may write routes. For etcd, deploy the supported release inside the enclave with its own storage, access controls and backups. For standalone, prepare the configuration file in your Git repository and plan how it reaches the nodes. Done means the store starts, accepts a test write or loads a test file, and you have recorded which mode the enclave uses.
Install APISIX from internal sources only
On each node or cluster, install APISIX from the internal package mirror, container registry or Helm repository, and point image pulls and package sources at those internal endpoints only. Confirm the package manager and container runtime do not fall back to public repositories. Done means the installed version matches the manifest on every node and the service starts with its configuration pointing at the internal etcd or standalone file.
Set the Admin API key from the environment
Generate the Admin API key inside the enclave and supply it through the process environment or the orchestrator's secret store, not in a configuration file checked into Git. Restrict access to the key and to the Admin API port to the operators who manage routes. Done means the Admin API rejects requests without the key, accepts requests with it, and the key does not appear in any rendered configuration, log or repository file you reviewed.
Configure internal OIDC discovery and certificates
Where the openid-connect plugin protects routes, point its discovery and token endpoints at your internal identity provider, and issue the certificates those endpoints use from your internal certificate authority. Trust the internal CA on the gateway nodes and in any client that calls the discovery document. Set valid issuers and audiences explicitly. Confirm the behavior of the release you run: the changelog records that 3.18.0 fails closed when the discovery document is unavailable and that 3.19.0 checks introspection issuers against configured valid_issuers. Done means a token from the internal provider is accepted, and a token with a wrong issuer or audience is rejected.
Run port checks on 9080 and 9180
Confirm the gateway answers client traffic on port 9080 and the Admin API on port 9180, which are the defaults in traditional mode, and confirm any ports you changed in your own configuration. Create a test route that returns a local response, then call it from an allowed client. Check the Admin API with and without the key. Done means both ports respond as designed, the test route works, and the results are saved as evidence.
Prove failed calls and no public reachability
From every node, run a DNS lookup for a public name and attempt connections to a public endpoint. Both must fail, and the failures must be logged. Then send a request through a route whose upstream or plugin calls an external service, and confirm it fails with a clear error rather than hanging or leaving the enclave. Done means no node resolves public DNS or reaches public endpoints, the failed-call test returns the expected error, and your network team signs off the captured output.
Security controls for an enclave gateway
An air-gapped APISIX gateway inherits the trust of everything that enters the enclave, so the controls below cover what crosses the boundary, who can change the gateway, and how it is reached. Each card names one control and what to confirm in your own environment before the install starts.
Verify every transferred package
Every image, package, Helm chart and plugin source carried across the boundary needs a recorded checksum or signature check before it is loaded. NERC CIP-013-2 expects procurement processes to address verification of software integrity and authenticity, so the transfer log should show who verified each artifact and when. Confirm with your supplier how signatures and checksums for the APISIX release artifacts are published, then check them on the inside of the enclave, not only on the transfer host.
Keep the Admin API internal
The Admin API listens on port 9180 in traditional mode, and anyone who reaches it with a valid key can change routes, plugins and upstreams. Bind it to the management network only, keep the client listener on port 9080 separate, and make sure the Control API on port 9092 is not reachable from user segments. Also confirm that etcd client ports accept connections only from APISIX nodes and the etcd peers.
Route remote access through an intermediate system
Where the sector requires it, vendor and staff access into the enclave should pass through an intermediate system that enforces encryption and multi-factor authentication. NERC CIP-005-7 also expects methods to detect and disable active vendor remote access sessions. Plan who may open a session to the gateway host, how sessions are logged, and how a vendor session is terminated during an incident. Confirm the exact obligations with your compliance lead, since applicability depends on your impact classification.
Store secrets outside configuration files
The Admin key, etcd credentials, TLS private keys and OIDC client secrets should not sit in plain YAML committed next to the gateway configuration. Pass the admin key through the process environment or a secrets store that exists inside the enclave, and restrict file permissions on the APISIX configuration directory. Rotation needs a runbook, because a rotated key that is not updated in every node causes an outage during a change window.
Export logs within the enclave
Access logs and error logs from the gateway are useful evidence only if they reach a collector you operate inside the enclave. Choose a log destination that the enclave can reach without an outbound route, and define retention in your own policy rather than relying on the gateway defaults. Test that log shipping keeps working after a network change, since a silent failure removes the record you would need during an investigation.
Change control for plugin sources
Custom plugins written in Lua, or run through plugin runners in Java, Go or Python, change gateway behavior as much as a route change does. Each plugin source should be versioned, reviewed, built inside the enclave from approved source, and recorded with the APISIX version it was tested against. Ask the vendor or your integrator which APISIX release notes affect the plugin interfaces you use before each offline upgrade.
Upgrading APISIX and its dependencies offline
Every offline upgrade starts with the CHANGELOG, not the mirror. For each target version, read the entries between your current release and the new one in the apache/apisix CHANGELOG, then mirror the release and its matching chart or image into the enclave. Two recent entries need a specific check before anything else. APISIX 3.18.0 made openid-connect bearer introspection fail closed when the discovery document is unavailable, and it enforces audience, issuer and required scopes. APISIX 3.19.0 rejects introspection responses whose iss does not match the configured valid_issuers. Because your enclave resolves discovery from an internal identity provider, confirm that the discovery URL, the published issuer string and the valid_issuers list still agree before you roll anything out. A mismatch that was tolerated before can now block every bearer token.
Next, run the full sequence in a staging enclave built from the same mirrored artifacts. Confirm that the new images or packages install from your internal registry or repository, that the chart renders with your values, and that routes, consumers and openid-connect plugins behave as they did before. Then take an etcd snapshot of the production cluster and store it outside the gateway nodes, because etcd is the state that every gateway reads. Roll gateway nodes one at a time, and wait for each node to pass its health checks before you touch the next. Keep the previous image, package set, chart version, etcd snapshot and configuration export until the new release has run long enough in production for you to accept it. Those artifacts are your rollback path, and they only work if they were mirrored and tested in the same offline way as the upgrade itself.
Plan the dependencies alongside APISIX. The etcd release, the Kubernetes version and the base operating system packages each carry their own compatibility notes, so confirm the supported etcd release for the target APISIX version in the installation guide and mirror any new dependency before the window opens. Record the checksum of every artifact you carry across the boundary and keep the approval record with the change ticket, which supports the integrity and provenance evidence that supply chain controls ask for. Confirm the exact release lines and support status with the APISIX downloads page and your own vendor agreement, since this page does not set a release cadence or support window.
Limits to confirm in your environment
An air-gapped APISIX install depends on several assumptions that the public docs do not settle for your exact versions. Each card below names one assumption, why it breaks an isolated install, and the check to run in a test enclave before the production build starts.
Plugin startup fetches
Some plugins may load resources, schemas or dependencies when APISIX starts, or call a URL the first time a route is hit. Read the plugin's documentation for the version you run and list every outbound host it touches. In a test enclave, block all egress and start the gateway with each plugin enabled. Any failure or timeout points to a resource you must mirror or configure internally before go-live.
Helm chart subcomponent sources
A chart version can reference images or dependent charts from public registries, and those references can change between chart releases. Render the chart offline with your chosen values and inspect every image reference and subchart. Mirror each one into your internal registry and override the repository values so no pull reaches a public host. Record the chart version so the same mirror set serves future upgrades.
Supported etcd release
The installation guide asks for a supported etcd release in etcd-backed modes, so the etcd version must match the APISIX release you deploy, not the latest one. Confirm the pairing in the installation guide and the release notes for your APISIX version. Mirror the etcd binary or image, and plan an internal etcd cluster with its own certificates and backup path, since no external etcd service is available inside the enclave.
Internal DNS and certificate authorities
The gateway, the identity provider and the etcd peers must resolve each other by name and trust the same certificate chain. Confirm that your internal DNS covers the Admin API, the identity provider, and any discovery host used by the openid-connect plugin. Confirm that your internal certificate authority issues certificates the plugins accept, and that the trust store on every node contains the root. A mismatch here usually appears as a failed discovery call, not a clear error.
Plugin runner dependencies
Java, Go and Python plugin runners may need language runtimes, SDKs or package dependencies that are not in the base image or the packages you mirrored. Build the runner image in a connected staging zone, then import it into the enclave and confirm it starts with no network access. Check that any Python or Go modules are vendored or sourced from an internal artifact repository, and record the exact versions so the build is reproducible.
Vendor install path changes
A commercial distribution built on APISIX, such as API7 Enterprise, may use its own installer, package sources, license check or update channel that differs from the open-source install path. Ask the vendor whether the license validation calls out to a service, what the offline bundle contains, and how updates reach an isolated network. Do not assume the open-source procedure applies to the commercial build until the vendor confirms it in writing.
Questions teams ask before an air-gapped APISIX install
How much more effort does an air-gapped APISIX install add compared with a connected one?
An offline install adds work in three places: building a complete set of artifacts outside the enclave, moving them across the boundary with checks, and proving the stack works with no outbound access. The gateway itself is the same. The extra effort comes from the supporting chain: the APISIX packages or container images, the Helm chart, the etcd release, any plugin dependencies, and the Kubernetes or host images they need. Each of these must be mirrored, verified and recorded, and anything missed shows up only when a pod or service tries to reach the internet during deployment. Ask any partner to show how they inventory every artifact and where the inventory is stored, because that list determines how much rework the first attempt will cause.
What drives the cost of an air-gapped APISIX install up or down?
The main drivers are the number of environments, the plugin set, the identity integration and whether a staging enclave exists. Each environment needs its own mirror content, configuration and verification, so a production enclave plus a staging enclave roughly doubles the repeated steps. A larger plugin set adds more external dependencies to mirror and test. Identity integration matters because OpenID Connect discovery must work inside the enclave, which usually means an internal identity provider and internal copies of its metadata and keys. A staging enclave that matches production lowers risk during upgrades but adds fixed setup cost. Ask for a quote that lists each environment, each plugin with an external call, and each identity dependency as separate line items.
Can our team run an air-gapped APISIX install by itself?
A team with Kubernetes or Linux operations experience and a working understanding of APISIX can usually handle the install, but the offline parts are where in-house teams most often lose time. These include building the mirror in a connected zone, setting up an internal registry and package repository, and validating the chart and images against the approved release. Skills needed include container registry administration, certificate management, identity protocol configuration and change control with the security team. Teams that already run their own internal mirrors for Kubernetes and Linux will find the gap smaller. Assess your team against that list honestly, and if a gap exists, name who will cover it before the schedule is set.
What does the work need from our organization before it starts?
Plan for four inputs from your side:
- Network access: a connected build zone to pull artifacts, plus a documented path for moving them across the boundary.
- Artifact approvals: named owners who approve each package, image and chart before it enters the enclave.
- CA material: the internal certificate authority, certificates for the gateway, the Admin API and etcd, and the trust bundle for internal identity endpoints.
- A test enclave: a place to rehearse the install and an upgrade before production change.
Supply-chain controls such as NERC CIP-013-2 require verification of software integrity and authenticity, so the approval step is not optional in regulated sectors. Confirm early which of these inputs your organization already has and which will take time to arrange.
How long will an air-gapped APISIX install take?
The duration depends mostly on your change process, not on APISIX itself. The steps that set the pace are artifact approval cycles, change board schedules, access requests for the enclave, and the number of rehearsals your security team requires before production. A team with a fast approval path will move much sooner than one that needs multiple sign-offs for each artifact. Ask any partner to base the schedule on your documented change process and to list which approvals sit on the critical path. This page does not state a duration, because no researched figure applies to your environment.
Can we upgrade APISIX in an air-gapped environment without internet access?
Yes, an offline upgrade follows the same pattern as the first install: build and verify the new artifacts in a connected zone, carry them across the boundary, rehearse in the test enclave, then apply the change. The new APISIX release, Ingress Controller version and chart each need their own review, and the release notes must be read for behavior changes. Recent APISIX releases changed authentication behavior: 3.18.0 made openid-connect bearer introspection fail closed when the discovery document is unavailable, and 3.19.0 rejects introspection responses whose issuer does not match configured valid issuers. Those changes can break a working offline identity setup, so test them in the staging enclave before production. Confirm the target release and its upgrade notes with the APISIX project before planning.
Do plugins that call external services work inside an enclave?
They work only when the services they call are reachable from inside the enclave. Plugins that fetch external metadata, check remote policy, or send logs to a cloud service need an internal replacement or a mirrored copy of the data they depend on. The openid-connect plugin is the most common case: it needs the identity provider's discovery document, keys and token endpoints reachable inside the enclave. Inventory every plugin in your route configuration, mark those with outbound calls, and decide for each whether the target is internal, mirrored or removed. Confirm the exact endpoints each plugin reads with the APISIX plugin documentation for your release.
How DeployOpen scopes an air-gapped APISIX installation
DeployOpen starts an air-gapped APISIX engagement with a written scope that fixes four things before any artifact crosses the boundary: the deployment mode, the artifact list, the identity integration and the upgrade procedure. The deployment mode decides whether the enclave needs an internal etcd cluster (traditional or decoupled) or can run file-driven standalone mode with conf/apisix.yaml. The artifact list names every image, package, Helm chart, plugin dependency and etcd release to be mirrored, with the versions confirmed against the APISIX installation guide at the time of the work. The identity section records which OpenID Connect discovery source the openid-connect plugin will use inside the enclave, and the upgrade section records how a new APISIX release is verified, transferred and rolled out without internet access.
DeployOpen implements the agreed scope inside your own infrastructure, whether that is your cloud accounts, data centers or isolated networks. Most engagements are fixed-scope, so the written scope also lists the deliverables, such as the mirrored artifact repository, the internal etcd or standalone configuration, the tested discovery and token paths, the runbooks and the offline upgrade procedure, and the timeline agreed before work starts. Ask any provider to show how each deliverable is verified in your environment, and confirm who holds the admin key, certificates and backups at handover.
After handover, many organizations keep a retainer for upgrades, security testing and re-validation of the offline bundle, since each APISIX release and each plugin change repeats part of the transfer and testing work. DeployOpen prepares systems, configuration, documentation and evidence that your team and assessors can use for compliance work, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies make those determinations, so agree early which evidence they will ask for and who keeps it current.
