From 15a1e067a6183eac67f811668d971641891d0dd3 Mon Sep 17 00:00:00 2001 From: Billy Tat Date: Fri, 28 Oct 2022 15:52:16 -0700 Subject: [PATCH 1/3] Convert h1 to h2 (2.6) --- .../air-gapped-upgrades.md | 4 +- .../helm-chart-options.md | 2 +- .../installation-references/tls-settings.md | 4 +- .../port-requirements.md | 6 +-- .../publish-images.md | 4 +- .../resources/add-tls-secrets.md | 4 +- .../resources/local-system-charts.md | 2 +- .../resources/update-rancher-certificate.md | 38 +++++++++---------- .../resources/upgrade-cert-manager.md | 2 +- docs/getting-started/overview.md | 10 ++--- .../enable-istio-in-cluster.md | 4 +- .../generate-and-view-traffic.md | 2 +- .../istio-setup-guide/set-up-istio-gateway.md | 6 +-- .../create-persistent-grafana-dashboard.md | 4 +- .../enable-monitoring.md | 6 +-- .../advanced-configuration/prometheus.md | 2 +- .../advanced-configuration/prometheusrules.md | 2 +- .../creator-permissions.md | 2 +- .../configure-google-oauth.md | 6 +-- .../configure-rancher-for-ms-adfs.md | 2 +- .../openldap-config-reference.md | 4 +- .../custom-branding.md | 2 +- ...up-rancher-launched-kubernetes-clusters.md | 14 +++---- ...aunched-kubernetes-clusters-from-backup.md | 4 +- .../helm-charts-in-rancher/create-apps.md | 6 +-- .../amazon-elb-load-balancer.md | 4 +- .../k3s-for-rancher.md | 4 +- .../rke1-for-rancher.md | 4 +- .../rke2-for-rancher.md | 5 ++- .../set-up-cloud-providers/azure.md | 4 +- .../configure-out-of-tree-vsphere.md | 6 +-- .../migrate-from-in-tree-to-out-of-tree.md | 4 +- .../kubernetes-and-docker-registries.md | 6 +-- .../ingress-configuration.md | 2 +- .../kubernetes-resources-setup/secrets.md | 6 +-- .../create-a-digitalocean-cluster.md | 3 +- .../create-an-amazon-ec2-cluster.md | 4 +- .../create-an-azure-cluster.md | 4 +- .../provision-kubernetes-clusters-in-aos.md | 8 ++-- ...rovision-kubernetes-clusters-in-vsphere.md | 2 +- .../use-aws-ec2-auto-scaling-groups.md | 2 +- .../use-fleet-behind-a-proxy.md | 2 +- .../air-gapped-helm-cli-install.md | 4 +- .../aws-cloud-marketplace.md | 9 +++-- .../configure-shibboleth-saml.md | 8 ++-- .../enable-experimental-features.md | 6 +-- .../gke-cluster-configuration.md | 6 +-- .../install-cluster-autoscaler.md | 2 +- ...install-upgrade-on-a-kubernetes-cluster.md | 4 +- .../installation-and-upgrade.md | 9 +++-- .../installation-requirements.md | 14 +++---- .../pages-for-subheaders/istio-setup-guide.md | 5 +-- .../kubernetes-components.md | 2 +- .../launch-kubernetes-with-rancher.md | 4 +- .../monitoring-and-alerting.md | 15 ++++---- .../monitoring-v2-configuration-guides.md | 6 +-- docs/pages-for-subheaders/nutanix.md | 2 +- .../rancher-behind-an-http-proxy.md | 2 +- .../rancher-on-a-single-node-with-docker.md | 8 ++-- .../use-existing-nodes.md | 5 +-- .../backup-restore-configuration/examples.md | 4 +- .../rancher-managed-clusters-in-vsphere.md | 8 ++-- .../cli-with-rancher/kubectl-utility.md | 2 +- .../pipelines/pipeline-configuration.md | 5 ++- .../architecture-recommendations.md | 12 +++--- ...unicating-with-downstream-user-clusters.md | 8 ++-- docs/reference-guides/system-tools.md | 6 +-- .../troubleshooting-controlplane-nodes.md | 6 +-- .../troubleshooting-nginx-proxy.md | 6 +-- ...ing-worker-nodes-and-generic-components.md | 4 +- 70 files changed, 193 insertions(+), 191 deletions(-) diff --git a/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md b/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md index 85bf16d827e..07f34e1d4d8 100644 --- a/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md +++ b/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md @@ -72,7 +72,7 @@ Use `kubectl` to apply the rendered manifests. kubectl -n cattle-system apply -R -f ./rancher ``` -# Verify the Upgrade +## Verify the Upgrade Log into Rancher to confirm that the upgrade succeeded. @@ -84,6 +84,6 @@ See [Restoring Cluster Networking](../../../../versioned_docs/version-2.0-2.4/ge ::: -# Known Upgrade Issues +## Known Upgrade Issues A 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) diff --git a/docs/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md b/docs/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md index 83c8e7da685..ad243672146 100644 --- a/docs/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md +++ b/docs/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md @@ -165,7 +165,7 @@ kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca- For details on installing Rancher with a private registry, see the [air gap installation docs.](../../../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. diff --git a/docs/getting-started/installation-and-upgrade/installation-references/tls-settings.md b/docs/getting-started/installation-and-upgrade/installation-references/tls-settings.md index 807a8227b24..108b1b12b64 100644 --- a/docs/getting-started/installation-and-upgrade/installation-references/tls-settings.md +++ b/docs/getting-started/installation-and-upgrade/installation-references/tls-settings.md @@ -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: diff --git a/docs/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md b/docs/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md index 61dd449096f..52f9fa45373 100644 --- a/docs/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md +++ b/docs/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md @@ -11,7 +11,7 @@ import PortsImportedHosted from '@site/src/components/PortsImportedHosted' To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes. -# Rancher Nodes +## Rancher Nodes The following table lists the ports that need to be open to and from nodes that are running the Rancher server. @@ -174,7 +174,7 @@ The following tables break down the port requirements for Rancher nodes, for inb -# Downstream Kubernetes Cluster Nodes +## Downstream Kubernetes Cluster Nodes Downstream Kubernetes clusters run your apps and services. This section describes what ports need to be opened on the nodes in downstream clusters so that Rancher can communicate with them. @@ -249,7 +249,7 @@ The following table depicts the port requirements for [registered clusters](../. -# Other Port Considerations +## Other Port Considerations ### Commonly Used Ports diff --git a/docs/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md b/docs/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md index 6e274ef1620..e15963fb7bd 100644 --- a/docs/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md +++ b/docs/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md @@ -127,7 +127,7 @@ The `rancher-images.txt` is expected to be on the workstation in the same direct For Rancher servers that will provision Linux and Windows clusters, there are distinctive steps to populate your private registry for the Windows images and the Linux images. Since a Windows cluster is a mix of Linux and Windows nodes, the Linux images pushed into the private registry are manifests. -# Windows Steps +## Windows Steps The Windows images need to be collected and pushed from a Windows server workstation. @@ -206,7 +206,7 @@ The `rancher-windows-images.txt` is expected to be on the workstation in the sam ./rancher-load-images.ps1 --registry ``` -# Linux Steps +## Linux Steps The Linux images need to be collected and pushed from a Linux host, but _must be done after_ populating the Windows images into the private registry. These step are different from the Linux only steps as the Linux images that are pushed will actually manifests that support Windows and Linux images. diff --git a/docs/getting-started/installation-and-upgrade/resources/add-tls-secrets.md b/docs/getting-started/installation-and-upgrade/resources/add-tls-secrets.md index 17423a59154..8e72f41c461 100644 --- a/docs/getting-started/installation-and-upgrade/resources/add-tls-secrets.md +++ b/docs/getting-started/installation-and-upgrade/resources/add-tls-secrets.md @@ -23,7 +23,7 @@ If you want to replace the certificate, you can delete the `tls-rancher-ingress` ::: -# Using a Private CA Signed Certificate +## Using a Private CA Signed Certificate If you are using a private CA, Rancher requires a copy of the CA certificate which is used by the Rancher Agent to validate the connection to the server. @@ -40,6 +40,6 @@ The configured `tls-ca` secret is retrieved when Rancher starts. On a running Ra ::: -# Updating a Private CA Certificate +## Updating a Private CA Certificate Follow the steps on [this page](update-rancher-certificate.md) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate. \ No newline at end of file diff --git a/docs/getting-started/installation-and-upgrade/resources/local-system-charts.md b/docs/getting-started/installation-and-upgrade/resources/local-system-charts.md index b2c1fd6dd9e..9ddb246f05f 100644 --- a/docs/getting-started/installation-and-upgrade/resources/local-system-charts.md +++ b/docs/getting-started/installation-and-upgrade/resources/local-system-charts.md @@ -6,7 +6,7 @@ The [System Charts](https://github.com/rancher/system-charts) repository contain In an air gapped installation of Rancher, you will need to configure Rancher to use a local copy of the system charts. This section describes how to use local system charts using a CLI flag. -# Using Local System Charts +## Using Local System Charts A local copy of `system-charts` has been packaged into the `rancher/rancher` container. To be able to use these features in an air gap install, you will need to run the Rancher install command with an extra environment variable, `CATTLE_SYSTEM_CATALOG=bundled`, which tells Rancher to use the local copy of the charts instead of attempting to fetch them from GitHub. diff --git a/docs/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md b/docs/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md index 8bf7bd86b2a..b33cca0021c 100644 --- a/docs/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md +++ b/docs/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md @@ -2,7 +2,7 @@ title: Updating the Rancher Certificate --- -# Updating a Private CA Certificate +## Updating a Private CA Certificate Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate. @@ -16,7 +16,7 @@ A summary of the steps is as follows: The details of these instructions are below. -## 1. Create/update the certificate secret resource +### 1. Create/update the certificate secret resource First, concatenate the server certificate followed by any intermediate certificate(s) to a file named `tls.crt` and provide the corresponding certificate key in a file named `tls.key`. @@ -37,7 +37,7 @@ $ kubectl -n cattle-system create secret tls tls-rancher-ingress \ --dry-run --save-config -o yaml | kubectl apply -f - ``` -## 2. Create/update the CA certificate secret resource +### 2. Create/update the CA certificate secret resource If the new certificate was signed by a private CA, you will need to copy the corresponding root CA certificate into a file named `cacerts.pem` and create or update the `tls-ca secret` in the `cattle-system` namespace. If the certificate was signed by an intermediate CA, then the `cacerts.pem` must contain both the intermediate and root CA certificates (in this order). @@ -56,7 +56,7 @@ $ kubectl -n cattle-system create secret generic tls-ca \ --dry-run --save-config -o yaml | kubectl apply -f - ``` -## 3. Reconfigure the Rancher deployment +### 3. Reconfigure the Rancher deployment :::note @@ -95,18 +95,18 @@ helm upgrade rancher rancher-stable/rancher \ When the upgrade is completed, navigate to `https:///v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier. -## 4. Reconfigure Rancher agents to trust the private CA +### 4. Reconfigure Rancher agents to trust the private CA This section covers three methods to reconfigure Rancher agents to trust the private CA. This step is required if either of the following is true: - Rancher was initially configured to use the Rancher self-signed certificate (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`) - The root CA certificate for the new custom certificate has changed -### Why is this step required? +#### Why is this step required? When Rancher is configured with a certificate signed by a private CA, the CA certificate chain is downloaded into Rancher agent containers. Agents compare the checksum of the downloaded certificate against the `CATTLE_CA_CHECKSUM` environment variable. This means that, when the private CA certificate is changed on Rancher server side, the environvment variable `CATTLE_CA_CHECKSUM` must be updated accordingly. -### Which method should I choose? +#### Which method should I choose? Method 1 is the easiest one but requires all clusters to be connected to Rancher after the certificates have been rotated. This is usually the case if the process is performed right after updating the Rancher deployment (Step 3). @@ -114,7 +114,7 @@ If the clusters have lost connection to Rancher but you have [Authorized Cluster Method 3 can be used as a fallback if method 1 and 2 are unfeasible. -### Method 1: Kubectl command +#### Method 1: Kubectl command For each cluster under Rancher management (except the `local` Rancher management cluster) run the following command using the Kubeconfig file of the Rancher management cluster (RKE or K3S). @@ -125,7 +125,7 @@ kubectl patch clusters.management.cattle.io -p '{"statu This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. -### Method 2: Manually update checksum +#### Method 2: Manually update checksum Manually patch the agent Kubernetes resources by updating the `CATTLE_CA_CHECKSUM` environment variable to the value matching the checksum of the new CA certificate. Generate the new checksum value like so: @@ -141,7 +141,7 @@ $ kubectl edit -n cattle-system ds/cattle-node-agent $ kubectl edit -n cattle-system deployment/cattle-cluster-agent ``` -### Method 3: Recreate Rancher agents +#### Method 3: Recreate Rancher agents With this method you are recreating the Rancher agents by running a set of commands on a controlplane node of each downstream cluster. @@ -150,15 +150,15 @@ First, generate the agent definitions as described here: https://gist.github.com Then, connect to a controlplane node of the downstream cluster via SSH, create a Kubeconfig and apply the definitions: https://gist.github.com/superseb/b14ed3b5535f621ad3d2aa6a4cd6443b -## 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher +### 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher Select 'Force Update' for the clusters within the [Continuous Delivery](../../../how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.md#accessing-fleet-in-the-rancher-ui) view of the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher. -### Why is this step required? +#### Why is this step required? Fleet agents in Rancher managed clusters store kubeconfig that is used to connect to the Rancher proxied kube-api in the fleet-agent secret of the fleet-system namespace. The kubeconfig contains a certificate-authority-data block containing the Rancher CA. When changing the Rancher CA, this block needs to be updated for a successful connection of the fleet-agent to Rancher. -# Updating from a Private CA Certificate to a Common Certificate +## Updating from a Private CA Certificate to a Common Certificate :::note @@ -166,7 +166,7 @@ It is possible to perform the opposite procedure as shown above: you may change ::: -## 1. Create/update the certificate secret resource +### 1. Create/update the certificate secret resource First, concatenate the server certificate followed by any intermediate certificate(s) to a file named `tls.crt` and provide the corresponding certificate key in a file named `tls.key`. @@ -187,7 +187,7 @@ $ kubectl -n cattle-system create secret tls tls-rancher-ingress \ --dry-run --save-config -o yaml | kubectl apply -f - ``` -## 2. Delete the CA certificate secret resource +### 2. Delete the CA certificate secret resource You will delete the `tls-ca secret` in the `cattle-system` namespace as it is no longer needed. You may also optionally save a copy of the `tls-ca secret` if desired. @@ -203,7 +203,7 @@ To delete the existing `tls-ca` secret: kubectl -n cattle-system delete secret tls-ca ``` -## 3. Reconfigure the Rancher deployment +### 3. Reconfigure the Rancher deployment :::note Important: @@ -249,14 +249,14 @@ On upgrade, you can either set privateCA=false ``` -## 4. Reconfigure Rancher agents for the non-private/common certificate +### 4. Reconfigure Rancher agents for the non-private/common certificate `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). -## 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher +### 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher Select 'Force Update' for the clusters within the [Continuous Delivery](../../../how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.md#accessing-fleet-in-the-rancher-ui) view of the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher. -### Why is this step required? +#### Why is this step required? Fleet agents in Rancher managed clusters store kubeconfig that is used to connect to the Rancher proxied kube-api in the fleet-agent secret of the fleet-system namespace. The kubeconfig contains a certificate-authority-data block containing the Rancher CA. When changing the Rancher CA, this block needs to be updated for a successful connection of the fleet-agent to Rancher. diff --git a/docs/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md b/docs/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md index 181aca14109..52a59e22f3e 100644 --- a/docs/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md +++ b/docs/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md @@ -19,7 +19,7 @@ If you are upgrading cert-manager to the latest version from a version older tha ::: -# Upgrade Cert-Manager +## Upgrade Cert-Manager The namespace used in these instructions depends on the namespace cert-manager is currently installed in. If it is in kube-system use that in the instructions below. You can verify by running `kubectl get pods --all-namespaces` and checking which namespace the cert-manager-\* pods are listed in. Do not change the namespace cert-manager is running in or this can cause issues. diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md index 8b3888e2150..479b0e61844 100644 --- a/docs/getting-started/overview.md +++ b/docs/getting-started/overview.md @@ -4,11 +4,11 @@ title: Overview Rancher is a container management platform built for organizations that deploy containers in production. Rancher makes it easy to run Kubernetes everywhere, meet IT requirements, and empower DevOps teams. -# Run Kubernetes Everywhere +## Run Kubernetes Everywhere Kubernetes has become the container orchestration standard. Most cloud and virtualization vendors now offer it as standard infrastructure. Rancher users have the choice of creating Kubernetes clusters with Rancher Kubernetes Engine (RKE) or cloud Kubernetes services, such as GKE, AKS, and EKS. Rancher users can also import and manage their existing Kubernetes clusters created using any Kubernetes distribution or installer. -# Meet IT Requirements +## Meet IT Requirements Rancher supports centralized authentication, access control, and monitoring for all Kubernetes clusters under its control. For example, you can: @@ -16,7 +16,7 @@ Rancher supports centralized authentication, access control, and monitoring for - Setup and enforce access control and security policies across all users, groups, projects, clusters, and clouds. - View the health and capacity of your Kubernetes clusters from a single-pane-of-glass. -# Empower DevOps Teams +## Empower DevOps Teams Rancher provides an intuitive user interface for DevOps engineers to manage their application workload. The user does not need to have in-depth knowledge of Kubernetes concepts to start using Rancher. Rancher catalog contains a set of useful DevOps tools. Rancher is certified with a wide selection of cloud native ecosystem products, including, for example, security tools, monitoring systems, container registries, and storage and networking drivers. @@ -24,7 +24,7 @@ The following figure illustrates the role Rancher plays in IT and DevOps organiz ![Platform](/img/platform.png) -# Features of the Rancher API Server +## Features of the Rancher API Server The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities: @@ -52,7 +52,7 @@ The Rancher API server is built on top of an embedded Kubernetes API server and - **Monitoring:** Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution. - **Alerting:** To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. -# Editing Downstream Clusters with Rancher +## Editing Downstream Clusters with Rancher The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters [provisioned by RKE](../pages-for-subheaders/launch-kubernetes-with-rancher.md) have **Cluster Options** available for editing. diff --git a/docs/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md b/docs/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md index 7e2d904749a..a578261769c 100644 --- a/docs/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md +++ b/docs/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md @@ -16,7 +16,7 @@ title: 1. Enable Istio in the Cluster 1. Click **Apps & Marketplace**. 1. Click **Charts**. 1. Click **Istio**. -1. If you have not already installed your own monitoring app, you will be prompted to install the rancher-monitoring app. Optional: Set your Selector or Scrape config options on rancher-monitoring app install. +1. If you have not already installed your own monitoring app, you will be prompted to install the rancher-monitoring app. Optional: Set your Selector or Scrape config options on rancher-monitoring app install. 1. Optional: Configure member access and [resource limits](../../../integrations-in-rancher/istio/cpu-and-memory-allocations.md) for the Istio components. Ensure you have enough resources on your worker nodes to enable Istio. 1. Optional: Make additional configuration changes to values.yaml if needed. 1. Optional: Add additional resources or configuration via the [overlay file.](../../../pages-for-subheaders/configuration-options.md#overlay-file) @@ -24,6 +24,6 @@ title: 1. Enable Istio in the Cluster **Result:** Istio is installed at the cluster level. -# Additional Config Options +## Additional Config Options For more information on configuring Istio, refer to the [configuration reference.](../../../pages-for-subheaders/configuration-options.md) diff --git a/docs/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md b/docs/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md index c79bef9c06a..070dc3a557b 100644 --- a/docs/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md +++ b/docs/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md @@ -4,7 +4,7 @@ title: 6. Generate and View Traffic This section describes how to view the traffic that is being managed by Istio. -# The Kiali Traffic Graph +## The Kiali Traffic Graph The Istio overview page provides a link to the Kiali dashboard. From the Kiali dashboard, you are able to view graphs for each namespace. The Kiali graph provides a powerful way to visualize the topology of your Istio service mesh. It shows you which services communicate with each other. diff --git a/docs/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md b/docs/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md index 0e932884787..bcafaaca525 100644 --- a/docs/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md +++ b/docs/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md @@ -16,7 +16,7 @@ For more information on the Istio gateway, refer to the [Istio documentation.](h ![In an Istio-enabled cluster, you can have two Ingresses: the default Nginx Ingress, and the default Istio controller.](/img/istio-ingress.svg) -# Enable an Istio Gateway +## Enable an Istio Gateway The ingress gateway is a Kubernetes service that will be deployed in your cluster. The Istio Gateway allows for more extensive customization and flexibility. @@ -29,7 +29,7 @@ The ingress gateway is a Kubernetes service that will be deployed in your cluste **Result:** The gateway is deployed, and will now route traffic with applied rules. -# Example Istio Gateway +## Example Istio Gateway We add the BookInfo app deployments in services when going through the Workloads example. Next we add an Istio Gateway so that the app is accessible from outside your cluster. @@ -127,7 +127,7 @@ To get the ingress gateway URL and port, For help inspecting the Istio controller URL and ports, try the commands the [Istio documentation.](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports) -# Troubleshooting +## Troubleshooting The [official Istio documentation](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#troubleshooting) suggests `kubectl` commands to inspect the correct ingress host and ingress port for external requests. diff --git a/docs/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md b/docs/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md index 7456187a062..4676292e0cb 100644 --- a/docs/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md +++ b/docs/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md @@ -10,7 +10,7 @@ To allow the Grafana dashboard to persist after the Grafana instance restarts, a - [Creating a Persistent Grafana Dashboard](#creating-a-persistent-grafana-dashboard) - [Known Issues](#known-issues) -# Creating a Persistent Grafana Dashboard +## Creating a Persistent Grafana Dashboard @@ -144,7 +144,7 @@ helm.sh/resource-policy: "keep" -# Known Issues +## Known Issues For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the `cattle-dashboards` namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation `helm.sh/resource-policy: "keep"`. diff --git a/docs/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md b/docs/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md index 9c954304b8d..1c8a5006fd3 100644 --- a/docs/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md +++ b/docs/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md @@ -8,7 +8,7 @@ This page describes how to enable monitoring and alerting within a cluster using You can enable monitoring with or without SSL. -# Requirements +## Requirements - Make sure that you are allowing traffic on port 9796 for each of your nodes because Prometheus will scrape metrics from here. - Make sure your cluster fulfills the resource requirements. The cluster should have at least 1950Mi memory available, 2700m CPU, and 50Gi storage. A breakdown of the resource limits and requests is [here.](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#configuring-resource-limits-and-requests) @@ -27,13 +27,13 @@ If you want to set up Alertmanager, Grafana or Ingress, it has to be done with t ::: -# Setting Resource Limits and Requests +#Setting Resource Limits and Requests The resource requests and limits can be configured when installing `rancher-monitoring`. To configure Prometheus resources from the Rancher UI, click **Apps & Marketplace > Monitoring** in the upper left corner. For more information about the default limits, see [this page.](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#configuring-resource-limits-and-requests) -# Install the Monitoring Application +## Install the Monitoring Application ### Enable Monitoring for use without SSL diff --git a/docs/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md b/docs/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md index 13bf81613e5..7a818f180c3 100644 --- a/docs/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md +++ b/docs/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md @@ -10,7 +10,7 @@ This section assumes familiarity with how monitoring components work together. F ::: -# About the Prometheus Custom Resource +## About the Prometheus Custom Resource The Prometheus CR defines a desired Prometheus deployment. The Prometheus Operator observes the Prometheus CR. When the CR changes, the Prometheus Operator creates `prometheus-rancher-monitoring-prometheus`, a Prometheus deployment based on the CR configuration. diff --git a/docs/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md b/docs/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md index 592ee6d3f81..daecc9853ef 100644 --- a/docs/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md +++ b/docs/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md @@ -45,7 +45,7 @@ Use the label selector field `ruleSelector` in the Prometheus object to define t For examples, refer to the Prometheus documentation on [recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/) and [alerting rules.](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) -# Configuration +## Configuration ### Rule Group diff --git a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md index ce0a3e8e8d1..8f90137fa7b 100644 --- a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md +++ b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md @@ -6,7 +6,7 @@ Administrators have the permission to create RKE templates, and only administrat For more information on administrator permissions, refer to the [documentation on global permissions](../manage-role-based-access-control-rbac/global-permissions.md). -# Giving Users Permission to Create Templates +## Giving Users Permission to Create Templates Templates can only be created by users who have the global permission **Create RKE Templates**. diff --git a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-google-oauth.md b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-google-oauth.md index 47ddaf89f92..60526b7ffb7 100644 --- a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-google-oauth.md +++ b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-google-oauth.md @@ -8,7 +8,7 @@ Only admins of the G Suite domain have access to the Admin SDK. Therefore, only Within Rancher, only administrators or users with the **Manage Authentication** [global role](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) can configure authentication. -# Prerequisites +## Prerequisites - You must have a [G Suite admin account](https://admin.google.com) configured. - G Suite requires a [top private domain FQDN](https://github.com/google/guava/wiki/InternetDomainNameExplained#public-suffixes-and-private-domains) as an authorized domain. One way to get an FQDN is by creating an A-record in Route53 for your Rancher server. You do not need to update your Rancher Server URL setting with that record, because there could be clusters using that URL. @@ -17,7 +17,7 @@ Within Rancher, only administrators or users with the **Manage Authentication** After the Admin SDK API is enabled, your G Suite domain's API screen should look like this: ![Enable Admin APIs](/img/Google-Enable-APIs-Screen.png) -# Setting up G Suite for OAuth with Rancher +## Setting up G Suite for OAuth with Rancher Before you can set up Google OAuth in Rancher, you need to log in to your G Suite account and do the following: @@ -93,7 +93,7 @@ Using the Unique ID of the service account key, register it as an Oauth Client u **Result:** The service account is registered as an OAuth client in your G Suite account. -# Configuring Google OAuth in Rancher +## Configuring Google OAuth in Rancher 1. Sign into Rancher using a local user assigned the [administrator](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) role. This user is also called the local principal. 1. In the top left corner, click **☰ > Users & Authentication**. diff --git a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md index fc7227f38e9..970c3db8f89 100644 --- a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md +++ b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md @@ -28,7 +28,7 @@ After you complete [Configuring Microsoft AD FS for Rancher](configure-ms-adfs-f **Result:** Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins. -# Configuration +## Configuration | Field | Description | |---------------------------|-----------------| diff --git a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md index 5e5df96b3c7..3ccca4af2ed 100644 --- a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md +++ b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md @@ -16,7 +16,7 @@ For further details on configuring OpenLDAP, refer to the [official documentatio 3. Once the user has been found, they are 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. @@ -39,7 +39,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. diff --git a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/custom-branding.md b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/custom-branding.md index 20e1efa9941..d8d0d9209b0 100644 --- a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/custom-branding.md +++ b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/custom-branding.md @@ -160,7 +160,7 @@ Can be any link, even to links outside of the cluster. It is required to provide either the `toService` directive or the `toURL` directive. -# Link Examples +## Link Examples ### Example of Link with `toUrl` diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md index 140a26384a6..7a3dd0f6336 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md @@ -8,7 +8,7 @@ Rancher recommends configuring recurrent `etcd` snapshots for all production clu Snapshots of the etcd database are taken and saved either [locally onto the etcd nodes](#local-backup-target) or to a [S3 compatible target](#s3-backup-target). The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster. -# How Snapshots Work +## How Snapshots Work ### Snapshot Components @@ -64,7 +64,7 @@ On restore, the following process is used: 4. The other etcd nodes download the snapshot and validate the checksum so that they all use the same snapshot for the restore. 5. The cluster is restored and post-restore actions will be done in the cluster. -# Configuring Recurring Snapshots +## Configuring Recurring Snapshots Select how often you want recurring snapshots to be taken as well as how many snapshots to keep. The amount of time is measured in hours. With timestamped snapshots, the user has the ability to do a point-in-time recovery. @@ -81,7 +81,7 @@ In the **Advanced Cluster Options** section, there are several options available | Recurring etcd Snapshot Creation Period | Time in hours between recurring snapshots| 12 hours | | Recurring etcd Snapshot Retention Count | Number of snapshots to retain| 6 | -# One-Time Snapshots +## One-Time Snapshots In addition to recurring snapshots, you may want to take a "one-time" snapshot. For example, before upgrading the Kubernetes version of a cluster it's best to backup the state of the cluster to protect against upgrade failure. @@ -91,7 +91,7 @@ In addition to recurring snapshots, you may want to take a "one-time" snapshot. **Result:** Based on your [snapshot backup target](#snapshot-backup-targets), a one-time snapshot will be taken and saved in the selected backup target. -# Snapshot Backup Targets +## Snapshot Backup Targets Rancher supports two different backup targets: @@ -130,7 +130,7 @@ The `S3` backup target supports using IAM authentication to AWS API in addition To give an application access to S3, refer to the AWS documentation on [Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances.](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html) -# Viewing Available Snapshots +## Viewing Available Snapshots The list of all available snapshots for the cluster is available in the Rancher UI. @@ -138,7 +138,7 @@ The list of all available snapshots for the cluster is available in the Rancher 1. In the **Clusters** page, go to the cluster where you want to view the snapshots and click its name. 1. Click the **Snapshots** tab to view the list of saved snapshots. These snapshots include a timestamp of when they were created. -# Safe Timestamps +## Safe Timestamps Snapshot files are timestamped to simplify processing the files using external tools and scripts, but in some S3 compatible backends, these timestamps were unusable. @@ -146,6 +146,6 @@ The option `safe_timestamp` is added to support compatible file names. When this This option is not available directly in the UI, and is only available through the `Edit as Yaml` interface. -# Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0 +## Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0 If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must [edit the cluster](../../../pages-for-subheaders/cluster-configuration.md) and _save_ it, in order to enable the updated snapshot features. Even if you were already creating snapshots before v2.2.0, you must do this step as the older snapshots will not be available to use to [back up and restore etcd through the UI](restore-rancher-launched-kubernetes-clusters-from-backup.md). diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md index 57975cbcae1..f878d12f725 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md @@ -70,8 +70,8 @@ If the group of etcd nodes loses quorum, the Kubernetes cluster will report a fa 5. Run the revised command. -6. After the single nodes is up and running, Rancher recommends adding additional etcd nodes to your cluster. If you have a [custom cluster](../../../pages-for-subheaders/use-existing-nodes.md) and you want to reuse an old node, you are required to [clean up the nodes](../manage-clusters/clean-cluster-nodes.md) before attempting to add them back into a cluster. +6. After the single nodes is up and running, Rancher recommends adding additional etcd nodes to your cluster. If you have a [custom cluster](../../../pages-for-subheaders/use-existing-nodes.md) and you want to reuse an old node, you are required to [clean up the nodes](../manage-clusters/clean-cluster-nodes.md) before attempting to add them back into a cluster. -# Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0 +## Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0 If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must [edit the cluster](../../../pages-for-subheaders/cluster-configuration.md) and _save_ it, in order to enable the updated snapshot features. Even if you were already creating snapshots before v2.2.0, you must do this step as the older snapshots will not be available to use to [back up and restore etcd through the UI](restore-rancher-launched-kubernetes-clusters-from-backup.md). diff --git a/docs/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.md b/docs/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.md index b5f9e5127ed..a2dd54c6d14 100644 --- a/docs/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.md +++ b/docs/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.md @@ -12,7 +12,7 @@ For a complete walkthrough of developing charts, see the [Chart Template Develop -# Chart Types +## Chart Types Rancher supports two different types of charts: Helm charts and Rancher charts. @@ -26,7 +26,7 @@ Rancher charts are native helm charts with two files that enhance user experienc Rancher charts add simplified chart descriptions and configuration forms to make the application deployment easy. Rancher users do not need to read through the entire list of Helm variables to understand how to launch an application. -# Chart Directory Structure +## Chart Directory Structure You can provide Helm Charts in a standard, HTTP based Helm Repository. For more information see the [Chart Repository Guide](https://helm.sh/docs/topics/chart_repository) in the official Helm documentation. @@ -48,7 +48,7 @@ The following table demonstrates the directory structure for a Git repository. T │ │ │ ├── templates/ # Directory containing templates that, when combined with values.yml, generates Kubernetes YAML. ``` -# Additional Files for Rancher Charts +## Additional Files for Rancher Charts Before you create your own custom catalog, you should have a basic understanding about how a Rancher chart differs from a native Helm chart. Rancher charts differ slightly from Helm charts in their directory structures. Rancher charts include two files that Helm charts do not. diff --git a/docs/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md b/docs/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md index dcaf97eb8cb..e4e4075d929 100644 --- a/docs/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md +++ b/docs/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md @@ -149,7 +149,7 @@ Look over the load balancer details and click **Create** when you're satisfied. After AWS creates the NLB, click **Close**. -# 4. Add listener to NLB for TCP port 80 +## 4. Add listener to NLB for TCP port 80 1. Select your newly created NLB and select the **Listeners** tab. @@ -163,7 +163,7 @@ After AWS creates the NLB, click **Close**. 6. Click **Save** in the top right of the screen. -# Health Check Paths for NGINX Ingress and Traefik Ingresses +## Health Check Paths for NGINX Ingress and Traefik Ingresses K3s and RKE Kubernetes clusters handle health checks differently because they use different Ingresses by default. diff --git a/docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md b/docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md index cffa823f721..0828db18cff 100644 --- a/docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md +++ b/docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md @@ -16,12 +16,12 @@ In both single-node setups, Rancher can be installed with Helm on the Kubernetes ::: -# Prerequisites +## Prerequisites These instructions assume you have set up two nodes, a load balancer, a DNS record, and an external MySQL database as described in [this section.](../infrastructure-setup/ha-k3s-kubernetes-cluster.md) Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/) To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script. -# Installing Kubernetes +## Installing Kubernetes ### 1. Install Kubernetes and Set up the K3s Server diff --git a/docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md b/docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md index e4225251ce9..9f229e56c91 100644 --- a/docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md +++ b/docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md @@ -23,7 +23,7 @@ In both single-node setups, Rancher can be installed with Helm on the Kubernetes ::: -# Installing Kubernetes +## Installing Kubernetes ### Required CLI Tools @@ -85,7 +85,7 @@ ingress: RKE has many configuration options for customizing the install to suit your specific environment. Please see the [RKE Documentation](https://rancher.com/docs/rke/latest/en/config-options/) for the full list of options and capabilities. - + For tuning your etcd cluster for larger Rancher installations, see the [etcd settings guide](../../advanced-user-guides/tune-etcd-for-large-installs.md). For more information regarding Dockershim support, refer to [this page](../../../getting-started/installation-and-upgrade/installation-requirements/dockershim.md) diff --git a/docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md b/docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md index d2f6d294015..41ef275e5ba 100644 --- a/docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md +++ b/docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md @@ -6,14 +6,15 @@ _Tested on v2.5.6_ This section describes how to install a Kubernetes cluster according to the [best practices for the Rancher server environment.](../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#environment-for-kubernetes-installations) -# Prerequisites +## Prerequisites These instructions assume you have set up three nodes, a load balancer, and a DNS record, as described in [this section.](../infrastructure-setup/ha-rke2-kubernetes-cluster.md) Note that in order for RKE2 to work correctly with the load balancer, you need to set up two listeners: one for the supervisor on port 9345, and one for the Kubernetes API on port 6443. Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/) To specify the RKE2 version, use the INSTALL_RKE2_VERSION environment variable when running the RKE2 installation script. -# Installing Kubernetes + +## Installing Kubernetes ### 1. Install Kubernetes and Set up the RKE2 Server diff --git a/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure.md b/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure.md index cdbf3c2c204..f710cfebd78 100644 --- a/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure.md +++ b/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure.md @@ -15,7 +15,7 @@ The following account types are not supported for Azure Subscriptions: - Single tenant accounts (i.e. accounts with no subscriptions). - Multi-subscription accounts. -# Prerequisites for RKE and RKE2 +## Prerequisites for RKE and RKE2 To set up the Azure cloud provider for both RKE and RKE2, the following credentials need to be configured: @@ -70,7 +70,7 @@ You should already assign custom hosts to this Network Security Group during pro Only hosts expected to be load balancer back ends need to be in this group. -# RKE2 Cluster Set-up in Rancher +## RKE2 Cluster Set-up in Rancher 1. Choose "Azure" from the Cloud Provider drop-down in the Cluster Configuration section. diff --git a/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md b/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md index 4bf0ec1f8ea..29566047b41 100644 --- a/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md +++ b/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md @@ -6,7 +6,7 @@ Kubernetes is moving away from maintaining cloud providers in-tree. vSphere has This page covers how to install the Cloud Provider Interface (CPI) and Cloud Storage Interface (CSI) plugins after bringing up a cluster. -# Prerequisites +## Prerequisites The vSphere versions supported: @@ -17,7 +17,7 @@ The Kubernetes version must be 1.19 or higher. Using the vSphere out-of-tree cloud provider requires Linux nodes and is not supported on Windows. -# Installation +## Installation The Cloud Provider Interface (CPI) should be installed first before installing the Cloud Storage Interface (CSI). @@ -55,7 +55,7 @@ The Cloud Provider Interface (CPI) should be installed first before installing t 1. Click **Install**. -# Using the CSI driver for provisioning volumes +## Using the CSI driver for provisioning volumes The CSI chart by default creates a storageClass. diff --git a/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-from-in-tree-to-out-of-tree.md b/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-from-in-tree-to-out-of-tree.md index 46e368a3092..45b10d3a8ef 100644 --- a/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-from-in-tree-to-out-of-tree.md +++ b/docs/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-from-in-tree-to-out-of-tree.md @@ -29,12 +29,12 @@ Upstream bug: https://github.com/kubernetes-sigs/vsphere-csi-driver/issues/628 Rancher issue tracking this bug: https://github.com/rancher/rancher/issues/31105 -# Prerequisites +## Prerequisites - vSphere CSI Migration requires vSphere 7.0u1. In order to be able to manage existing in-tree vSphere volumes, upgrade vSphere to 7.0u1. - The Kubernetes version must be 1.19 or higher. -# Migration +## Migration ### 1. Install the CPI plugin diff --git a/docs/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md b/docs/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md index ba1068bdb4b..bb68ea8916d 100644 --- a/docs/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md +++ b/docs/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md @@ -13,7 +13,7 @@ Deployments use the Kubernetes registry secret to authenticate with a private Do Currently, deployments pull the private registry credentials automatically only if the workload is created in the Rancher UI and not when it is created via kubectl. -# Creating a Registry in Namespaces +## Creating a Registry in Namespaces :::note Prerequisite: @@ -44,7 +44,7 @@ You must have a [private registry](https://docs.docker.com/registry/deploying/) - You can view the secret in the Rancher UI by clicking either **Storage > Secrets** or **More Resources > Core > Secrets**. - Any workload that you create in the Rancher UI will have the credentials to access the registry if the workload is within the registry's scope. -# Creating a Registry in Projects +## Creating a Registry in Projects :::note Prerequisites: @@ -87,7 +87,7 @@ Project-scoped registries on the local cluster are only visible when a single pr ::: -# Using a Private Registry +## Using a Private Registry You can deploy a workload with an image from a private registry through the Rancher UI, or with `kubectl`. diff --git a/docs/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.md b/docs/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.md index d53c2b64a14..d69d7219875 100644 --- a/docs/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.md +++ b/docs/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.md @@ -7,7 +7,7 @@ description: Ingress configuration For Kubernetes v1.21 and up, the NGINX Ingress controller no longer runs in hostNetwork but uses hostPorts for port 80 and port 443. This was done so the admission webhook can be configured to be accessed using ClusterIP so it can only be reached inside the cluster. -# Ingress Rule Configuration +## Ingress Rule Configuration - [Specify a hostname to use](#specify-a-hostname-to-use) - [Use as the default backend](#use-as-the-default-backend) diff --git a/docs/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md b/docs/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md index d7ca8f8f76e..5422eef7807 100644 --- a/docs/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md +++ b/docs/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md @@ -14,7 +14,7 @@ When configuring a workload, you'll be able to choose which secrets to include. Mounted secrets will be updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/configuration/secret/#mounted-secrets-are-updated-automatically) -# Creating Secrets in Namespaces +## Creating Secrets in Namespaces 1. In the upper left corner, click **☰ > Cluster Management**. 1. Go to the cluster where you want to add a secret and click **Explore**. @@ -47,7 +47,7 @@ Mounted secrets will be updated automatically unless they are mounted as subpath Mounted secrets will be updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/configuration/secret/#mounted-secrets-are-updated-automatically) -# Creating Secrets in Projects +## Creating Secrets in Projects Before v2.6, secrets were required to be in a project scope. Projects are no longer required, and you may use the namespace scope instead. As a result, the Rancher UI was updated to reflect this new functionality. However, you may still create project-scoped secrets if desired. Note that you have to first enable the `legacy` feature flag and look at a single project to do so. Use the following steps to set up your project-level secret: @@ -69,7 +69,7 @@ Project-scoped secrets on the local cluster are only visible when a single proje ::: -# What's Next? +## What's Next? Now that you have a secret added to a namespace, you can add it to a workload that you deploy. diff --git a/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md b/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md index c0e25e9f62c..86451ce637c 100644 --- a/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md +++ b/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md @@ -93,7 +93,8 @@ You can access your cluster after its state is updated to **Active**. - `Default`, containing the `default` namespace - `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces -# 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: diff --git a/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md b/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md index 55526c4f22c..e49b9a43919 100644 --- a/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md +++ b/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md @@ -21,7 +21,7 @@ Then you will create an EC2 cluster in Rancher, and when configuring the new clu - [Example IAM Policy to allow encrypted EBS volumes](#example-iam-policy-to-allow-encrypted-ebs-volumes) - **IAM Policy added as Permission** to the user. See [Amazon Documentation: Adding Permissions to a User (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) how to attach it to an user. -# Creating an EC2 Cluster +## Creating an EC2 Cluster The steps to create a cluster differ based on your Rancher version. @@ -133,7 +133,7 @@ After creating your cluster, you can access it through the Rancher UI. As a best - **Access your cluster with the kubectl CLI:** Follow [these steps](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-on-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. - **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. -# IAM Policies +## IAM Policies ### Example IAM Policy diff --git a/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md b/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md index afc9aff2f0a..61bb8cd1664 100644 --- a/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md +++ b/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md @@ -29,7 +29,7 @@ For more information on configuring Azure node templates, refer to the [Azure no - [Preparation in Azure](#preparation-in-azure) - [Creating an Azure Cluster](#creating-an-azure-cluster) -# Preparation in Azure +## Preparation in Azure Before creating a node template in Rancher using a cloud infrastructure such as Azure, we must configure Rancher to allow the manipulation of resources in an Azure subscription. @@ -46,7 +46,7 @@ az ad sp create-for-rbac \ The creation of this service principal returns three pieces of identification information, *The application ID, also called the client ID*, and *The client secret*. This information will be used when you create a node template for Azure. -# Creating an Azure Cluster +## Creating an Azure Cluster diff --git a/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.md b/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.md index f0c27ae45c4..4e07ed2785a 100644 --- a/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.md +++ b/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.md @@ -17,7 +17,7 @@ For details on configuring RKE Kubernetes clusters in Rancher, refer to the [clu - [Preparation in Nutanix AOS](#preparation-in-nutanix-aos) - [Creating a Nutanix AOS Cluster](#creating-a-nutanix-aos-cluster) -# Preparation in Nutanix AOS +## Preparation in Nutanix AOS The following sections describe the requirements for setting up Nutanix AOS so that Rancher can provision VMs and clusters. @@ -26,6 +26,7 @@ The following sections describe the requirements for setting up Nutanix AOS so t The node templates are documented and tested with Nutanix AOS version 5.20.2 and 6.0.1. ::: + ### Create Credentials in Nutanix AOS Before proceeding to create a cluster, you must ensure that you have a [Nutanix Prism Central user account](https://portal.nutanix.com/page/documents/details?targetId=Nutanix-Security-Guide-v6_0:wc-user-create-wc-t.html) with admin permissions. When you set up a node template, the template will need to use these credentials. @@ -43,7 +44,7 @@ See [Node Networking Requirements](../../../kubernetes-clusters-in-rancher-setup Setting up [VM-VM Anti-Affinity Policies](https://portal.nutanix.com/page/documents/details?targetId=AHV-Admin-Guide-v6_1:ahv-vm-anti-affinity-t.html) is recommended. These rules allow VMs assigned the etcd and control-plane roles to operate on separate AHV hosts when they are assigned to different node pools. This practice ensures that the failure of a single physical machine does not affect the availability of those planes. -# Creating a Nutanix AOS Cluster +## Creating a Nutanix AOS Cluster 1. [Create a node template ](#1-create-a-node-template) 2. [Create a cluster with node pools using the node template](#2-create-a-cluster-with-node-pools-using-the-node-template) @@ -82,8 +83,7 @@ You can access your cluster after its state is updated to **Active**. - `Default`, containing the `default` namespace - `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces - -# 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: diff --git a/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md b/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md index 5ce89c381db..4d9f1c06fbc 100644 --- a/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md +++ b/docs/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md @@ -16,7 +16,7 @@ For details on configuring RKE Kubernetes clusters in Rancher, refer to the [clu - [Preparation in vSphere](#preparation-in-vsphere) - [Creating a vSphere Cluster](#creating-a-vsphere-cluster) -# Preparation in vSphere +## Preparation in vSphere This section describes the requirements for setting up vSphere so that Rancher can provision VMs and clusters. diff --git a/docs/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md b/docs/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md index 9b1ca75b6c0..1dc500cfef9 100644 --- a/docs/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md +++ b/docs/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md @@ -513,7 +513,7 @@ Cluster-autoscaler deployment can also be set up using [manual configuration](ht ::: -# Testing +## Testing At this point, we should have a cluster-scaler up and running in our Rancher custom cluster. Cluster-scale should manage `K8sWorkerAsg` ASG to scale up and down between 2 and 10 nodes, when one of the following conditions is true: diff --git a/docs/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.md b/docs/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.md index 6c500a9758e..e6a3f8cf961 100644 --- a/docs/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.md +++ b/docs/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.md @@ -14,7 +14,7 @@ For public downstream clusters, it is sufficient to [set the required environmen For private nodes or private clusters, the environment variables need to be set on the nodes themselves. Then the environment variables are configured from the Rancher UI, typically when provisioning a custom cluster or when registering the private cluster. For an example of how to set the environment variables on Ubuntu node in a K3s Kubernetes cluster, see [this section.](#setting-environment-variables-on-private-nodes) -# Required Environment Variables +## Required Environment Variables When adding Fleet agent environment variables for the proxy, replace with your private proxy IP. diff --git a/docs/pages-for-subheaders/air-gapped-helm-cli-install.md b/docs/pages-for-subheaders/air-gapped-helm-cli-install.md index 5c4a5aec1e3..058b697d93d 100644 --- a/docs/pages-for-subheaders/air-gapped-helm-cli-install.md +++ b/docs/pages-for-subheaders/air-gapped-helm-cli-install.md @@ -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) diff --git a/docs/pages-for-subheaders/aws-cloud-marketplace.md b/docs/pages-for-subheaders/aws-cloud-marketplace.md index 5be068ab186..0b4c8185342 100644 --- a/docs/pages-for-subheaders/aws-cloud-marketplace.md +++ b/docs/pages-for-subheaders/aws-cloud-marketplace.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?** diff --git a/docs/pages-for-subheaders/configure-shibboleth-saml.md b/docs/pages-for-subheaders/configure-shibboleth-saml.md index 9ea4d2ae640..1dd59a2a807 100644 --- a/docs/pages-for-subheaders/configure-shibboleth-saml.md +++ b/docs/pages-for-subheaders/configure-shibboleth-saml.md @@ -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. diff --git a/docs/pages-for-subheaders/enable-experimental-features.md b/docs/pages-for-subheaders/enable-experimental-features.md index d6bbff9633c..f81d240f0fc 100644 --- a/docs/pages-for-subheaders/enable-experimental-features.md +++ b/docs/pages-for-subheaders/enable-experimental-features.md @@ -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 `/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. diff --git a/docs/pages-for-subheaders/gke-cluster-configuration.md b/docs/pages-for-subheaders/gke-cluster-configuration.md index a611ab70462..f12a3a4c0bc 100644 --- a/docs/pages-for-subheaders/gke-cluster-configuration.md +++ b/docs/pages-for-subheaders/gke-cluster-configuration.md @@ -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. diff --git a/docs/pages-for-subheaders/install-cluster-autoscaler.md b/docs/pages-for-subheaders/install-cluster-autoscaler.md index 7ad4de0d618..74034865131 100644 --- a/docs/pages-for-subheaders/install-cluster-autoscaler.md +++ b/docs/pages-for-subheaders/install-cluster-autoscaler.md @@ -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) diff --git a/docs/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md b/docs/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md index e9f0f97e373..07d554b59d8 100644 --- a/docs/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md +++ b/docs/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md @@ -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. diff --git a/docs/pages-for-subheaders/installation-and-upgrade.md b/docs/pages-for-subheaders/installation-and-upgrade.md index 5718232bd95..67277ae8d73 100644 --- a/docs/pages-for-subheaders/installation-and-upgrade.md +++ b/docs/pages-for-subheaders/installation-and-upgrade.md @@ -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. diff --git a/docs/pages-for-subheaders/installation-requirements.md b/docs/pages-for-subheaders/installation-requirements.md index 1092d203c62..da9db12a19f 100644 --- a/docs/pages-for-subheaders/installation-requirements.md +++ b/docs/pages-for-subheaders/installation-requirements.md @@ -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). diff --git a/docs/pages-for-subheaders/istio-setup-guide.md b/docs/pages-for-subheaders/istio-setup-guide.md index 705e8b673c9..2c6ba0c4118 100644 --- a/docs/pages-for-subheaders/istio-setup-guide.md +++ b/docs/pages-for-subheaders/istio-setup-guide.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: diff --git a/docs/pages-for-subheaders/kubernetes-components.md b/docs/pages-for-subheaders/kubernetes-components.md index b316a70dbde..5e482f2a1e8 100644 --- a/docs/pages-for-subheaders/kubernetes-components.md +++ b/docs/pages-for-subheaders/kubernetes-components.md @@ -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)
Lines show the traffic flow between components. Colors are used purely for visual aid \ No newline at end of file diff --git a/docs/pages-for-subheaders/launch-kubernetes-with-rancher.md b/docs/pages-for-subheaders/launch-kubernetes-with-rancher.md index 2ef362e38c3..7050181372e 100644 --- a/docs/pages-for-subheaders/launch-kubernetes-with-rancher.md +++ b/docs/pages-for-subheaders/launch-kubernetes-with-rancher.md @@ -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) \ No newline at end of file diff --git a/docs/pages-for-subheaders/monitoring-and-alerting.md b/docs/pages-for-subheaders/monitoring-and-alerting.md index 5153d5123ff..fc5684035ca 100644 --- a/docs/pages-for-subheaders/monitoring-and-alerting.md +++ b/docs/pages-for-subheaders/monitoring-and-alerting.md @@ -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) @@ -62,7 +62,7 @@ For information on configuring access to monitoring, see [this page.](../integra - [Debugging high memory usage](../how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md) - [Migrating from Monitoring V1 to V2](../how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5+-monitoring.md) -# Configuration +## Configuration ### Configuring Monitoring Resources in Rancher @@ -79,7 +79,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. @@ -88,8 +88,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. diff --git a/docs/pages-for-subheaders/monitoring-v2-configuration-guides.md b/docs/pages-for-subheaders/monitoring-v2-configuration-guides.md index 457bd2dc293..443e84dfd96 100644 --- a/docs/pages-for-subheaders/monitoring-v2-configuration-guides.md +++ b/docs/pages-for-subheaders/monitoring-v2-configuration-guides.md @@ -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 V2 has significantly higher CPU usage (up to 70%) ::: -# 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. diff --git a/docs/pages-for-subheaders/nutanix.md b/docs/pages-for-subheaders/nutanix.md index c4424818752..23a9f5590da 100644 --- a/docs/pages-for-subheaders/nutanix.md +++ b/docs/pages-for-subheaders/nutanix.md @@ -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. \ No newline at end of file diff --git a/docs/pages-for-subheaders/rancher-behind-an-http-proxy.md b/docs/pages-for-subheaders/rancher-behind-an-http-proxy.md index ef0d4acbe8e..59a7eec2dba 100644 --- a/docs/pages-for-subheaders/rancher-behind-an-http-proxy.md +++ b/docs/pages-for-subheaders/rancher-behind-an-http-proxy.md @@ -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) diff --git a/docs/pages-for-subheaders/rancher-on-a-single-node-with-docker.md b/docs/pages-for-subheaders/rancher-on-a-single-node-with-docker.md index 4dd65127b1d..83782f88f91 100644 --- a/docs/pages-for-subheaders/rancher-on-a-single-node-with-docker.md +++ b/docs/pages-for-subheaders/rancher-on-a-single-node-with-docker.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. diff --git a/docs/pages-for-subheaders/use-existing-nodes.md b/docs/pages-for-subheaders/use-existing-nodes.md index f4e0a01f7ae..dc38e3b0ecf 100644 --- a/docs/pages-for-subheaders/use-existing-nodes.md +++ b/docs/pages-for-subheaders/use-existing-nodes.md @@ -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: diff --git a/docs/reference-guides/backup-restore-configuration/examples.md b/docs/reference-guides/backup-restore-configuration/examples.md index 1c449a8dd9d..99bcfc2190f 100644 --- a/docs/reference-guides/backup-restore-configuration/examples.md +++ b/docs/reference-guides/backup-restore-configuration/examples.md @@ -242,7 +242,7 @@ spec: encryptionConfigSecretName: test-encryptionconfig ``` -# Example Credential Secret for Storing Backups in S3 +## Example Credential Secret for Storing Backups in S3 ```yaml apiVersion: v1 @@ -255,7 +255,7 @@ data: secretKey: ``` -# Example EncryptionConfiguration +## Example EncryptionConfiguration The snippet below demonstrates two different types of secrets and their relevance with respect to Backup and Restore of custom resources. diff --git a/docs/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md b/docs/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md index 6d027542c4c..a95a03b3d8d 100644 --- a/docs/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md +++ b/docs/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md @@ -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 diff --git a/docs/reference-guides/cli-with-rancher/kubectl-utility.md b/docs/reference-guides/cli-with-rancher/kubectl-utility.md index 5792215c085..0f4d4ded34c 100644 --- a/docs/reference-guides/cli-with-rancher/kubectl-utility.md +++ b/docs/reference-guides/cli-with-rancher/kubectl-utility.md @@ -2,7 +2,7 @@ title: kubectl Utility --- -# kubectl +## kubectl Interact with Rancher using kubectl. diff --git a/docs/reference-guides/pipelines/pipeline-configuration.md b/docs/reference-guides/pipelines/pipeline-configuration.md index 01625cd48d2..f643400c2a2 100644 --- a/docs/reference-guides/pipelines/pipeline-configuration.md +++ b/docs/reference-guides/pipelines/pipeline-configuration.md @@ -61,7 +61,8 @@ stages: pushRemote: true registry: reg.example.com ``` -# Step Type: Run Script + +## Step Type: Run Script The **Run Script** step executes arbitrary commands in the workspace inside a specified container. You can use it to build, test and do more, given whatever utilities the base image provides. For your convenience, you can use variables to refer to metadata of a pipeline execution. Please refer to the [pipeline variable substitution reference](#pipeline-variable-substitution-reference) for the list of available variables. @@ -623,7 +624,7 @@ If you want to use a version control provider with a certificate from a custom/i **Result:** Pipelines can be used and new pods will be able to work with the self-signed-certificate. -# Persistent Data for Pipeline Components +## Persistent Data for Pipeline Components The internal Docker registry and the Minio workloads use ephemeral volumes by default. This default storage works out-of-the-box and makes testing easy, but you lose the build images and build logs if the node running the Docker Registry or Minio fails. In most cases this is fine. If you want build images and logs to survive node failures, you can configure the Docker Registry and Minio to use persistent volumes. diff --git a/docs/reference-guides/rancher-manager-architecture/architecture-recommendations.md b/docs/reference-guides/rancher-manager-architecture/architecture-recommendations.md index f8bc2f030cf..9e3a6277c22 100644 --- a/docs/reference-guides/rancher-manager-architecture/architecture-recommendations.md +++ b/docs/reference-guides/rancher-manager-architecture/architecture-recommendations.md @@ -4,7 +4,7 @@ title: Architecture Recommendations 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 (ACE) +## Architecture for an Authorized Cluster Endpoint (ACE) If you are using an [authorized cluster endpoint (ACE),](../../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. diff --git a/docs/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md b/docs/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md index 6eabc6401a2..c79e1b8c27e 100644 --- a/docs/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md +++ b/docs/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md @@ -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/new-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/new-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: diff --git a/docs/reference-guides/system-tools.md b/docs/reference-guides/system-tools.md index 01c3b9a6c05..d9480976757 100644 --- a/docs/reference-guides/system-tools.md +++ b/docs/reference-guides/system-tools.md @@ -8,11 +8,11 @@ System Tools has been deprecated since June 2022. ::: -# Logs +## Logs Please use [logs-collector](https://github.com/rancherlabs/support-tools/tree/master/collection/rancher/v2.x/logs-collector) to collect logs from your cluster. -# Stats +## Stats If you want to replicate the stats command, you can run the following command on your cluster nodes: @@ -26,6 +26,6 @@ This command below requires the package `sysstat` on the cluster node. /usr/bin/sar -u -r -F 1 1 ``` -# Remove +## Remove Please use the [Rancher Cleanup](https://github.com/rancher/rancher-cleanup) tool. diff --git a/docs/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md b/docs/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md index 20640bcdedc..2d352dd7bc5 100644 --- a/docs/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md +++ b/docs/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md @@ -4,7 +4,7 @@ title: Troubleshooting Controlplane Nodes This section applies to nodes with the `controlplane` role. -# Check if the Controlplane Containers are Running +## Check if the Controlplane Containers are Running There are three specific containers launched on nodes with the `controlplane` role: @@ -26,7 +26,7 @@ f3d287ca4549 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." bdf3898b8063 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." 3 hours ago Up 3 hours kube-controller-manager ``` -# Controlplane Container Logging +## Controlplane Container Logging :::note @@ -42,7 +42,7 @@ docker logs kube-controller-manager docker logs kube-scheduler ``` -# RKE2 Server Logging +## RKE2 Server Logging If Rancher provisions an RKE2 cluster that can't communicate with Rancher, you can run this command on a server node in the downstream cluster to get the RKE2 server logs: diff --git a/docs/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md b/docs/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md index d7cde4f794e..08d71c4c028 100644 --- a/docs/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md +++ b/docs/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md @@ -4,7 +4,7 @@ title: Troubleshooting nginx-proxy The `nginx-proxy` container is deployed on every node that does not have the `controlplane` role. It provides access to all the nodes with the `controlplane` role by dynamically generating the NGINX configuration based on available nodes with the `controlplane` role. -# Check if the Container is Running +## Check if the Container is Running The container is called `nginx-proxy` and should have status `Up`. The duration shown after `Up` is the time the container has been running. @@ -20,7 +20,7 @@ CONTAINER ID IMAGE COMMAND CREATED c3e933687c0e rancher/rke-tools:v0.1.15 "nginx-proxy CP_HO..." 3 hours ago Up 3 hours nginx-proxy ``` -# Check Generated NGINX Configuration +## Check Generated NGINX Configuration The generated configuration should include the IP addresses of the nodes with the `controlplane` role. The configuration can be checked using the following command: @@ -59,7 +59,7 @@ stream { } ``` -# nginx-proxy Container Logging +## nginx-proxy Container Logging The logging of the containers can contain information on what the problem could be. diff --git a/docs/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md b/docs/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md index 6d3a8bd7fcd..66c36f68bb7 100644 --- a/docs/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md +++ b/docs/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md @@ -4,7 +4,7 @@ title: Troubleshooting Worker Nodes and Generic Components This section applies to every node as it includes components that run on nodes with any role. -# Check if the Containers are Running +## Check if the Containers are Running There are two specific containers launched on nodes with the `worker` role: @@ -24,7 +24,7 @@ CONTAINER ID IMAGE COMMAND a30717ecfb55 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." 3 hours ago Up 3 hours kubelet ``` -# Container Logging +## Container Logging The logging of the containers can contain information on what the problem could be. From bb76e99d205b5771b6a29849d73b3dbf36cd8f43 Mon Sep 17 00:00:00 2001 From: Billy Tat Date: Fri, 28 Oct 2022 17:08:01 -0700 Subject: [PATCH 2/3] Convert h1 to h2 (2.5) --- .../rke-clusters/options/options.md | 2 +- .../version-2.5/contribute-to-rancher.md | 8 ++-- .../istio/cpu-and-memory-allocations.md | 2 +- .../outputs-and-clusteroutputs.md | 4 +- .../open-ports-with-firewalld.md | 4 +- .../istio-traffic-management-features.md | 2 +- .../air-gapped-upgrades.md | 10 ++--- .../rancher-on-aks.md | 18 ++++----- .../rancher-on-amazon-eks.md | 4 +- .../rancher-on-gke.md | 22 +++++------ .../rollbacks.md | 6 +-- .../upgrades.md | 14 +++---- .../port-requirements.md | 6 +-- .../install-rancher-ha.md | 20 +++++----- .../publish-images.md | 4 +- .../upgrade-docker-installed-rancher.md | 22 +++++------ .../resources/add-tls-secrets.md | 4 +- .../resources/local-system-charts.md | 3 +- .../resources/update-rancher-certificate.md | 37 +++++++++---------- .../resources/upgrade-cert-manager.md | 3 +- .../upgrade-and-roll-back-kubernetes.md | 2 +- .../getting-started/introduction/overview.md | 10 ++--- .../configure-google-oauth.md | 7 ++-- .../configure-rancher-for-ms-adfs.md | 16 ++------ .../creator-permissions.md | 2 +- .../global-permissions.md | 7 ++-- .../enable-istio-in-cluster.md | 2 +- .../generate-and-view-traffic.md | 2 +- .../istio-setup-guide/set-up-istio-gateway.md | 6 +-- .../use-aws-ec2-auto-scaling-groups.md | 2 +- .../manage-clusters/nodes-and-node-pools.md | 18 ++++----- .../create-persistent-grafana-dashboard.md | 4 +- .../enable-monitoring.md | 6 +-- .../advanced-configuration/prometheus.md | 2 +- .../advanced-configuration/prometheusrules.md | 6 +-- ...up-rancher-launched-kubernetes-clusters.md | 14 +++---- ...aunched-kubernetes-clusters-from-backup.md | 2 +- .../amazon-elb-load-balancer.md | 14 +++---- .../k3s-for-rancher.md | 5 ++- .../rke1-for-rancher.md | 2 +- .../rke2-for-rancher.md | 5 ++- .../roles-for-nodes-in-kubernetes.md | 8 ++-- .../vsphere/configure-out-of-tree-vsphere.md | 6 +-- .../migrate-from-in-tree-to-out-of-tree.md | 4 +- .../create-an-amazon-ec2-cluster.md | 7 ++-- .../create-an-azure-cluster.md | 4 +- .../kubernetes-and-docker-registries.md | 4 +- .../add-ingresses.md | 2 +- .../kubernetes-resources-setup/secrets.md | 4 +- .../air-gapped-helm-cli-install.md | 4 +- .../configure-shibboleth-saml.md | 7 ++-- .../enable-experimental-features.md | 7 ++-- .../gke-cluster-configuration.md | 16 ++++---- .../install-cluster-autoscaler.md | 2 +- .../install-rancher-on-linux.md | 17 +++++---- ...install-upgrade-on-a-kubernetes-cluster.md | 4 +- .../installation-and-upgrade.md | 11 +++--- .../installation-requirements.md | 14 +++---- .../pages-for-subheaders/istio-setup-guide.md | 5 +-- .../kubernetes-components.md | 2 +- .../monitoring-and-alerting.md | 16 ++++---- .../monitoring-v2-configuration-guides.md | 7 ++-- .../pages-for-subheaders/pipelines.md | 15 ++++---- .../rancher-behind-an-http-proxy.md | 2 +- .../rancher-on-a-single-node-with-docker.md | 6 +-- .../use-existing-nodes.md | 4 +- .../use-new-nodes-in-an-infra-provider.md | 9 ++--- .../use-windows-clusters.md | 14 +++---- .../vsphere-cloud-provider.md | 4 +- .../pages-for-subheaders/vsphere.md | 2 +- .../backup-restore-configuration/examples.md | 4 +- .../rancher-managed-clusters-in-vsphere.md | 8 ++-- .../cli-with-rancher/kubectl-utility.md | 10 ++--- .../node-template-configuration/vsphere.md | 2 +- .../rancherd-configuration-reference.md | 13 +++---- .../rke1-cluster-configuration.md | 6 +-- .../openldap-config-reference.md | 4 +- .../helm-chart-options.md | 2 +- .../installation-references/tls-settings.md | 4 +- .../reference-guides/rancher-cluster-tools.md | 13 ++++--- .../architecture-recommendations.md | 12 +++--- ...unicating-with-downstream-user-clusters.md | 16 ++++---- .../reference-guides/system-tools.md | 8 ++-- .../troubleshooting-controlplane-nodes.md | 4 +- .../troubleshooting-nginx-proxy.md | 6 +-- ...ing-worker-nodes-and-generic-components.md | 4 +- .../kubernetes-resources.md | 3 +- 87 files changed, 319 insertions(+), 336 deletions(-) diff --git a/versioned_docs/version-2.5/cluster-provisioning/rke-clusters/options/options.md b/versioned_docs/version-2.5/cluster-provisioning/rke-clusters/options/options.md index df00c9d57fe..926cfec3cfc 100644 --- a/versioned_docs/version-2.5/cluster-provisioning/rke-clusters/options/options.md +++ b/versioned_docs/version-2.5/cluster-provisioning/rke-clusters/options/options.md @@ -256,7 +256,7 @@ The table below indicates what DNS provider is deployed by default. See [RKE doc | v2.2.5 and higher | v1.13.x and lower | kube-dns | | v2.2.4 and lower | any | kube-dns | -# Rancher specific parameters +## Rancher specific parameters Besides the RKE config file options, there are also Rancher specific settings that can be configured in the Config File (YAML): diff --git a/versioned_docs/version-2.5/contribute-to-rancher.md b/versioned_docs/version-2.5/contribute-to-rancher.md index ef2b2d48497..84b51360dba 100644 --- a/versioned_docs/version-2.5/contribute-to-rancher.md +++ b/versioned_docs/version-2.5/contribute-to-rancher.md @@ -14,7 +14,7 @@ For more detailed information on how to contribute to the development of Rancher On the Rancher Users Slack, the channel for developers is **#developer**. -# Repositories +## Repositories All of repositories are located within our main GitHub organization. There are many repositories used for Rancher, but we'll provide descriptions of some of the main ones used in Rancher. @@ -38,13 +38,13 @@ To see all libraries/projects used in Rancher, see the [`go.mod` file](https://g ![Rancher diagram](/img/ranchercomponentsdiagram.svg)
Rancher components used for provisioning/managing Kubernetes clusters. -# Building +## Building Every repository should have a Makefile and can be built using the `make` command. The `make` targets are based on the scripts in the `/scripts` directory in the repository, and each target will use [Dapper](https://github.com/rancher/dapper) to run the target in an isolated environment. The `Dockerfile.dapper` will be used for this process, and includes all the necessary build tooling needed. The default target is `ci`, and will run `./scripts/validate`, `./scripts/build`, `./scripts/test` and `./scripts/package`. The resulting binaries of the build will be in `./build/bin` and are usually also packaged in a Docker image. -# Bugs, Issues or Questions +## Bugs, Issues or Questions If you find any bugs or are having any trouble, please search the [reported issue](https://github.com/rancher/rancher/issues) as someone may have experienced the same issue or we are actively working on a solution. @@ -110,7 +110,7 @@ Please follow this checklist when filing an issue which will helps us investigat - `/var/log/docker.log` - **Metrics:** If you are experiencing performance issues, please provide as much of data (files or screenshots) of metrics which can help determining what is going on. If you have an issue related to a machine, it helps to supply output of `top`, `free -m`, `df` which shows processes/memory/disk usage. -# Docs +## Docs If you have any updates to our documentation, please make any pull request to our docs repo. diff --git a/versioned_docs/version-2.5/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.md b/versioned_docs/version-2.5/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.md index b985fdd8c44..90bba7a8d76 100644 --- a/versioned_docs/version-2.5/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.md +++ b/versioned_docs/version-2.5/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.md @@ -42,7 +42,7 @@ Totals: | 1710m | 3304Mi | >8800m | >6048Mi | - -# Configuring Resource Allocations +## Configuring Resource Allocations You can individually configure the resource allocation for each type of Istio component. This section includes the default resource allocations for each component. diff --git a/versioned_docs/version-2.5/explanations/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.md b/versioned_docs/version-2.5/explanations/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.md index 88ccb108608..6d0a4cbbfc7 100644 --- a/versioned_docs/version-2.5/explanations/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.md +++ b/versioned_docs/version-2.5/explanations/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.md @@ -22,7 +22,7 @@ The `Outputs` and `ClusterOutputs` can now be configured by filling out forms in -# Outputs +## Outputs The `Output` resource defines where your `Flows` can send the log messages. `Outputs` are the final stage for a logging `Flow`. @@ -72,7 +72,7 @@ For the details of the `ClusterOutput` custom resource, see [ClusterOutput.](htt -# Outputs +## Outputs The `Output` resource defines where your `Flows` can send the log messages. `Outputs` are the final stage for a logging `Flow`. diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.md index f2b9c80842c..a3ffcb2a1a5 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.md @@ -33,7 +33,7 @@ sudo iptables --list This section describes how to use `firewalld` to apply the [firewall port rules](../../installation-requirements/port-requirements.md) for nodes in a high-availability Rancher server cluster. -# Prerequisite +## Prerequisite Install v7.x or later ofv`firewalld`: @@ -43,7 +43,7 @@ systemctl start firewalld systemctl enable firewalld ``` -# Applying Firewall Port Rules +## Applying Firewall Port Rules In the Rancher high-availability installation instructions, the Rancher server is set up on three nodes that have all three Kubernetes roles: etcd, controlplane, and worker. If your Rancher server nodes have all three roles, run the following commands on each node: diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.md index 8f3b09de600..bb4d42a6d50 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.md @@ -13,7 +13,7 @@ Environment Variable Key | Default Value | Status | Available as of `istio-virtual-service-ui` |`false` | Experimental | v2.3.0 `istio-virtual-service-ui` | `true` | GA | v2.3.2 -# About this Feature +## About this Feature A central advantage of Istio's traffic management features is that they allow dynamic request routing, which is useful for canary deployments, blue/green deployments, or A/B testing. diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md index 84bfcb55b70..101b046278f 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; > These instructions assume you have already followed the instructions for a Kubernetes upgrade on [this page,](upgrades.md) including the prerequisites, up until step 3. Upgrade Rancher. -### Rancher Helm Template Options +## Rancher Helm Template Options Render the Rancher template using the same chosen options that were used when installing Rancher. 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. @@ -20,7 +20,6 @@ Placeholder | Description `` | The DNS name for your private registry. `` | Cert-manager version running on k8s cluster. - ### Option A: Default Self-signed Certificate @@ -112,8 +111,7 @@ helm template rancher ./rancher-.tgz --output-dir . \ - -### Apply the Rendered Templates +## Apply the Rendered Templates Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates. @@ -123,7 +121,7 @@ Use `kubectl` to apply the rendered manifests. kubectl -n cattle-system apply -R -f ./rancher ``` -# Verify the Upgrade +## Verify the Upgrade Log into Rancher to confirm that the upgrade succeeded. @@ -131,6 +129,6 @@ Log into Rancher to confirm that the upgrade succeeded. > > See [Restoring Cluster Networking](../../../../version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md). -# Known Upgrade Issues +## Known Upgrade Issues A 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) diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md index f937060f426..f6e196e23f9 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md @@ -8,7 +8,7 @@ The guide uses command line tools to provision an AKS cluster with an ingress. I If you already have an AKS Kubernetes cluster, skip to the step about [installing an ingress.](#5-install-an-ingress) Then install the Rancher Helm chart following the instructions on [this page.](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart) -# Prerequisites +## Prerequisites >**Note** >Deploying to Microsoft Azure will incur charges. @@ -19,7 +19,7 @@ If you already have an AKS Kubernetes cluster, skip to the step about [installin - Your subscription has sufficient quota for at least 2 vCPUs. For details on Rancher server resource requirements, refer to [this section](../../../pages-for-subheaders/installation-requirements.md#rke-and-hosted-kubernetes) - When installing Rancher with Helm in Azure, use the L7 load balancer to avoid networking issues. For more information, refer to the documentation on [Azure load balancer limitations](https://docs.microsoft.com/en-us/azure/load-balancer/components#limitations). -# 1. Prepare your Workstation +## 1. Prepare your Workstation Install the following command line tools on your workstation: @@ -27,7 +27,7 @@ Install the following command line tools on your workstation: - **kubectl:** For help, refer to these [installation steps.](https://kubernetes.io/docs/tasks/tools/#kubectl) - **helm:** For help, refer to these [installation steps.](https://helm.sh/docs/intro/install/) -# 2. Create a Resource Group +## 2. Create a Resource Group After installing the CLI, you will need to log in with your Azure account. @@ -41,7 +41,7 @@ Create a [resource group](https://docs.microsoft.com/en-us/azure/azure-resource- az group create --name rancher-rg --location eastus ``` -# 3. Create the AKS Cluster +## 3. Create the AKS Cluster To create an AKS cluster, run the following command. Use a VM size that applies to your use case. Refer to [this article](https://docs.microsoft.com/en-us/azure/virtual-machines/sizes) for available sizes and options. When choosing a Kubernetes version, be sure to first consult the [support matrix](https://rancher.com/support-matrix/) to find the highest version of Kubernetes that has been validated for your Rancher version. @@ -56,7 +56,7 @@ az aks create \ The cluster will take some time to be deployed. -# 4. Get Access Credentials +## 4. Get Access Credentials After the cluster is deployed, get the access credentials. @@ -66,7 +66,7 @@ az aks get-credentials --resource-group rancher-rg --name rancher-server This command merges your cluster's credentials into the existing kubeconfig and allows `kubectl` to interact with the cluster. -# 5. Install an Ingress +## 5. Install an Ingress The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. Installing an Ingress requires allocating a public IP address. Ensure you have sufficient quota, otherwise it will fail to assign the IP address. Limits for public IP addresses are applicable at a regional level per subscription. @@ -83,7 +83,7 @@ helm upgrade --install \ --create-namespace ``` -# 6. Get Load Balancer IP +## 6. Get Load Balancer IP To get the address of the load balancer, run: @@ -102,7 +102,7 @@ ingress-nginx-controller LoadBalancer 10.0.116.18 40.31.180.83 80:31229 Save the `EXTERNAL-IP`. -# 7. Set up DNS +## 7. Set up DNS External traffic to the Rancher server will need to be directed at the load balancer you created. @@ -110,7 +110,7 @@ Set up a DNS to point at the `EXTERNAL-IP` that you saved. This DNS will be used There are many valid ways to set up the DNS. For help, refer to the [Azure DNS documentation](https://docs.microsoft.com/en-us/azure/dns/) -# 8. Install the Rancher Helm Chart +## 8. Install the Rancher Helm Chart Next, install the Rancher Helm chart by following the instructions on [this page.](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart) The Helm instructions are the same for installing Rancher on any Kubernetes distribution. diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md index c1cdff17b5d..bd1f18ffac3 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md @@ -13,7 +13,7 @@ If you already have an EKS Kubernetes cluster, skip to the step about [installin - [Automated Quickstart using AWS Best Practices](#automated-quickstart-using-aws-best-practices) - [Creating an EKS Cluster for the Rancher Server](#creating-an-eks-cluster-for-the-rancher-server) -# Automated Quickstart using AWS Best Practices +## Automated Quickstart using AWS Best Practices Rancher and Amazon Web Services collaborated on a quick start guide for deploying Rancher on an EKS cluster following AWS best practices. The deployment guide is [here.](https://aws-quickstart.github.io/quickstart-eks-rancher/) @@ -39,7 +39,7 @@ Deploying this Quick Start for a new virtual private cloud (VPC) and new Amazon \* The CloudFormation template that deploys the Quick Start into an existing Amazon EKS cluster skips the components marked by asterisks and prompts you for your existing VPC configuration. -# Creating an EKS Cluster for the Rancher Server +## Creating an EKS Cluster for the Rancher Server In this section, you'll install an EKS cluster with an ingress by using command line tools. This guide may be useful if you want to use fewer resources while trying out Rancher on EKS. diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md index 635e96538dc..caef08688f5 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md @@ -9,13 +9,13 @@ In this section, you'll learn how to install Rancher using Google Kubernetes Eng If you already have a GKE Kubernetes cluster, skip to the step about [installing an ingress.](#7-install-an-ingress) Then install the Rancher Helm chart following the instructions on [this page.](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart) -# Prerequisites +## Prerequisites - You will need a Google account. - You will need a Google Cloud billing account. You can manage your Cloud Billing accounts using the Google Cloud Console. For more information about the Cloud Console, visit [General guide to the console.](https://support.google.com/cloud/answer/3465889?hl=en&ref_topic=3340599) - You will need a cloud quota for at least one in-use IP address and at least 2 CPUs. For more details about hardware requirements for the Rancher server, refer to [this section.](../../../pages-for-subheaders/installation-requirements.md#rke-and-hosted-kubernetes) -# 1. Enable the Kubernetes Engine API +## 1. Enable the Kubernetes Engine API Take the following steps to enable the Kubernetes Engine API: @@ -24,7 +24,7 @@ Take the following steps to enable the Kubernetes Engine API: 1. Open the project and enable the Kubernetes Engine API for the project. Wait for the API and related services to be enabled. This can take several minutes. 1. Make sure that billing is enabled for your Cloud project. For information on how to enable billing for your project, refer to the [Google Cloud documentation.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project) -# 2. Open the Cloud Shell +## 2. Open the Cloud Shell Cloud Shell is a shell environment for managing resources hosted on Google Cloud. Cloud Shell comes preinstalled with the `gcloud` command-line tool and kubectl command-line tool. The `gcloud` tool provides the primary command-line interface for Google Cloud, and `kubectl` provides the primary command-line interface for running commands against Kubernetes clusters. @@ -63,7 +63,7 @@ To install `gcloud` and `kubectl`, perform the following steps: -# 3. Configure the gcloud CLI +## 3. Configure the gcloud CLI Set up default gcloud settings using one of the following methods: @@ -91,7 +91,7 @@ To install `gcloud` and `kubectl`, perform the following steps: -# 4. Confirm that gcloud is configured correctly +## 4. Confirm that gcloud is configured correctly Run: @@ -113,7 +113,7 @@ project = Your active configuration is: [default] ``` -# 5. Create a GKE Cluster +## 5. Create a GKE Cluster The following command creates a three-node cluster. @@ -125,7 +125,7 @@ When choosing a Kubernetes version, be sure to first consult the [support matrix gcloud container clusters create cluster-name --num-nodes=3 --cluster-version=1.20.10-gke.301 ``` -# 6. Get Authentication Credentials +## 6. Get Authentication Credentials After creating your cluster, you need to get authentication credentials to interact with the cluster: @@ -135,7 +135,7 @@ gcloud container clusters get-credentials cluster-name This command configures `kubectl` to use the cluster you created. -# 7. Install an Ingress +## 7. Install an Ingress The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. @@ -152,7 +152,7 @@ helm upgrade --install \ --create-namespace ``` -# 8. Get the Load Balancer IP +## 8. Get the Load Balancer IP To get the address of the load balancer, run: @@ -169,7 +169,7 @@ ingress-nginx-controller LoadBalancer 10.3.244.156 35.233.206.34 80:3187 Save the `EXTERNAL-IP`. -# 9. Set up DNS +## 9. Set up DNS External traffic to the Rancher server will need to be directed at the load balancer you created. @@ -177,7 +177,7 @@ Set up a DNS to point at the external IP that you saved. This DNS will be used a There are many valid ways to set up the DNS. For help, refer to the Google Cloud documentation about [managing DNS records.](https://cloud.google.com/dns/docs/records) -# 10. Install the Rancher Helm chart +## 10. Install the Rancher Helm chart Next, install the Rancher Helm chart by following the instructions on [this page.](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart) The Helm instructions are the same for installing Rancher on any Kubernetes distribution. diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md index 1c563222f41..f2a5ce6e694 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md @@ -6,7 +6,7 @@ title: Rollbacks - [Rolling Back to Rancher v2.2-v2.4+](#rolling-back-to-rancher-v2-2-v2-4) - [Rolling Back to Rancher v2.0-v2.1](#rolling-back-to-rancher-v2-0-v2-1) -# Rolling Back to Rancher v2.5.0+ +## Rolling Back to Rancher v2.5.0+ To roll back to Rancher v2.5.0+, use the **Rancher Backups** application and restore Rancher from backup. @@ -90,7 +90,7 @@ When the target revision is determined, perform the rollback. This example will helm rollback rancher 3 -n cattle-system ``` -# Rolling Back to Rancher v2.2-v2.4+ +## Rolling Back to Rancher v2.2-v2.4+ To roll back to Rancher before v2.5, follow the procedure detailed here: [Restoring Backups — Kubernetes installs](../../../../version-2.0-2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md) Restoring a snapshot of the Rancher server cluster will revert Rancher to the version and state at the time of the snapshot. @@ -98,6 +98,6 @@ For information on how to roll back Rancher installed with Docker, refer to [thi > Managed clusters are authoritative for their state. This means restoring the rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken. -# Rolling Back to Rancher v2.0-v2.1 +## Rolling Back to Rancher v2.0-v2.1 Rolling back to Rancher v2.0-v2.1 is no longer supported. The instructions for rolling back to these versions are preserved [here](../../../../version-2.0-2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md) and are intended to be used only in cases where upgrading to Rancher v2.2+ is not feasible. diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md index 85db55591a8..464a19437f2 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md @@ -15,7 +15,7 @@ To upgrade the components in your Kubernetes cluster, or the definition of the [ - [Known Upgrade Issues](#known-upgrade-issues) - [RKE Add-on Installs](#rke-add-on-installs) -# Prerequisites +## Prerequisites ### Access to kubeconfig @@ -49,7 +49,7 @@ If you are upgrading to Rancher v2.5 from a Rancher server that was started with [Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) Upgrade cert-manager to the latest version by following [these instructions.](../resources/upgrade-cert-manager.md) -# Upgrade Outline +## Upgrade Outline Follow the steps to upgrade Rancher server: @@ -58,13 +58,13 @@ Follow the steps to upgrade Rancher server: - [3. Upgrade Rancher](#3-upgrade-rancher) - [4. Verify the Upgrade](#4-verify-the-upgrade) -# 1. Back up Your Kubernetes Cluster that is Running Rancher Server +## 1. Back up Your Kubernetes Cluster that is Running Rancher Server Use the [backup application](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md) to back up Rancher. You'll use the backup as a restoration point if something goes wrong during upgrade. -# 2. Update the Helm chart repository +## 2. Update the Helm chart repository 1. Update your local helm repo cache. @@ -114,7 +114,7 @@ You'll use the backup as a restoration point if something goes wrong during upgr helm fetch rancher-/rancher --version=2.5.16 ``` -# 3. Upgrade Rancher +## 3. Upgrade Rancher This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm. @@ -180,7 +180,7 @@ If you are currently running the cert-manager whose version is older than v0.11, --set hostname=rancher.my.org ``` -# 4. Verify the Upgrade +## 4. Verify the Upgrade Log into Rancher to confirm that the upgrade succeeded. @@ -188,6 +188,6 @@ Log into Rancher to confirm that the upgrade succeeded. > > See [Restoring Cluster Networking](../../../../version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md). -# Known Upgrade Issues +## Known Upgrade Issues A 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) diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md index 598aa1ce669..5eee695e181 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md @@ -11,7 +11,7 @@ import PortsImportedHosted from '@site/src/components/PortsImportedHosted' To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes. -# Rancher Nodes +## Rancher Nodes The following table lists the ports that need to be open to and from nodes that are running the Rancher server. @@ -163,7 +163,7 @@ The following tables break down the port requirements for Rancher nodes, for inb -# Downstream Kubernetes Cluster Nodes +## Downstream Kubernetes Cluster Nodes Downstream Kubernetes clusters run your apps and services. This section describes what ports need to be opened on the nodes in downstream clusters so that Rancher can communicate with them. @@ -229,7 +229,7 @@ The following table depicts the port requirements for [registered clusters](../. -# Other Port Considerations +## Other Port Considerations ### Commonly Used Ports diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md index e91930eb77f..158359aa069 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md @@ -11,11 +11,11 @@ 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. @@ -26,7 +26,7 @@ This section describes installing Rancher: - [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. @@ -57,7 +57,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. @@ -70,7 +70,7 @@ When Rancher is installed on an air gapped Kubernetes cluster, there are two rec | Rancher Generated Self-Signed Certificates | `ingress.tls.source=rancher` | Use certificates issued by Rancher's generated CA (self signed)
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).
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. @@ -80,11 +80,11 @@ When setting up the Rancher Helm template, there are several options in the Helm | `systemDefaultRegistry` | `` | 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. @@ -177,7 +177,7 @@ helm template rancher ./rancher-.tgz --output-dir . \ -# Option B: Certificates From Files using Kubernetes Secrets +## Option B: Certificates From Files using Kubernetes Secrets ### 1. Create secrets @@ -262,7 +262,7 @@ Then refer to [Adding TLS Secrets](../../resources/add-tls-secrets.md/) to publi -# 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. @@ -307,7 +307,7 @@ The installation is complete. > **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. -# Additional Resources +## Additional Resources These resources could be helpful when installing Rancher: diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md index 43e2e8c8612..b77c5028260 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md @@ -110,7 +110,7 @@ The `rancher-images.txt` is expected to be on the workstation in the same direct For Rancher servers that will provision Linux and Windows clusters, there are distinctive steps to populate your private registry for the Windows images and the Linux images. Since a Windows cluster is a mix of Linux and Windows nodes, the Linux images pushed into the private registry are manifests. -# Windows Steps +## Windows Steps The Windows images need to be collected and pushed from a Windows server workstation. @@ -189,7 +189,7 @@ The `rancher-windows-images.txt` is expected to be on the workstation in the sam ./rancher-load-images.ps1 --registry ``` -# Linux Steps +## Linux Steps The Linux images need to be collected and pushed from a Linux host, but _must be done after_ populating the Windows images into the private registry. These step are different from the Linux only steps as the Linux images that are pushed will actually manifests that support Windows and Linux images. diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md index 8a87aef578f..b8e0cffd01f 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md @@ -7,12 +7,12 @@ import TabItem from '@theme/TabItem'; The following instructions will guide you through upgrading a Rancher server that was installed with Docker. -# Prerequisites +## Prerequisites - **Review the [known upgrade issues](../../install-upgrade-on-a-kubernetes-cluster/upgrades.md#known-upgrade-issues) 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 (``). @@ -24,7 +24,7 @@ docker stop In this command, `` 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: @@ -48,7 +48,7 @@ Write down or copy this information before starting the upgrade. You can obtain `` and `` 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 Outline During upgrade, you create a copy of the data from your current Rancher container and a backup in case something goes wrong. Then you deploy the new version of Rancher in a new container using your existing data. Follow the steps to upgrade Rancher server: @@ -59,7 +59,7 @@ During upgrade, you create a copy of the data from your current Rancher containe - [5. Verify the Upgrade](#5-verify-the-upgrade) - [6. Clean up your old Rancher server container](#6-clean-up-your-old-rancher-server-container) -# 1. Create a copy of the data from your Rancher server container +## 1. 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. @@ -75,7 +75,7 @@ During upgrade, you create a copy of the data from your current Rancher containe docker create --volumes-from --name rancher-data rancher/rancher: ``` -# 2. Create a backup tarball +## 2. Create a backup tarball 1. From the data container that you just created (rancher-data), create a backup tarball (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz). @@ -97,7 +97,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. @@ -109,7 +109,7 @@ Placeholder | Description docker pull rancher/rancher: ``` -# 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. @@ -351,7 +351,7 @@ As of Rancher v2.5, privileged access is [required.](../../../../pages-for-subhe **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. @@ -360,10 +360,10 @@ Log into Rancher. Confirm that the upgrade succeeded by checking the version dis > See [Restoring Cluster Networking](../../../../../version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md). -# 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). diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/add-tls-secrets.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/add-tls-secrets.md index 6c31231b0db..c649daf31b1 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/add-tls-secrets.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/add-tls-secrets.md @@ -19,7 +19,7 @@ kubectl -n cattle-system create secret tls tls-rancher-ingress \ > **Note:** If you want to replace the certificate, you can delete the `tls-rancher-ingress` secret using `kubectl -n cattle-system delete secret tls-rancher-ingress` and add a new one using the command shown above. If you are using a private CA signed certificate, replacing the certificate is only possible if the new certificate is signed by the same CA as the certificate currently in use. -# Using a Private CA Signed Certificate +## Using a Private CA Signed Certificate If you are using a private CA, Rancher requires a copy of the CA certificate which is used by the Rancher Agent to validate the connection to the server. @@ -32,6 +32,6 @@ kubectl -n cattle-system create secret generic tls-ca \ > **Note:** The configured `tls-ca` secret is retrieved when Rancher starts. On a running Rancher installation the updated CA will take effect after new Rancher pods are started. -# Updating a Private CA Certificate +## Updating a Private CA Certificate Follow the steps on [this page](update-rancher-certificate.md) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate. \ No newline at end of file diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/local-system-charts.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/local-system-charts.md index bc758c0bb22..b1a86fad7ab 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/local-system-charts.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/local-system-charts.md @@ -6,9 +6,8 @@ The [System Charts](https://github.com/rancher/system-charts) repository contain In an air gapped installation of Rancher, you will need to configure Rancher to use a local copy of the system charts. This section describes how to use local system charts using a CLI flag. -# Using Local System Charts +## Using Local System Charts A local copy of `system-charts` has been packaged into the `rancher/rancher` container. To be able to use these features in an air gap install, you will need to run the Rancher install command with an extra environment variable, `CATTLE_SYSTEM_CATALOG=bundled`, which tells Rancher to use the local copy of the charts instead of attempting to fetch them from GitHub. Example commands for a Rancher installation with a bundled `system-charts` are included in the [air gap Docker installation](../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md) instructions and the [air gap Kubernetes installation](../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md) instructions. - diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md index 40c4792277a..0c1ab63ddac 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md @@ -2,7 +2,7 @@ title: Updating the Rancher Certificate --- -# Updating a Private CA Certificate +## Updating a Private CA Certificate Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate. @@ -16,7 +16,7 @@ A summary of the steps is as follows: The details of these instructions are below. -## 1. Create/update the certificate secret resource +### 1. Create/update the certificate secret resource First, concatenate the server certificate followed by any intermediate certificate(s) to a file named `tls.crt` and provide the corresponding certificate key in a file named `tls.key`. @@ -37,7 +37,7 @@ $ kubectl -n cattle-system create secret tls tls-rancher-ingress \ --dry-run --save-config -o yaml | kubectl apply -f - ``` -## 2. Create/update the CA certificate secret resource +### 2. Create/update the CA certificate secret resource If the new certificate was signed by a private CA, you will need to copy the corresponding root CA certificate into a file named `cacerts.pem` and create or update the `tls-ca secret` in the `cattle-system` namespace. If the certificate was signed by an intermediate CA, then the `cacerts.pem` must contain both the intermediate and root CA certificates (in this order). @@ -56,7 +56,7 @@ $ kubectl -n cattle-system create secret generic tls-ca \ --dry-run --save-config -o yaml | kubectl apply -f - ``` -## 3. Reconfigure the Rancher deployment +### 3. Reconfigure the Rancher deployment > Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4. @@ -91,18 +91,18 @@ helm upgrade rancher rancher-stable/rancher \ When the upgrade is completed, navigate to `https:///v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier. -## 4. Reconfigure Rancher agents to trust the private CA +### 4. Reconfigure Rancher agents to trust the private CA This section covers three methods to reconfigure Rancher agents to trust the private CA. This step is required if either of the following is true: - Rancher was initially configured to use the Rancher self-signed certificate (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`) - The root CA certificate for the new custom certificate has changed -### Why is this step required? +#### Why is this step required? When Rancher is configured with a certificate signed by a private CA, the CA certificate chain is downloaded into Rancher agent containers. Agents compare the checksum of the downloaded certificate against the `CATTLE_CA_CHECKSUM` environment variable. This means that, when the private CA certificate is changed on Rancher server side, the environvment variable `CATTLE_CA_CHECKSUM` must be updated accordingly. -### Which method should I choose? +#### Which method should I choose? Method 1 is the easiest one but requires all clusters to be connected to Rancher after the certificates have been rotated. This is usually the case if the process is performed right after updating the Rancher deployment (Step 3). @@ -110,7 +110,7 @@ If the clusters have lost connection to Rancher but you have [Authorized Cluster Method 3 can be used as a fallback if method 1 and 2 are unfeasible. -### Method 1: Kubectl command +#### Method 1: Kubectl command For each cluster under Rancher management (except the `local` Rancher management cluster) run the following command using the Kubeconfig file of the Rancher management cluster (RKE or K3S). @@ -120,8 +120,7 @@ kubectl patch clusters.management.cattle.io -p '{"statu This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. - -### Method 2: Manually update checksum +#### Method 2: Manually update checksum Manually patch the agent Kubernetes resources by updating the `CATTLE_CA_CHECKSUM` environment variable to the value matching the checksum of the new CA certificate. Generate the new checksum value like so: @@ -137,7 +136,7 @@ $ kubectl edit -n cattle-system ds/cattle-node-agent $ kubectl edit -n cattle-system deployment/cattle-cluster-agent ``` -### Method 3: Recreate Rancher agents +#### Method 3: Recreate Rancher agents With this method you are recreating the Rancher agents by running a set of commands on a controlplane node of each downstream cluster. @@ -147,7 +146,7 @@ Then, connect to a controlplane node of the downstream cluster via SSH, create a https://gist.github.com/superseb/b14ed3b5535f621ad3d2aa6a4cd6443b -## 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher +### 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher Select 'Force Update' for the clusters within the [Continuous Delivery](../../../how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.md#accessing-fleet-in-the-rancher-ui) view under Cluster Explorer in the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher. @@ -155,11 +154,11 @@ Select 'Force Update' for the clusters within the [Continuous Delivery](../../.. Fleet agents in Rancher managed clusters store kubeconfig that is used to connect to the Rancher proxied kube-api in the fleet-agent secret of the fleet-system namespace. The kubeconfig contains a certificate-authority-data block containing the Rancher CA. When changing the Rancher CA, this block needs to be updated for a successful connection of the fleet-agent to Rancher. -# Updating from a Private CA Certificate to a Common Certificate +## Updating from a Private CA Certificate to a Common Certificate >It is possible to perform the opposite procedure as shown above: you may change from a private certificate to a common, or non-private, certificate. The steps involved are outlined below. -## 1. Create/update the certificate secret resource +### 1. Create/update the certificate secret resource First, concatenate the server certificate followed by any intermediate certificate(s) to a file named `tls.crt` and provide the corresponding certificate key in a file named `tls.key`. @@ -180,7 +179,7 @@ $ kubectl -n cattle-system create secret tls tls-rancher-ingress \ --dry-run --save-config -o yaml | kubectl apply -f - ``` -## 2. Delete the CA certificate secret resource +### 2. Delete the CA certificate secret resource You will delete the `tls-ca secret` in the `cattle-system` namespace as it is no longer needed. You may also optionally save a copy of the `tls-ca secret` if desired. @@ -196,7 +195,7 @@ To delete the existing `tls-ca` secret: kubectl -n cattle-system delete secret tls-ca ``` -## 3. Reconfigure the Rancher deployment +### 3. Reconfigure the Rancher deployment > Before proceeding, [generate an API token in the Rancher UI](../../../reference-guides/user-settings/api-keys.md#creating-an-api-key) (User > API & Keys). @@ -238,14 +237,14 @@ On upgrade, you can either set privateCA=false ``` -## 4. Reconfigure Rancher agents for the non-private/common certificate +### 4. Reconfigure Rancher agents for the non-private/common certificate `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). -## 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher +### 5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher Select 'Force Update' for the clusters within the [Continuous Delivery](../../../how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.md#accessing-fleet-in-the-rancher-ui) view under Cluster Explorer in the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher. -### Why is this step required? +#### Why is this step required? Fleet agents in Rancher managed clusters store kubeconfig that is used to connect to the Rancher proxied kube-api in the fleet-agent secret of the fleet-system namespace. The kubeconfig contains a certificate-authority-data block containing the Rancher CA. When changing the Rancher CA, this block needs to be updated for a successful connection of the fleet-agent to Rancher. \ No newline at end of file diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md index 8114cc656bc..2330eb7ec46 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md @@ -24,7 +24,7 @@ To address these changes, this guide will do two things: > For reinstalling Rancher with Helm, please check [Option B: Reinstalling Rancher Chart](../install-upgrade-on-a-kubernetes-cluster/upgrades.md) under the upgrade Rancher section. -# Upgrade Cert-Manager +## Upgrade Cert-Manager The namespace used in these instructions depends on the namespace cert-manager is currently installed in. If it is in kube-system use that in the instructions below. You can verify by running `kubectl get pods --all-namespaces` and checking which namespace the cert-manager-\* pods are listed in. Do not change the namespace cert-manager is running in or this can cause issues. @@ -239,4 +239,3 @@ We have also removed support for the old configuration format that was deprecate Details about the change and migration instructions can be found in the [cert-manager v0.10 to v0.11 upgrade instructions](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/). More info about [cert-manager upgrade information](https://cert-manager.io/docs/installation/upgrading/). - diff --git a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md index 8bf01f5ed4e..4faa8ce61b5 100644 --- a/versioned_docs/version-2.5/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md +++ b/versioned_docs/version-2.5/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md @@ -45,7 +45,7 @@ The restore operation will work on a cluster that is not in a healthy or active **Result:** Kubernetes begins upgrading for the cluster. -# Rolling Back +## Rolling Back A cluster can be restored to a backup in which the previous Kubernetes version was used. For more information, refer to the following sections: diff --git a/versioned_docs/version-2.5/getting-started/introduction/overview.md b/versioned_docs/version-2.5/getting-started/introduction/overview.md index 22aa55bd068..35d048c189f 100644 --- a/versioned_docs/version-2.5/getting-started/introduction/overview.md +++ b/versioned_docs/version-2.5/getting-started/introduction/overview.md @@ -4,11 +4,11 @@ title: Overview Rancher is a container management platform built for organizations that deploy containers in production. Rancher makes it easy to run Kubernetes everywhere, meet IT requirements, and empower DevOps teams. -# Run Kubernetes Everywhere +## Run Kubernetes Everywhere Kubernetes has become the container orchestration standard. Most cloud and virtualization vendors now offer it as standard infrastructure. Rancher users have the choice of creating Kubernetes clusters with Rancher Kubernetes Engine (RKE) or cloud Kubernetes services, such as GKE, AKS, and EKS. Rancher users can also import and manage their existing Kubernetes clusters created using any Kubernetes distribution or installer. -# Meet IT requirements +## Meet IT requirements Rancher supports centralized authentication, access control, and monitoring for all Kubernetes clusters under its control. For example, you can: @@ -16,7 +16,7 @@ Rancher supports centralized authentication, access control, and monitoring for - Setup and enforce access control and security policies across all users, groups, projects, clusters, and clouds. - View the health and capacity of your Kubernetes clusters from a single-pane-of-glass. -# Empower DevOps Teams +## Empower DevOps Teams Rancher provides an intuitive user interface for DevOps engineers to manage their application workload. The user does not need to have in-depth knowledge of Kubernetes concepts to start using Rancher. Rancher catalog contains a set of useful DevOps tools. Rancher is certified with a wide selection of cloud native ecosystem products, including, for example, security tools, monitoring systems, container registries, and storage and networking drivers. @@ -24,7 +24,7 @@ The following figure illustrates the role Rancher plays in IT and DevOps organiz ![Platform](/img/platform.png) -# Features of the Rancher API Server +## Features of the Rancher API Server The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities: @@ -52,7 +52,7 @@ The Rancher API server is built on top of an embedded Kubernetes API server and - **Monitoring:** Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution. - **Alerting:** To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. -# Editing Downstream Clusters with Rancher +## Editing Downstream Clusters with Rancher The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters [provisioned by RKE](../../pages-for-subheaders/launch-kubernetes-with-rancher.md) have **Cluster Options** available for editing. diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md index 99fc5e23827..8840a2fe95d 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md @@ -8,7 +8,7 @@ Only admins of the G Suite domain have access to the Admin SDK. Therefore, only Within Rancher, only administrators or users with the **Manage Authentication** [global role](../../manage-role-based-access-control-rbac/global-permissions.md) can configure authentication. -# Prerequisites +## Prerequisites - You must have a [G Suite admin account](https://admin.google.com) configured. - G Suite requires a [top private domain FQDN](https://github.com/google/guava/wiki/InternetDomainNameExplained#public-suffixes-and-private-domains) as an authorized domain. One way to get an FQDN is by creating an A-record in Route53 for your Rancher server. You do not need to update your Rancher Server URL setting with that record, because there could be clusters using that URL. - You must have the Admin SDK API enabled for your G Suite domain. You can enable it using the steps on [this page.](https://support.google.com/a/answer/60757?hl=en) @@ -16,7 +16,7 @@ Within Rancher, only administrators or users with the **Manage Authentication** After the Admin SDK API is enabled, your G Suite domain's API screen should look like this: ![Enable Admin APIs](/img/Google-Enable-APIs-Screen.png) -# Setting up G Suite for OAuth with Rancher +## Setting up G Suite for OAuth with Rancher Before you can set up Google OAuth in Rancher, you need to log in to your G Suite account and do the following: 1. [Add Rancher as an authorized domain in G Suite](#1-adding-rancher-as-an-authorized-domain) @@ -89,7 +89,8 @@ Using the Unique ID of the service account key, register it as an Oauth Client u **Result:** The service account is registered as an OAuth client in your G Suite account. -# Configuring Google OAuth in Rancher +## Configuring Google OAuth in Rancher + 1. Sign into Rancher using a local user assigned the [administrator](../../manage-role-based-access-control-rbac/global-permissions.md) role. This user is also called the local principal. 1. From the **Global** view, click **Security > Authentication** from the main menu. 1. Click **Google.** The instructions in the UI cover the steps to set up authentication with Google OAuth. diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md index 427b4a072fc..ec0f27d8e2f 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md @@ -10,19 +10,11 @@ After you complete [Configuring Microsoft AD FS for Rancher](configure-ms-adfs-f >- The Relying Party Trust identifier URL is: `https:///v1-saml/adfs/saml/metadata` >- You must export the `federationmetadata.xml` file from your AD FS server. This can be found at: `https:///federationmetadata/2007-06/federationmetadata.xml` +1. From the **Global** view, select **Security > Authentication** from the main menu. -1. From the **Global** view, select **Security > Authentication** from the main menu. - -1. Select **Microsoft Active Directory Federation Services**. - -1. Complete the **Configure AD FS Account** form. Microsoft AD FS lets you specify an existing Active Directory (AD) server. The [configuration section below](#configuration) describe how you can map AD attributes to fields within Rancher. - - - - - - +1. Select **Microsoft Active Directory Federation Services**. +1. Complete the **Configure AD FS Account** form. Microsoft AD FS lets you specify an existing Active Directory (AD) server. The [configuration section below](#configuration) describe how you can map AD attributes to fields within Rancher. 1. After you complete the **Configure AD FS Account** form, click **Authenticate with AD FS**, which is at the bottom of the page. @@ -32,7 +24,7 @@ After you complete [Configuring Microsoft AD FS for Rancher](configure-ms-adfs-f **Result:** Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins. -# Configuration +## Configuration | Field | Description | |---------------------------|-----------------| diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md index dcadeb51b2f..95bb13ca4e8 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md @@ -6,7 +6,7 @@ Administrators have the permission to create RKE templates, and only administrat For more information on administrator permissions, refer to the [documentation on global permissions](../manage-role-based-access-control-rbac/global-permissions.md). -# Giving Users Permission to Create Templates +## Giving Users Permission to Create Templates Templates can only be created by users who have the global permission **Create RKE Templates.** diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md index 123feab5703..51de52b295e 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md @@ -17,7 +17,7 @@ Global Permissions define user authorization outside the scope of any particular You cannot update or delete the built-in Global Permissions. -# Restricted Admin +## Restricted Admin A new `restricted-admin` role was created in Rancher v2.5 in order to prevent privilege escalation from the local Rancher server Kubernetes cluster. This role has full administrator access to all downstream clusters managed by Rancher, but it does not have permission to alter the local Kubernetes cluster. @@ -30,6 +30,7 @@ To bootstrap Rancher with the `restricted-admin` as the initial user, the Ranche ``` CATTLE_RESTRICTED_DEFAULT_ADMIN=true ``` + ### List of `restricted-admin` Permissions The permissions for the `restricted-admin` role differ based on the Rancher version. @@ -75,7 +76,7 @@ This can be done through **Security > Users** and moving any Administrator role Signed-in users can change themselves over to the `restricted-admin` if they wish, but they should only do that as the last step, otherwise they won't have the permissions to do so. -# Global Permission Assignment +## Global Permission Assignment Global permissions for local users are assigned differently than users who log in to Rancher using external authentication. @@ -95,7 +96,7 @@ Permissions can be assigned to an individual user with [these steps.](#configuri You can [assign a role to everyone in the group at the same time](#configuring-global-permissions-for-groups) if the external authentication provider supports groups. -# Custom Global Permissions +## Custom Global Permissions Using custom permissions is convenient for providing users with narrow or specialized access to Rancher. diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md index 35d48666c07..d49f9885802 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md @@ -19,6 +19,6 @@ title: 1. Enable Istio in the Cluster **Result:** Istio is installed at the cluster level. -# Additional Config Options +## Additional Config Options For more information on configuring Istio, refer to the [configuration reference.](../../../pages-for-subheaders/configuration-options.md) diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md index 71a3f2a879c..5dca79353e0 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md @@ -4,7 +4,7 @@ title: 6. Generate and View Traffic This section describes how to view the traffic that is being managed by Istio. -# The Kiali Traffic Graph +## The Kiali Traffic Graph The Istio overview page provides a link to the Kiali dashboard. From the Kiali dashboard, you are able to view graphs for each namespace. The Kiali graph provides a powerful way to visualize the topology of your Istio service mesh. It shows you which services communicate with each other. diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md index 83c886c2244..1de19a10271 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md @@ -16,7 +16,7 @@ For more information on the Istio gateway, refer to the [Istio documentation.](h ![In an Istio-enabled cluster, you can have two Ingresses: the default Nginx Ingress, and the default Istio controller.](/img/istio-ingress.svg) -# Enable an Istio Gateway +## Enable an Istio Gateway The ingress gateway is a Kubernetes service that will be deployed in your cluster. The Istio Gateway allows for more extensive customization and flexibility. @@ -28,7 +28,7 @@ The ingress gateway is a Kubernetes service that will be deployed in your cluste **Result:** The gateway is deployed, and will now route traffic with applied rules -# Example Istio Gateway +## Example Istio Gateway We add the BookInfo app deployments in services when going through the Workloads example. Next we add an Istio Gateway so that the app is accessible from outside your cluster. @@ -122,7 +122,7 @@ To get the ingress gateway URL and port, For help inspecting the Istio controller URL and ports, try the commands the [Istio documentation.](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports) -# Troubleshooting +## Troubleshooting The [official Istio documentation](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#troubleshooting) suggests `kubectl` commands to inspect the correct ingress host and ingress port for external requests. diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md index c0ea2d0642b..9dceda8b29f 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md @@ -509,7 +509,7 @@ kubectl -n kube-system apply -f cluster-autoscaler-deployment.yaml **Note:** Cluster-autoscaler deployment can also be set up using [manual configuration](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler/cloudprovider/aws#manual-configuration) -# Testing +## Testing At this point, we should have a cluster-scaler up and running in our Rancher custom cluster. Cluster-scale should manage `K8sWorkerAsg` ASG to scale up and down between 2 and 10 nodes, when one of the following conditions is true: diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.md index 6cd8fcf886d..c50f0543947 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.md @@ -7,7 +7,7 @@ After you launch a Kubernetes cluster in Rancher, you can manage individual node > If you want to manage the _cluster_ and not individual nodes, see [Editing Clusters](../../../pages-for-subheaders/cluster-configuration.md). -# Node Options Available for Each Cluster Creation Option +## Node Options Available for Each Cluster Creation Option The following table lists which node options are available for each type of cluster in Rancher. Click the links in the **Option** column for more detailed information about each feature. @@ -48,7 +48,7 @@ Options for managing nodes [hosted by a Kubernetes provider](../../../pages-for- Although you can deploy workloads to a [registered cluster](../../new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md) using Rancher, you cannot manage individual cluster nodes. All management of imported cluster nodes must take place outside of Rancher. -# Managing and Editing Individual Nodes +## Managing and Editing Individual Nodes Editing a node lets you: @@ -59,11 +59,11 @@ Editing a node lets you: To manage individual nodes, browse to the cluster that you want to manage and then select **Nodes** from the main menu. You can open the options menu for a node by clicking its **⋮** icon (**...**). -# Viewing a Node in the Rancher API +## Viewing a Node in the Rancher API Select this option to view the node's [API endpoints](../../../pages-for-subheaders/about-the-api.md). -# Deleting a Node +## Deleting a Node Use **Delete** to remove defective nodes from the cloud provider. @@ -71,11 +71,11 @@ When you the delete a defective node, Rancher can automatically replace it with >**Tip:** If your cluster is hosted by an infrastructure provider, and you want to scale your cluster down instead of deleting a defective node, [scale down](#scaling-nodes) rather than delete. -# Scaling Nodes +## Scaling Nodes For nodes hosted by an infrastructure provider, you can scale the number of nodes in each [node pool](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md#node-pools) by using the scale controls. This option isn't available for other cluster types. -# SSH into a Node Hosted by an Infrastructure Provider +## SSH into a Node Hosted by an Infrastructure Provider For [nodes hosted by an infrastructure provider](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md), you have the option of downloading its SSH key so that you can connect to it remotely from your desktop. @@ -95,11 +95,11 @@ For [nodes hosted by an infrastructure provider](../../../pages-for-subheaders/u ssh -i id_rsa root@ ``` -# Cordoning a Node +## Cordoning a Node _Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades, or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it. -# Draining a Node +## Draining a Node _Draining_ is the process of first cordoning the node, and then evicting all its pods. This feature is useful for performing node maintenance (like kernel upgrades or hardware maintenance). It prevents new pods from deploying to the node while redistributing existing pods so that users don't experience service interruption. @@ -144,7 +144,7 @@ Once drain successfully completes, the node will be in a state of `drained`. You >**Want to know more about cordon and drain?** See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/cluster-management/#maintenance-on-a-node). -# Labeling a Node to be Ignored by Rancher +## Labeling a Node to be Ignored by Rancher Some solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster. diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md index 59262573937..283e57a809a 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md @@ -10,7 +10,7 @@ To allow the Grafana dashboard to persist after the Grafana instance restarts, a - [Creating a Persistent Grafana Dashboard](#creating-a-persistent-grafana-dashboard) - [Known Issues](#known-issues) -# Creating a Persistent Grafana Dashboard +## Creating a Persistent Grafana Dashboard @@ -126,7 +126,7 @@ helm.sh/resource-policy: "keep" -# Known Issues +## Known Issues For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the `cattle-dashboards` namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation `helm.sh/resource-policy: "keep"`. diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md index cde740a7d2a..eafcbe5e8b7 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md @@ -11,7 +11,7 @@ This page describes how to enable monitoring and alerting within a cluster using You can enable monitoring with or without SSL. -# Requirements +## Requirements - Make sure that you are allowing traffic on port 9796 for each of your nodes because Prometheus will scrape metrics from here. - Make sure your cluster fulfills the resource requirements. The cluster should have at least 1950Mi memory available, 2700m CPU, and 50Gi storage. A breakdown of the resource limits and requests is [here.](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#configuring-resource-limits-and-requests) @@ -26,13 +26,13 @@ rkeEtcd: > **Note:** If you want to set up Alertmanager, Grafana or Ingress, it has to be done with the settings on the Helm chart deployment. It's problematic to create Ingress outside the deployment. -# Setting Resource Limits and Requests +## Setting Resource Limits and Requests The resource requests and limits can be configured when installing `rancher-monitoring`. To configure Prometheus resources from the Rancher UI, click **Apps & Marketplace > Monitoring** in the upper left corner. For more information about the default limits, see [this page.](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#configuring-resource-limits-and-requests) -# Install the Monitoring Application +## Install the Monitoring Application diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md index 16f1a6c6796..2e2272a5e51 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md @@ -5,7 +5,7 @@ title: Prometheus Configuration It is usually not necessary to directly edit the Prometheus custom resource because the monitoring application automatically updates it based on changes to ServiceMonitors and PodMonitors. > This section assumes familiarity with how monitoring components work together. For more information, see [this section.](../../../../explanations/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md) -# About the Prometheus Custom Resource +## About the Prometheus Custom Resource The Prometheus CR defines a desired Prometheus deployment. The Prometheus Operator observes the Prometheus CR. When the CR changes, the Prometheus Operator creates `prometheus-rancher-monitoring-prometheus`, a Prometheus deployment based on the CR configuration. diff --git a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md index f60903d087d..3fc9d75ae0c 100644 --- a/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md +++ b/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md @@ -9,7 +9,7 @@ A PrometheusRule defines a group of Prometheus alerting and/or recording rules. > This section assumes familiarity with how monitoring components work together. For more information, see [this section.](../../../../explanations/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md) -### Creating PrometheusRules in the Rancher UI +## Creating PrometheusRules in the Rancher UI _Available as of v2.5.4_ @@ -25,7 +25,7 @@ To create rule groups in the Rancher UI, **Result:** Alerts can be configured to send notifications to the receiver(s). -### About the PrometheusRule Custom Resource +## About the PrometheusRule Custom Resource When you define a Rule (which is declared within a RuleGroup in a PrometheusRule resource), the [spec of the Rule itself](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/api.md#rule) contains labels that are used by Alertmanager to figure out which Route should receive this Alert. For example, an Alert with the label `team: front-end` will be sent to all Routes that match on that label. @@ -42,7 +42,7 @@ Use the label selector field `ruleSelector` in the Prometheus object to define t For examples, refer to the Prometheus documentation on [recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/) and [alerting rules.](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) -# Configuration +## Configuration diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md index a863ae55a25..6fec91e759f 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md @@ -8,7 +8,7 @@ Rancher recommends configuring recurrent `etcd` snapshots for all production clu Snapshots of the etcd database are taken and saved either [locally onto the etcd nodes](#local-backup-target) or to a [S3 compatible target](#s3-backup-target). The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster. -# How Snapshots Work +## How Snapshots Work ### Snapshot Components @@ -64,7 +64,7 @@ On restore, the following process is used: 4. The other etcd nodes download the snapshot and validate the checksum so that they all use the same snapshot for the restore. 5. The cluster is restored and post-restore actions will be done in the cluster. -# Configuring Recurring Snapshots +## Configuring Recurring Snapshots Select how often you want recurring snapshots to be taken as well as how many snapshots to keep. The amount of time is measured in hours. With timestamped snapshots, the user has the ability to do a point-in-time recovery. @@ -81,7 +81,7 @@ In the **Advanced Cluster Options** section, there are several options available | Recurring etcd Snapshot Creation Period | Time in hours between recurring snapshots| 12 hours | | Recurring etcd Snapshot Retention Count | Number of snapshots to retain| 6 | -# One-Time Snapshots +## One-Time Snapshots In addition to recurring snapshots, you may want to take a "one-time" snapshot. For example, before upgrading the Kubernetes version of a cluster it's best to backup the state of the cluster to protect against upgrade failure. @@ -91,7 +91,7 @@ In addition to recurring snapshots, you may want to take a "one-time" snapshot. **Result:** Based on your [snapshot backup target](#snapshot-backup-targets), a one-time snapshot will be taken and saved in the selected backup target. -# Snapshot Backup Targets +## Snapshot Backup Targets Rancher supports two different backup targets: @@ -130,7 +130,7 @@ The `S3` backup target supports using IAM authentication to AWS API in addition To give an application access to S3, refer to the AWS documentation on [Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances.](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html) -# Viewing Available Snapshots +## Viewing Available Snapshots The list of all available snapshots for the cluster is available in the Rancher UI. @@ -138,7 +138,7 @@ The list of all available snapshots for the cluster is available in the Rancher 2. Click **Tools > Snapshots** from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created. -# Safe Timestamps +## Safe Timestamps Snapshot files are timestamped to simplify processing the files using external tools and scripts, but in some S3 compatible backends, these timestamps were unusable. @@ -146,6 +146,6 @@ The option `safe_timestamp` is added to support compatible file names. When this This option is not available directly in the UI, and is only available through the `Edit as Yaml` interface. -# Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0 +## Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0 If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must [edit the cluster](../../../pages-for-subheaders/cluster-configuration.md) and _save_ it, in order to enable the updated snapshot features. Even if you were already creating snapshots before v2.2.0, you must do this step as the older snapshots will not be available to use to [back up and restore etcd through the UI](restore-rancher-launched-kubernetes-clusters-from-backup.md). diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md index 51111c3878f..1212c084472 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md @@ -72,6 +72,6 @@ If the group of etcd nodes loses quorum, the Kubernetes cluster will report a fa 6. After the single nodes is up and running, Rancher recommends adding additional etcd nodes to your cluster. If you have a [custom cluster](../../../pages-for-subheaders/use-existing-nodes.md) and you want to reuse an old node, you are required to [clean up the nodes](../../advanced-user-guides/manage-clusters/clean-cluster-nodes.md) before attempting to add them back into a cluster. -# Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0 +## Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0 If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must [edit the cluster](../../../pages-for-subheaders/cluster-configuration.md) and _save_ it, in order to enable the updated snapshot features. Even if you were already creating snapshots before v2.2.0, you must do this step as the older snapshots will not be available to use to [back up and restore etcd through the UI](restore-rancher-launched-kubernetes-clusters-from-backup.md). diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md index daf5fd980be..a9fdbbed9a6 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md @@ -10,7 +10,7 @@ This tutorial is about one possible way to set up your load balancer, not the on Rancher only supports using the Amazon NLB when terminating traffic in `tcp` mode for port 443 rather than `tls` mode. This is due to the fact that the NLB does not inject the correct headers into requests when terminated at the NLB. This means that if you want to use certificates managed by the Amazon Certificate Manager (ACM), you should use an ALB. -# Setting up the Load Balancer +## Setting up the Load Balancer Configuring an Amazon NLB is a multistage process: @@ -19,11 +19,11 @@ Configuring an Amazon NLB is a multistage process: 3. [Create Your NLB](#3-create-your-nlb) 4. [Add listener to NLB for TCP port 80](#4-add-listener-to-nlb-for-tcp-port-80) -# Requirements +## Requirements These instructions assume you have already created Linux instances in EC2. The load balancer will direct traffic to these nodes. -# 1. Create Target Groups +## 1. Create Target Groups Begin by creating two target groups for the **TCP** protocol, one with TCP port 443 and one regarding TCP port 80 (providing redirect to TCP port 443). You'll add your Linux nodes to these groups. @@ -86,7 +86,7 @@ Health check settings: | Timeout | `6 seconds` | | Interval | `10 seconds` | -# 2. Register Targets +## 2. Register Targets Next, add your Linux nodes to both target groups. @@ -110,7 +110,7 @@ When the instances are added, click **Save** on the bottom right of the screen. Repeat those steps, replacing **rancher-tcp-443** with **rancher-tcp-80**. The same instances need to be added as targets to this target group. -# 3. Create Your NLB +## 3. Create Your NLB Use Amazon's Wizard to create a Network Load Balancer. As part of this process, you'll add the target groups you created in [1. Create Target Groups](#1-create-target-groups). @@ -152,7 +152,7 @@ Look over the load balancer details and click **Create** when you're satisfied. After AWS creates the NLB, click **Close**. -# 4. Add listener to NLB for TCP port 80 +## 4. Add listener to NLB for TCP port 80 1. Select your newly created NLB and select the **Listeners** tab. @@ -166,7 +166,7 @@ After AWS creates the NLB, click **Close**. 6. Click **Save** in the top right of the screen. -# Health Check Paths for NGINX Ingress and Traefik Ingresses +## Health Check Paths for NGINX Ingress and Traefik Ingresses K3s and RKE Kubernetes clusters handle health checks differently because they use different Ingresses by default. diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md index 34098280ba5..a4af034aa2b 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md @@ -13,12 +13,13 @@ For systems without direct internet access, refer to the air gap installation in > > In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster. -# Prerequisites +## Prerequisites These instructions assume you have set up two nodes, a load balancer, a DNS record, and an external MySQL database as described in [this section.](../infrastructure-setup/ha-k3s-kubernetes-cluster.md) Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/) To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script. -# Installing Kubernetes + +## Installing Kubernetes ### 1. Install Kubernetes and Set up the K3s Server diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md index a825a493014..b5b07014fd0 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md @@ -16,7 +16,7 @@ For systems without direct internet access, refer to [Air Gap: Kubernetes instal > > In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster. -# Installing Kubernetes +## Installing Kubernetes ### Required CLI Tools diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md index abb77415021..e38776cd49a 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md @@ -6,14 +6,15 @@ _Tested on v2.5.6_ This section describes how to install a Kubernetes cluster according to the [best practices for the Rancher server environment.](../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#environment-for-kubernetes-installations) -# Prerequisites +## Prerequisites These instructions assume you have set up three nodes, a load balancer, and a DNS record, as described in [this section.](../infrastructure-setup/ha-rke2-kubernetes-cluster.md) Note that in order for RKE2 to work correctly with the load balancer, you need to set up two listeners: one for the supervisor on port 9345, and one for the Kubernetes API on port 6443. Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/) To specify the RKE2 version, use the INSTALL_RKE2_VERSION environment variable when running the RKE2 installation script. -# Installing Kubernetes + +## Installing Kubernetes ### 1. Install Kubernetes and Set up the RKE2 Server diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md index 55daa6129e1..4d50822545c 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md @@ -9,13 +9,13 @@ This diagram is applicable to Kubernetes clusters [launched with Rancher using R ![Cluster diagram](/img/clusterdiagram.svg)
Lines show the traffic flow between components. Colors are used purely for visual aid -# etcd +## etcd Nodes with the `etcd` role run etcd, which is a consistent and highly available key value store used as Kubernetes’ backing store for all cluster data. etcd replicates the data to each node. >**Note:** Nodes with the `etcd` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default. -# controlplane +## controlplane Nodes with the `controlplane` role run the Kubernetes master components (excluding `etcd`, as it's a separate role). See [Kubernetes: Master Components](https://kubernetes.io/docs/concepts/overview/components/#master-components) for a detailed list of components. @@ -33,10 +33,10 @@ The Kubernetes controller manager uses leader election using an endpoint in Kube The Kubernetes scheduler uses leader election using an endpoint in Kubernetes. One instance of the `kube-scheduler` will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive). -# worker +## worker Nodes with the `worker` role run the Kubernetes node components. See [Kubernetes: Node Components](https://kubernetes.io/docs/concepts/overview/components/#node-components) for a detailed list of components. -# References +## References * [Kubernetes: Node Components](https://kubernetes.io/docs/concepts/overview/components/#node-components) \ No newline at end of file diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere.md index 98132c74cbd..768cf02ac5a 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere.md @@ -8,7 +8,7 @@ Kubernetes is moving away from maintaining cloud providers in-tree. vSphere has This page covers how to install the Cloud Provider Interface (CPI) and Cloud Storage Interface (CSI) plugins after bringing up a cluster. -# Prerequisites +## Prerequisites The vSphere versions supported: @@ -19,7 +19,7 @@ The Kubernetes version must be 1.19 or higher. Using the vSphere out-of-tree cloud provider requires Linux nodes and is not supported on Windows. -# Installation +## Installation The Cloud Provider Interface (CPI) should be installed first before installing the Cloud Storage Interface (CSI). @@ -47,7 +47,7 @@ The Cloud Provider Interface (CPI) should be installed first before installing t 3. This chart creates a StorageClass with the `csi.vsphere.vmware.com` as the provisioner. Fill out the details for the StorageClass and launch the chart. -# Using the CSI driver for provisioning volumes +## Using the CSI driver for provisioning volumes The CSI chart by default creates a storageClass. diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree.md index c2f5c692fd7..5b4b6ca05b9 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree.md @@ -32,12 +32,12 @@ Upstream bug: https://github.com/kubernetes-sigs/vsphere-csi-driver/issues/628 Rancher issue tracking this bug: https://github.com/rancher/rancher/issues/31105 -# Prerequisites +## Prerequisites - vSphere CSI Migration requires vSphere 7.0u1. In order to be able to manage existing in-tree vSphere volumes, upgrade vSphere to 7.0u1. - The Kubernetes version must be 1.19 or higher. -# Migration +## Migration ### 1. Install the CPI plugin diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md index 6c3519baccf..f412993de56 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md @@ -9,7 +9,7 @@ First, you will set up your EC2 cloud credentials in Rancher. Then you will use Then you will create an EC2 cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool. -### Prerequisites +## Prerequisites - **AWS EC2 Access Key and Secret Key** that will be used to create the instances. See [Amazon Documentation: Creating Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) how to create an Access Key and Secret Key. - **IAM Policy created** to add to the user of the Access Key And Secret Key. See [Amazon Documentation: Creating IAM Policies (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) how to create an IAM policy. See our three example JSON policies below: @@ -18,7 +18,7 @@ Then you will create an EC2 cluster in Rancher, and when configuring the new clu - [Example IAM Policy to allow encrypted EBS volumes](#example-iam-policy-to-allow-encrypted-ebs-volumes) - **IAM Policy added as Permission** to the user. See [Amazon Documentation: Adding Permissions to a User (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) how to attach it to an user. -# Creating an EC2 Cluster +## Creating an EC2 Cluster The steps to create a cluster differ based on your Rancher version. @@ -70,6 +70,7 @@ You can access your cluster after its state is updated to **Active.** - `Default`, containing the `default` namespace - `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + ### 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: @@ -77,7 +78,7 @@ After creating your cluster, you can access it through the Rancher UI. As a best - **Access your cluster with the kubectl CLI:** Follow [these steps](../../../../advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-on-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. - **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps](../../../../advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. -# IAM Policies +## IAM Policies ### Example IAM Policy diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md index d9bb1804874..9994dbbbf72 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md @@ -22,7 +22,7 @@ For more information on configuring Azure node templates, refer to the [Azure no - [Preparation in Azure](#preparation-in-azure) - [Creating an Azure Cluster](#creating-an-azure-cluster) -# Preparation in Azure +## Preparation in Azure Before creating a node template in Rancher using a cloud infrastructure such as Azure, we must configure Rancher to allow the manipulation of resources in an Azure subscription. @@ -39,7 +39,7 @@ az ad sp create-for-rbac \ The creation of this service principal returns three pieces of identification information, *The application ID, also called the client ID*, *The client secret*, and *The tenant ID*. This information will be used when you create a node template for Azure. -# Creating an Azure Cluster +## Creating an Azure Cluster 1. [Create your cloud credentials](#1-create-your-cloud-credentials) diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md index f3e97c2abd2..ed981585969 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md @@ -14,7 +14,7 @@ Deployments use the Kubernetes registry secret to authenticate with a private Do Currently, deployments pull the private registry credentials automatically only if the workload is created in the Rancher UI and not when it is created via kubectl. -# Creating a Registry +## Creating a Registry >**Prerequisites:** You must have a [private registry](https://docs.docker.com/registry/deploying/) available to use. @@ -40,7 +40,7 @@ Currently, deployments pull the private registry credentials automatically only - You can view the secret in the Rancher UI from the **Resources > Registries** view. - Any workload that you create in the Rancher UI will have the credentials to access the registry if the workload is within the registry's scope. -# Using a Private Registry +## Using a Private Registry You can deploy a workload with an image from a private registry through the Rancher UI, or with `kubectl`. diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md index d08828a46a1..8473af95a8d 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md @@ -15,7 +15,7 @@ Ingress can be added for workloads to provide load balancing, SSL termination an **Result:** Your ingress is added to the project. The ingress begins enforcing your ingress rules. -# Ingress Rule Configuration +## Ingress Rule Configuration - [Automatically generate a sslip.io hostname](#automatically-generate-a-sslip-io-hostname) - [Specify a hostname to use](#specify-a-hostname-to-use) diff --git a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md index d5a4b0eca03..93eabd4ced0 100644 --- a/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md +++ b/versioned_docs/version-2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md @@ -10,7 +10,7 @@ When configuring a workload, you'll be able to choose which secrets to include. Mounted secrets will be updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/configuration/secret/#mounted-secrets-are-updated-automatically) -# Creating Secrets +## Creating Secrets When creating a secret, you can make it available for any deployment within a project, or you can limit it to a single namespace. @@ -36,7 +36,7 @@ When creating a secret, you can make it available for any deployment within a pr Mounted secrets will be updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/configuration/secret/#mounted-secrets-are-updated-automatically) -# What's Next? +## What's Next? Now that you have a secret added to the project or namespace, you can add it to a workload that you deploy. diff --git a/versioned_docs/version-2.5/pages-for-subheaders/air-gapped-helm-cli-install.md b/versioned_docs/version-2.5/pages-for-subheaders/air-gapped-helm-cli-install.md index 24e89c137c5..cd300d3ed8d 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/air-gapped-helm-cli-install.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/air-gapped-helm-cli-install.md @@ -12,14 +12,14 @@ Throughout the installation instructions, there will be _tabs_ for each installa > **Important:** If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation. -# Installation Outline +## 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) diff --git a/versioned_docs/version-2.5/pages-for-subheaders/configure-shibboleth-saml.md b/versioned_docs/version-2.5/pages-for-subheaders/configure-shibboleth-saml.md index aac5cd72b94..f756fa548a8 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/configure-shibboleth-saml.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/configure-shibboleth-saml.md @@ -10,8 +10,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/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.md) - -# Setting up Shibboleth in Rancher +## Setting up Shibboleth in Rancher ### Shibboleth Prerequisites > @@ -69,7 +68,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. @@ -91,6 +90,6 @@ Configure the settings for the OpenLDAP server, groups and users. For help filli 2. From the **Global** view, navigate to **Security** > **Authentication** 3. Select **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. diff --git a/versioned_docs/version-2.5/pages-for-subheaders/enable-experimental-features.md b/versioned_docs/version-2.5/pages-for-subheaders/enable-experimental-features.md index 0a46135b9b3..afdb4e68834 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/enable-experimental-features.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/enable-experimental-features.md @@ -24,7 +24,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](../reference-guides/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. @@ -84,8 +84,7 @@ docker run -d -p 80:80 -p 443:443 \ --features==true,=true ``` - -# 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**. @@ -101,7 +100,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 `/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. diff --git a/versioned_docs/version-2.5/pages-for-subheaders/gke-cluster-configuration.md b/versioned_docs/version-2.5/pages-for-subheaders/gke-cluster-configuration.md index 1b54868dbaa..1eb14ce6e3c 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/gke-cluster-configuration.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/gke-cluster-configuration.md @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem'; -# Changes in v2.5.8 +## Changes in v2.5.8 - We now support private GKE clusters. Note: This advanced setup can require more steps during the cluster provisioning process. For details, see [this section.](../reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.md) - [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc) are now supported. @@ -22,7 +22,7 @@ import TabItem from '@theme/TabItem'; - Node pools can be added while configuring the GKE cluster - When provisioning a GKE cluster, you can now use reusable cloud credentials instead of using a service account token directly to create the cluster. -# Cluster Location +## Cluster Location | Value | Description | |--------|--------------| @@ -31,7 +31,7 @@ import TabItem from '@theme/TabItem'; | Additional Zones | For zonal clusters, you can select additional zones to create a [multi-zone cluster.](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#multi-zonal_clusters) | | Region | For [regional clusters,](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#regional_clusters) you can select a region. For more information about available regions and zones, refer to [this section](https://cloud.google.com/compute/docs/regions-zones#available). The first part of each zone name is the name of the region. | -# Cluster Options +## Cluster Options ### Kubernetes Version @@ -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. @@ -240,7 +240,7 @@ You can apply labels to the node pool, which applies the labels to all nodes in Invalid labels can prevent upgrades or can prevent Rancher from starting. For details on label syntax requirements, see the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) -# Group Details +## Group Details In this section, enter details describing the node pool. @@ -306,13 +306,13 @@ The shorter the refresh window, the less likely any race conditions will occur, -# Labels & Annotations +## Labels & Annotations Add Kubernetes [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to the cluster. Invalid labels can prevent upgrades or can prevent Rancher from starting. For details on label syntax requirements, see the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) -# Kubernetes Options +## Kubernetes Options ### Location Type Zonal or Regional. With GKE, you can create a cluster tailored to the availability requirements of your workload and your budget. By default, a cluster's nodes run in a single compute zone. When multiple zones are selected, the cluster's nodes will span multiple compute zones, while the controlplane is located in a single zone. Regional clusters increase the availability of the controlplane as well. For help choosing the type of cluster availability, refer to [these docs.](https://cloud.google.com/kubernetes-engine/docs/best-practices/scalability#choosing_a_regional_or_zonal_control_plane) diff --git a/versioned_docs/version-2.5/pages-for-subheaders/install-cluster-autoscaler.md b/versioned_docs/version-2.5/pages-for-subheaders/install-cluster-autoscaler.md index 0dcca143dd7..cd0fac015c7 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/install-cluster-autoscaler.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/install-cluster-autoscaler.md @@ -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) diff --git a/versioned_docs/version-2.5/pages-for-subheaders/install-rancher-on-linux.md b/versioned_docs/version-2.5/pages-for-subheaders/install-rancher-on-linux.md index 69bef1d5a29..cb42c1cd49d 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/install-rancher-on-linux.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/install-rancher-on-linux.md @@ -17,7 +17,7 @@ RancherD is a single binary that first launches an RKE2 Kubernetes cluster, then - [Uninstall](#uninstall) - [RKE2 Documentation](#rke2-documentation) -# About RancherD Installs +## About RancherD Installs When RancherD is launched on a host, it first installs an RKE2 Kubernetes cluster, then deploys Rancher on the cluster as a Kubernetes daemonset. @@ -29,7 +29,7 @@ In Part I of these instructions, you'll learn how to launch RancherD on a single Part II explains how to convert the single-node Rancher installation into a high-availability installation. If the Rancher server will manage downstream Kubernetes clusters, it is important to follow these steps. A discussion of recommended architecture for highly available Rancher deployments can be found in our [Best Practices Guide.](./rancher-server.md) -# Prerequisites +## Prerequisites ### Node Requirements @@ -38,6 +38,7 @@ RancherD must be launched on a Linux OS. At this time, only OSes that leverage s The Linux node needs to fulfill the [installation requirements](installation-requirements.md) for hardware and networking. Docker is not required for RancherD installs. To install RancherD on SELinux Enforcing CentOS 8 nodes or RHEL 8 nodes, some [additional steps](installation-requirements.md#rancherd-on-selinux-enforcing-centos-8-or-rhel-8-nodes) are required. + ### Root Access Before running the installation commands, you will need to log in as root: @@ -71,7 +72,7 @@ The following should be taken into consideration when configuring the load balan - The Kubernetes API is served on port 6443, as normal. - In RancherD installs, the Rancher UI is served on port 8443 by default. (This is different from Helm chart installs, where port 443 is used by default.) -# Part I: Installing Rancher +## Part I: Installing Rancher ### 1. Set up Configurations @@ -170,7 +171,7 @@ This will give you the URL, username and password needed to log into Rancher. Fo If Rancher will only manage the local Kubernetes cluster, the installation is complete. -# Part II: High Availability +## Part II: High Availability If you plan to use the Rancher server to manage downstream Kubernetes clusters, Rancher needs to be highly available. In these steps, you will add more nodes to achieve a high-availability cluster. Since Rancher is running as a daemonset, it will automatically launch on the nodes you add. @@ -216,15 +217,15 @@ Repeat steps one and two for another Linux node, bringing the number of nodes in **Result:** Rancher is highly available and the installation is complete. -# Upgrades +## Upgrades For information on upgrades and rollbacks, refer to [this page.](../getting-started/installation-and-upgrade/other-installation-methods/install-rancher-on-linux/upgrade-rancherd.md) -# Configuration +## Configuration For information on how to configure certificates, node taints, Rancher Helm chart options, or RancherD CLI options, refer to the [configuration reference.](../reference-guides/cluster-configuration/rancher-server-configuration/rancherd-configuration-reference.md) -# Uninstall +## Uninstall To uninstall RancherD from your system, run the command below. This will shut down the process, remove the RancherD binary, and clean up files used by RancherD. @@ -232,6 +233,6 @@ To uninstall RancherD from your system, run the command below. This will shut do rancherd-uninstall.sh ``` -# RKE2 Documentation +## RKE2 Documentation For more information on RKE2, the Kubernetes distribution used to provision the underlying cluster, refer to the documentation [here.](https://docs.rke2.io/) \ No newline at end of file diff --git a/versioned_docs/version-2.5/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md b/versioned_docs/version-2.5/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md index 74e901527b1..4a85e435a38 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md @@ -8,7 +8,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) - [CLI Tools](#cli-tools) @@ -42,7 +42,7 @@ To deploy Rancher v2.5 on a hosted Kubernetes cluster such as EKS, GKE, or AKS, For an example of how to deploy an ingress on EKS, refer to [this section.](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md#5-install-an-ingress) -# Install the Rancher Helm Chart +## Install the Rancher Helm Chart Rancher is installed using the Helm package manager for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents. diff --git a/versioned_docs/version-2.5/pages-for-subheaders/installation-and-upgrade.md b/versioned_docs/version-2.5/pages-for-subheaders/installation-and-upgrade.md index ee43ee958e3..379a1cfb38a 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/installation-and-upgrade.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/installation-and-upgrade.md @@ -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, @@ -15,7 +15,7 @@ In this section, - **RKE2** is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector. - **RancherD** was an experimental tool for installing Rancher; a single binary that first launched an RKE2 Kubernetes cluster, then installed the Rancher server Helm chart on the cluster. It was available as part of Rancher v2.5.4 through v2.5.10 but is now deprecated and not available for recent releases. -# Changes to Installation in Rancher v2.5 +## Changes to Installation in Rancher v2.5 In Rancher v2.5, the Rancher management server can be installed on any Kubernetes cluster, including hosted clusters, such as Amazon EKS clusters. @@ -23,7 +23,7 @@ For Docker installations, a local Kubernetes cluster is installed in the single The `restrictedAdmin` Helm chart option was added. 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/advanced-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: @@ -79,10 +79,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. diff --git a/versioned_docs/version-2.5/pages-for-subheaders/installation-requirements.md b/versioned_docs/version-2.5/pages-for-subheaders/installation-requirements.md index 3225596b629..ec227c51773 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/installation-requirements.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/installation-requirements.md @@ -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 Chrome. -# Operating Systems and Container Runtime Requirements +## Operating Systems and Container Runtime Requirements Rancher should work with any modern Linux distribution. @@ -101,11 +101,11 @@ Docker is required for Helm chart installs, and it can be installed by following Docker is not required for RancherD installs. -# 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. @@ -168,7 +168,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. @@ -185,11 +185,11 @@ Currently, RKE2 deploys nginx-ingress as a deployment by default, so you will ne ### Ingress for EKS For an example of how to deploy an nginx-ingress-controller with a LoadBalancer service, refer to [this section.](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md#5-install-an-ingress) -# 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. @@ -201,7 +201,7 @@ 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. -# RancherD on SELinux Enforcing CentOS 8 or RHEL 8 Nodes +## RancherD on SELinux Enforcing CentOS 8 or RHEL 8 Nodes Before installing Rancher on SELinux Enforcing CentOS 8 nodes or RHEL 8 nodes, you must install `container-selinux` and `iptables`: diff --git a/versioned_docs/version-2.5/pages-for-subheaders/istio-setup-guide.md b/versioned_docs/version-2.5/pages-for-subheaders/istio-setup-guide.md index 4b763ee612b..15c31d9b8fc 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/istio-setup-guide.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/istio-setup-guide.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.](../explan 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 > **Quick Setup** If you don't need external traffic to reach Istio, and you just want to set up Istio for monitoring and tracing traffic within the cluster, skip the steps for [setting up the Istio gateway](../how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md) and [setting up Istio's components for traffic management.](../how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.md) diff --git a/versioned_docs/version-2.5/pages-for-subheaders/kubernetes-components.md b/versioned_docs/version-2.5/pages-for-subheaders/kubernetes-components.md index e93dd6bc8fd..b2271a50909 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/kubernetes-components.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/kubernetes-components.md @@ -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)
Lines show the traffic flow between components. Colors are used purely for visual aid \ No newline at end of file diff --git a/versioned_docs/version-2.5/pages-for-subheaders/monitoring-and-alerting.md b/versioned_docs/version-2.5/pages-for-subheaders/monitoring-and-alerting.md index d41356fa60c..162b7f675cf 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/monitoring-and-alerting.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/monitoring-and-alerting.md @@ -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.](../explanations/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.](../explanations/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.](../explanations/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) @@ -62,7 +62,7 @@ For information on configuring access to monitoring, see [this page.](../explana - [Debugging high memory usage](../how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md) - [Migrating from Monitoring V1 to V2](../how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5+-monitoring.md) -# Configuration +## Configuration ### Configuring Monitoring Resources in Rancher @@ -79,7 +79,7 @@ For information on configuring access to monitoring, see [this page.](../explana 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 _Available as of v2.5.8_ @@ -89,9 +89,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.](../explanations/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 setting `prometheus.prometheusSpec.resources.memory.limit` to 2500 Mi and `prometheus.prometheusSpec.resources.memory.request` to 1750 Mi. diff --git a/versioned_docs/version-2.5/pages-for-subheaders/monitoring-v2-configuration-guides.md b/versioned_docs/version-2.5/pages-for-subheaders/monitoring-v2-configuration-guides.md index 3324a7daa10..2b588bf2d15 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/monitoring-v2-configuration-guides.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/monitoring-v2-configuration-guides.md @@ -6,19 +6,18 @@ 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) >**Note:** On an idle cluster, Monitoring V2 has significantly higher CPU usage (up to 70%) as compared to Monitoring V1. To improve performance and achieve similar results as in Monitoring V1, turn off the Prometheus adapter. -# Prometheus Configuration +## Prometheus Configuration It is usually not necessary to directly edit the Prometheus custom resource. Instead, to configure Prometheus to scrape custom metrics, you will only need to create a new ServiceMonitor or PodMonitor to configure Prometheus to scrape additional metrics. - ### ServiceMonitor and PodMonitor Configuration For details, see [this page.](../reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md) @@ -27,7 +26,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. diff --git a/versioned_docs/version-2.5/pages-for-subheaders/pipelines.md b/versioned_docs/version-2.5/pages-for-subheaders/pipelines.md index 6d5a2432769..b74ad2e44b4 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/pipelines.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/pipelines.md @@ -24,11 +24,11 @@ After configuring Rancher and GitHub, you can deploy containers running Jenkins >**Note:** Rancher's pipeline provides a simple CI/CD experience, but it does not offer the full power and flexibility of and is not a replacement of enterprise-grade Jenkins or other CI tools your team uses. -# Concepts +## Concepts For an explanation of concepts and terminology used in this section, refer to [this page.](../reference-guides/pipelines/concepts.md) -# How Pipelines Work +## How Pipelines Work After enabling the ability to use pipelines in a project, you can configure multiple pipelines in each project. Each pipeline is unique and can be configured independently. @@ -54,7 +54,7 @@ When you configure a pipeline in one of your projects, a namespace specifically >**Note:** The managed Jenkins instance works statelessly, so don't worry about its data persistency. The Docker Registry and Minio instances use ephemeral volumes by default, which is fine for most use cases. If you want to make sure pipeline logs can survive node failures, you can configure persistent volumes for them, as described in [data persistency for pipeline components](../reference-guides/pipelines/configure-persistent-data.md). -# Roles-based Access Control for Pipelines +## Roles-based Access Control for Pipelines If you can access a project, you can enable repositories to start building pipelines. @@ -62,7 +62,7 @@ Only [administrators](../how-to-guides/advanced-user-guides/authentication-permi Project members can only configure repositories and pipelines. -# Setting up Pipelines +## Setting up Pipelines To set up pipelines, you will need to do the following: @@ -202,7 +202,7 @@ Now that repositories are added to your project, you can start configuring the p **Results:** Your pipeline is now configured and ready to be run. -# Pipeline Configuration Reference +## Pipeline Configuration Reference Refer to [this page](../reference-guides/pipelines/pipeline-configuration.md) for details on how to configure a pipeline to: @@ -220,8 +220,7 @@ The configuration reference also covers how to configure: - Environment variables - Secrets - -# Running your Pipelines +## Running your Pipelines Run your pipeline for the first time. From the project view in Rancher, go to **Resources > Pipelines.** Find your pipeline and select the vertical **⋮ > Run**. @@ -233,7 +232,7 @@ During this initial run, your pipeline is tested, and the following pipeline com This process takes several minutes. When it completes, you can view each pipeline component from the project **Workloads** tab. -# Triggering a Pipeline +## Triggering a Pipeline When a repository is enabled, a webhook is automatically set in the version control provider. By default, the pipeline is triggered by a **push** event to a repository, but you can modify the event(s) that trigger running the pipeline. diff --git a/versioned_docs/version-2.5/pages-for-subheaders/rancher-behind-an-http-proxy.md b/versioned_docs/version-2.5/pages-for-subheaders/rancher-behind-an-http-proxy.md index ef0d4acbe8e..59a7eec2dba 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/rancher-behind-an-http-proxy.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/rancher-behind-an-http-proxy.md @@ -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) diff --git a/versioned_docs/version-2.5/pages-for-subheaders/rancher-on-a-single-node-with-docker.md b/versioned_docs/version-2.5/pages-for-subheaders/rancher-on-a-single-node-with-docker.md index 44d64ff1149..91dad2642fc 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/rancher-on-a-single-node-with-docker.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/rancher-on-a-single-node-with-docker.md @@ -18,15 +18,15 @@ The Rancher backup operator can be used to migrate Rancher from the single Docke 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. diff --git a/versioned_docs/version-2.5/pages-for-subheaders/use-existing-nodes.md b/versioned_docs/version-2.5/pages-for-subheaders/use-existing-nodes.md index 18510024a25..d7c57476e94 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/use-existing-nodes.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/use-existing-nodes.md @@ -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 >**Want to use Windows hosts as Kubernetes workers?** > @@ -108,7 +108,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: diff --git a/versioned_docs/version-2.5/pages-for-subheaders/use-new-nodes-in-an-infra-provider.md b/versioned_docs/version-2.5/pages-for-subheaders/use-new-nodes-in-an-infra-provider.md index e46ffe7226f..d9ef8dd7242 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/use-new-nodes-in-an-infra-provider.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/use-new-nodes-in-an-infra-provider.md @@ -8,8 +8,7 @@ One benefit of installing Kubernetes on node pools hosted by an infrastructure p The available cloud providers to create a node template are decided based on active [node drivers](use-new-nodes-in-an-infra-provider.md#node-drivers). - -# Node Templates +## Node Templates A node template is the saved configuration for the parameters to use when provisioning nodes in a specific cloud provider. These nodes can be launched from the UI. Rancher uses [Docker Machine](https://docs.docker.com/machine/) to provision these nodes. The available cloud providers to create node templates are based on the active node drivers in Rancher. @@ -38,7 +37,7 @@ To access all node templates, an administrator will need to do the following: **Result:** All node templates are listed and grouped by owner. The templates can be edited or cloned by clicking the **⋮.** -# Node Pools +## Node Pools Using Rancher, you can create pools of nodes based on a [node template](#node-templates). @@ -102,7 +101,7 @@ You can disable node auto-replace from the Rancher UI with the following steps: **Result:** Node auto-replace is disabled for the node pool. -# Cloud Credentials +## Cloud Credentials Node templates can use cloud credentials to store credentials for launching nodes in your cloud provider, which has some benefits: @@ -114,6 +113,6 @@ Node templates can use cloud credentials to store credentials for launching node After cloud credentials are created, the user can start [managing the cloud credentials that they created](../reference-guides/user-settings/manage-cloud-credentials.md). -# Node Drivers +## Node Drivers If you don't find the node driver that you want to use, you can see if it is available in Rancher's built-in [node drivers and activate it](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#activating-deactivating-node-drivers), or you can [add your own custom node driver](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#adding-custom-node-drivers). diff --git a/versioned_docs/version-2.5/pages-for-subheaders/use-windows-clusters.md b/versioned_docs/version-2.5/pages-for-subheaders/use-windows-clusters.md index bf73c5ac1c6..8d4d76d5fa5 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/use-windows-clusters.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/use-windows-clusters.md @@ -20,8 +20,7 @@ For the full list of requirements, see [this section.](#requirements-for-windows For a summary of Kubernetes features supported in Windows, see the Kubernetes documentation on [supported functionality and limitations for using Kubernetes with Windows](https://kubernetes.io/docs/setup/production-environment/windows/intro-windows-in-kubernetes/#supported-functionality-and-limitations) or the [guide for scheduling Windows containers in Kubernetes](https://kubernetes.io/docs/setup/production-environment/windows/user-guide-windows-containers/). - -# Requirements for Windows Clusters +## Requirements for Windows Clusters The general node requirements for networking, operating systems, and Docker are the same as the node requirements for a [Rancher installation](installation-requirements.md). @@ -137,7 +136,7 @@ If you are using the GCE (Google Compute Engine) cloud provider, you must do the - Enable the GCE cloud provider in the `cluster.yml` by following [these steps.](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.md) - When provisioning the cluster in Rancher, choose **Custom cloud provider** as the cloud provider in the Rancher UI. -# Tutorial: How to Create a Cluster with Windows Support +## Tutorial: How to Create a Cluster with Windows Support This tutorial describes how to create a Rancher-provisioned cluster with the three nodes in the [recommended architecture.](#guide-architecture) @@ -145,8 +144,7 @@ When you provision a cluster with Rancher on existing nodes, you will add nodes To set up a cluster with support for Windows nodes and containers, you will need to complete the tasks below. - -# 1. Provision Hosts +## 1. Provision Hosts To begin provisioning a cluster on existing nodes with Windows support, prepare your hosts. @@ -170,7 +168,7 @@ You will provision three nodes: If your nodes are hosted by a **Cloud Provider** and you want automation support such as loadbalancers or persistent storage devices, your nodes have additional configuration requirements. For details, see [Selecting Cloud Providers.](./set-up-cloud-providers.md) -# 2. Create the Cluster on Existing Nodes +## 2. Create the Cluster on Existing Nodes The instructions for creating a Windows cluster on existing nodes are very similar to the general [instructions for creating a custom cluster](use-existing-nodes.md) with some Windows-specific requirements. @@ -185,7 +183,7 @@ The instructions for creating a Windows cluster on existing nodes are very simil > **Important:** For Host Gateway (L2bridge) networking, it's best to use the same Layer 2 network for all nodes. Otherwise, you need to configure the route rules for them. For details, refer to the [documentation on configuring cloud-hosted VM routes.](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.md#cloud-hosted-vm-routes-configuration) You will also need to [disable private IP address checks](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.md#disabling-private-ip-address-checks) if you are using Amazon EC2, Google GCE, or Azure VM. -# 3. Add Nodes to the Cluster +## 3. Add Nodes to the Cluster This section describes how to register your Linux and Worker nodes to your cluster. You will run a command on each node, which will install the Rancher agent and allow Rancher to manage each node. @@ -263,6 +261,6 @@ After creating your cluster, you can access it through the Rancher UI. As a best - **Access your cluster with the kubectl CLI:** Follow [these steps](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-on-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. - **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through the Rancher server. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. -# Configuration for Storage Classes in Azure +## Configuration for Storage Classes in Azure If you are using Azure VMs for your nodes, you can use [Azure files](https://docs.microsoft.com/en-us/azure/aks/azure-files-dynamic-pv) as a StorageClass for the cluster. For details, refer to [this section.](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.md) diff --git a/versioned_docs/version-2.5/pages-for-subheaders/vsphere-cloud-provider.md b/versioned_docs/version-2.5/pages-for-subheaders/vsphere-cloud-provider.md index 4f193f98fa2..3e22f1c3660 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/vsphere-cloud-provider.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/vsphere-cloud-provider.md @@ -4,11 +4,11 @@ title: Setting up the vSphere Cloud Provider In this section, you'll learn how to set up a vSphere cloud provider for a Rancher managed RKE Kubernetes cluster in vSphere. -# In-tree Cloud Provider +## In-tree Cloud Provider To use the in-tree vSphere cloud provider, you will need to use an RKE configuration option. For details, refer to [this page.](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-in-tree-vsphere.md) -# Out-of-tree Cloud Provider +## Out-of-tree Cloud Provider _Available as of v2.5+_ diff --git a/versioned_docs/version-2.5/pages-for-subheaders/vsphere.md b/versioned_docs/version-2.5/pages-for-subheaders/vsphere.md index c778357c6df..782786a1e77 100644 --- a/versioned_docs/version-2.5/pages-for-subheaders/vsphere.md +++ b/versioned_docs/version-2.5/pages-for-subheaders/vsphere.md @@ -15,7 +15,7 @@ A vSphere cluster may consist of multiple groups of VMs with distinct properties - [Provisioning Storage](#provisioning-storage) - [Enabling the vSphere Cloud Provider](#enabling-the-vsphere-cloud-provider) -# vSphere Enhancements in Rancher v2.3 +## vSphere Enhancements in Rancher v2.3 The vSphere node templates have been updated, allowing you to bring cloud operations on-premises with the following enhancements: diff --git a/versioned_docs/version-2.5/reference-guides/backup-restore-configuration/examples.md b/versioned_docs/version-2.5/reference-guides/backup-restore-configuration/examples.md index 712e062cda4..739f5a4d2fe 100644 --- a/versioned_docs/version-2.5/reference-guides/backup-restore-configuration/examples.md +++ b/versioned_docs/version-2.5/reference-guides/backup-restore-configuration/examples.md @@ -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: ``` -# Example EncryptionConfiguration +## Example EncryptionConfiguration ```yaml apiVersion: apiserver.config.k8s.io/v1 diff --git a/versioned_docs/version-2.5/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md b/versioned_docs/version-2.5/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md index 6d027542c4c..a95a03b3d8d 100644 --- a/versioned_docs/version-2.5/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md +++ b/versioned_docs/version-2.5/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md @@ -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 diff --git a/versioned_docs/version-2.5/reference-guides/cli-with-rancher/kubectl-utility.md b/versioned_docs/version-2.5/reference-guides/cli-with-rancher/kubectl-utility.md index 8de59255c26..0e1e6ad73dc 100644 --- a/versioned_docs/version-2.5/reference-guides/cli-with-rancher/kubectl-utility.md +++ b/versioned_docs/version-2.5/reference-guides/cli-with-rancher/kubectl-utility.md @@ -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. \ No newline at end of file diff --git a/versioned_docs/version-2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md b/versioned_docs/version-2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md index 0e5a6ab6463..d1aa27af2ef 100644 --- a/versioned_docs/version-2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md +++ b/versioned_docs/version-2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md @@ -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. diff --git a/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/rancherd-configuration-reference.md b/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/rancherd-configuration-reference.md index f50e315e647..292f52cd6f5 100644 --- a/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/rancherd-configuration-reference.md +++ b/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/rancherd-configuration-reference.md @@ -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: diff --git a/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md b/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md index d06281e1f2e..6e69a75231e 100644 --- a/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md +++ b/versioned_docs/version-2.5/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md @@ -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 **⋮ > 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`. diff --git a/versioned_docs/version-2.5/reference-guides/configure-openldap/openldap-config-reference.md b/versioned_docs/version-2.5/reference-guides/configure-openldap/openldap-config-reference.md index 9e0b5ce1ad8..2ffd181fa9c 100644 --- a/versioned_docs/version-2.5/reference-guides/configure-openldap/openldap-config-reference.md +++ b/versioned_docs/version-2.5/reference-guides/configure-openldap/openldap-config-reference.md @@ -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. diff --git a/versioned_docs/version-2.5/reference-guides/installation-references/helm-chart-options.md b/versioned_docs/version-2.5/reference-guides/installation-references/helm-chart-options.md index a9512322830..c591c18c6cf 100644 --- a/versioned_docs/version-2.5/reference-guides/installation-references/helm-chart-options.md +++ b/versioned_docs/version-2.5/reference-guides/installation-references/helm-chart-options.md @@ -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. diff --git a/versioned_docs/version-2.5/reference-guides/installation-references/tls-settings.md b/versioned_docs/version-2.5/reference-guides/installation-references/tls-settings.md index 807a8227b24..108b1b12b64 100644 --- a/versioned_docs/version-2.5/reference-guides/installation-references/tls-settings.md +++ b/versioned_docs/version-2.5/reference-guides/installation-references/tls-settings.md @@ -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: diff --git a/versioned_docs/version-2.5/reference-guides/rancher-cluster-tools.md b/versioned_docs/version-2.5/reference-guides/rancher-cluster-tools.md index b3560923a1b..25743e44b37 100644 --- a/versioned_docs/version-2.5/reference-guides/rancher-cluster-tools.md +++ b/versioned_docs/version-2.5/reference-guides/rancher-cluster-tools.md @@ -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. diff --git a/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/architecture-recommendations.md b/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/architecture-recommendations.md index ad036fe5ea9..372fe076825 100644 --- a/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/architecture-recommendations.md +++ b/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/architecture-recommendations.md @@ -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. diff --git a/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md b/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md index 854787dc4fe..aee16457d71 100644 --- a/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md +++ b/versioned_docs/version-2.5/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md @@ -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: diff --git a/versioned_docs/version-2.5/reference-guides/system-tools.md b/versioned_docs/version-2.5/reference-guides/system-tools.md index 96add4fc939..eae035fb601 100644 --- a/versioned_docs/version-2.5/reference-guides/system-tools.md +++ b/versioned_docs/version-2.5/reference-guides/system-tools.md @@ -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 , -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 , -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 , -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. diff --git a/versioned_docs/version-2.5/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md b/versioned_docs/version-2.5/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md index 6f45a7a5b86..3680d702ecb 100644 --- a/versioned_docs/version-2.5/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md +++ b/versioned_docs/version-2.5/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md @@ -4,7 +4,7 @@ title: Troubleshooting Controlplane Nodes This section applies to nodes with the `controlplane` role. -# Check if the Controlplane Containers are Running +## Check if the Controlplane Containers are Running There are three specific containers launched on nodes with the `controlplane` role: @@ -26,7 +26,7 @@ f3d287ca4549 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." bdf3898b8063 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." 3 hours ago Up 3 hours kube-controller-manager ``` -# Controlplane Container Logging +## Controlplane Container Logging > **Note:** If you added multiple nodes with the `controlplane` role, both `kube-controller-manager` and `kube-scheduler` use a leader election process to determine the leader. Only the current leader will log the performed actions. See [Kubernetes leader election](../other-troubleshooting-tips/kubernetes-resources.md#kubernetes-leader-election) how to retrieve the current leader. diff --git a/versioned_docs/version-2.5/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md b/versioned_docs/version-2.5/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md index d7cde4f794e..08d71c4c028 100644 --- a/versioned_docs/version-2.5/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md +++ b/versioned_docs/version-2.5/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md @@ -4,7 +4,7 @@ title: Troubleshooting nginx-proxy The `nginx-proxy` container is deployed on every node that does not have the `controlplane` role. It provides access to all the nodes with the `controlplane` role by dynamically generating the NGINX configuration based on available nodes with the `controlplane` role. -# Check if the Container is Running +## Check if the Container is Running The container is called `nginx-proxy` and should have status `Up`. The duration shown after `Up` is the time the container has been running. @@ -20,7 +20,7 @@ CONTAINER ID IMAGE COMMAND CREATED c3e933687c0e rancher/rke-tools:v0.1.15 "nginx-proxy CP_HO..." 3 hours ago Up 3 hours nginx-proxy ``` -# Check Generated NGINX Configuration +## Check Generated NGINX Configuration The generated configuration should include the IP addresses of the nodes with the `controlplane` role. The configuration can be checked using the following command: @@ -59,7 +59,7 @@ stream { } ``` -# nginx-proxy Container Logging +## nginx-proxy Container Logging The logging of the containers can contain information on what the problem could be. diff --git a/versioned_docs/version-2.5/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md b/versioned_docs/version-2.5/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md index 6d3a8bd7fcd..66c36f68bb7 100644 --- a/versioned_docs/version-2.5/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md +++ b/versioned_docs/version-2.5/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md @@ -4,7 +4,7 @@ title: Troubleshooting Worker Nodes and Generic Components This section applies to every node as it includes components that run on nodes with any role. -# Check if the Containers are Running +## Check if the Containers are Running There are two specific containers launched on nodes with the `worker` role: @@ -24,7 +24,7 @@ CONTAINER ID IMAGE COMMAND a30717ecfb55 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." 3 hours ago Up 3 hours kubelet ``` -# Container Logging +## Container Logging The logging of the containers can contain information on what the problem could be. diff --git a/versioned_docs/version-2.5/troubleshooting/other-troubleshooting-tips/kubernetes-resources.md b/versioned_docs/version-2.5/troubleshooting/other-troubleshooting-tips/kubernetes-resources.md index 849fba9dd57..ce5fd3c661c 100644 --- a/versioned_docs/version-2.5/troubleshooting/other-troubleshooting-tips/kubernetes-resources.md +++ b/versioned_docs/version-2.5/troubleshooting/other-troubleshooting-tips/kubernetes-resources.md @@ -6,7 +6,6 @@ The commands/steps listed on this page can be used to check the most important K Make sure you configured the correct kubeconfig (for example, `export KUBECONFIG=$PWD/kube_config_cluster.yml` for Rancher HA) or are using the embedded kubectl via the UI. - ## Nodes ### Get nodes @@ -128,7 +127,7 @@ Retrieve generated configuration in each pod: kubectl -n ingress-nginx get pods -l app=ingress-nginx --no-headers -o custom-columns=.NAME:.metadata.name | while read pod; do kubectl -n ingress-nginx exec $pod -- cat /etc/nginx/nginx.conf; done ``` -# Rancher agents +## Rancher agents Communication to the cluster (Kubernetes API via `cattle-cluster-agent`) and communication to the nodes (cluster provisioning via `cattle-node-agent`) is done through Rancher agents. From eaa89030f646ea801b4fe2a12cc4c0a182ba0939 Mon Sep 17 00:00:00 2001 From: Billy Tat Date: Fri, 28 Oct 2022 18:48:50 -0700 Subject: [PATCH 3/3] Convert h1 to h2 (2.0-2.4) --- .../cluster-alerts/default-alerts.md | 13 +++--- .../cluster-monitoring/expression.md | 18 ++++---- .../cluster-monitoring/prometheus.md | 10 ++--- .../istio/disable-istio.md | 6 +-- .../istio/rbac-for-istio.md | 8 ++-- .../istio/release-notes.md | 2 +- .../integrations-in-rancher/notifiers.md | 13 +++--- .../version-2.0-2.4/faq/upgrades-to-2x.md | 12 ++--- .../air-gap-helm2/prepare-nodes.md | 4 +- .../open-ports-with-firewalld.md | 4 +- .../istio-traffic-management-features.md | 2 +- .../upgrades/helm2.md | 4 +- .../port-requirements.md | 7 ++- .../install-rancher-ha.md | 12 ++--- .../publish-images.md | 4 +- .../upgrade-docker-installed-rancher.md | 23 +++++----- .../resources/add-tls-secrets.md | 4 +- .../resources/local-system-charts.md | 4 +- .../resources/update-rancher-certificate.md | 30 ++++++------- .../resources/upgrade-cert-manager.md | 2 +- .../upgrade-and-roll-back-kubernetes.md | 17 ++++--- .../getting-started/introduction/overview.md | 10 ++--- .../configure-google-oauth.md | 8 ++-- .../configure-rancher-for-ms-adfs.md | 2 +- .../creator-permissions.md | 2 +- .../global-permissions.md | 5 +-- .../cis-scan-guides/run-a-scan.md | 2 +- .../enable-istio-in-cluster.md | 4 +- .../generate-and-view-traffic.md | 4 +- .../istio-setup-guide/node-selectors.md | 4 +- .../istio-setup-guide/set-up-istio-gateway.md | 6 +-- .../manage-clusters/backing-up-etcd.md | 15 +++---- .../use-aws-ec2-auto-scaling-groups.md | 2 +- .../manage-clusters/nodes-and-node-pools.md | 19 ++++---- ...up-rancher-launched-kubernetes-clusters.md | 10 ++--- .../deploy-apps-across-clusters.md | 15 +++---- .../helm-charts-in-rancher/adding-catalogs.md | 10 ++--- .../helm-charts-in-rancher/catalog-config.md | 10 ++--- .../helm-charts-in-rancher/creating-apps.md | 8 ++-- .../helm-charts-in-rancher/globaldns.md | 22 +++++---- .../helm-charts-in-rancher/launching-apps.md | 6 +-- .../amazon-elb-load-balancer.md | 14 +++--- .../k3s-for-rancher.md | 5 ++- .../rke1-for-rancher.md | 2 +- .../roles-for-nodes-in-kubernetes.md | 8 ++-- .../import-existing-clusters.md | 10 ++--- .../create-a-digitalocean-cluster.md | 8 ++-- .../create-an-amazon-ec2-cluster.md | 6 +-- .../create-an-azure-cluster.md | 4 +- ...rovision-kubernetes-clusters-in-vsphere.md | 2 +- .../kubernetes-and-docker-registries.md | 4 +- .../add-ingresses.md | 2 +- .../kubernetes-resources-setup/secrets.md | 4 +- .../pages-for-subheaders/air-gap-helm2.md | 2 +- .../air-gapped-helm-cli-install.md | 4 +- .../pages-for-subheaders/cis-scans.md | 4 +- .../pages-for-subheaders/cluster-alerts.md | 30 ++++++------- .../pages-for-subheaders/cluster-logging.md | 9 ++-- .../cluster-monitoring.md | 8 ++-- .../configure-shibboleth-saml.md | 6 +-- .../enable-experimental-features.md | 6 +-- .../install-cluster-autoscaler.md | 2 +- ...install-upgrade-on-a-kubernetes-cluster.md | 4 +- .../installation-and-upgrade.md | 9 ++-- .../installation-requirements.md | 8 ++-- .../pages-for-subheaders/istio.md | 14 +++--- .../kubernetes-clusters-in-rancher-setup.md | 6 +-- .../kubernetes-components.md | 2 +- .../pages-for-subheaders/project-tools.md | 8 ++-- .../rancher-behind-an-http-proxy.md | 2 +- .../rancher-on-a-single-node-with-docker.md | 6 +-- .../pages-for-subheaders/upgrades.md | 16 +++---- .../use-existing-nodes.md | 4 +- .../use-new-nodes-in-an-infra-provider.md | 8 ++-- .../use-windows-clusters.md | 13 +++--- .../best-practices/deployment-strategies.md | 4 +- .../best-practices/management.md | 45 ++++++++++++++++--- .../cli-with-rancher/kubectl-utility.md | 2 +- .../rke1-cluster-configuration.md | 2 +- .../openldap-config-reference.md | 4 +- .../helm-chart-options.md | 2 +- .../installation-references/tls-settings.md | 7 ++- .../reference-guides/rancher-cluster-tools.md | 18 ++++---- .../architecture-recommendations.md | 12 ++--- .../rancher-project-tools/project-logging.md | 10 ++--- .../reference-guides/system-tools.md | 8 ++-- .../troubleshooting-controlplane-nodes.md | 4 +- .../troubleshooting-nginx-proxy.md | 6 +-- ...ing-worker-nodes-and-generic-components.md | 4 +- 89 files changed, 377 insertions(+), 354 deletions(-) diff --git a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-alerts/default-alerts.md b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-alerts/default-alerts.md index 0fa0661ea21..bcd9eab107e 100644 --- a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-alerts/default-alerts.md +++ b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-alerts/default-alerts.md @@ -6,7 +6,8 @@ When you create a cluster, some alert rules are predefined. These alerts notify Several of the alerts use Prometheus expressions as the metric that triggers the alert. For more information on how expressions work, you can refer to the Rancher [documentation about Prometheus expressions](../cluster-monitoring/expression.md) or the Prometheus [documentation about querying metrics](https://prometheus.io/docs/prometheus/latest/querying/basics/). -# Alerts for etcd +## Alerts for etcd + Etcd is the key-value store that contains the state of the Kubernetes cluster. Rancher provides default alerts if the built-in monitoring detects a potential problem with etcd. You don't have to enable monitoring to receive these alerts. A leader is the node that handles all client requests that need cluster consensus. For more information, you can refer to this [explanation of how etcd works.](https://rancher.com/blog/2019/2019-01-29-what-is-etcd/#how-does-etcd-work) @@ -20,8 +21,7 @@ The leader of the cluster can change in response to certain events. It is normal | Etcd is unavailable | A critical alert is triggered when etcd becomes unavailable. | | Etcd member has no leader | A critical alert is triggered when the etcd cluster does not have a leader for at least three minutes. | - -# Alerts for Kubernetes Components +## Alerts for Kubernetes Components Rancher provides alerts when core Kubernetes system components become unhealthy. Controllers update Kubernetes resources based on changes in etcd. The [controller manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/) monitors the cluster desired state through the Kubernetes API server and makes the necessary changes to the current state to reach the desired state. @@ -33,16 +33,16 @@ The [scheduler](https://kubernetes.io/docs/reference/command-line-tools-referenc | Controller Manager is unavailable | A critical warning is triggered when the cluster’s controller-manager becomes unavailable. | | Scheduler is unavailable | A critical warning is triggered when the cluster’s scheduler becomes unavailable. | +## Alerts for Events -# Alerts for Events Kubernetes events are objects that provide insight into what is happening inside a cluster, such as what decisions were made by the scheduler or why some pods were evicted from the node. In the Rancher UI, from the project view, you can see events for each workload. | Alert | Explanation | |-------|-------------| | Get warning deployment event | A warning alert is triggered when a warning event happens on a deployment. | +## Alerts for Nodes -# Alerts for Nodes Alerts can be triggered based on node metrics. Each computing resource in a Kubernetes cluster is called a node. Nodes can be either bare-metal servers or virtual machines. | Alert | Explanation | @@ -51,5 +51,6 @@ Alerts can be triggered based on node metrics. Each computing resource in a Kube | High node memory utilization | A warning alert is triggered if the node uses more than 80 percent of its available memory for at least three minutes. | | Node disk is running full within 24 hours | A critical alert is triggered if the disk space on the node is expected to run out in the next 24 hours based on the disk growth over the last 6 hours. | -# Project-level Alerts +## Project-level Alerts + When you enable monitoring for the project, some project-level alerts are provided. For details, refer to the [section on project-level alerts.](../../../reference-guides/rancher-project-tools/project-alerts.md) diff --git a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-monitoring/expression.md b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-monitoring/expression.md index a4bb296b62f..569e3222f17 100644 --- a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-monitoring/expression.md +++ b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-monitoring/expression.md @@ -8,8 +8,7 @@ The PromQL expressions in this doc can be used to configure [alerts.](../../../p For more information about querying Prometheus, refer to the official [Prometheus documentation.](https://prometheus.io/docs/prometheus/latest/querying/basics/) - -# Cluster Metrics +## Cluster Metrics ### Cluster CPU Utilization @@ -60,7 +59,7 @@ For more information about querying Prometheus, refer to the official [Prometheu | Detail |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
| | Summary |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
| -# Node Metrics +## Node Metrics ### Node CPU Utilization @@ -111,7 +110,7 @@ For more information about querying Prometheus, refer to the official [Prometheu | Detail |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
| | Summary |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
| -# Etcd Metrics +## Etcd Metrics ### Etcd Has a Leader @@ -181,7 +180,7 @@ For more information about querying Prometheus, refer to the official [Prometheu | Detail |
wal`histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le))`
db`histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le))`
| | Summary |
wal`sum(histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le)))`
db`sum(histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le)))`
| -# Kubernetes Components Metrics +## Kubernetes Components Metrics ### API Server Request Latency @@ -239,8 +238,7 @@ For more information about querying Prometheus, refer to the official [Prometheu | Detail | `topk(10, histogram_quantile(0.95,sum by (le, host, path)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))` | | Summary | `topk(10, histogram_quantile(0.95,sum by (le, host)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))` | -# Rancher Logging Metrics - +## Rancher Logging Metrics ### Fluentd Buffer Queue Rate @@ -270,7 +268,7 @@ For more information about querying Prometheus, refer to the official [Prometheu | Detail | `sum(rate(fluentd_output_status_num_records_total[5m])) by (instance)` | | Summary | `sum(rate(fluentd_output_status_num_records_total[5m]))` | -# Workload Metrics +## Workload Metrics ### Workload CPU Utilization @@ -307,7 +305,7 @@ For more information about querying Prometheus, refer to the official [Prometheu | Detail |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| | Summary |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| -# Pod Metrics +## Pod Metrics ### Pod CPU Utilization @@ -344,7 +342,7 @@ For more information about querying Prometheus, refer to the official [Prometheu | Detail |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)`
| | Summary |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| -# Container Metrics +## Container Metrics ### Container CPU Utilization diff --git a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-monitoring/prometheus.md b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-monitoring/prometheus.md index af9a782c160..62654f4f5c4 100644 --- a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-monitoring/prometheus.md +++ b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/cluster-monitoring/prometheus.md @@ -12,7 +12,7 @@ While configuring monitoring at either the [cluster level](../../../pages-for-su - [Persistent Storage](#persistent-storage) - [Remote Storage](#remote-storage) -# Basic Configuration +## Basic Configuration Option | Description -------|------------- @@ -27,7 +27,7 @@ Prometheus [Memory Limit](https://kubernetes.io/docs/concepts/configuration/mana Prometheus [Memory Reservation](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory) | Memory resource requests for the Prometheus pod. Selector | Ability to select the nodes in which Prometheus and Grafana pods are deployed to. To use this option, the nodes must have labels. -# Advanced Options +## Advanced Options Since monitoring is an [application](https://github.com/rancher/system-charts/tree/dev/charts/rancher-monitoring) from the [Rancher catalog](../../../pages-for-subheaders/helm-charts-in-rancher.md), it can be configured like any other catalog application, by passing in values to Helm. @@ -64,7 +64,7 @@ Some example key-value pairs are: | `prometheus.livenessProbe.timeoutSeconds` | 60 | | `prometheus.readinessProbe.timeoutSeconds` | 60 | -# Node Exporter +## Node Exporter The [node exporter](https://github.com/prometheus/node_exporter/blob/master/README.md) is a popular open source exporter, which exposes the metrics for hardware and \*NIX kernels OS. It is designed to monitor the host system. However, there are still issues with namespaces when running it in a container, mostly around filesystem mount spaces. In order to monitor actual network metrics for the container network, the node exporter must be deployed with the `hostNetwork` mode. @@ -72,7 +72,7 @@ When configuring Prometheus and enabling the node exporter, enter a host port in >**Warning:** In order for Prometheus to collect the metrics of the node exporter, after enabling cluster monitoring, you must open the Node Exporter Host Port in the host firewall rules to allow intranet access. By default, `9796` is used as that host port. -# Persistent Storage +## Persistent Storage >**Prerequisite:** Configure one or more StorageClasses to use as [persistent storage](../../../pages-for-subheaders/create-kubernetes-persistent-storage.md) for your Prometheus or Grafana pod. @@ -80,7 +80,7 @@ By default, when you enable Prometheus for either a cluster or project, all moni When enabling persistent storage for Prometheus or Grafana, specify the size of the persistent volume and select the StorageClass. -# Remote Storage +## Remote Storage >**Prerequisite:** Need a remote storage endpoint to be available. The possible list of integrations is available [here](https://prometheus.io/docs/operating/integrations/) diff --git a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/istio/disable-istio.md b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/istio/disable-istio.md index 7b53260c1f6..6baf169687a 100644 --- a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/istio/disable-istio.md +++ b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/istio/disable-istio.md @@ -4,7 +4,7 @@ title: Disabling Istio This section describes how to disable Istio in a cluster, namespace, or workload. -# Disable Istio in a Cluster +## Disable Istio in a Cluster To disable Istio, @@ -14,13 +14,13 @@ To disable Istio, **Result:** The `cluster-istio` application in the cluster's `system` project gets removed. The Istio sidecar cannot be deployed on any workloads in the cluster. -# Disable Istio in a Namespace +## Disable Istio in a Namespace 1. In the Rancher UI, go to the project that has the namespace where you want to disable Istio. 1. On the **Workloads** tab, you will see a list of namespaces and the workloads deployed in them. Go to the namespace where you want to disable and click the **⋮ > Disable Istio Auto Injection.** **Result:** When workloads are deployed in this namespace, they will not have the Istio sidecar. -# Remove the Istio Sidecar from a Workload +## Remove the Istio Sidecar from a Workload Disable Istio in the namespace, then redeploy the workloads with in it. They will be deployed without the Istio sidecar. \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/istio/rbac-for-istio.md b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/istio/rbac-for-istio.md index 85ab75e9f16..0fccf48ad80 100644 --- a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/istio/rbac-for-istio.md +++ b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/istio/rbac-for-istio.md @@ -4,7 +4,7 @@ title: Role-based Access Control This section describes the permissions required to access Istio features and how to configure access to the Kiali and Jaeger visualizations. -# Cluster-level Access +## Cluster-level Access By default, only cluster administrators can: @@ -12,7 +12,7 @@ By default, only cluster administrators can: - Configure resource allocations for Istio - View each UI for Prometheus, Grafana, Kiali, and Jaeger -# Project-level Access +## Project-level Access After Istio is enabled in a cluster, project owners and members have permission to: @@ -22,7 +22,7 @@ After Istio is enabled in a cluster, project owners and members have permission - View the Kiali and Jaeger visualizations if cluster administrators give access to project members - Configure Istio's resources (such as the gateway, destination rules, or virtual services) with `kubectl` (This does not apply to read-only project members) -# Access to Visualizations +## Access to Visualizations By default, the Kiali and Jaeger visualizations are restricted to the cluster owner because the information in them could be sensitive. @@ -40,7 +40,7 @@ To configure who has permission to access the Kiali and Jaeger UI, **Result:** The access levels for Kiali and Jaeger have been updated. -# Summary of Default Permissions for Istio Users +## Summary of Default Permissions for Istio Users | Permission | Cluster Administrators | Project Owners | Project Members | Read-only Project Members | |------------------------------------------|----------------|----------------|-----------------|---------------------------| diff --git a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/istio/release-notes.md b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/istio/release-notes.md index 9b819eb4500..cf631a81f7a 100644 --- a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/istio/release-notes.md +++ b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/istio/release-notes.md @@ -3,7 +3,7 @@ title: Release Notes --- -# Istio 1.5.8 +## Istio 1.5.8 ### Important note on 1.5.x versions diff --git a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/notifiers.md b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/notifiers.md index 721038ba487..a7fecf3f7d5 100644 --- a/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/notifiers.md +++ b/versioned_docs/version-2.0-2.4/explanations/integrations-in-rancher/notifiers.md @@ -15,11 +15,11 @@ Rancher integrates with a variety of popular IT services, including: - **Microsoft Teams**: (Available as of v2.4.6) Send alert notifications to Teams using a webhook. -# Roles-based Access Control for Notifiers +## Roles-based Access Control for Notifiers Notifiers are configured at the cluster level. This model ensures that only cluster owners need to configure notifiers, leaving project owners to simply configure alerts in the scope of their projects. You don't need to dispense privileges like SMTP server access or cloud account access. -# Adding Notifiers +## Adding Notifiers Set up a notifier so that you can begin configuring and sending alerts. @@ -31,7 +31,7 @@ Set up a notifier so that you can begin configuring and sending alerts. **Result:** Your notifier is added to Rancher. -# Configuration +## Configuration - [Slack](#slack) - [Email](#email) @@ -140,7 +140,7 @@ _Available as of v2.4.6_ **Validation:** Click **Test.** If the test is successful, the Teams notifier output is **MicrosoftTeams setting validated.** -# Managing Notifiers +## Managing Notifiers After you set up notifiers, you can manage them. From the **Global** view, open the cluster that you want to manage your notifiers. Select **Tools > Notifiers**. You can: @@ -148,7 +148,7 @@ After you set up notifiers, you can manage them. From the **Global** view, open - **Clone** them, to quickly setup slightly different notifiers. - **Delete** them when they're no longer necessary. -# Example Payload for a Webhook Alert Notifier +## Example Payload for a Webhook Alert Notifier ```json { @@ -184,7 +184,8 @@ After you set up notifiers, you can manage them. From the **Global** view, open } } ``` -# What's Next? + +## What's Next? After creating a notifier, set up alerts to receive notifications of Rancher system events. diff --git a/versioned_docs/version-2.0-2.4/faq/upgrades-to-2x.md b/versioned_docs/version-2.0-2.4/faq/upgrades-to-2x.md index 50190872188..dc343937e01 100644 --- a/versioned_docs/version-2.0-2.4/faq/upgrades-to-2x.md +++ b/versioned_docs/version-2.0-2.4/faq/upgrades-to-2x.md @@ -4,7 +4,7 @@ title: Questions about Upgrading to Rancher v2.x This page contains frequently asked questions about the changes between Rancher v1.x and v2.x, and how to upgrade from Rancher v1.x to v2.x. -# Kubernetes +## Kubernetes **What does it mean when you say Rancher v2.x is built on Kubernetes?** @@ -34,7 +34,7 @@ No. Unfortunately, the differences were enough such that we cannot support Ranc Absolutely. -# Cattle +## Cattle **How does Rancher v2.x affect Cattle?** @@ -46,7 +46,7 @@ Cattle will not supported in v2.x as Rancher has been re-architected to be based Yes. In the upcoming Rancher v2.1 release we will provide a tool to help translate existing Cattle workloads in Compose format to Kubernetes YAML format. You will then be able to deploy those workloads on the v2.x platform. -# Feature Changes +## Feature Changes **Can we still add our own infrastructure services, which had a separate view/filter in 1.6.x?** @@ -70,7 +70,7 @@ Yes. You can do so by leveraging Kubernetes' network policies. Yes. Definitely. -# Environments & Clusters +## Environments & Clusters **Can I still create templates for environments and clusters?** @@ -84,7 +84,7 @@ Kubernetes RKE Templates is on our roadmap for 2.x. Please refer to our Release Yes. We still provide you with the same way of executing our Rancher agents directly on hosts. -# Upgrading/Migrating +## Upgrading/Migrating **How would the migration from v1.x to v2.x work?** @@ -96,7 +96,7 @@ Due to the technical difficulty in transforming a Docker container into a pod ru At this time, we are still exploring this scenario and taking feedback. We anticipate that you will need to launch a new Rancher instance and then relaunch on v2.x. Once you've moved to v2.x, upgrades will be in place, as they are in v1.6. -# Support +## Support **Are you planning some long-term support releases for Rancher v1.6?** diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/prepare-nodes.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/prepare-nodes.md index b46ba8bc838..6a21fd67761 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/prepare-nodes.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/prepare-nodes.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; This section is about how to prepare your node(s) to install Rancher for your air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. There are _tabs_ for either a high availability (recommended) or a Docker installation. -# Prerequisites +## Prerequisites @@ -47,7 +47,7 @@ If you need help with creating a private registry, please refer to the [Docker d -# Set up Infrastructure +## Set up Infrastructure diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.md index f2b9c80842c..a3ffcb2a1a5 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.md @@ -33,7 +33,7 @@ sudo iptables --list This section describes how to use `firewalld` to apply the [firewall port rules](../../installation-requirements/port-requirements.md) for nodes in a high-availability Rancher server cluster. -# Prerequisite +## Prerequisite Install v7.x or later ofv`firewalld`: @@ -43,7 +43,7 @@ systemctl start firewalld systemctl enable firewalld ``` -# Applying Firewall Port Rules +## Applying Firewall Port Rules In the Rancher high-availability installation instructions, the Rancher server is set up on three nodes that have all three Kubernetes roles: etcd, controlplane, and worker. If your Rancher server nodes have all three roles, run the following commands on each node: diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.md index b57cbc7f360..572fe9dc0f9 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.md @@ -13,7 +13,7 @@ Environment Variable Key | Default Value | Status | Available as of `istio-virtual-service-ui` |`false` | Experimental | v2.3.0 `istio-virtual-service-ui` | `true` | GA | v2.3.2 -# About this Feature +## About this Feature A central advantage of Istio's traffic management features is that they allow dynamic request routing, which is useful for canary deployments, blue/green deployments, or A/B testing. diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.md index 132d6cc5489..61b699dfee0 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.md @@ -23,12 +23,12 @@ If you installed Rancher using the RKE Add-on yaml, follow the directions to [mi > - If you are upgrading Rancher from v2.x to v2.3+, and you are using external TLS termination, you will need to edit the cluster.yml to [enable using forwarded host headers.](../../../../reference-guides/installation-references/helm-chart-options.md#configuring-ingress-for-external-tls-when-using-nginx-v0-25) > - The upgrade instructions assume you are using Helm 3. For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) This [section](../../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.md) provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible. -# Prerequisites +## Prerequisites - **Review the [known upgrade issues](../../../../pages-for-subheaders/upgrades.md)** 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) - **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](../../other-installation-methods/air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to. -# Upgrade Outline +## Upgrade Outline Follow the steps to upgrade Rancher server: diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md index 70b699fdf78..f1eaa328a5a 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md @@ -9,7 +9,7 @@ import PortsImportedHosted from '@site/src/components/PortsImportedHosted' To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes. -# Rancher Nodes +## Rancher Nodes The following table lists the ports that need to be open to and from nodes that are running the Rancher server. @@ -127,7 +127,7 @@ The following tables break down the port requirements for Rancher nodes, for inb -# Downstream Kubernetes Cluster Nodes +## Downstream Kubernetes Cluster Nodes Downstream Kubernetes clusters run your apps and services. This section describes what ports need to be opened on the nodes in downstream clusters so that Rancher can communicate with them. @@ -191,8 +191,7 @@ The following table depicts the port requirements for [imported clusters](../../ - -# Other Port Considerations +## Other Port Considerations ### Commonly Used Ports diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md index fbe224fb464..34cd1043acc 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md @@ -20,7 +20,7 @@ This section describes installing Rancher in five parts: - [4. Install Rancher](#4-install-rancher) - [5. For Rancher versions before v2.3.0, Configure System Charts](#5-for-rancher-versions-before-v2-3-0-configure-system-charts) -# 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. @@ -51,7 +51,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. @@ -64,7 +64,7 @@ When Rancher is installed on an air gapped Kubernetes cluster, there are two rec | Rancher Generated Self-Signed Certificates | `ingress.tls.source=rancher` | Use certificates issued by Rancher's generated CA (self signed)
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).
This option must be passed when rendering the Rancher Helm template. | no | -# 3. Render the Rancher Helm Template +## 3. Render the Rancher Helm Template When setting up the Rancher Helm template, there are several options in the Helm chart that are designed specifically for air gap installations. @@ -180,7 +180,7 @@ Then refer to [Adding TLS Secrets](../../resources/add-tls-secrets.md) to publis -# 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. @@ -225,11 +225,11 @@ kubectl -n cattle-system apply -R -f ./rancher > **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. -# 5. For Rancher versions before v2.3.0, Configure System Charts +## 5. For Rancher versions before v2.3.0, Configure System Charts If you are installing Rancher versions before v2.3.0, you will not be able to use the packaged system charts. Since the Rancher system charts are hosted in Github, an air gapped installation will not be able to access these charts. Therefore, you must [configure the Rancher system charts](../../resources/local-system-charts.md). -# Additional Resources +## Additional Resources These resources could be helpful when installing Rancher: diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md index 68baa679e83..4242d7b6d24 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md @@ -112,7 +112,7 @@ _Available as of v2.3.0_ For Rancher servers that will provision Linux and Windows clusters, there are distinctive steps to populate your private registry for the Windows images and the Linux images. Since a Windows cluster is a mix of Linux and Windows nodes, the Linux images pushed into the private registry are manifests. -# Windows Steps +## Windows Steps The Windows images need to be collected and pushed from a Windows server workstation. @@ -191,7 +191,7 @@ The `rancher-windows-images.txt` is expected to be on the workstation in the sam ./rancher-load-images.ps1 --registry ``` -# Linux Steps +## Linux Steps The Linux images needs to be collected and pushed from a Linux host, but _must be done after_ populating the Windows images into the private registry. These step are different from the Linux only steps as the Linux images that are pushed will actually manifests that support Windows and Linux images. diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md index 631c53f6d31..5eb215ba38e 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md @@ -7,12 +7,12 @@ import TabItem from '@theme/TabItem'; The following instructions will guide you through upgrading a Rancher server that was installed with Docker. -# Prerequisites +## Prerequisites - **Review the [known upgrade issues](../../../../pages-for-subheaders/upgrades.md#known-upgrade-issues) 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 (``). @@ -24,7 +24,7 @@ docker stop In this command, `` 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: @@ -48,7 +48,7 @@ Write down or copy this information before starting the upgrade. You can obtain `` and `` 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 Outline During upgrade, you create a copy of the data from your current Rancher container and a backup in case something goes wrong. Then you deploy the new version of Rancher in a new container using your existing data. Follow the steps to upgrade Rancher server: @@ -59,7 +59,7 @@ During upgrade, you create a copy of the data from your current Rancher containe - [5. Verify the Upgrade](#5-verify-the-upgrade) - [6. Clean up your old Rancher server container](#6-clean-up-your-old-rancher-server-container) -# 1. Create a copy of the data from your Rancher server container +## 1. 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. @@ -75,7 +75,7 @@ During upgrade, you create a copy of the data from your current Rancher containe docker create --volumes-from --name rancher-data rancher/rancher: ``` -# 2. Create a backup tarball +## 2. Create a backup tarball 1. From the data container that you just created (rancher-data), create a backup tarball (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz). @@ -97,7 +97,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. @@ -109,7 +109,7 @@ Placeholder | Description docker pull rancher/rancher: ``` -# 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. @@ -338,7 +338,7 @@ docker run -d --volumes-from rancher-data \ **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. @@ -346,11 +346,10 @@ Log into Rancher. Confirm that the upgrade succeeded by checking the version dis > > See [Restoring Cluster Networking](../../install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md#restoring-cluster-networking). - -# 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). diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/add-tls-secrets.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/add-tls-secrets.md index 6c31231b0db..c649daf31b1 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/add-tls-secrets.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/add-tls-secrets.md @@ -19,7 +19,7 @@ kubectl -n cattle-system create secret tls tls-rancher-ingress \ > **Note:** If you want to replace the certificate, you can delete the `tls-rancher-ingress` secret using `kubectl -n cattle-system delete secret tls-rancher-ingress` and add a new one using the command shown above. If you are using a private CA signed certificate, replacing the certificate is only possible if the new certificate is signed by the same CA as the certificate currently in use. -# Using a Private CA Signed Certificate +## Using a Private CA Signed Certificate If you are using a private CA, Rancher requires a copy of the CA certificate which is used by the Rancher Agent to validate the connection to the server. @@ -32,6 +32,6 @@ kubectl -n cattle-system create secret generic tls-ca \ > **Note:** The configured `tls-ca` secret is retrieved when Rancher starts. On a running Rancher installation the updated CA will take effect after new Rancher pods are started. -# Updating a Private CA Certificate +## Updating a Private CA Certificate Follow the steps on [this page](update-rancher-certificate.md) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate. \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/local-system-charts.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/local-system-charts.md index f844065ed66..1ad0874fcdd 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/local-system-charts.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/local-system-charts.md @@ -9,13 +9,13 @@ The [System Charts](https://github.com/rancher/system-charts) repository contain In an air gapped installation of Rancher, you will need to configure Rancher to use a local copy of the system charts. This section describes how to use local system charts using a CLI flag in Rancher v2.3.0, and using a Git mirror for Rancher versions before v2.3.0. -# Using Local System Charts in Rancher v2.3.0 +## Using Local System Charts in Rancher v2.3.0 In Rancher v2.3.0, a local copy of `system-charts` has been packaged into the `rancher/rancher` container. To be able to use these features in an air gap install, you will need to run the Rancher install command with an extra environment variable, `CATTLE_SYSTEM_CATALOG=bundled`, which tells Rancher to use the local copy of the charts instead of attempting to fetch them from GitHub. Example commands for a Rancher installation with a bundled `system-charts` are included in the [air gap Docker installation](../advanced-options/advanced-use-cases/air-gap-helm2/install-rancher.md) instructions and the [air gap Kubernetes installation](../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md) instructions. -# Setting Up System Charts for Rancher Before v2.3.0 +## Setting Up System Charts for Rancher Before v2.3.0 ### A. Prepare System Charts diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md index 4951198d00f..a106fa84564 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md @@ -2,7 +2,7 @@ title: Updating the Rancher Certificate --- -# Updating a Private CA Certificate +## Updating a Private CA Certificate Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../../../pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate. @@ -15,7 +15,7 @@ A summary of the steps is as follows: The details of these instructions are below. -## 1. Create/update the certificate secret resource +### 1. Create/update the certificate secret resource First, concatenate the server certificate followed by any intermediate certificate(s) to a file named `tls.crt` and provide the corresponding certificate key in a file named `tls.key`. @@ -36,7 +36,7 @@ $ kubectl -n cattle-system create secret tls tls-rancher-ingress \ --dry-run --save-config -o yaml | kubectl apply -f - ``` -## 2. Create/update the CA certificate secret resource +### 2. Create/update the CA certificate secret resource If the new certificate was signed by a private CA, you will need to copy the corresponding root CA certificate into a file named `cacerts.pem` and create or update the `tls-ca secret` in the `cattle-system` namespace. If the certificate was signed by an intermediate CA, then the `cacerts.pem` must contain both the intermediate and root CA certificates (in this order). @@ -55,7 +55,7 @@ $ kubectl -n cattle-system create secret generic tls-ca \ --dry-run --save-config -o yaml | kubectl apply -f - ``` -## 3. Reconfigure the Rancher deployment +### 3. Reconfigure the Rancher deployment > Before proceeding, [generate an API token in the Rancher UI](../../../reference-guides/user-settings/api-keys.md#creating-an-api-key) (User > API & Keys). @@ -90,18 +90,18 @@ helm upgrade rancher rancher-stable/rancher \ When the upgrade is completed, navigate to `https:///v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier. -## 4. Reconfigure Rancher agents to trust the private CA +### 4. Reconfigure Rancher agents to trust the private CA This section covers three methods to reconfigure Rancher agents to trust the private CA. This step is required if either of the following is true: - Rancher was initially configured to use the Rancher self-signed certificate (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`) - The root CA certificate for the new custom certificate has changed -### Why is this step required? +#### Why is this step required? When Rancher is configured with a certificate signed by a private CA, the CA certificate chain is downloaded into Rancher agent containers. Agents compare the checksum of the downloaded certificate against the `CATTLE_CA_CHECKSUM` environment variable. This means that, when the private CA certificate is changed on Rancher server side, the environvment variable `CATTLE_CA_CHECKSUM` must be updated accordingly. -### Which method should I choose? +#### Which method should I choose? Method 1 is the easiest one but requires all clusters to be connected to Rancher after the certificates have been rotated. This is usually the case if the process is performed right after updating the Rancher deployment (Step 3). @@ -109,7 +109,7 @@ If the clusters have lost connection to Rancher but you have [Authorized Cluster Method 3 can be used as a fallback if method 1 and 2 are unfeasible. -### Method 1: Kubectl command +#### Method 1: Kubectl command For each cluster under Rancher management (including `local`) run the following command using the Kubeconfig file of the Rancher management cluster (RKE or K3S). @@ -120,7 +120,7 @@ kubectl patch clusters -p '{"status":{"agentImage":"dum This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate. -### Method 2: Manually update checksum +#### Method 2: Manually update checksum Manually patch the agent Kubernetes resources by updating the `CATTLE_CA_CHECKSUM` environment variable to the value matching the checksum of the new CA certificate. Generate the new checksum value like so: @@ -136,7 +136,7 @@ $ kubectl edit -n cattle-system ds/cattle-node-agent $ kubectl edit -n cattle-system deployment/cluster-agent ``` -### Method 3: Recreate Rancher agents +#### Method 3: Recreate Rancher agents With this method you are recreating the Rancher agents by running a set of commands on a controlplane node of each downstream cluster. @@ -145,11 +145,11 @@ First, generate the agent definitions as described here: https://gist.github.com Then, connect to a controlplane node of the downstream cluster via SSH, create a Kubeconfig and apply the definitions: https://gist.github.com/superseb/b14ed3b5535f621ad3d2aa6a4cd6443b -# Updating from a Private CA Certificate to a Common Certificate +## Updating from a Private CA Certificate to a Common Certificate >It is possible to perform the opposite procedure as shown above: you may change from a private certificate to a common, or non-private, certificate. The steps involved are outlined below. -## 1. Create/update the certificate secret resource +### 1. Create/update the certificate secret resource First, concatenate the server certificate followed by any intermediate certificate(s) to a file named `tls.crt` and provide the corresponding certificate key in a file named `tls.key`. @@ -170,7 +170,7 @@ $ kubectl -n cattle-system create secret tls tls-rancher-ingress \ --dry-run --save-config -o yaml | kubectl apply -f - ``` -## 2. Delete the CA certificate secret resource +### 2. Delete the CA certificate secret resource You will delete the `tls-ca secret` in the `cattle-system` namespace as it is no longer needed. You may also optionally save a copy of the `tls-ca secret` if desired. @@ -186,7 +186,7 @@ To delete the existing `tls-ca` secret: kubectl -n cattle-system delete secret tls-ca ``` -## 3. Reconfigure the Rancher deployment +### 3. Reconfigure the Rancher deployment > Before proceeding, [generate an API token in the Rancher UI](https://rancher.com/docs/rancher/v2.6/en/user-settings/api-keys/#creating-an-api-key) (User > API & Keys) and save the Bearer Token which you might need in step 4. @@ -228,6 +228,6 @@ On upgrade, you can either set privateCA=false ``` -## 4. Reconfigure Rancher agents for the non-private/common certificate +### 4. Reconfigure Rancher agents for the non-private/common certificate `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md index 953f7bbcd8d..6e3147b7d95 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md @@ -24,7 +24,7 @@ To address these changes, this guide will do two things: > For reinstalling Rancher with Helm, please check [Option B: Reinstalling Rancher Chart](../../../pages-for-subheaders/upgrades.md) under the upgrade Rancher section. -# Upgrade Cert-Manager +## Upgrade Cert-Manager The namespace used in these instructions depends on the namespace cert-manager is currently installed in. If it is in kube-system use that in the instructions below. You can verify by running `kubectl get pods --all-namespaces` and checking which namespace the cert-manager-\* pods are listed in. Do not change the namespace cert-manager is running in or this can cause issues. diff --git a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md index fdcd07955a1..b58cd8fb6d6 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md +++ b/versioned_docs/version-2.0-2.4/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md @@ -10,7 +10,7 @@ Following an upgrade to the latest version of Rancher, downstream Kubernetes clu Rancher calls RKE (Rancher Kubernetes Engine) as a library when provisioning and editing RKE clusters. For more information on configuring the upgrade strategy for RKE clusters, refer to the [RKE documentation](https://rancher.com/docs/rke/latest/en/). -# New Features +## New Features As of Rancher v2.3.0, the Kubernetes metadata feature was added, which allows Rancher to ship Kubernetes patch versions without upgrading Rancher. For details, refer to the [section on Kubernetes metadata.](upgrade-kubernetes-without-upgrading-rancher.md) @@ -19,18 +19,17 @@ As of Rancher v2.4.0, - The ability to import K3s Kubernetes clusters into Rancher was added, along with the ability to upgrade Kubernetes when editing those clusters. For details, refer to the [section on imported clusters.](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.md) - New advanced options are exposed in the Rancher UI for configuring the upgrade strategy of an RKE cluster: **Maximum Worker Nodes Unavailable** and **Drain nodes.** These options leverage the new cluster upgrade process of RKE v1.1.0, in which worker nodes are upgraded in batches, so that applications can remain available during cluster upgrades, under [certain conditions.](#maintaining-availability-for-applications-during-upgrades) -# Tested Kubernetes Versions +## Tested Kubernetes Versions Before a new version of Rancher is released, it's tested with the latest minor versions of Kubernetes to ensure compatibility. For details on which versions of Kubernetes were tested on each Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.4.17/) -# How Upgrades Work +## How Upgrades Work RKE v1.1.0 changed the way that clusters are upgraded. In this section of the [RKE documentation,](https://rancher.com/docs/rke/latest/en/upgrades/how-upgrades-work) you'll learn what happens when you edit or upgrade your RKE Kubernetes cluster. - -# Recommended Best Practice for Upgrades +## Recommended Best Practice for Upgrades @@ -57,7 +56,7 @@ The cluster cannot be downgraded to a previous Kubernetes version. -# Upgrading the Kubernetes Version +## Upgrading the Kubernetes Version > **Prerequisites:** > @@ -74,7 +73,7 @@ The cluster cannot be downgraded to a previous Kubernetes version. **Result:** Kubernetes begins upgrading for the cluster. -# Rolling Back +## Rolling Back _Available as of v2.4_ @@ -83,7 +82,7 @@ A cluster can be restored to a backup in which the previous Kubernetes version w - [Backing up a cluster](../../how-to-guides/advanced-user-guides/manage-clusters/backing-up-etcd.md#how-snapshots-work) - [Restoring a cluster from backup](../../how-to-guides/advanced-user-guides/manage-clusters/restoring-etcd.md#restoring-a-cluster-from-a-snapshot) -# Configuring the Upgrade Strategy +## Configuring the Upgrade Strategy As of RKE v1.1.0, additional upgrade options became available to give you more granular control over the upgrade process. These options can be used to maintain availability of your applications during a cluster upgrade if certain [conditions and requirements](https://rancher.com/docs/rke/latest/en/upgrades/maintaining-availability) are met. @@ -134,7 +133,7 @@ More advanced upgrade strategy configuration options are available by editing th For details, refer to [Configuring the Upgrade Strategy](https://rancher.com/docs/rke/latest/en/upgrades/configuring-strategy) in the RKE documentation. The section also includes an example `cluster.yml` for configuring the upgrade strategy. -# Troubleshooting +## Troubleshooting If a node doesn't come up after an upgrade, the `rke up` command errors out. diff --git a/versioned_docs/version-2.0-2.4/getting-started/introduction/overview.md b/versioned_docs/version-2.0-2.4/getting-started/introduction/overview.md index 22aa55bd068..35d048c189f 100644 --- a/versioned_docs/version-2.0-2.4/getting-started/introduction/overview.md +++ b/versioned_docs/version-2.0-2.4/getting-started/introduction/overview.md @@ -4,11 +4,11 @@ title: Overview Rancher is a container management platform built for organizations that deploy containers in production. Rancher makes it easy to run Kubernetes everywhere, meet IT requirements, and empower DevOps teams. -# Run Kubernetes Everywhere +## Run Kubernetes Everywhere Kubernetes has become the container orchestration standard. Most cloud and virtualization vendors now offer it as standard infrastructure. Rancher users have the choice of creating Kubernetes clusters with Rancher Kubernetes Engine (RKE) or cloud Kubernetes services, such as GKE, AKS, and EKS. Rancher users can also import and manage their existing Kubernetes clusters created using any Kubernetes distribution or installer. -# Meet IT requirements +## Meet IT requirements Rancher supports centralized authentication, access control, and monitoring for all Kubernetes clusters under its control. For example, you can: @@ -16,7 +16,7 @@ Rancher supports centralized authentication, access control, and monitoring for - Setup and enforce access control and security policies across all users, groups, projects, clusters, and clouds. - View the health and capacity of your Kubernetes clusters from a single-pane-of-glass. -# Empower DevOps Teams +## Empower DevOps Teams Rancher provides an intuitive user interface for DevOps engineers to manage their application workload. The user does not need to have in-depth knowledge of Kubernetes concepts to start using Rancher. Rancher catalog contains a set of useful DevOps tools. Rancher is certified with a wide selection of cloud native ecosystem products, including, for example, security tools, monitoring systems, container registries, and storage and networking drivers. @@ -24,7 +24,7 @@ The following figure illustrates the role Rancher plays in IT and DevOps organiz ![Platform](/img/platform.png) -# Features of the Rancher API Server +## Features of the Rancher API Server The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities: @@ -52,7 +52,7 @@ The Rancher API server is built on top of an embedded Kubernetes API server and - **Monitoring:** Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution. - **Alerting:** To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. -# Editing Downstream Clusters with Rancher +## Editing Downstream Clusters with Rancher The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters [provisioned by RKE](../../pages-for-subheaders/launch-kubernetes-with-rancher.md) have **Cluster Options** available for editing. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md index 31593ebfacd..45db48c0734 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.md @@ -10,7 +10,7 @@ Only admins of the G Suite domain have access to the Admin SDK. Therefore, only Within Rancher, only administrators or users with the **Manage Authentication** [global role](../../manage-role-based-access-control-rbac/global-permissions.md) can configure authentication. -# Prerequisites +## Prerequisites - You must have a [G Suite admin account](https://admin.google.com) configured. - G Suite requires a [top private domain FQDN](https://github.com/google/guava/wiki/InternetDomainNameExplained#public-suffixes-and-private-domains) as an authorized domain. One way to get an FQDN is by creating an A-record in Route53 for your Rancher server. You do not need to update your Rancher Server URL setting with that record, because there could be clusters using that URL. - You must have the Admin SDK API enabled for your G Suite domain. You can enable it using the steps on [this page.](https://support.google.com/a/answer/60757?hl=en) @@ -18,7 +18,8 @@ Within Rancher, only administrators or users with the **Manage Authentication** After the Admin SDK API is enabled, your G Suite domain's API screen should look like this: ![Enable Admin APIs](/img/Google-Enable-APIs-Screen.png) -# Setting up G Suite for OAuth with Rancher +## Setting up G Suite for OAuth with Rancher + Before you can set up Google OAuth in Rancher, you need to log in to your G Suite account and do the following: 1. [Add Rancher as an authorized domain in G Suite](#1-adding-rancher-as-an-authorized-domain) @@ -91,7 +92,8 @@ Using the Unique ID of the service account key, register it as an Oauth Client u **Result:** The service account is registered as an OAuth client in your G Suite account. -# Configuring Google OAuth in Rancher +## Configuring Google OAuth in Rancher + 1. Sign into Rancher using a local user assigned the [administrator](../../manage-role-based-access-control-rbac/global-permissions.md) role. This user is also called the local principal. 1. From the **Global** view, click **Security > Authentication** from the main menu. 1. Click **Google.** The instructions in the UI cover the steps to set up authentication with Google OAuth. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md index c890013cdb1..4d3adf6fd81 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md @@ -34,7 +34,7 @@ After you complete [Configuring Microsoft AD FS for Rancher](configure-ms-adfs-f **Result:** Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins. -# Configuration +## Configuration | Field | Description | |---------------------------|-----------------| diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md index dcadeb51b2f..95bb13ca4e8 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md @@ -6,7 +6,7 @@ Administrators have the permission to create RKE templates, and only administrat For more information on administrator permissions, refer to the [documentation on global permissions](../manage-role-based-access-control-rbac/global-permissions.md). -# Giving Users Permission to Create Templates +## Giving Users Permission to Create Templates Templates can only be created by users who have the global permission **Create RKE Templates.** diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md index e235d1df755..e34038b4cca 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md @@ -14,8 +14,7 @@ Global Permissions define user authorization outside the scope of any particular You cannot update or delete the built-in Global Permissions. - -# Global Permission Assignment +## Global Permission Assignment Global permissions for local users are assigned differently than users who log in to Rancher using external authentication. @@ -35,7 +34,7 @@ Permissions can be assigned to an individual user with [these steps.](#configuri As of Rancher v2.4.0, you can [assign a role to everyone in the group at the same time](#configuring-global-permissions-for-groups) if the external authentication provider supports groups. -# Custom Global Permissions +## Custom Global Permissions Using custom permissions is convenient for providing users with narrow or specialized access to Rancher. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md index b68cd59c32d..ad39adae73f 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md @@ -2,7 +2,7 @@ title: Run a Scan --- -# Run a Scan +## Run a Scan 1. From the cluster view in Rancher, click **Tools > CIS Scans.** 1. Click **Run Scan.** diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md index ab576bfd910..042356d3c03 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md @@ -6,7 +6,7 @@ This cluster uses the default Nginx controller to allow traffic into the cluster A Rancher [administrator](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) or [cluster owner](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles) can configure Rancher to deploy Istio in a Kubernetes cluster. -# Prerequisites +## Prerequisites This guide assumes you have already [installed Rancher,](../../../pages-for-subheaders/installation-and-upgrade.md) and you have already [provisioned a separate Kubernetes cluster](../../../pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md) on which you will install Istio. @@ -16,7 +16,7 @@ The workloads and services that you want to be controlled by Istio must meet [Is > If the cluster has a Pod Security Policy enabled there are [additional prerequisites steps](enable-istio-in-cluster-with-psp.md) -# Enable Istio in the Cluster +## Enable Istio in the Cluster 1. From the **Global** view, navigate to the **cluster** where you want to enable Istio. 1. Click **Tools > Istio.** diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md index 76103d2cc3e..9eb37070717 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md @@ -4,7 +4,7 @@ title: 7. Generate and View Traffic This section describes how to view the traffic that is being managed by Istio. -# The Kiali Traffic Graph +## The Kiali Traffic Graph Rancher integrates a Kiali graph into the Rancher UI. The Kiali graph provides a powerful way to visualize the topology of your Istio service mesh. It shows you which services communicate with each other. @@ -17,7 +17,7 @@ If you refresh the URL to the BookInfo app several times, you should be able to For additional tools and visualizations, you can go to each UI for Kiali, Jaeger, Grafana, and Prometheus by clicking their icons in the top right corner of the page. -# Viewing Traffic Metrics +## Viewing Traffic Metrics Istio’s monitoring features provide visibility into the performance of all your services. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/node-selectors.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/node-selectors.md index ff1d63a0e3b..6df5cde370e 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/node-selectors.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/node-selectors.md @@ -8,7 +8,7 @@ This section describes how use node selectors to configure Istio components to b In larger deployments, it is strongly advised that Istio's infrastructure be placed on dedicated nodes in the cluster by adding a node selector for each Istio component. -# Adding a Label to the Istio Node +## Adding a Label to the Istio Node First, add a label to the node where Istio components should be deployed. This label can have any key-value pair. For this example, we will use the key `istio` and the value `enabled`. @@ -21,7 +21,7 @@ First, add a label to the node where Istio components should be deployed. This l **Result:** A worker node has the label that will allow you to designate it for Istio components. -# Configuring Istio Components to Use the Labeled Node +## Configuring Istio Components to Use the Labeled Node Configure each Istio component to be deployed to the node with the Istio label. Each Istio component can be configured individually, but in this tutorial, we will configure all of the components to be scheduled on the same node for the sake of simplicity. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md index dabb8e75a81..3e8996509f1 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md @@ -16,7 +16,7 @@ For more information on the Istio gateway, refer to the [Istio documentation.](h ![In an Istio-enabled cluster, you can have two ingresses: the default Nginx ingress, and the default Istio controller.](/img/istio-ingress.svg) -# Enable the Istio Gateway +## Enable the Istio Gateway The ingress gateway is a Kubernetes service that will be deployed in your cluster. There is only one Istio gateway per cluster. @@ -29,7 +29,7 @@ The ingress gateway is a Kubernetes service that will be deployed in your cluste **Result:** The gateway is deployed, which allows Istio to receive traffic from outside the cluster. -# Add a Kubernetes Gateway that Points to the Istio Gateway +## Add a Kubernetes Gateway that Points to the Istio Gateway To allow traffic to reach Ingress, you will also need to provide a Kubernetes gateway resource in your YAML that points to Istio's implementation of the ingress gateway to the cluster. @@ -111,7 +111,7 @@ To get the ingress gateway URL and port, For help inspecting the Istio controller URL and ports, try the commands the [Istio documentation.](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports) -# Troubleshooting +## Troubleshooting The [official Istio documentation](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#troubleshooting) suggests `kubectl` commands to inspect the correct ingress host and ingress port for external requests. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/manage-clusters/backing-up-etcd.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/manage-clusters/backing-up-etcd.md index 50de7b1edf1..81995935d9b 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/manage-clusters/backing-up-etcd.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/manage-clusters/backing-up-etcd.md @@ -13,8 +13,7 @@ Rancher recommends configuring recurrent `etcd` snapshots for all production clu Snapshots of the etcd database are taken and saved either [locally onto the etcd nodes](#local-backup-target) or to a [S3 compatible target](#s3-backup-target). The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster. - -# How Snapshots Work +## How Snapshots Work @@ -122,7 +121,7 @@ On restore, the following process is used: -# Configuring Recurring Snapshots +## Configuring Recurring Snapshots Select how often you want recurring snapshots to be taken as well as how many snapshots to keep. The amount of time is measured in hours. With timestamped snapshots, the user has the ability to do a point-in-time recovery. @@ -139,7 +138,7 @@ In the **Advanced Cluster Options** section, there are several options available | Recurring etcd Snapshot Creation Period | Time in hours between recurring snapshots| 12 hours | | Recurring etcd Snapshot Retention Count | Number of snapshots to retain| 6 | -# One-Time Snapshots +## One-Time Snapshots In addition to recurring snapshots, you may want to take a "one-time" snapshot. For example, before upgrading the Kubernetes version of a cluster it's best to backup the state of the cluster to protect against upgrade failure. @@ -149,7 +148,7 @@ In addition to recurring snapshots, you may want to take a "one-time" snapshot. **Result:** Based on your [snapshot backup target](#snapshot-backup-targets), a one-time snapshot will be taken and saved in the selected backup target. -# Snapshot Backup Targets +## Snapshot Backup Targets Rancher supports two different backup targets: @@ -190,7 +189,7 @@ The `S3` backup target supports using IAM authentication to AWS API in addition To give an application access to S3, refer to the AWS documentation on [Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances.](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html) -# Viewing Available Snapshots +## Viewing Available Snapshots The list of all available snapshots for the cluster is available in the Rancher UI. @@ -198,7 +197,7 @@ The list of all available snapshots for the cluster is available in the Rancher 2. Click **Tools > Snapshots** from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created. -# Safe Timestamps +## Safe Timestamps _Available as of v2.3.0_ @@ -206,6 +205,6 @@ As of v2.2.6, snapshot files are timestamped to simplify processing the files us This option is not available directly in the UI, and is only available through the `Edit as Yaml` interface. -# Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0 +## Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0 If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must [edit the cluster](../../../pages-for-subheaders/cluster-configuration.md) and _save_ it, in order to enable the updated snapshot features. Even if you were already creating snapshots before v2.2.0, you must do this step as the older snapshots will not be available to use to [back up and restore etcd through the UI](restoring-etcd.md). diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md index 845235fbb0a..5969de42e03 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md @@ -507,7 +507,7 @@ kubectl -n kube-system apply -f cluster-autoscaler-deployment.yaml **Note:** Cluster-autoscaler deployment can also be set up using [manual configuration](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler/cloudprovider/aws#manual-configuration) -# Testing +## Testing At this point, we should have a cluster-scaler up and running in our Rancher custom cluster. Cluster-scale should manage `K8sWorkerAsg` ASG to scale up and down between 2 and 10 nodes, when one of the following conditions is true: diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.md b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.md index 54fc4609406..f9e116fe4ad 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.md @@ -9,8 +9,7 @@ After you launch a Kubernetes cluster in Rancher, you can manage individual node > If you want to manage the _cluster_ and not individual nodes, see [Editing Clusters](../../../pages-for-subheaders/cluster-configuration.md#editing-clusters-with-yaml). - -# Node Options Available for Each Cluster Creation Option +## Node Options Available for Each Cluster Creation Option The following table lists which node options are available for each type of cluster in Rancher. Click the links in the **Option** column for more detailed information about each feature. @@ -47,7 +46,7 @@ Options for managing nodes [hosted by a Kubernetes provider](../../../pages-for- Although you can deploy workloads to an [imported cluster](../../new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.md) using Rancher, you cannot manage individual cluster nodes. All management of imported cluster nodes must take place outside of Rancher. -# Managing and Editing Individual Nodes +## Managing and Editing Individual Nodes Editing a node lets you: @@ -58,11 +57,11 @@ Editing a node lets you: To manage individual nodes, browse to the cluster that you want to manage and then select **Nodes** from the main menu. You can open the options menu for a node by clicking its **⋮** icon (**...**). -# Viewing a Node in the Rancher API +## Viewing a Node in the Rancher API Select this option to view the node's [API endpoints](../../../pages-for-subheaders/about-the-api.md). -# Deleting a Node +## Deleting a Node Use **Delete** to remove defective nodes from the cloud provider. @@ -70,11 +69,11 @@ When you the delete a defective node, Rancher can automatically replace it with >**Tip:** If your cluster is hosted by an infrastructure provider, and you want to scale your cluster down instead of deleting a defective node, [scale down](#scaling-nodes) rather than delete. -# Scaling Nodes +## Scaling Nodes For nodes hosted by an infrastructure provider, you can scale the number of nodes in each [node pool](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md#node-pools) by using the scale controls. This option isn't available for other cluster types. -# SSH into a Node Hosted by an Infrastructure Provider +## SSH into a Node Hosted by an Infrastructure Provider For [nodes hosted by an infrastructure provider](../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md), you have the option of downloading its SSH key so that you can connect to it remotely from your desktop. @@ -94,11 +93,11 @@ For [nodes hosted by an infrastructure provider](../../../pages-for-subheaders/u ssh -i id_rsa root@ ``` -# Cordoning a Node +## Cordoning a Node _Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades, or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it. -# Draining a Node +## Draining a Node _Draining_ is the process of first cordoning the node, and then evicting all its pods. This feature is useful for performing node maintenance (like kernel upgrades or hardware maintenance). It prevents new pods from deploying to the node while redistributing existing pods so that users don't experience service interruption. @@ -169,7 +168,7 @@ Once drain successfully completes, the node will be in a state of `drained`. You >**Want to know more about cordon and drain?** See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/cluster-management/#maintenance-on-a-node). -# Labeling a Node to be Ignored by Rancher +## Labeling a Node to be Ignored by Rancher _Available as of 2.3.3_ diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md index 4a65f33cd8c..c667a8b803e 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md @@ -13,7 +13,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) -# Requirements +## Requirements ### RKE Version @@ -23,9 +23,7 @@ The commands for taking `etcd` snapshots are only available in RKE v0.1.7 and la You'll need the RKE config file that you used for Rancher install, `rancher-cluster.yml`. You created this file during your initial install. Place this file in same directory as the RKE binary. - -# Backup Outline - +## Backup Outline Backing up your high-availability Rancher cluster is process that involves completing multiple tasks. @@ -38,7 +36,7 @@ Backing up your high-availability Rancher cluster is process that involves compl After taking your snapshots, export them to a safe location that won't be affected if your cluster encounters issues. -# 1. Take Snapshots of the `etcd` Database +## 1. Take Snapshots of the `etcd` Database Take snapshots of your `etcd` database. You can use these snapshots later to recover from a disaster scenario. There are two ways to take snapshots: recurringly, or as a one-off. Each option is better suited to a specific use case. Read the short description below each link to know when to use each option. @@ -161,7 +159,7 @@ _Available as of RKE v0.2.0_ **Result:** RKE takes a snapshot of `etcd` running on each `etcd` node. The file is saved to `/opt/rke/etcd-snapshots`. It is also uploaded to the S3 compatible backend. -# 2. Back up Local Snapshots to a Safe Location +## 2. Back up Local Snapshots to a Safe Location > **Note:** If you are using RKE v0.2.0, you can enable saving the backups to a S3 compatible backend directly and skip this step. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/deploy-apps-across-clusters.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/deploy-apps-across-clusters.md index 6a185c3c7b4..91172ecf217 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/deploy-apps-across-clusters.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/deploy-apps-across-clusters.md @@ -25,14 +25,14 @@ After creating a multi-cluster application, you can program a [Global DNS entry] - [Multi-cluster application management](#multi-cluster-application-management) - [Deleting a multi-cluster application](#deleting-a-multi-cluster-application) -# Prerequisites +## Prerequisites To create a multi-cluster app in Rancher, you must have at least one of the following permissions: - A [project-member role](../advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles) in the target cluster(s), which gives you the ability to create, read, update, and delete the workloads - A [cluster owner role](../advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles) for the clusters(s) that include the target project(s) -# Launching a Multi-Cluster App +## Launching a Multi-Cluster App 1. From the **Global** view, choose **Apps** in the navigation bar. Click **Launch**. @@ -54,7 +54,7 @@ To create a multi-cluster app in Rancher, you must have at least one of the foll **Result**: Your application is deployed to your chosen namespace. You can view the application status from the project's: -# Multi-cluster App Configuration Options +## Multi-cluster App Configuration Options Rancher has divided the configuration option for the multi-cluster application into several sections. @@ -86,7 +86,7 @@ When launching the application, Rancher will confirm if you have these permissio > **Note:** There are some applications like _Grafana_ or _Datadog_ that require access to specific cluster-scoped resources. These applications will require the _Cluster_ role. If you find out later that the application requires cluster roles, the multi-cluster application can be upgraded to update the roles. -# Application Configuration Options +## Application Configuration Options For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of –set](https://helm.sh/docs/intro/using_helm/#the-format-and-limitations-of---set), as Rancher passes them as `--set` flags to Helm. @@ -130,7 +130,7 @@ The ability to use the same configuration to deploy the same application across - **Answer**: Enter the answer that you want to be used instead. -# Upgrading Multi-Cluster App Roles and Projects +## Upgrading Multi-Cluster App Roles and Projects - **Changing Roles on an existing Multi-Cluster app** The creator and any users added with the access-type "owner" to a multi-cluster app, can upgrade its Roles. When adding a new Role, we check if the user has that exact role in all current target projects. These checks allow the same relaxations for global admins, cluster owners and project-owners as described in the installation section for the field `Roles`. @@ -139,8 +139,7 @@ The creator and any users added with the access-type "owner" to a multi-cluster 1. The creator and any users added with access-type "owner" to a multi-cluster app, can add or remove its target projects. When adding a new project, we check if the caller of this request has all Roles defined on multi-cluster app, in the new projects they want to add. The roles checks are again relaxed for global admins, cluster-owners and project-owners. 2. We do not do these membership checks when removing target projects. This is because the caller's permissions could have with respect to the target project, or the project could have been deleted and hence the caller wants to remove it from targets list. - -# Multi-Cluster Application Management +## Multi-Cluster Application Management One of the benefits of using a multi-cluster application as opposed to multiple individual applications of the same type, is the ease of management. Multi-cluster applications can be cloned, upgraded or rolled back. @@ -152,7 +151,7 @@ One of the benefits of using a multi-cluster application as opposed to multiple * **Upgrade**: Upgrade your multi-cluster application to change some part of the configuration. When performing an upgrade for multi-cluster application, the [upgrade strategy](#upgrades) can be modified if you have the correct [access type](#members). * **Rollback**: Rollback your application to a specific version. If after an upgrade, there are issues for your multi-cluster application for one or more of your [targets](#targets), Rancher has stored up to 10 versions of the multi-cluster application. Rolling back a multi-cluster application reverts the application for **all** target clusters and projects, not just the targets(s) affected by the upgrade issue. -# Deleting a Multi-Cluster Application +## Deleting a Multi-Cluster Application 1. From the **Global** view, choose **Apps** in the navigation bar. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/adding-catalogs.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/adding-catalogs.md index df8f507b15c..5919a6bbcbc 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/adding-catalogs.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/adding-catalogs.md @@ -13,7 +13,7 @@ Custom catalogs can be added into Rancher at a global scope, cluster scope, or p - [Adding project level catalogs](#adding-project-level-catalogs) - [Custom catalog configuration reference](#custom-catalog-configuration-reference) -# Adding Catalog Repositories +## Adding Catalog Repositories Adding a catalog is as simple as adding a catalog name, a URL and a branch name. @@ -43,7 +43,7 @@ For more information on private Git/Helm catalogs, refer to the [custom catalog **Result:** Your catalog is added to Rancher. -# Adding Global Catalogs +## Adding Global Catalogs >**Prerequisites:** In order to manage the [built-in catalogs](./built-in.md) or manage global catalogs, you need _one_ of the following permissions: > @@ -57,7 +57,7 @@ For more information on private Git/Helm catalogs, refer to the [custom catalog **Result**: Your custom global catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [multi-cluster apps](../deploy-apps-across-clusters.md) or [applications in any project](./launching-apps.md) from this catalog. -# Adding Cluster Level Catalogs +## Adding Cluster Level Catalogs _Available as of v2.2.0_ @@ -75,7 +75,7 @@ _Available as of v2.2.0_ **Result**: Your custom cluster catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [applications in any project in that cluster](../../../pages-for-subheaders/helm-charts-in-rancher.md) from this catalog. -# Adding Project Level Catalogs +## Adding Project Level Catalogs _Available as of v2.2.0_ @@ -94,6 +94,6 @@ _Available as of v2.2.0_ **Result**: Your custom project catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [applications in that project](../../../pages-for-subheaders/helm-charts-in-rancher.md) from this catalog. -# Custom Catalog Configuration Reference +## Custom Catalog Configuration Reference Refer to [this page](./catalog-config.md) more information on configuring custom catalogs. \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/catalog-config.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/catalog-config.md index 5b70a79e345..e82cbf7dad3 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/catalog-config.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/catalog-config.md @@ -12,18 +12,18 @@ Any user can create custom catalogs to add into Rancher. Besides the content of - [Using Username and Password](#using-username-and-password) - [Using an OAuth token](#using-an-oauth-token) -# Types of Repositories +## Types of Repositories Rancher supports adding in different types of repositories as a catalog: * Custom Git Repository * Custom Helm Chart Repository -# Custom Git Repository +## Custom Git Repository The Git URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will default to use the `master` branch. Whenever you add a catalog to Rancher, it will be available almost immediately. -# Custom Helm Chart Repository +## Custom Helm Chart Repository A Helm chart repository is an HTTP server that contains one or more packaged charts. Any HTTP server that can serve YAML files and tar files and can answer GET requests can be used as a repository server. @@ -31,7 +31,7 @@ Helm comes with a built-in package server for developer testing (`helm serve`). In Rancher, you can add the custom Helm chart repository with only a catalog name and the URL address of the chart repository. -# Catalog Fields +## Catalog Fields When [adding your catalog](./adding-catalogs.md) to Rancher, you'll provide the following information: @@ -46,7 +46,7 @@ When [adding your catalog](./adding-catalogs.md) to Rancher, you'll provide the | Branch | For a Git repository, the branch name. Default: `master`. For a Helm Chart repository, this field is ignored. | | Helm version | The Helm version that will be used to deploy all of the charts in the catalog. This field cannot be changed later. For more information, refer to the [section on Helm versions.](../../../pages-for-subheaders/helm-charts-in-rancher.md#catalog-helm-deployment-versions) | -# Private Repositories +## Private Repositories _Available as of v2.2.0_ diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/creating-apps.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/creating-apps.md index cf9ef65a5b9..877de7b0157 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/creating-apps.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/creating-apps.md @@ -7,7 +7,7 @@ Rancher's catalog service requires any custom catalogs to be structured in a spe > For a complete walkthrough of developing charts, see the [Chart Template Developer's Guide](https://helm.sh/docs/chart_template_guide/) in the official Helm documentation. -# Chart Types +## Chart Types Rancher supports two different types of charts: Helm charts and Rancher charts. @@ -27,7 +27,7 @@ Advantages of Rancher charts include: - **Streamlined application launch:** Rancher charts add simplified chart descriptions and configuration forms to make catalog application deployment easy. Rancher users need not read through the entire list of Helm variables to understand how to launch an application. - **Application resource management:** Rancher tracks all the resources created by a specific application. Users can easily navigate to and troubleshoot on a page listing all the workload objects used to power an application. -# Chart Directory Structure +## Chart Directory Structure The following table demonstrates the directory structure for a Rancher Chart. The `charts` directory is the top level directory under the repository base. Adding the repository to Rancher will expose all charts contained within it. This information is helpful when customizing charts for a custom catalog. The `questions.yaml`, `README.md`, and `requirements.yml` files are specific to Rancher charts, but are optional for chart customization. @@ -45,7 +45,7 @@ The following table demonstrates the directory structure for a Rancher Chart. Th │ │ │ ├── templates/ # Directory containing templates that, when combined with values.yml, generates Kubernetes YAML. ``` -# Additional Files for Rancher Charts +## Additional Files for Rancher Charts Before you create your own custom catalog, you should have a basic understanding about how a Rancher chart differs from a native Helm chart. Rancher charts differ slightly from Helm charts in their directory structures. Rancher charts include two files that Helm charts do not. @@ -110,6 +110,6 @@ This reference contains variables that you can use in `questions.yml` nested und >**Note:** `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported. -# Tutorial: Example Custom Chart Creation +## Tutorial: Example Custom Chart Creation For a tutorial on adding a custom Helm chart to a custom catalog, refer to [this page.](./tutorial.md) diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.md index 3e396621264..8aace5af93a 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.md @@ -21,7 +21,7 @@ Rancher's Global DNS feature provides a way to program an external DNS provider - [AliDNS](#alidns) - [Adding Annotations to Ingresses to program the External DNS](#adding-annotations-to-ingresses-to-program-the-external-dns) -# Global DNS Providers +## Global DNS Providers Before adding in Global DNS entries, you will need to configure access to an external provider. @@ -33,29 +33,29 @@ The following table lists the first version of Rancher each provider debuted. | [CloudFlare](https://www.cloudflare.com/dns/) | v2.2.0 | | [AliDNS](https://www.alibabacloud.com/product/dns) | v2.2.0 | -# Global DNS Entries +## Global DNS Entries For each application that you want to route traffic to, you will need to create a Global DNS Entry. This entry will use a fully qualified domain name (a.k.a FQDN) from a global DNS provider to target applications. The applications can either resolve to a single [multi-cluster application](../deploy-apps-across-clusters.md) or to specific projects. You must [add specific annotation labels](#adding-annotations-to-ingresses-to-program-the-external-dns) to the ingresses in order for traffic to be routed correctly to the applications. Without this annotation, the programming for the DNS entry will not work. -# Permissions for Global DNS Providers and Entries +## Permissions for Global DNS Providers and Entries By default, only [global administrators](../../advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) and the creator of the Global DNS provider or Global DNS entry have access to use, edit and delete them. When creating the provider or entry, the creator can add additional users in order for those users to access and manage them. By default, these members will get `Owner` role to manage them. -# Setting up Global DNS for Applications +## Setting up Global DNS for Applications 1. From the **Global View**, select **Tools > Global DNS Providers**. 1. To add a provider, choose from the available provider options and configure the Global DNS Provider with necessary credentials and an optional domain. For help, see [DNS Provider Configuration.](#dns-provider-configuration) 1. (Optional) Add additional users so they could use the provider when creating Global DNS entries as well as manage the Global DNS provider. 1. (Optional) Pass any custom values in the Additional Options section. -# Adding a Global DNS Entry +## Adding a Global DNS Entry 1. From the **Global View**, select **Tools > Global DNS Entries**. 1. Click on **Add DNS Entry**. 1. Fill out the form. For help, refer to [Global DNS Entry Configuration.](#global-dns-entry-configuration) 1. Click **Create.** -# Editing a Global DNS Provider +## Editing a Global DNS Provider The [global administrators](../../advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md), creator of the Global DNS provider and any users added as `members` to a Global DNS provider, have _owner_ access to that provider. Any members can edit the following fields: @@ -68,7 +68,7 @@ The [global administrators](../../advanced-user-guides/authentication-permission 1. For the Global DNS provider that you want to edit, click the **⋮ > Edit**. -# Editing a Global DNS Entry +## Editing a Global DNS Entry The [global administrators](../../advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md), creator of the Global DNS entry and any users added as `members` to a Global DNS entry, have _owner_ access to that DNS entry. Any members can edit the following fields: @@ -86,8 +86,7 @@ Permission checks are relaxed for removing target projects in order to support s 1. For the Global DNS entry that you want to edit, click the **⋮ > Edit**. - -# Global DNS Entry Configuration +## Global DNS Entry Configuration | Field | Description | |----------|--------------------| @@ -98,7 +97,7 @@ Permission checks are relaxed for removing target projects in order to support s | DNS TTL | Configure the DNS time to live value in seconds. By default, it will be 300 seconds. | | Member Access | Search for any users that you want to have the ability to manage this Global DNS entry. | -# DNS Provider Configuration +## DNS Provider Configuration ### Route53 @@ -114,7 +113,6 @@ Permission checks are relaxed for removing target projects in order to support s | Secret Key | Enter the AWS **Secret Key**. | | Member Access | Under **Member Access**, search for any users that you want to have the ability to use this provider. By adding this user, they will also be able to manage the Global DNS Provider entry. | - ### CloudFlare | Field | Explanation | @@ -141,7 +139,7 @@ Permission checks are relaxed for removing target projects in order to support s | Secret Key | Enter the **Secret Key**. | | Member Access | Search for any users that you want to have the ability to use this provider. By adding this user, they will also be able to manage the Global DNS Provider entry. | -# Adding Annotations to Ingresses to program the External DNS +## Adding Annotations to Ingresses to program the External DNS In order for Global DNS entries to be programmed, you will need to add a specific annotation on an ingress in your application or target project. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/launching-apps.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/launching-apps.md index 1517c1ebd16..28be363ea5e 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/launching-apps.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/launching-apps.md @@ -14,7 +14,7 @@ If your application is using ingresses, you can program the ingress hostname to - [Launching a catalog app](#launching-a-catalog-app) - [Configuration options](#configuration-options) -# Prerequisites +## Prerequisites When Rancher deploys a catalog app, it launches an ephemeral instance of a Helm service account that has the permissions of the user deploying the catalog app. Therefore, a user cannot gain more access to the cluster through Helm or a catalog application than they otherwise would have. @@ -25,7 +25,7 @@ To launch an app from a catalog in Rancher, you must have at least one of the fo Before launching an app, you'll need to either [enable a built-in global catalog](./built-in.md) or [add your own custom catalog.](./adding-catalogs.md) -# Launching a Catalog App +## Launching a Catalog App 1. From the **Global** view, open the project that you want to deploy an app to. @@ -50,7 +50,7 @@ Before launching an app, you'll need to either [enable a built-in global catalog **Result**: Your application is deployed to your chosen namespace. You can view the application status from the project's **Workloads** view or **Apps** view. In versions before v2.2.0, this is the **Catalog Apps** view. -# Configuration Options +## Configuration Options For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of –set](https://helm.sh/docs/intro/using_helm/#the-format-and-limitations-of---set), as Rancher passes them as `--set` flags to Helm. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md index daf5fd980be..a9fdbbed9a6 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md @@ -10,7 +10,7 @@ This tutorial is about one possible way to set up your load balancer, not the on Rancher only supports using the Amazon NLB when terminating traffic in `tcp` mode for port 443 rather than `tls` mode. This is due to the fact that the NLB does not inject the correct headers into requests when terminated at the NLB. This means that if you want to use certificates managed by the Amazon Certificate Manager (ACM), you should use an ALB. -# Setting up the Load Balancer +## Setting up the Load Balancer Configuring an Amazon NLB is a multistage process: @@ -19,11 +19,11 @@ Configuring an Amazon NLB is a multistage process: 3. [Create Your NLB](#3-create-your-nlb) 4. [Add listener to NLB for TCP port 80](#4-add-listener-to-nlb-for-tcp-port-80) -# Requirements +## Requirements These instructions assume you have already created Linux instances in EC2. The load balancer will direct traffic to these nodes. -# 1. Create Target Groups +## 1. Create Target Groups Begin by creating two target groups for the **TCP** protocol, one with TCP port 443 and one regarding TCP port 80 (providing redirect to TCP port 443). You'll add your Linux nodes to these groups. @@ -86,7 +86,7 @@ Health check settings: | Timeout | `6 seconds` | | Interval | `10 seconds` | -# 2. Register Targets +## 2. Register Targets Next, add your Linux nodes to both target groups. @@ -110,7 +110,7 @@ When the instances are added, click **Save** on the bottom right of the screen. Repeat those steps, replacing **rancher-tcp-443** with **rancher-tcp-80**. The same instances need to be added as targets to this target group. -# 3. Create Your NLB +## 3. Create Your NLB Use Amazon's Wizard to create a Network Load Balancer. As part of this process, you'll add the target groups you created in [1. Create Target Groups](#1-create-target-groups). @@ -152,7 +152,7 @@ Look over the load balancer details and click **Create** when you're satisfied. After AWS creates the NLB, click **Close**. -# 4. Add listener to NLB for TCP port 80 +## 4. Add listener to NLB for TCP port 80 1. Select your newly created NLB and select the **Listeners** tab. @@ -166,7 +166,7 @@ After AWS creates the NLB, click **Close**. 6. Click **Save** in the top right of the screen. -# Health Check Paths for NGINX Ingress and Traefik Ingresses +## Health Check Paths for NGINX Ingress and Traefik Ingresses K3s and RKE Kubernetes clusters handle health checks differently because they use different Ingresses by default. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md index 34098280ba5..a4af034aa2b 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md @@ -13,12 +13,13 @@ For systems without direct internet access, refer to the air gap installation in > > In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster. -# Prerequisites +## Prerequisites These instructions assume you have set up two nodes, a load balancer, a DNS record, and an external MySQL database as described in [this section.](../infrastructure-setup/ha-k3s-kubernetes-cluster.md) Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/) To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script. -# Installing Kubernetes + +## Installing Kubernetes ### 1. Install Kubernetes and Set up the K3s Server diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md index 75fab19826f..ae8da6d6333 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md @@ -20,7 +20,7 @@ For systems without direct internet access, refer to [Air Gap: Kubernetes instal > > In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster. -# Installing Kubernetes +## Installing Kubernetes ### Required CLI Tools diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md index 55daa6129e1..4d50822545c 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md @@ -9,13 +9,13 @@ This diagram is applicable to Kubernetes clusters [launched with Rancher using R ![Cluster diagram](/img/clusterdiagram.svg)
Lines show the traffic flow between components. Colors are used purely for visual aid -# etcd +## etcd Nodes with the `etcd` role run etcd, which is a consistent and highly available key value store used as Kubernetes’ backing store for all cluster data. etcd replicates the data to each node. >**Note:** Nodes with the `etcd` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default. -# controlplane +## controlplane Nodes with the `controlplane` role run the Kubernetes master components (excluding `etcd`, as it's a separate role). See [Kubernetes: Master Components](https://kubernetes.io/docs/concepts/overview/components/#master-components) for a detailed list of components. @@ -33,10 +33,10 @@ The Kubernetes controller manager uses leader election using an endpoint in Kube The Kubernetes scheduler uses leader election using an endpoint in Kubernetes. One instance of the `kube-scheduler` will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive). -# worker +## worker Nodes with the `worker` role run the Kubernetes node components. See [Kubernetes: Node Components](https://kubernetes.io/docs/concepts/overview/components/#node-components) for a detailed list of components. -# References +## References * [Kubernetes: Node Components](https://kubernetes.io/docs/concepts/overview/components/#node-components) \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.md index 2c96956115a..7d81d9f4bd9 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.md @@ -22,7 +22,7 @@ Rancher v2.4 added the capability to import a K3s cluster into Rancher, as well - [Debug Logging and Troubleshooting for Imported K3s clusters](#debug-logging-and-troubleshooting-for-imported-k3s-clusters) - [Annotating imported clusters](#annotating-imported-clusters) -# Features +## Features After importing a cluster, the cluster owner can: @@ -35,7 +35,7 @@ After importing a cluster, the cluster owner can: After importing a K3s cluster, the cluster owner can also [upgrade Kubernetes from the Rancher UI.](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md) -# Prerequisites +## Prerequisites If your existing Kubernetes cluster already has a `cluster-admin` role defined, you must have this `cluster-admin` privilege to import the cluster into Rancher. @@ -53,7 +53,7 @@ By default, GKE users are not given this privilege, so you will need to run the > If you are importing a K3s cluster, make sure the `cluster.yml` is readable. It is protected by default. For details, refer to [Configuring a K3s cluster to enable importation to Rancher.](#configuring-a-k3s-cluster-to-enable-importation-to-rancher) -# Importing a Cluster +## Importing a Cluster 1. From the **Clusters** page, click **Add Cluster**. 2. Choose **Import**. @@ -74,7 +74,7 @@ By default, GKE users are not given this privilege, so you will need to run the > **Note:** > You can not re-import a cluster that is currently active in a Rancher setup. -# Imported K3s Clusters +## Imported K3s Clusters You can now import a K3s Kubernetes cluster into Rancher. [K3s](https://rancher.com/docs/k3s/latest/en/) is a lightweight, fully compliant Kubernetes distribution. You can also upgrade Kubernetes by editing the K3s cluster in the Rancher UI. @@ -139,7 +139,7 @@ If the cluster becomes stuck in upgrading, restart the `system-upgrade-controlle To prevent issues when upgrading, the [Kubernetes upgrade best practices](https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/) should be followed. -# Annotating Imported Clusters +## Annotating Imported Clusters For all types of imported Kubernetes clusters except for K3s Kubernetes clusters, Rancher doesn't have any information about how the cluster is provisioned or configured. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md index 28adb98b7b7..bd36268e4f1 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md @@ -18,7 +18,7 @@ Then you will create a DigitalOcean cluster in Rancher, and when configuring the 2. [Create a node template with your cloud credentials](#2-create-a-node-template-with-your-cloud-credentials) 3. [Create a cluster with node pools using the node template](#3-create-a-cluster-with-node-pools-using-the-node-template) -### 1. Create your cloud credentials +## 1. Create your cloud credentials 1. In the Rancher UI, click the user profile button in the upper right corner, and click **Cloud Credentials.** 1. Click **Add Cloud Credential.** @@ -29,7 +29,7 @@ Then you will create a DigitalOcean cluster in Rancher, and when configuring the **Result:** You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters. -### 2. Create a node template with your cloud credentials +## 2. Create a node template with your cloud credentials Creating a [node template](../../../../../pages-for-subheaders/use-new-nodes-in-an-infra-provider.md#node-templates) for DigitalOcean will allow Rancher to provision new nodes in DigitalOcean. Node templates can be reused for other clusters. @@ -37,7 +37,7 @@ Creating a [node template](../../../../../pages-for-subheaders/use-new-nodes-in- 1. Click **Add Template.** 1. Fill out a node template for DigitalOcean. For help filling out the form, refer to [DigitalOcean Node Template Configuration.](../../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.md) -### 3. Create a cluster with node pools using the node template +## 3. Create a cluster with node pools using the node template 1. From the **Clusters** page, click **Add Cluster**. 1. Choose **DigitalOcean**. @@ -83,7 +83,7 @@ You can access your cluster after its state is updated to **Active.** -# 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: diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md index 19a255bbe8b..9eca446529b 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md @@ -12,7 +12,7 @@ First, you will set up your EC2 cloud credentials in Rancher. Then you will use Then you will create an EC2 cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool. -### Prerequisites +## Prerequisites - **AWS EC2 Access Key and Secret Key** that will be used to create the instances. See [Amazon Documentation: Creating Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) how to create an Access Key and Secret Key. - **IAM Policy created** to add to the user of the Access Key And Secret Key. See [Amazon Documentation: Creating IAM Policies (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) how to create an IAM policy. See our three example JSON policies below: @@ -23,7 +23,7 @@ Then you will create an EC2 cluster in Rancher, and when configuring the new clu > **Note:** Rancher v2.4.6 and v2.4.7 had an issue where the `kms:ListKeys` permission was required to create, edit, or clone Amazon EC2 node templates. This requirement was removed in v2.4.8. -# Creating an EC2 Cluster +## Creating an EC2 Cluster The steps to create a cluster differ based on your Rancher version. @@ -110,7 +110,7 @@ After creating your cluster, you can access it through the Rancher UI. As a best - **Access your cluster with the kubectl CLI:** Follow [these steps](../../../../advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-on-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. - **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps](../../../../advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. -# IAM Policies +## IAM Policies > **Note:** Rancher v2.4.6 and v2.4.7 had an issue where the `kms:ListKeys` permission was required to create, edit, or clone Amazon EC2 node templates. This requirement was removed in v2.4.8. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md index 789775259f6..940290e6307 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md @@ -25,7 +25,7 @@ For more information on configuring Azure node templates, refer to the [Azure no - [Preparation in Azure](#preparation-in-azure) - [Creating an Azure Cluster](#creating-an-azure-cluster) -# Preparation in Azure +## Preparation in Azure Before creating a node template in Rancher using a cloud infrastructure such as Azure, we must configure Rancher to allow the manipulation of resources in an Azure subscription. @@ -42,7 +42,7 @@ az ad sp create-for-rbac \ The creation of this service principal returns three pieces of identification information, *The application ID, also called the client ID*, *The client secret*, and *The tenant ID*. This information will be used when you create a node template for Azure. -# Creating an Azure Cluster +## Creating an Azure Cluster diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md index 601ebdcd683..ea817be05ad 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md @@ -19,7 +19,7 @@ For details on configuring RKE Kubernetes clusters in Rancher, refer to the [clu - [Preparation in vSphere](#preparation-in-vsphere) - [Creating a vSphere Cluster](#creating-a-vsphere-cluster) -# Preparation in vSphere +## Preparation in vSphere This section describes the requirements for setting up vSphere so that Rancher can provision VMs and clusters. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md index be16905f3c1..87123aef5cd 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md @@ -14,7 +14,7 @@ Deployments use the Kubernetes registry secret to authenticate with a private Do Currently, deployments pull the private registry credentials automatically only if the workload is created in the Rancher UI and not when it is created via kubectl. -# Creating a Registry +## Creating a Registry >**Prerequisites:** You must have a [private registry](https://docs.docker.com/registry/deploying/) available to use. @@ -40,7 +40,7 @@ Currently, deployments pull the private registry credentials automatically only - You can view the secret in the Rancher UI from the **Resources > Registries** view. - Any workload that you create in the Rancher UI will have the credentials to access the registry if the workload is within the registry's scope. -# Using a Private Registry +## Using a Private Registry You can deploy a workload with an image from a private registry through the Rancher UI, or with `kubectl`. diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md index d1550358ffa..ccdcc64d865 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md @@ -15,7 +15,7 @@ Ingress can be added for workloads to provide load balancing, SSL termination an **Result:** Your ingress is added to the project. The ingress begins enforcing your ingress rules. -# Ingress Rule Configuration +## Ingress Rule Configuration - [Automatically generate a sslip.io hostname](#automatically-generate-a-sslip-io-hostname) - [Specify a hostname to use](#specify-a-hostname-to-use) diff --git a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md index d5a4b0eca03..93eabd4ced0 100644 --- a/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md +++ b/versioned_docs/version-2.0-2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md @@ -10,7 +10,7 @@ When configuring a workload, you'll be able to choose which secrets to include. Mounted secrets will be updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/configuration/secret/#mounted-secrets-are-updated-automatically) -# Creating Secrets +## Creating Secrets When creating a secret, you can make it available for any deployment within a project, or you can limit it to a single namespace. @@ -36,7 +36,7 @@ When creating a secret, you can make it available for any deployment within a pr Mounted secrets will be updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/configuration/secret/#mounted-secrets-are-updated-automatically) -# What's Next? +## What's Next? Now that you have a secret added to the project or namespace, you can add it to a workload that you deploy. diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/air-gap-helm2.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/air-gap-helm2.md index fe0ec4478a0..349bab11263 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/air-gap-helm2.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/air-gap-helm2.md @@ -28,7 +28,7 @@ The Docker installation is for Rancher users that are wanting to test out Ranche Instead of running the Docker installation, you have the option to follow the Kubernetes Install guide, but only use one node to install Rancher. Afterwards, you can scale up the etcd nodes in your Kubernetes cluster to make it a Kubernetes Installation. -# Installation Outline +## Installation Outline - [1. Prepare your Node(s)](../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) diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/air-gapped-helm-cli-install.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/air-gapped-helm-cli-install.md index c7713ae4b22..b2ea746630a 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/air-gapped-helm-cli-install.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/air-gapped-helm-cli-install.md @@ -12,14 +12,14 @@ Throughout the installation instructions, there will be _tabs_ for each installa > **Important:** If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation. -# Installation Outline +## 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.](upgrades.md) diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/cis-scans.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/cis-scans.md index 2db04db6f13..84402b5c3c1 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/cis-scans.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/cis-scans.md @@ -7,7 +7,7 @@ _Available as of v2.4.0_ - [Prerequisites](#prerequisites) - [How-to Guides](#how-to-guides) -# Prerequisites +## Prerequisites To run security scans on a cluster and access the generated reports, you must be an [Administrator](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) or [Cluster Owner.](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) @@ -17,6 +17,6 @@ The security scan cannot run in a cluster that has Windows nodes. You will only be able to see the CIS scan reports for clusters that you have access to. -# How-to Guides +## How-to Guides Please refer [here](../pages-for-subheaders/cis-scan-guides.md) for how-to guides on CIS scans. \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/cluster-alerts.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/cluster-alerts.md index 5447245fc33..413d8309f58 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/cluster-alerts.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/cluster-alerts.md @@ -5,7 +5,7 @@ title: Cluster Alerts To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. When an event occurs, your alert is triggered, and you are sent a notification. You can then, if necessary, follow up with corrective actions. -# About Alerts +## About Alerts Notifiers and alerts are built on top of the [Prometheus Alertmanager](https://prometheus.io/docs/alerting/alertmanager/). Leveraging these tools, Rancher can notify [cluster owners](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles) and [project owners](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles) of events they need to address. @@ -55,7 +55,7 @@ After you set up cluster alerts, you can manage each alert object. To manage ale - Mute firing alerts - Unmute muted alerts -# Adding Cluster Alerts +## Adding Cluster Alerts As a [cluster owner](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles), you can configure Rancher to send you alerts for cluster events. @@ -74,16 +74,16 @@ As a [cluster owner](../how-to-guides/advanced-user-guides/authentication-permis **Result:** Your alert is configured. A notification is sent when the alert is triggered. -# Cluster Alert Configuration +## Cluster Alert Configuration - - [System Service Alerts](#system-service-alerts) - - [Resource Event Alerts](#resource-event-alerts) - - [Node Alerts](#node-alerts) - - [Node Selector Alerts](#node-selector-alerts) - - [CIS Scan Alerts](#cis-scan-alerts) - - [Metric Expression Alerts](#metric-expression-alerts) +- [System Service Alerts](#system-service-alerts) +- [Resource Event Alerts](#resource-event-alerts) +- [Node Alerts](#node-alerts) +- [Node Selector Alerts](#node-selector-alerts) +- [CIS Scan Alerts](#cis-scan-alerts) +- [Metric Expression Alerts](#metric-expression-alerts) -# System Service Alerts +## System Service Alerts This alert type monitor for events that affect one of the Kubernetes master components, regardless of the node it occurs on. @@ -119,7 +119,7 @@ By default, the below options will apply to all alert rules within the group. Yo - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - **Repeat Wait Time**: How long to wait before re-sending a given alert that has already been sent, default to 1 hour. -# Resource Event Alerts +## Resource Event Alerts This alert type monitors for specific events that are thrown from a resource type. @@ -161,7 +161,7 @@ By default, the below options will apply to all alert rules within the group. Yo - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - **Repeat Wait Time**: How long to wait before re-sending a given alert that has already been sent, default to 1 hour. -# Node Alerts +## Node Alerts This alert type monitors for events that occur on a specific node. @@ -197,7 +197,7 @@ By default, the below options will apply to all alert rules within the group. Yo - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - **Repeat Wait Time**: How long to wait before re-sending a given alert that has already been sent, default to 1 hour. -# Node Selector Alerts +## Node Selector Alerts This alert type monitors for events that occur on any node on marked with a label. For more information, see the Kubernetes documentation for [Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/). @@ -233,7 +233,7 @@ By default, the below options will apply to all alert rules within the group. Yo - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - **Repeat Wait Time**: How long to wait before re-sending a given alert that has already been sent, default to 1 hour. -# CIS Scan Alerts +## CIS Scan Alerts _Available as of v2.4.0_ This alert type is triggered based on the results of a CIS scan. @@ -269,7 +269,7 @@ By default, the below options will apply to all alert rules within the group. Yo - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - **Repeat Wait Time**: How long to wait before re-sending a given alert that has already been sent, default to 1 hour. -# Metric Expression Alerts +## Metric Expression Alerts This alert type monitors for the overload from Prometheus expression querying, it would be available after you enable monitoring. diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/cluster-logging.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/cluster-logging.md index ac734593563..aeeb8be555c 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/cluster-logging.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/cluster-logging.md @@ -19,8 +19,7 @@ Rancher supports integration with the following services: - Syslog - Fluentd - -# How Logging Integrations Work +## How Logging Integrations Work Rancher can integrate with popular external services used for event streams, telemetry, or search. These services can log errors and warnings in your Kubernetes infrastructure to a stream. @@ -32,7 +31,7 @@ Additionally, you'll have the opportunity to enter key-value pairs to filter the >**Note:** You can only configure one logging service per cluster or per project. -# Requirements +## Requirements The Docker daemon on each node in the cluster should be [configured](https://docs.docker.com/config/containers/logging/configure/) with the (default) log-driver: `json-file`. You can check the log-driver by running the following command: @@ -41,7 +40,7 @@ $ docker info | grep 'Logging Driver' Logging Driver: json-file ``` -# Logging Scope +## Logging Scope You can configure logging at either cluster level or project level. @@ -53,7 +52,7 @@ Logs that are sent to your logging service are from the following locations: - Pod logs stored at `/var/log/containers`. - Kubernetes system components logs stored at `/var/lib/rancher/rke/log/`. -# Enabling Cluster Logging +## Enabling Cluster Logging As an [administrator](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) or [cluster owner](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles), you can configure Rancher to send Kubernetes logs to a logging service. diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/cluster-monitoring.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/cluster-monitoring.md index e78dea7d404..cbb8e81bdc0 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/cluster-monitoring.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/cluster-monitoring.md @@ -7,7 +7,7 @@ _Available as of v2.2.0_ 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. -# About Prometheus +## About Prometheus Prometheus provides a _time series_ of your data, which is, according to [Prometheus documentation](https://prometheus.io/docs/concepts/data_model/): @@ -21,7 +21,7 @@ By viewing data that Prometheus scrapes from your cluster control plane, nodes, Multi-tenancy support in terms of cluster-only and project-only Prometheus instances are also supported. -# Monitoring Scope +## Monitoring Scope Using Prometheus, you can monitor Rancher at both the cluster level and [project level](../explanations/integrations-in-rancher/cluster-monitoring/project-monitoring.md). For each cluster and project that is enabled for monitoring, Rancher deploys a Prometheus server. @@ -33,7 +33,7 @@ Using Prometheus, you can monitor Rancher at both the cluster level and [project - [Project monitoring](../explanations/integrations-in-rancher/cluster-monitoring/project-monitoring.md) allows you to view the state of pods running in a given project. Prometheus collects metrics from the project's deployed HTTP and TCP/UDP workloads. -# Enabling Cluster Monitoring +## Enabling Cluster Monitoring As an [administrator](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) or [cluster owner](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles), you can configure Rancher to deploy Prometheus to monitor your Kubernetes cluster. @@ -62,7 +62,7 @@ As an [administrator](../how-to-guides/advanced-user-guides/authentication-permi > The default username and password for the Grafana instance will be `admin/admin`. However, Grafana dashboards are served via the Rancher authentication proxy, so only users who are currently authenticated into the Rancher server have access to the Grafana dashboard. -# Resource Consumption +## Resource Consumption When enabling cluster monitoring, you need to ensure your worker nodes and Prometheus pod have enough resources. The tables below provides a guide of how much resource consumption will be used. In larger deployments, it is strongly advised that the monitoring infrastructure be placed on dedicated nodes in the cluster. diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/configure-shibboleth-saml.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/configure-shibboleth-saml.md index 7a715831100..075d978b53c 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/configure-shibboleth-saml.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/configure-shibboleth-saml.md @@ -13,7 +13,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/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.md) -# Setting up Shibboleth in Rancher +## Setting up Shibboleth in Rancher ### Shibboleth Prerequisites > @@ -71,7 +71,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. @@ -93,6 +93,6 @@ Configure the settings for the OpenLDAP server, groups and users. For help filli 2. From the **Global** view, navigate to **Security** > **Authentication** 3. Select **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. diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/enable-experimental-features.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/enable-experimental-features.md index 7dc222a7bb6..b396a57fd38 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/enable-experimental-features.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/enable-experimental-features.md @@ -24,7 +24,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](../reference-guides/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. @@ -97,7 +97,7 @@ docker run -d -p 80:80 -p 443:443 \ -# Enabling Features with the Rancher UI +## Enabling Features with the Rancher UI 1. Go to the **Global** view and click **Settings.** 1. Click the **Feature Flags** tab. You will see a list of experimental features. @@ -113,7 +113,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 `/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. diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/install-cluster-autoscaler.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/install-cluster-autoscaler.md index 0dcca143dd7..cd0fac015c7 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/install-cluster-autoscaler.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/install-cluster-autoscaler.md @@ -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) diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md index 36c6e615a6f..964f1cb6568 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md @@ -6,7 +6,7 @@ description: Learn how to install Rancher in development and production environm import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Prerequisite +## Prerequisite Set up the Rancher server's local Kubernetes cluster. @@ -19,7 +19,7 @@ For the tutorial to install an RKE Kubernetes cluster, refer to [this page.](../ For the tutorial to install a K3s Kubernetes cluster, refer to [this page.](../how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md) For help setting up the infrastructure for a high-availability K3s cluster, refer to [this page.](../how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.md) -# Install the Rancher Helm Chart +## Install the Rancher Helm Chart Rancher is installed using the Helm package manager for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents. diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/installation-and-upgrade.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/installation-and-upgrade.md index d902ed409e7..9f19859700e 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/installation-and-upgrade.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/installation-and-upgrade.md @@ -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, @@ -13,7 +13,7 @@ In this section, - **RKE (Rancher Kubernetes Engine)** is a certified Kubernetes distribution and CLI/library which creates and manages a Kubernetes cluster. - **K3s (Lightweight Kubernetes)** is also a fully compliant Kubernetes distribution. It is newer than RKE, easier to use, and more lightweight, with a binary size of less than 100 MB. As of Rancher v2.4, Rancher can be installed on a K3s cluster. -# Overview of Installation Options +## Overview of Installation Options Rancher can be installed on these main architectures: @@ -60,10 +60,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/deployment-types.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. diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/installation-requirements.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/installation-requirements.md index 1d65bddd95f..e7bc24b1a26 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/installation-requirements.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/installation-requirements.md @@ -25,7 +25,7 @@ For a list of best practices that we recommend for running the Rancher server in The Rancher UI works best in Firefox or Chrome. -# Operating Systems and Container Runtime Requirements +## Operating Systems and Container Runtime Requirements Rancher should work with any modern Linux distribution. @@ -53,11 +53,11 @@ If you are installing Rancher on a K3s cluster with **Raspbian Buster**, follow If you are installing Rancher on a K3s cluster with Alpine Linux, follow [these steps](https://rancher.com/docs/k3s/latest/en/advanced/#additional-preparation-for-alpine-linux-setup) for additional setup. - ### Installing Docker Docker is required for Helm chart installs, and it can be installed by following the steps in the official [Docker documentation.](https://docs.docker.com/) Rancher also provides [scripts](../getting-started/installation-and-upgrade/installation-requirements/install-docker.md) to install Docker with one command. -# Hardware Requirements + +## Hardware Requirements This section describes the CPU, memory, and disk requirements for the nodes where the Rancher server is installed. @@ -133,7 +133,7 @@ These requirements apply to installing Rancher on an RKE Kubernetes cluster befo 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. diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/istio.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/istio.md index 7ad799b77b2..2518b3c0510 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/istio.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/istio.md @@ -31,19 +31,19 @@ Rancher's Istio integration comes with comprehensive visualization aids: Istio needs to be set up by a Rancher administrator or cluster administrator before it can be used in a project. -# Prerequisites +## Prerequisites Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough [CPU and memory](../explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.md) to run all of the components of Istio. -# Setup Guide +## Setup Guide Refer to the [setup guide](istio-setup-guide.md) for instructions on how to set up Istio and use it in a project. -# Disabling Istio +## Disabling Istio To remove Istio components from a cluster, namespace, or workload, refer to the section on [disabling Istio.](../explanations/integrations-in-rancher/istio/disable-istio.md) -# Accessing Visualizations +## Accessing Visualizations > By default, only cluster owners have access to Jaeger and Kiali. For instructions on how to allow project members to access them, see [this section.](../explanations/integrations-in-rancher/istio/rbac-for-istio.md) @@ -55,19 +55,19 @@ To see the visualizations, go to the cluster where Istio is set up and click **T You can also get to the visualization tools from the project view. -# Viewing the Kiali Traffic Graph +## Viewing the Kiali Traffic Graph 1. From the project view in Rancher, click **Resources > Istio.** 1. If you are a cluster owner, you can go to the **Traffic Graph** tab. This tab has the Kiali network visualization integrated into the UI. -# Viewing Traffic Metrics +## Viewing Traffic Metrics Istio’s monitoring features provide visibility into the performance of all your services. 1. From the project view in Rancher, click **Resources > Istio.** 1. Go to the **Traffic Metrics** tab. After traffic is generated in your cluster, you should be able to see metrics for **Success Rate, Request Volume, 4xx Response Count, Project 5xx Response Count** and **Request Duration.** Cluster owners can see all of the metrics, while project members can see a subset of the metrics. -# Architecture +## Architecture Istio installs a service mesh that uses [Envoy](https://www.envoyproxy.io/learn/service-mesh) sidecar proxies to intercept traffic to each workload. These sidecars intercept and manage service-to-service communication, allowing fine-grained observation and control over traffic within the cluster. diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md index 14235e618f8..b40ea279368 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.md @@ -15,7 +15,7 @@ import ClusterCapabilitiesTable from '../shared-files/_cluster-capabilities-tabl -# Setting up Clusters in a Hosted Kubernetes Provider +## Setting up Clusters in a Hosted Kubernetes Provider In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service. @@ -23,7 +23,7 @@ If you use a Kubernetes provider such as Google GKE, Rancher integrates with its For more information, refer to the section on [hosted Kubernetes clusters.](set-up-clusters-from-hosted-kubernetes-providers.md) -# Launching Kubernetes with Rancher +## Launching Kubernetes with Rancher Rancher uses the [Rancher Kubernetes Engine (RKE)](https://rancher.com/docs/rke/latest/en/) as a library when provisioning Kubernetes on your own nodes. RKE is Rancher’s own lightweight Kubernetes installer. @@ -55,7 +55,7 @@ You can bring any nodes you want to Rancher and use them to create a cluster. These nodes include on-prem bare metal servers, cloud-hosted virtual machines, or on-prem virtual machines. -# Importing Existing Clusters +## Importing Existing Clusters _Available from Rancher v2.0.x-v2.4.x_ diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/kubernetes-components.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/kubernetes-components.md index e93dd6bc8fd..b2271a50909 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/kubernetes-components.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/kubernetes-components.md @@ -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)
Lines show the traffic flow between components. Colors are used purely for visual aid \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/project-tools.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/project-tools.md index 3b5a78c1920..e3ade14bad7 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/project-tools.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/project-tools.md @@ -4,17 +4,17 @@ title: Tools for Logging, Monitoring, and More 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. -# Notifiers +## Notifiers [Notifiers](../explanations/integrations-in-rancher/notifiers.md) are services that inform you of alert events. You can configure notifiers to send alert notifications to staff best suited to take corrective action. Notifications can be sent with Slack, email, PagerDuty, WeChat, and webhooks. -# Alerts +## Alerts [Alerts](./cluster-alerts.md) are rules that trigger notifications. Before you can receive alerts, you must configure one or more notifier in Rancher. The scope for alerts can be set at either the cluster or project level. For details on project-level alerts, see [this page.](../reference-guides/rancher-project-tools/project-alerts.md) -# Logging +## Logging Logging is helpful because it allows you to: @@ -30,7 +30,7 @@ For details on setting up logging at the cluster level, refer to the [logging se For details on project-level logging, see [this section.](../reference-guides/rancher-project-tools/project-logging.md) -# Monitoring +## Monitoring _Available as of v2.2.0_ diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-behind-an-http-proxy.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-behind-an-http-proxy.md index ef0d4acbe8e..59a7eec2dba 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-behind-an-http-proxy.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-behind-an-http-proxy.md @@ -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) diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-on-a-single-node-with-docker.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-on-a-single-node-with-docker.md index de8227bfd01..a8918e5fe11 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-on-a-single-node-with-docker.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/rancher-on-a-single-node-with-docker.md @@ -14,15 +14,15 @@ A Docker installation of Rancher is recommended only for development and testing For Rancher v2.0-v2.4, there is no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start. -# 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. diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/upgrades.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/upgrades.md index cd5eff2b4ed..f557126d378 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/upgrades.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/upgrades.md @@ -18,7 +18,7 @@ If you installed Rancher using the RKE Add-on yaml, follow the directions to [mi - [Known Upgrade Issues](#known-upgrade-issues) - [RKE Add-on Installs](#rke-add-on-installs) -# Prerequisites +## Prerequisites ### Access to kubeconfig @@ -54,7 +54,7 @@ If you are upgrading Rancher from v2.x to v2.3+, and you are using external TLS [Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) Upgrade cert-manager to the latest version by following [these instructions.](../getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md) -# Upgrade Outline +## Upgrade Outline Follow the steps to upgrade Rancher server: @@ -63,7 +63,7 @@ Follow the steps to upgrade Rancher server: - [3. Upgrade Rancher](#3-upgrade-rancher) - [4. Verify the Upgrade](#4-verify-the-upgrade) -# 1. Back up Your Kubernetes Cluster that is Running Rancher Server +## 1. Back up Your Kubernetes Cluster that is Running Rancher Server [Take a one-time snapshot](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md#option-b-one-time-snapshots) @@ -71,7 +71,7 @@ of your Kubernetes cluster running Rancher server. You'll use the backup as a restoration point if something goes wrong during upgrade. -# 2. Update the Helm chart repository +## 2. Update the Helm chart repository 1. Update your local helm repo cache. @@ -121,7 +121,7 @@ You'll use the backup as a restoration point if something goes wrong during upgr helm fetch rancher-/rancher --version=v2.4.11 ``` -# 3. Upgrade Rancher +## 3. Upgrade Rancher This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm. @@ -256,7 +256,7 @@ kubectl -n cattle-system apply -R -f ./rancher -# 4. Verify the Upgrade +## 4. Verify the Upgrade Log into Rancher to confirm that the upgrade succeeded. @@ -264,7 +264,7 @@ Log into Rancher to confirm that the upgrade succeeded. > > See [Restoring Cluster Networking](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md#restoring-cluster-networking). -# Known Upgrade Issues +## Known Upgrade Issues The following table lists some of the most noteworthy issues to be considered 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) @@ -276,7 +276,7 @@ Upgrading to v2.2.0-v2.2.x | Rancher introduced the [system charts](https://gith Upgrading from v2.0.13 or earlier | If your cluster's certificates have expired, you will need to perform [additional steps](../how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.md#rotating-expired-certificates-after-upgrading-older-rancher-versions) to rotate the certificates. Upgrading from v2.0.7 or earlier | Rancher introduced the `system` project, which is a project that's automatically created to store important namespaces that Kubernetes needs to operate. During upgrade to v2.0.7+, Rancher expects these namespaces to be unassigned from all projects. Before beginning upgrade, check your system namespaces to make sure that they're unassigned to [prevent cluster networking issues.](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md) -# RKE Add-on Installs +## RKE Add-on Installs **Important: RKE add-on install is only supported up to Rancher v2.0.8** diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/use-existing-nodes.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/use-existing-nodes.md index a4a1f25b3f4..6baa97d58a5 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/use-existing-nodes.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/use-existing-nodes.md @@ -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 >**Want to use Windows hosts as Kubernetes workers?** > @@ -106,7 +106,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: diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/use-new-nodes-in-an-infra-provider.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/use-new-nodes-in-an-infra-provider.md index 3f9e1612be4..a28666e109a 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/use-new-nodes-in-an-infra-provider.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/use-new-nodes-in-an-infra-provider.md @@ -9,7 +9,7 @@ One benefit of installing Kubernetes on node pools hosted by an infrastructure p The available cloud providers to create a node template are decided based on active [node drivers](use-new-nodes-in-an-infra-provider.md#node-drivers). -# Node Templates +## Node Templates A node template is the saved configuration for the parameters to use when provisioning nodes in a specific cloud provider. These nodes can be launched from the UI. Rancher uses [Docker Machine](https://docs.docker.com/machine/) to provision these nodes. The available cloud providers to create node templates are based on the active node drivers in Rancher. @@ -40,7 +40,7 @@ To access all node templates, an administrator will need to do the following: **Result:** All node templates are listed and grouped by owner. The templates can be edited or cloned by clicking the **⋮.** -# Node Pools +## Node Pools Using Rancher, you can create pools of nodes based on a [node template](#node-templates). @@ -108,7 +108,7 @@ You can disable node auto-replace from the Rancher UI with the following steps: **Result:** Node auto-replace is disabled for the node pool. -# Cloud Credentials +## Cloud Credentials _Available as of v2.2.0_ @@ -124,6 +124,6 @@ Node templates can use cloud credentials to store credentials for launching node After cloud credentials are created, the user can start [managing the cloud credentials that they created](../reference-guides/user-settings/manage-cloud-credentials.md). -# Node Drivers +## Node Drivers If you don't find the node driver that you want to use, you can see if it is available in Rancher's built-in [node drivers and activate it](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#activating-deactivating-node-drivers), or you can [add your own custom node driver](../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#adding-custom-node-drivers). diff --git a/versioned_docs/version-2.0-2.4/pages-for-subheaders/use-windows-clusters.md b/versioned_docs/version-2.0-2.4/pages-for-subheaders/use-windows-clusters.md index 9119acf2e4b..80c4912411a 100644 --- a/versioned_docs/version-2.0-2.4/pages-for-subheaders/use-windows-clusters.md +++ b/versioned_docs/version-2.0-2.4/pages-for-subheaders/use-windows-clusters.md @@ -20,7 +20,7 @@ For the full list of requirements, see [this section.](#requirements-for-windows For a summary of Kubernetes features supported in Windows, see the Kubernetes documentation on [supported functionality and limitations for using Kubernetes with Windows](https://kubernetes.io/docs/setup/production-environment/windows/intro-windows-in-kubernetes/#supported-functionality-and-limitations) or the [guide for scheduling Windows containers in Kubernetes](https://kubernetes.io/docs/setup/production-environment/windows/user-guide-windows-containers/). -# Requirements for Windows Clusters +## Requirements for Windows Clusters The general node requirements for networking, operating systems, and Docker are the same as the node requirements for a [Rancher installation](installation-requirements.md). @@ -95,7 +95,7 @@ If you are using the GCE (Google Compute Engine) cloud provider, you must do the - Enable the GCE cloud provider in the `cluster.yml` by following [these steps.](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.md) - When provisioning the cluster in Rancher, choose **Custom cloud provider** as the cloud provider in the Rancher UI. -# Tutorial: How to Create a Cluster with Windows Support +## Tutorial: How to Create a Cluster with Windows Support This tutorial describes how to create a Rancher-provisioned cluster with the three nodes in the [recommended architecture.](#guide-architecture) @@ -103,8 +103,7 @@ When you provision a cluster with Rancher on existing nodes, you will add nodes To set up a cluster with support for Windows nodes and containers, you will need to complete the tasks below. - -# 1. Provision Hosts +## 1. Provision Host To begin provisioning a cluster on existing nodes with Windows support, prepare your hosts. @@ -128,7 +127,7 @@ You will provision three nodes: If your nodes are hosted by a **Cloud Provider** and you want automation support such as loadbalancers or persistent storage devices, your nodes have additional configuration requirements. For details, see [Selecting Cloud Providers.](../pages-for-subheaders/set-up-cloud-providers.md) -# 2. Create the Cluster on Existing Nodes +## 2. Create the Cluster on Existing Nodes The instructions for creating a Windows cluster on existing nodes are very similar to the general [instructions for creating a custom cluster](use-existing-nodes.md) with some Windows-specific requirements. @@ -143,7 +142,7 @@ The instructions for creating a Windows cluster on existing nodes are very simil > **Important:** For Host Gateway (L2bridge) networking, it's best to use the same Layer 2 network for all nodes. Otherwise, you need to configure the route rules for them. For details, refer to the [documentation on configuring cloud-hosted VM routes.](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.md#cloud-hosted-vm-routes-configuration) You will also need to [disable private IP address checks](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.md#disabling-private-ip-address-checks) if you are using Amazon EC2, Google GCE, or Azure VM. -# 3. Add Nodes to the Cluster +## 3. Add Nodes to the Cluster This section describes how to register your Linux and Worker nodes to your cluster. You will run a command on each node, which will install the Rancher agent and allow Rancher to manage each node. @@ -221,6 +220,6 @@ After creating your cluster, you can access it through the Rancher UI. As a best - **Access your cluster with the kubectl CLI:** Follow [these steps](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-on-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. - **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through the Rancher server. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. -# Configuration for Storage Classes in Azure +## Configuration for Storage Classes in Azure If you are using Azure VMs for your nodes, you can use [Azure files](https://docs.microsoft.com/en-us/azure/aks/azure-files-dynamic-pv) as a StorageClass for the cluster. For details, refer to [this section.](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.md) \ No newline at end of file diff --git a/versioned_docs/version-2.0-2.4/reference-guides/best-practices/deployment-strategies.md b/versioned_docs/version-2.0-2.4/reference-guides/best-practices/deployment-strategies.md index 6fbf11b1836..e249f50c289 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/best-practices/deployment-strategies.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/best-practices/deployment-strategies.md @@ -7,7 +7,7 @@ There are two recommended deployment strategies. Each one has its own pros and c * [Hub and Spoke](#hub-and-spoke-strategy) * [Regional](#regional-strategy) -# Hub and Spoke Strategy +## Hub and Spoke Strategy --- In this deployment scenario, there is a single Rancher control plane managing Kubernetes clusters across the globe. The control plane would be run on a high-availability Kubernetes cluster, and there would be impact due to latencies. @@ -25,7 +25,7 @@ In this deployment scenario, there is a single Rancher control plane managing Ku * Subject to network latencies. * If the control plane goes out, global provisioning of new services is unavailable until it is restored. However, each Kubernetes cluster can continue to be managed individually. -# Regional Strategy +## Regional Strategy --- In the regional deployment model a control plane is deployed in close proximity to the compute nodes. diff --git a/versioned_docs/version-2.0-2.4/reference-guides/best-practices/management.md b/versioned_docs/version-2.0-2.4/reference-guides/best-practices/management.md index 7ca1e045c19..b0e8975159f 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/best-practices/management.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/best-practices/management.md @@ -12,30 +12,36 @@ Rancher allows you to set up numerous combinations of configurations. Some confi - [Class of Service and Kubernetes Clusters](#class-of-service-and-kubernetes-clusters) - [Network Security](#network-security) -# Tips for Preventing and Handling Problems +## Tips for Preventing and Handling Problems These tips can help you solve problems before they happen. ### Run Rancher on a Supported OS and Supported Docker Version + Rancher is container-based and can potentially run on any Linux-based operating system. However, only operating systems listed in the [requirements documentation](../../pages-for-subheaders/installation-requirements.md) should be used for running Rancher, along with a supported version of Docker. These versions have been most thoroughly tested and can be properly supported by the Rancher Support team. ### Upgrade Your Kubernetes Version + Keep your Kubernetes cluster up to date with a recent and supported version. Typically the Kubernetes community will support the current version and previous three minor releases (for example, 1.14.x, 1.13.x, 1.12.x, and 1.11.x). After a new version is released, the third-oldest supported version reaches EOL (End of Life) status. Running on an EOL release can be a risk if a security issues are found and patches are not available. The community typically makes minor releases every quarter (every three months). Rancher’s SLAs are not community dependent, but as Kubernetes is a community-driven software, the quality of experience will degrade as you get farther away from the community's supported target. ### Kill Pods Randomly During Testing + Run chaoskube or a similar mechanism to randomly kill pods in your test environment. This will test the resiliency of your infrastructure and the ability of Kubernetes to self-heal. It's not recommended to run this in your production environment. ### Deploy Complicated Clusters with Terraform + Rancher's "Add Cluster" UI is preferable for getting started with Kubernetes cluster orchestration or for simple use cases. However, for more complex or demanding use cases, it is recommended to use a CLI/API driven approach. [Terraform](https://www.terraform.io/) is recommended as the tooling to implement this. When you use Terraform with version control and a CI/CD environment, you can have high assurances of consistency and reliability when deploying Kubernetes clusters. This approach also gives you the most customization options. Rancher [maintains a Terraform provider](https://rancher.com/blog/2019/rancher-2-terraform-provider/) for working with Rancher 2.0 Kubernetes. It is called the [Rancher2 Provider.](https://www.terraform.io/docs/providers/rancher2/index.html) ### Upgrade Rancher in a Staging Environment + All upgrades, both patch and feature upgrades, should be first tested on a staging environment before production is upgraded. The more closely the staging environment mirrors production, the higher chance your production upgrade will be successful. ### Renew Certificates Before they Expire + Multiple people in your organization should set up calendar reminders for certificate renewal. Consider renewing the certificate two weeks to one month in advance. If you have multiple certificates to track, consider using [monitoring and alerting mechanisms](../rancher-cluster-tools.md) to track certificate expiration. Rancher-provisioned Kubernetes clusters will use certificates that expire in one year. Clusters provisioned by other means may have a longer or shorter expiration. @@ -43,12 +49,15 @@ Rancher-provisioned Kubernetes clusters will use certificates that expire in one Certificates can be renewed for Rancher-provisioned clusters [through the Rancher user interface](../../how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.md). ### Enable Recurring Snapshots for Backing up and Restoring the Cluster + Make sure etcd recurring snapshots are enabled. Extend the snapshot retention to a period of time that meets your business needs. In the event of a catastrophic failure or deletion of data, this may be your only recourse for recovery. For details about configuring snapshots, refer to the [RKE documentation](https://rancher.com/docs/rke/latest/en/etcd-snapshots/) or the [Rancher documentation on backups](../../pages-for-subheaders/backup-restore-and-disaster-recovery.md). ### Provision Clusters with Rancher + When possible, use Rancher to provision your Kubernetes cluster rather than importing a cluster. This will ensure the best compatibility and supportability. ### Use Stable and Supported Rancher Versions for Production + Do not upgrade production environments to alpha, beta, release candidate (rc), or "latest" versions. These early releases are often not stable and may not have a future upgrade path. When installing or upgrading a non-production environment to an early release, anticipate problems such as features not working, data loss, outages, and inability to upgrade without a reinstall. @@ -59,81 +68,103 @@ Keep in mind that Rancher does End of Life support for old versions, so you will For more detail on what happens during the Rancher product lifecycle, refer to the [Support Maintenance Terms](https://rancher.com/support-maintenance-terms/). -# Network Topology +## Network Topology + These tips can help Rancher work more smoothly with your network. ### Use Low-latency Networks for Communication Within Clusters + Kubernetes clusters are best served by low-latency networks. This is especially true for the control plane components and etcd, where lots of coordination and leader election traffic occurs. Networking between Rancher server and the Kubernetes clusters it manages are more tolerant of latency. ### Allow Rancher to Communicate Directly with Clusters + Limit the use of proxies or load balancers between Rancher server and Kubernetes clusters. As Rancher is maintaining a long-lived web sockets connection, these intermediaries can interfere with the connection lifecycle as they often weren't configured with this use case in mind. +## Tips for Scaling and Reliability -# Tips for Scaling and Reliability These tips can help you scale your cluster more easily. ### Use One Kubernetes Role Per Host + Separate the etcd, control plane, and worker roles onto different hosts. Don't assign multiple roles to the same host, such as a worker and control plane. This will give you maximum scalability. ### Run the Control Plane and etcd on Virtual Machines + Run your etcd and control plane nodes on virtual machines where you can scale vCPU and memory easily if needed in the future. ### Use at Least Three etcd Nodes + Provision 3 or 5 etcd nodes. Etcd requires a quorum to determine a leader by the majority of nodes, therefore it is not recommended to have clusters of even numbers. Three etcd nodes is generally sufficient for smaller clusters and five etcd nodes for large clusters. ### Use at Least Three Control Plane Nodes + Provision three or more control plane nodes. Some control plane components, such as the `kube-apiserver`, run in [active-active](https://www.jscape.com/blog/active-active-vs-active-passive-high-availability-cluster) mode and will give you more scalability. Other components such as kube-scheduler and kube-controller run in active-passive mode (leader elect) and give you more fault tolerance. ### Monitor Your Cluster + Closely monitor and scale your nodes as needed. You should [enable cluster monitoring](../../pages-for-subheaders/cluster-monitoring.md) and use the Prometheus metrics and Grafana visualization options as a starting point. +## Tips for Security -# Tips for Security Below are some basic tips for increasing security in Rancher. For more detailed information about securing your cluster, you can refer to these resources: - Rancher's [security documentation and Kubernetes cluster hardening guide](../../pages-for-subheaders/rancher-security.md) - [101 More Security Best Practices for Kubernetes](https://rancher.com/blog/2019/2019-01-17-101-more-kubernetes-security-best-practices/) ### Update Rancher with Security Patches + Keep your Rancher installation up to date with the latest patches. Patch updates have important software fixes and sometimes have security fixes. When patches with security fixes are released, customers with Rancher licenses are notified by e-mail. These updates are also posted on Rancher's [forum](https://forums.rancher.com/). ### Report Security Issues Directly to Rancher + If you believe you have uncovered a security-related problem in Rancher, please communicate this immediately and discretely to the Rancher team (security@rancher.com). Posting security issues on public forums such as Twitter, Rancher Slack, GitHub, etc. can potentially compromise security for all Rancher customers. Reporting security issues discretely allows Rancher to assess and mitigate the problem. Security patches are typically given high priority and released as quickly as possible. ### Only Upgrade One Component at a Time + In addition to Rancher software updates, closely monitor security fixes for related software, such as Docker, Linux, and any libraries used by your workloads. For production environments, try to avoid upgrading too many entities during a single maintenance window. Upgrading multiple components can make it difficult to root cause an issue in the event of a failure. As business requirements allow, upgrade one component at a time. -# Tips for Multi-Tenant Clusters +## Tips for Multi-Tenant Clusters ### Namespaces + Each tenant should have their own unique namespaces within the cluster. This avoids naming conflicts and allows resources to be only visible to their owner through use of RBAC policy ### Project Isolation + Use Rancher's Project Isolation to automatically generate Network Policy between Projects (sets of Namespaces). This further protects workloads from interference ### Resource Limits + Enforce use of sane resource limit definitions for every deployment in your cluster. This not only protects the owners of the deployment, but the neighboring resources from other tenants as well. Remember, namespaces do not isolate at the node level, so over-consumption of resources on a node affects other namespace deployments. Admission controllers can be written to require resource limit definitions ### Resource Requirements + Enforce use of resource requirement definitions for each deployment in your cluster. This enables the scheduler to appropriately schedule workloads. Otherwise you will eventually end up with over-provisioned nodes. -# Class of Service and Kubernetes Clusters +## Class of Service and Kubernetes Clusters + A class of service describes the expectations around cluster uptime, durability, and duration of maintenance windows. Typically organizations group these characteristics into labels such as "dev" or "prod" ### Consider fault domains + Kubernetes clusters can span multiple classes of service, however it is important to consider the ability for one workload to affect another. Without proper deployment practices such as resource limits, requirements, etc, a deployment that is not behaving well has the potential to impact the health of the cluster. In a "dev" environment it is common for end-users to exercise less caution with deployments, thus increasing the chance of such behavior. Sharing this behavior with your production workload increases risk. ### Upgrade risks + Upgrades of Kubernetes are not without risk, the best way to predict the outcome of an upgrade is try it on a cluster of similar load and use case as your production cluster. This is where having non-prod class of service clusters can be advantageous. ### Resource Efficiency + Clusters can be built with varying degrees of redundancy. In a class of service with low expectations for uptime, resources and cost can be conserved by building clusters without redundant Kubernetes control components. This approach may also free up more budget/resources to increase the redundancy at the production level -# Network Security +## Network Security + In general, you can use network security best practices in your Rancher and Kubernetes clusters. Consider the following: ### Use a Firewall Between your Hosts and the Internet + Firewalls should be used between your hosts and the Internet (or corporate Intranet). This could be enterprise firewall appliances in a datacenter or SDN constructs in the cloud, such as VPCs, security groups, ingress, and egress rules. Try to limit inbound access only to ports and IP addresses that require it. Outbound access can be shut off (air gap) if environment sensitive information that requires this restriction. If available, use firewalls with intrusion detection and DDoS prevention. ### Run Periodic Security Scans + Run security and penetration scans on your environment periodically. Even with well design infrastructure, a poorly designed microservice could compromise the entire environment. diff --git a/versioned_docs/version-2.0-2.4/reference-guides/cli-with-rancher/kubectl-utility.md b/versioned_docs/version-2.0-2.4/reference-guides/cli-with-rancher/kubectl-utility.md index decccb345ae..30de2616f05 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/cli-with-rancher/kubectl-utility.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/cli-with-rancher/kubectl-utility.md @@ -2,7 +2,7 @@ title: kubectl Utility --- -# kubectl +## kubectl Interact with Rancher using kubectl. diff --git a/versioned_docs/version-2.0-2.4/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md b/versioned_docs/version-2.0-2.4/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md index dc65b97fc6d..fceb63f5050 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md @@ -338,7 +338,7 @@ The table below indicates what DNS provider is deployed by default. See [RKE doc | v2.2.5 and higher | v1.13.x and lower | kube-dns | | v2.2.4 and lower | any | kube-dns | -# Rancher specific parameters +## Rancher specific parameters _Available as of v2.2.0_ diff --git a/versioned_docs/version-2.0-2.4/reference-guides/configure-openldap/openldap-config-reference.md b/versioned_docs/version-2.0-2.4/reference-guides/configure-openldap/openldap-config-reference.md index 9e0b5ce1ad8..2ffd181fa9c 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/configure-openldap/openldap-config-reference.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/configure-openldap/openldap-config-reference.md @@ -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. diff --git a/versioned_docs/version-2.0-2.4/reference-guides/installation-references/helm-chart-options.md b/versioned_docs/version-2.0-2.4/reference-guides/installation-references/helm-chart-options.md index aee80fad2fa..6115c847131 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/installation-references/helm-chart-options.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/installation-references/helm-chart-options.md @@ -150,7 +150,7 @@ For details on installing Rancher with a private registry, see: - [Air Gap: Kubernetes Install](../../pages-for-subheaders/air-gap-helm2.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. diff --git a/versioned_docs/version-2.0-2.4/reference-guides/installation-references/tls-settings.md b/versioned_docs/version-2.0-2.4/reference-guides/installation-references/tls-settings.md index 5e2195a6d83..35c5ce01778 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/installation-references/tls-settings.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/installation-references/tls-settings.md @@ -4,7 +4,7 @@ title: TLS Settings In Rancher v2.1.7, the default TLS configuration changed to only accept TLS 1.2 and secure TLS cipher suites. TLS 1.3 and TLS 1.3 exclusive cipher suites are not supported. -# Configuring TLS settings +## Configuring TLS settings The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation. @@ -12,15 +12,14 @@ The Audit Log is enabled and configured by passing environment variables to the - [TLS settings in Helm chart options](helm-chart-options.md#tls-settings) -# TLS Environment Variables +## TLS Environment Variables | Parameter | Description | Default | Available options | |-----|-----|-----|-----| | `CATTLE_TLS_MIN_VERSION` | Minimum TLS version | `1.2` | `1.0`, `1.1`, `1.2` | | `CATTLE_TLS_CIPHERS` | Allowed TLS cipher suites | `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,`
`TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,`
`TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,`
`TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,`
`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,`
`TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305` | See [Golang tls constants](https://golang.org/pkg/crypto/tls/#pkg-constants) | - -# Legacy configuration +## Legacy configuration If you need to configure TLS the same way as it was before Rancher v2.1.7, please use the following settings: diff --git a/versioned_docs/version-2.0-2.4/reference-guides/rancher-cluster-tools.md b/versioned_docs/version-2.0-2.4/reference-guides/rancher-cluster-tools.md index 1f02f912841..5d38d2a391f 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/rancher-cluster-tools.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/rancher-cluster-tools.md @@ -5,7 +5,7 @@ title: Tools for Logging, Monitoring, and More 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: @@ -19,24 +19,27 @@ Rancher can integrate with Elasticsearch, splunk, kafka, syslog, and fluentd. Refer to the logging documentation [here.](../pages-for-subheaders/cluster-logging.md) -# Monitoring +## Monitoring 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. For details, refer to [Monitoring.](../pages-for-subheaders/cluster-monitoring.md) -# Alerts + +## Alerts After monitoring is enabled, you can set up alerts and notifiers that provide the mechanism to receive them. Alerts are rules that trigger notifications. Before you can receive alerts, you must configure one or more notifier in Rancher. The scope for alerts can be set at either the cluster or project level. For details, refer to [Alerts.](../pages-for-subheaders/cluster-alerts.md) -# Notifiers + +## Notifiers Notifiers are services that inform you of alert events. You can configure notifiers to send alert notifications to staff best suited to take corrective action. Notifications can be sent with Slack, email, PagerDuty, WeChat, and webhooks. For details, refer to [Notifiers.](../explanations/integrations-in-rancher/notifiers.md) -# Istio + +## Istio _Available as of v2.3_ @@ -44,12 +47,11 @@ _Available as of v2.3_ 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. diff --git a/versioned_docs/version-2.0-2.4/reference-guides/rancher-manager-architecture/architecture-recommendations.md b/versioned_docs/version-2.0-2.4/reference-guides/rancher-manager-architecture/architecture-recommendations.md index 5a2d28689de..7f04615b306 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/rancher-manager-architecture/architecture-recommendations.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/rancher-manager-architecture/architecture-recommendations.md @@ -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 cluster 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 @@ In Kubernetes installations of Rancher, the Rancher server cluster should also b ![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. @@ -44,7 +44,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: @@ -57,7 +57,7 @@ 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. @@ -65,7 +65,7 @@ For the best performance and greater security, we recommend a dedicated Kubernet It is not recommended to install Rancher on top of a managed Kubernetes service such as Amazon’s EKS or Google Kubernetes Engine. These hosted Kubernetes solutions do not expose etcd to a degree that is manageable for Rancher, and their customizations can interfere with Rancher operations. -# Recommended Node Roles for Kubernetes Installations +## Recommended Node Roles for Kubernetes Installations Our recommendations for the roles of each node differ depending on whether Rancher is installed on a K3s Kubernetes cluster or an RKE Kubernetes cluster. @@ -107,7 +107,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. diff --git a/versioned_docs/version-2.0-2.4/reference-guides/rancher-project-tools/project-logging.md b/versioned_docs/version-2.0-2.4/reference-guides/rancher-project-tools/project-logging.md index 0a2b5aec5a1..7e314084b10 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/rancher-project-tools/project-logging.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/rancher-project-tools/project-logging.md @@ -18,7 +18,7 @@ Rancher supports the following services: Only [administrators](../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md), [cluster owners or members](../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles), or [project owners](../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles) can configure Rancher to send Kubernetes logs to a logging service. -# Requirements +## Requirements The Docker daemon on each node in the cluster should be [configured](https://docs.docker.com/config/containers/logging/configure/) with the (default) log-driver: `json-file`. You can check the log-driver by running the following command: @@ -27,7 +27,7 @@ $ docker info | grep 'Logging Driver' Logging Driver: json-file ``` -# Advantages +## Advantages Setting up a logging service to collect logs from your cluster/project has several advantages: @@ -36,7 +36,7 @@ Setting up a logging service to collect logs from your cluster/project has sever - Helps you when troubleshooting or debugging. - Saves your logs to a safe location outside of your cluster, so that you can still access them even if your cluster encounters issues. -# Logging Scope +## Logging Scope You can configure logging at either cluster level or project level. @@ -50,7 +50,7 @@ Logs that are sent to your logging service are from the following locations: - Kubernetes system components logs stored at `/var/lib/rancher/rke/logs/`. -# Enabling Project Logging +## Enabling Project Logging 1. From the **Global** view, navigate to the project that you want to configure project logging. @@ -102,6 +102,6 @@ Logs that are sent to your logging service are from the following locations: **Result:** Rancher is now configured to send logs to the selected service. Log into the logging service so that you can start viewing the logs. -# Related Links +## Related Links [Logging Architecture](https://kubernetes.io/docs/concepts/cluster-administration/logging/) diff --git a/versioned_docs/version-2.0-2.4/reference-guides/system-tools.md b/versioned_docs/version-2.0-2.4/reference-guides/system-tools.md index 7af40f196e4..ddde9d731a6 100644 --- a/versioned_docs/version-2.0-2.4/reference-guides/system-tools.md +++ b/versioned_docs/version-2.0-2.4/reference-guides/system-tools.md @@ -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 , -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 , -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 , -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](../pages-for-subheaders/backup-restore-and-disaster-recovery.md) before executing the command. diff --git a/versioned_docs/version-2.0-2.4/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md b/versioned_docs/version-2.0-2.4/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md index 6f45a7a5b86..3680d702ecb 100644 --- a/versioned_docs/version-2.0-2.4/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md +++ b/versioned_docs/version-2.0-2.4/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md @@ -4,7 +4,7 @@ title: Troubleshooting Controlplane Nodes This section applies to nodes with the `controlplane` role. -# Check if the Controlplane Containers are Running +## Check if the Controlplane Containers are Running There are three specific containers launched on nodes with the `controlplane` role: @@ -26,7 +26,7 @@ f3d287ca4549 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." bdf3898b8063 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." 3 hours ago Up 3 hours kube-controller-manager ``` -# Controlplane Container Logging +## Controlplane Container Logging > **Note:** If you added multiple nodes with the `controlplane` role, both `kube-controller-manager` and `kube-scheduler` use a leader election process to determine the leader. Only the current leader will log the performed actions. See [Kubernetes leader election](../other-troubleshooting-tips/kubernetes-resources.md#kubernetes-leader-election) how to retrieve the current leader. diff --git a/versioned_docs/version-2.0-2.4/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md b/versioned_docs/version-2.0-2.4/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md index d7cde4f794e..08d71c4c028 100644 --- a/versioned_docs/version-2.0-2.4/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md +++ b/versioned_docs/version-2.0-2.4/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md @@ -4,7 +4,7 @@ title: Troubleshooting nginx-proxy The `nginx-proxy` container is deployed on every node that does not have the `controlplane` role. It provides access to all the nodes with the `controlplane` role by dynamically generating the NGINX configuration based on available nodes with the `controlplane` role. -# Check if the Container is Running +## Check if the Container is Running The container is called `nginx-proxy` and should have status `Up`. The duration shown after `Up` is the time the container has been running. @@ -20,7 +20,7 @@ CONTAINER ID IMAGE COMMAND CREATED c3e933687c0e rancher/rke-tools:v0.1.15 "nginx-proxy CP_HO..." 3 hours ago Up 3 hours nginx-proxy ``` -# Check Generated NGINX Configuration +## Check Generated NGINX Configuration The generated configuration should include the IP addresses of the nodes with the `controlplane` role. The configuration can be checked using the following command: @@ -59,7 +59,7 @@ stream { } ``` -# nginx-proxy Container Logging +## nginx-proxy Container Logging The logging of the containers can contain information on what the problem could be. diff --git a/versioned_docs/version-2.0-2.4/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md b/versioned_docs/version-2.0-2.4/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md index 6d3a8bd7fcd..66c36f68bb7 100644 --- a/versioned_docs/version-2.0-2.4/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md +++ b/versioned_docs/version-2.0-2.4/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md @@ -4,7 +4,7 @@ title: Troubleshooting Worker Nodes and Generic Components This section applies to every node as it includes components that run on nodes with any role. -# Check if the Containers are Running +## Check if the Containers are Running There are two specific containers launched on nodes with the `worker` role: @@ -24,7 +24,7 @@ CONTAINER ID IMAGE COMMAND a30717ecfb55 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." 3 hours ago Up 3 hours kubelet ``` -# Container Logging +## Container Logging The logging of the containers can contain information on what the problem could be.