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

2026-09-26 13:08:11 +00:00 · 2022-11-16 10:29:26 -08:00
parent 3597c79a43 c8fd4b6102
commit 421d791dd2
257 changed files with 1947 additions and 1888 deletions
@@ -16,14 +16,14 @@ If you install Rancher following the Docker installation guide, there is no upgr

 :::

-# Installation Outline
+## Installation Outline

 1. [Set up infrastructure and private registry](../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md)
 2. [Collect and publish images to your private registry](../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md)
 3. [Set up a Kubernetes cluster (Skip this step for Docker installations)](../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.md)
 4. [Install Rancher](../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md)

-# Upgrades
+## Upgrades

 To upgrade Rancher with Helm CLI in an air gap environment, follow [this procedure.](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md)

@@ -2,11 +2,11 @@
 title: AWS Marketplace Integration
 ---

-# Overview
+## Overview

 Rancher offers an integration with the AWS Marketplace which allows users to purchase a support contract with SUSE. This integration allows you easily adjust your support needs as you start to support more clusters.

-# Limitations
+## Limitations

 - You must be running Rancher v2.6.7 or higher
 - Rancher must be deployed with additional metrics enabled.
@@ -14,11 +14,12 @@ Rancher offers an integration with the AWS Marketplace which allows users to pur
 - You must purchase at least one entitlement to Rancher support through AWS Marketplace.
 - You may need additional setup to support proxy/airgap use cases. See the [prerequisites](../integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements.md) for more information.

-# How to Use
+## How to Use
+
 1. Complete the [prerequisite steps](../integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements.md).
 2. [Install the CSP Adapter](../integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md).

-# FAQ
+## FAQ

 **Can I purchase support for more nodes later on?**

@@ -11,7 +11,7 @@ If you also configure OpenLDAP as the back end to Shibboleth, it will return a S
 > The instructions in this section assume that you understand how Rancher, Shibboleth, and OpenLDAP work together. For a more detailed explanation of how it works, refer to [this page.](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/about-group-permissions.md)


-# Setting up Shibboleth in Rancher
+## Setting up Shibboleth in Rancher

 ### Shibboleth Prerequisites
 >
@@ -73,7 +73,7 @@ If you configure Shibboleth without OpenLDAP, the following caveats apply due to

 To enable searching for groups when assigning permissions in Rancher, you will need to configure a back end for the SAML provider that supports groups, such as OpenLDAP.

-# Setting up OpenLDAP in Rancher
+## Setting up OpenLDAP in Rancher

 If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then authenticated users will be able to access resources in Rancher that their groups have permissions for.

