mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-25 12:38:05 +00:00
Merge pull request #709 from rancher/staging
making single node install, upgrade/rollback, backup/restore clearer
This commit is contained in:
Denise
@@ -6,41 +6,67 @@ aliases:
|
||||
- /rancher/v2.x/en/installation/backups-and-restoration/single-node-backup-and-restoration/
|
||||
---
|
||||
|
||||
After completing your single node installation of Rancher, you can create a backup of your current installation at any time. We recommend making a backup before [upgrading]({{< baseurl >}}/rancher/v2.x/en/upgrades/single-node-upgrade/). Use this backup as a restoration point in disaster scenarios or when you need to [rollback]({{< baseurl >}}/rancher/v2.x/en/backups/rollbacks/single-node-rollbacks/) to an older version.
|
||||
After completing your single node installation of Rancher, we recommend creating backups of it on a regular basis. Use these backups as a restoration point in a disaster scenario.
|
||||
|
||||
>**Prerequisite:** Open Rancher and write down the version number displayed in the lower-left of the browser (example: `v2.0.0`). You'll need this number during the backup process.
|
||||
## Before You Start
|
||||
|
||||
1. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_ID>` with the ID of your Rancher container.
|
||||
During creation of your backup, 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 (`<EXAMPLE>`). Here's an example of a command with a placeholder:
|
||||
|
||||
```
|
||||
docker run --volumes-from rancher-data-<DATE> -v $PWD:/backup alpine tar zcvf /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).
|
||||
|
||||
<sup>Terminal `docker ps` Command, Displaying Where to Find `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>`</sup>
|
||||
|
||||
|
||||
| Placeholder | Example | Description |
|
||||
| -------------------------- | -------------------------- | --------------------------------------------------------- |
|
||||
| `<RANCHER_CONTAINER_TAG>` | `v2.0.5` | The rancher/rancher image you pulled for initial install. |
|
||||
| `<RANCHER_CONTAINER_NAME>` | `festive_mestorf` | The name of your Rancher container. |
|
||||
| `<RANCHER_VERSION>` | `v2.0.5` | The version of Rancher that you're creating a backup for. |
|
||||
| `<DATE>` | `9-27-18` | The date that the data container or backup was created. |
|
||||
<br/>
|
||||
|
||||
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 using a different command: `docker ps -a`. Use these commands for help anytime during while creating backups.
|
||||
|
||||
## Creating a Backup
|
||||
|
||||
This procedure creates a backup that you can restore to in case Rancher encounters a disaster scenario.
|
||||
|
||||
|
||||
1. Using a remote Terminal connection, log into the node running your Rancher Server.
|
||||
|
||||
1. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_NAME>` with the [name of your Rancher container](#before-you-start).
|
||||
|
||||
```
|
||||
docker stop <RANCHER_CONTAINER_ID>
|
||||
docker stop <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
|
||||
>**Tip:** You can obtain the ID for your Rancher container by entering the following command: `docker ps`.
|
||||
|
||||
2. <a id="backup"></a>Create a data container. This container contains the data from your current Rancher Server, and can be used to start Rancher Server.
|
||||
|
||||
- Replace `<RANCHER_CONTAINER_ID>` with the same ID from the previous step.
|
||||
- Replace `<RANCHER_VERSION>` and `<RANCHER_CONTAINER_TAG>` with the version of Rancher that you are currently running, as mentioned in the **Prerequisite** above.
|
||||
1. <a id="backup"></a>Use the command below, replacing each [placeholder](#before-you-start), to create a data container from the Rancher container that you just stopped.
|
||||
|
||||
```
|
||||
docker create --volumes-from <RANCHER_CONTAINER_ID> \
|
||||
--name rancher-data-<RANCHER_VERSION> rancher/rancher:<RANCHER_CONTAINER_TAG>
|
||||
docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data-<DATE> rancher/rancher:<RANCHER_CONTAINER_TAG>
|
||||
```
|
||||
|
||||
3. During upgrade, you point to a Rancher server to the same Rancher data container and the Rancher data in the data container will continue to be updated/changed. Therefore, you need to get a snapshot of the data to be used for disaster recovery or in case you need to rollback the upgrade.
|
||||
1. <a id="tarball"></a>From the data container that you just created (`rancher-data-<DATE>`), create a backup tarball (`rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz`). Use the following command, replacing each [placeholder](#before-you-start).
|
||||
|
||||
```
|
||||
docker run --volumes-from rancher-data-<RANCHER_VERSION> \
|
||||
-v $PWD:/backup alpine tar zcvf \
|
||||
/backup/rancher-data-backup-<RANCHER_VERSION>.tar.gz /var/lib/rancher
|
||||
docker run --volumes-from rancher-data-<DATE> -v $PWD:/backup alpine tar zcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
|
||||
```
|
||||
|
||||
3. After you've created your backup, you can either restart Rancher server or [upgrade]({{< baseurl >}}/rancher/v2.x/en/upgrades/single-node-upgrade/). Replace `<RANCHER_CONTAINER_ID>` with the ID of your Rancher container.
|
||||
**Step Result:** A stream of commands runs on screen.
|
||||
|
||||
1. Enter the `dir` command to confirm that the backup tarball was created. It will have a name similar to `rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz`.
|
||||
|
||||
1. Move your backup tarball to a safe location external from your Rancher Server. Then delete the `rancher-data-<DATE>` container from your Rancher Server.
|
||||
|
||||
1. Restart Rancher Server. Replace `<RANCHER_CONTAINER_NAME>` with the name of your [Rancher container](#before-you-start).
|
||||
|
||||
```
|
||||
# Restart Rancher server
|
||||
docker start <RANCHER_CONTAINER_ID>
|
||||
docker start <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
|
||||
**Result:** A backup of your Rancher Server is created. If you ever need to restore your backup, see [Restoring Backups: Single Node Installs]({{< baseurl >}}/rancher/v2.x/en/upgrades/restorations/single-node-restoration).
|
||||
**Result:** A backup tarball of your Rancher Server data is created. See [Restoring Backups: Single Node Installs]({{< baseurl >}}/rancher/v2.x/en/backups/restorations/single-node-restoration) if you need to restore backup data.
|
||||
|
||||
@@ -6,26 +6,66 @@ aliases:
|
||||
- /rancher/v2.x/en/installation/after-installation/single-node-backup-and-restoration/
|
||||
---
|
||||
|
||||
Restoring to a backup for your Rancher install if you encounter issues in your Rancher setup.
|
||||
If you encounter a disaster scenario, you can restore your Rancher Server to your most recent backup.
|
||||
|
||||
1. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_ID>` with the ID of your Rancher container.
|
||||
## Before You Start
|
||||
|
||||
During restoration of your backup, 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 (`<EXAMPLE>`). Here's an example of a command with a placeholder:
|
||||
|
||||
```
|
||||
docker run --volumes-from <RANCHER_CONTAINER_NAME> -v $PWD:/backup
|
||||
alpine sh -c "rm /var/lib/rancher/* -rf &&
|
||||
tar zxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>"
|
||||
```
|
||||
|
||||
In this command, `<RANCHER_CONTAINER_NAME>` and `<RANCHER_VERSION>-<DATE>` are environment variables for your Rancher deployment.
|
||||
|
||||
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).
|
||||
|
||||
<sup>Terminal `docker ps` Command, Displaying Where to Find `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>`</sup>
|
||||
|
||||
|
||||
| Placeholder | Example | Description |
|
||||
| -------------------------- | -------------------------- | --------------------------------------------------------- |
|
||||
| `<RANCHER_CONTAINER_TAG>` | `v2.0.5` | The rancher/rancher image you pulled for initial install. |
|
||||
| `<RANCHER_CONTAINER_NAME>` | `festive_mestorf` | The name of your Rancher container. |
|
||||
| `<RANCHER_VERSION>` | `v2.0.5` | The version number for your Rancher backup. |
|
||||
| `<DATE>` | `9-27-18` | The date that the data container or backup was created. |
|
||||
<br/>
|
||||
|
||||
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 using a different command: `docker ps -a`. Use these commands for help anytime during while creating backups.
|
||||
|
||||
## Restoring Backups
|
||||
|
||||
Using a [backup]({{< baseurl >}}/rancher/v2.x/en/backups/backups/single-node-backups/) that you created earlier, restore Rancher to its last known healthy state.
|
||||
|
||||
1. Using a remote Terminal connection, log into the node running your Rancher Server.
|
||||
|
||||
1. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_NAME>` with the [name of your Rancher container](#before-you-start).
|
||||
|
||||
```
|
||||
docker stop <RANCHER_CONTAINER_ID>
|
||||
docker stop <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
1. Move the backup tarball that you created during completion of [Creating Backups—Single Node Installs]({{< baseurl >}}/rancher/v2.x/en/backups/backups/single-node-backups/) onto your Rancher Server. Change to the directory that you moved it to. Enter `dir` to confirm that it's there.
|
||||
|
||||
2. Go to the location where you saved your [backup tar balls]({{< baseurl >}}/rancher/v2.x/en/backups/backups/single-node-backups/#backup). Run the following command to delete your current state data and start your backup data:
|
||||
If you followed the naming convention we suggested in [Creating Backups—Single Node Installs]({{< baseurl >}}/rancher/v2.x/en/backups/backups/single-node-backups/), it will have a name similar to `rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz`.
|
||||
|
||||
1. Enter the following command to delete your current state data and replace it with your backup data, replacing the [placeholders](#before-you-start). Don't forget to close the quotes.
|
||||
|
||||
>**Warning!** This command deletes all current state data from your Rancher Server container. Any changes saved after your backup tarball was created will be lost.
|
||||
|
||||
```
|
||||
docker run --volumes-from <RANCHER_CONTAINER_ID> -v $PWD:/backup \
|
||||
alpine sh -c "rm /var/lib/rancher/* -rf && \
|
||||
tar zxvf /backup/<BACKUP_FILENAME>.tar.gz"
|
||||
docker run --volumes-from <RANCHER_CONTAINER_NAME> -v $PWD:/backup
|
||||
alpine sh -c "rm /var/lib/rancher/* -rf &&
|
||||
tar zxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz"
|
||||
```
|
||||
|
||||
>**Warning!** Running this command will delete ALL current state data from your Rancher Server container. Any changes that happened after the backup point you are restoring will be lost.
|
||||
**Step Result:** A series of commands should run.
|
||||
|
||||
3. Start you rancher server container back. The container will start with the data from the restored backup.
|
||||
1. Restart your Rancher Server container, replacing the [placeholder](#before-you-start). It will restart using your backup data.
|
||||
|
||||
```
|
||||
docker start <RANCHER_CONTAINER_ID>
|
||||
docker start <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
|
||||
1. Wait a few moments and then open Rancher in a web browser. Confirm that the restoration succeeded and that your data is restored.
|
||||
@@ -10,139 +10,106 @@ For development environments, we recommend installing Rancher by running a singl
|
||||
>**Want to use an external load balancer?**
|
||||
> See [Single Node Install with an External Load Balancer]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/single-node-install-external-lb) instead.
|
||||
|
||||
## Installation Outline
|
||||
|
||||
Installation of Rancher on a single node involves multiple procedures. Review this outline to learn about each procedure you need to complete.
|
||||
|
||||
1. [Provision Linux Host](#1-provision-linux-host)
|
||||
|
||||
Provision a single Linux host to launch your {{< product >}} Server.
|
||||
|
||||
2. [Choose an SSL Option and Install Rancher](#2-choose-an-ssl-option-and-install-rancher)
|
||||
|
||||
Choose an SSL option for Rancher communication encryption. After choosing an option, run the command that accompanies it to deploy Rancher.
|
||||
|
||||
## 1. Provision Linux Host
|
||||
|
||||
Provision a single Linux host to launch your {{< product >}} Server.
|
||||
Provision a single Linux host to launch your Rancher Server.
|
||||
|
||||
### Requirements
|
||||
|
||||
#### Operating System
|
||||
|
||||
{{% tabs %}}
|
||||
{{% tab "Operating Systems" %}}
|
||||
{{< requirements_os >}}
|
||||
|
||||
#### Hardware
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab "Hardware" %}}
|
||||
{{< requirements_hardware >}}
|
||||
|
||||
#### Software
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab "Software" %}}
|
||||
{{< requirements_software >}}
|
||||
|
||||
{{< note_server-tags >}}
|
||||
|
||||
#### Ports
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab "Ports" %}}
|
||||
The following diagram depicts the basic port requirements for Rancher. For a comprehensive list, see [Port Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/references/).
|
||||
|
||||
|
||||
{{% /tab %}}
|
||||
{{% /tabs %}}
|
||||
|
||||
|
||||
## 2. Choose an SSL Option and Install Rancher
|
||||
|
||||
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.
|
||||
|
||||
>**Attention Air Gap Users:**
|
||||
> If you are visiting this page to complete an [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `<REGISTRY.DOMAIN.COM:PORT>` with your private registry URL in front of `rancher/rancher:latest`.
|
||||
>**Do you want to...**
|
||||
>
|
||||
> Example:
|
||||
```
|
||||
<REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest
|
||||
```
|
||||
>- Complete an Air Gap Installation?
|
||||
>- Record all transactions with the Rancher API?
|
||||
>
|
||||
>See [Advanced Options](#advanced-options) below before continuing.
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
- [Option A—Default Self-Signed Certificate](#option-a-default-self-signed-certificate)
|
||||
- [Option B—Bring Your Own Certificate: Self-Signed](#option-b-bring-your-own-certificate-self-signed)
|
||||
- [Option C—Bring Your Own Certificate: Signed by Recognized CA](#option-c-bring-your-own-certificate-signed-by-recognized-ca)
|
||||
- [Option D—Bring Your Own Certificate: Private CA Root Certificate CA](#option-d-bring-your-own-certificate-private-ca-root-certificate)
|
||||
- [Option E—Let's Encrypt Certificate](#option-e-let-s-encrypt-certificate)
|
||||
{{% accordion id="option-a" label="Option A—Default Self-Signed Certificate" %}}
|
||||
|
||||
>**Want records of all transactions with the Rancher API?**
|
||||
>
|
||||
>Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your install command.
|
||||
>```
|
||||
-e AUDIT_LEVEL=1 \
|
||||
-e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \
|
||||
-e AUDIT_LOG_MAXAGE=20 \
|
||||
-e AUDIT_LOG_MAXBACKUP=20 \
|
||||
-e AUDIT_LOG_MAXSIZE=100 \
|
||||
```
|
||||
If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself.
|
||||
|
||||
### Option A—Default Self-Signed Certificate
|
||||
Log into your Linux host, and then run the minimum installation command below.
|
||||
|
||||
If you install Rancher without using your own certificate, Rancher generates a self-signed certificate that's used for encryption. If you're satisfied with this certificate, there's no need to obtain your own.
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
rancher/rancher:latest
|
||||
|
||||
**To Install Rancher Using the Default Certificate:**
|
||||
|
||||
1. From your Linux host, run the Docker command to install Rancher without any additional parameters:
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
rancher/rancher:latest
|
||||
```
|
||||
|
||||
### Option B—Bring Your Own Certificate: Self-Signed
|
||||
|
||||
Your Rancher install can use a self-signed certificate that you provide to encrypt communications.
|
||||
{{% /accordion %}}
|
||||
{{% accordion id="option-b" label="Option B—Bring Your Own Certificate: Self-Signed" %}}
|
||||
In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher.
|
||||
|
||||
>**Prerequisites:**
|
||||
>Create a self-signed certificate.
|
||||
>Create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice.
|
||||
>
|
||||
>- The certificate files must be in [PEM format](#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).
|
||||
|
||||
**To Install Rancher Using a Self-Signed Cert:**
|
||||
After creating your certificate, run the Docker command below to install Rancher. Use the `-v` flag and provide the path to your certificates to mount them in your container.
|
||||
|
||||
Your Rancher install can use a self-signed certificate that you provide to encrypt communications.
|
||||
- Replace `<CERT_DIRECTORY>` with the directory path to your certificate file.
|
||||
- Replace `<FULL_CHAIN.pem>`,`<PRIVATE_KEY.pem>`, and `<CA_CERTS>` with your certificate names.
|
||||
|
||||
1. After creating your certificate, run the Docker command to install Rancher, pointing toward your certificate files.
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
|
||||
-v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
|
||||
-v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
|
||||
rancher/rancher:latest
|
||||
```
|
||||
{{% /accordion %}}
|
||||
{{% accordion id="option-c" label="Option C—Bring Your Own Certificate: Signed by Recognized CA" %}}
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-v /etc/<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
|
||||
-v /etc/<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
|
||||
-v /etc/<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
|
||||
rancher/rancher:latest
|
||||
```
|
||||
In production environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings.
|
||||
|
||||
### Option C—Bring Your Own Certificate: Signed by Recognized CA
|
||||
>**Prerequisite:** The certificate files must be in [PEM format](#pem).
|
||||
|
||||
If you're publishing your app publicly, you should ideally be using a certificate signed by a recognized CA.
|
||||
After obtaining your certificate, run the Docker command below.
|
||||
|
||||
>**Prerequisites:**
|
||||
>
|
||||
>- The certificate files must be in [PEM format](#pem).
|
||||
>- Make sure that the container includes your certificate file and the key file. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.
|
||||
>- Add `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher.
|
||||
- Use the `-v` flag and provide the path to your certificates to mount them in your container. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.
|
||||
|
||||
**To Install Rancher Using a Certificate Signed by a Recognized CA:**
|
||||
- Replace `<CERT_DIRECTORY>` with the directory path to your certificate file.
|
||||
- Replace `<FULL_CHAIN.pem>` and `<PRIVATE_KEY.pem>` with your certificate names.
|
||||
|
||||
1. After obtaining your certificate, run the Docker command to deploy Rancher while pointing toward your certificate files.
|
||||
- Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher.
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-v /etc/your_certificate_directory/fullchain.pem:/etc/rancher/ssl/cert.pem \
|
||||
-v /etc/your_certificate_directory/privkey.pem:/etc/rancher/ssl/key.pem \
|
||||
rancher/rancher:latest --no-cacerts
|
||||
```
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
|
||||
-v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
|
||||
rancher/rancher:latest --no-cacerts
|
||||
```
|
||||
{{% /accordion %}}
|
||||
{{% accordion id="option-d" label="Option D—Bring Your Own Certificate: Private CA Root Certificate" %}}
|
||||
|
||||
### Option D—Bring Your Own Certificate: Private CA Root Certificate
|
||||
If you're using Rancher in a internal production environment where you aren't exposing apps publicly, use a certificate from a private certificate authority (CA).
|
||||
|
||||
Services that Rancher needs to access are sometimes configured with a certificate from an custom/internal Certificate Authority (CA) root, also known as self signed certificate. If the presented certificate from the service cannot be validated by Rancher, the following error will appear: `x509: certificate signed by unknown authority`.
|
||||
Services that Rancher needs to access are sometimes configured with a certificate from an custom/internal CA root, also known as self signed certificate. If the presented certificate from the service cannot be validated by Rancher, the following error displays: `x509: certificate signed by unknown authority`.
|
||||
|
||||
To validate the certificate, the CA root certificates need to be added to Rancher. As Rancher is written in Go, we can use the environment variable `SSL_CERT_DIR` to point to the directory where the CA root certificates are located in the container. The CA root certificates directory can be mounted using the Docker volume option (`-v host-source-directory:container-destination-directory`) when starting the Rancher container.
|
||||
|
||||
@@ -152,14 +119,12 @@ Examples of services that Rancher can access:
|
||||
* Authentication providers
|
||||
* Accessing hosting/cloud API when using Node Drivers
|
||||
|
||||
#### Start Rancher Container with custom CA root certificates
|
||||
Use the the command example to start a Rancher container with you private CA certificates mounted.
|
||||
|
||||
The requirements are:
|
||||
|
||||
* Mount the host directory containing the CA root certificates in the container using the volume option.
|
||||
* Add the environment variable `SSL_CERT_DIR` with as value the mounted CA root certificates directory location inside the container.
|
||||
|
||||
Passing environment variables to the Rancher container can be done using `-e KEY=VALUE` or `--env KEY=VALUE`, mounting a host directory inside the container can be done using `-v host-source-directory:container-destination-directory` or `--volume host-source-directory:container-destination-directory`.
|
||||
- The volume option (`-v`) should specify the host directory containing the CA root certificates.
|
||||
- The `e` flag in combination with `SSL_CERT_DIR` declares an environment variable that specifies the mounted CA root certificates directory location inside the container.
|
||||
- Passing environment variables to the Rancher container can be done using `-e KEY=VALUE` or `--env KEY=VALUE`.
|
||||
- Mounting a host directory inside the container can be done using `-v host-source-directory:container-destination-directory` or `--volume host-source-directory:container-destination-directory`.
|
||||
|
||||
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.
|
||||
|
||||
@@ -170,10 +135,10 @@ docker run -d --restart=unless-stopped \
|
||||
-e SSL_CERT_DIR="/container/certs" \
|
||||
rancher/rancher:latest
|
||||
```
|
||||
{{% /accordion %}}
|
||||
{{% accordion id="option-e" label="Option E—Let's Encrypt Certificate" %}}
|
||||
|
||||
### Option E—Let's Encrypt Certificate
|
||||
|
||||
Rancher supports Let's Encrypt certificates. Let's Encrypt uses an `http-01 challenge` to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, `rancher.mydomain.com`) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS.
|
||||
For production environments, you also have the options of using [Let's Encrypt](https://letsencrypt.org/) certificates. Let's Encrypt uses an http-01 challenge to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, `rancher.mydomain.com`) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS.
|
||||
|
||||
>**Prerequisites:**
|
||||
>
|
||||
@@ -182,27 +147,20 @@ Rancher supports Let's Encrypt certificates. Let's Encrypt uses an `http-01 chal
|
||||
>- 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.
|
||||
|
||||
|
||||
**To Install Rancher Using a Let's Encrypt Certificate:**
|
||||
After you fulfill the prerequisites, you can install Rancher using a Let's Encrypt certificate by running the following command. Replace `<YOUR.DNS.NAME>` with your your domain.
|
||||
|
||||
Run the following commands from your Linux host.
|
||||
|
||||
1. Run the Docker command.
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
rancher/rancher:latest \
|
||||
--acme-domain <YOUR.DNS.NAME>
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
rancher/rancher:latest \
|
||||
--acme-domain rancher.mydomain.com
|
||||
```
|
||||
|
||||
>
|
||||
>**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/).
|
||||
{{% /accordion %}}
|
||||
|
||||
## What's Next?
|
||||
|
||||
You have a couple of options:
|
||||
|
||||
- Create a backup of your Rancher Server in case of a disaster scenario: [Single Node Backup and Restoration]({{< baseurl >}}/rancher/v2.x/en/installation/backups-and-restoration/single-node-backup-and-restoration/).
|
||||
- **Recommended:** Review [Single Node Backup and Restoration]({{< baseurl >}}/rancher/v2.x/en/installation/backups-and-restoration/single-node-backup-and-restoration/). Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use.
|
||||
- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/).
|
||||
|
||||
<br/>
|
||||
@@ -211,11 +169,31 @@ You have a couple of options:
|
||||
|
||||
{{< ssl_faq_single >}}
|
||||
|
||||
## Persistent Data
|
||||
## Advanced Options
|
||||
|
||||
### API Auditing
|
||||
|
||||
If you want to record all transations with the Rancher API, enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your install command.
|
||||
|
||||
-e AUDIT_LEVEL=1 \
|
||||
-e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \
|
||||
-e AUDIT_LOG_MAXAGE=20 \
|
||||
-e AUDIT_LOG_MAXBACKUP=20 \
|
||||
-e AUDIT_LOG_MAXSIZE=100 \
|
||||
|
||||
### Air Gap
|
||||
|
||||
If you are visiting this page to complete an [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `<REGISTRY.DOMAIN.COM:PORT>` with your private registry URL in front of `rancher/rancher:latest`.
|
||||
|
||||
**Example:**
|
||||
|
||||
<REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest
|
||||
|
||||
### Persistent Data
|
||||
|
||||
{{< persistentdata >}}
|
||||
|
||||
## Running `rancher/rancher` and `rancher/rancher-agent` on the same node
|
||||
### Running `rancher/rancher` and `rancher/rancher-agent` on the Same Node
|
||||
|
||||
In the situation where you want to use a single node to run Rancher and to be able to add the same node to a cluster, you have to adjust the host ports mapped for the `rancher/rancher` container.
|
||||
|
||||
|
||||
+50
-56
@@ -10,24 +10,14 @@ For development environments, we recommend installing Rancher by running a singl
|
||||
>**Want to skip the external load balancer?**
|
||||
> See [Single Node Installation]({{< baseurl >}}/rancher/v2.x/en/installation/single-node) instead.
|
||||
|
||||
|
||||
|
||||
## Installation Outline
|
||||
<!-- TOC -->
|
||||
|
||||
Installation of Rancher on a single node with an external load balancer involves multiple procedures. Review this outline to learn about each procedure you need to complete.
|
||||
|
||||
1. [Provision Linux Host](#1-provision-linux-host)
|
||||
|
||||
Provision a single Linux host to launch your {{< product >}} Server.
|
||||
|
||||
2. [Choose an SSL Option and Install Rancher](#2-choose-an-ssl-option-and-install-rancher)
|
||||
|
||||
Choose an SSL option for Rancher communication encryption. After choosing an option, run the command that accompanies it to deploy Rancher.
|
||||
|
||||
3. [Configure Load Balancer](#3-configure-load-balancer)
|
||||
|
||||
Setup a load balancer to direct communications with Rancher and your Kubernetes cluster.
|
||||
- [1. Provision Linux Host](#1-provision-linux-host)
|
||||
- [2. Choose an SSL Option and Install Rancher](#2-choose-an-ssl-option-and-install-rancher)
|
||||
- [3. Configure Load Balancer](#3-configure-load-balancer)
|
||||
|
||||
<!-- /TOC -->
|
||||
|
||||
## 1. Provision Linux Host
|
||||
|
||||
@@ -35,54 +25,38 @@ Provision a single Linux host to launch your {{< product >}} Server.
|
||||
|
||||
### Host Requirements
|
||||
|
||||
#### Operating System
|
||||
|
||||
{{% tabs %}}
|
||||
{{% tab "Operating System" %}}
|
||||
{{< requirements_os >}}
|
||||
|
||||
#### Hardware
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab "Hardware" %}}
|
||||
{{< requirements_hardware >}}
|
||||
|
||||
#### Software
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab "Software" %}}
|
||||
{{< requirements_software >}}
|
||||
|
||||
{{< note_server-tags >}}
|
||||
|
||||
#### Ports
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab "Ports" %}}
|
||||
The following diagram depicts the basic port requirements for Rancher. For a comprehensive list, see [Port Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/references/).
|
||||
|
||||
|
||||
{{% /tab %}}
|
||||
{{% /tabs %}}
|
||||
|
||||
## 2. Choose an SSL Option and Install Rancher
|
||||
|
||||
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.
|
||||
|
||||
>**Attention Air Gap Users:**
|
||||
> If you are visiting this page to complete [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must prepend your private registry URL to the server tag when running the installation command in the option that you choose. Replace `<REGISTRY.DOMAIN.COM:PORT>` with your private registry URL.
|
||||
>**Do you want to...**
|
||||
>
|
||||
> Example:
|
||||
```
|
||||
<REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest
|
||||
```
|
||||
|
||||
- [Option A-Bring Your Own Certificate: Self-Signed](#option-a-bring-your-own-certificate-self-signed)
|
||||
- [Option B-Bring Your Own Certificate: Signed by Recognized CA](#option-b-bring-your-own-certificate-signed-by-recognized-ca)
|
||||
|
||||
>**Want records of all transactions with the Rancher API?**
|
||||
>- Complete an Air Gap Installation?
|
||||
>- Record all transactions with the Rancher API?
|
||||
>
|
||||
>Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your install command.
|
||||
>```
|
||||
-e AUDIT_LEVEL=1 \
|
||||
-e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \
|
||||
-e AUDIT_LOG_MAXAGE=20 \
|
||||
-e AUDIT_LOG_MAXBACKUP=20 \
|
||||
-e AUDIT_LOG_MAXSIZE=100 \
|
||||
```
|
||||
>See [Advanced Options](#advanced-options) below before continuing.
|
||||
|
||||
### Option A-Bring Your Own Certificate: Self-Signed
|
||||
Choose from the following options:
|
||||
|
||||
{{% accordion id="option-a" label="Option A-Bring Your Own Certificate: Self-Signed" %}}
|
||||
If you elect to use a self-signed certificate to encrypt communication, you must install the certificate on your load balancer (which you'll do later) and your Rancher container. Run the docker command to deploy Rancher, pointing it toward your certificate.
|
||||
|
||||
>**Prerequisites:**
|
||||
@@ -100,9 +74,9 @@ If you elect to use a self-signed certificate to encrypt communication, you must
|
||||
-v /etc/your_certificate_directory/cacerts.pem:/etc/rancher/ssl/cacerts.pem \
|
||||
rancher/rancher:latest
|
||||
```
|
||||
|
||||
### Option B-Bring Your Own Certificate: Signed by Recognized CA
|
||||
|
||||
|
||||
{{% /accordion %}}
|
||||
{{% accordion id="option-b" label="Option B-Bring Your Own Certificate: Signed by Recognized CA" %}}
|
||||
If your cluster is public facing, it's best to use a certificate signed by a recognized CA.
|
||||
|
||||
>**Prerequisites:**
|
||||
@@ -117,9 +91,10 @@ If you use a certificate signed by a recognized CA, installing your certificate
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
rancher/rancher:latest --no-cacerts
|
||||
```
|
||||
-p 80:80 -p 443:443 \
|
||||
rancher/rancher:latest --no-cacerts
|
||||
```
|
||||
{{% /accordion %}}
|
||||
|
||||
## 3. Configure Load Balancer
|
||||
|
||||
@@ -186,9 +161,8 @@ server {
|
||||
<br/>
|
||||
|
||||
## What's Next?
|
||||
You have a couple of options:
|
||||
|
||||
- Create a backup of your Rancher Server in case of a disaster scenario: [Single Node Backup and Restoration]({{< baseurl >}}/rancher/v2.x/en/installation/backups-and-restoration/single-node-backup-and-restoration/).
|
||||
- **Recommended:** Review [Single Node Backup and Restoration]({{< baseurl >}}/rancher/v2.x/en/installation/backups-and-restoration/single-node-backup-and-restoration/). Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use.
|
||||
- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/).
|
||||
|
||||
<br/>
|
||||
@@ -197,6 +171,26 @@ You have a couple of options:
|
||||
|
||||
{{< ssl_faq_single >}}
|
||||
|
||||
## Persistent Data
|
||||
## Advanced Options
|
||||
|
||||
### API Auditing
|
||||
|
||||
If you want to record all transations with the Rancher API, enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your install command.
|
||||
|
||||
-e AUDIT_LEVEL=1 \
|
||||
-e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \
|
||||
-e AUDIT_LOG_MAXAGE=20 \
|
||||
-e AUDIT_LOG_MAXBACKUP=20 \
|
||||
-e AUDIT_LOG_MAXSIZE=100 \
|
||||
|
||||
### Air Gap
|
||||
|
||||
If you are visiting this page to complete an [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `<REGISTRY.DOMAIN.COM:PORT>` with your private registry URL in front of `rancher/rancher:latest`.
|
||||
|
||||
**Example:**
|
||||
|
||||
<REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest
|
||||
|
||||
### Persistent Data
|
||||
|
||||
{{< persistentdata >}}
|
||||
|
||||
@@ -6,34 +6,78 @@ aliases:
|
||||
- /rancher/v2.x/en/upgrades/single-node-rollbacks
|
||||
---
|
||||
|
||||
Rolling back an unsuccessful Rancher upgrade requires you to
|
||||
restore the backup you created while completing [Single Node Upgrade]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrade-scenarios/single-node-upgrade/).
|
||||
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/upgrade-scenarios/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 (`<EXAMPLE>`). Here's an example of a command with a placeholder:
|
||||
|
||||
```
|
||||
docker pull rancher/rancher:<PRIOR_RANCHER_VERSION>
|
||||
```
|
||||
|
||||
In this command, `<PRIOR_RANCHER_VERSION>` 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).
|
||||
|
||||
<sup>Terminal `docker ps` Command, Displaying Where to Find `<PRIOR_RANCHER_VERSION>` and `<RANCHER_CONTAINER_NAME>`</sup>
|
||||
|
||||
|
||||
| Placeholder | Example | Description |
|
||||
| -------------------------- | -------------------------- | ------------------------------------------------------- |
|
||||
| `<PRIOR_RANCHER_VERSION>` | `v2.0.5` | The rancher/rancher image you used before upgrade. |
|
||||
| `<RANCHER_CONTAINER_NAME>` | `festive_mestorf` | The name of your Rancher container. |
|
||||
| `<RANCHER_VERSION>` | `v2.0.5` | The version of Rancher that the backup is for. |
|
||||
| `<DATE>` | `9-27-18` | The date that the data container or backup was created. |
|
||||
<br/>
|
||||
|
||||
You can obtain `<PRIOR_RANCHER_VERSION>` 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 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. Pull the version of Rancher that you were running prior to upgrade.
|
||||
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 `<PRIOR_RANCHER_VERSION>` 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:<PRIOR_VERSION>
|
||||
docker pull rancher/rancher:<PRIOR_RANCHER_VERSION>
|
||||
```
|
||||
|
||||
2. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_ID>` with the ID of your Rancher container.
|
||||
|
||||
1. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_NAME>` with the name of your Rancher container.
|
||||
|
||||
```
|
||||
docker stop <RANCHER_CONTAINER_ID>
|
||||
docker stop <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
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-<RANCHER_VERSION>-<DATE>.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 alpine sh -c "rm /var/lib/rancher/* -rf
|
||||
&& tar zxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz"
|
||||
```
|
||||
|
||||
3. Go to the location where you saved your [backup tar balls]({{< baseurl>}}/rancher/v2.x/en/upgrades/single-node-upgrade/#backup). Run the following command to create a data container from the backup tar ball.
|
||||
|
||||
```
|
||||
docker run --volumes-from rancher-data \
|
||||
-v $PWD:/backup alpine sh -c "rm /var/lib/rancher/* -rf \
|
||||
&& tar zxvf /backup/<BACKUP_FILENAME>.tar.gz"
|
||||
```
|
||||
|
||||
4. Start a new Rancher Server container with the `<PRIOR_VERSION>` tag pointing to the data container.
|
||||
1. Start a new Rancher Server container with the `<PRIOR_RANCHER_VERSION>` 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:<PRIOR_VERSION>
|
||||
docker run -d --volumes-from rancher-data
|
||||
--restart=unless-stopped -p 80:80 -p 443:443 rancher/rancher:<PRIOR_RANCHER_VERSION>
|
||||
```
|
||||
>**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.
|
||||
@@ -4,43 +4,76 @@ weight: 1010
|
||||
aliases:
|
||||
- /rancher/v2.x/en/upgrades/single-node-upgrade/
|
||||
---
|
||||
To upgrade Rancher Server 2.x after a new version is released, create a backup of your server and then run the upgrade command.
|
||||
<a id="prereq"></a>
|
||||
To upgrade Rancher Server 2.x when a new version is released, create a data container for your current Rancher deployment, pull the latest image of Rancher, and then start a new Rancher container using your data container.
|
||||
|
||||
>**Prerequisites:** Open Rancher and write down the version number displayed in the lower-left of the browser (example: `v2.0.0`). You'll need this number during the upgrade process.
|
||||
## Before You Start
|
||||
|
||||
1. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_ID>` with the ID of your Rancher container.
|
||||
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 (`<EXAMPLE>`). Here's an example of a command with a placeholder:
|
||||
|
||||
|
||||
```
|
||||
docker run --volumes-from rancher-data -v $PWD:/backup alpine tar zcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
|
||||
```
|
||||
|
||||
In this command, `<RANCHER_VERSION>-<DATE>` is the the version number and date of creation for a backup of Rancher.
|
||||
|
||||
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](#completing-the-upgrade).
|
||||
|
||||
<sup>Terminal `docker ps` Command, Displaying Where to Find `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>`</sup>
|
||||
|
||||
|
||||
| Placeholder | Example | Description |
|
||||
| -------------------------- | -------------------------- | --------------------------------------------------------- |
|
||||
| `<RANCHER_CONTAINER_TAG>` | `v2.0.5` | The rancher/rancher image you pulled for initial install. |
|
||||
| `<RANCHER_CONTAINER_NAME>` | `festive_mestorf` | The name of your Rancher container. |
|
||||
| `<RANCHER_VERSION>` | `v2.0.5` | The version of Rancher that you're creating a backup for. |
|
||||
| `<DATE>` | `9-27-18` | The date that the data container or backup was created. |
|
||||
<br/>
|
||||
|
||||
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 using a different command: `docker ps -a`. Use these commands for help anytime during while creating backups.
|
||||
|
||||
## Completing the Upgrade
|
||||
|
||||
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.
|
||||
|
||||
1. Using a remote Terminal connection, log into the node running your Rancher Server.
|
||||
|
||||
|
||||
1. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_NAME>` with the [name of your Rancher container](#before-you-start).
|
||||
|
||||
```
|
||||
docker stop <RANCHER_CONTAINER_ID>
|
||||
docker stop <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
|
||||
>**Tip:** You can obtain the ID for your Rancher container by entering the following command: `docker ps`.
|
||||
|
||||
1. Create a container of your current Rancher data for use in your upgraded Rancher Server. Name the container `rancher-data`.
|
||||
|
||||
- Replace `<RANCHER_CONTAINER_ID>` with the same ID from the previous step.
|
||||
- Replace `<RANCHER_CONTAINER_TAG>` with the version of Rancher that you are currently running, as mentioned in the **Prerequisite** above.
|
||||
1. <a id="backup"></a>Use the command below, replacing each [placeholder](#before-you-start), to create a data container from the Rancher container that you just stopped.
|
||||
|
||||
```
|
||||
docker create --volumes-from <RANCHER_CONTAINER_ID> \
|
||||
--name rancher-data rancher/rancher:<RANCHER_CONTAINER_TAG>
|
||||
docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data rancher/rancher:<RANCHER_CONTAINER_TAG>
|
||||
```
|
||||
|
||||
1. <a id="backup"></a>Create a backup tar ball of your current Rancher data. If you need to rollback, use this backup tar ball.
|
||||
1. <a id="tarball"></a>From the data container that you just created (`rancher-data`), create a backup tarball (`rancher-data-backup-<RANCHER_VERSION>-<DATE>.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).
|
||||
|
||||
- Replace `<RANCHER_VERSION>` with the tag for the version of Rancher currently installed.
|
||||
|
||||
```
|
||||
docker run --volumes-from rancher-data -v $PWD:/backup \
|
||||
alpine tar zcvf /backup/rancher-data-backup-<RANCHER_VERSION>.tar.gz \
|
||||
/var/lib/rancher
|
||||
docker run --volumes-from rancher-data -v $PWD:/backup alpine tar zcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
|
||||
```
|
||||
|
||||
**Step Result:** When you enter this command, a series of commands should run.
|
||||
|
||||
1. Enter the `dir` command to confirm that the backup tarball was created. It will have a name similar to `rancher-data-backup-<RANCHER_VERSION>-<DATE>`.
|
||||
|
||||
|
||||
|
||||
|
||||
1. Move your backup tarball to a safe location external from your Rancher Server.
|
||||
|
||||
|
||||
1. Pull the most recent image of Rancher.
|
||||
|
||||
```
|
||||
docker pull rancher/rancher:latest
|
||||
docker pull rancher/rancher:latest
|
||||
```
|
||||
|
||||
>**Attention Air Gap Users:**
|
||||
@@ -49,11 +82,10 @@ docker pull rancher/rancher:latest
|
||||
> Example: `<registry.yourdomain.com:port>/rancher/rancher:latest`
|
||||
>
|
||||
|
||||
1. Launch a new Rancher Server container using the `rancher-data` container.
|
||||
1. Start a new Rancher Server container using the data from the `rancher-data` container.
|
||||
|
||||
```
|
||||
docker run -d --volumes-from rancher-data --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 rancher/rancher:latest
|
||||
docker run -d --volumes-from rancher-data --restart=unless-stopped -p 80:80 -p 443:443 rancher/rancher:latest
|
||||
```
|
||||
|
||||
>**Want records of all transactions with the Rancher API?**
|
||||
@@ -74,10 +106,12 @@ docker run -d --volumes-from rancher-data --restart=unless-stopped \
|
||||
|
||||
1. Log into Rancher. Confirm that the upgrade succeeded by checking the version displayed in the bottom-left corner of the browser window.
|
||||
|
||||
<!--/img/rancher/)-->
|
||||
|
||||
1. 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.
|
||||
|
||||
**Result:** Rancher Server is upgraded to the latest version.
|
||||
|
||||
>**Note:** If your upgrade does not complete successfully, you can roll Rancher Server and its data back to its last healthy state. For more information, see [Restoring Backups—Single Node Installs]({{< baseurl >}}/rancher/v2.x/en/backups/restorations/single-node-restoration/).
|
||||
>**Note:** If your upgrade does not complete successfully, you can roll 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/).
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: Migrating from Rancher v1.6 to v2.x
|
||||
weight: 10000
|
||||
draft: true
|
||||
---
|
||||
|
||||
|
||||
### Checklist for migration of a 1.6 setup to 2.0
|
||||
|
||||
Blog Post: https://rancher.com/blog/2018/2018-08-09-migrate-1dot6-setup-to-2dot0/
|
||||
|
||||
### Concepts of Stack, Service
|
||||
How to map Cattle's Stack and service design to k8s world and launch a simple service
|
||||
|
||||
Blog Post: https://rancher.com/blog/2018/2018-08-02-journey-from-cattle-to-k8s/
|
||||
|
||||
|
||||
### Exposing your service publicly
|
||||
How to publicly expose your Service using port mapping in 1.6 and its equivalent 2.0 method
|
||||
|
||||
Blog Post: https://rancher.com/blog/2018/expose-and-monitor-workloads/
|
||||
|
||||
### Monitoring a service using healthchecks
|
||||
How to add TCP/HTTP healthchecks in Rancher 2.0
|
||||
|
||||
Blog Post: https://rancher.com/blog/2018/2018-08-22-k8s-monitoring-and-healthchecks/
|
||||
|
||||
### Scheduling rules for placement of service containers & Global Service
|
||||
How to find equivalence in 2.0 for scheduling your containers using host affinity/anti-affinity and other 1.6 scheduling labels
|
||||
How to launch a global service in 2.0
|
||||
|
||||
Blog Post: Coming soon!
|
||||
|
||||
### Service Discovery: Rancher internal DNS
|
||||
How to discover services, use external_name/alias in 2.0
|
||||
|
||||
Blog Post: Coming soon!
|
||||
|
||||
### LoadBalancing
|
||||
How to achieve TCP/HTTP load balancing and configure hostname/path based routing in 2.0
|
||||
|
||||
Blog Post: Coming soon!
|
||||
|
||||
<!--
|
||||
- [ ] Secrets - How to manage and use secrets in 2.0
|
||||
- [ ] Storage - How to configure storage with Rancher 2.0 on Kubernetes
|
||||
- [ ] Rancher metadata - What can be alternative solutions to rancher 1.6 metadata in rancher 2.0
|
||||
- [ ] Environment management - What is the equivalence in 2.0 to creating and managing 1.6 environments
|
||||
- [ ] External DNS integration- Alternative ways in 2.0 to integrate with external DNS providers supported by Rancher 1.6
|
||||
- [ ] Differences in Upgrade procedure for applications deployed on Rancher
|
||||
-->
|
||||
@@ -1,8 +1,8 @@
|
||||
<blockquote>
|
||||
<p><strong>Note:</strong></p>
|
||||
|
||||
<p>The <code>rancher/rancher</code> container is hosted on <a href="https://hub.docker.com/r/rancher/rancher/tags/">DockerHub</a>. If you don't have access to DockerHub, or you are installing Rancher without an Internet connection, refer to how to prepare for an <a href="/docs/rancher/v2.x/en/installation/air-gap-installation/">Air Gap Installation</a>.</p>
|
||||
<p><strong>Note:</strong></p>
|
||||
<p>For a list of other Rancher Server tags available, refer to <a href="/docs/rancher/v2.x/en/installation/server-tags/">Rancher Server Tags</a>.</p>
|
||||
|
||||
<p><strong>Notes:</strong></p>
|
||||
<ul>
|
||||
<li>If you are using RancherOS, make sure you switch the Docker engine to a supported version using <code>sudo ros engine switch docker-17.03.2-ce</code>
|
||||
</li>
|
||||
<li>The <code>rancher/rancher</code> container is hosted on <a href="https://hub.docker.com/r/rancher/rancher/tags/">DockerHub</a>. If you don't have access to DockerHub, or you are installing Rancher without an Internet connection, refer to how to prepare for an <a href="/docs/rancher/v2.x/en/installation/air-gap-installation/">Air Gap Installation</a>.</li>
|
||||
</ul>
|
||||
</blockquote>
|
||||
|
||||
@@ -1,9 +1,7 @@
|
||||
<div>
|
||||
<ul>
|
||||
<li>
|
||||
<p>Docker</p>
|
||||
<blockquote><strong>Note:</strong>If you are using RancherOS, make sure you switch the Docker engine to a supported version using <code>sudo ros engine switch docker-17.03.2-ce</code></blockquote>
|
||||
<p><strong>Supported Versions</strong></p>
|
||||
|
||||
<p>A supported version of <a href="https://www.docker.com/">Docker</a> is required.</p>
|
||||
<p>Supported Versions:</p>
|
||||
<ul>
|
||||
<li><code>1.12.6</code></li>
|
||||
<li><code>1.13.1</code></li>
|
||||
@@ -11,6 +9,5 @@
|
||||
</ul>
|
||||
<br/>
|
||||
<p><a href="https://docs.docker.com/install/">Docker Documentation: Installation Instructions</a></p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 57 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 85 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 158 KiB |
Reference in New Issue
Block a user