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

Fix order of headings (#1465)

Browse Source 
* Fix 'title out of sequence' errors

fixed Dockershim.md

* fixed deprecated-features.md

* fixed install-and-configure-kubectl.md

* fixed rancher-is-no-longer-needed.md

* fixed security.md

* fixed technical-items.md + spacing, duplicate section, admonitions

* fixed telemetry.md

* fixed upgrades.md

* fixed upgrade-kubernetes-without-upgrading-rancher.md

* fixed air-gapped-upgrades.md

* fixed dockershim.md

* fixed docker-install-commands.md

* fixed install-kubernetes.md

* fixed infrastructure-private-registry.md

* fixed install-rancher-ha

* fixed manage-namespaces and tune-etcd-for-large-installs.md

* fixed cis-scans/configuration-reference.md

* fixed custom-benchmark.md

* fixed supportconfig.md

* fixed harvester/overview.md

* fixed logging-architecture.md

* fixed logging-helm-chart-options.md + rm'd unnecessary annotation title

* fixed taints-and-tolerances.md

* fixed longhorn/overview.md

* fixed neuvector/overview.md

* fixed monitoring-and-alerting

* fixed rancher-cli.md

* fixed cluster-configuration.md

* fixed monitoring-v2-configuration/examples.md

* fixed servicemonitors-and-podmonitors.md

* fixed other-troubleshooting-tips/dns.md
This commit is contained in:
Marty Hernandez Avedon
2024-09-18 14:02:55 -04:00
committed by GitHub
parent 9f8e1a7a53
commit c869ea69ac
191 changed files with 1059 additions and 1135 deletions
Download Patch File Download Diff File Expand all files Collapse all files
versioned_docs/version-2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.md
+2 -2
View File
@@ -6,7 +6,7 @@ When running larger Rancher installations with 15 or more clusters it is recomme
The etcd data set is automatically cleaned up on a five minute interval by Kubernetes. There are situations, e.g. deployment thrashing, where enough events could be written to etcd and deleted before garbage collection occurs and cleans things up causing the keyspace to fill up. If you see `mvcc: database space exceeded` errors, in the etcd logs or Kubernetes API server logs, you should consider increasing the keyspace size. This can be accomplished by setting the [quota-backend-bytes](https://etcd.io/docs/v3.3/op-guide/maintenance/#space-quota) setting on the etcd servers.
### Example: This snippet of the RKE cluster.yml file increases the keyspace size to 5GB
## Example: This Snippet of the RKE Cluster.yml file Increases the Keyspace Size to 5GB
```yaml
# RKE cluster.yml
@@ -17,7 +17,7 @@ services:
quota-backend-bytes: 5368709120
```
## Scaling etcd disk performance
## Scaling etcd Disk Performance
You can follow the recommendations from [the etcd docs](https://etcd.io/docs/v3.3/tuning/#disk) on how to tune the disk priority on the host.
versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.md
+6 -5
View File
@@ -26,7 +26,7 @@ For security purposes, SSL (Secure Sockets Layer) is required when using Rancher
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>
@@ -53,7 +53,7 @@ docker run -d --restart=unless-stopped \
</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>
@@ -93,7 +93,7 @@ docker run -d --restart=unless-stopped \
</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>
@@ -130,7 +130,8 @@ docker run -d --restart=unless-stopped \
</details>
:::note
If you don't intend to send telemetry data, opt out [telemetry](../../../../faq/telemetry.md) during the initial login.
> **Note:** If you don't intend to send telemetry data, opt out [telemetry](../../../../faq/telemetry.md) during the initial login.
:::
versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md
+13 -13
View File
@@ -25,7 +25,7 @@ We recommend setting up the following infrastructure for a high-availability ins
- **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
## 1. Set up Linux Nodes
These hosts will be disconnected from the internet, but require being able to connect with your private registry.
@@ -33,7 +33,7 @@ Make sure that your nodes fulfill the general installation requirements for [OS,
For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.
### 2. Set up External Datastore
## 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.
@@ -49,7 +49,7 @@ For an example of one way to set up the database, refer to this [tutorial](../..
For the complete list of options that are available for configuring a K3s cluster datastore, refer to the [K3s documentation.](https://rancher.com/docs/k3s/latest/en/installation/datastore/)
### 3. Set up the Load Balancer
## 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.
@@ -69,7 +69,7 @@ For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to
> **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
## 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.
@@ -79,7 +79,7 @@ You will need to specify this hostname in a later step when you install Rancher,
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
## 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.
@@ -99,13 +99,13 @@ To install the Rancher management server on a high-availability RKE cluster, we
These nodes must be in the same region/data center. You may place these servers in separate availability zones.
### Why three nodes?
## 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
## 1. Set up Linux Nodes
These hosts will be disconnected from the internet, but require being able to connect with your private registry.
@@ -113,7 +113,7 @@ Make sure that your nodes fulfill the general installation requirements for [OS,
For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.
### 2. Set up the Load Balancer
## 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.
@@ -133,7 +133,7 @@ For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to
> **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
## 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.
@@ -143,7 +143,7 @@ You will need to specify this hostname in a later step when you install Rancher,
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
## 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.
@@ -159,7 +159,7 @@ If you need help with creating a private registry, please refer to the [official
>
> As of Rancher v2.5, 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.](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)
### 1. Set up a Linux Node
## 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.
@@ -167,7 +167,7 @@ Make sure that your node fulfills the general installation requirements for [OS,
For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.
### 2. Set up a Private Docker Registry
## 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.
@@ -176,4 +176,4 @@ If you need help with creating a private registry, please refer to the [official
</TabItem>
</Tabs>
### [Next: Collect and Publish Images to your Private Registry](publish-images.md)
## [Next: Collect and Publish Images to your Private Registry](publish-images.md)
versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.md
+14 -12
View File
@@ -19,14 +19,15 @@ The steps to set up an air-gapped Kubernetes cluster on RKE or K3s are shown bel
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
## 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
## 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:
@@ -36,7 +37,8 @@ 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
## 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:
@@ -62,7 +64,7 @@ Note, at this time only secure registries are supported with K3s (SSL with custo
For more information on private registries configuration file for K3s, refer to the [K3s documentation.](https://rancher.com/docs/k3s/latest/en/installation/private-registry/)
### 3. Install K3s
## 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/)
@@ -91,7 +93,7 @@ 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
## 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.
@@ -131,7 +133,7 @@ kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces
For more information about the `kubeconfig` file, refer to the [K3s documentation](https://rancher.com/docs/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
## Note on Upgrading
Upgrading an air-gap environment can be accomplished in the following manner:
@@ -144,11 +146,11 @@ Upgrading an air-gap environment can be accomplished in the following manner:
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
## 1. Install RKE
Install RKE by following the instructions in the [RKE documentation.](https://rancher.com/docs/rke/latest/en/installation/)
### 2. Create an RKE Config File
## 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`.
@@ -195,7 +197,7 @@ private_registries:
is_default: true
```
### 3. Run RKE
## 3. Run RKE
After configuring `rancher-cluster.yml`, bring up your Kubernetes cluster:
@@ -203,7 +205,7 @@ After configuring `rancher-cluster.yml`, bring up your Kubernetes cluster:
rke up --config ./rancher-cluster.yml
```
### 4. Save Your Files
## 4. Save Your Files
> **Important**
> The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.
@@ -219,8 +221,8 @@ Save a copy of the following files in a secure location:
> **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?
## Issues or Errors?
See the [Troubleshooting](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md) page.
### [Next: Install Rancher](install-rancher-ha.md)
## [Next: Install Rancher](install-rancher-ha.md)
versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md
+95 -160
View File
@@ -8,7 +8,7 @@ title: 4. Install Rancher
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 v2.5+
## 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.
@@ -20,14 +20,7 @@ If you want to continue the air gapped installation using Docker commands, skip
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.
@@ -44,9 +37,9 @@ From a system that has access to the internet, fetch the latest Helm chart and c
```
- Alpha: Experimental preview of upcoming releases.
```
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha
```
Note: Upgrades are not supported to, from, or between Alphas.
Note: Upgrades are not supported to, from, or between Alphas.
3. Fetch the latest Rancher chart. This will pull down the chart and save it in the current directory as a `.tgz` file.
```plain
@@ -58,20 +51,24 @@ 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.
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](../../../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination).
:::note
If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer](../../installation-references/helm-chart-options.md#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
### 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.
@@ -81,19 +78,21 @@ 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. Fetch the Cert-Manager Chart
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.
> **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](../../resources/upgrade-cert-manager.md/).
:::note
### 1. Add the cert-manager repo
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](../../resources/upgrade-cert-manager.md).
:::
##### 1. Add the cert-manager Repo
From a system connected to the internet, add the cert-manager repo to Helm:
@@ -102,38 +101,78 @@ 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://hub.helm.sh/charts/jetstack/cert-manager).
Fetch the latest cert-manager chart available from the [Helm chart repository](https://artifacthub.io/packages/helm/cert-manager/cert-manager).
```plain
helm fetch jetstack/cert-manager --version v1.5.1
helm fetch jetstack/cert-manager --version v1.11.0
```
### 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.5.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
##### 3. Retrieve the cert-manager CRDs
Download the required CRD file for cert-manager:
```plain
curl -L -o cert-manager-crd.yaml https://github.com/jetstack/cert-manager/releases/download/v1.5.1/cert-manager.crds.yaml
curl -L -o cert-manager-crd.yaml https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.crds.yaml
```
### 5. Render the Rancher template
### 4. Install Rancher
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.
Copy the fetched charts to a system that has access to the Rancher server cluster to complete installation.
#### 1. Install cert-manager
Install cert-manager with the same options you would use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry.
:::note
To see options on how to customize the cert-manager install (including for cases where your cluster uses PodSecurityPolicies), see the [cert-manager docs](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration).
:::
<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
```
2. Create the cert-manager CustomResourceDefinitions (CRDs).
```plain
kubectl apply -f cert-manager-crd.yaml
```
3. Install cert-manager.
```plain
helm install cert-manager ./cert-manager-v1.11.0.tgz \
--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
```
</details>
#### 2. Install Rancher
First, refer to [Adding TLS Secrets](../../resources/add-tls-secrets.md) to publish the certificate files so Rancher and the ingress controller can use them.
Then, create the namespace for Rancher using kubectl:
```plain
kubectl create namespace cattle-system
```
Next, install Rancher, 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.
For Kubernetes v1.25 or later, set `global.cattle.psp.enabled` to `false` when using Rancher v2.7.2-v2.7.4. This is not necessary for Rancher v2.7.5 and above, but you can still manually set the option if you choose.
Placeholder | Description
------------|-------------
@@ -142,12 +181,8 @@ Placeholder | Description
`<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.
`<CERTMANAGER_VERSION>` | Cert-manager version running on k8s cluster.
<Tabs>
<TabItem value="Rancher v2.5.8+">
```plain
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
--no-hooks \ # prevent files for Helm hooks from being generated
helm install rancher ./rancher-<VERSION>.tgz \
--namespace cattle-system \
--set hostname=<RANCHER.YOURDOMAIN.COM> \
--set certmanager.version=<CERTMANAGER_VERSION> \
@@ -158,36 +193,17 @@ 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`
</TabItem>
<TabItem value="Rancher before v2.5.8">
#### Option B: Certificates From Files Using Kubernetes Secrets
```plain
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
--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.6`
</TabItem>
</Tabs>
## 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. Install Rancher
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.
Install Rancher, 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.
For Kubernetes v1.25 or later, set `global.cattle.psp.enabled` to `false` when using Rancher v2.7.2-v2.7.4. This is not necessary for Rancher v2.7.5 and above, but you can still manually set the option if you choose.
| Placeholder | Description |
| -------------------------------- | ----------------------------------------------- |
@@ -195,12 +211,8 @@ Render the Rancher template, declaring your chosen options. Use the reference ta
| `<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer. |
| `<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry. |
<Tabs>
<TabItem value="Rancher v2.5.8+">
```plain
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
--no-hooks \ # prevent files for Helm hooks from being generated
helm install rancher ./rancher-<VERSION>.tgz \
--namespace cattle-system \
--set hostname=<RANCHER.YOURDOMAIN.COM> \
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
@@ -212,8 +224,7 @@ Render the Rancher template, declaring your chosen options. Use the reference ta
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
helm install rancher ./rancher-<VERSION>.tgz \
--namespace cattle-system \
--set hostname=<RANCHER.YOURDOMAIN.COM> \
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
@@ -223,95 +234,19 @@ If you are using a Private CA signed cert, add `--set privateCA=true` following
--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](../../resources/add-tls-secrets.md/) to publish the certificate files so Rancher and the ingress controller can use them.
</TabItem>
<TabItem value="Rancher before v2.5.8">
```plain
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
--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 . \
--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](../../resources/add-tls-secrets.md/) to publish the certificate files so Rancher and the ingress controller can use them.
</TabItem>
</Tabs>
## 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 [2. Choose your SSL Configuration](#2-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.
:::caution
> **Note:** If you don't intend to send telemetry data, opt out [telemetry](../../../../faq/telemetry.md) during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully.
If you don't intend to send telemetry data, opt out [telemetry](../../../../faq/telemetry.md) 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](../../../../reference-guides/installation-references/helm-chart-options.md/)
- [Importing and installing extensions in an air-gapped environment](../../../../integrations-in-rancher/rancher-extensions.md#importing-and-installing-extensions-in-an-air-gapped-environment)
- [Rancher Helm chart options](../../installation-references/helm-chart-options.md)
- [Adding TLS secrets](../../resources/add-tls-secrets.md)
- [Troubleshooting Rancher Kubernetes Installations](../../install-upgrade-on-a-kubernetes-cluster/upgrades.md)
- [Troubleshooting Rancher Kubernetes Installations](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md)
versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/install-rancher-on-linux/upgrade-rancherd.md
+2 -4
View File
@@ -10,7 +10,7 @@ During a RancherD upgrade, there is very little downtime, but it is possible tha
When Rancher is installed with RancherD, the underlying Kubernetes cluster can't be upgraded from the Rancher UI. It needs to be upgraded using the RancherD CLI.
### Upgrading the Rancher Helm Chart without Upgrading the Underlying Cluster
## Upgrading the Rancher Helm Chart without Upgrading the Underlying Cluster
To upgrade Rancher without upgrading the underlying Kubernetes cluster, follow these steps.
@@ -38,7 +38,7 @@ To upgrade Rancher without upgrading the underlying Kubernetes cluster, follow t
If necessary, restore Rancher from backup by following [these steps.](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md)
### Upgrading Both Rancher and the Underlying Cluster
## Upgrading Both Rancher and the Underlying Cluster
Upgrade both RancherD and the underlying Kubernetes cluster by re-running the RancherD installation script.
@@ -65,5 +65,3 @@ systemctl start rancherd-server
```
The upgrade can also be performed by manually installing the binary of the desired version.
versioned_docs/version-2.5/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md
+3 -2
View File
@@ -28,7 +28,7 @@ Administrators might configure the RKE metadata settings to do the following:
- Change the metadata URL that Rancher uses to sync the metadata, which is useful for air gap setups if you need to sync Rancher locally instead of with GitHub
- Prevent Rancher from auto-syncing the metadata, which is one way to prevent new and unsupported Kubernetes versions from being available in Rancher
### Refresh Kubernetes Metadata
## Refresh Kubernetes Metadata
The option to refresh the Kubernetes metadata is available for administrators by default, or for any user who has the **Manage Cluster Drivers** [global role.](../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md)
@@ -56,7 +56,8 @@ To edit the metadata config in Rancher,
If you don't have an air gap setup, you don't need to specify the URL where Rancher gets the metadata, because the default setting is to pull from [Rancher's metadata Git repository.](https://github.com/rancher/kontainer-driver-metadata/blob/dev-v2.5/data/data.json)
However, if you have an [air gap setup,](#air-gap-setups) you will need to mirror the Kubernetes metadata repository in a location available to Rancher. Then you need to change the URL to point to the new location of the JSON file.
### Air Gap Setups
## Air Gap Setups
Rancher relies on a periodic refresh of the `rke-metadata-config` to download new Kubernetes version metadata if it is supported with the current version of the Rancher server. For a table of compatible Kubernetes and Rancher versions, refer to the [service terms section.](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.2.8/)