mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-05-16 01:53:51 +00:00
Merge pull request #2381 from davidnuzik/airgap-changes
[K3s] Update airgap docs to mention both airgap install methods
This commit is contained in:
David Nuzik
GitHub
@@ -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: <path to the cert file used in the registry>
|
||||
key_file: <path to the key file used in the registry>
|
||||
ca_file: <path to the ca file used in the registry>
|
||||
```
|
||||
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.
|
||||
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user