mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-26 21:18:04 +00:00
Remove unneeded intermediate folders
This commit is contained in:
Billy Tat
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: Air Gapped Helm CLI Install
|
||||
weight: 1
|
||||
---
|
||||
|
||||
This section is about using the Helm CLI to install the Rancher server in an air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.
|
||||
|
||||
The installation steps differ depending on whether Rancher is installed on an RKE Kubernetes cluster, a K3s Kubernetes cluster, or a single Docker container.
|
||||
|
||||
For more information on each installation option, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/)
|
||||
|
||||
Throughout the installation instructions, there will be _tabs_ for each installation option.
|
||||
|
||||
> **Important:** If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation.
|
||||
|
||||
# Installation Outline
|
||||
|
||||
1. [Set up infrastructure and private registry]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/prepare-nodes/)
|
||||
2. [Collect and publish images to your private registry]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/populate-private-registry/)
|
||||
3. [Set up a Kubernetes cluster (Skip this step for Docker installations)]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/launch-kubernetes/)
|
||||
4. [Install Rancher]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/install-rancher/)
|
||||
|
||||
# Upgrades
|
||||
|
||||
To upgrade Rancher with Helm CLI in an air gap environment, follow [this procedure.]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/upgrades/)
|
||||
|
||||
### [Next: Prepare your Node(s)]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/prepare-nodes/)
|
||||
+133
@@ -0,0 +1,133 @@
|
||||
---
|
||||
title: Docker Install Commands
|
||||
weight: 1
|
||||
---
|
||||
|
||||
The Docker installation is for Rancher users who want to test out Rancher.
|
||||
|
||||
Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a `docker run` command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.
|
||||
|
||||
The backup application can be used to migrate the Rancher server from a Docker install to a Kubernetes install using [these steps.]({{<baseurl>}}/rancher/v2.6/en/backups/migrating-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.
|
||||
|
||||
| Environment Variable Key | Environment Variable Value | Description |
|
||||
| -------------------------------- | -------------------------------- | ---- |
|
||||
| `CATTLE_SYSTEM_DEFAULT_REGISTRY` | `<REGISTRY.YOURDOMAIN.COM:PORT>` | Configure Rancher server to always pull from your private registry when provisioning clusters. |
|
||||
| `CATTLE_SYSTEM_CATALOG` | `bundled` | Configure Rancher server to use the packaged copy of Helm system charts. The [system charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. |
|
||||
|
||||
> **Do you want to..**.
|
||||
>
|
||||
> - Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{<baseurl>}}/rancher/v2.6/en/installation/resources/custom-ca-root-certificate/).
|
||||
> - Record all transactions with the Rancher API? See [API Auditing]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/advanced/#api-audit-log).
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
### Option A: Default Self-Signed Certificate
|
||||
|
||||
<details id="option-a">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
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 installation command below. When entering the command, use the table below to replace each placeholder.
|
||||
|
||||
| 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 install. |
|
||||
|
||||
Privileged access is [required.](#privileged-access-for-rancher)
|
||||
|
||||
```
|
||||
docker run -d --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>
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Option B: Bring Your Own Certificate: Self-Signed
|
||||
|
||||
<details id="option-b">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
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:**
|
||||
> From a computer with an internet connection, 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, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. 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. |
|
||||
| `<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 install. |
|
||||
|
||||
Privileged access is [required.](#privileged-access-for-rancher)
|
||||
|
||||
```
|
||||
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>
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Option C: Bring Your Own Certificate: Signed by Recognized CA
|
||||
|
||||
<details id="option-c">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
In development or testing 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.
|
||||
|
||||
> **Prerequisite:** The certificate files must be in PEM format.
|
||||
|
||||
After obtaining your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.
|
||||
|
||||
| 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.6/en/installation/resources/chart-options/) that you want to install. |
|
||||
|
||||
> **Note:** Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher.
|
||||
|
||||
Privileged access is [required.](#privileged-access-for-rancher)
|
||||
|
||||
```
|
||||
docker run -d --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>
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
|
||||
> **Note:** If you don't intend to send telemetry data, opt out [telemetry]({{<baseurl>}}/rancher/v2.6/en/faq/telemetry/) during the initial login.
|
||||
|
||||
+245
@@ -0,0 +1,245 @@
|
||||
---
|
||||
title: 4. Install Rancher
|
||||
weight: 400
|
||||
---
|
||||
|
||||
This section is about how to deploy Rancher for your air gapped environment in a high-availability Kubernetes installation. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.
|
||||
|
||||
### Privileged Access for Rancher
|
||||
|
||||
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.
|
||||
|
||||
# Docker Instructions
|
||||
|
||||
If you want to continue the air gapped installation using Docker commands, skip the rest of this page and follow the instructions on [this page.](./docker-install-commands)
|
||||
|
||||
# Kubernetes Instructions
|
||||
|
||||
Rancher recommends installing Rancher on a Kubernetes cluster. A highly available Kubernetes install is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails.
|
||||
|
||||
This section describes installing Rancher:
|
||||
|
||||
- [1. Add the Helm Chart Repository](#1-add-the-helm-chart-repository)
|
||||
- [2. Choose your SSL Configuration](#2-choose-your-ssl-configuration)
|
||||
- [3. Render the Rancher Helm Template](#3-render-the-rancher-helm-template)
|
||||
- [4. Install Rancher](#4-install-rancher)
|
||||
|
||||
# 1. Add the Helm Chart Repository
|
||||
|
||||
From a system that has access to the internet, fetch the latest Helm chart and copy the resulting manifests to a system that has access to the Rancher server cluster.
|
||||
|
||||
1. If you haven't already, install `helm` locally on a workstation that has internet access. Note: Refer to the [Helm version requirements]({{<baseurl>}}/rancher/v2.6/en/installation/resources/helm-version) to choose a version of Helm to install Rancher.
|
||||
|
||||
2. Use `helm repo add` command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see [Choosing a Version of Rancher]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#helm-chart-repositories).
|
||||
{{< release-channel >}}
|
||||
```
|
||||
helm repo add rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>
|
||||
```
|
||||
|
||||
3. Fetch the latest Rancher chart. This will pull down the chart and save it in the current directory as a `.tgz` file.
|
||||
```plain
|
||||
helm fetch rancher-<CHART_REPO>/rancher
|
||||
```
|
||||
|
||||
If you require a specific version of Rancher, you can fetch this with the Helm `--version` parameter like in the following example:
|
||||
```plain
|
||||
helm fetch rancher-stable/rancher --version=v2.4.8
|
||||
```
|
||||
|
||||
# 2. Choose your SSL Configuration
|
||||
|
||||
Rancher Server is designed to be secure by default and requires SSL/TLS configuration.
|
||||
|
||||
When Rancher is installed on an air gapped Kubernetes cluster, there are two recommended options for the source of the certificate.
|
||||
|
||||
> **Note:** If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#external-tls-termination).
|
||||
|
||||
| Configuration | Chart option | Description | Requires cert-manager |
|
||||
| ------------------------------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
|
||||
| Rancher Generated Self-Signed Certificates | `ingress.tls.source=rancher` | Use certificates issued by Rancher's generated CA (self signed)<br/> This is the **default** and does not need to be added when rendering the Helm template. | yes |
|
||||
| Certificates from Files | `ingress.tls.source=secret` | Use your own certificate files by creating Kubernetes Secret(s). <br/> This option must be passed when rendering the Rancher Helm template. | no |
|
||||
|
||||
# Helm Chart Options for Air Gap Installations
|
||||
|
||||
When setting up the Rancher Helm template, there are several options in the Helm chart that are designed specifically for air gap installations.
|
||||
|
||||
| Chart Option | Chart Value | Description |
|
||||
| ----------------------- | -------------------------------- | ---- |
|
||||
| `certmanager.version` | `<version>` | Configure proper Rancher TLS issuer depending of running cert-manager version. |
|
||||
| `systemDefaultRegistry` | `<REGISTRY.YOURDOMAIN.COM:PORT>` | Configure Rancher server to always pull from your private registry when provisioning clusters. |
|
||||
| `useBundledSystemChart` | `true` | Configure Rancher server to use the packaged copy of Helm system charts. The [system charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. |
|
||||
|
||||
# 3. Render the Rancher Helm Template
|
||||
|
||||
Based on the choice your made in [2. Choose your SSL Configuration](#2-choose-your-ssl-configuration), complete one of the procedures below.
|
||||
|
||||
# Option A: Default Self-Signed Certificate
|
||||
|
||||
|
||||
By default, Rancher generates a CA and uses cert-manager to issue the certificate for access to the Rancher server interface.
|
||||
|
||||
> **Note:**
|
||||
> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade cert-manager documentation]({{<baseurl>}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/).
|
||||
|
||||
### 1. Add the cert-manager repo
|
||||
|
||||
From a system connected to the internet, add the cert-manager repo to Helm:
|
||||
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
```
|
||||
|
||||
### 2. Fetch the cert-manager chart
|
||||
|
||||
Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager).
|
||||
|
||||
**Note:** New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.
|
||||
|
||||
```plain
|
||||
helm fetch jetstack/cert-manager --version v1.7.1
|
||||
```
|
||||
|
||||
### 3. Render the cert-manager template
|
||||
|
||||
Render the cert-manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files.
|
||||
|
||||
```plain
|
||||
helm template cert-manager ./cert-manager-v1.7.1.tgz --output-dir . \
|
||||
--namespace cert-manager \
|
||||
--set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller \
|
||||
--set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook \
|
||||
--set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector \
|
||||
--set startupapicheck.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-ctl
|
||||
```
|
||||
|
||||
### 4. Download the cert-manager CRD
|
||||
|
||||
Download the required CRD file for cert-manager:
|
||||
```plain
|
||||
curl -L -o cert-manager/cert-manager-crd.yaml https://github.com/jetstack/cert-manager/releases/download/v1.7.1/cert-manager.crds.yaml
|
||||
```
|
||||
|
||||
### 5. Render the Rancher template
|
||||
|
||||
Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.
|
||||
|
||||
|
||||
Placeholder | Description
|
||||
------------|-------------
|
||||
`<VERSION>` | The version number of the output tarball.
|
||||
`<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer.
|
||||
`<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.
|
||||
`<CERTMANAGER_VERSION>` | Cert-manager version running on k8s cluster.
|
||||
|
||||
```plain
|
||||
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--no-hooks \ # prevent files for Helm hooks from being generated
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set certmanager.version=<CERTMANAGER_VERSION> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
**Optional**: To install a specific Rancher version, set the `rancherImageTag` value, example: `--set rancherImageTag=v2.5.8`
|
||||
|
||||
# Option B: Certificates From Files using Kubernetes Secrets
|
||||
|
||||
|
||||
### 1. Create secrets
|
||||
|
||||
Create Kubernetes secrets from your own certificates for Rancher to use. The common name for the cert will need to match the `hostname` option in the command below, or the ingress controller will fail to provision the site for Rancher.
|
||||
|
||||
### 2. Render the Rancher template
|
||||
|
||||
Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.
|
||||
|
||||
| Placeholder | Description |
|
||||
| -------------------------------- | ----------------------------------------------- |
|
||||
| `<VERSION>` | The version number of the output tarball. |
|
||||
| `<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer. |
|
||||
| `<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry. |
|
||||
|
||||
```plain
|
||||
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--no-hooks \ # prevent files for Helm hooks from being generated
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`:
|
||||
|
||||
```plain
|
||||
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--no-hooks \ # prevent files for Helm hooks from being generated
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set privateCA=true \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
**Optional**: To install a specific Rancher version, set the `rancherImageTag` value, example: `--set rancherImageTag=v2.3.6`
|
||||
|
||||
Then refer to [Adding TLS Secrets]({{<baseurl>}}/rancher/v2.6/en/installation/resources/tls-secrets/) to publish the certificate files so Rancher and the ingress controller can use them.
|
||||
|
||||
# 4. Install Rancher
|
||||
|
||||
Copy the rendered manifest directories to a system that has access to the Rancher server cluster to complete installation.
|
||||
|
||||
Use `kubectl` to create namespaces and apply the rendered manifests.
|
||||
|
||||
If you choose to use self-signed certificates in [B. Choose your SSL Configuration](#b-choose-your-ssl-configuration), install cert-manager.
|
||||
|
||||
### For Self-Signed Certificate Installs, Install Cert-manager
|
||||
|
||||
<details id="install-cert-manager">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
If you are using self-signed certificates, install cert-manager:
|
||||
|
||||
1. Create the namespace for cert-manager.
|
||||
```plain
|
||||
kubectl create namespace cert-manager
|
||||
```
|
||||
|
||||
1. Create the cert-manager CustomResourceDefinitions (CRDs).
|
||||
```plain
|
||||
kubectl apply -f cert-manager/cert-manager-crd.yaml
|
||||
```
|
||||
|
||||
> **Note:**
|
||||
> If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above, or else you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.
|
||||
|
||||
1. Launch cert-manager.
|
||||
```plain
|
||||
kubectl apply -R -f ./cert-manager
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Install Rancher with kubectl
|
||||
|
||||
```plain
|
||||
kubectl create namespace cattle-system
|
||||
kubectl -n cattle-system apply -R -f ./rancher
|
||||
```
|
||||
The installation is complete.
|
||||
|
||||
> **Note:** If you don't intend to send telemetry data, opt out [telemetry]({{<baseurl>}}/rancher/v2.6/en/faq/telemetry/) during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully.
|
||||
|
||||
# Additional Resources
|
||||
|
||||
These resources could be helpful when installing Rancher:
|
||||
|
||||
- [Rancher Helm chart options]({{<baseurl>}}/rancher/v2.6/en/installation/resources/chart-options/)
|
||||
- [Adding TLS secrets]({{<baseurl>}}/rancher/v2.6/en/installation/resources/tls-secrets/)
|
||||
- [Troubleshooting Rancher Kubernetes Installations]({{<baseurl>}}/rancher/v2.6/en/installation/resources/troubleshooting/)
|
||||
+226
@@ -0,0 +1,226 @@
|
||||
---
|
||||
title: '3. Install Kubernetes (Skip for Docker Installs)'
|
||||
weight: 300
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
> Skip this section if you are installing Rancher on a single node with Docker.
|
||||
|
||||
This section describes how to install a Kubernetes cluster according to our [best practices for the Rancher server environment.]({{<baseurl>}}/rancher/v2.6/en/overview/architecture-recommendations/#environment-for-kubernetes-installations) This cluster should be dedicated to run only the Rancher server.
|
||||
|
||||
Rancher can be installed on any Kubernetes cluster, including hosted Kubernetes providers.
|
||||
|
||||
The steps to set up an air-gapped Kubernetes cluster on RKE or K3s are shown below.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="K3s">
|
||||
|
||||
In this guide, we are assuming you have created your nodes in your air gapped environment and have a secure Docker private registry on your bastion server.
|
||||
|
||||
### Installation Outline
|
||||
|
||||
1. [Prepare Images Directory](#1-prepare-images-directory)
|
||||
2. [Create Registry YAML](#2-create-registry-yaml)
|
||||
3. [Install K3s](#3-install-k3s)
|
||||
4. [Save and Start Using the kubeconfig File](#4-save-and-start-using-the-kubeconfig-file)
|
||||
|
||||
### 1. Prepare Images Directory
|
||||
Obtain the images tar file for your architecture from the [releases](https://github.com/rancher/k3s/releases) page for the version of K3s you will be running.
|
||||
|
||||
Place the tar file in the `images` directory before starting K3s on each node, for example:
|
||||
|
||||
```sh
|
||||
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
|
||||
sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/
|
||||
```
|
||||
|
||||
### 2. Create Registry YAML
|
||||
Create the registries.yaml file at `/etc/rancher/k3s/registries.yaml`. This will tell K3s the necessary details to connect to your private registry.
|
||||
|
||||
The registries.yaml file should look like this before plugging in the necessary information:
|
||||
|
||||
```
|
||||
---
|
||||
mirrors:
|
||||
customreg:
|
||||
endpoint:
|
||||
- "https://ip-to-server:5000"
|
||||
configs:
|
||||
customreg:
|
||||
auth:
|
||||
username: xxxxxx # this is the registry username
|
||||
password: xxxxxx # this is the registry password
|
||||
tls:
|
||||
cert_file: <path to the cert file used in the registry>
|
||||
key_file: <path to the key file used in the registry>
|
||||
ca_file: <path to the ca file used in the registry>
|
||||
```
|
||||
|
||||
Note, at this time only secure registries are supported with K3s (SSL with custom CA).
|
||||
|
||||
For more information on private registries configuration file for K3s, refer to the [K3s documentation.]({{<baseurl>}}/k3s/latest/en/installation/private-registry/)
|
||||
|
||||
### 3. Install K3s
|
||||
|
||||
Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/)
|
||||
|
||||
To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script.
|
||||
|
||||
Obtain the K3s binary from the [releases](https://github.com/rancher/k3s/releases) page, matching the same version used to get the airgap images tar.
|
||||
Also obtain the K3s install script at https://get.k3s.io
|
||||
|
||||
Place the binary in `/usr/local/bin` on each node.
|
||||
Place the install script anywhere on each node, and name it `install.sh`.
|
||||
|
||||
Install K3s on each server:
|
||||
|
||||
```
|
||||
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh
|
||||
```
|
||||
|
||||
Install K3s on each agent:
|
||||
|
||||
```
|
||||
INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken ./install.sh
|
||||
```
|
||||
|
||||
Note, take care to ensure you replace `myserver` with the IP or valid DNS of the server and replace `mynodetoken` with the node-token from the server.
|
||||
The node-token is on the server at `/var/lib/rancher/k3s/server/node-token`
|
||||
|
||||
>**Note:** K3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gap networks.
|
||||
|
||||
### 4. Save and Start Using the kubeconfig File
|
||||
|
||||
When you installed K3s on each Rancher server node, a `kubeconfig` file was created on the node at `/etc/rancher/k3s/k3s.yaml`. This file contains credentials for full access to the cluster, and you should save this file in a secure location.
|
||||
|
||||
To use this `kubeconfig` file,
|
||||
|
||||
1. Install [kubectl,](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) a Kubernetes command-line tool.
|
||||
2. Copy the file at `/etc/rancher/k3s/k3s.yaml` and save it to the directory `~/.kube/config` on your local machine.
|
||||
3. In the kubeconfig file, the `server` directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example `k3s.yaml`:
|
||||
|
||||
```
|
||||
apiVersion: v1
|
||||
clusters:
|
||||
- cluster:
|
||||
certificate-authority-data: [CERTIFICATE-DATA]
|
||||
server: [LOAD-BALANCER-DNS]:6443 # Edit this line
|
||||
name: default
|
||||
contexts:
|
||||
- context:
|
||||
cluster: default
|
||||
user: default
|
||||
name: default
|
||||
current-context: default
|
||||
kind: Config
|
||||
preferences: {}
|
||||
users:
|
||||
- name: default
|
||||
user:
|
||||
password: [PASSWORD]
|
||||
username: admin
|
||||
```
|
||||
|
||||
**Result:** You can now use `kubectl` to manage your K3s cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using `kubectl`:
|
||||
|
||||
```
|
||||
kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces
|
||||
```
|
||||
|
||||
For more information about the `kubeconfig` file, refer to the [K3s documentation]({{<baseurl>}}/k3s/latest/en/cluster-access/) or the [official Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) about organizing cluster access using `kubeconfig` files.
|
||||
|
||||
### Note on Upgrading
|
||||
|
||||
Upgrading an air-gap environment can be accomplished in the following manner:
|
||||
|
||||
1. Download the new air-gap images (tar file) from the [releases](https://github.com/rancher/k3s/releases) page for the version of K3s you will be upgrading to. Place the tar in the `/var/lib/rancher/k3s/agent/images/` directory on each node. Delete the old tar file.
|
||||
2. Copy and replace the old K3s binary in `/usr/local/bin` on each node. Copy over the install script at https://get.k3s.io (as it is possible it has changed since the last release). Run the script again just as you had done in the past with the same environment variables.
|
||||
3. Restart the K3s service (if not restarted automatically by installer).
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="RKE">
|
||||
|
||||
We will create a Kubernetes cluster using Rancher Kubernetes Engine (RKE). Before being able to start your Kubernetes cluster, you’ll need to install RKE and create a RKE config file.
|
||||
|
||||
### 1. Install RKE
|
||||
|
||||
Install RKE by following the instructions in the [RKE documentation.]({{<baseurl>}}/rke/latest/en/installation/)
|
||||
|
||||
### 2. Create an RKE Config File
|
||||
|
||||
From a system that can access ports 22/TCP and 6443/TCP on the Linux host node(s) that you set up in a previous step, use the sample below to create a new file named `rancher-cluster.yml`.
|
||||
|
||||
This file is an RKE configuration file, which is a configuration for the cluster you're deploying Rancher to.
|
||||
|
||||
Replace values in the code sample below with help of the _RKE Options_ table. Use the IP address or DNS names of the three nodes you created.
|
||||
|
||||
> **Tip:** For more details on the options available, see the RKE [Config Options]({{<baseurl>}}/rke/latest/en/config-options/).
|
||||
|
||||
<figcaption>RKE Options</figcaption>
|
||||
|
||||
| Option | Required | Description |
|
||||
| ------------------ | -------------------- | --------------------------------------------------------------------------------------- |
|
||||
| `address` | ✓ | The DNS or IP address for the node within the air gapped network. |
|
||||
| `user` | ✓ | A user that can run Docker commands. |
|
||||
| `role` | ✓ | List of Kubernetes roles assigned to the node. |
|
||||
| `internal_address` | optional<sup>1</sup> | The DNS or IP address used for internal cluster traffic. |
|
||||
| `ssh_key_path` | | Path to the SSH private key used to authenticate to the node (defaults to `~/.ssh/id_rsa`). |
|
||||
|
||||
> <sup>1</sup> Some services like AWS EC2 require setting the `internal_address` if you want to use self-referencing security groups or firewalls.
|
||||
|
||||
```yaml
|
||||
nodes:
|
||||
- address: 10.10.3.187 # node air gap network IP
|
||||
internal_address: 172.31.7.22 # node intra-cluster IP
|
||||
user: rancher
|
||||
role: ['controlplane', 'etcd', 'worker']
|
||||
ssh_key_path: /home/user/.ssh/id_rsa
|
||||
- address: 10.10.3.254 # node air gap network IP
|
||||
internal_address: 172.31.13.132 # node intra-cluster IP
|
||||
user: rancher
|
||||
role: ['controlplane', 'etcd', 'worker']
|
||||
ssh_key_path: /home/user/.ssh/id_rsa
|
||||
- address: 10.10.3.89 # node air gap network IP
|
||||
internal_address: 172.31.3.216 # node intra-cluster IP
|
||||
user: rancher
|
||||
role: ['controlplane', 'etcd', 'worker']
|
||||
ssh_key_path: /home/user/.ssh/id_rsa
|
||||
|
||||
private_registries:
|
||||
- url: <REGISTRY.YOURDOMAIN.COM:PORT> # private registry url
|
||||
user: rancher
|
||||
password: '*********'
|
||||
is_default: true
|
||||
```
|
||||
|
||||
### 3. Run RKE
|
||||
|
||||
After configuring `rancher-cluster.yml`, bring up your Kubernetes cluster:
|
||||
|
||||
```
|
||||
rke up --config ./rancher-cluster.yml
|
||||
```
|
||||
|
||||
### 4. Save Your Files
|
||||
|
||||
> **Important**
|
||||
> The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.
|
||||
|
||||
Save a copy of the following files in a secure location:
|
||||
|
||||
- `rancher-cluster.yml`: The RKE cluster configuration file.
|
||||
- `kube_config_cluster.yml`: The [Kubeconfig file]({{<baseurl>}}/rke/latest/en/kubeconfig/) for the cluster, this file contains credentials for full access to the cluster.
|
||||
- `rancher-cluster.rkestate`: The [Kubernetes Cluster State file]({{<baseurl>}}/rke/latest/en/installation/#kubernetes-cluster-state), this file contains the current state of the cluster including the RKE configuration and the certificates.<br/><br/>_The Kubernetes Cluster State file is only created when using RKE v0.2.0 or higher._
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.
|
||||
|
||||
### Issues or errors?
|
||||
|
||||
See the [Troubleshooting]({{<baseurl>}}/rancher/v2.6/en/installation/resources/troubleshooting/) page.
|
||||
|
||||
### [Next: Install Rancher](../install-rancher)
|
||||
+294
@@ -0,0 +1,294 @@
|
||||
---
|
||||
title: '2. Collect and Publish Images to your Private Registry'
|
||||
weight: 200
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
This section describes how to set up your private registry so that when you install Rancher, Rancher will pull all the required images from this registry.
|
||||
|
||||
By default, all images used to [provision Kubernetes clusters]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/) or launch any tools in Rancher, e.g. monitoring, pipelines, alerts, are pulled from Docker Hub. In an air gapped installation of Rancher, you will need a private registry that is located somewhere accessible by your Rancher server. Then, you will load the registry with all the images.
|
||||
|
||||
Populating the private registry with images is the same process for installing Rancher with Docker and for installing Rancher on a Kubernetes cluster.
|
||||
|
||||
The steps in this section differ depending on whether or not you are planning to use Rancher to provision a downstream cluster with Windows nodes or not. By default, we provide the steps of how to populate your private registry assuming that Rancher will provision downstream Kubernetes clusters with only Linux nodes. But if you plan on provisioning any [downstream Kubernetes clusters using Windows nodes]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/), there are separate instructions to support the images needed.
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
> You must have a [private registry](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry) available to use.
|
||||
>
|
||||
> If the registry has certs, follow [this K3s documentation](https://rancher.com/docs/k3s/latest/en/installation/private-registry/) about adding a private registry. The certs and registry configuration files need to be mounted into the Rancher container.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Linux Only Clusters">
|
||||
|
||||
For Rancher servers that will only provision Linux clusters, these are the steps to populate your private registry.
|
||||
|
||||
1. [Find the required assets for your Rancher version](#1-find-the-required-assets-for-your-rancher-version)
|
||||
2. [Collect the cert-manager image](#2-collect-the-cert-manager-image) (unless you are bringing your own certificates or terminating TLS on a load balancer)
|
||||
3. [Save the images to your workstation](#3-save-the-images-to-your-workstation)
|
||||
4. [Populate the private registry](#4-populate-the-private-registry)
|
||||
|
||||
### Prerequisites
|
||||
|
||||
These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space.
|
||||
|
||||
If you will use ARM64 hosts, the registry must support manifests. As of April 2020, Amazon Elastic Container Registry does not support manifests.
|
||||
|
||||
### 1. Find the required assets for your Rancher version
|
||||
|
||||
1. Go to our [releases page,](https://github.com/rancher/rancher/releases) find the Rancher v2.x.x release that you want to install, and click **Assets**. Note: Don't use releases marked `rc` or `Pre-release`, as they are not stable for production environments.
|
||||
|
||||
2. From the release's **Assets** section, download the following files, which are required to install Rancher in an air gap environment:
|
||||
|
||||
| Release File | Description |
|
||||
| ---------------- | -------------- |
|
||||
| `rancher-images.txt` | This file contains a list of images needed to install Rancher, provision clusters and user Rancher tools. |
|
||||
| `rancher-save-images.sh` | This script pulls all the images in the `rancher-images.txt` from Docker Hub and saves all of the images as `rancher-images.tar.gz`. |
|
||||
| `rancher-load-images.sh` | This script loads images from the `rancher-images.tar.gz` file and pushes them to your private registry. |
|
||||
|
||||
### 2. Collect the cert-manager image
|
||||
|
||||
> Skip this step if you are using your own certificates, or if you are terminating TLS on an external load balancer.
|
||||
|
||||
In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the [`cert-manager`](https://hub.helm.sh/charts/jetstack/cert-manager) image to `rancher-images.txt` as well.
|
||||
|
||||
**Note:** New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.
|
||||
|
||||
1. Fetch the latest `cert-manager` Helm chart and parse the template for image details:
|
||||
|
||||
> **Note:** Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation]({{<baseurl>}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/).
|
||||
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
helm fetch jetstack/cert-manager --version v1.7.1
|
||||
helm template ./cert-manager-<version>.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt
|
||||
```
|
||||
|
||||
2. Sort and unique the images list to remove any overlap between the sources:
|
||||
|
||||
```plain
|
||||
sort -u rancher-images.txt -o rancher-images.txt
|
||||
```
|
||||
|
||||
### 3. Save the images to your workstation
|
||||
|
||||
1. Make `rancher-save-images.sh` an executable:
|
||||
```
|
||||
chmod +x rancher-save-images.sh
|
||||
```
|
||||
|
||||
1. Run `rancher-save-images.sh` with the `rancher-images.txt` image list to create a tarball of all the required images:
|
||||
```plain
|
||||
./rancher-save-images.sh --image-list ./rancher-images.txt
|
||||
```
|
||||
**Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-images.tar.gz`. Check that the output is in the directory.
|
||||
|
||||
### 4. Populate the private registry
|
||||
|
||||
Next, you will move the images in the `rancher-images.tar.gz` to your private registry using the scripts to load the images.
|
||||
|
||||
Move the images in the `rancher-images.tar.gz` to your private registry using the scripts to load the images.
|
||||
|
||||
The `rancher-images.txt` is expected to be on the workstation in the same directory that you are running the `rancher-load-images.sh` script. The `rancher-images.tar.gz` should also be in the same directory.
|
||||
|
||||
1. Log into your private registry if required:
|
||||
```plain
|
||||
docker login <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
1. Make `rancher-load-images.sh` an executable:
|
||||
```
|
||||
chmod +x rancher-load-images.sh
|
||||
```
|
||||
|
||||
1. Use `rancher-load-images.sh` to extract, tag and push `rancher-images.txt` and `rancher-images.tar.gz` to your private registry:
|
||||
```plain
|
||||
./rancher-load-images.sh --image-list ./rancher-images.txt --registry <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Linux and Windows Clusters">
|
||||
|
||||
For Rancher servers that will provision Linux and Windows clusters, there are distinctive steps to populate your private registry for the Windows images and the Linux images. Since a Windows cluster is a mix of Linux and Windows nodes, the Linux images pushed into the private registry are manifests.
|
||||
|
||||
# Windows Steps
|
||||
|
||||
The Windows images need to be collected and pushed from a Windows server workstation.
|
||||
|
||||
1. <a href="#windows-1">Find the required assets for your Rancher version</a>
|
||||
2. <a href="#windows-2">Save the images to your Windows Server workstation</a>
|
||||
3. <a href="#windows-3">Prepare the Docker daemon</a>
|
||||
4. <a href="#windows-4">Populate the private registry</a>
|
||||
|
||||
### Prerequisites
|
||||
|
||||
These steps expect you to use a Windows Server 1809 workstation that has internet access, access to your private registry, and at least 50 GB of disk space.
|
||||
|
||||
The workstation must have Docker 18.02+ in order to support manifests, which are required when provisioning Windows clusters.
|
||||
|
||||
Your registry must support manifests. As of April 2020, Amazon Elastic Container Registry does not support manifests.
|
||||
|
||||
<a name="windows-1"></a>
|
||||
|
||||
### 1. Find the required assets for your Rancher version
|
||||
|
||||
1. Browse to our [releases page](https://github.com/rancher/rancher/releases) and find the Rancher v2.x.x release that you want to install. Don't download releases marked `rc` or `Pre-release`, as they are not stable for production environments.
|
||||
|
||||
2. From the release's "Assets" section, download the following files:
|
||||
|
||||
| Release File | Description |
|
||||
|----------------------------|------------------|
|
||||
| `rancher-windows-images.txt` | This file contains a list of Windows images needed to provision Windows clusters. |
|
||||
| `rancher-save-images.ps1` | This script pulls all the images in the `rancher-windows-images.txt` from Docker Hub and saves all of the images as `rancher-windows-images.tar.gz`. |
|
||||
| `rancher-load-images.ps1` | This script loads the images from the `rancher-windows-images.tar.gz` file and pushes them to your private registry. |
|
||||
|
||||
<a name="windows-2"></a>
|
||||
|
||||
### 2. Save the images to your Windows Server workstation
|
||||
|
||||
1. Using `powershell`, go to the directory that has the files that were downloaded in the previous step.
|
||||
|
||||
1. Run `rancher-save-images.ps1` to create a tarball of all the required images:
|
||||
```plain
|
||||
./rancher-save-images.ps1
|
||||
```
|
||||
|
||||
**Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-windows-images.tar.gz`. Check that the output is in the directory.
|
||||
|
||||
<a name="windows-3"></a>
|
||||
|
||||
### 3. Prepare the Docker daemon
|
||||
|
||||
Append your private registry address to the `allow-nondistributable-artifacts` config field in the Docker daemon (`C:\ProgramData\Docker\config\daemon.json`). Since the base image of Windows images are maintained by the `mcr.microsoft.com` registry, this step is required as the layers in the Microsoft registry are missing from Docker Hub and need to be pulled into the private registry.
|
||||
|
||||
```
|
||||
{
|
||||
...
|
||||
"allow-nondistributable-artifacts": [
|
||||
...
|
||||
"<REGISTRY.YOURDOMAIN.COM:PORT>"
|
||||
]
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
<a name="windows-4"></a>
|
||||
|
||||
### 4. Populate the private registry
|
||||
|
||||
Move the images in the `rancher-windows-images.tar.gz` to your private registry using the scripts to load the images.
|
||||
|
||||
The `rancher-windows-images.txt` is expected to be on the workstation in the same directory that you are running the `rancher-load-images.ps1` script. The `rancher-windows-images.tar.gz` should also be in the same directory.
|
||||
|
||||
1. Using `powershell`, log into your private registry if required:
|
||||
```plain
|
||||
docker login <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
1. Using `powershell`, use `rancher-load-images.ps1` to extract, tag and push the images from `rancher-images.tar.gz` to your private registry:
|
||||
```plain
|
||||
./rancher-load-images.ps1 --registry <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
# Linux Steps
|
||||
|
||||
The Linux images need to be collected and pushed from a Linux host, but _must be done after_ populating the Windows images into the private registry. These step are different from the Linux only steps as the Linux images that are pushed will actually manifests that support Windows and Linux images.
|
||||
|
||||
1. <a href="#linux-1">Find the required assets for your Rancher version</a>
|
||||
2. <a href="#linux-2">Collect all the required images</a>
|
||||
3. <a href="#linux-3">Save the images to your Linux workstation</a>
|
||||
4. <a href="#linux-4">Populate the private registry</a>
|
||||
|
||||
### Prerequisites
|
||||
|
||||
You must populate the private registry with the Windows images before populating the private registry with Linux images. If you have already populated the registry with Linux images, you will need to follow these instructions again as they will publish manifests that support Windows and Linux images.
|
||||
|
||||
These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space.
|
||||
|
||||
The workstation must have Docker 18.02+ in order to support manifests, which are required when provisioning Windows clusters.
|
||||
|
||||
<a name="linux-1"></a>
|
||||
|
||||
### 1. Find the required assets for your Rancher version
|
||||
|
||||
1. Browse to our [releases page](https://github.com/rancher/rancher/releases) and find the Rancher v2.x.x release that you want to install. Don't download releases marked `rc` or `Pre-release`, as they are not stable for production environments. Click **Assets**.
|
||||
|
||||
2. From the release's **Assets** section, download the following files:
|
||||
|
||||
| Release File | Description |
|
||||
|----------------------------| -------------------------- |
|
||||
| `rancher-images.txt` | This file contains a list of images needed to install Rancher, provision clusters and user Rancher tools. |
|
||||
| `rancher-windows-images.txt` | This file contains a list of images needed to provision Windows clusters. |
|
||||
| `rancher-save-images.sh` | This script pulls all the images in the `rancher-images.txt` from Docker Hub and saves all of the images as `rancher-images.tar.gz`. |
|
||||
| `rancher-load-images.sh` | This script loads images from the `rancher-images.tar.gz` file and pushes them to your private registry. |
|
||||
|
||||
<a name="linux-2"></a>
|
||||
|
||||
### 2. Collect all the required images
|
||||
|
||||
**For Kubernetes Installs using Rancher Generated Self-Signed Certificate:** In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the [`cert-manager`](https://hub.helm.sh/charts/jetstack/cert-manager) image to `rancher-images.txt` as well. You skip this step if you are using you using your own certificates.
|
||||
|
||||
1. Fetch the latest `cert-manager` Helm chart and parse the template for image details:
|
||||
> **Note:** Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation]({{<baseurl>}}/rancher/v2.6/en/installation/resources/upgrading-cert-manager/).
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
helm fetch jetstack/cert-manager --version v0.12.0
|
||||
helm template ./cert-manager-<version>.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt
|
||||
```
|
||||
|
||||
2. Sort and unique the images list to remove any overlap between the sources:
|
||||
```plain
|
||||
sort -u rancher-images.txt -o rancher-images.txt
|
||||
```
|
||||
|
||||
<a name="linux-3"></a>
|
||||
|
||||
### 3. Save the images to your workstation
|
||||
|
||||
1. Make `rancher-save-images.sh` an executable:
|
||||
```
|
||||
chmod +x rancher-save-images.sh
|
||||
```
|
||||
|
||||
1. Run `rancher-save-images.sh` with the `rancher-images.txt` image list to create a tarball of all the required images:
|
||||
```plain
|
||||
./rancher-save-images.sh --image-list ./rancher-images.txt
|
||||
```
|
||||
|
||||
**Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-images.tar.gz`. Check that the output is in the directory.
|
||||
|
||||
<a name="linux-4"></a>
|
||||
|
||||
### 4. Populate the private registry
|
||||
|
||||
Move the images in the `rancher-images.tar.gz` to your private registry using the `rancher-load-images.sh script` to load the images.
|
||||
|
||||
The image list, `rancher-images.txt` or `rancher-windows-images.txt`, is expected to be on the workstation in the same directory that you are running the `rancher-load-images.sh` script. The `rancher-images.tar.gz` should also be in the same directory.
|
||||
|
||||
1. Log into your private registry if required:
|
||||
```plain
|
||||
docker login <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
1. Make `rancher-load-images.sh` an executable:
|
||||
```
|
||||
chmod +x rancher-load-images.sh
|
||||
```
|
||||
|
||||
1. Use `rancher-load-images.sh` to extract, tag and push the images from `rancher-images.tar.gz` to your private registry:
|
||||
|
||||
```plain
|
||||
./rancher-load-images.sh --image-list ./rancher-images.txt \
|
||||
--windows-image-list ./rancher-windows-images.txt \
|
||||
--registry <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### [Next step for Kubernetes Installs - Launch a Kubernetes Cluster]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/launch-kubernetes/)
|
||||
|
||||
### [Next step for Docker Installs - Install Rancher]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/install-rancher/)
|
||||
+178
@@ -0,0 +1,178 @@
|
||||
---
|
||||
title: '1. Set up Infrastructure and Private Registry'
|
||||
weight: 100
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
In this section, you will provision the underlying infrastructure for your Rancher management server in an air gapped environment. You will also set up the private Docker registry that must be available to your Rancher node(s).
|
||||
|
||||
An air gapped environment is an environment where the Rancher server is installed offline or behind a firewall.
|
||||
|
||||
The infrastructure depends on whether you are installing Rancher on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container. For more information on each installation option, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/)
|
||||
|
||||
Rancher can be installed on any Kubernetes cluster. The RKE and K3s Kubernetes infrastructure tutorials below are still included for convenience.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="K3s">
|
||||
|
||||
We recommend setting up the following infrastructure for a high-availability installation:
|
||||
|
||||
- **Two Linux nodes,** typically virtual machines, in the infrastructure provider of your choice.
|
||||
- **An external database** to store the cluster data. PostgreSQL, MySQL, and etcd are supported.
|
||||
- **A load balancer** to direct traffic to the two nodes.
|
||||
- **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.
|
||||
- **A private Docker registry** to distribute Docker images to your machines.
|
||||
|
||||
### 1. Set up Linux Nodes
|
||||
|
||||
These hosts will be disconnected from the internet, but require being able to connect with your private registry.
|
||||
|
||||
Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node) for setting up nodes as instances in Amazon EC2.
|
||||
|
||||
### 2. Set up External Datastore
|
||||
|
||||
The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available options allow you to select a datastore that best fits your use case.
|
||||
|
||||
For a high-availability K3s installation, you will need to set up one of the following external databases:
|
||||
|
||||
* [PostgreSQL](https://www.postgresql.org/) (certified against versions 10.7 and 11.5)
|
||||
* [MySQL](https://www.mysql.com/) (certified against version 5.7)
|
||||
* [etcd](https://etcd.io/) (certified against version 3.3.15)
|
||||
|
||||
When you install Kubernetes, you will pass in details for K3s to connect to the database.
|
||||
|
||||
For an example of one way to set up the database, refer to this [tutorial]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/rds) for setting up a MySQL database on Amazon's RDS service.
|
||||
|
||||
For the complete list of options that are available for configuring a K3s cluster datastore, refer to the [K3s documentation.]({{<baseurl>}}/k3s/latest/en/installation/datastore/)
|
||||
|
||||
### 3. Set up the Load Balancer
|
||||
|
||||
You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.
|
||||
|
||||
When Kubernetes gets set up in a later step, the K3s tool will deploy a Traefik Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.
|
||||
|
||||
When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Traefik Ingress controller to listen for traffic destined for the Rancher hostname. The Traefik Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.
|
||||
|
||||
For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:
|
||||
|
||||
- **A layer-4 load balancer** is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
|
||||
- **A layer-7 load balancer** is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the `--set tls=external` option when installing Rancher in a later step. For more information, refer to the [Rancher Helm chart options.]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#external-tls-termination)
|
||||
|
||||
For an example showing how to set up an NGINX load balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nginx/)
|
||||
|
||||
For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/)
|
||||
|
||||
> **Important:**
|
||||
> Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications.
|
||||
|
||||
### 4. Set up the DNS Record
|
||||
|
||||
Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.
|
||||
|
||||
Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.
|
||||
|
||||
You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.
|
||||
|
||||
For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)
|
||||
|
||||
### 5. Set up a Private Docker Registry
|
||||
|
||||
Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing Docker images to your machines.
|
||||
|
||||
In a later step, when you set up your K3s Kubernetes cluster, you will create a [private registries configuration file]({{<baseurl>}}/k3s/latest/en/installation/private-registry/) with details from this registry.
|
||||
|
||||
If you need help with creating a private registry, please refer to the [official Docker documentation.](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry)
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="RKE">
|
||||
|
||||
To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure:
|
||||
|
||||
- **Three Linux nodes,** typically virtual machines, in an infrastructure provider such as Amazon's EC2, Google Compute Engine, or vSphere.
|
||||
- **A load balancer** to direct front-end traffic to the three nodes.
|
||||
- **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.
|
||||
- **A private Docker registry** to distribute Docker images to your machines.
|
||||
|
||||
These nodes must be in the same region/data center. You may place these servers in separate availability zones.
|
||||
|
||||
### Why three nodes?
|
||||
|
||||
In an RKE cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes.
|
||||
|
||||
The etcd database requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can suffer from [split brain](https://www.quora.com/What-is-split-brain-in-distributed-systems), requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes.
|
||||
|
||||
### 1. Set up Linux Nodes
|
||||
|
||||
These hosts will be disconnected from the internet, but require being able to connect with your private registry.
|
||||
|
||||
Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/) for setting up nodes as instances in Amazon EC2.
|
||||
|
||||
### 2. Set up the Load Balancer
|
||||
|
||||
You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.
|
||||
|
||||
When Kubernetes gets set up in a later step, the RKE tool will deploy an NGINX Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.
|
||||
|
||||
When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.
|
||||
|
||||
For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:
|
||||
|
||||
- **A layer-4 load balancer** is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
|
||||
- **A layer-7 load balancer** is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the `--set tls=external` option when installing Rancher in a later step. For more information, refer to the [Rancher Helm chart options.]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#external-tls-termination)
|
||||
|
||||
For an example showing how to set up an NGINX load balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nginx/)
|
||||
|
||||
For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/)
|
||||
|
||||
> **Important:**
|
||||
> Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications.
|
||||
|
||||
### 3. Set up the DNS Record
|
||||
|
||||
Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.
|
||||
|
||||
Depending on your environment, this may be an A record pointing to the LB IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.
|
||||
|
||||
You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.
|
||||
|
||||
For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)
|
||||
|
||||
### 4. Set up a Private Docker Registry
|
||||
|
||||
Rancher supports air gap installs using a secure Docker private registry. You must have your own private registry or other means of distributing Docker images to your machines.
|
||||
|
||||
In a later step, when you set up your RKE Kubernetes cluster, you will create a [private registries configuration file]({{<baseurl>}}/rke/latest/en/config-options/private-registries/) with details from this registry.
|
||||
|
||||
If you need help with creating a private registry, please refer to the [official Docker documentation.](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry)
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker">
|
||||
|
||||
> The Docker installation is for Rancher users that are wanting to test out Rancher. Since there is only one node and a single Docker container, if the node goes down, you will lose all the data of your Rancher server.
|
||||
>
|
||||
> 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.6/en/backups/migrating-rancher)
|
||||
|
||||
### 1. Set up a Linux Node
|
||||
|
||||
This host will be disconnected from the Internet, but needs to be able to connect to your private registry.
|
||||
|
||||
Make sure that your node fulfills the general installation requirements for [OS, Docker, hardware, and networking.]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/) for setting up nodes as instances in Amazon EC2.
|
||||
|
||||
### 2. Set up a Private Docker Registry
|
||||
|
||||
Rancher supports air gap installs using a Docker private registry on your bastion server. You must have your own private registry or other means of distributing Docker images to your machines.
|
||||
|
||||
If you need help with creating a private registry, please refer to the [official Docker documentation.](https://docs.docker.com/registry/)
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### [Next: Collect and Publish Images to your Private Registry]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/populate-private-registry/)
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Installing Rancher behind an HTTP Proxy
|
||||
weight: 4
|
||||
---
|
||||
|
||||
In a lot of enterprise environments, servers or VMs running on premise do not have direct Internet access, but must connect to external services through a HTTP(S) proxy for security reasons. This tutorial shows step by step how to set up a highly available Rancher installation in such an environment.
|
||||
|
||||
Alternatively, it is also possible to set up Rancher completely air-gapped without any Internet access. This process is described in detail in the [Rancher docs]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/).
|
||||
|
||||
# Installation Outline
|
||||
|
||||
1. [Set up infrastructure]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/behind-proxy/prepare-nodes/)
|
||||
2. [Set up a Kubernetes cluster]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/behind-proxy/launch-kubernetes/)
|
||||
3. [Install Rancher]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/behind-proxy/install-rancher/)
|
||||
+89
@@ -0,0 +1,89 @@
|
||||
---
|
||||
title: 3. Install Rancher
|
||||
weight: 300
|
||||
---
|
||||
|
||||
Now that you have a running RKE cluster, you can install Rancher in it. For security reasons all traffic to Rancher must be encrypted with TLS. For this tutorial you are going to automatically issue a self-signed certificate through [cert-manager](https://cert-manager.io/). In a real-world use-case you will likely use Let's Encrypt or provide your own certificate.
|
||||
|
||||
> **Note:** These installation instructions assume you are using Helm 3.
|
||||
|
||||
### Install cert-manager
|
||||
|
||||
Add the cert-manager helm repository:
|
||||
|
||||
```
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
```
|
||||
|
||||
Create a namespace for cert-manager:
|
||||
|
||||
```
|
||||
kubectl create namespace cert-manager
|
||||
```
|
||||
|
||||
Install the CustomResourceDefinitions of cert-manager:
|
||||
|
||||
**Note:** New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.
|
||||
|
||||
```
|
||||
kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.7.1/cert-manager.crds.yaml
|
||||
```
|
||||
|
||||
And install it with Helm. Note that cert-manager also needs your proxy configured in case it needs to communicate with Let's Encrypt or other external certificate issuers:
|
||||
|
||||
```
|
||||
helm upgrade --install cert-manager jetstack/cert-manager \
|
||||
--namespace cert-manager --version v1.7.1 \
|
||||
--set http_proxy=http://${proxy_host} \
|
||||
--set https_proxy=http://${proxy_host} \
|
||||
--set no_proxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local
|
||||
```
|
||||
|
||||
Now you should wait until cert-manager is finished starting up:
|
||||
|
||||
```
|
||||
kubectl rollout status deployment -n cert-manager cert-manager
|
||||
kubectl rollout status deployment -n cert-manager cert-manager-webhook
|
||||
```
|
||||
|
||||
### Install Rancher
|
||||
|
||||
Next you can install Rancher itself. First add the helm repository:
|
||||
|
||||
```
|
||||
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
|
||||
```
|
||||
|
||||
Create a namespace:
|
||||
|
||||
```
|
||||
kubectl create namespace cattle-system
|
||||
```
|
||||
|
||||
And install Rancher with Helm. Rancher also needs a proxy configuration so that it can communicate with external application catalogs or retrieve Kubernetes version update metadata:
|
||||
|
||||
```
|
||||
helm upgrade --install rancher rancher-latest/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.example.com \
|
||||
--set proxy=http://${proxy_host} \
|
||||
--set noProxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local
|
||||
```
|
||||
|
||||
After waiting for the deployment to finish:
|
||||
|
||||
```
|
||||
kubectl rollout status deployment -n cattle-system rancher
|
||||
```
|
||||
|
||||
You can now navigate to `https://rancher.example.com` and start using Rancher.
|
||||
|
||||
> **Note:** If you don't intend to send telemetry data, opt out [telemetry]({{<baseurl>}}/rancher/v2.6/en/faq/telemetry/) during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully.
|
||||
|
||||
### Additional Resources
|
||||
|
||||
These resources could be helpful when installing Rancher:
|
||||
|
||||
- [Rancher Helm chart options]({{<baseurl>}}/rancher/v2.6/en/installation/resources/chart-options/)
|
||||
- [Adding TLS secrets]({{<baseurl>}}/rancher/v2.6/en/installation/resources/tls-secrets/)
|
||||
- [Troubleshooting Rancher Kubernetes Installations]({{<baseurl>}}/rancher/v2.6/en/installation/resources/troubleshooting/)
|
||||
+169
@@ -0,0 +1,169 @@
|
||||
---
|
||||
title: '2. Install Kubernetes'
|
||||
weight: 200
|
||||
---
|
||||
|
||||
Once the infrastructure is ready, you can continue with setting up an RKE cluster to install Rancher in.
|
||||
|
||||
### Installing Docker
|
||||
|
||||
First, you have to install Docker and setup the HTTP proxy on all three Linux nodes. For this perform the following steps on all three nodes.
|
||||
|
||||
For convenience, export the IP address and port of your proxy into an environment variable and set up the HTTP_PROXY variables for your current shell:
|
||||
|
||||
```
|
||||
export proxy_host="10.0.0.5:8888"
|
||||
export HTTP_PROXY=http://${proxy_host}
|
||||
export HTTPS_PROXY=http://${proxy_host}
|
||||
export NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16
|
||||
```
|
||||
|
||||
Next configure apt to use this proxy when installing packages. If you are not using Ubuntu, you have to adapt this step accordingly:
|
||||
|
||||
```
|
||||
cat <<'EOF' | sudo tee /etc/apt/apt.conf.d/proxy.conf > /dev/null
|
||||
Acquire::http::Proxy "http://${proxy_host}/";
|
||||
Acquire::https::Proxy "http://${proxy_host}/";
|
||||
EOF
|
||||
```
|
||||
|
||||
Now you can install Docker:
|
||||
|
||||
```
|
||||
curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh
|
||||
```
|
||||
|
||||
Then ensure that your current user is able to access the Docker daemon without sudo:
|
||||
|
||||
```
|
||||
sudo usermod -aG docker YOUR_USERNAME
|
||||
```
|
||||
|
||||
And configure the Docker daemon to use the proxy to pull images:
|
||||
|
||||
```
|
||||
sudo mkdir -p /etc/systemd/system/docker.service.d
|
||||
cat <<'EOF' | sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf > /dev/null
|
||||
[Service]
|
||||
Environment="HTTP_PROXY=http://${proxy_host}"
|
||||
Environment="HTTPS_PROXY=http://${proxy_host}"
|
||||
Environment="NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16"
|
||||
EOF
|
||||
```
|
||||
|
||||
To apply the configuration, restart the Docker daemon:
|
||||
|
||||
```
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart docker
|
||||
```
|
||||
|
||||
#### Air-gapped proxy
|
||||
|
||||
_New in v2.6.4_
|
||||
|
||||
You can now provision node driver clusters from an air-gapped cluster configured to use a proxy for outbound connections.
|
||||
|
||||
In addition to setting the default rules for a proxy server, you will need to add additional rules, shown below, to provision node driver clusters from a proxied Rancher environment.
|
||||
|
||||
You will configure your filepath according to your setup, e.g., `/etc/apt/apt.conf.d/proxy.conf`:
|
||||
|
||||
```
|
||||
acl SSL_ports port 22
|
||||
acl SSL_ports port 2376
|
||||
|
||||
acl Safe_ports port 22 # ssh
|
||||
acl Safe_ports port 2376 # docker port
|
||||
```
|
||||
|
||||
### Creating the RKE Cluster
|
||||
|
||||
You need several command line tools on the host where you have SSH access to the Linux nodes to create and interact with the cluster:
|
||||
|
||||
* [RKE CLI binary]({{<baseurl>}}/rke/latest/en/installation/#download-the-rke-binary)
|
||||
|
||||
```
|
||||
sudo curl -fsSL -o /usr/local/bin/rke https://github.com/rancher/rke/releases/download/v1.1.4/rke_linux-amd64
|
||||
sudo chmod +x /usr/local/bin/rke
|
||||
```
|
||||
|
||||
* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
|
||||
|
||||
```
|
||||
curl -LO "https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl"
|
||||
chmod +x ./kubectl
|
||||
sudo mv ./kubectl /usr/local/bin/kubectl
|
||||
```
|
||||
|
||||
* [helm](https://helm.sh/docs/intro/install/)
|
||||
|
||||
```
|
||||
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3
|
||||
chmod +x get_helm.sh
|
||||
sudo ./get_helm.sh
|
||||
```
|
||||
|
||||
Next, create a YAML file that describes the RKE cluster. Ensure that the IP addresses of the nodes and the SSH username are correct. For more information on the cluster YAML, have a look at the [RKE documentation]({{<baseurl>}}/rke/latest/en/example-yamls/).
|
||||
|
||||
```
|
||||
nodes:
|
||||
- address: 10.0.1.200
|
||||
user: ubuntu
|
||||
role: [controlplane,worker,etcd]
|
||||
- address: 10.0.1.201
|
||||
user: ubuntu
|
||||
role: [controlplane,worker,etcd]
|
||||
- address: 10.0.1.202
|
||||
user: ubuntu
|
||||
role: [controlplane,worker,etcd]
|
||||
|
||||
services:
|
||||
etcd:
|
||||
backup_config:
|
||||
interval_hours: 12
|
||||
retention: 6
|
||||
```
|
||||
|
||||
After that, you can create the Kubernetes cluster by running:
|
||||
|
||||
```
|
||||
rke up --config rancher-cluster.yaml
|
||||
```
|
||||
|
||||
RKE creates a state file called `rancher-cluster.rkestate`, this is needed if you want to perform updates, modify your cluster configuration or restore it from a backup. It also creates a `kube_config_cluster.yaml` file, that you can use to connect to the remote Kubernetes cluster locally with tools like kubectl or Helm. Make sure to save all of these files in a secure location, for example by putting them into a version control system.
|
||||
|
||||
To have a look at your cluster run:
|
||||
|
||||
```
|
||||
export KUBECONFIG=kube_config_cluster.yaml
|
||||
kubectl cluster-info
|
||||
kubectl get pods --all-namespaces
|
||||
```
|
||||
|
||||
You can also verify that your external load balancer works, and the DNS entry is set up correctly. If you send a request to either, you should receive HTTP 404 response from the ingress controller:
|
||||
|
||||
```
|
||||
$ curl 10.0.1.100
|
||||
default backend - 404
|
||||
$ curl rancher.example.com
|
||||
default backend - 404
|
||||
```
|
||||
|
||||
### Save Your Files
|
||||
|
||||
> **Important**
|
||||
> The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.
|
||||
|
||||
Save a copy of the following files in a secure location:
|
||||
|
||||
- `rancher-cluster.yml`: The RKE cluster configuration file.
|
||||
- `kube_config_cluster.yml`: The [Kubeconfig file]({{<baseurl>}}/rke/latest/en/kubeconfig/) for the cluster, this file contains credentials for full access to the cluster.
|
||||
- `rancher-cluster.rkestate`: The [Kubernetes Cluster State file]({{<baseurl>}}/rke/latest/en/installation/#kubernetes-cluster-state), this file contains the current state of the cluster including the RKE configuration and the certificates.
|
||||
|
||||
> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.
|
||||
|
||||
### Issues or errors?
|
||||
|
||||
See the [Troubleshooting]({{<baseurl>}}/rancher/v2.6/en/installation/resources/troubleshooting/) page.
|
||||
|
||||
### [Next: Install Rancher](../install-rancher)
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: '1. Set up Infrastructure'
|
||||
weight: 100
|
||||
---
|
||||
|
||||
In this section, you will provision the underlying infrastructure for your Rancher management server with internete access through a HTTP proxy.
|
||||
|
||||
To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure:
|
||||
|
||||
- **Three Linux nodes,** typically virtual machines, in an infrastructure provider such as Amazon's EC2, Google Compute Engine, or vSphere.
|
||||
- **A load balancer** to direct front-end traffic to the three nodes.
|
||||
- **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.
|
||||
|
||||
These nodes must be in the same region/data center. You may place these servers in separate availability zones.
|
||||
|
||||
### Why three nodes?
|
||||
|
||||
In an RKE cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes.
|
||||
|
||||
The etcd database requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can suffer from [split brain](https://www.quora.com/What-is-split-brain-in-distributed-systems), requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes.
|
||||
|
||||
### 1. Set up Linux Nodes
|
||||
|
||||
These hosts will connect to the internet through an HTTP proxy.
|
||||
|
||||
Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/) for setting up nodes as instances in Amazon EC2.
|
||||
|
||||
### 2. Set up the Load Balancer
|
||||
|
||||
You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.
|
||||
|
||||
When Kubernetes gets set up in a later step, the RKE tool will deploy an NGINX Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.
|
||||
|
||||
When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.
|
||||
|
||||
For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:
|
||||
|
||||
- **A layer-4 load balancer** is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
|
||||
- **A layer-7 load balancer** is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the `--set tls=external` option when installing Rancher in a later step. For more information, refer to the [Rancher Helm chart options.]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#external-tls-termination)
|
||||
|
||||
For an example showing how to set up an NGINX load balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nginx/)
|
||||
|
||||
For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/)
|
||||
|
||||
> **Important:**
|
||||
> Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications.
|
||||
|
||||
### 3. Set up the DNS Record
|
||||
|
||||
Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.
|
||||
|
||||
Depending on your environment, this may be an A record pointing to the LB IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.
|
||||
|
||||
You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.
|
||||
|
||||
For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)
|
||||
|
||||
|
||||
### [Next: Set up a Kubernetes cluster]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/behind-proxy/launch-kubernetes/)
|
||||
+20
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: Other Installation Methods
|
||||
weight: 3
|
||||
---
|
||||
|
||||
### Air Gapped Installations
|
||||
|
||||
Follow [these steps]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap) to install the Rancher server in an air gapped environment.
|
||||
|
||||
An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.
|
||||
|
||||
### Docker Installations
|
||||
|
||||
The [single-node Docker installation]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker) is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster using Helm, you install the Rancher server component on a single node using a `docker run` command.
|
||||
|
||||
The Docker installation is for development and testing environments only.
|
||||
|
||||
Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.
|
||||
|
||||
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.6/en/backups/migrating-rancher)
|
||||
+115
@@ -0,0 +1,115 @@
|
||||
---
|
||||
title: Advanced Options for Docker Installs
|
||||
weight: 5
|
||||
---
|
||||
|
||||
When installing Rancher, there are several advanced 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.
|
||||
|
||||
Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
|
||||
```
|
||||
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.6/en/installation/resources/advanced/api-audit-log) for more information and options.
|
||||
|
||||
Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
|
||||
See [TLS settings]({{<baseurl>}}/rancher/v2.6/en/installation/resources/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
|
||||
```
|
||||
|
||||
Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
+60
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: HTTP Proxy Configuration
|
||||
weight: 251
|
||||
---
|
||||
|
||||
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.6/en/installation/other-installation-methods/single-node-docker/) 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
|
||||
```
|
||||
|
||||
Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
|
||||
### Air-gapped proxy configuration
|
||||
|
||||
_New in v2.6.4_
|
||||
|
||||
You can now provision node driver clusters from an air-gapped cluster configured to use a proxy for outbound connections.
|
||||
|
||||
In addition to setting the default rules for a proxy server as shown above, you will need to add additional rules, shown below, to provision node driver clusters from a proxied Rancher environment.
|
||||
|
||||
You will configure your filepath according to your setup, e.g., `/etc/apt/apt.conf.d/proxy.conf`:
|
||||
|
||||
```
|
||||
acl SSL_ports port 22
|
||||
acl SSL_ports port 2376
|
||||
|
||||
acl Safe_ports port 22 # ssh
|
||||
acl Safe_ports port 2376 # docker port
|
||||
```
|
||||
+192
@@ -0,0 +1,192 @@
|
||||
---
|
||||
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
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
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.6/en/backups/migrating-rancher)
|
||||
|
||||
### Privileged Access for Rancher
|
||||
|
||||
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.6/en/installation/requirements/)
|
||||
|
||||
# 1. Provision Linux Host
|
||||
|
||||
Provision a single Linux host according to our [Requirements]({{<baseurl>}}/rancher/v2.6/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.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:
|
||||
|
||||
- [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 E: Localhost tunneling, no Certificate](#option-e-localhost-tunneling-no-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 host, and run the command below:
|
||||
|
||||
```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.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.
|
||||
|
||||
| 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. |
|
||||
|
||||
Log into your host, and run the command below:
|
||||
|
||||
```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, you would use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings.
|
||||
|
||||
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)
|
||||
|
||||
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. |
|
||||
|
||||
Log into your host, and run the command below:
|
||||
|
||||
```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.
|
||||
|
||||
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.
|
||||
|
||||
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 |
|
||||
|
||||
Log into your host, and run the command below:
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
--privileged \
|
||||
rancher/rancher:latest \
|
||||
--acme-domain <YOUR.DNS.NAME>
|
||||
```
|
||||
|
||||
### Option E: Localhost tunneling, no Certificate
|
||||
|
||||
If you are installing Rancher in a development or testing environment where you have a localhost tunneling solution running, such as [ngrok](https://ngrok.com/), avoid generating a certificate. This installation option doesn't require a certificate.
|
||||
|
||||
- You will use `--no-cacerts` in the argument to disable the default CA certificate generated by Rancher.
|
||||
|
||||
Log into your host, and run the command below:
|
||||
|
||||
```bash
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
--privileged \
|
||||
rancher/rancher:latest \
|
||||
--no-cacerts
|
||||
```
|
||||
|
||||
## 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.6/en/backups/docker-installs). 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.6/en/cluster-provisioning/).
|
||||
+84
@@ -0,0 +1,84 @@
|
||||
---
|
||||
title: Rolling Back Rancher Installed with Docker
|
||||
weight: 1015
|
||||
---
|
||||
|
||||
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.6/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><PRIOR_RANCHER_VERSION></code> and <code><RANCHER_CONTAINER_NAME></code></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 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.6/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.6/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>
|
||||
```
|
||||
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.
|
||||
|
||||
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.
|
||||
+375
@@ -0,0 +1,375 @@
|
||||
---
|
||||
title: Upgrading Rancher Installed with Docker
|
||||
weight: 1010
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
> **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
|
||||
|
||||
- **Review the [known upgrade issues]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/upgrades/#known-upgrade-issues)** section 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.6/en/installation/install-rancher-on-k8s/chart-options/#helm-chart-repositories/) aren’t supported.
|
||||
- **For [air gap installs only,]({{<baseurl>}}/rancher/v2.6/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.6/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><RANCHER_CONTAINER_TAG></code> and <code><RANCHER_CONTAINER_NAME></code></sup>
|
||||
|
||||
|
||||
|
||||
| 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-<RANCHER_VERSION>-<DATE>.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.6/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.6/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.6/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.6/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.6/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>
|
||||
```
|
||||
|
||||
Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
|
||||
</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.6/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>
|
||||
```
|
||||
|
||||
Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
|
||||
</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.6/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.6/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
|
||||
```
|
||||
|
||||
Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
</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.6/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>
|
||||
```
|
||||
|
||||
Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
|
||||
</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.6/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>
|
||||
```
|
||||
|
||||
Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
|
||||
</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.6/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.6/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>
|
||||
```
|
||||
Privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
|
||||
</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.6/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.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.
|
||||
|
||||
```
|
||||
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>
|
||||
```
|
||||
privileged access is [required.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher)
|
||||
|
||||
</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.6/en/installation/other-installation-methods/single-node-docker/single-node-rollbacks/).
|
||||
+88
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: Certificate Troubleshooting
|
||||
weight: 4
|
||||
---
|
||||
### 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)
|
||||
```
|
||||
Reference in New Issue
Block a user