Updating notes

2026-09-25 20:48:11 +00:00 · 2022-07-08 16:18:20 -04:00
parent 6b9095d077
commit b6237a5a7f
43 changed files with 518 additions and 190 deletions
@@ -13,7 +13,11 @@ Make sure `NO_PROXY` contains the network addresses, network address ranges and
 | 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.
+:::note Important:
+
+NO_PROXY must be in uppercase to use network range (CIDR) notation.
+
+:::

 ## Docker Installation

@@ -8,8 +8,11 @@ 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.6/en/installation/resources/advanced/single-node-install-external-lb) instead.
+:::note Want to use an external load balancer?
+
+See [Docker Install with an External Load Balancer]({{<baseurl>}}/rancher/v2.6/en/installation/resources/advanced/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:

@@ -31,12 +34,14 @@ Provision a single Linux host according to our [Requirements]({{<baseurl>}}/ranc

 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.6/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.6/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.6/en/installation/other-installation-methods/air-gap/)
-> - Record all transactions with the Rancher API? See [API Auditing](./advanced/#api-audit-log)
+:::tip Do you want to..
+
+- Use a proxy? See [HTTP Proxy Configuration]({{<baseurl>}}/rancher/v2.6/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.6/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.6/en/installation/other-installation-methods/air-gap/)
+- Record all transactions with the Rancher API? See [API Auditing](./advanced/#api-audit-log)
+
+:::

 Choose from the following options:

@@ -62,11 +67,14 @@ docker run -d --restart=unless-stopped \
 ### 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.6/en/installation/other-installation-methods/single-node-docker/troubleshooting)
+:::note 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.6/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.

@@ -95,10 +103,12 @@ In production environments where you're exposing an app publicly, you would use

 The Docker install is not recommended for production. These instructions are provided for testing and development purposes only.

-> **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.6/en/installation/other-installation-methods/single-node-docker/troubleshooting)
+:::note 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.6/en/installation/other-installation-methods/single-node-docker/troubleshooting)
+
+:::

 After obtaining your certificate, run the Docker command below.

@@ -125,17 +135,23 @@ docker run -d --restart=unless-stopped \

 ### 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/).
+:::caution
+
+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.

 The Docker install is not recommended for production. These instructions are provided for testing and development purposes only.

-> **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.
+:::note 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.

@@ -37,7 +37,11 @@ You can obtain `<PRIOR_RANCHER_VERSION>` and `<RANCHER_CONTAINER_NAME>` by loggi

 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.
+:::danger
+
+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.

@@ -78,7 +82,11 @@ If you have issues upgrading Rancher, roll it back to its latest known healthy s
    ```
    Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
    
-    >**Note:** _Do not_ stop the rollback after initiating it, even if the rollback process seems longer than expected. Stopping the rollback may result in database issues during future upgrades.
+    :::note Important:
+    
+    **_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.

@@ -5,7 +5,11 @@ weight: 1010

 The following instructions will guide you through upgrading a Rancher server that was installed with Docker.

-> **Docker installs are not supported in production environments.** These instructions are provided for testing and development purposes only. If you have already deployed a Docker install in production and need to upgrade to a new Rancher version, we recommend [migrating to the Helm chart install]({{<baseurl>}}/rancher/v2.6/en/backups/migrating-rancher/) before upgrading.
+:::note Important:
+
+**Docker installs are not supported in production environments.** These instructions are provided for testing and development purposes only. If you have already deployed a Docker install in production and need to upgrade to a new Rancher version, we recommend [migrating to the Helm chart install]({{<baseurl>}}/rancher/v2.6/en/backups/migrating-rancher/) before upgrading.
+
+:::

 # Prerequisites

@@ -112,7 +116,11 @@ docker pull rancher/rancher:<RANCHER_VERSION_TAG>

 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.
+:::note 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.6/en/installation/other-installation-methods/single-node-docker/proxy/)

@@ -158,7 +166,11 @@ Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/othe

 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.
+:::note 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
 ------------|-------------
@@ -189,7 +201,11 @@ Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/othe

 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.6/en/installation/other-installation-methods/single-node-docker/troubleshooting)
+:::note 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.6/en/installation/other-installation-methods/single-node-docker/troubleshooting)
+
+:::

 Placeholder | Description
 ------------|-------------
@@ -216,14 +232,20 @@ Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/othe

 {{% accordion id="option-d" label="Click to expand" %}}

->**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/).
+:::caution
+
+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.
+:::note 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
 ------------|-------------
@@ -280,7 +302,11 @@ Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/othe

 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.6/en/installation/other-installation-methods/single-node-docker/troubleshooting)
+:::note 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. For an example, see [Certificate Troubleshooting.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting)
+
+:::

 Placeholder | Description
 ------------|-------------
@@ -311,7 +337,11 @@ Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/othe

 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.6/en/installation/other-installation-methods/single-node-docker/troubleshooting)
+  :::note 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.6/en/installation/other-installation-methods/single-node-docker/troubleshooting)
+
+  :::

 Placeholder | Description
 ------------|-------------
@@ -321,7 +351,11 @@ 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.6/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.
+:::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 \
@@ -346,10 +380,11 @@ privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/othe

 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).
+:::note 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