Continental Innovates with Rancher and Kubernetes
You can install K3s in an air-gapped environment using two different methods. You can either deploy a private registry and mirror docker.io or you can manually deploy images such as for small clusters.
This document assumes you have already created your nodes in your air-gap environment and have a Docker private registry on your bastion host.
If you have not yet set up a private Docker registry, refer to the official documentation here.
Follow the Private Registry Configuration guide to create and configure the registry.yaml file.
Once you have completed this, you may now go to the Install K3s section below.
We are assuming you have created your nodes in your air-gap environment. This method requires you to manually deploy the necessary images to each node and is appropriate for edge deployments where running a private registry is not practical.
Obtain the images tar file for your architecture from the releases page for the version of K3s you will be running.
Place the tar file in the images directory, for example:
images
sudo mkdir -p /var/lib/rancher/k3s/agent/images/ sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/
Place the k3s binary at /usr/local/bin/k3s and ensure it is executable.
/usr/local/bin/k3s
Follow the steps in the next section to install K3s.
Only after you have completed either the Private Registry Method or the Manually Deploy Images Method above should you install K3s.
Obtain the K3s binary from the releases page, matching the same version used to get the airgap images. Obtain the K3s install script at https://get.k3s.io
Place the binary in /usr/local/bin on each node and ensure it is executable. Place the install script anywhere on each node, and name it install.sh.
/usr/local/bin
install.sh
You can install K3s on one or more servers as described below.
To install K3s on a single server simply do the following on the server node.
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh
Then, to optionally add additional agents do the following on each agent node. Take care to ensure you replace myserver with the IP or valid DNS of the server and replace mynodetoken with the node token from the server typically at /var/lib/rancher/k3s/server/node-token
myserver
mynodetoken
/var/lib/rancher/k3s/server/node-token
INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken ./install.sh
Reference the High Availability with an External DB or High Availability with Embedded DB guides. You will be tweaking install commands so you specify INSTALL_K3S_SKIP_DOWNLOAD=true and run your install script locally instead of via curl. You will also utilize INSTALL_K3S_EXEC='args' to supply any arguments to k3s.
INSTALL_K3S_SKIP_DOWNLOAD=true
INSTALL_K3S_EXEC='args'
For example, step two of the High Availability with an External DB guide mentions the following:
curl -sfL https://get.k3s.io | sh -s - server \ --datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name"
Instead, you would modify such examples like below:
INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_EXEC='server --datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name"' ./install.sh
Note: K3s additionally provides a --resolv-conf flag for kubelets, which may help with configuring DNS in air-gap networks.
--resolv-conf
Upgrading an air-gap environment can be accomplished in the following manner:
/var/lib/rancher/k3s/agent/images/
As of v1.17.4+k3s1 K3s supports automated upgrades. To enable this in air-gapped environments, you must ensure the required images are available in your private registry.
You will need the version of rancher/k3s-upgrade that corresponds to the version of K3s you intend to upgrade to. Note, the image tag replaces the + in the K3s release with a - because Docker images do not support +.
+
-
You will also need the versions of system-upgrade-controller and kubectl that are specified in the system-upgrade-controller manifest YAML that you will deploy. Check for the latest release of the system-upgrade-controller here and download the system-upgrade-controller.yaml to determine the versions you need to push to your private registry. For example, in release v0.4.0 of the system-upgrade-controller, these images are specified in the manifest YAML:
rancher/system-upgrade-controller:v0.4.0 rancher/kubectl:v0.17.0
Once you have added the necessary rancher/k3s-upgrade, rancher/system-upgrade-controller, and rancher/kubectl images to your private registry, follow the automated upgrades guide.