I'm new to K3s and need to deploy a cluster in a genuinely air-gapped environment. I currently have five VMs running under Proxmox. My idea is to connect them to the internet initially, install K3s on the first VM with cluster initialization, and then join the remaining VMs as additional servers or agents using the cluster token. I would also add the first VM to each node's /etc/hosts file so the nodes can resolve it by name.
After deploying my workloads while the VMs still have internet access, I would change the network configuration, move all of the VMs onto the isolated network, update /etc/hosts if necessary, and restart the K3s services.
Will the cluster continue working after external connectivity is removed? Is this bootstrap-and-disconnect approach reliable, or should I follow a dedicated air-gapped installation process instead? I also want to know what images, binaries, and other dependencies need to be prepared in advance.
4 Answers
K3s has a dedicated air-gap installation procedure, and that is the safer approach. Prepare the K3s binary, installation assets, and every container image your workloads and system components will need, then transfer them into the isolated environment. If you bootstrap online and disconnect later, the existing cluster may keep running, but anything that needs an image pull, upgrade, external endpoint, certificate renewal, or other internet dependency can fail.
Your general plan can work if the cluster is fully installed and all required images are already present before you remove external access. Kubernetes itself does not require the internet for normal internal scheduling and service traffic. However, simply changing /etc/hosts is not a complete air-gap strategy: verify that every node can still reach the K3s server and that the server address, certificates, DNS behavior, time synchronization, storage, and any external services are suitable for the isolated network.
The important distinction is that you are bootstrapping while connected and then creating the isolation. That is possible, but you should test the exact disconnected setup rather than assuming a restart will expose no missing dependency.
The same general principles apply to other Kubernetes distributions: an isolated cluster is manageable, but you need an inventory of everything it depends on. Besides K3s and workload images, account for DNS, a private image registry, package repositories, monitoring or logging endpoints, certificate authorities, time sources, and any application APIs outside the cluster. If those dependencies are unavailable after the network change, the cluster may remain up while individual features stop working.
For a real air-gapped deployment, use the documented offline workflow instead of piping an online installer directly into a shell on each node. Download and transfer the required binaries and image archives using an approved method, optionally run a local registry inside the isolated network, and load or mirror the images there. This is especially useful if the cluster will be installed repeatedly or needs regular upgrades.
Make sure you pre-stage all required images before disconnecting. Otherwise new pods can get stuck in ImagePullBackOff as soon as the cluster tries to retrieve something that is not already available locally.