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 b437e283cfa..34e7c85b340 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 @@ -5,6 +5,7 @@ aliases: - /rancher/v2.x/en/upgrades/single-node-upgrade/ - /rancher/v2.x/en/upgrades/upgrades/single-node-air-gap-upgrade - /rancher/v2.x/en/upgrades/upgrades/single-node + - /rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/ --- The following instructions will guide you through upgrading a Rancher server that was installed with Docker. diff --git a/content/rancher/v2.x/en/installation/upgrades-rollbacks/rollbacks/single-node-rollbacks/_index.md b/content/rancher/v2.x/en/installation/upgrades-rollbacks/rollbacks/single-node-rollbacks/_index.md deleted file mode 100644 index f0304c2eb44..00000000000 --- a/content/rancher/v2.x/en/installation/upgrades-rollbacks/rollbacks/single-node-rollbacks/_index.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Single Node Rollback -weight: 1015 -aliases: - - /rancher/v2.x/en/backups/rollbacks/single-node-rollbacks - - /rancher/v2.x/en/upgrades/single-node-rollbacks ---- - -If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before [Single Node Upgrade]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade). Rolling back restores: - -- Your previous version of Rancher. -- Your data backup created before upgrade. - -## Before You Start - -During rollback to a prior version of Rancher, 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 pull rancher/rancher: -``` - -In this command, `` is the version of Rancher you were running before your unsuccessful upgrade. `v2.0.5` 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). - -Terminal `docker ps` Command, Displaying Where to Find `` and `` -![Placeholder Reference]({{< baseurl >}}/img/rancher/placeholder-ref-2.png) - -| Placeholder | Example | Description | -| -------------------------- | -------------------------- | ------------------------------------------------------- | -| `` | `v2.0.5` | The rancher/rancher image you used before upgrade. | -| `` | `festive_mestorf` | The name of your Rancher container. | -| `` | `v2.0.5` | The version of Rancher that the backup is for. | -| `` | `9-27-18` | 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. - -## Rolling Back Rancher - -If you have issues upgrading Rancher, roll it back to its lastest known healthy state by pulling the last version you used and then restoring the backup you made before upgrade. - ->**Warning!** Rolling back to a previous version of Rancher destroys any changes made to Rancher following the upgrade. Unrecoverable data loss may occur. - -1. Using a remote Terminal connection, log into the node running your Rancher Server. - -1. Pull the version of Rancher that you were running prior to upgrade. Replace the `` with [that version](#before-you-start). - - For example, if you were running Rancher v2.0.5 before upgrade, pull v2.0.5. - - ``` - docker pull rancher/rancher: - ``` - -1. Stop the container currently running Rancher Server. Replace `` with the name of your Rancher container. - - ``` - docker stop - ``` - You can obtain the name for your Rancher container by entering `docker ps`. - -1. Move the backup tarball that you created during completion of [Single Node Upgrade]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/) onto your Rancher Server. Change to the directory that you moved it to. Enter `dir` to confirm that it's there. - - If you followed the naming convention we suggested in [Single Node Upgrade]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/), it will have a name similar to (`rancher-data-backup--.tar.gz`). - -1. Run the following command to replace the data in the `rancher-data` container with the data in the backup tarball, replacing the [placeholder](#before-you-start). Don't forget to close the quotes. - - ``` - docker run --volumes-from rancher-data \ - -v $PWD:/backup busybox sh -c "rm /var/lib/rancher/* -rf \ - && tar zxvf /backup/rancher-data-backup--.tar.gz" - ``` - -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: - ``` - >**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. - -**Result:** Rancher is rolled back to its version and data state prior to upgrade. diff --git a/content/rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/_index.md b/content/rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/_index.md index c45f6f1a381..4429dbd6a77 100644 --- a/content/rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/_index.md +++ b/content/rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/_index.md @@ -6,7 +6,7 @@ aliases: --- 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]({{}}/rancher/v2.x/en/installation/install-rancher-on-k8s/upgrades/upgrades/single-node/) +- [Upgrading Rancher installed with Docker]({{}}/rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-upgrades) - [Upgrading Rancher installed on a Kubernetes cluster]({{}}/rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/ha/) ### Known Upgrade Issues diff --git a/content/rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/single-node/_index.md b/content/rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/single-node/_index.md deleted file mode 100644 index a9b01d4e78c..00000000000 --- a/content/rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/single-node/_index.md +++ /dev/null @@ -1,331 +0,0 @@ ---- -title: Single Node Upgrade -weight: 1010 -aliases: - - /rancher/v2.x/en/upgrades/single-node-upgrade/ - - /rancher/v2.x/en/upgrades/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 installed with Docker. - -## 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)** - -- **[Air Gap Installs Only:]({{< baseurl >}}/rancher/v2.x/en/installation/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/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]({{< baseurl >}}/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 -- B. Create a backup tarball -Get the options set from your current Rancher install -- C. Upgrade Rancher -- D. Verify the Upgrade -- E. 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. Upgrade Rancher - -1. Pull the image of the Rancher version that you want to upgrade to. - - Placeholder | Description - ------------|------------- - `` | The release tag of the [Rancher version]({{< baseurl >}}/rancher/v2.x/en/installation/server-tags/) that you want to upgrade to. - - ``` - docker pull rancher/rancher: - ``` - -1. 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. - - >**Note:** After upgrading Rancher Server, data from your upgraded server is now saved to the `rancher-data` container for use in future upgrades. - - >**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. - - >**Did you...** - > - >- Use a proxy? See [HTTP Proxy Configuration]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/proxy/) - >- Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{< baseurl >}}/rancher/v2.x/en/admin-settings/custom-ca-root-certificate/) - >- Record all transactions with the Rancher API? See [API Auditing](#api-audit-log) - > - - Choose from the following options: - - * Single Node Upgrade - * Single Node Upgrade for Air Gap Installs - - {{% tabs %}} - {{% tab "Single Node 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]({{< baseurl >}}/rancher/v2.x/en/installation/server-tags/) that you want to upgrade to. - - ``` - docker run -d --volumes-from rancher-data \ - --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - 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]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#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 private key. - `` | The release tag of the [Rancher version]({{< baseurl >}}/rancher/v2.x/en/installation/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 \ - 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. 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]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#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]({{< baseurl >}}/rancher/v2.x/en/installation/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: \ - --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]({{< baseurl >}}/rancher/v2.x/en/installation/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 \ - rancher/rancher: \ - --acme-domain - ``` - - {{% /accordion %}} - - {{% /tab %}} - {{% tab "Single Node 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. - - >**Did you...** - > - >- Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{< baseurl >}}/rancher/v2.x/en/admin-settings/custom-ca-root-certificate/). - >- Record all transactions with the Rancher API? See [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#api-audit-log). - - - 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) - - 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]({{< baseurl >}}/rancher/v2.x/en/installation/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 - /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 Prerequisite:** The certificate files must be in [PEM format]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#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 private key. - `` | Your private registry URL and port. - `` | The release tag of the [Rancher version]({{< baseurl >}}/rancher/v2.x/en/installation/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 - /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]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#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]({{< baseurl >}}/rancher/v2.x/en/installation/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 - /rancher/rancher: - ``` - - {{% /accordion %}} - {{% /tab %}} - {{% /tabs %}} - -### D. 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]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrades/namespace-migration/#restoring-cluster-networking). - - -### E. 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 [Single Node Rollback]({{< baseurl >}}/rancher/v2.x/en/upgrades/rollbacks/single-node-rollbacks/).