mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-05-13 00:23:23 +00:00
Reorganize upgrade docs because RancherD docs were added
This commit is contained in:
Catherine Luse
@@ -12,17 +12,27 @@ aliases:
|
||||
|
||||
After completing your Docker installation of Rancher, we recommend creating backups of it on a regular basis. Having a recent backup will let you recover quickly from an unexpected disaster.
|
||||
|
||||
## Before You Start
|
||||
### How to Read Placeholders
|
||||
|
||||
During the creation of your backup, you'll enter a series of commands, replacing placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (`<EXAMPLE>`). Here's an example of a command with a placeholder:
|
||||
|
||||
```
|
||||
docker run --volumes-from rancher-data-<DATE> -v $PWD:/backup busybox tar pzcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
|
||||
docker run \
|
||||
--volumes-from rancher-data-<DATE> \
|
||||
-v $PWD:/backup busybox tar pzcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
|
||||
```
|
||||
|
||||
In this command, `<DATE>` is a placeholder for the date that the data container and backup were created. `9-27-18` for example.
|
||||
|
||||
Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the [procedure below](#creating-a-backup).
|
||||
### Obtaining Placeholder Data
|
||||
|
||||
Get the placeholder data by running:
|
||||
|
||||
```
|
||||
docker ps
|
||||
```
|
||||
|
||||
Write down or copy this information before starting the [procedure below](#creating-a-backup).
|
||||
|
||||
<sup>Terminal `docker ps` Command, Displaying Where to Find `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>`</sup>
|
||||
|
||||
@@ -37,7 +47,7 @@ Cross reference the image and reference table below to learn how to obtain this
|
||||
|
||||
You can obtain `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>` by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: `docker ps`. You can also view containers that are stopped with `docker ps -a`. Use these commands for help anytime while creating backups.
|
||||
|
||||
## Creating a Backup
|
||||
### Creating a Backup
|
||||
|
||||
This procedure creates a backup that you can restore if Rancher encounters a disaster scenario.
|
||||
|
||||
|
||||
@@ -13,16 +13,24 @@ aliases:
|
||||
---
|
||||
This section describes how to create backups of your high-availability Rancher install.
|
||||
|
||||
>**Prerequisites:** {{< requirements_rollback >}}
|
||||
|
||||
## RKE Kubernetes Cluster Data
|
||||
|
||||
In an RKE installation, the cluster data is replicated on each of three etcd nodes in the cluster, providing redundancy and data duplication in case one of the nodes fails.
|
||||
|
||||
<figcaption>Architecture of an RKE Kubernetes Cluster Running the Rancher Management Server</figcaption>
|
||||
<figcaption>Cluster Data within an RKE Kubernetes Cluster Running the Rancher Management Server</figcaption>
|
||||
|
||||
|
||||
## Backup Outline
|
||||
# Requirements
|
||||
|
||||
### RKE Version
|
||||
|
||||
The commands for taking `etcd` snapshots are only available in RKE v0.1.7 and later.
|
||||
|
||||
### RKE Config File
|
||||
|
||||
You'll need the RKE config file that you used for Rancher install, `rancher-cluster.yml`. You created this file during your initial install. Place this file in same directory as the RKE binary.
|
||||
|
||||
|
||||
# Backup Outline
|
||||
|
||||
|
||||
Backing up your high-availability Rancher cluster is process that involves completing multiple tasks.
|
||||
|
||||
@@ -30,13 +38,12 @@ Backing up your high-availability Rancher cluster is process that involves compl
|
||||
|
||||
Take snapshots of your current `etcd` database using Rancher Kubernetes Engine (RKE).
|
||||
|
||||
1. [Store Snapshot(s) Externally](#2-backup-snapshots-to-a-safe-location)
|
||||
1. [Store Snapshot(s) Externally](#2-back-up-local-snapshots-to-a-safe-location)
|
||||
|
||||
After taking your snapshots, export them to a safe location that won't be affected if your cluster encounters issues.
|
||||
|
||||
<br/>
|
||||
|
||||
### 1. Take Snapshots of the `etcd` Database
|
||||
# 1. Take Snapshots of the `etcd` Database
|
||||
|
||||
Take snapshots of your `etcd` database. You can use these snapshots later to recover from a disaster scenario. There are two ways to take snapshots: recurringly, or as a one-off. Each option is better suited to a specific use case. Read the short description below each link to know when to use each option.
|
||||
|
||||
@@ -48,7 +55,7 @@ Take snapshots of your `etcd` database. You can use these snapshots later to rec
|
||||
|
||||
We advise taking one-time snapshots before events like upgrades or restoration of another snapshot.
|
||||
|
||||
#### Option A: Recurring Snapshots
|
||||
### Option A: Recurring Snapshots
|
||||
|
||||
For all high-availability Rancher installs, we recommend taking recurring snapshots so that you always have a safe restoration point available.
|
||||
|
||||
@@ -103,7 +110,7 @@ To take recurring snapshots, enable the `etcd-snapshot` service, which is a serv
|
||||
|
||||
**Result:** RKE is configured to take recurring snapshots of `etcd` on all nodes running the `etcd` role. Snapshots are saved locally to the following directory: `/opt/rke/etcd-snapshots/`. If configured, the snapshots are also uploaded to your S3 compatible backend.
|
||||
|
||||
#### Option B: One-Time Snapshots
|
||||
### Option B: One-Time Snapshots
|
||||
|
||||
When you're about to upgrade Rancher or restore it to a previous snapshot, you should snapshot your live image so that you have a backup of `etcd` in its last known state.
|
||||
|
||||
@@ -114,7 +121,9 @@ When you're about to upgrade Rancher or restore it to a previous snapshot, you s
|
||||
2. Enter the following command. Replace `<SNAPSHOT.db>` with any name that you want to use for the snapshot (e.g. `upgrade.db`).
|
||||
|
||||
```
|
||||
rke etcd snapshot-save --name <SNAPSHOT.db> --config rancher-cluster.yml
|
||||
rke etcd snapshot-save \
|
||||
--name <SNAPSHOT.db> \
|
||||
--config rancher-cluster.yml
|
||||
```
|
||||
|
||||
**Result:** RKE takes a snapshot of `etcd` running on each `etcd` node. The file is saved to `/opt/rke/etcd-snapshots`.
|
||||
@@ -128,15 +137,20 @@ _Available as of RKE v0.2.0_
|
||||
2. Enter the following command. Replace `<SNAPSHOT.db>` with any name that you want to use for the snapshot (e.g. `upgrade.db`).
|
||||
|
||||
```shell
|
||||
rke etcd snapshot-save --config rancher-cluster.yml --name snapshot-name \
|
||||
--s3 --access-key S3_ACCESS_KEY --secret-key S3_SECRET_KEY \
|
||||
--bucket-name s3-bucket-name --s3-endpoint s3.amazonaws.com \
|
||||
--folder folder-name # Available as of v2.3.0
|
||||
rke etcd snapshot-save \
|
||||
--config rancher-cluster.yml \
|
||||
--name snapshot-name \
|
||||
--s3 \
|
||||
--access-key S3_ACCESS_KEY \
|
||||
--secret-key S3_SECRET_KEY \
|
||||
--bucket-name s3-bucket-name \
|
||||
--s3-endpoint s3.amazonaws.com \
|
||||
--folder folder-name # Available as of v2.3.0
|
||||
```
|
||||
|
||||
**Result:** RKE takes a snapshot of `etcd` running on each `etcd` node. The file is saved to `/opt/rke/etcd-snapshots`. It is also uploaded to the S3 compatible backend.
|
||||
|
||||
### 2. Backup Local Snapshots to a Safe Location
|
||||
# 2. Back up Local Snapshots to a Safe Location
|
||||
|
||||
> **Note:** If you are using RKE v0.2.0, you can enable saving the backups to a S3 compatible backend directly and skip this step.
|
||||
|
||||
|
||||
@@ -34,6 +34,8 @@ Prepare by creating 3 new nodes to be the target for the restored Rancher instan
|
||||
|
||||
Alternatively you can re-use the existing nodes after clearing Kubernetes and Rancher configurations. This will destroy the data on these nodes. See [Node Cleanup]({{<baseurl>}}/rancher/v2.x/en/faq/cleaning-cluster-nodes/) for the procedure.
|
||||
|
||||
You must restore each of your etcd nodes to the same snapshot. Copy the snapshot you're using from one of your nodes to the others before running the `etcd snapshot-restore` command.
|
||||
|
||||
> **IMPORTANT:** Before starting the restore make sure all the Kubernetes services on the old cluster nodes are stopped. We recommend powering off the nodes to be sure.
|
||||
|
||||
### 2. Place Snapshot
|
||||
|
||||
+8
-1
@@ -1,12 +1,19 @@
|
||||
---
|
||||
title: Helm Chart Options
|
||||
weight: 2
|
||||
weight: 1
|
||||
aliases:
|
||||
- /rancher/v2.x/en/installation/options/
|
||||
- /rancher/v2.x/en/installation/options/chart-options/
|
||||
- /rancher/v2.x/en/installation/options/helm2/helm-rancher/chart-options/
|
||||
- /rancher/v2.x/en/installation/resources/chart-options
|
||||
---
|
||||
|
||||
This page is a configuration reference for the Rancher Helm chart.
|
||||
|
||||
For help choosing a Helm chart version, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/installation/resources/choosing-version/)
|
||||
|
||||
For information on enabling experimental features, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/installation/resources/feature-flags/)
|
||||
|
||||
- [Common Options](#common-options)
|
||||
- [Advanced Options](#advanced-options)
|
||||
- [API Audit Log](#api-audit-log)
|
||||
+11
-10
@@ -1,22 +1,24 @@
|
||||
---
|
||||
title: Rollbacks
|
||||
weight: 1010
|
||||
weight: 3
|
||||
aliases:
|
||||
- /rancher/v2.x/en/upgrades/rollbacks
|
||||
- /rancher/v2.x/en/installation/upgrades-rollbacks/rollbacks
|
||||
- /rancher/v2.x/en/upgrades/ha-server-rollbacks
|
||||
- /rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks
|
||||
- /rancher/v2.x/en/installation/upgrades-rollbacks/rollbacks/ha-server-rollbacks
|
||||
- /rancher/v2.x/en/installation/install-rancher-on-k8s/upgrades-rollbacks/rollbacks
|
||||
---
|
||||
|
||||
This section contains information about how to roll back your Rancher server to a previous version.
|
||||
To roll back to Rancher v2.5+, use the `rancher-backup` application and restore Rancher from backup according to [this section.]({{<baseurl>}}/rancher/v2.x/en/backups/restoring-rancher/)
|
||||
|
||||
If you upgrade Rancher and the upgrade does not complete successfully, you may need to [restore Rancher from backup.](../../backups/restores)
|
||||
To roll back to Rancher prior to v2.5, follow the procedure detailed here: [Restoring Backups — Kubernetes installs]({{<baseurl>}}/rancher/v2.x/en/backups/restorations/ha-restoration) Restoring a snapshot of the Rancher Server cluster will revert Rancher to the version and state at the time of the snapshot.
|
||||
|
||||
Restoring a snapshot of the Rancher Server cluster will revert Rancher to the version and state at the time of the snapshot.
|
||||
For information on how to roll back Rancher installed with Docker, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks)
|
||||
|
||||
>**Note:** Managed clusters are authoritative for their state. This means restoring the rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken.
|
||||
> Managed clusters are authoritative for their state. This means restoring the rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken.
|
||||
|
||||
- [Rolling back Rancher installed with Docker]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks)
|
||||
- [Rolling back Rancher installed on a Kubernetes cluster]({{<baseurl>}}/rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks/)
|
||||
|
||||
### Special Scenarios regarding Rollbacks
|
||||
### Rolling back to v2.0.0-v2.1.5
|
||||
|
||||
If you are rolling back to versions in either of these scenarios, you must follow some extra instructions in order to get your clusters working.
|
||||
|
||||
@@ -27,7 +29,6 @@ Because of the changes necessary to address [CVE-2018-20321](https://cve.mitre.o
|
||||
|
||||
1. Record the `serviceAccountToken` for each cluster. To do this, save the following script on a machine with `kubectl` access to the Rancher management plane and execute it. You will need to run these commands on the machine where the rancher container is running. Ensure JQ is installed before running the command. The commands will vary depending on how you installed Rancher.
|
||||
|
||||
|
||||
**Rancher Installed with Docker**
|
||||
```
|
||||
docker exec <NAME OF RANCHER CONTAINER> kubectl get clusters -o json | jq '[.items[] | select(any(.status.conditions[]; .type == "ServiceAccountMigrated")) | {name: .metadata.name, token: .status.serviceAccountToken}]' > tokens.json
|
||||
@@ -0,0 +1,288 @@
|
||||
---
|
||||
title: Upgrades
|
||||
weight: 2
|
||||
aliases:
|
||||
- /rancher/v2.x/en/upgrades/upgrades
|
||||
- /rancher/v2.x/en/installation/upgrades-rollbacks/upgrades
|
||||
- /rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade-helm-airgap
|
||||
- /rancher/v2.x/en/upgrades/air-gap-upgrade/
|
||||
- /rancher/v2.x/en/upgrades/upgrades/ha
|
||||
- /rancher/v2.x/en/installation/install-rancher-on-k8s/upgrades/upgrades/ha
|
||||
- /rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/
|
||||
- /rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade-helm/
|
||||
- /rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/ha
|
||||
- /rancher/v2.x/en/installation/install-rancher-on-k8s/upgrades-rollbacks/upgrades
|
||||
---
|
||||
The following instructions will guide you through upgrading a Rancher server that was installed on a Kubernetes cluster with Helm. These steps also apply to air gap installs with Helm.
|
||||
|
||||
For the instructions to upgrade Rancher installed on Kubernetes with RancherD, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/installation/install-rancher-on-linux/upgrades)
|
||||
|
||||
For the instructions to upgrade Rancher installed with Docker, refer to [ths page.]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-upgrades)
|
||||
|
||||
To upgrade the components in your Kubernetes cluster, or the definition of the [Kubernetes services]({{<baseurl>}}/rke/latest/en/config-options/services/) or [add-ons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/), refer to the [upgrade documentation for RKE]({{<baseurl>}}/rke/latest/en/upgrades/), the Rancher Kubernetes Engine.
|
||||
|
||||
If you installed Rancher using the RKE Add-on yaml, follow the directions to [migrate or upgrade]({{<baseurl>}}/rancher/v2.x/en/upgrades/upgrades/migrating-from-rke-add-on).
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Upgrade Outline](#upgrade-outline)
|
||||
- [Known Upgrade Issues](#known-upgrade-issues)
|
||||
- [RKE Add-on Installs](#rke-add-on-installs)
|
||||
|
||||
# Prerequisites
|
||||
|
||||
### Access to kubeconfig
|
||||
|
||||
Helm should be run from the same location as your kubeconfig file, or the same location where you run your kubectl commands from.
|
||||
|
||||
If you installed Kubernetes with RKE, the config will have been created in the directory you ran `rke up` in.
|
||||
|
||||
The kubeconfig can also be manually targeted for the intended cluster with the `--kubeconfig` tag (see: https://helm.sh/docs/helm/helm/)
|
||||
|
||||
### Review Known Issues
|
||||
|
||||
Review the [known upgrade issues](#known-upgrade-issues) in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher.
|
||||
|
||||
A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
|
||||
|
||||
Note that upgrades _to_ or _from_ any chart in the [rancher-alpha repository]({{<baseurl>}}/rancher/v2.x/en/installation/resources/chart-options/#helm-chart-repositories/) aren't supported.
|
||||
|
||||
### Helm Version
|
||||
|
||||
The upgrade instructions assume you are using Helm 3.
|
||||
|
||||
For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) The [Helm 2 upgrade page here]({{<baseurl>}}/rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/ha/helm2)provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
|
||||
### For air gap installs: Populate private registry
|
||||
|
||||
-For [air gap installs only,]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/air-gap) collect and populate images for the new Rancher server version. Follow the guide to [populate your private registry]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/air-gap/populate-private-registry/) with the images for the Rancher version that you want to upgrade to.
|
||||
|
||||
### For upgrades from a Rancher server with a hidden local cluster
|
||||
|
||||
If you are upgrading to Rancher v2.5 from a Rancher server that was started with the Helm chart option `--add-local=false`, you will need to drop that flag when upgrading. Otherwise, the Rancher server will not start. The `restricted-admin` role can be used to continue restricting access to the local cluster. For more information, see [this section.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#upgrading-from-rancher-with-a-hidden-local-cluster)
|
||||
|
||||
### For upgrades from v2.0-v2.2 with external TLS termination
|
||||
|
||||
If you are upgrading Rancher from v2.x to v2.3+, and you are using external TLS termination, you will need to edit the cluster.yml to [enable using forwarded host headers.]({{<baseurl>}}/rancher/v2.x/en/installation/resources/chart-options/#configuring-ingress-for-external-tls-when-using-nginx-v0-25)
|
||||
|
||||
### For upgrades with cert-manager older than 0.8.0
|
||||
|
||||
[Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) Upgrade cert-manager to the latest version by following [these instructions.]({{<baseurl>}}/rancher/v2.x/en/installation/options/upgrading-cert-manager)
|
||||
|
||||
# Upgrade Outline
|
||||
|
||||
Follow the steps to upgrade Rancher server:
|
||||
|
||||
- [1. Back up your Kubernetes cluster that is running Rancher server](#1-back-up-your-kubernetes-cluster-that-is-running-rancher-server)
|
||||
- [2. Update the Helm chart repository](#2-update-the-helm-chart-repository)
|
||||
- [3. Upgrade Rancher](#3-upgrade-rancher)
|
||||
- [4. Verify the Upgrade](#4-verify-the-upgrade)
|
||||
|
||||
# 1. Back up Your Kubernetes Cluster that is Running Rancher Server
|
||||
|
||||
For Rancher v2.5+, use the [backup application]({{<baseurl>}}/rancher/v2.x/en/backups/v2.5/back-up-rancher) to back up Rancher.
|
||||
|
||||
For Rancher v2.0-v2.4, [take a one-time snapshot]({{<baseurl>}}/rancher/v2.x/en/backups/backups/ha-backups/#option-b-one-time-snapshots)
|
||||
of your Kubernetes cluster running Rancher server.
|
||||
|
||||
You'll use the backup as a restoration point if something goes wrong during upgrade.
|
||||
|
||||
# 2. Update the Helm chart repository
|
||||
|
||||
1. Update your local helm repo cache.
|
||||
|
||||
```
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Get the repository name that you used to install Rancher.
|
||||
|
||||
For information about the repos and their differences, see [Helm Chart Repositories]({{<baseurl>}}/rancher/v2.x/en/installation/resources/chart-options/#helm-chart-repositories).
|
||||
|
||||
{{< release-channel >}}
|
||||
|
||||
```
|
||||
helm repo list
|
||||
|
||||
NAME URL
|
||||
stable https://kubernetes-charts.storage.googleapis.com
|
||||
rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>
|
||||
```
|
||||
|
||||
> **Note:** If you want to switch to a different Helm chart repository, please follow the [steps on how to switch repositories]({{<baseurl>}}/rancher/v2.x/en/installation/resources/chart-options/#switching-to-a-different-helm-chart-repository). If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added.
|
||||
|
||||
|
||||
1. Fetch the latest chart to install Rancher from the Helm chart repository.
|
||||
|
||||
This command will pull down the latest charts and save it in the current directory as a `.tgz` file.
|
||||
|
||||
```plain
|
||||
helm fetch rancher-<CHART_REPO>/rancher
|
||||
```
|
||||
You can fetch the chart for the specific version you are upgrading to by adding in the `--version=` tag. For example:
|
||||
|
||||
```plain
|
||||
helm fetch rancher-<CHART_REPO>/rancher --version=v2.4.11
|
||||
```
|
||||
|
||||
# 3. Upgrade Rancher
|
||||
|
||||
This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.
|
||||
|
||||
{{% tabs %}}
|
||||
{{% tab "Kubernetes Upgrade" %}}
|
||||
|
||||
Get the values, which were passed with `--set`, from the current Rancher Helm chart that is installed.
|
||||
|
||||
```
|
||||
helm get values rancher -n cattle-system
|
||||
|
||||
hostname: rancher.my.org
|
||||
```
|
||||
|
||||
> **Note:** There will be more values that are listed with this command. This is just an example of one of the values.
|
||||
|
||||
If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow [Option B: Reinstalling Rancher and cert-manager.](#option-b-reinstalling-rancher-and-cert-manager)
|
||||
|
||||
Otherwise, follow [Option A: Upgrading Rancher.](#option-a-upgrading-rancher)
|
||||
|
||||
### Option A: Upgrading Rancher
|
||||
|
||||
Upgrade Rancher to the latest version with all your settings.
|
||||
|
||||
Take all the values from the previous step and append them to the command using `--set key=value`:
|
||||
|
||||
```
|
||||
helm upgrade rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
> **Note:** The above is an example, there may be more values from the previous step that need to be appended.
|
||||
|
||||
Alternatively, it's possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version:
|
||||
|
||||
```
|
||||
helm get values rancher -n cattle-system -o yaml > values.yaml
|
||||
|
||||
helm upgrade rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
-f values.yaml \
|
||||
--version=2.4.5
|
||||
```
|
||||
|
||||
### Option B: Reinstalling Rancher and cert-manager
|
||||
|
||||
If you are currently running the cert-manger whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, then you need to reinstall both Rancher and cert-manger due to the API change in cert-manger v0.11.
|
||||
|
||||
1. Uninstall Rancher
|
||||
|
||||
```
|
||||
helm delete rancher -n cattle-system
|
||||
```
|
||||
|
||||
2. Uninstall and reinstall `cert-manager` according to the instructions on the [Upgrading Cert-Manager]({{<baseurl>}}/rancher/v2.x/en/installation/options/upgrading-cert-manager) page.
|
||||
|
||||
3. Reinstall Rancher to the latest version with all your settings. Take all the values from the step 1 and append them to the command using `--set key=value`. Note: There will be many more options from the step 1 that need to be appended.
|
||||
|
||||
```
|
||||
helm install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
{{% /tab %}}
|
||||
|
||||
{{% tab "Kubernetes Air Gap Upgrade" %}}
|
||||
|
||||
Render the Rancher template using the same chosen options that were used when installing Rancher. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.
|
||||
|
||||
Based on the choice you made during installation, complete one of the procedures below.
|
||||
|
||||
Placeholder | Description
|
||||
------------|-------------
|
||||
`<VERSION>` | The version number of the output tarball.
|
||||
`<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer.
|
||||
`<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.
|
||||
`<CERTMANAGER_VERSION>` | Cert-manager version running on k8s cluster.
|
||||
|
||||
|
||||
### Option A: Default Self-signed Certificate
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set certmanager.version=<CERTMANAGER_VERSION> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
### Option B: Certificates from Files using Kubernetes Secrets
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`:
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set privateCA=true \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
### Apply the Rendered Templates
|
||||
|
||||
Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates.
|
||||
|
||||
Use `kubectl` to apply the rendered manifests.
|
||||
|
||||
```plain
|
||||
kubectl -n cattle-system apply -R -f ./rancher
|
||||
```
|
||||
|
||||
{{% /tab %}}
|
||||
{{% /tabs %}}
|
||||
|
||||
# 4. Verify the Upgrade
|
||||
|
||||
Log into Rancher to confirm that the upgrade succeeded.
|
||||
|
||||
>**Having network issues following upgrade?**
|
||||
>
|
||||
> See [Restoring Cluster Networking]({{<baseurl>}}/rancher/v2.x/en/installation/install-rancher-on-k8s/upgrades/namespace-migration/#restoring-cluster-networking).
|
||||
|
||||
# Known Upgrade Issues
|
||||
|
||||
The following table lists some of the most noteworthy issues to be considered when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
|
||||
|
||||
Upgrade Scenario | Issue
|
||||
---|---
|
||||
Upgrading to v2.4.6 or v2.4.7 | These Rancher versions had an issue where the `kms:ListKeys` permission was required to create, edit, or clone Amazon EC2 node templates. This requirement was removed in v2.4.8.
|
||||
Upgrading to v2.3.0+ | Any user provisioned cluster will be automatically updated upon any edit as tolerations were added to the images used for Kubernetes provisioning.
|
||||
Upgrading to v2.2.0-v2.2.x | Rancher introduced the [system charts](https://github.com/rancher/system-charts) repository which contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. To be able to use these features in an air gap install, you will need to mirror the `system-charts` repository locally and configure Rancher to use that repository. Please follow the instructions to [configure Rancher system charts]({{<baseurl>}}/rancher/v2.x/en/installation/resources/local-system-charts/#setting-up-system-charts-for-rancher-prior-to-v2-3-0).
|
||||
Upgrading from v2.0.13 or earlier | If your cluster's certificates have expired, you will need to perform [additional steps]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/certificate-rotation/#rotating-expired-certificates-after-upgrading-older-rancher-versions) to rotate the certificates.
|
||||
Upgrading from v2.0.7 or earlier | Rancher introduced the `system` project, which is a project that's automatically created to store important namespaces that Kubernetes needs to operate. During upgrade to v2.0.7+, Rancher expects these namespaces to be unassigned from all projects. Before beginning upgrade, check your system namespaces to make sure that they're unassigned to [prevent cluster networking issues]({{<baseurl>}}/rancher/v2.x/en/upgrades/upgrades/namespace-migration/#preventing-cluster-networking-issues).
|
||||
|
||||
# RKE Add-on Installs
|
||||
|
||||
**Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
|
||||
Please use the Rancher helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install - Installation Outline]({{<baseurl>}}/rancher/v2.x/en/installation/install-rancher-on-k8s/#installation-outline).
|
||||
|
||||
If you are currently using the RKE add-on install method, see [Migrating from a RKE add-on install]({{<baseurl>}}/rancher/v2.x/en/upgrades/upgrades/migrating-from-rke-add-on/) for details on how to move to using the helm chart.
|
||||
+3
@@ -4,6 +4,9 @@ weight: 1050
|
||||
aliases:
|
||||
- /rancher/v2.x/en/upgrades/upgrades/ha/helm2
|
||||
- /rancher/v2.x/en/upgrades/helm2
|
||||
- /rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/ha/helm2
|
||||
- /rancher/v2.x/en/installation/install-rancher-on-k8s/upgrades-rollbacks/upgrades/ha/helm2
|
||||
- /rancher/v2.x/en/installation/install-rancher-on-k8s/upgrades-rollbacks/upgrades/helm2
|
||||
---
|
||||
|
||||
> Helm 3 has been released. If you are using Helm 2, we recommend [migrating to Helm 3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) because it is simpler to use and more secure than Helm 2.
|
||||
+2
@@ -5,6 +5,8 @@ aliases:
|
||||
- /rancher/v2.x/en/upgrades/ha-server-upgrade/
|
||||
- /rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/
|
||||
- /rancher/v2.x/en/upgrades/upgrades/migrating-from-rke-add-on
|
||||
- /rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/migrating-from-rke-add-on
|
||||
- /rancher/v2.x/en/installation/install-rancher-on-k8s/upgrades-rollbacks/upgrades/migrating-from-rke-add-on
|
||||
---
|
||||
|
||||
> **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
+2
@@ -3,6 +3,8 @@ title: Upgrading to v2.0.7+ — Namespace Migration
|
||||
weight: 1040
|
||||
aliases:
|
||||
- /rancher/v2.x/en/upgrades/upgrades/namespace-migration
|
||||
- /rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/namespace-migration
|
||||
- /rancher/v2.x/en/installation/install-rancher-on-k8s/upgrades-rollbacks/upgrades/namespace-migration
|
||||
---
|
||||
>This section applies only to Rancher upgrades from v2.0.6 or earlier to v2.0.7 or later. Upgrades from v2.0.7 to later version are unaffected.
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
title: Rollbacks
|
||||
weight: 3
|
||||
---
|
||||
|
||||
To roll back Rancher to a previous version, re-run the installation script with the previous version specified in the `INSTALL_RANCHERD_VERSION` environment variable.
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Upgrades and Rollbacks
|
||||
weight:
|
||||
title: Upgrades
|
||||
weight: 2
|
||||
---
|
||||
|
||||
When RancherD is upgraded, the Rancher Helm controller and the Fleet pods are upgraded.
|
||||
@@ -37,8 +37,6 @@ To upgrade Rancher without upgrading the underlying Kubernetes cluster, follow t
|
||||
|
||||
If necessary, restore Rancher from backup by following [these steps.]({{<baseurl>}}/rancher/v2.x/en/backups/v2.5/restoring-rancher/)
|
||||
|
||||
To roll back Rancher to a previous version, uninstall the Helm chart and reinstall the Helm chart for the previous version.
|
||||
|
||||
### Upgrading Both Rancher and the Underlying Cluster
|
||||
|
||||
Upgrade both RancherD and the underlying Kubernetes cluster by re-running the RancherD installation script.
|
||||
@@ -67,4 +65,4 @@ systemctl start rancherd-server
|
||||
|
||||
The upgrade can also be performed by manually installing the binary of the desired version.
|
||||
|
||||
To roll back Rancher to a previous version, re-run the installation script with the previous version specified in the `INSTALL_RANCHERD_VERSION` environment variable.
|
||||
|
||||
|
||||
+3
-2
@@ -3,6 +3,7 @@ title: About Custom CA Root Certificates
|
||||
weight: 1
|
||||
aliases:
|
||||
- /rancher/v2.x/en/installation/options/custom-ca-root-certificate/
|
||||
- /rancher/v2.x/en/installation/resources/choosing-version/encryption/custom-ca-root-certificate
|
||||
---
|
||||
|
||||
If you're using Rancher in an internal production environment where you aren't exposing apps publicly, use a certificate from a private certificate authority (CA).
|
||||
@@ -21,7 +22,7 @@ Examples of services that Rancher can access:
|
||||
|
||||
For details on starting a Rancher container with your private CA certificates mounted, refer to the installation docs:
|
||||
|
||||
- [Docker Install]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/advanced/#custom-ca-certificate)
|
||||
- [Docker install Custom CA certificate options]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/advanced/#custom-ca-certificate)
|
||||
|
||||
- [Kubernetes Install]({{<baseurl>}}/rancher/v2.x/en/installation/resources/chart-options/#additional-trusted-cas)
|
||||
- [Kubernetes install options for Additional Trusted CAs]({{<baseurl>}}/rancher/v2.x/en/installation/install-rancher-on-k8s/chart-options/#additional-trusted-cas)
|
||||
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
title: Encryption
|
||||
weight: 3
|
||||
---
|
||||
|
||||
The documents in this section contain information about certificate configuration and `cert-manager`.
|
||||
+1
@@ -3,6 +3,7 @@ title: Adding TLS Secrets
|
||||
weight: 2
|
||||
aliases:
|
||||
- /rancher/v2.x/en/installation/options/tls-secrets/
|
||||
- /rancher/v2.x/en/installation/resources/encryption/tls-secrets
|
||||
---
|
||||
|
||||
Kubernetes will create all the objects and services for Rancher, but it will not become available until we populate the `tls-rancher-ingress` secret in the `cattle-system` namespace with the certificate and key.
|
||||
+6
-5
@@ -4,19 +4,20 @@ weight: 3
|
||||
aliases:
|
||||
- /rancher/v2.x/en/installation/options/tls-settings/
|
||||
- /rancher/v2.x/en/admin-settings/tls-settings
|
||||
- /rancher/v2.x/en/installation/resources/encryption/tls-settings
|
||||
---
|
||||
|
||||
In Rancher v2.1.7, the default TLS configuration changed to only accept TLS 1.2 and secure TLS cipher suites. TLS 1.3 and TLS 1.3 exclusive cipher suites are not supported.
|
||||
|
||||
## Configuring TLS settings
|
||||
# Configuring TLS settings
|
||||
|
||||
The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation.
|
||||
|
||||
- [Installing Rancher on a single node with Docker]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/advanced/#tls-settings)
|
||||
- [TLS settings in Docker options]({{<baseurl>}}/v2.x/en/installation/other-installation-methods/single-node-docker/advanced/#tls-settings)
|
||||
|
||||
- [Installing Rancher on Kubernetes]({{<baseurl>}}/rancher/v2.x/en/installation/resources/chart-options/#tls-settings)
|
||||
- [TLS settings in Helm chart options]({{<baseurl>}}/rancher/v2.x/en/installation/install-rancher-on-k8s/chart-options/#tls-settings)
|
||||
|
||||
## TLS settings
|
||||
# TLS Environment Variables
|
||||
|
||||
| Parameter | Description | Default | Available options |
|
||||
|-----|-----|-----|-----|
|
||||
@@ -24,7 +25,7 @@ The Audit Log is enabled and configured by passing environment variables to the
|
||||
| `CATTLE_TLS_CIPHERS` | Allowed TLS cipher suites | `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,`<br/>`TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,`<br/>`TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,`<br/>`TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,`<br/>`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,`<br/>`TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305` | See [Golang tls constants](https://golang.org/pkg/crypto/tls/#pkg-constants) |
|
||||
|
||||
|
||||
## Legacy configuration
|
||||
# Legacy configuration
|
||||
|
||||
If you need to configure TLS the same way as it was before Rancher v2.1.7, please use the following settings:
|
||||
|
||||
+1
@@ -4,6 +4,7 @@ weight: 4
|
||||
aliases:
|
||||
- /rancher/v2.x/en/installation/options/upgrading-cert-manager
|
||||
- /rancher/v2.x/en/installation/options/upgrading-cert-manager/helm-2-instructions
|
||||
- /rancher/v2.x/en/installation/resources/encryption/upgrading-cert-manager
|
||||
---
|
||||
|
||||
Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, three important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher:
|
||||
+1
@@ -3,6 +3,7 @@ title: Upgrading Cert-Manager with Helm 2
|
||||
weight: 2040
|
||||
aliases:
|
||||
- /rancher/v2.x/en/installation/options/upgrading-cert-manager/helm-2-instructions
|
||||
- /rancher/v2.x/en/installation/resources/choosing-version/encryption/upgrading-cert-manager/helm-2-instructions
|
||||
---
|
||||
|
||||
Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, three important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher:
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
title: Upgrades and Rollbacks
|
||||
weight: 150
|
||||
aliases:
|
||||
- /rancher/v2.x/en/upgrades
|
||||
---
|
||||
|
||||
### Upgrading Rancher
|
||||
|
||||
To upgrade Rancher, refer to [these instructions.](./upgrades/)
|
||||
|
||||
### Rolling Back Unsuccessful Upgrades
|
||||
|
||||
In the event that your Rancher Server does not upgrade successfully, you can rollback to your installation prior to upgrade using these instructions: [Rollbacks for Rancher installed on a Kubernetes cluster](./rollbacks/ha-server-rollbacks)
|
||||
|
||||
> **Note:** If you are rolling back to versions in either of these scenarios, you must follow some extra [instructions]({{<baseurl>}}/rancher/v2.x/en/upgrades/rollbacks/) in order to get your clusters working.
|
||||
>
|
||||
>- Rolling back from v2.1.6+ to any version between v2.1.0 - v2.1.5 or v2.0.0 - v2.0.10.
|
||||
>- Rolling back from v2.0.11+ to any version between v2.0.0 - v2.0.10.
|
||||
-17
@@ -1,17 +0,0 @@
|
||||
---
|
||||
title: Kubernetes Rollback
|
||||
weight: 1025
|
||||
aliases:
|
||||
- /rancher/v2.x/en/upgrades/ha-server-rollbacks
|
||||
- /rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks
|
||||
---
|
||||
|
||||
If you upgrade Rancher and the upgrade does not complete successfully, you may need to rollback your Rancher Server to its last healthy state.
|
||||
|
||||
To restore Rancher prior to v2.5, follow the procedure detailed here: [Restoring Backups — Kubernetes installs]({{<baseurl>}}/rancher/v2.x/en/backups/restorations/ha-restoration)
|
||||
|
||||
To restore Rancher v2.5, you can use the `rancher-backup` application and restore Rancher from backup according to [this section.]({{<baseurl>}}/rancher/v2.x/en/backups/restoring-rancher/)
|
||||
|
||||
Restoring a snapshot of the Rancher Server cluster will revert Rancher to the version and state at the time of the snapshot.
|
||||
|
||||
>**Note:** Managed cluster are authoritative for their state. This means restoring the rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken.
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
title: Upgrades
|
||||
weight: 1005
|
||||
aliases:
|
||||
- /rancher/v2.x/en/upgrades/upgrades
|
||||
---
|
||||
This section contains information about how to upgrade your Rancher server to a newer version. Regardless if you installed in an air gap environment or not, the upgrade steps mainly depend on whether you have a single node or high-availability installation of Rancher. Select from the following options:
|
||||
|
||||
- [Upgrading Rancher installed with Docker]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-upgrades)
|
||||
- [Upgrading Rancher installed on a Kubernetes cluster]({{<baseurl>}}/rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/ha/)
|
||||
|
||||
### Known Upgrade Issues
|
||||
|
||||
The following table lists some of the most noteworthy issues to be considered when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
|
||||
|
||||
Upgrade Scenario | Issue
|
||||
---|---
|
||||
Upgrading to v2.4.6 or v2.4.7 | These Rancher versions had an issue where the `kms:ListKeys` permission was required to create, edit, or clone Amazon EC2 node templates. This requirement was removed in v2.4.8.
|
||||
Upgrading to v2.3.0+ | Any user provisioned cluster will be automatically updated upon any edit as tolerations were added to the images used for Kubernetes provisioning.
|
||||
Upgrading to v2.2.0-v2.2.x | Rancher introduced the [system charts](https://github.com/rancher/system-charts) repository which contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. To be able to use these features in an air gap install, you will need to mirror the `system-charts` repository locally and configure Rancher to use that repository. Please follow the instructions to [configure Rancher system charts]({{<baseurl>}}/rancher/v2.x/en/installation/resources/local-system-charts/#setting-up-system-charts-for-rancher-prior-to-v2-3-0).
|
||||
Upgrading from v2.0.13 or earlier | If your cluster's certificates have expired, you will need to perform [additional steps]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/certificate-rotation/#rotating-expired-certificates-after-upgrading-older-rancher-versions) to rotate the certificates.
|
||||
Upgrading from v2.0.7 or earlier | Rancher introduced the `system` project, which is a project that's automatically created to store important namespaces that Kubernetes needs to operate. During upgrade to v2.0.7+, Rancher expects these namespaces to be unassigned from all projects. Before beginning upgrade, check your system namespaces to make sure that they're unassigned to [prevent cluster networking issues]({{<baseurl>}}/rancher/v2.x/en/upgrades/upgrades/namespace-migration/#preventing-cluster-networking-issues).
|
||||
|
||||
### Caveats
|
||||
Upgrades _to_ or _from_ any chart in the [rancher-alpha repository]({{<baseurl>}}/rancher/v2.x/en/installation/resources/chart-options/#helm-chart-repositories/) aren't supported.
|
||||
|
||||
### RKE Add-on Installs
|
||||
|
||||
**Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
|
||||
Please use the Rancher helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install - Installation Outline]({{<baseurl>}}/rancher/v2.x/en/installation/install-rancher-on-k8s/#installation-outline).
|
||||
|
||||
If you are currently using the RKE add-on install method, see [Migrating from a RKE add-on install]({{<baseurl>}}/rancher/v2.x/en/upgrades/upgrades/migrating-from-rke-add-on/) for details on how to move to using the helm chart.
|
||||
@@ -1,231 +0,0 @@
|
||||
---
|
||||
title: Upgrading Rancher Installed on Kubernetes
|
||||
weight: 1020
|
||||
aliases:
|
||||
- /rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade-helm-airgap
|
||||
- /rancher/v2.x/en/upgrades/air-gap-upgrade/
|
||||
- /rancher/v2.x/en/upgrades/upgrades/ha
|
||||
- /rancher/v2.x/en/installation/install-rancher-on-k8s/upgrades/upgrades/ha
|
||||
- /rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/
|
||||
- /rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade-helm/
|
||||
---
|
||||
|
||||
The following instructions will guide you through using Helm to upgrade a Rancher server that was installed on a Kubernetes cluster.
|
||||
|
||||
To upgrade the components in your Kubernetes cluster, or the definition of the [Kubernetes services]({{<baseurl>}}/rke/latest/en/config-options/services/) or [add-ons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/), refer to the [upgrade documentation for RKE]({{<baseurl>}}/rke/latest/en/upgrades/), the Rancher Kubernetes Engine.
|
||||
|
||||
If you installed Rancher using the RKE Add-on yaml, follow the directions to [migrate or upgrade]({{<baseurl>}}/rancher/v2.x/en/upgrades/upgrades/migrating-from-rke-add-on).
|
||||
|
||||
>**Notes:**
|
||||
>
|
||||
> - If you are upgrading to Rancher v2.5 from a Rancher server that was started with the Helm chart option `--add-local=false`, you will need to drop that flag when upgrading. Otherwise, the Rancher server will not start. The `restricted-admin` role can be used to continue restricting access to the local cluster. For more information, see [this section.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#upgrading-from-rancher-with-a-hidden-local-cluster)
|
||||
> - [Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) Upgrade cert-manager to the latest version by following [these instructions.]({{<baseurl>}}/rancher/v2.x/en/installation/options/upgrading-cert-manager)
|
||||
> - Helm should be run from the same location as your kubeconfig file (where you run your kubectl commands from. If you installed K8s with RKE, the config will have been created in the directory you ran `rke up` in) or should manually target the kubeconfig for the intended cluster with the `--kubeconfig` tag (see: https://helm.sh/docs/helm/helm/)
|
||||
> - The upgrade instructions assume you are using Helm 3. For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) The [Helm 2 upgrade page here]({{<baseurl>}}/rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/ha/helm2)provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
> - If you are upgrading Rancher from v2.x to v2.3+, and you are using external TLS termination, you will need to edit the cluster.yml to [enable using forwarded host headers.]({{<baseurl>}}/rancher/v2.x/en/installation/resources/chart-options/#configuring-ingress-for-external-tls-when-using-nginx-v0-25)
|
||||
|
||||
# Prerequisites
|
||||
|
||||
- **Review the [known upgrade issues]({{<baseurl>}}/rancher/v2.x/en/upgrades/upgrades/#known-upgrade-issues) and [caveats]({{<baseurl>}}/rancher/v2.x/en/upgrades/upgrades/#caveats)** in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
|
||||
- **For [air gap installs only,]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/air-gap) collect and populate images for the new Rancher server version.** Follow the guide to [populate your private registry]({{<baseurl>}}/rancher/v2.x/en/installation/other-installation-methods/air-gap/populate-private-registry/) with the images for the Rancher version that you want to upgrade to.
|
||||
|
||||
# Upgrade Outline
|
||||
|
||||
Follow the steps to upgrade Rancher server:
|
||||
|
||||
- [A. Back up your Kubernetes cluster that is running Rancher server](#a-back-up-your-kubernetes-cluster-that-is-running-rancher-server)
|
||||
- [B. Update the Helm chart repository](#b-update-the-helm-chart-repository)
|
||||
- [C. Upgrade Rancher](#c-upgrade-rancher)
|
||||
- [D. Verify the Upgrade](#d-verify-the-upgrade)
|
||||
|
||||
### A. Back up Your Kubernetes Cluster that is Running Rancher Server
|
||||
|
||||
[Take a one-time snapshot]({{<baseurl>}}/rancher/v2.x/en/backups/backups/ha-backups/#option-b-one-time-snapshots)
|
||||
of your Kubernetes cluster running Rancher server. You'll use the snapshot as a restoration point if something goes wrong during upgrade.
|
||||
|
||||
### B. Update the Helm chart repository
|
||||
|
||||
1. Update your local helm repo cache.
|
||||
|
||||
```
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Get the repository name that you used to install Rancher.
|
||||
|
||||
For information about the repos and their differences, see [Helm Chart Repositories]({{<baseurl>}}/rancher/v2.x/en/installation/resources/chart-options/#helm-chart-repositories).
|
||||
|
||||
{{< release-channel >}}
|
||||
|
||||
```
|
||||
helm repo list
|
||||
|
||||
NAME URL
|
||||
stable https://kubernetes-charts.storage.googleapis.com
|
||||
rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>
|
||||
```
|
||||
|
||||
> **Note:** If you want to switch to a different Helm chart repository, please follow the [steps on how to switch repositories]({{<baseurl>}}/rancher/v2.x/en/installation/resources/chart-options/#switching-to-a-different-helm-chart-repository). If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added.
|
||||
|
||||
|
||||
1. Fetch the latest chart to install Rancher from the Helm chart repository.
|
||||
|
||||
This command will pull down the latest charts and save it in the current directory as a `.tgz` file.
|
||||
|
||||
```plain
|
||||
helm fetch rancher-<CHART_REPO>/rancher
|
||||
```
|
||||
You can fetch the chart for the specific version you are upgrading to by adding in the `--version=` tag. For example:
|
||||
|
||||
```plain
|
||||
helm fetch rancher-<CHART_REPO>/rancher --version=v2.4.11
|
||||
```
|
||||
|
||||
### C. Upgrade Rancher
|
||||
|
||||
This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.
|
||||
|
||||
{{% tabs %}}
|
||||
{{% tab "Kubernetes Upgrade" %}}
|
||||
|
||||
Get the values, which were passed with `--set`, from the current Rancher Helm chart that is installed.
|
||||
|
||||
```
|
||||
helm get values rancher -n cattle-system
|
||||
|
||||
hostname: rancher.my.org
|
||||
```
|
||||
|
||||
> **Note:** There will be more values that are listed with this command. This is just an example of one of the values.
|
||||
|
||||
If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow `Option B: Reinstalling Rancher and cert-manager`. Otherwise, follow `Option A: Upgrading Rancher`.
|
||||
|
||||
{{% accordion label="Option A: Upgrading Rancher" %}}
|
||||
|
||||
Upgrade Rancher to the latest version with all your settings.
|
||||
|
||||
Take all the values from the previous step and append them to the command using `--set key=value`:
|
||||
|
||||
```
|
||||
helm upgrade rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
> **Note:** The above is an example, there may be more values from the previous step that need to be appended.
|
||||
|
||||
Alternatively, it's possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version:
|
||||
|
||||
```
|
||||
helm get values rancher -n cattle-system -o yaml > values.yaml
|
||||
|
||||
helm upgrade rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
-f values.yaml \
|
||||
--version=2.4.5
|
||||
```
|
||||
|
||||
{{% /accordion %}}
|
||||
|
||||
{{% accordion label="Option B: Reinstalling Rancher and cert-manager" %}}
|
||||
|
||||
If you are currently running the cert-manger whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, then you need to reinstall both Rancher and cert-manger due to the API change in cert-manger v0.11.
|
||||
|
||||
1. Uninstall Rancher
|
||||
|
||||
```
|
||||
helm delete rancher -n cattle-system
|
||||
```
|
||||
|
||||
2. Uninstall and reinstall `cert-manager` according to the instructions on the [Upgrading Cert-Manager]({{<baseurl>}}/rancher/v2.x/en/installation/options/upgrading-cert-manager) page.
|
||||
|
||||
3. Reinstall Rancher to the latest version with all your settings. Take all the values from the step 1 and append them to the command using `--set key=value`. Note: There will be many more options from the step 1 that need to be appended.
|
||||
|
||||
```
|
||||
helm install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
{{% /accordion %}}
|
||||
|
||||
{{% /tab %}}
|
||||
|
||||
{{% tab "Kubernetes Air Gap Upgrade" %}}
|
||||
|
||||
1. Render the Rancher template using the same chosen options that were used when installing Rancher. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.
|
||||
|
||||
Based on the choice you made during installation, complete one of the procedures below.
|
||||
|
||||
Placeholder | Description
|
||||
------------|-------------
|
||||
`<VERSION>` | The version number of the output tarball.
|
||||
`<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer.
|
||||
`<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.
|
||||
`<CERTMANAGER_VERSION>` | Cert-manager version running on k8s cluster.
|
||||
|
||||
{{% accordion id="self-signed" label="Option A-Default Self-Signed Certificate" %}}
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set certmanager.version=<CERTMANAGER_VERSION> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
{{% /accordion %}}
|
||||
{{% accordion id="secret" label="Option B: Certificates From Files using Kubernetes Secrets" %}}
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`:
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set privateCA=true \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
{{% /accordion %}}
|
||||
|
||||
2. Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates.
|
||||
|
||||
Use `kubectl` to apply the rendered manifests.
|
||||
|
||||
```plain
|
||||
kubectl -n cattle-system apply -R -f ./rancher
|
||||
```
|
||||
|
||||
{{% /tab %}}
|
||||
{{% /tabs %}}
|
||||
|
||||
### D. Verify the Upgrade
|
||||
|
||||
Log into Rancher to confirm that the upgrade succeeded.
|
||||
|
||||
>**Having network issues following upgrade?**
|
||||
>
|
||||
> See [Restoring Cluster Networking]({{<baseurl>}}/rancher/v2.x/en/upgrades/upgrades/namespace-migration/#restoring-cluster-networking).
|
||||
|
||||
## Rolling Back
|
||||
|
||||
Should something go wrong, follow the [roll back]({{<baseurl>}}/rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks/) instructions to restore the snapshot you took before you preformed the upgrade.
|
||||
@@ -1,15 +0,0 @@
|
||||
<div>
|
||||
<ul>
|
||||
<li>
|
||||
<p>Rancher Kubernetes Engine v0.1.7 or later</p>
|
||||
<p>The commands for taking <code>etcd</code> snapshots are only available in RKE v0.1.7 and later.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code>rancher-cluster.yml</code></p>
|
||||
<p>You'll need the RKE config file that you used for Rancher install, <code>rancher-cluster.yml</code>. You created this file during your initial install. Place this file in same directory as the RKE binary.</p>
|
||||
</li>
|
||||
<li>
|
||||
You must restore each of your <code>etcd</code> nodes to the <i>same</i> snapshot. Copy the snapshot you're using from one of your nodes to the others before running the <code>etcd snapshot-restore</code> command.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
Reference in New Issue
Block a user