Merge branch 'main' into main-to-release/v2.7

2026-09-25 12:38:05 +00:00 · 2022-11-16 10:29:26 -08:00
parent 3597c79a43 c8fd4b6102
commit 421d791dd2
257 changed files with 1947 additions and 1888 deletions
@@ -238,7 +238,7 @@ spec:
  encryptionConfigSecretName: test-encryptionconfig
 ```

-# Example Credential Secret for Storing Backups in S3
+## Example Credential Secret for Storing Backups in S3

 ```yaml
 apiVersion: v1
@@ -251,7 +251,7 @@ data:
  secretKey: <Enter your base64-encoded secret key>
 ```

-# Example EncryptionConfiguration
+## Example EncryptionConfiguration

 ```yaml
 apiVersion: apiserver.config.k8s.io/v1
@@ -13,7 +13,7 @@ This guide outlines a reference architecture for provisioning downstream Rancher

 ![Solution Overview](/img/solution_overview.drawio.svg)

-# 1. VM Considerations
+## 1. VM Considerations

 ### Leverage VM Templates to Construct the Environment

@@ -31,7 +31,7 @@ Doing so will ensure node VM's are spread across multiple datastores - preventin

 It’s important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double-checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node.

-# 2. Network Considerations
+## 2. Network Considerations

 ### Leverage Low Latency, High Bandwidth Connectivity Between ETCD Nodes

@@ -41,13 +41,13 @@ Deploy etcd members within a single data center where possible to avoid latency

 Each node used should have a static IP configured. In the case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.

-# 3. Storage Considerations
+## 3. Storage Considerations

 ### Leverage SSD Drives for ETCD Nodes

 ETCD is very sensitive to write latency. Therefore, leverage SSD disks where possible.

-# 4. Backups and Disaster Recovery
+## 4. Backups and Disaster Recovery

 ### Perform Regular Downstream Cluster Backups

@@ -2,7 +2,7 @@
 title: kubectl Utility
 ---

-# kubectl
+## kubectl

 Interact with Rancher using kubectl.

@@ -18,15 +18,15 @@ Run `kubectl cluster-info` or `kubectl get pods` successfully.

 _Requirements_

