public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-05-05 12:43:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove unneeded intermediate folders

Browse Source
This commit is contained in:
Billy Tat
2022-08-17 10:23:03 -07:00
parent 506e174643
commit 07355d1446
1146 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
versioned_docs/version-2.5/installation/other-installation-methods/single-node-docker/advanced/advanced.md
+117
View File
@@ -0,0 +1,117 @@
---
title: Advanced Options for Docker Installs
weight: 5
aliases:
- /rancher/v2.x/en/installation/other-installation-methods/single-node-docker/advanced/
---
When installing Rancher, there are several [advanced options]({{<baseurl>}}/rancher/v2.5/en/installation/options/) that can be enabled:
- [Custom CA Certificate](#custom-ca-certificate)
- [API Audit Log](#api-audit-log)
- [TLS Settings](#tls-settings)
- [Air Gap](#air-gap)
- [Persistent Data](#persistent-data)
- [Running `rancher/rancher` and `rancher/rancher-agent` on the Same Node](#running-rancher-rancher-and-rancher-rancher-agent-on-the-same-node)
### Custom CA Certificate
If you want to configure Rancher to use a CA root certificate to be used when validating services, you would start the Rancher container sharing the directory that contains the CA root certificate.
Use the command example to start a Rancher container with your private CA certificates mounted.
- The volume flag (`-v`) should specify the host directory containing the CA root certificates.
- The environment variable flag (`-e`) in combination with `SSL_CERT_DIR` and directory 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.
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
-v /host/certs:/container/certs \
-e SSL_CERT_DIR="/container/certs" \
--privileged \
rancher/rancher:latest
```
### API Audit Log
The API Audit Log records all the user and system transactions made through Rancher server.
The API Audit Log writes to `/var/log/auditlog` inside the rancher container by default. Share that directory as a volume and set your `AUDIT_LEVEL` to enable the log.
See [API Audit Log]({{<baseurl>}}/rancher/v2.5/en/installation/api-auditing) for more information and options.
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
-v /var/log/rancher/auditlog:/var/log/auditlog \
-e AUDIT_LEVEL=1 \
--privileged \
rancher/rancher:latest
```
### TLS settings
To set a different TLS configuration, you can use the `CATTLE_TLS_MIN_VERSION` and `CATTLE_TLS_CIPHERS` environment variables. For example, to configure TLS 1.0 as minimum accepted TLS version:
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
-e CATTLE_TLS_MIN_VERSION="1.0" \
--privileged \
rancher/rancher:latest
```
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
See [TLS settings]({{<baseurl>}}/rancher/v2.5/en/admin-settings/tls-settings) for more information and options.
### Air Gap
If you are visiting this page to complete an 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. 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
Rancher uses etcd as a datastore. When Rancher is installed with Docker, the embedded etcd is being used. The persistent data is at the following path in the container: `/var/lib/rancher`.
You can bind mount a host volume to this location to preserve data on the host it is running on:
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
-v /opt/rancher:/var/lib/rancher \
--privileged \
rancher/rancher:latest
```
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
### 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.
If a node is added to a cluster, it deploys the nginx ingress controller which will use port 80 and 443. This will conflict with the default ports we advise to expose for the `rancher/rancher` container.
Please note that this setup is not recommended for production use, but can be convenient for development/demo purposes.
To change the host ports mapping, replace the following part `-p 80:80 -p 443:443` with `-p 8080:80 -p 8443:443`:
```
docker run -d --restart=unless-stopped \
-p 8080:80 -p 8443:443 \
--privileged \
rancher/rancher:latest
```
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
versioned_docs/version-2.5/installation/other-installation-methods/single-node-docker/proxy/proxy.md
+46
View File
@@ -0,0 +1,46 @@
---
title: HTTP Proxy Configuration
weight: 251
aliases:
- /rancher/v2.5/en/installation/proxy-configuration/
- /rancher/v2.5/en/installation/single-node/proxy
- /rancher/v2.x/en/installation/other-installation-methods/single-node-docker/proxy/
---
If you operate Rancher behind a proxy and you want to access services through the proxy (such as retrieving catalogs), you must provide Rancher information about your proxy. As Rancher is written in Go, it uses the common proxy environment variables as shown below.
Make sure `NO_PROXY` contains the network addresses, network address ranges and domains that should be excluded from using the proxy.
| Environment variable | Purpose |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| HTTP_PROXY | Proxy address to use when initiating HTTP connection(s) |
| HTTPS_PROXY | Proxy address to use when initiating HTTPS connection(s) |
| NO_PROXY | Network address(es), network address range(s) and domains to exclude from using the proxy when initiating connection(s) |
> **Note** NO_PROXY must be in uppercase to use network range (CIDR) notation.
## Docker Installation
Passing environment variables to the Rancher container can be done using `-e KEY=VALUE` or `--env KEY=VALUE`. Required values for `NO_PROXY` in a [Docker Installation]({{<baseurl>}}/rancher/v2.5/en/installation/single-node-install/) are:
- `localhost`
- `127.0.0.1`
- `0.0.0.0`
- `10.0.0.0/8`
- `cattle-system.svc`
- `.svc`
- `.cluster.local`
The example below is based on a proxy server accessible at `http://192.168.0.1:3128`, and excluding usage the proxy when accessing network range `192.168.10.0/24` and every hostname under the domain `example.com`.
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
-e HTTP_PROXY="http://192.168.10.1:3128" \
-e HTTPS_PROXY="http://192.168.10.1:3128" \
-e NO_PROXY="localhost,127.0.0.1,0.0.0.0,10.0.0.0/8,cattle-system.svc,192.168.10.0/24,.svc,.cluster.local,example.com" \
--privileged \
rancher/rancher:latest
```
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
versioned_docs/version-2.5/installation/other-installation-methods/single-node-docker/single-node-docker.md
+179
View File
@@ -0,0 +1,179 @@
---
title: Installing Rancher on a Single Node Using Docker
description: For development and testing environments only, use a Docker install. Install Docker on a single Linux host, and deploy Rancher with a single Docker container.
weight: 2
aliases:
- /rancher/v2.5/en/installation/single-node-install/
- /rancher/v2.5/en/installation/single-node
- /rancher/v2.5/en/installation/other-installation-methods/single-node
- /rancher/v2.x/en/installation/requirements/installing-docker/
- /rancher/v2.x/en/installation/other-installation-methods/single-node-docker/
---
Rancher can be installed by running a single Docker container.
In this installation scenario, you'll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container.
> **Want to use an external load balancer?**
> See [Docker Install with an External Load Balancer]({{<baseurl>}}/rancher/v2.5/en/installation/options/single-node-install-external-lb) instead.
A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version:
The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on [migrating Rancher to a new cluster.]({{<baseurl>}}/rancher/v2.5/en/backups/migrating-rancher)
### Privileged Access for Rancher v2.5+
When the Rancher server is deployed in the Docker container, a local Kubernetes cluster is installed within the container for Rancher to use. Because many features of Rancher run as deployments, and privileged mode is required to run containers within containers, you will need to install Rancher with the `--privileged` option.
# Requirements for OS, Docker, Hardware, and Networking
Make sure that your node fulfills the general [installation requirements.]({{<baseurl>}}/rancher/v2.5/en/installation/requirements/)
# 1. Provision Linux Host
Provision a single Linux host according to our [Requirements]({{<baseurl>}}/rancher/v2.5/en/installation/requirements) to launch your Rancher server.
# 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.
> **Do you want to...**
>
> - Use a proxy? See [HTTP Proxy Configuration]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/proxy/)
> - Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/advanced/#custom-ca-certificate/)
> - Complete an Air Gap Installation? See [Air Gap: Docker Install]({{<baseurl>}}/rancher/v2.5/en/installation/air-gap-single-node/)
> - Record all transactions with the Rancher API? See [API Auditing](./advanced/#api-audit-log)
Choose from the following options:
- [Option A: Default Rancher-generated Self-signed Certificate](#option-a-default-rancher-generated-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 a Recognized CA](#option-c-bring-your-own-certificate-signed-by-a-recognized-ca)
- [Option D: Let's Encrypt Certificate](#option-d-let-s-encrypt-certificate)
### Option A: Default Rancher-generated Self-signed Certificate
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.
Log into your Linux host, and then run the minimum installation command below.
As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5)
```bash
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
--privileged \
rancher/rancher:latest
```
### 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 using [OpenSSL](https://www.openssl.org/) or another method of your choice.
>
> - The certificate files must be in PEM format.
> - 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 [Certificate Troubleshooting.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/troubleshooting)
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.
| Placeholder | Description |
| ------------------- | --------------------- |
| `<CERT_DIRECTORY>` | The path to the directory containing your certificate files. |
| `<FULL_CHAIN.pem>` | The path to your full certificate chain. |
| `<PRIVATE_KEY.pem>` | The path to the private key for your certificate. |
| `<CA_CERTS.pem>` | The path to the certificate authority's certificate. |
As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5)
```bash
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
-v /<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 \
--privileged \
rancher/rancher:latest
```
### Option C: Bring Your Own Certificate, Signed by a Recognized CA
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.
> **Prerequisites:**
>
> - The certificate files must be in PEM format.
> - 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 [Certificate Troubleshooting.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/troubleshooting)
After obtaining your certificate, run the Docker command below.
- 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.
- Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher.
| Placeholder | Description |
| ------------------- | ----------------------------- |
| `<CERT_DIRECTORY>` | The path to the directory containing your certificate files. |
| `<FULL_CHAIN.pem>` | The path to your full certificate chain. |
| `<PRIVATE_KEY.pem>` | The path to the private key for your certificate. |
As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5)
```bash
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
-v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
-v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
--privileged \
rancher/rancher:latest \
--no-cacerts
```
### 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/).
For production environments, you also have the option 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:**
>
> - Let's Encrypt is an Internet service. Therefore, this option cannot be used in an internal/air gapped network.
> - 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.
After you fulfill the prerequisites, you can install Rancher using a Let's Encrypt certificate by running the following command.
| Placeholder | Description |
| ----------------- | ------------------- |
| `<YOUR.DNS.NAME>` | Your domain address |
As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5)
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
--privileged \
rancher/rancher:latest \
--acme-domain <YOUR.DNS.NAME>
```
## Advanced Options
When installing Rancher on a single node with Docker, there are several advanced options that can be enabled:
- Custom CA Certificate
- API Audit Log
- TLS Settings
- Air Gap
- Persistent Data
- Running `rancher/rancher` and `rancher/rancher-agent` on the Same Node
Refer to [this page](./advanced) for details.
## Troubleshooting
Refer to [this page](./troubleshooting) for frequently asked questions and troubleshooting tips.
## What's Next?
- **Recommended:** Review [Single Node Backup and Restore]({{<baseurl>}}/rancher/v2.5/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.5/en/cluster-provisioning/).
versioned_docs/version-2.5/installation/other-installation-methods/single-node-docker/single-node-rollbacks/single-node-rollbacks.md
+88
View File
@@ -0,0 +1,88 @@
---
title: Rolling Back Rancher Installed with Docker
weight: 1015
aliases:
- /rancher/v2.5/en/upgrades/single-node-rollbacks
- /rancher/v2.5/en/upgrades/rollbacks/single-node-rollbacks
- /rancher/v2.x/en/installation/other-installation-methods/single-node-docker/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 [Docker Upgrade]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/single-node-upgrades). 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.
<sup>Terminal <code>docker ps</code> Command, Displaying Where to Find <code>&lt;PRIOR_RANCHER_VERSION&gt;</code> and <code>&lt;RANCHER_CONTAINER_NAME&gt;</code></sup>![Placeholder Reference]({{<baseurl>}}/img/rancher/placeholder-ref-2.png)
| 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 latest 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 before upgrade. Replace the `<PRIOR_RANCHER_VERSION>` with that version.
For example, if you were running Rancher v2.0.5 before upgrade, pull v2.0.5.
```
docker pull rancher/rancher:<PRIOR_RANCHER_VERSION>
```
1. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_NAME>` with the name of your Rancher container.
```
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 [Docker Upgrade]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/single-node-upgrades) 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 [Docker Upgrade]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/single-node-upgrades), 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. 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-<RANCHER_VERSION>-<DATE>.tar.gz"
```
1. Start a new Rancher Server container with the `<PRIOR_RANCHER_VERSION>` tag placeholder pointing to the data container.
```
docker run -d --volumes-from rancher-data \
--restart=unless-stopped \
-p 80:80 -p 443:443 \
--privileged \
rancher/rancher:<PRIOR_RANCHER_VERSION>
```
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
>**Note:** _Do not_ stop the rollback after initiating it, even if the rollback process seems longer than expected. Stopping the rollback may result in database issues during future upgrades.
1. Wait a few moments and then open Rancher in a web browser. Confirm that the rollback succeeded and that your data is restored.
**Result:** Rancher is rolled back to its version and data state before upgrade.
versioned_docs/version-2.5/installation/other-installation-methods/single-node-docker/single-node-upgrades/single-node-upgrades.md
+377
View File
@@ -0,0 +1,377 @@
---
title: Upgrading Rancher Installed with Docker
weight: 1010
aliases:
- /rancher/v2.5/en/upgrades/single-node-upgrade/
- /rancher/v2.5/en/upgrades/upgrades/single-node-air-gap-upgrade
- /rancher/v2.5/en/upgrades/upgrades/single-node
- /rancher/v2.5/en/upgrades/upgrades/single-node-upgrade/
- /rancher/v2.5/en/installation/install-rancher-on-k8s/upgrades/upgrades/single-node/
- /rancher/v2.x/en/installation/other-installation-methods/single-node-docker/single-node-upgrades/
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
The following instructions will guide you through upgrading a Rancher server that was installed with Docker.
# Prerequisites
- **Review the [known upgrade issues]({{<baseurl>}}/rancher/v2.5/en/installation/install-rancher-on-k8s/upgrades/#known-upgrade-issues) in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12) Note that upgrades to or from any chart in the [rancher-alpha repository]({{<baseurl>}}/rancher/v2.5/en/installation/install-rancher-on-k8s/chart-options/#helm-chart-repositories/) aren’t supported.
- **For [air gap installs only,]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/air-gap) collect and populate images for the new Rancher server version.** Follow the guide to [populate your private registry]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/air-gap/populate-private-registry/) with the images for the Rancher version that you want to upgrade to.
# Placeholder Review
During upgrade, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (`<EXAMPLE>`).
Here's an **example** of a command with a placeholder:
```
docker stop <RANCHER_CONTAINER_NAME>
```
In this command, `<RANCHER_CONTAINER_NAME>` is the name of your Rancher container.
# Get Data for Upgrade Commands
To obtain the data to replace the placeholders, run:
```
docker ps
```
Write down or copy this information before starting the upgrade.
<sup>Terminal <code>docker ps</code> Command, Displaying Where to Find <code>&lt;RANCHER_CONTAINER_TAG&gt;</code> and <code>&lt;RANCHER_CONTAINER_NAME&gt;</code></sup>
![Placeholder Reference]({{<baseurl>}}/img/rancher/placeholder-ref.png)
| Placeholder | Example | Description |
| -------------------------- | -------------------------- | --------------------------------------------------------- |
| `<RANCHER_CONTAINER_TAG>` | `v2.1.3` | The rancher/rancher image you pulled for initial install. |
| `<RANCHER_CONTAINER_NAME>` | `festive_mestorf` | The name of your Rancher container. |
| `<RANCHER_VERSION>` | `v2.1.3` | The version of Rancher that you're creating a backup for. |
| `<DATE>` | `2018-12-19` | 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.
# 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:
- [1. Create a copy of the data from your Rancher server container](#1-create-a-copy-of-the-data-from-your-rancher-server-container)
- [2. Create a backup tarball](#2-create-a-backup-tarball)
- [3. Pull the new Docker image](#3-pull-the-new-docker-image)
- [4. Start the new Rancher server container](#4-start-the-new-rancher-server-container)
- [5. Verify the Upgrade](#5-verify-the-upgrade)
- [6. Clean up your old Rancher server container](#6-clean-up-your-old-rancher-server-container)
# 1. 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 `<RANCHER_CONTAINER_NAME>` with the name of your Rancher container.
```
docker stop <RANCHER_CONTAINER_NAME>
```
1. <a id="backup"></a>Use the command below, replacing each placeholder, to create a data container from the Rancher container that you just stopped.
```
docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data rancher/rancher:<RANCHER_CONTAINER_TAG>
```
# 2. Create a backup tarball
1. <a id="tarball"></a>From the data container that you just created (<code>rancher-data</code>), create a backup tarball (<code>rancher-data-backup-&lt;RANCHER_VERSION&gt;-&lt;DATE&gt;.tar.gz</code>).
This tarball will serve as a rollback point if something goes wrong during upgrade. Use the following command, replacing each placeholder.
```
docker run --volumes-from rancher-data -v "$PWD:/backup" --rm busybox 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 `ls` command to confirm that the backup tarball was created. It will have a name similar to `rancher-data-backup-<RANCHER_VERSION>-<DATE>.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.
# 3. Pull the New Docker Image
Pull the image of the Rancher version that you want to upgrade to.
Placeholder | Description
------------|-------------
`<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version]({{<baseurl>}}/rancher/v2.5/en/installation/resources/chart-options/) that you want to upgrade to.
```
docker pull rancher/rancher:<RANCHER_VERSION_TAG>
```
# 4. Start the New Rancher Server Container
Start a new Rancher server container using the data from the `rancher-data` container. Remember to pass in all the environment variables that you had used when you started the original container.
>**Important:** _Do not_ stop the upgrade after initiating it, even if the upgrade process seems longer than expected. Stopping the upgrade may result in database migration errors during future upgrades.
If you used a proxy, see [HTTP Proxy Configuration.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/proxy/)
If you configured a custom CA root certificate to access your services, see [Custom CA root certificate.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/advanced/#custom-ca-certificate)
If you are recording all transactions with the Rancher API, see [API Auditing]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/advanced/#api-audit-log)
To see the command to use when starting the new Rancher server container, choose from the following options:
- Docker Upgrade
- Docker Upgrade for Air Gap Installs
<Tabs>
<TabItem value="Docker Upgrade">
Select which option you had installed Rancher server
### Option A: Default Self-Signed Certificate
<details id="option-a">
<summary>Click to expand</summary>
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
------------|-------------
`<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version]({{<baseurl>}}/rancher/v2.5/en/installation/resources/chart-options/) that you want to upgrade to.
```
docker run -d --volumes-from rancher-data \
--restart=unless-stopped \
-p 80:80 -p 443:443 \
--privileged \
rancher/rancher:<RANCHER_VERSION_TAG>
```
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
</details>
### Option B: Bring Your Own Certificate: Self-Signed
<details id="option-b">
<summary>Click to expand</summary>
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. In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates.
Placeholder | Description
------------|-------------
`<CERT_DIRECTORY>` | The path to the directory containing your certificate files.
`<FULL_CHAIN.pem>` | The path to your full certificate chain.
`<PRIVATE_KEY.pem>` | The path to the private key for your certificate.
`<CA_CERTS.pem>` | The path to the certificate authority's certificate.
`<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version]({{<baseurl>}}/rancher/v2.5/en/installation/resources/chart-options/) that you want to upgrade to.
```
docker run -d --volumes-from rancher-data \
--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 \
--privileged \
rancher/rancher:<RANCHER_VERSION_TAG>
```
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
</details>
### Option C: Bring Your Own Certificate: Signed by Recognized CA
<details id="option-c">
<summary>Click to expand</summary>
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. 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 [Certificate Troubleshooting.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/troubleshooting)
Placeholder | Description
------------|-------------
`<CERT_DIRECTORY>` | The path to the directory containing your certificate files.
`<FULL_CHAIN.pem>` | The path to your full certificate chain.
`<PRIVATE_KEY.pem>` | The path to the private key for your certificate.
`<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version]({{<baseurl>}}/rancher/v2.5/en/installation/resources/chart-options/) that you want to upgrade to.
```
docker run -d --volumes-from rancher-data \
--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 \
--privileged \
rancher/rancher:<RANCHER_VERSION_TAG> \
--no-cacerts
```
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
</details>
### Option D: Let's Encrypt Certificate
<details id="option-d">
<summary>Click to expand</summary>
>**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
------------|-------------
`<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version]({{<baseurl>}}/rancher/v2.5/en/installation/resources/chart-options/) that you want to upgrade to.
`<YOUR.DNS.NAME>` | The domain address that you had originally started with
```
docker run -d --volumes-from rancher-data \
--restart=unless-stopped \
-p 80:80 -p 443:443 \
--privileged \
rancher/rancher:<RANCHER_VERSION_TAG> \
--acme-domain <YOUR.DNS.NAME>
```
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
</details>
</TabItem>
<TabItem value="Docker Air Gap Upgrade">
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
When starting the new Rancher server container, choose from the following options:
### Option A: Default Self-Signed Certificate
<details id="option-a">
<summary>Click to expand</summary>
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
------------|-------------
`<REGISTRY.YOURDOMAIN.COM:PORT>` | Your private registry URL and port.
`<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version]({{<baseurl>}}/rancher/v2.5/en/installation/resources/chart-options/) 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=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
-e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts
--privileged \
<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>
```
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
</details>
### Option B: Bring Your Own Certificate: Self-Signed
<details id="option-b">
<summary>Click to expand</summary>
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. 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 [Certificate Troubleshooting.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/troubleshooting)
Placeholder | Description
------------|-------------
`<CERT_DIRECTORY>` | The path to the directory containing your certificate files.
`<FULL_CHAIN.pem>` | The path to your full certificate chain.
`<PRIVATE_KEY.pem>` | The path to the private key for your certificate.
`<CA_CERTS.pem>` | The path to the certificate authority's certificate.
`<REGISTRY.YOURDOMAIN.COM:PORT>` | Your private registry URL and port.
`<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version]({{<baseurl>}}/rancher/v2.5/en/installation/resources/chart-options/) that you want to upgrade to.
```
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 \
-e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
-e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts
--privileged \
<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>
```
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
</details>
### Option C: Bring Your Own Certificate: Signed by Recognized CA
<details id="option-c">
<summary>Click to expand</summary>
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. 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 [Certificate Troubleshooting.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/troubleshooting)
Placeholder | Description
------------|-------------
`<CERT_DIRECTORY>` | The path to the directory containing your certificate files.
`<FULL_CHAIN.pem>` | The path to your full certificate chain.
`<PRIVATE_KEY.pem>` | The path to the private key for your certificate.
`<REGISTRY.YOURDOMAIN.COM:PORT>` | Your private registry URL and port.
`<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version]({{<baseurl>}}/rancher/v2.5/en/installation/resources/chart-options/) 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 /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
-v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
-e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
-e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts
--privileged
<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>
```
As of Rancher v2.5, privileged access is [required.]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
</details>
</TabItem>
</Tabs>
**Result:** You have upgraded Rancher. Data from your upgraded server is now saved to the `rancher-data` container for use in future upgrades.
# 5. 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.0-v2.4/en/installation/install-rancher-on-k8s/upgrades/namespace-migration).
# 6. Clean up Your Old Rancher Server Container
Remove the previous Rancher server container. If you only stop the previous Rancher server container (and don't remove it), the container may restart after the next server reboot.
# Rolling Back
If your upgrade does not complete successfully, you can roll back Rancher server and its data back to its last healthy state. For more information, see [Docker Rollback]({{<baseurl>}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks).
versioned_docs/version-2.5/installation/other-installation-methods/single-node-docker/troubleshooting/troubleshooting.md
+90
View File
@@ -0,0 +1,90 @@
---
title: Certificate Troubleshooting
weight: 4
aliases:
- /rancher/v2.x/en/installation/other-installation-methods/single-node-docker/troubleshooting/
---
### How Do I Know if My Certificates are in PEM Format?
You can recognize the PEM format by the following traits:
- The file begins with the following header:
```
-----BEGIN CERTIFICATE-----
```
- The header is followed by a long string of characters.
- The file ends with a footer:
-----END CERTIFICATE-----
PEM Certificate Example:
```
----BEGIN CERTIFICATE-----
MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
... more lines
VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END CERTIFICATE-----
```
PEM Certificate Key Example:
```
-----BEGIN RSA PRIVATE KEY-----
MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
... more lines
VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END RSA PRIVATE KEY-----
```
If your key looks like the example below, see [Converting a Certificate Key From PKCS8 to PKCS1.](#converting-a-certificate-key-from-pkcs8-to-pkcs1)
```
-----BEGIN PRIVATE KEY-----
MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
... more lines
VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END PRIVATE KEY-----
```
### Converting a Certificate Key From PKCS8 to PKCS1
If you are using a PKCS8 certificate key file, Rancher will log the following line:
```
ListenConfigController cli-config [listener] failed with : failed to read private key: asn1: structure error: tags don't match (2 vs {class:0 tag:16 length:13 isCompound:true})
```
To make this work, you will need to convert the key from PKCS8 to PKCS1 using the command below:
```
openssl rsa -in key.pem -out convertedkey.pem
```
You can now use `convertedkey.pem` as certificate key file for Rancher.
### What is the Order of Certificates if I Want to Add My Intermediate(s)?
The order of adding certificates is as follows:
```
-----BEGIN CERTIFICATE-----
%YOUR_CERTIFICATE%
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
%YOUR_INTERMEDIATE_CERTIFICATE%
-----END CERTIFICATE-----
```
### How Do I Validate My Certificate Chain?
You can validate the certificate chain by using the `openssl` binary. If the output of the command (see the command example below) ends with `Verify return code: 0 (ok)`, your certificate chain is valid. The `ca.pem` file must be the same as you added to the `rancher/rancher` container.
When using a certificate signed by a recognized Certificate Authority, you can omit the `-CAfile` parameter.
Command:
```
openssl s_client -CAfile ca.pem -connect rancher.yourdomain.com:443
...
Verify return code: 0 (ok)
```