public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-26 21:18:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix tables of contents, headers and formatting

Browse Source
This commit is contained in:
Catherine Luse
2022-09-10 00:26:51 -07:00
parent 11ebb7d341
commit 5fdfa52386
336 changed files with 1249 additions and 3710 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.md
+2 -2
View File
@@ -45,7 +45,7 @@ Create the registries.yaml file at `/etc/rancher/k3s/registries.yaml`. This will
The registries.yaml file should look like this before plugging in the necessary information:
```
```yaml
---
mirrors:
customreg:
@@ -109,7 +109,7 @@ To use this `kubeconfig` file,
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`:
```
```yaml
apiVersion: v1
clusters:
- cluster:
docs/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md
+30 -38
View File
@@ -9,22 +9,15 @@ This section is about how to deploy Rancher for your air gapped environment in a
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
## 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.md)
# Kubernetes Instructions
## 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
### 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.
@@ -55,7 +48,7 @@ From a system that has access to the internet, fetch the latest Helm chart and c
helm fetch rancher-stable/rancher --version=v2.4.8
```
# 2. Choose your SSL Configuration
### 2. Choose your SSL Configuration
Rancher Server is designed to be secure by default and requires SSL/TLS configuration.
@@ -72,7 +65,7 @@ If you want terminate SSL/TLS externally, see [TLS termination on an External Lo
| 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
### 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.
@@ -82,11 +75,11 @@ When setting up the Rancher Helm template, there are several options in the Helm
| `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
### 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
#### 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.
@@ -97,7 +90,7 @@ Recent changes to cert-manager require an upgrade. If you are upgrading Rancher
:::
### 1. Add the cert-manager repo
##### 1. Add the cert-manager repo
From a system connected to the internet, add the cert-manager repo to Helm:
@@ -106,7 +99,7 @@ helm repo add jetstack https://charts.jetstack.io
helm repo update
```
### 2. Fetch the cert-manager chart
##### 2. Fetch the cert-manager chart
Fetch the latest cert-manager chart available from the [Helm chart repository](https://artifacthub.io/packages/helm/cert-manager/cert-manager).
@@ -120,7 +113,7 @@ New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommen
helm fetch jetstack/cert-manager --version v1.7.1
```
### 3. Render the cert-manager template
##### 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.
@@ -133,14 +126,14 @@ helm template cert-manager ./cert-manager-v1.7.1.tgz --output-dir . \
--set startupapicheck.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-ctl
```
### 4. Download the cert-manager CRD
##### 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/cert-manager/cert-manager/releases/download/v1.7.1/cert-manager.crds.yaml
```
### 5. Render the Rancher template
##### 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.
@@ -165,14 +158,14 @@ helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
**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
#### Option B: Certificates From Files using Kubernetes Secrets
### 1. Create 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
##### 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.
@@ -211,7 +204,7 @@ If you are using a Private CA signed cert, add `--set privateCA=true` following
Then refer to [Adding TLS Secrets](../../resources/add-tls-secrets.md) to publish the certificate files so Rancher and the ingress controller can use them.
# 4. Install Rancher
### 4. Install Rancher
Copy the rendered manifest directories to a system that has access to the Rancher server cluster to complete installation.
@@ -219,7 +212,7 @@ 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
#### For Self-Signed Certificate Installs, Install Cert-manager
<details id="install-cert-manager">
<summary>Click to expand</summary>
@@ -227,14 +220,13 @@ If you choose to use self-signed certificates in [B. Choose your SSL Configurati
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
```
```plain
kubectl create namespace cert-manager
```
2. Create the cert-manager CustomResourceDefinitions (CRDs).
```plain
kubectl apply -f cert-manager/cert-manager-crd.yaml
```
:::note
@@ -242,14 +234,14 @@ kubectl apply -f cert-manager/cert-manager-crd.yaml
:::
1. Launch cert-manager.
```plain
kubectl apply -R -f ./cert-manager
```
3. Launch cert-manager.
```plain
kubectl apply -R -f ./cert-manager
```
</details>
### Install Rancher with kubectl
#### Install Rancher with kubectl
```plain
kubectl create namespace cattle-system
@@ -263,7 +255,7 @@ If you don't intend to send telemetry data, opt out [telemetry](../../../../faq/
:::
# Additional Resources
## Additional Resources
These resources could be helpful when installing Rancher:
docs/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md
+1 -1
View File
@@ -178,7 +178,7 @@ Your registry must support manifests. As of April 2020, Amazon Elastic Container
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.
```
```json
{
...
"allow-nondistributable-artifacts": [
docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.md
+1 -3
View File
@@ -5,8 +5,6 @@ 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:
@@ -105,7 +103,7 @@ 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](https://rancher.com/docs/rke/latest/en/example-yamls/).
```
```yml
nodes:
- address: 10.0.1.200
user: ubuntu
docs/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md
+20 -30
View File
@@ -14,12 +14,12 @@ The following instructions will guide you through upgrading a Rancher server tha
:::
# Prerequisites
## Prerequisites
- **Review the [known upgrade issues](../../install-upgrade-on-a-kubernetes-cluster/upgrades.md#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](../../../../reference-guides/installation-references/helm-chart-options.md#helm-chart-repositories/) aren’t supported.
- **For [air gap installs only,](../../../../pages-for-subheaders/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version**. Follow the guide to [populate your private registry](../air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to.
# Placeholder Review
## 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>`).
@@ -31,7 +31,7 @@ docker stop <RANCHER_CONTAINER_NAME>
In this command, `<RANCHER_CONTAINER_NAME>` is the name of your Rancher container.
# Get Data for Upgrade Commands
## Get Data for Upgrade Commands
To obtain the data to replace the placeholders, run:
@@ -55,18 +55,10 @@ Write down or copy this information before starting the upgrade.
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
## Upgrade
During upgrade, you create a copy of the data from your current Rancher container and a backup in case something goes wrong. Then you deploy the new version of Rancher in a new container using your existing data. 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
During upgrade, you create a copy of the data from your current Rancher container and a backup in case something goes wrong. Then you deploy the new version of Rancher in a new container using your existing data.
### 1. 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.
@@ -82,13 +74,11 @@ During upgrade, you create a copy of the data from your current Rancher containe
docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data rancher/rancher:<RANCHER_CONTAINER_TAG>
```
# 2. Create a backup tarball
### 2. Create a backup tarball
1. <a id="tarball"></a>From the data container that you just created (<code>rancher-data</code>), create a backup tarball (<code>rancher-data-backup-&lt;RANCHER_VERSION&gt;-&lt;DATE&gt;.tar.gz</code>).
This tarball will serve as a rollback point if something goes wrong during upgrade. Use the following command, replacing each placeholder.
```
docker run --volumes-from rancher-data -v "$PWD:/backup" --rm busybox tar zcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
```
@@ -104,7 +94,7 @@ During upgrade, you create a copy of the data from your current Rancher containe
1. Move your backup tarball to a safe location external from your Rancher server.
# 3. Pull the New Docker Image
### 3. Pull the New Docker Image
Pull the image of the Rancher version that you want to upgrade to.
@@ -116,7 +106,7 @@ Placeholder | Description
docker pull rancher/rancher:<RANCHER_VERSION_TAG>
```
# 4. Start the New Rancher Server Container
### 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.
@@ -142,7 +132,7 @@ To see the command to use when starting the new Rancher server container, choose
Select which option you had installed Rancher server
### Option A: Default Self-Signed Certificate
#### Option A: Default Self-Signed Certificate
<details id="option-a">
<summary>Click to expand</summary>
@@ -165,10 +155,10 @@ Privileged access is [required.](../../../../pages-for-subheaders/rancher-on-a-s
</details>
### Option B: Bring Your Own Certificate: Self-Signed
#### Option B: Bring Your Own Certificate: Self-Signed
<details id="option-b">
<summary>Click to expand</summary>
<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.
@@ -201,7 +191,7 @@ Privileged access is [required.](../../../../pages-for-subheaders/rancher-on-a-s
</details>
### Option C: Bring Your Own Certificate: Signed by Recognized CA
#### Option C: Bring Your Own Certificate: Signed by Recognized CA
<details id="option-c">
<summary>Click to expand</summary>
@@ -235,7 +225,7 @@ docker run -d --volumes-from rancher-data \
Privileged access is [required.](../../../../pages-for-subheaders/rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher)
</details>
### Option D: Let's Encrypt Certificate
#### Option D: Let's Encrypt Certificate
<details id="option-d">
<summary>Click to expand</summary>
@@ -280,7 +270,7 @@ For security purposes, SSL (Secure Sockets Layer) is required when using Rancher
When starting the new Rancher server container, choose from the following options:
### Option A: Default Self-Signed Certificate
#### Option A: Default Self-Signed Certificate
<details id="option-a">
<summary>Click to expand</summary>
@@ -305,7 +295,7 @@ Placeholder | Description
Privileged access is [required.](../../../../pages-for-subheaders/rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher)
</details>
### Option B: Bring Your Own Certificate: Self-Signed
#### Option B: Bring Your Own Certificate: Self-Signed
<details id="option-b">
<summary>Click to expand</summary>
@@ -341,7 +331,7 @@ docker run -d --restart=unless-stopped \
Privileged access is [required.](../../../../pages-for-subheaders/rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher)
</details>
### Option C: Bring Your Own Certificate: Signed by Recognized CA
#### Option C: Bring Your Own Certificate: Signed by Recognized CA
<details id="option-c">
<summary>Click to expand</summary>
@@ -388,7 +378,7 @@ privileged access is [required.](../../../../pages-for-subheaders/rancher-on-a-s
**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
### 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.
@@ -398,10 +388,10 @@ See [Restoring Cluster Networking](../../../../../versioned_docs/version-2.0-2.4
:::
# 6. Clean up Your Old Rancher Server Container
### 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
## 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](roll-back-docker-installed-rancher.md).