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 new file mode 100644 index 00000000000..a9b01d4e78c --- /dev/null +++ b/content/rancher/v2.x/en/installation/upgrades-rollbacks/upgrades/single-node/_index.md @@ -0,0 +1,331 @@ +--- +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/).