diff --git a/content/k3s/latest/en/installation/airgap/_index.md b/content/k3s/latest/en/installation/airgap/_index.md index dbfe7a38898..7f9f4a8ec21 100644 --- a/content/k3s/latest/en/installation/airgap/_index.md +++ b/content/k3s/latest/en/installation/airgap/_index.md @@ -3,77 +3,115 @@ title: "Air-Gap Install" weight: 60 --- -In this guide, we are assuming you have created your nodes in your air-gap environment and have a secure Docker private registry on your bastion server. +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. -# Installation Outline +# Private Registry Method -1. [Prepare Images Directory](#prepare-images-directory) -2. [Create Registry YAML](#create-registry-YAML) -3. [Install K3s](#install-k3s) +This document assumes you have already created your nodes in your air-gap environment and have a secure Docker private registry on your bastion host. +If you have not yet set up a private Docker registry, refer to the official documentation [here](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry). -### Prepare Images Directory +### Create the Registry YAML + +Follow the [Private Registry Configuration]({{< baseurl >}}/k3s/latest/en/installation/private-registry) guide to create and configure the registry.yaml file. + +Once you have completed this, you may now go to the [Install K3s](#install-k3s) section below. + + +# Manually Deploy Images Method + +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. + +### Prepare the Images Directory and K3s Binary Obtain the images tar file for your architecture from the [releases](https://github.com/rancher/k3s/releases) page for the version of K3s you will be running. -Place the tar file in the `images` directory before starting K3s on each node, for example: +Place the tar file in the `images` directory, for example: ```sh sudo mkdir -p /var/lib/rancher/k3s/agent/images/ sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/ ``` -### Create Registry YAML -Create the registries.yaml file at `/etc/rancher/k3s/registries.yaml`. This will tell K3s the necessary details to connect to your private registry. -The registries.yaml file should look like this before plugging in the necessary information: +Place the k3s binary at /usr/local/bin/k3s and ensure it is executable. -``` ---- -mirrors: - "mycustomreg.com:5000": - endpoint: - - "https://mycustomreg.com:5000" -configs: - "mycustomreg:5000": - auth: - username: xxxxxx # this is the registry username - password: xxxxxx # this is the registry password - tls: - cert_file: - key_file: - ca_file: -``` +Follow the steps in the next section to install K3s. -Note, at this time only secure registries are supported with K3s (SSL with custom CA) +# Install K3s -### Install K3s +Only after you have completed either the [Private Registry Method](#private-registry-method) or the [Manually Deploy Images Method](#manually-deploy-images-method) above should you install K3s. -Obtain the K3s binary from the [releases](https://github.com/rancher/k3s/releases) page, matching the same version used to get the airgap images tar. -Also obtain the K3s install script at https://get.k3s.io +Obtain the K3s binary from the [releases](https://github.com/rancher/k3s/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. -Place the install script anywhere on each node, name it `install.sh`. +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`. -Install K3s on each server: + +### Install Options +You can install K3s on one or more servers as described below. + +{{% tabs %}} +{{% tab "Single Server Configuration" %}} + +To install K3s on a single server simply do the following on the server node. ``` INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh ``` -Install K3s on each agent: +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` ``` INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken ./install.sh ``` -Note, 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. -The node-token is on the server at `/var/lib/rancher/k3s/server/node-token` +{{% /tab %}} +{{% tab "High Availability Configuration" %}} +Reference the [High Availability with an External DB]({{< baseurl >}}/k3s/latest/en/installation/ha) or [High Availability with Embedded DB (Experimental)]({{< baseurl >}}/k3s/latest/en/installation/ha-embedded) 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. + +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 +``` + +{{% /tab %}} +{{% /tabs %}} >**Note:** K3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gap networks. # Upgrading +### Install Script Method + Upgrading an air-gap environment can be accomplished in the following manner: -1. Download the new air-gap images (tar file) from the [releases](https://github.com/rancher/k3s/releases) page for the version of K3s you will be upgrading to. Place the tar in the `/var/lib/rancher/k3s/agent/images/` directory on each node. Delete the old tar file. -2. Copy and replace the old K3s binary in `/usr/local/bin` on each node. Copy over the install script at https://get.k3s.io (as it is possible it has changed since the last release). Run the script again just as you had done in the past with the same environment variables. +1. Download the new air-gap images (tar file) from the [releases](https://github.com/rancher/k3s/releases) page for the version of K3s you will be upgrading to. Place the tar in the `/var/lib/rancher/k3s/agent/images/` directory on each +node. Delete the old tar file. +2. Copy and replace the old K3s binary in `/usr/local/bin` on each node. Copy over the install script at https://get.k3s.io (as it is possible it has changed since the last release). Run the script again just as you had done in the past +with the same environment variables. 3. Restart the K3s service (if not restarted automatically by installer). + + +### Automated Upgrades Method + +As of v1.17.4+k3s1 K3s supports [automated upgrades]({{< baseurl >}}/k3s/latest/en/upgrades/automated/). 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](https://github.com/rancher/system-upgrade-controller/releases/latest) 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]({{< baseurl >}}/k3s/latest/en/upgrades/automated/) guide. diff --git a/content/k3s/latest/en/installation/private-registry/_index.md b/content/k3s/latest/en/installation/private-registry/_index.md index 6160866e13a..ac068a6f423 100644 --- a/content/k3s/latest/en/installation/private-registry/_index.md +++ b/content/k3s/latest/en/installation/private-registry/_index.md @@ -25,7 +25,7 @@ Mirrors is a directive that defines the names and endpoints of the private regis ``` mirrors: - "mycustomreg.com:5000": + docker.io: endpoint: - "https://mycustomreg.com:5000" ``` @@ -59,7 +59,7 @@ Below are examples showing how you may configure `/etc/rancher/k3s/registries.ya ``` mirrors: - "mycustomreg.com:5000": + docker.io: endpoint: - "https://mycustomreg.com:5000" configs: @@ -78,7 +78,7 @@ configs: ``` mirrors: - "mycustomreg.com:5000": + docker.io: endpoint: - "https://mycustomreg.com:5000" configs: @@ -101,7 +101,7 @@ Below are examples showing how you may configure `/etc/rancher/k3s/registries.ya ``` mirrors: - "mycustomreg.com:5000": + docker.io: endpoint: - "http://mycustomreg.com:5000" configs: @@ -116,7 +116,7 @@ configs: ``` mirrors: - "mycustomreg.com:5000": + docker.io: endpoint: - "http://mycustomreg.com:5000" ``` @@ -127,3 +127,18 @@ mirrors: > In case of no TLS communication, you need to specify `http://` for the endpoints, otherwise it will default to https. In order for the registry changes to take effect, you need to restart K3s on each node. + +# Adding Images to the Private Registry + +First, obtain the k3s-images.txt file from GitHub for the release you are working with. +Pull the K3s images listed on the k3s-images.txt file from docker.io + +Example: `docker pull docker.io/rancher/coredns-coredns:1.6.3` + +Then, retag the images to the private registry. + +Example: `docker tag coredns-coredns:1.6.3 mycustomreg:5000/coredns-coredns` + +Last, push the images to the private registry. + +Example: `docker push mycustomreg:5000/coredns-coredns`