diff --git a/content/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher/_index.md b/content/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher/_index.md index 80281d3e061..f8096d2c2cf 100644 --- a/content/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/other-installation-methods/air-gap/install-rancher/_index.md @@ -12,6 +12,10 @@ This section is about how to deploy Rancher for your air gapped environment. An > **Note:** These installation 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/) This [section]({{}}/rancher/v2.x/en/installation/options/air-gap-helm2) provides a copy of the older air gap installation instructions for Rancher installed on Kubernetes with Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible. +### Privileged Access for Rancher v2.5+ + +When the Rancher server is deployed in the Docker container, a local Kubernetes cluster is installed within the container, then Rancher is deployed on the cluster. Because privileged access is required to run containers within containers, you will need to install Rancher with the `--privileged` option in order to access many features of Rancher, including deploying pods on the local Kubernetes cluster. + {{% tabs %}} {{% tab "Kubernetes Install (Recommended)" %}} @@ -252,11 +256,14 @@ Log into your Linux host, and then run the installation command below. When ente | `` | Your private registry URL and port. | | `` | The release tag of the [Rancher version]({{}}/rancher/v2.x/en/installation/options/server-tags/) that you want to install. | +As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) + ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher -e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts + --privileged \ /rancher/rancher: ``` @@ -282,6 +289,8 @@ After creating your certificate, log into your Linux host, and then run the inst | `` | Your private registry URL and port. | | `` | The release tag of the [Rancher version]({{}}/rancher/v2.x/en/installation/options/server-tags/) that you want to install. | +As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) + ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ @@ -290,6 +299,7 @@ docker run -d --restart=unless-stopped \ -v //:/etc/rancher/ssl/cacerts.pem \ -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher -e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts + --privileged \ /rancher/rancher: ``` @@ -312,6 +322,8 @@ After obtaining your certificate, log into your Linux host, and then run the ins > **Note:** Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. +As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) + ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ @@ -320,6 +332,7 @@ docker run -d --restart=unless-stopped \ -v //:/etc/rancher/ssl/key.pem \ -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher -e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts + --privileged /rancher/rancher: ``` diff --git a/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/_index.md b/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/_index.md index 56890fe07da..35e2c65a748 100644 --- a/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/_index.md +++ b/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/_index.md @@ -17,6 +17,10 @@ In this installation scenario, you'll install Docker on a single Linux host, and > **Want to use an external load balancer?** > See [Docker Install with an External Load Balancer]({{}}/rancher/v2.x/en/installation/options/single-node-install-external-lb) instead. +### Privileged Access for Rancher v2.5+ + +When the Rancher server is deployed in the Docker container, a local Kubernetes cluster is installed within the container, then Rancher is deployed on the cluster. Because privileged access is required to run containers within containers, you will need to install Rancher with the `--privileged` option in order to access many features of Rancher, including deploying pods on the local Kubernetes cluster. + # Requirements for OS, Docker, Hardware, and Networking Make sure that your node fulfills the general [installation requirements.]({{}}/rancher/v2.x/en/installation/requirements/) @@ -44,9 +48,12 @@ If you are installing Rancher in a development or testing environment where iden Log into your Linux host, and then run the minimum installation command below. +As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) + ```bash docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ + --privileged \ rancher/rancher:latest ``` @@ -68,12 +75,15 @@ After creating your certificate, run the Docker command below to install Rancher | `` | The path to the private key for your certificate. | | `` | The path to the certificate authority's certificate. | +As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) + ```bash docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ -v //:/etc/rancher/ssl/cert.pem \ -v //:/etc/rancher/ssl/key.pem \ -v //:/etc/rancher/ssl/cacerts.pem \ + --privileged \ rancher/rancher:latest ``` @@ -97,12 +107,15 @@ After obtaining your certificate, run the Docker command below. | `` | The path to your full certificate chain. | | `` | The path to the private key for your certificate. | +As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) + ```bash docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ -v //:/etc/rancher/ssl/cert.pem \ -v //:/etc/rancher/ssl/key.pem \ rancher/rancher:latest \ + --privileged \ --no-cacerts ``` @@ -124,10 +137,13 @@ After you fulfill the prerequisites, you can install Rancher using a Let's Encry | ----------------- | ------------------- | | `` | Your domain address | +As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) + ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ rancher/rancher:latest \ + --privileged \ --acme-domain ``` diff --git a/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/advanced/_index.md b/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/advanced/_index.md index 3aa2362b502..8eefb2db503 100644 --- a/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/advanced/_index.md +++ b/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/advanced/_index.md @@ -25,11 +25,14 @@ Use the command example to start a Rancher container with your private CA certif The example below is based on having the CA root certificates in the `/host/certs` directory on the host and mounting this directory on `/container/certs` inside the Rancher container. +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) + ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ -v /host/certs:/container/certs \ -e SSL_CERT_DIR="/container/certs" \ + --privileged \ rancher/rancher:latest ``` @@ -41,11 +44,14 @@ The API Audit Log writes to `/var/log/auditlog` inside the rancher container by See [API Audit Log]({{}}/rancher/v2.x/en/installation/api-auditing) for more information and options. +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) + ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ -v /var/log/rancher/auditlog:/var/log/auditlog \ -e AUDIT_LEVEL=1 \ + --privileged \ rancher/rancher:latest ``` @@ -59,9 +65,12 @@ To set a different TLS configuration, you can use the `CATTLE_TLS_MIN_VERSION` a docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ -e CATTLE_TLS_MIN_VERSION="1.0" \ + --privileged \ rancher/rancher:latest ``` +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) + See [TLS settings]({{}}/rancher/v2.x/en/admin-settings/tls-settings) for more information and options. ### Air Gap @@ -89,5 +98,8 @@ To change the host ports mapping, replace the following part `-p 80:80 -p 443:44 ``` docker run -d --restart=unless-stopped \ -p 8080:80 -p 8443:443 \ + --privileged \ rancher/rancher:latest ``` + +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) diff --git a/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/proxy/_index.md b/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/proxy/_index.md index da3e4484bfe..100acc4f282 100644 --- a/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/proxy/_index.md +++ b/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/proxy/_index.md @@ -35,5 +35,8 @@ docker run -d --restart=unless-stopped \ -e HTTP_PROXY="http://192.168.10.1:3128" \ -e HTTPS_PROXY="http://192.168.10.1:3128" \ -e NO_PROXY="localhost,127.0.0.1,0.0.0.0,10.0.0.0/8,192.168.10.0/24,example.com" \ + --privileged \ rancher/rancher:latest ``` + +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) diff --git a/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/_index.md b/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/_index.md index c74ccc9c9bb..c87b0571c8b 100644 --- a/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/_index.md +++ b/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/_index.md @@ -74,8 +74,13 @@ If you have issues upgrading Rancher, roll it back to its latest known healthy s 1. Start a new Rancher Server container with the `` tag [placeholder](#before-you-start) pointing to the data container. ``` docker run -d --volumes-from rancher-data \ - --restart=unless-stopped -p 80:80 -p 443:443 rancher/rancher: + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher: ``` + As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) + >**Note:** _Do not_ stop the rollback after initiating it, even if the rollback process seems longer than expected. Stopping the rollback may result in database issues during future upgrades. 1. Wait a few moments and then open Rancher in a web browser. Confirm that the rollback succeeded and that your data is restored. diff --git a/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/_index.md b/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/_index.md index ad2babc1fb7..ec0e0c6236f 100644 --- a/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/_index.md +++ b/content/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/_index.md @@ -136,9 +136,12 @@ Placeholder | Description docker run -d --volumes-from rancher-data \ --restart=unless-stopped \ -p 80:80 -p 443:443 \ + --privileged \ rancher/rancher: ``` +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) + {{% /accordion %}} {{% accordion id="option-b" label="Option B-Bring Your Own Certificate: Self-Signed" %}} @@ -162,9 +165,12 @@ docker run -d --volumes-from rancher-data \ - //:/etc/rancher/ssl/cert.pem \ - //:/etc/rancher/ssl/key.pem \ - //:/etc/rancher/ssl/cacerts.pem \ + --privileged rancher/rancher: ``` +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) + {{% /accordion %}} {{% accordion id="option-c" label="Option C-Bring Your Own Certificate: Signed by Recognized CA" %}} @@ -186,8 +192,11 @@ docker run -d --volumes-from rancher-data \ - //:/etc/rancher/ssl/cert.pem \ - //:/etc/rancher/ssl/key.pem \ rancher/rancher: \ + --privileged \ --no-cacerts ``` + +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) {{% /accordion %}} {{% accordion id="option-d" label="Option D-Let's Encrypt Certificate" %}} @@ -209,10 +218,13 @@ Placeholder | Description docker run -d --volumes-from rancher-data \ --restart=unless-stopped \ -p 80:80 -p 443:443 \ + --privileged \ rancher/rancher: \ --acme-domain ``` +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) + {{% /accordion %}} {{% /tab %}} @@ -239,8 +251,11 @@ Placeholder | Description -p 80:80 -p 443:443 \ -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher -e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts + --privileged \ /rancher/rancher: ``` + +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) {{% /accordion %}} {{% accordion id="option-b" label="Option B-Bring Your Own Certificate: Self-Signed" %}} @@ -266,8 +281,10 @@ docker run -d --restart=unless-stopped \ -v //:/etc/rancher/ssl/cacerts.pem \ -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher -e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts + --privileged \ /rancher/rancher: ``` +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) {{% /accordion %}} {{% accordion id="option-c" label="Option C-Bring Your Own Certificate: Signed by Recognized CA" %}} @@ -295,8 +312,10 @@ docker run -d --volumes-from rancher-data \ -v //:/etc/rancher/ssl/key.pem \ -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher -e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts + --privileged /rancher/rancher: ``` +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) {{% /accordion %}} {{% /tab %}} {{% /tabs %}} diff --git a/content/rancher/v2.x/en/quick-start-guide/deployment/quickstart-manual-setup/_index.md b/content/rancher/v2.x/en/quick-start-guide/deployment/quickstart-manual-setup/_index.md index b4c2457eeaa..f0ee9913026 100644 --- a/content/rancher/v2.x/en/quick-start-guide/deployment/quickstart-manual-setup/_index.md +++ b/content/rancher/v2.x/en/quick-start-guide/deployment/quickstart-manual-setup/_index.md @@ -49,7 +49,7 @@ To install Rancher on your host, connect to it and then use a shell to install. 2. From your shell, enter the following command: ``` -sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 rancher/rancher +sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 --privileged rancher/rancher ``` **Result:** Rancher is installed. diff --git a/content/rancher/v2.x/en/upgrades/upgrades/single-node/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/single-node/_index.md new file mode 100644 index 00000000000..5ec2e0fe082 --- /dev/null +++ b/content/rancher/v2.x/en/upgrades/upgrades/single-node/_index.md @@ -0,0 +1,332 @@ +--- +title: Upgrading Rancher Installed with Docker +weight: 1010 +aliases: + - /rancher/v2.x/en/upgrades/single-node-upgrade/ + - /rancher/v2.x/en/upgrades/upgrades/single-node-air-gap-upgrade +--- + +The following instructions will guide you through upgrading a Rancher server that was installed with Docker. + +# Prerequisites + +- **Review the [known upgrade issues]({{}}/rancher/v2.x/en/upgrades/upgrades/#known-upgrade-issues) and [caveats]({{}}/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,]({{}}/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]({{}}/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. + +# Placeholder Review + +During upgrade, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (``). + +Here's an **example** of a command with a placeholder: + +``` +docker stop +``` + +In this command, `` is the name of your Rancher container. + +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 upgrade. + +Terminal `docker ps` Command, Displaying Where to Find `` and `` +![Placeholder Reference]({{}}/img/rancher/placeholder-ref.png) + +| Placeholder | Example | Description | +| -------------------------- | -------------------------- | --------------------------------------------------------- | +| `` | `v2.1.3` | The rancher/rancher image you pulled for initial install. | +| `` | `festive_mestorf` | The name of your Rancher container. | +| `` | `v2.1.3` | The version of Rancher that you're creating a backup for. | +| `` | `2018-12-19` | The date that the data container or backup was created. | +
+ +You can obtain `` and `` 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 using a different command: `docker ps -a`. Use these commands for help anytime during while creating backups. + +# Upgrade Outline + +During upgrade, you create a copy of the data from your current Rancher container and a backup in case something goes wrong. Then you deploy the new version of Rancher in a new container using your existing data. Follow the steps to upgrade Rancher server: + +- [A. Create a copy of the data from your Rancher server container](#a-create-a-copy-of-the-data-from-your-rancher-server-container) +- [B. Create a backup tarball](#b-create-a-backup-tarball) +- [C. Pull the new Docker image](#c-pull-the-new-docker-image) +- [D. Start the new Rancher server container](#d-start-the-new-rancher-server-container) +- [E. Verify the Upgrade](#e-verify-the-upgrade) +- [F. Clean up your old Rancher server container](#f-clean-up-your-old-rancher-server-container) + +### A. Create a copy of the data from your Rancher server container + +1. Using a remote Terminal connection, log into the node running your Rancher server. + +1. Stop the container currently running Rancher server. Replace `` with the name of your Rancher container. + + ``` + docker stop + ``` + +1. Use the command below, replacing each placeholder, to create a data container from the Rancher container that you just stopped. + + ``` + docker create --volumes-from --name rancher-data rancher/rancher: + ``` + +### B. Create a backup tarball + +1. From the data container that you just created (`rancher-data`), create a backup tarball (`rancher-data-backup--.tar.gz`). + + This tarball will serve as a rollback point if something goes wrong during upgrade. Use the following command, replacing each [placeholder](#before-you-start). + + + ``` + docker run --volumes-from rancher-data -v $PWD:/backup busybox tar zcvf /backup/rancher-data-backup--.tar.gz /var/lib/rancher + ``` + + **Step Result:** When you enter this command, a series of commands should run. + +1. Enter the `ls` command to confirm that the backup tarball was created. It will have a name similar to `rancher-data-backup--.tar.gz`. + + ``` + [rancher@ip-10-0-0-50 ~]$ ls + rancher-data-backup-v2.1.3-20181219.tar.gz + ``` + +1. Move your backup tarball to a safe location external from your Rancher server. + +### C. Pull the New Docker Image + +Pull the image of the Rancher version that you want to upgrade to. + +Placeholder | Description +------------|------------- +`` | The release tag of the [Rancher version]({{}}/rancher/v2.x/en/installation/options/server-tags/) that you want to upgrade to. + +``` +docker pull rancher/rancher: +``` + +### D. Start the New Rancher Server Container + +Start a new Rancher server container using the data from the `rancher-data` container. Remember to pass in all the environment variables that you had used when you started the original container. + +>**Important:** _Do not_ stop the upgrade after initiating it, even if the upgrade process seems longer than expected. Stopping the upgrade may result in database migration errors during future upgrades. + +If you used a proxy, see [HTTP Proxy Configuration.]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/proxy/) + +If you configured a custom CA root certificate to access your services, see [Custom CA root certificate.]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/advanced/#custom-ca-certificate) + +If you are recording all transactions with the Rancher API, see [API Auditing]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/advanced/#api-audit-log) + +To see the command to use when starting the new Rancher server container, choose from the following options: + +- Docker Upgrade +- Docker Upgrade for Air Gap Installs + +{{% tabs %}} +{{% tab "Docker Upgrade" %}} + +Select which option you had installed Rancher server + +{{% accordion id="option-a" label="Option A-Default Self-Signed Certificate" %}} + +If you have selected to use the Rancher generated self-signed certificate, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container. + +Placeholder | Description +------------|------------- +`` | The release tag of the [Rancher version]({{}}/rancher/v2.x/en/installation/options/server-tags/) that you want to upgrade to. + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher: +``` + +{{% /accordion %}} + +{{% accordion id="option-b" label="Option B-Bring Your Own Certificate: Self-Signed" %}} + +If you have selected to bring your own self-signed certificate, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to have access to the same certificate that you had originally installed with. + +>**Reminder of the Cert Prerequisite:** The certificate files must be in [PEM format]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/#pem). In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [SSL FAQ / Troubleshooting](#cert-order). + +Placeholder | Description +------------|------------- + `` | The path to the directory containing your certificate files. +`` | The path to your full certificate chain. +`` | The path to the private key for your certificate. +`` | The path to the certificate authority's certificate. +`` | The release tag of the [Rancher version]({{}}/rancher/v2.x/en/installation/options/server-tags/) that you want to upgrade to. + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + --privileged \ + rancher/rancher: +``` + +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) + +{{% /accordion %}} +{{% accordion id="option-c" label="Option C-Bring Your Own Certificate: Signed by Recognized CA" %}} + +If you have selected to use a certificate signed by a recognized CA, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to have access to the same certificates that you had originally installed with. Remember to include `--no-cacerts` as an argument to the container to disable the default CA certificate generated by Rancher. + +>**Reminder of the Cert Prerequisite:** The certificate files must be in [PEM format]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/#pem). In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see [SSL FAQ / Troubleshooting](#cert-order). + +Placeholder | Description +------------|------------- +`` | The path to the directory containing your certificate files. +`` | The path to your full certificate chain. +`` | The path to the private key for your certificate. +`` | The release tag of the [Rancher version]({{}}/rancher/v2.x/en/installation/options/server-tags/) that you want to upgrade to. + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + rancher/rancher: \ + --privileged \ + --no-cacerts +``` +{{% /accordion %}} +{{% accordion id="option-d" label="Option D-Let's Encrypt Certificate" %}} + +>**Remember:** Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see [Let's Encrypt documentation on rate limits](https://letsencrypt.org/docs/rate-limits/). + +If you have selected to use [Let's Encrypt](https://letsencrypt.org/) certificates, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to provide the domain that you had used when you originally installed Rancher. + +>**Reminder of the Cert Prerequisites:** +> +>- Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (`rancher.mydomain.com` for example). +>- Open port `TCP/80` on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port `TCP/80` must be open to all IP addresses. + +Placeholder | Description +------------|------------- +`` | The release tag of the [Rancher version]({{}}/rancher/v2.x/en/installation/options/server-tags/) that you want to upgrade to. +`` | The domain address that you had originally started with + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher: \ + --acme-domain +``` +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) + +{{% /accordion %}} + +{{% /tab %}} +{{% tab "Docker Air Gap Upgrade" %}} + +For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster. + +> For Rancher versions from v2.2.0 to v2.2.x, you will need to mirror the `system-charts` repository to a location in your network that Rancher can reach. Then, after Rancher is installed, you will need to configure Rancher to use that repository. For details, refer to the documentation on [setting up the system charts for Rancher prior to v2.3.0.]({{}}/rancher/v2.x/en/installation/options/local-system-charts/#setting-up-system-charts-for-rancher-prior-to-v2-3-0) + +When starting the new Rancher server container, choose from the following options: + +{{% accordion id="option-a" label="Option A-Default Self-Signed Certificate" %}} + +If you have selected to use the Rancher generated self-signed certificate, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container. + +Placeholder | Description +------------|------------- +`` | Your private registry URL and port. +`` | The release tag of the [Rancher version]({{}}/rancher/v2.x/en/installation/options/server-tags/) that you want to to upgrade to. + +``` + docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher + -e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts + --privileged + /rancher/rancher: +``` +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) +{{% /accordion %}} + +{{% accordion id="option-b" label="Option B-Bring Your Own Certificate: Self-Signed" %}} + +If you have selected to bring your own self-signed certificate, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to have access to the same certificate that you had originally installed with. + +>**Reminder of the Prerequisite:** The certificate files must be in [PEM format]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/#pem). In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [SSL FAQ / Troubleshooting](#cert-order). + +Placeholder | Description +------------|------------- +`` | The path to the directory containing your certificate files. +`` | The path to your full certificate chain. +`` | The path to the private key for your certificate. +`` | The path to the certificate authority's certificate. +`` | Your private registry URL and port. +`` | The release tag of the [Rancher version]({{}}/rancher/v2.x/en/installation/options/server-tags/) that you want to upgrade to. + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher + -e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts + --privileged \ + /rancher/rancher: +``` +{{% /accordion %}} + +{{% accordion id="option-c" label="Option C-Bring Your Own Certificate: Signed by Recognized CA" %}} + +If you have selected to use a certificate signed by a recognized CA, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to have access to the same certificates that you had originally installed with. + + >**Reminder of the Prerequisite:** The certificate files must be in [PEM format]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/#pem). In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see [SSL FAQ / Troubleshooting](#cert-order). + +Placeholder | Description +------------|------------- +`` | The path to the directory containing your certificate files. +`` | The path to your full certificate chain. +`` | The path to the private key for your certificate. +`` | Your private registry URL and port. +`` | The release tag of the [Rancher version]({{}}/rancher/v2.x/en/installation/options/server-tags/) that you want to upgrade to. + +> **Note:** Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --no-cacerts \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher + -e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts + --privileged \ + /rancher/rancher: +``` +As of Rancher v2.5, privileged access is [required.](../#privileged-access-for-rancher-v2-5) +{{% /accordion %}} +{{% /tab %}} +{{% /tabs %}} + +**Result:** You have upgraded Rancher. Data from your upgraded server is now saved to the `rancher-data` container for use in future upgrades. + +### E. Verify the Upgrade + +Log into Rancher. Confirm that the upgrade succeeded by checking the version displayed in the bottom-left corner of the browser window. + +>**Having network issues in your user clusters following upgrade?** +> +> See [Restoring Cluster Networking]({{}}/rancher/v2.x/en/upgrades/upgrades/namespace-migration/#restoring-cluster-networking). + + +### F. Clean up Your Old Rancher Server Container + +Remove the previous Rancher server container. If you only stop the previous Rancher server container (and don't remove it), the container may restart after the next server reboot. + +## Rolling Back + +If your upgrade does not complete successfully, you can roll back Rancher server and its data back to its last healthy state. For more information, see [Docker Rollback]({{}}/rancher/v2.x/en/upgrades/rollbacks/single-node-rollbacks/).