-If admins have [enforced TTL on kubeconfig tokens](../../reference-guides/about-the-api/api-tokens.md#setting-ttl-on-kubeconfig-tokens), the kubeconfig file requires the [Rancher CLI](../../pages-for-subheaders/cli-with-rancher.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like: 
+If admins have [enforced TTL on kubeconfig tokens](../../reference-guides/about-the-api/api-tokens.md#setting-ttl-on-kubeconfig-tokens), the kubeconfig file requires the [Rancher CLI](../../pages-for-subheaders/cli-with-rancher.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like:
 `Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`.

-This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported: 
+This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported:

 1. Local
 2. Active Directory (LDAP only)
 3. FreeIPA
-4. OpenLDAP 
-5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth 
+4. OpenLDAP
+5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth

 When you first run kubectl, for example, `kubectl get pods`, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../reference-guides/about-the-api/api-tokens.md#setting-ttl-on-kubeconfig-tokens-period), or [gets deleted from the Rancher server](../../reference-guides/about-the-api/api-tokens.md#deleting-tokens). Upon expiration, the next `kubectl get pods` will ask you to log in with the Rancher server again.
@@ -19,7 +19,7 @@ Your cloud credential has these fields:
 | Port | Optional: configure configure the port of the vCenter or ESXi server. |
 | Username and password | Enter your vSphere login username and password. |

-# Scheduling
+## Scheduling

 Choose what hypervisor the virtual machine will be scheduled to.

@@ -16,7 +16,7 @@ In the RancherD installation instructions, we recommend running three server nod
 - [RancherD Server CLI Options](#rancherd-server-cli-options)
 - [RancherD Agent CLI Options](#rancherd-agent-cli-options)

-# Certificates for the Rancher Server
+## Certificates for the Rancher Server

 Rancherd does not use cert-manager to provision certs. Instead RancherD allows you to bring your own self-signed or trusted certs by storing the .pem files in `/etc/rancher/ssl/`. When doing this you should also set the `publicCA` parameter to `true` in your HelmChartConfig. For more information on the HelmChartConfig, refer to the section about [customizing the RancherD Helm chart.](#customizing-the-rancherd-helm-chart)

@@ -28,7 +28,7 @@ CA Certificate(self-signed): `/etc/rancher/ssl/cacerts.pem`

 Additional CA Certificate: `/etc/ssl/certs/ca-additional.pem`

-# Node Taints
+## Node Taints

 By default, server nodes will be schedulable and thus your workloads can get launched on them. If you wish to have a dedicated control plane where no user workloads will run, you can use taints. The node-taint parameter will allow you to configure nodes with taints. Here is an example of adding a node taint to the `config.yaml`:

@@ -36,7 +36,8 @@ By default, server nodes will be schedulable and thus your workloads can get lau
 node-taint:
  - "CriticalAddonsOnly=true:NoExecute"
 ```
-# Customizing the RancherD Helm Chart
+
+## Customizing the RancherD Helm Chart

 Rancher is launched as a [Helm](https://helm.sh/) chart using the cluster’s [Helm integration.](https://docs.rke2.io/helm/) This means that you can easily customize the application through a manifest file describing your custom parameters.

@@ -83,7 +84,7 @@ Put this manifest on your host in `/var/lib/rancher/rke2/server/manifests` befor
 | `useBundledSystemChart`        | false                                                 | ***bool*** - select to use the system-charts packaged with Rancher server. This option is used for air gapped installations.                     |
 | `publicCA`                     | false                                                 | ***bool*** - Set to true if your cert is signed by a public CA                                                                                                                                               |

-# RancherD Server CLI Options
+## RancherD Server CLI Options

 The command to run the Rancher management server is:

@@ -227,9 +228,7 @@ It can be run with the following options:
 |  `--cluster-reset`  | Forget all peers and become sole member of a new cluster |
 | `--secrets-encryption`  | Enable Secret encryption at rest |

-
-
-# RancherD Agent CLI Options
+## RancherD Agent CLI Options

 The following command is used to run the RancherD agent:

@@ -8,7 +8,7 @@ In [clusters launched by RKE](../../../pages-for-subheaders/launch-kubernetes-wi
 - [Editing Clusters with YAML](#editing-clusters-with-yaml)
 - [Updating ingress-nginx](#updating-ingress-nginx)

-# Configuration Options in the Rancher UI
+## Configuration Options in the Rancher UI

 To edit your cluster, open the **Global** view, make sure the **Clusters** tab is selected, and then select **&#8942; > Edit** for the cluster that you want to edit.

@@ -58,7 +58,7 @@ If you enable **Pod Security Policy Support**, use this drop-down to choose the

 If you're using a cloud provider to host cluster nodes launched by RKE, enable [this option](../../../pages-for-subheaders/set-up-cloud-providers.md) so that you can use the cloud provider's native features. If you want to store persistent data for your cloud-hosted cluster, this option is required.

-# Editing Clusters with YAML
+## Editing Clusters with YAML

 Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration, by specifying them in YAML.

@@ -71,7 +71,7 @@ For an example of RKE config file syntax, see the [RKE documentation](https://ra

 For the complete reference of configurable options for RKE Kubernetes clusters in YAML, see the [RKE documentation.](https://rancher.com/docs/rke/latest/en/config-options/)

-# Updating ingress-nginx
+## Updating ingress-nginx

 Clusters that were created before Kubernetes 1.16 will have an `ingress-nginx` `updateStrategy` of `OnDelete`. Clusters that were created with Kubernetes 1.16 or newer will have `RollingUpdate`.

@@ -21,7 +21,7 @@ For further details on configuring OpenLDAP, refer to the [official documentatio
 3. Once the user has been found, he is authenticated with another LDAP bind request using the user's DN and provided password.
 4. Once authentication succeeded, Rancher then resolves the group memberships both from the membership attribute in the user's object and by performing a group search based on the configured user mapping attribute.

-# OpenLDAP Server Configuration
+## OpenLDAP Server Configuration

 You will need to enter the address, port, and protocol to connect to your OpenLDAP server. `389` is the standard port for insecure traffic, `636` for TLS traffic.

@@ -44,7 +44,7 @@ If you are in doubt about the correct values to enter in the user/group Search B
 | User Search Base | Enter the Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".|
 | Group Search Base | If your groups live under a different node than the one configured under `User Search Base` you will need to provide the Distinguished Name here. Otherwise leave this field empty. For example: "ou=groups,dc=acme,dc=com".|

-# User/Group Schema Configuration
+## User/Group Schema Configuration

 If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the **Customize Schema** section to match it.

@@ -145,7 +145,7 @@ kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca-

 For details on installing Rancher with a private registry, see [Air Gapped Helm CLI Install](../../pages-for-subheaders/air-gapped-helm-cli-install.md).

-# External TLS Termination
+## External TLS Termination

 We recommend configuring your load balancer as a Layer 4 balancer, forwarding plain 80/tcp and 443/tcp to the Rancher Management cluster nodes. The Ingress Controller on the cluster will redirect http traffic on port 80 to https on port 443.

@@ -4,14 +4,14 @@ title: TLS Settings

 Changing the default TLS settings depends on the chosen installation method.

-# Running Rancher in a highly available Kubernetes cluster
+## Running Rancher in a highly available Kubernetes cluster

 When you install Rancher inside of a Kubernetes cluster, TLS is offloaded at the cluster's ingress controller. The possible TLS settings depend on the used ingress controller:

 * nginx-ingress-controller (default for RKE1 and RKE2): [Default TLS Version and Ciphers](https://kubernetes.github.io/ingress-nginx/user-guide/tls/#default-tls-version-and-ciphers).
 * traefik (default for K3s): [TLS Options](https://doc.traefik.io/traefik/https/tls/#tls-options).

-# Running Rancher in a single Docker container
+## Running Rancher in a single Docker container

 The default TLS configuration only accepts TLS 1.2 and secure TLS cipher suites. You can change this by setting the following environment variables:

@@ -4,8 +4,7 @@ title: Tools for Logging, Monitoring, and Visibility

 Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently.

-
-# Logging
+## Logging

 Logging is helpful because it allows you to:

@@ -18,7 +17,8 @@ Logging is helpful because it allows you to:
 Rancher can integrate with Elasticsearch, splunk, kafka, syslog, and fluentd.

 For more information, refer to the logging documentation [here.](../pages-for-subheaders/logging.md)
-# Monitoring and Alerts
+
+## Monitoring and Alerts

 Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with [Prometheus](https://prometheus.io/), a leading open-source monitoring solution.

@@ -30,18 +30,19 @@ Alerts are rules that trigger those notifications. Before you can receive alerts

 For more information, refer to the monitoring documentation [here.](../pages-for-subheaders/monitoring-and-alerting.md)

-# Istio
+## Istio

 [Istio](https://istio.io/) is an open-source tool that makes it easier for DevOps teams to observe, control, troubleshoot, and secure the traffic within a complex network of microservices.

 Rancher's integration with Istio was improved in Rancher v2.5.

 For more information, refer to the Istio documentation [here.](../pages-for-subheaders/istio.md)
-# OPA Gatekeeper
+
+## OPA Gatekeeper

 [OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper) is an open-source project that provides integration between OPA and Kubernetes to provide policy control via admission controller webhooks. For details on how to enable Gatekeeper in Rancher, refer to the [OPA Gatekeeper section.](../explanations/integrations-in-rancher/opa-gatekeeper.md)

-# CIS Scans
+## CIS Scans

 Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark.

@@ -4,7 +4,7 @@ title: Architecture Recommendations

 Kubernetes cluster. If you are installing Rancher on a single node, the main architecture recommendation that applies to your installation is that the node running Rancher should be [separate from downstream clusters.](#separation-of-rancher-and-user-clusters)

-# Separation of Rancher and User Clusters
+## Separation of Rancher and User Clusters

 A user cluster is a downstream Kubernetes cluster that runs your apps and services.

@@ -14,7 +14,7 @@ If Rancher is intended to manage downstream Kubernetes clusters, the Kubernetes

 ![Separation of Rancher Server from User Clusters](/img/rancher-architecture-separation-of-rancher-server.svg)

-# Why HA is Better for Rancher in Production
+## Why HA is Better for Rancher in Production

 We recommend installing the Rancher server on a high-availability Kubernetes cluster, primarily because it protects the Rancher server data. In a high-availability installation, a load balancer serves as the single point of contact for clients, distributing network traffic across multiple servers in the cluster and helping to prevent any one server from becoming a point of failure.

@@ -36,7 +36,7 @@ In an RKE installation, the cluster data is replicated on each of three etcd nod

 ![Architecture of an RKE Kubernetes cluster running the Rancher management server](/img/rke-server-storage.svg)

-# Recommended Load Balancer Configuration for Kubernetes Installations
+## Recommended Load Balancer Configuration for Kubernetes Installations

 We recommend the following configurations for the load balancer and Ingress controllers:

@@ -49,13 +49,13 @@ We recommend the following configurations for the load balancer and Ingress cont

 ![Rancher HA](/img/ha/rancher2ha.svg)

-# Environment for Kubernetes Installations
+## Environment for Kubernetes Installations

 It is strongly recommended to install Rancher on a Kubernetes cluster on hosted infrastructure such as Amazon's EC2 or Google Compute Engine.

 For the best performance and greater security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters](../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md) for running your workloads.

-# Recommended Node Roles for Kubernetes Installations
+## Recommended Node Roles for Kubernetes Installations

 The below recommendations apply when Rancher is installed on a K3s Kubernetes cluster or an RKE Kubernetes cluster.

@@ -97,7 +97,7 @@ Because no additional workloads will be deployed on the Rancher server cluster,

 For more best practices for downstream clusters, refer to the [production checklist](../../pages-for-subheaders/checklist-for-production-ready-clusters.md) or our [best practices guide.](../../pages-for-subheaders/best-practices.md)

-# Architecture for an Authorized Cluster Endpoint
+## Architecture for an Authorized Cluster Endpoint

 If you are using an [authorized cluster endpoint,](../../pages-for-subheaders/rancher-manager-architecture.md#4-authorized-cluster-endpoint) we recommend creating an FQDN pointing to a load balancer which balances traffic across your nodes with the `controlplane` role.

@@ -17,7 +17,7 @@ The following descriptions correspond to the numbers in the diagram above:
 3. [Node Agents](#3-node-agents)
 4. [Authorized Cluster Endpoint](#4-authorized-cluster-endpoint)

-### 1. The Authentication Proxy
+## 1. The Authentication Proxy

 In this diagram, a user named Bob wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a `kubectl` command to see
 the pods. Bob is authenticated through Rancher's authentication proxy.
@@ -28,7 +28,7 @@ Rancher communicates with Kubernetes clusters using a [service account,](https:/

 By default, Rancher generates a [kubeconfig file](../../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) that contains credentials for proxying through the Rancher server to connect to the Kubernetes API server on a downstream user cluster. The kubeconfig file (`kube_config_cluster.yml`) contains full access to the cluster.

-### 2. Cluster Controllers and Cluster Agents
+## 2. Cluster Controllers and Cluster Agents

 Each downstream user cluster has a cluster agent, which opens a tunnel to the corresponding cluster controller within the Rancher server.

@@ -48,13 +48,13 @@ The cluster agent, also called `cattle-cluster-agent`, is a component that runs
 -  Applies the roles and bindings defined in each cluster's global policies
 - Communicates between the cluster and Rancher server (through a tunnel to the cluster controller) about events, stats, node info, and health

-### 3. Node Agents
+## 3. Node Agents

 If the cluster agent (also called `cattle-cluster-agent`) is not available, one of the node agents creates a tunnel to the cluster controller to communicate with Rancher.

 The `cattle-node-agent` is deployed using a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) resource to make sure it runs on every node in a Rancher-launched Kubernetes cluster. It is used to interact with the nodes when performing cluster operations. Examples of cluster operations include upgrading the Kubernetes version and creating or restoring etcd snapshots.

-### 4. Authorized Cluster Endpoint
+## 4. Authorized Cluster Endpoint

 An authorized cluster endpoint allows users to connect to the Kubernetes API server of a downstream cluster without having to route their requests through the Rancher authentication proxy.

@@ -71,11 +71,11 @@ Like the authorized cluster endpoint, the `kube-api-auth` authentication service

 > **Example scenario:** Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant latency, which Alice can reduce by using the authorized cluster endpoint.

-With this endpoint enabled for the downstream cluster, Rancher generates an extra Kubernetes context in the kubeconfig file in order to connect directly to the cluster. This file has the credentials for `kubectl` and `helm`. 
+With this endpoint enabled for the downstream cluster, Rancher generates an extra Kubernetes context in the kubeconfig file in order to connect directly to the cluster. This file has the credentials for `kubectl` and `helm`.

 You will need to use a context defined in this kubeconfig file to access the cluster if Rancher goes down. Therefore, we recommend exporting the kubeconfig file so that if Rancher goes down, you can still use the credentials in the file to access your cluster. For more information, refer to the section on accessing your cluster with [kubectl and the kubeconfig file.](../../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md)

-# Important Files
+## Important Files

 The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster:

@@ -87,7 +87,7 @@ The files mentioned below are needed to maintain, troubleshoot and upgrade your

 For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the [kubeconfig file](../../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) documentation.

-# Tools for Provisioning Kubernetes Clusters
+## Tools for Provisioning Kubernetes Clusters

 The tools that Rancher uses to provision downstream user clusters depends on the type of cluster that is being provisioned.

@@ -113,7 +113,7 @@ Rancher provisions this type of cluster using [kontainer-engine.](https://github

 In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster.

-# Rancher Server Components and Source Code
+## Rancher Server Components and Source Code

 This diagram shows each component that the Rancher server is composed of:

@@ -15,7 +15,7 @@ The following commands are available:
 | [stats](#stats) | Stream system metrics from nodes.
 | [remove](#remove) | Remove Kubernetes resources created by Rancher.

-# Download System Tools
+## Download System Tools

 You can download the latest version of System Tools from the [GitHub releases page](https://github.com/rancher/system-tools/releases/latest). Download the version of `system-tools` for the OS that you are using to interact with the cluster.

@@ -38,7 +38,7 @@ After you download the tools, complete the following actions:
    chmod +x system-tools
    ```

-# Logs
+## Logs

 The logs subcommand will collect log files of core Kubernetes cluster components from nodes in [Rancher-launched Kubernetes clusters](../pages-for-subheaders/launch-kubernetes-with-rancher.md) or nodes on an [RKE Kubernetes cluster that Rancher is installed on.](../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md). See [Troubleshooting](../troubleshooting.md) for a list of core Kubernetes cluster components.

@@ -58,7 +58,7 @@ The following are the options for the logs command:
 | `--output <FILENAME>, -o cluster-logs.tar`             | Name of the created tarball containing the logs. If no output filename is defined, the options defaults to `cluster-logs.tar`.
 | `--node <NODENAME>, -n node1`                         | Specify the nodes to collect the logs from. If no node is specified, logs from all nodes in the cluster will be collected.

-# Stats
+## Stats

 The stats subcommand will display system metrics from nodes in [Rancher-launched Kubernetes clusters](../pages-for-subheaders/launch-kubernetes-with-rancher.md) or nodes in an [RKE Kubernetes cluster that Rancher is installed on.](../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md).

@@ -78,7 +78,7 @@ The following are the options for the stats command:
 | `--node <NODENAME>, -n node1`                          | Specify the nodes to display the system metrics from. If no node is specified, logs from all nodes in the cluster will be displayed.
 | `--stats-command value, -s value`                      | The command to run to display the system metrics. If no command is defined, the options defaults to `/usr/bin/sar -u -r -F 1 1`.

-# Remove
+## Remove

 >**Warning:** This command will remove data from your etcd nodes. Make sure you have created a [backup of etcd](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md) before executing the command.