From b215eb1e7bbdbadd5461866b719dcd258b1aa7b4 Mon Sep 17 00:00:00 2001 From: David Nuzik Date: Tue, 24 Mar 2020 18:42:33 -0700 Subject: [PATCH 1/6] Update airgap docs to mention both airgap install methods - Separate out the Manually Deploy Images method from the Private Registry method -- Explain the caveat with manual image deployment (could be unmanagable for larger clusters) - Show separate tabs for installing in a single server configuration or HA configuration - Update the upgrade section to include the system upgrade controller - Various tweaks throughout to improve readability --- .../latest/en/installation/airgap/_index.md | 181 +++++++++++++++--- 1 file changed, 150 insertions(+), 31 deletions(-) diff --git a/content/k3s/latest/en/installation/airgap/_index.md b/content/k3s/latest/en/installation/airgap/_index.md index dbfe7a38898..e0db18c9fe0 100644 --- a/content/k3s/latest/en/installation/airgap/_index.md +++ b/content/k3s/latest/en/installation/airgap/_index.md @@ -3,32 +3,20 @@ 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 such as on your bastion host 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) +We are assuming you have already created your nodes in your air-gap environment and have a secure Docker private registry on your bastion host. -### Prepare Images Directory -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: - -```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 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: ``` --- mirrors: - "mycustomreg.com:5000": + docker.io: endpoint: - "https://mycustomreg.com:5000" configs: @@ -37,43 +25,174 @@ configs: username: xxxxxx # this is the registry username password: xxxxxx # this is the registry password tls: - cert_file: - key_file: - ca_file: + 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 +1. Pull the K3s images from the k3s-images.txt file from docker.io + Note, the k3s-images.txt file is an asset on GitHub for your release. -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 +2. Retag the images to the private registry. -Place the binary in `/usr/local/bin` on each node. -Place the install script anywhere on each node, name it `install.sh`. +3. Push the images to the private registry. -Install K3s on each server: +You can now go to the [Install K3s](install-k3s) section below and begin K3s installation. + + +# 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. As such, it's not recommended for larger clusters as this could be difficult to manage. + +### 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, 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/ +``` + +Place the k3s binary at /usr/local/bin/k3s and ensure it is executable. + +Follow the steps in the next section to 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. +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`. + + +### 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/instalaltion/ha) or [High Availability with Embedded DB (Experimental)]({{< baseurl >}}/k3s/latest/en/installatin/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). + + +### System Upgrade Controller Method + +As of v1.17.4+k3s1 the [System Upgrade Controller](https://github.com/rancher/system-upgrade-controller/blob/master/README.md) is supported. The system upgrade controller can be utilized in an environment that has a private registry to rollout upgrades to your cluster as directed in a new CRD the controller introduces called a **Plan**. + +First, push necessary (newer) images to the registry. Take care to replace TAG with the newer tag, using the latest stable release (tag) for each image. + +``` +rancher/k3s-upgrade:TAG +rancher/system-upgrade-controller:TAG +rancher/kubectl:TAG +``` + +Then, install the system upgrade controller by applying the manifest yaml. For example v0.3.1 is at https://github.com/rancher/system-upgrade-controller/blob/v0.3.1/manifests/system-upgrade-controller.yaml +You will need to obtain the latest release of the yaml before you apply it. + +Now, configure your system upgrade controller YAML (Plan) to your liking. Refer to the [readme](https://github.com/rancher/system-upgrade-controller/blob/master/README.md) for more information. +Below, we have provided an example for server nodes and agent nodes. You should take care to ensure each Plan you will utilize meets your needs. Please note, before you apply your Plans, ensure you have set your labels appropriately for each node. + +``` +--- +# Example server upgrade plan +# Always upgrade server nodes first +apiVersion: upgrade.cattle.io/v1 +kind: Plan +metadata: + name: k3s-server-plan + namespace: system-upgrade +spec: + concurrency: 1 + version: v1.17.4-k3s1 + nodeSelector: + matchExpressions: + - {key: k3s-server-upgrade, operator: Exists} + serviceAccountName: system-upgrade + drain: + force: true + upgrade: + image: rancher/k3s-upgrade +``` + +``` +--- +# Example agent upgrade plan +# Always upgrade any agent nodes last +apiVersion: upgrade.cattle.io/v1 +kind: Plan +metadata: + name: k3s-agent-plan + namespace: system-upgrade +spec: + prepare: + image: rancher/k3s-upgrade:latest + args: ["prepare","k3s-master-plan"] + concurrency: 1 + version: v1.17.4-k3s1 + nodeSelector: + matchExpressions: + - {key: k3s-agent-upgrade, operator: Exists} + serviceAccountName: system-upgrade + drain: + force: true + upgrade: + image: rancher/k3s-upgrade +``` + +Once you have applied the necessary labels to each node you can apply your Plans. Always take care to deploy the plan for servers first before applying the plan to agents. +Based on our examples provided above, we would need to set the `k3s-server-upgrade` label for our server plan and the `k3s-agent-upgrade` label for our agent plan. + +The System Upgrade Controller will rollout the upgrade plan as per the spec for each plan. Please be patient as the rollout can take time in large clusters depending on the concurrency value. + From 052a66a145b31296ad152498f8d96d19e471c66a Mon Sep 17 00:00:00 2001 From: David Nuzik Date: Tue, 24 Mar 2020 20:16:42 -0700 Subject: [PATCH 2/6] Various tweaks to address comments - Explain what the registry yaml we suggest will accomplish - Provide docker pull, tag, push examples - Resolve issues in S.U.C. agent YAML --- .../latest/en/installation/airgap/_index.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/content/k3s/latest/en/installation/airgap/_index.md b/content/k3s/latest/en/installation/airgap/_index.md index e0db18c9fe0..fab40f66bb5 100644 --- a/content/k3s/latest/en/installation/airgap/_index.md +++ b/content/k3s/latest/en/installation/airgap/_index.md @@ -11,7 +11,8 @@ We are assuming you have already created your nodes in your air-gap environment ### Create the 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: +It is recommended to mirror docker.io and the following YAML will accomplish this. +Make sure you replace `mycustomreg.com` in both places, and supply the registry auth username, pass, and all tls cert paths. ``` --- @@ -34,10 +35,13 @@ Note, at this time only secure registries are supported with K3s (SSL with custo 1. Pull the K3s images from the k3s-images.txt file from docker.io Note, the k3s-images.txt file is an asset on GitHub for your release. +Example: `docker pull docker.io/rancher/coredns-coredns:1.6.3` 2. Retag the images to the private registry. +Example: `docker tag coredns-coredns:1.6.3 mycustomreg:5000/coredns-coredns` 3. Push the images to the private registry. +Example: `docker push mycustomreg:5000/coredns-coredns` You can now go to the [Install K3s](install-k3s) section below and begin K3s installation. @@ -142,7 +146,7 @@ Then, install the system upgrade controller by applying the manifest yaml. For e You will need to obtain the latest release of the yaml before you apply it. Now, configure your system upgrade controller YAML (Plan) to your liking. Refer to the [readme](https://github.com/rancher/system-upgrade-controller/blob/master/README.md) for more information. -Below, we have provided an example for server nodes and agent nodes. You should take care to ensure each Plan you will utilize meets your needs. Please note, before you apply your Plans, ensure you have set your labels appropriately for each node. +Below, we have provided an example for server nodes and agent nodes. You should take care to ensure each Plan you will utilize meets your needs. Please note, before you apply your Plans, ensure you have set your labels appropriately for each node and if using the examples below that you have plugged in the K3s version for each instance of `VERSION_HERE`. ``` --- @@ -155,7 +159,7 @@ metadata: namespace: system-upgrade spec: concurrency: 1 - version: v1.17.4-k3s1 + version: VERSION_HERE nodeSelector: matchExpressions: - {key: k3s-server-upgrade, operator: Exists} @@ -163,7 +167,7 @@ spec: drain: force: true upgrade: - image: rancher/k3s-upgrade + image: k3s-upgrade ``` ``` @@ -178,9 +182,9 @@ metadata: spec: prepare: image: rancher/k3s-upgrade:latest - args: ["prepare","k3s-master-plan"] + args: ["prepare","k3s-server-plan"] concurrency: 1 - version: v1.17.4-k3s1 + version: VERSION_HERE nodeSelector: matchExpressions: - {key: k3s-agent-upgrade, operator: Exists} @@ -188,7 +192,7 @@ spec: drain: force: true upgrade: - image: rancher/k3s-upgrade + image: k3s-upgrade ``` Once you have applied the necessary labels to each node you can apply your Plans. Always take care to deploy the plan for servers first before applying the plan to agents. From 015a5fe035e3ba909bbedb709174bc781c73569b Mon Sep 17 00:00:00 2001 From: David Nuzik Date: Tue, 24 Mar 2020 21:18:01 -0700 Subject: [PATCH 3/6] Various tweaks to address comments 2 - Resolve issues Craig outlined: https://github.com/rancher/docs/pull/2381#pullrequestreview-380835214 https://github.com/rancher/docs/pull/2381#pullrequestreview-380837701 https://github.com/rancher/docs/pull/2381#pullrequestreview-380838546 - Fix the airgap page so we instead reference the private-registry page https://github.com/rancher/docs/pull/2381#pullrequestreview-380839331 - Modify the private-registry page so that it includes our newly added docker command examples and some other tweaks --- .../latest/en/installation/airgap/_index.md | 45 ++++--------------- .../installation/private-registry/_index.md | 25 ++++++++--- 2 files changed, 28 insertions(+), 42 deletions(-) diff --git a/content/k3s/latest/en/installation/airgap/_index.md b/content/k3s/latest/en/installation/airgap/_index.md index fab40f66bb5..3eb5a1477f8 100644 --- a/content/k3s/latest/en/installation/airgap/_index.md +++ b/content/k3s/latest/en/installation/airgap/_index.md @@ -3,53 +3,24 @@ title: "Air-Gap Install" weight: 60 --- -You can install K3s in an air-gapped environment using two different methods. You can either deploy a private registry such as on your bastion host and mirror docker.io or you can manually deploy images such as for small clusters. +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. # Private Registry Method -We are assuming you have already created your nodes in your air-gap environment and have a secure Docker private registry on your bastion host. +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). ### Create the 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. -It is recommended to mirror docker.io and the following YAML will accomplish this. -Make sure you replace `mycustomreg.com` in both places, and supply the registry auth username, pass, and all tls cert paths. -``` ---- -mirrors: - docker.io: - 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 [Private Registry Configuration]({{< baseurl >}}/k3s/latest/en/installation/private-registry) guide to create and configure the registry.yaml file. -Note, at this time only secure registries are supported with K3s (SSL with custom CA) - -1. Pull the K3s images from the k3s-images.txt file from docker.io - Note, the k3s-images.txt file is an asset on GitHub for your release. -Example: `docker pull docker.io/rancher/coredns-coredns:1.6.3` - -2. Retag the images to the private registry. -Example: `docker tag coredns-coredns:1.6.3 mycustomreg:5000/coredns-coredns` - -3. Push the images to the private registry. -Example: `docker push mycustomreg:5000/coredns-coredns` - -You can now go to the [Install K3s](install-k3s) section below and begin K3s installation. +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. As such, it's not recommended for larger clusters as this could be difficult to manage. +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. @@ -67,7 +38,7 @@ Follow the steps in the next section to 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. +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. Obtain the K3s install script at https://get.k3s.io @@ -97,7 +68,7 @@ INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetok {{% /tab %}} {{% tab "High Availability Configuration" %}} -Reference the [High Availability with an External DB]({{< baseurl >}}/k3s/latest/en/instalaltion/ha) or [High Availability with Embedded DB (Experimental)]({{< baseurl >}}/k3s/latest/en/installatin/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. +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: 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` From 05ee3bb540c26f3744fe9de070bc8a79d7a96830 Mon Sep 17 00:00:00 2001 From: David Nuzik Date: Tue, 24 Mar 2020 21:55:53 -0700 Subject: [PATCH 4/6] Modify system upgrade controller upgrade section - Address comment https://github.com/rancher/docs/pull/2381#pullrequestreview-380841861 -- This modifies the section and now calls it Automated upgrades. The necessary images to add to the private registry are listed and the guide now links to the Automated Upgrades guide. --- .../latest/en/installation/airgap/_index.md | 66 ++----------------- 1 file changed, 4 insertions(+), 62 deletions(-) diff --git a/content/k3s/latest/en/installation/airgap/_index.md b/content/k3s/latest/en/installation/airgap/_index.md index 3eb5a1477f8..fc2df77bf89 100644 --- a/content/k3s/latest/en/installation/airgap/_index.md +++ b/content/k3s/latest/en/installation/airgap/_index.md @@ -101,11 +101,11 @@ with the same environment variables. 3. Restart the K3s service (if not restarted automatically by installer). -### System Upgrade Controller Method +### Automated Upgrades Method -As of v1.17.4+k3s1 the [System Upgrade Controller](https://github.com/rancher/system-upgrade-controller/blob/master/README.md) is supported. The system upgrade controller can be utilized in an environment that has a private registry to rollout upgrades to your cluster as directed in a new CRD the controller introduces called a **Plan**. - -First, push necessary (newer) images to the registry. Take care to replace TAG with the newer tag, using the latest stable release (tag) for each image. +As of v1.17.4+k3s1 the [System Upgrade Controller](https://github.com/rancher/system-upgrade-controller/blob/master/README.md) is supported. The system upgrade controller can be utilized in an environment that has a private registry to rollout upgrades to your cluster as directed in a new CRD the controller introduces called a **Plan**. + +>**Note:** In order to leverage automated upgrades with the System Upgrade Controller in an airgapped environemnt, push the necessary images to the registry. Take care to replace TAG with the latest stable release (tag) for each image. After you have completed this, you can then follow the [Automated upgrades]({{< baseurl >}}/k3s/latest/en/upgrades/automated/) guide to learn more about the System Upgrade Controller and how to configure it. ``` rancher/k3s-upgrade:TAG @@ -113,61 +113,3 @@ rancher/system-upgrade-controller:TAG rancher/kubectl:TAG ``` -Then, install the system upgrade controller by applying the manifest yaml. For example v0.3.1 is at https://github.com/rancher/system-upgrade-controller/blob/v0.3.1/manifests/system-upgrade-controller.yaml -You will need to obtain the latest release of the yaml before you apply it. - -Now, configure your system upgrade controller YAML (Plan) to your liking. Refer to the [readme](https://github.com/rancher/system-upgrade-controller/blob/master/README.md) for more information. -Below, we have provided an example for server nodes and agent nodes. You should take care to ensure each Plan you will utilize meets your needs. Please note, before you apply your Plans, ensure you have set your labels appropriately for each node and if using the examples below that you have plugged in the K3s version for each instance of `VERSION_HERE`. - -``` ---- -# Example server upgrade plan -# Always upgrade server nodes first -apiVersion: upgrade.cattle.io/v1 -kind: Plan -metadata: - name: k3s-server-plan - namespace: system-upgrade -spec: - concurrency: 1 - version: VERSION_HERE - nodeSelector: - matchExpressions: - - {key: k3s-server-upgrade, operator: Exists} - serviceAccountName: system-upgrade - drain: - force: true - upgrade: - image: k3s-upgrade -``` - -``` ---- -# Example agent upgrade plan -# Always upgrade any agent nodes last -apiVersion: upgrade.cattle.io/v1 -kind: Plan -metadata: - name: k3s-agent-plan - namespace: system-upgrade -spec: - prepare: - image: rancher/k3s-upgrade:latest - args: ["prepare","k3s-server-plan"] - concurrency: 1 - version: VERSION_HERE - nodeSelector: - matchExpressions: - - {key: k3s-agent-upgrade, operator: Exists} - serviceAccountName: system-upgrade - drain: - force: true - upgrade: - image: k3s-upgrade -``` - -Once you have applied the necessary labels to each node you can apply your Plans. Always take care to deploy the plan for servers first before applying the plan to agents. -Based on our examples provided above, we would need to set the `k3s-server-upgrade` label for our server plan and the `k3s-agent-upgrade` label for our agent plan. - -The System Upgrade Controller will rollout the upgrade plan as per the spec for each plan. Please be patient as the rollout can take time in large clusters depending on the concurrency value. - From de2e81292ef1d7fa6a14c86bce0eabc65b6f03a7 Mon Sep 17 00:00:00 2001 From: David Nuzik Date: Thu, 26 Mar 2020 14:55:28 -0700 Subject: [PATCH 5/6] Fix Automated Upgrades section of Airgap doc Addresses concerns outlined here: https://github.com/rancher/docs/pull/2381#pullrequestreview-382323414 - fix S.U.C. capitalization and format - Remove S.U.C. explanation as this is coverd in the Automated Upgrades guide - Rephrase and reformat things as recommended by Craig. the latest version of the S.U.C. manifest YAML is now hyperlinked and an example provided for v0.4.0 --- .../k3s/latest/en/installation/airgap/_index.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/content/k3s/latest/en/installation/airgap/_index.md b/content/k3s/latest/en/installation/airgap/_index.md index fc2df77bf89..cedbabd58ac 100644 --- a/content/k3s/latest/en/installation/airgap/_index.md +++ b/content/k3s/latest/en/installation/airgap/_index.md @@ -103,13 +103,16 @@ with the same environment variables. ### Automated Upgrades Method -As of v1.17.4+k3s1 the [System Upgrade Controller](https://github.com/rancher/system-upgrade-controller/blob/master/README.md) is supported. The system upgrade controller can be utilized in an environment that has a private registry to rollout upgrades to your cluster as directed in a new CRD the controller introduces called a **Plan**. - ->**Note:** In order to leverage automated upgrades with the System Upgrade Controller in an airgapped environemnt, push the necessary images to the registry. Take care to replace TAG with the latest stable release (tag) for each image. After you have completed this, you can then follow the [Automated upgrades]({{< baseurl >}}/k3s/latest/en/upgrades/automated/) guide to learn more about the System Upgrade Controller and how to configure it. +As of v1.17.4+k3s1 K3s supports [automated upgrades]({{< baseurl >}}/k3s/latest/en/upgrades/automated/). To enable this in an air-gapped networks, 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/k3s-upgrade:TAG -rancher/system-upgrade-controller:TAG -rancher/kubectl:TAG +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. From 24ffa4453f8b03814b1d19f86e2789cdeddb08b8 Mon Sep 17 00:00:00 2001 From: David Nuzik Date: Thu, 26 Mar 2020 16:36:19 -0700 Subject: [PATCH 6/6] Resolving remaining concerns around K3s airgap page - Tweaks to the Automated upgrades section --- content/k3s/latest/en/installation/airgap/_index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/content/k3s/latest/en/installation/airgap/_index.md b/content/k3s/latest/en/installation/airgap/_index.md index cedbabd58ac..7f9f4a8ec21 100644 --- a/content/k3s/latest/en/installation/airgap/_index.md +++ b/content/k3s/latest/en/installation/airgap/_index.md @@ -103,12 +103,11 @@ with the same environment variables. ### Automated Upgrades Method -As of v1.17.4+k3s1 K3s supports [automated upgrades]({{< baseurl >}}/k3s/latest/en/upgrades/automated/). To enable this in an air-gapped networks, you must ensure the required images are available in your private registry. +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: +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