@@ -92,10 +92,10 @@ Configure the settings for the OpenLDAP server, groups and users. For help filli
 > Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users](authentication-config.md#external-authentication-configuration-and-principal-users).

 1. Log into the Rancher UI using the initial local `admin` account.
-1.	In the top left corner, click **☰ > Users & Authentication**.
+1. In the top left corner, click **☰ > Users & Authentication**.
 1. In the left navigation menu, click **Auth Provider**.
 1. Click **OpenLDAP**. The **Configure an OpenLDAP server** form will be displayed.

-# Troubleshooting
+## Troubleshooting

 If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging](../faq/technical-items.md#how-can-i-enable-debug-logging) in this documentation.
@@ -20,7 +20,7 @@ Because the API sets the actual value and the command line sets the default valu

 For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect. See the [feature flags page](../getting-started/installation-and-upgrade/installation-references/feature-flags.md) for more information.

-# Enabling Features when Starting Rancher
+## Enabling Features when Starting Rancher

 When you install Rancher, enable the feature you want with a feature flag. The command is different depending on whether you are installing Rancher on a single node or if you are doing a Kubernetes Installation of Rancher.

@@ -81,7 +81,7 @@ docker run -d -p 80:80 -p 443:443 \
 ```


-# Enabling Features with the Rancher UI
+## Enabling Features with the Rancher UI

 1. In the upper left corner, click **☰ > Global Settings**.
 1. Click **Feature Flags**.
@@ -97,7 +97,7 @@ docker run -d -p 80:80 -p 443:443 \

 **Result:** The feature is disabled.

-# Enabling Features with the Rancher API
+## Enabling Features with the Rancher API

 1. Go to `<RANCHER-SERVER-URL>/v3/features`.
 1. In the `data` section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the `id` field. Click the name of the feature you want to enable.
@@ -133,7 +133,7 @@ _Mutable: yes_

 Enable control plane authorized networks to block untrusted non-GCP source IPs from accessing the Kubernetes master through HTTPS. If selected, additional authorized networks may be added. If the cluster is created with a public endpoint, this option is useful for locking down access to the public endpoint to only certain networks, such as the network where your Rancher service is running. If the cluster only has a private endpoint, this setting is required.

-# Additional Options
+## Additional Options

 ### Cluster Addons

@@ -182,7 +182,7 @@ _Mutable: yes_

 Set the start time for a 4 hour maintenance window. The time is specified in the UTC time zone using the HH:MM format. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/maintenance-windows-and-exclusions)

-# Node Pools
+## Node Pools

 In this section, enter details describing the configuration of each node in the node pool.

@@ -256,7 +256,7 @@ You can add network tags to the node pool to make firewall rules and routes betw

 For details on tag syntax and requirements, see the [Kubernetes documentation](https://cloud.google.com/vpc/docs/add-remove-network-tags).

-# Group Details
+## Group Details

 In this section, enter details describing the node pool.

@@ -15,7 +15,7 @@ Cluster Autoscaler is designed to run on Kubernetes master nodes. It can run in

 It's possible to run a customized deployment of Cluster Autoscaler on worker nodes, but extra care needs to be taken to ensure that Cluster Autoscaler remains up and running.

-# Cloud Providers
+## Cloud Providers

 Cluster Autoscaler provides support to distinct cloud providers. For more information, go to [cluster-autoscaler supported cloud providers.](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler#deployment)

@@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem';
 In this section, you'll learn how to deploy Rancher on a Kubernetes cluster using the Helm CLI.


-# Prerequisites
+## Prerequisites

 - [Kubernetes Cluster](#kubernetes-cluster)
 - [Ingress Controller](#ingress-controller)
@@ -47,7 +47,7 @@ The following CLI tools are required for setting up the Kubernetes cluster. Plea
 - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes command-line tool.
 - [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. Refer to the [Helm version requirements](../getting-started/installation-and-upgrade/resources/helm-version-requirements.md) to choose a version of Helm to install Rancher. Refer to the [instructions provided by the Helm project](https://helm.sh/docs/intro/install/) for your specific platform.

-# Install the Rancher Helm Chart
+## Install the Rancher Helm Chart

 Rancher is installed using the [Helm](https://helm.sh/) package manager for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents. With Helm, we can create configurable deployments instead of just using static files.

@@ -5,7 +5,7 @@ description: Learn how to install Rancher in development and production environm

 This section provides an overview of the architecture options of installing Rancher, describing advantages of each option.

-# Terminology
+## Terminology

 In this section,

@@ -16,7 +16,7 @@ In this section,

 Note the `restrictedAdmin` Helm chart option available for **the Rancher Server**. When this option is set to true, the initial Rancher user has restricted access to the local Kubernetes cluster to prevent privilege escalation. For more information, see the section about the [restricted-admin role.](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md#restricted-admin)

-# Overview of Installation Options
+## Overview of Installation Options

 Rancher can be installed on these main architectures:

@@ -62,10 +62,11 @@ When the nodes in your Kubernetes cluster are running and fulfill the [node requ

 For a longer discussion of Rancher architecture, refer to the [architecture overview,](rancher-manager-architecture.md) [recommendations for production-grade architecture,](../reference-guides/rancher-manager-architecture/architecture-recommendations.md) or our [best practices guide.](../reference-guides/best-practices/rancher-server/tips-for-running-rancher.md)

-# Prerequisites
+## Prerequisites
+
 Before installing Rancher, make sure that your nodes fulfill all of the [installation requirements.](installation-requirements.md)

-# Architecture Tip
+## Architecture Tip

 For the best performance and greater security, we recommend a separate, 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](kubernetes-clusters-in-rancher-setup.md) for running your workloads.

@@ -35,7 +35,7 @@ For a list of best practices that we recommend for running the Rancher server in

 The Rancher UI works best in Firefox or Chromium based browsers (Chrome, Edge, Opera, Brave, ...).

-# Operating Systems and Container Runtime Requirements
+## Operating Systems and Container Runtime Requirements

 Rancher should work with any modern Linux distribution.

@@ -77,11 +77,11 @@ For the container runtime, RKE2 bundles its own containerd. Docker is not requir

 For details on which OS versions were tested with RKE2, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/)

-# Hardware Requirements
+## Hardware Requirements

 The following sections describe the CPU, memory, and disk requirements for the nodes where the Rancher server is installed.

-# CPU and Memory
+## CPU and Memory

 Hardware requirements scale based on the size of your Rancher deployment. Provision each individual node according to the requirements. The requirements are different depending on if you are installing Rancher in a single container with Docker, or if you are installing Rancher on a Kubernetes cluster.

@@ -134,7 +134,7 @@ These CPU and memory requirements apply to a host with a [single-node](rancher-o
 | Small           | Up to 5  | Up to 50  | 1     | 4 GB |
 | Medium          | Up to 15 | Up to 200 | 2     | 8 GB |

-# Ingress
+## Ingress

 Each node in the Kubernetes cluster that Rancher is installed on should run an Ingress.

@@ -148,11 +148,11 @@ For hosted Kubernetes clusters (EKS, GKE, AKS), you will need to set up the ingr
 - **AKS:** For details on how to install Rancher with Azure Kubernetes Service, including how to install an ingress so that the Rancher server can be accessed, refer to [this page.](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md)
 - **GKE:** For details on how to install Rancher with Google Kubernetes Engine, including how to install an ingress so that the Rancher server can be accessed, refer to [this page.](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md)

-# Disks
+## Disks

 Rancher performance depends on etcd in the cluster performance. To ensure optimal speed, we recommend always using SSD disks to back your Rancher management Kubernetes cluster. On cloud providers, you will also want to use the minimum size that allows the maximum IOPS. In larger clusters, consider using dedicated storage devices for etcd data and wal directories.

-# Networking Requirements
+## Networking Requirements

 This section describes the networking requirements for the node(s) where the Rancher server is installed.

@@ -170,6 +170,6 @@ Each node used should have a static IP configured, regardless of whether you are

 To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes. [Port Requirements](../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md) lists all the necessary ports for Rancher and Downstream Clusters for the different cluster types.

-# Dockershim Support
+## Dockershim Support

 For more information on Dockershim support, refer to [this page](../getting-started/installation-and-upgrade/installation-requirements/dockershim.md).
@@ -6,7 +6,7 @@ This section describes how to enable Istio and start using it in your projects.

 If you use Istio for traffic management, you will need to allow external traffic to the cluster. In that case, you will need to follow all of the steps below.

-# Prerequisites
+## Prerequisites

 This guide assumes you have already [installed Rancher,](installation-and-upgrade.md) and you have already [provisioned a separate Kubernetes cluster](kubernetes-clusters-in-rancher-setup.md) on which you will install Istio.

@@ -14,8 +14,7 @@ The nodes in your cluster must meet the [CPU and memory requirements.](../integr

 The workloads and services that you want to be controlled by Istio must meet [Istio's requirements.](https://istio.io/docs/setup/additional-setup/requirements/)

-
-# Install
+## Install

 :::tip Quick Setup Tip:

@@ -11,7 +11,7 @@ This section includes troubleshooting tips in the following categories:
 - [Troubleshooting nginx-proxy Nodes](../troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md)
 - [Troubleshooting Worker Nodes and Generic Components](../troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md)

-# Kubernetes Component Diagram
+## Kubernetes Component Diagram

 ![Cluster diagram](/img/clusterdiagram.svg)<br/>
 <sup>Lines show the traffic flow between components. Colors are used purely for visual aid</sup>
@@ -34,7 +34,7 @@ If you want to reuse a node from a previous custom cluster, [clean the node](../

 For more information, refer to the section on [custom nodes.](use-existing-nodes.md)

-# Programmatically Creating RKE Clusters
+### Programmatically Creating RKE Clusters

 The most common way to programmatically deploy RKE clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is [here.](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster)

@@ -75,6 +75,6 @@ RKE2 provisioning also allows you to install custom clusters on pre-provisioned

 If you want to reuse a node from a previous custom cluster, clean the node before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail.

-# Programmatically Creating RKE2 Clusters
+### Programmatically Creating RKE2 Clusters

 The most common way to programmatically deploy RKE2 clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is [here.](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster_v2)
@@ -23,11 +23,11 @@ The monitoring application allows you to:
 - Defines precomputed, frequently needed or computationally expensive expressions as new time series based on metrics collected via Prometheus
 - Expose collected metrics from Prometheus to the Kubernetes Custom Metrics API via Prometheus Adapter for use in HPA

-# How Monitoring Works
+## How Monitoring Works

 For an explanation of how the monitoring components work together, see [this page.](../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md)

-# Default Components and Deployments
+## Default Components and Deployments

 ### Built-in Dashboards

@@ -48,11 +48,11 @@ The monitoring application deploys some alerts by default. To see the default al

 For a list of monitoring components exposed in the Rancher UI, along with common use cases for editing them, see [this section.](../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md#components-exposed-in-the-rancher-ui)

-# Role-based Access Control
+## Role-based Access Control

 For information on configuring access to monitoring, see [this page.](../integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md)

-# Guides
+## Guides

 - [Enable monitoring](../how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md)
 - [Uninstall monitoring](../how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.md)
@@ -61,7 +61,7 @@ For information on configuring access to monitoring, see [this page.](../integra
 - [Persistent Grafana dashboards](../how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md)
 - [Debugging high memory usage](../how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md)

-# Configuration
+## Configuration

 ### Configuring Monitoring Resources in Rancher

@@ -78,7 +78,7 @@ For information on configuring access to monitoring, see [this page.](../integra

 For more information on `rancher-monitoring` chart options, including options to set resource limits and requests, see [this page.](../reference-guides/monitoring-v2-configuration/helm-chart-options.md)

-# Windows Cluster Support
+## Windows Cluster Support

 When deployed onto an RKE1 Windows cluster, Monitoring V2 will now automatically deploy a [windows-exporter](https://github.com/prometheus-community/windows_exporter) DaemonSet and set up a ServiceMonitor to collect metrics from each of the deployed Pods. This will populate Prometheus with `windows_` metrics that are akin to the `node_` metrics exported by [node_exporter](https://github.com/prometheus/node_exporter) for Linux hosts.

@@ -87,8 +87,7 @@ To be able to fully deploy Monitoring V2 for Windows, all of your Windows hosts
 For more details on how to upgrade wins on existing Windows hosts, refer to the section on [Windows cluster support for Monitoring V2.](../integrations-in-rancher/monitoring-and-alerting/windows-support.md)


-
-# Known Issues
+## Known Issues

 There is a [known issue](https://github.com/rancher/rancher/issues/28787#issuecomment-693611821) that K3s clusters require more default memory. If you are enabling monitoring on a K3s cluster, we recommend to setting `prometheus.prometheusSpec.resources.memory.limit` to 2500 Mi and `prometheus.prometheusSpec.resources.memory.request` to 1750 Mi.

@@ -6,7 +6,7 @@ This page captures some of the most important options for configuring Monitoring

 For information on configuring custom scrape targets and rules for Prometheus, please refer to the upstream documentation for the [Prometheus Operator.](https://github.com/prometheus-operator/prometheus-operator) Some of the most important custom resources are explained in the Prometheus Operator [design documentation.](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/design.md) The Prometheus Operator documentation can help also you set up RBAC, Thanos, or custom configuration.

-# Setting Resource Limits and Requests
+## Setting Resource Limits and Requests

 The resource requests and limits for the monitoring application can be configured when installing `rancher-monitoring`. For more information about the default limits, see [this page.](../reference-guides/monitoring-v2-configuration/helm-chart-options.md#configuring-resource-limits-and-requests)

@@ -16,7 +16,7 @@ On an idle cluster, Monitoring may have high CPU usage. To improve performance,

 :::

-# Prometheus Configuration
+## Prometheus Configuration

 It is usually not necessary to directly edit the Prometheus custom resource.

@@ -31,7 +31,7 @@ For details, see [this page.](../reference-guides/monitoring-v2-configuration/se

 For more information about directly editing the Prometheus custom resource, which may be helpful in advanced use cases, see [this page.](../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md)

-# Alertmanager Configuration
+## Alertmanager Configuration

 The Alertmanager custom resource usually doesn't need to be edited directly. For most common use cases, you can manage alerts by updating Routes and Receivers.

@@ -12,6 +12,6 @@ A Nutanix cluster may consist of multiple groups of VMs with distinct properties
 - [Creating a Nutanix Cluster](../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.md#creating-a-nutanix-aos-cluster)
 - [Provisioning Storage](../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos)

-# Creating a Nutanix Cluster
+## Creating a Nutanix Cluster

 In [this section,](../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.md) you'll learn how to use Rancher to install an [RKE](https://rancher.com/docs/rke/latest/en/) Kubernetes cluster in Nutanix AOS.
@@ -6,7 +6,7 @@ In a lot of enterprise environments, servers or VMs running on premise do not ha

 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](air-gapped-helm-cli-install.md).

-# Installation Outline
+## Installation Outline

 1. [Set up infrastructure](../getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.md)
 2. [Set up a Kubernetes cluster](../getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.md)
@@ -17,19 +17,19 @@ A Docker installation of Rancher is recommended only for development and testing

 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)

-### Privileged Access for 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
+## Requirements for OS, Docker, Hardware, and Networking

 Make sure that your node fulfills the general [installation requirements.](installation-requirements.md)

-# 1. Provision Linux Host
+## 1. Provision Linux Host

 Provision a single Linux host according to our [Requirements](installation-requirements.md) to launch your Rancher server.

-# 2. Choose an SSL Option and Install Rancher
+## 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.

@@ -9,7 +9,7 @@ To use this option you'll need access to servers you intend to use in your Kuber

 This section describes how to set up a custom cluster.

-# Creating a Cluster with Custom Nodes
+## Creating a Cluster with Custom Nodes

 :::note Want to use Windows hosts as Kubernetes workers?

@@ -17,7 +17,6 @@ See [Configuring Custom Clusters for Windows](use-windows-clusters.md) before yo

 :::

-
 ### 1. Provision a Linux Host

 Begin creation of a custom cluster by provisioning a Linux host. Your host can be:
@@ -130,7 +129,7 @@ If you share resources between clusters, you can change the tag to:
 Key=kubernetes.io/cluster/CLUSTERID, Value=shared
 ```

-# Optional Next Steps
+## Optional Next Steps

 After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster: