public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-27 05:28:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2381 from davidnuzik/airgap-changes

Browse Source 
[K3s] Update airgap docs to mention both airgap install methods
This commit is contained in:
David Nuzik
2020-03-26 16:38:23 -07:00
committed by GitHub
parent 632dd58ff0 24ffa4453f
commit 5b6ac23316
2 changed files with 96 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/k3s/latest/en/installation/airgap/_index.md
+76 -38
View File
@@ -3,77 +3,115 @@ title: "Air-Gap Install"
weight: 60 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) 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.
2. [Create Registry YAML](#create-registry-YAML) 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).
3. [Install K3s](#install-k3s)
### 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. 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 ```sh
sudo mkdir -p /var/lib/rancher/k3s/agent/images/ sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/ sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/
``` ```
### Create Registry YAML Place the k3s binary at /usr/local/bin/k3s and ensure it is executable.
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:
``` Follow the steps in the next section to install K3s.
---
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>
```
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. Obtain the K3s binary from the [releases](https://github.com/rancher/k3s/releases) page, matching the same version used to get the airgap images.
Also obtain the K3s install script at https://get.k3s.io Obtain the K3s install script at https://get.k3s.io
Place the binary in `/usr/local/bin` on each node. Place the binary in `/usr/local/bin` on each node and ensure it is executable.
Place the install script anywhere on each node, name it `install.sh`. 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_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 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. {{% /tab %}}
The node-token is on the server at `/var/lib/rancher/k3s/server/node-token` {{% 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. >**Note:** K3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gap networks.
# Upgrading # Upgrading
### Install Script Method
Upgrading an air-gap environment can be accomplished in the following manner: 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. 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
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. 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). 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.
content/k3s/latest/en/installation/private-registry/_index.md
+20 -5
View File
@@ -25,7 +25,7 @@ Mirrors is a directive that defines the names and endpoints of the private regis
``` ```
mirrors: mirrors:
"mycustomreg.com:5000": docker.io:
endpoint: endpoint:
- "https://mycustomreg.com:5000" - "https://mycustomreg.com:5000"
``` ```
@@ -59,7 +59,7 @@ Below are examples showing how you may configure `/etc/rancher/k3s/registries.ya
``` ```
mirrors: mirrors:
"mycustomreg.com:5000": docker.io:
endpoint: endpoint:
- "https://mycustomreg.com:5000" - "https://mycustomreg.com:5000"
configs: configs:
@@ -78,7 +78,7 @@ configs:
``` ```
mirrors: mirrors:
"mycustomreg.com:5000": docker.io:
endpoint: endpoint:
- "https://mycustomreg.com:5000" - "https://mycustomreg.com:5000"
configs: configs:
@@ -101,7 +101,7 @@ Below are examples showing how you may configure `/etc/rancher/k3s/registries.ya
``` ```
mirrors: mirrors:
"mycustomreg.com:5000": docker.io:
endpoint: endpoint:
- "http://mycustomreg.com:5000" - "http://mycustomreg.com:5000"
configs: configs:
@@ -116,7 +116,7 @@ configs:
``` ```
mirrors: mirrors:
"mycustomreg.com:5000": docker.io:
endpoint: endpoint:
- "http://mycustomreg.com:5000" - "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 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. 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`