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

Merge pull request #3439 from rancher/staging

Browse Source 
Merge staging to master
This commit is contained in:
Catherine Luse
2021-08-30 19:52:21 -07:00
committed by GitHub
parent 7e5dc73ac4 c60816babc
commit 283bedcfb8
444 changed files with 41911 additions and 521 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/_index.html
+23
View File
@@ -91,6 +91,29 @@
<div class="row max-sized cards-container">
<div class="col-12 cards-wrap">
<div class="row center-xs card-items-wrap">
<div class="
col-xl-4
col-lg-4
col-md-4
col-sm-12
col-xs-12
col-12
card-item">
<div class="card-wrap">
<h3 class="title-label">
<span class="background">2.6</span>
Rancher 2.6
</h3>
<hr/>
<p class="description-label">Rancher manages all of your Kubernetes clusters everywhere, unifies them under centralized RBAC, monitors them and lets you easily deploy and manage workloads through an intuitive user interface.</p>
<div class="buttons-container">
<a href="{{<baseurl>}}/rancher/v2.6/en/">Rancher v2.6</a>
</div>
</div>
</div>
<div class="
col-xl-4
col-lg-4
content/rancher/v2.0-v2.4/en/cluster-admin/tools/cluster-monitoring/_index.md
+3 -1
View File
@@ -53,7 +53,7 @@ Using Prometheus, you can monitor Rancher at both the cluster level and [project
As an [administrator]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/global-permissions/) or [cluster owner]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/cluster-project-roles/#cluster-roles), you can configure Rancher to deploy Prometheus to monitor your Kubernetes cluster.
> **Prerequisite:** The following TCP ports need to be opened for metrics scraping:
> **Prerequisites:** The following TCP ports need to be opened for metrics scraping:
>
> | Port | Node type | Component |
> | --- | --- | --- |
@@ -64,6 +64,8 @@ As an [administrator]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/glo
> | 10252 | Controlplane | Kube controller manager |
> | 2379 | Etcd | Etcd server |
> Monitoring V1 requires a Kubernetes verison less than or equal to v1.20.x. To install monitoring on Kubernetes v1.21+, you will need to [migrate to Monitoring V2.]({{<baseurl>}}/rancher/v2.5/en/monitoring-alerting/migrating/)
1. From the **Global** view, navigate to the cluster that you want to configure cluster monitoring.
1. Select **Tools > Monitoring** in the navigation bar.
content/rancher/v2.0-v2.4/en/project-admin/resource-quotas/quotas-for-projects/_index.md
+1 -1
View File
@@ -28,7 +28,7 @@ The resource quota includes two limits, which you set while creating or editing
In the following diagram, a Rancher administrator wants to apply a resource quota that sets the same CPU and memory limit for every namespace in their project (`Namespace 1-4`). However, in Rancher, the administrator can set a resource quota for the project (`Project Resource Quota`) rather than individual namespaces. This quota includes resource limits for both the entire project (`Project Limit`) and individual namespaces (`Namespace Default Limit`). Rancher then propagates the `Namespace Default Limit` quotas to each namespace (`Namespace Resource Quota`) when created.
<sup>Rancher: Resource Quotas Propagating to Each Namespace</sup>
![Rancher Resource Quota Implementation]({{<baseurl>}}/img/rancher/rancher-resource-quota.svg)
![Rancher Resource Quota Implementation]({{<baseurl>}}/img/rancher/rancher-resource-quota.png)
Let's highlight some more nuanced functionality. If a quota is deleted at the project level, it will also be removed from all namespaces contained within that project, despite any overrides that may exist. Further, updating an existing namespace default limit for a quota at the project level will not result in that value being propagated to existing namespaces in the project; the updated value will only be applied to newly created namespaces in that project. To update a namespace default limit for existing namespaces you can delete and subsequently recreate the quota at the project level with the new default value. This will result in the new default value being applied to all existing namespaces in the project.
content/rancher/v2.5/_index.md
+2 -2
View File
@@ -1,5 +1,5 @@
---
title: Rancher 2.5.7-2.5.9 (Latest)
weight: 1
title: Rancher 2.5.7-2.5.9
weight: 2
showBreadcrumb: false
---
content/rancher/v2.5/en/_index.md
+3 -3
View File
@@ -1,11 +1,11 @@
---
title: "Rancher 2.5.7-2.5.9 (Latest)"
shortTitle: "Rancher 2.5.7-2.5.9 (Latest)"
title: "Rancher 2.5.7-2.5.9"
shortTitle: "Rancher 2.5.7-2.5.8+"
description: "Rancher adds significant value on top of Kubernetes: managing hundreds of clusters from one interface, centralizing RBAC, enabling monitoring and alerting. Read more."
metaTitle: "Rancher 2.5.7-2.5.9 Docs: What is New?"
metaDescription: "Rancher 2 adds significant value on top of Kubernetes: managing hundreds of clusters from one interface, centralizing RBAC, enabling monitoring and alerting. Read more."
insertOneSix: false
weight: 1
weight: 2
ctaBanner: 0
---
Rancher was originally built to work with multiple orchestrators, and it included its own orchestrator called Cattle. With the rise of Kubernetes in the marketplace, Rancher 2 exclusively deploys and manages Kubernetes clusters running anywhere, on any provider.
content/rancher/v2.5/en/admin-settings/authentication/keycloak/_index.md
+21 -19
View File
@@ -61,24 +61,7 @@ If your organization uses Keycloak Identity Provider (IdP) for user authenticati
1. Select **Keycloak**.
1. Complete the **Configure Keycloak Account** form.
| Field | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Display Name Field | The attribute that contains the display name of users. <br/><br/>Example: `givenName` |
| User Name Field | The attribute that contains the user name/given name. <br/><br/>Example: `email` |
| UID Field | An attribute that is unique to every user. <br/><br/>Example: `email` |
| Groups Field | Make entries for managing group memberships. <br/><br/>Example: `member` |
| Entity ID Field | The ID that needs to be configured as a client ID in the Keycloak client. <br/><br/>Default: `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata` |
| Rancher API Host | The URL for your Rancher Server. |
| Private Key / Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP. |
| IDP-metadata | The `metadata.xml` file that you exported from your IdP server. |
>**Tip:** You can generate a key/certificate pair using an openssl command. For example:
>
> openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert
1. Complete the **Configure Keycloak Account** form. For help with filling the form, see the [configuration reference](#configuration-reference).
1. After you complete the **Configure Keycloak Account** form, click **Authenticate with Keycloak**, which is at the bottom of the page.
@@ -90,13 +73,32 @@ If your organization uses Keycloak Identity Provider (IdP) for user authenticati
{{< saml_caveats >}}
## Configuration Reference
| Field | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Display Name Field | The attribute that contains the display name of users. <br/><br/>Example: `givenName` |
| User Name Field | The attribute that contains the user name/given name. <br/><br/>Example: `email` |
| UID Field | An attribute that is unique to every user. <br/><br/>Example: `email` |
| Groups Field | Make entries for managing group memberships. <br/><br/>Example: `member` |
| Entity ID Field | The ID that needs to be configured as a client ID in the Keycloak client. <br/><br/>Default: `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata` |
| Rancher API Host | The URL for your Rancher Server. |
| Private Key / Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP. |
| IDP-metadata | The `metadata.xml` file that you exported from your IdP server. |
>**Tip:** You can generate a key/certificate pair using an openssl command. For example:
>
> openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert
## Annex: Troubleshooting
If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration option of your SAML client. 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]({{<baseurl>}}/rancher/v2.5/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
### You are not redirected to Keycloak
When you click on **Authenticate with Keycloak**, your are not redirected to your IdP.
When you click on **Authenticate with Keycloak**, you are not redirected to your IdP.
* Verify your Keycloak client configuration.
* Make sure `Force Post Binding` set to `OFF`.
content/rancher/v2.5/en/admin-settings/rbac/global-permissions/_index.md
+2 -2
View File
@@ -46,7 +46,7 @@ CATTLE_RESTRICTED_DEFAULT_ADMIN=true
The permissions for the `restricted-admin` role differ based on the Rancher version.
{{% tabs %}}
{{% tab "v2.5.6" %}}
{{% tab "v2.5.7+" %}}
The `restricted-admin` permissions are as follows:
@@ -55,7 +55,7 @@ The `restricted-admin` permissions are as follows:
- Can create other restricted admins.
{{% /tab %}}
{{% tab "v2.5.0-v2.5.5" %}}
{{% tab "v2.5.0-v2.5.6" %}}
The `restricted-admin` permissions are as follows:
content/rancher/v2.5/en/cluster-admin/nodes/_index.md
+1 -14
View File
@@ -175,19 +175,6 @@ You can label nodes to be ignored by using a setting in the Rancher UI, or by us
> **Note:** There is an [open issue](https://github.com/rancher/rancher/issues/24172) in which nodes labeled to be ignored can get stuck in an updating state.
### Labeling Nodes to be Ignored with the Rancher UI
To add a node that is ignored by Rancher,
1. From the **Global** view, click the **Settings** tab.
1. Go to the `ignore-node-name` setting and click **&#8942; > Edit.**
1. Enter a name that Rancher will use to ignore nodes. All nodes with this name will be ignored.
1. Click **Save.**
**Result:** Rancher will not wait to register nodes with this name. In the UI, the node will displayed with a grayed-out status. The node is still part of the cluster and can be listed with `kubectl`.
If the setting is changed afterward, the ignored nodes will continue to be hidden.
### Labeling Nodes to be Ignored with kubectl
To add a node that will be ignored by Rancher, use `kubectl` to create a node that has the following label:
@@ -202,4 +189,4 @@ If the label is added before the node is added to the cluster, the node will not
If the label is added after the node is added to a Rancher cluster, the node will not be removed from the UI.
If you delete the node from the Rancher server using the Rancher UI or API, the node will not be removed from the cluster if the `nodeName` is listed in the Rancher settings under `ignore-node-name`.
If you delete the node from the Rancher server using the Rancher UI or API, the node will not be removed from the cluster if the `nodeName` is listed in the Rancher settings in the Rancher API under `v3/settings/ignore-node-name`.
content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/aks/_index.md
+6 -4
View File
@@ -114,16 +114,18 @@ To give role-based access to your service principal,
Use Rancher to set up and configure your Kubernetes cluster.
1. From the **Clusters** page, click **Add Cluster**.
1. In the upper left corner, click **≡ > Cluster Management.**
1. Choose **Azure Kubernetes Service**.
1. From the **Clusters** page, click **Create**.
1. Choose **Azure AKS**.
1. Enter a **Cluster Name**.
1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user.
1. Use your subscription ID, tenant ID, app ID, and client secret to give your cluster access to AKS. If you don't have all of that information, you can retrieve it using these instructions:
- **App ID and tenant ID:** To get the app ID and tenant ID, you can go to the Azure Portal, then click **Azure Active Directory**, then click **App registrations,** then click the name of the service principal. The app ID and tenant ID are both on the app registration detail page.
1. Use your subscription ID, client ID, and client secret to give your cluster access to AKS. If you don't have all of that information, you can retrieve it using these instructions:
- **Client ID:** To get the Client ID, you can go to the Azure Portal, then click **Azure Active Directory**, then click **Enterprise applications.** Click **All applications.** Select your application, click **Properties,** and copy the application ID.
- **Client secret:** If you didn't copy the client secret when creating the service principal, you can get a new one if you go to the app registration detail page, then click **Certificates & secrets**, then click **New client secret.**
- **Subscription ID:** You can get the subscription ID is available in the portal from **All services > Subscriptions.**
content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/eks/_index.md
+3 -1
View File
@@ -49,7 +49,9 @@ For more detailed information on IAM policies for EKS, refer to the official [do
Use Rancher to set up and configure your Kubernetes cluster.
1. From the **Clusters** page, click **Add Cluster**.
1. In the upper left corner, click **≡ > Cluster Management.**
1. From the **Clusters** page, click **Create**.
1. Choose **Amazon EKS**.
content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/_index.md
+3 -2
View File
@@ -63,8 +63,9 @@ To get the project ID of an existing project, refer to the Google cloud document
### 2. Create the GKE Cluster
Use Rancher to set up and configure your Kubernetes cluster.
1. From the **Clusters** page, click **Add Cluster**.
1. Under **With a hosted Kubernetes provider,** click **Google GKE**.
1. In the upper left corner, click **≡ > Cluster Management.**
1. From the **Clusters** page, click **Create**.
1. Click **Google GKE**.
1. Enter a **Cluster Name**.
1. Optional: Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user.
1. Optional: 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.
content/rancher/v2.5/en/cluster-provisioning/registered-clusters/_index.md
+3 -2
View File
@@ -36,8 +36,9 @@ If you are registering a K3s cluster, make sure the `cluster.yml` is readable. I
# Registering a Cluster
1. From the **Clusters** page, click **Add Cluster**.
2. Choose **Register**.
1. In the upper left corner, click **≡ > Cluster Management.**
1. From the **Clusters** page, click **Import Existing**.
2. Click the type of Kubernetes cluster you want to import.
3. Enter a **Cluster Name**.
4. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user.
5. For Rancher v2.5.6+, use **Agent Environment Variables** under **Cluster Options** to set environment variables for [rancher cluster agent]({{<baseurl>}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/rancher-agents/). The environment variables can be set using key value pairs. If rancher agent requires use of proxy to communicate with Rancher server, `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables can be set using agent environment variables.
content/rancher/v2.5/en/cluster-provisioning/rke-clusters/cloud-providers/vsphere/out-of-tree/_index.md
+4 -2
View File
@@ -23,8 +23,10 @@ The Cloud Provider Interface (CPI) should be installed first before installing t
### 1. Create a vSphere cluster
1. On the Clusters page, click on **Add Cluster** and select the **vSphere** option or **Existing Nodes** option.
1. Under **Cluster Options > Cloud Provider** select **External (Out-of-tree)**. This sets the cloud provider option on the Kubernetes cluster to `external` which sets your Kubernetes cluster up to be configured with an out-of-tree cloud provider.
1. In the upper left corner, click **≡ > Cluster Management.**
1. From the **Clusters** page, click **Create.**
1. Click **VMWare vSphere.**
1. Under **Cluster Options** in the **Cloud Provider** section, select **External (Out-of-tree)**. This sets the cloud provider option on the Kubernetes cluster to `external` which sets your Kubernetes cluster up to be configured with an out-of-tree cloud provider.
1. Finish creating your cluster.
### 2. Install the CPI plugin
content/rancher/v2.5/en/cluster-provisioning/rke-clusters/custom-nodes/_index.md
+13 -11
View File
@@ -44,38 +44,40 @@ Provision the host according to the [installation requirements]({{<baseurl>}}/ra
Clusters won't begin provisioning until all three node roles (worker, etcd and controlplane) are present.
1. From the **Clusters** page, click **Add Cluster**.
1. In the upper left corner, click **≡ > Cluster Management.**
2. Choose **Custom**.
1. From the **Clusters** page, click **Create.**
3. Enter a **Cluster Name**.
1. Click **Custom.**
4. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user.
1. Enter a **Cluster Name**.
5. Use **Cluster Options** to choose the version of Kubernetes, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on **Show advanced options.**
1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user.
1. Use **Cluster Options** to choose the version of Kubernetes, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on **Show advanced options.**
>**Using Windows nodes as Kubernetes workers?**
>
>- See [Enable the Windows Support Option]({{<baseurl>}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/windows-clusters/).
>- The only Network Provider available for clusters with Windows support is Flannel.
6. <a id="step-6"></a>Click **Next**.
1. <a id="step-6"></a>Click **Next**.
7. From **Node Role**, choose the roles that you want filled by a cluster node. You must provision at least one node for each role: `etcd`, `worker`, and `control plane`. All three roles are required for a custom cluster to finish provisioning. For more information on roles, see [this section.]({{<baseurl>}}/rancher/v2.5/en/overview/concepts/#roles-for-nodes-in-kubernetes-clusters)
1. From **Node Role**, choose the roles that you want filled by a cluster node. You must provision at least one node for each role: `etcd`, `worker`, and `control plane`. All three roles are required for a custom cluster to finish provisioning. For more information on roles, see [this section.]({{<baseurl>}}/rancher/v2.5/en/overview/concepts/#roles-for-nodes-in-kubernetes-clusters)
>**Notes:**
>
>- Using Windows nodes as Kubernetes workers? See [this section]({{<baseurl>}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/windows-clusters/).
>- Bare-Metal Server Reminder: If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers).
8. <a id="step-8"></a>**Optional**: Click **[Show advanced options]({{<baseurl>}}/rancher/v2.5/en/admin-settings/agent-options/)** to specify IP address(es) to use when registering the node, override the hostname of the node, or to add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) to the node.
1. <a id="step-8"></a>**Optional**: Click **[Show advanced options]({{<baseurl>}}/rancher/v2.5/en/admin-settings/agent-options/)** to specify IP address(es) to use when registering the node, override the hostname of the node, or to add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) to the node.
9. Copy the command displayed on screen to your clipboard.
1. Copy the command displayed on screen to your clipboard.
10. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard.
1. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard.
>**Note:** Repeat steps 7-10 if you want to dedicate specific hosts to specific node roles. Repeat the steps as many times as needed.
11. When you finish running the command(s) on your Linux host(s), click **Done**.
1. When you finish running the command(s) on your Linux host(s), click **Done**.
**Result:**
content/rancher/v2.5/en/cluster-provisioning/rke-clusters/node-pools/_index.md
+4 -4
View File
@@ -100,8 +100,8 @@ When you create the node pool, you can specify the amount of time in minutes tha
You can also enable node auto-replace after the cluster is created with the following steps:
1. From the Global view, click the Clusters tab.
1. Go to the cluster where you want to enable node auto-replace, click the vertical &#8942; **(…)**, and click **Edit.**
1. In the upper left corner, click **≡ > Cluster Management.**
1. In the list of clusters, go to the cluster where you want to enable node auto-replace. Click the vertical &#8942; **(…)**, and click **Edit Config.**
1. In the **Node Pools** section, go to the node pool where you want to enable node auto-replace. In the **Recreate Unreachable After** field, enter the number of minutes that Rancher should wait for a node to respond before replacing the node.
1. Click **Save.**
@@ -111,8 +111,8 @@ You can also enable node auto-replace after the cluster is created with the foll
You can disable node auto-replace from the Rancher UI with the following steps:
1. From the Global view, click the Clusters tab.
1. Go to the cluster where you want to enable node auto-replace, click the vertical &#8942; **(…)**, and click **Edit.**
1. In the upper left corner, click **≡ > Cluster Management.**
1. In the list of clusters, go to the cluster where you want to enable node auto-replace. Click the vertical &#8942; **(…)**, and click **Edit Config.**
1. In the **Node Pools** section, go to the node pool where you want to enable node auto-replace. In the **Recreate Unreachable After** field, enter 0.
1. Click **Save.**
content/rancher/v2.5/en/cluster-provisioning/rke-clusters/node-pools/azure/_index.md
+8 -5
View File
@@ -45,10 +45,11 @@ The creation of this service principal returns three pieces of identification in
### 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.**
1. In the upper left corner, click **≡ > Cluster Management.**
1. In the left navigation menu, click **Cloud Credentials.**
1. Click **Create.**
1. Click **Azure.**
1. Enter a name for the cloud credential.
1. In the **Cloud Credential Type** field, select **Azure**.
1. Enter your Azure credentials.
1. Click **Create.**
@@ -58,7 +59,8 @@ The creation of this service principal returns three pieces of identification in
Creating a [node template]({{<baseurl>}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/node-pools/#node-templates) for Azure will allow Rancher to provision new nodes in Azure. Node templates can be reused for other clusters.
1. In the Rancher UI, click the user profile button in the upper right corner, and click **Node Templates.**
1. In the upper left corner, click **≡ > Cluster Management.**
1. In the left navigation menu, click **Node Templates.**
1. Click **Add Template.**
1. Fill out a node template for Azure. For help filling out the form, refer to [Azure Node Template Configuration.](./azure-node-template-config)
@@ -68,7 +70,8 @@ Use Rancher to create a Kubernetes cluster in Azure.
Clusters won't begin provisioning until all three node roles (worker, etcd and controlplane) are present.
1. From the **Clusters** page, click **Add Cluster**.
1. In the upper left corner, click **≡ > Cluster Management**.
1. Click **Create**.
1. Choose **Azure**.
1. Enter a **Cluster Name**.
1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user.
content/rancher/v2.5/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/_index.md
+8 -6
View File
@@ -18,10 +18,11 @@ Then you will create a DigitalOcean cluster in Rancher, and when configuring the
### 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.**
1. In the upper left corner, click **≡ > Cluster Management.**
1. In the left navigation menu, click **Cloud Credentials.**
1. Click **Create.**
1. Click **Digital Ocean.**
1. Enter a name for the cloud credential.
1. In the **Cloud Credential Type** field, select **DigitalOcean**.
1. Enter your Digital Ocean credentials.
1. Click **Create.**
@@ -31,15 +32,16 @@ Then you will create a DigitalOcean cluster in Rancher, and when configuring the
Creating a [node template]({{<baseurl>}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/node-pools/#node-templates) for DigitalOcean will allow Rancher to provision new nodes in DigitalOcean. Node templates can be reused for other clusters.
1. In the Rancher UI, click the user profile button in the upper right corner, and click **Node Templates.**
1. Click **Add Template.**
1. In the upper left corner, click **≡ > Cluster Management.**
1. In the left navigation menu, click **Node Templates.**
1. Fill out a node template for DigitalOcean. For help filling out the form, refer to [DigitalOcean Node Template Configuration.](./do-node-template-config)
### 3. Create a cluster with node pools using the node template
Clusters won't begin provisioning until all three node roles (worker, etcd and controlplane) are present.
1. From the **Clusters** page, click **Add Cluster**.
1. In the upper left corner, click **≡ > Cluster Management**.
1. Click **Create**.
1. Choose **DigitalOcean**.
1. Enter a **Cluster Name**.
1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user.
content/rancher/v2.5/en/cluster-provisioning/rke-clusters/node-pools/ec2/_index.md
+10 -7
View File
@@ -29,12 +29,13 @@ The steps to create a cluster differ based on your Rancher version.
### 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.**
1. In the upper left corner, click **≡ > Cluster Management.**
1. In the left navigation menu, click **Cloud Credentials.**
1. Click **Create.**
1. Click **Amazon.**
1. Enter a name for the cloud credential.
1. In the **Cloud Credential Type** field, select **Amazon.**
1. In the **Region** field, select the AWS region where your cluster nodes will be located.
1. Enter your AWS EC2 **Access Key** and **Secret Key.**
1. In the **Default Region** field, select the AWS region where your cluster nodes will be located.
1. Click **Create.**
**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.
@@ -43,8 +44,8 @@ The steps to create a cluster differ based on your Rancher version.
Creating a [node template]({{<baseurl>}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/node-pools/#node-templates) for EC2 will allow Rancher to provision new nodes in EC2. Node templates can be reused for other clusters.
1. In the Rancher UI, click the user profile button in the upper right corner, and click **Node Templates.**
1. Click **Add Template.**
1. In the upper left corner, click **≡ > Cluster Management.**
1. In the left navigation menu, click **Node Templates.**
1. Fill out a node template for EC2. For help filling out the form, refer to [EC2 Node Template Configuration.](./ec2-node-template-config)
### 3. Create a cluster with node pools using the node template
@@ -53,7 +54,8 @@ Add one or more node pools to your cluster. For more information about node pool
Clusters won't begin provisioning until all three node roles (worker, etcd and controlplane) are present.
1. From the **Clusters** page, click **Add Cluster**.
1. In the upper left corner, click **≡ > Cluster Management**.
1. Click **Create**.
1. Choose **Amazon EC2**.
1. Enter a **Cluster Name**.
1. Create a node pool for each Kubernetes role. For each node pool, choose a node template that you created. For more information about node pools, including best practices for assigning Kubernetes roles to them, see [this section.]({{<baseurl>}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/node-pools)
@@ -71,6 +73,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:
content/rancher/v2.5/en/cluster-provisioning/rke-clusters/node-pools/vsphere/provisioning-vsphere-clusters/_index.md
+9 -8
View File
@@ -56,10 +56,10 @@ The a vSphere cluster is created in Rancher depends on the Rancher version.
### 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.**
1. Enter a name for the cloud credential.
1. In the **Cloud Credential Type** field, select **vSphere**.
1. In the upper left corner, click **≡ > Cluster Management.**
1. In the left navigation menu, click **Cloud Credentials.**
1. Click **Create.**
1. Click **VMware vSphere.**
1. Enter your vSphere credentials. For help, refer to **Account Access** in the [node template configuration reference.]({{<baseurl>}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/node-pools/vsphere/vsphere-node-template-config/)
1. Click **Create.**
@@ -69,8 +69,8 @@ The a vSphere cluster is created in Rancher depends on the Rancher version.
Creating a [node template]({{<baseurl>}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/node-pools/#node-templates) for vSphere will allow Rancher to provision new nodes in vSphere. Node templates can be reused for other clusters.
1. In the Rancher UI, click the user profile button in the upper right corner, and click **Node Templates.**
1. Click **Add Template.**
1. In the upper left corner, click **≡ > Cluster Management.**
1. In the left navigation menu, click **Node Templates.**
1. Fill out a node template for vSphere. For help filling out the form, refer to the vSphere node template [configuration reference.]({{<baseurl>}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/node-pools/vsphere/vsphere-node-template-config/).
### 3. Create a cluster with node pools using the node template
@@ -79,8 +79,9 @@ Use Rancher to create a Kubernetes cluster in vSphere.
Clusters won't begin provisioning until all three node roles (worker, etcd and controlplane) are present.
1. Navigate to **Clusters** in the **Global** view.
1. Click **Add Cluster** and select the **vSphere** infrastructure provider.
1. In the upper left corner, click **≡ > Cluster Management**.
1. Click **Create**.
1. Select the **VMware vSphere** infrastructure provider.
1. Enter a **Cluster Name.**
1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user.
1. Use **Cluster Options** to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on **Show advanced options.** For help configuring the cluster, refer to the [RKE cluster configuration reference.]({{<baseurl>}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/options)
content/rancher/v2.5/en/deploy-across-clusters/fleet/_index.md
+21 -21
View File
@@ -9,39 +9,39 @@ Fleet is GitOps at scale. Fleet is designed to manage up to a million clusters.
Fleet is a separate project from Rancher, and can be installed on any Kubernetes cluster with Helm.
![Architecture]({{<baseurl>}}/img/rancher/fleet-architecture.png)
- [Architecture](#architecture)
- [Accessing Fleet in the Rancher UI](#accessing-fleet-in-the-rancher-ui)
- [Windows Support](#windows-support)
- [GitHub Repository](#github-repository)
- [Documentation](#documentation)
Fleet can manage deployments from git of raw Kubernetes YAML, Helm charts, or Kustomize or any combination of the three. Regardless of the source, all resources are dynamically turned into Helm charts, and Helm is used as the engine to deploy everything in the cluster. This gives you a high degree of control, consistency, and auditability. Fleet focuses not only on the ability to scale, but to give one a high degree of control and visibility to exactly what is installed on the cluster.
# Architecture
### Accessing Fleet in the Rancher UI
For information about how Fleet works, see [this page.](./architecture)
# Accessing Fleet in the Rancher UI
Fleet comes preinstalled in Rancher v2.5. To access it, go to the **Cluster Explorer** in the Rancher UI. In the top left dropdown menu, click **Cluster Explorer > Continuous Delivery.** On this page, you can edit Kubernetes resources and cluster groups managed by Fleet.
### Windows Support
# Windows Support
Prior to Rancher v2.5.6, the `agent` did not have native Windows manifests on downstream clusters with Windows nodes.
This would result in a failing `agent` pod for the cluster.
If you are upgrading from an older version of Rancher to v2.5.6+, you can deploy a working `agent` with the following workflow *in the downstream cluster*:
_Available as of v2.5.6_
1. Cordon all Windows nodes.
1. Apply the below toleration to the `agent` workload.
1. Uncordon all Windows nodes.
1. Delete all `agent` pods. New pods should be created with the new toleration.
1. Once the `agent` pods are running, and auto-update is enabled for Fleet, they should be updated to a Windows-compatible `agent` version.
For details on support for clusters with Windows nodes, see [this page.](./windows)
```yaml
tolerations:
- effect: NoSchedule
key: cattle.io/os
operator: Equal
value: linux
```
### GitHub Repository
# GitHub Repository
The Fleet Helm charts are available [here.](https://github.com/rancher/fleet/releases/latest)
### Documentation
# Using Fleet Behind a Proxy
_Available as of v2.5.8_
For details on using Fleet behind a proxy, see [this page.](./proxy)
# Documentation
The Fleet documentation is at [https://fleet.rancher.io/.](https://fleet.rancher.io/)
content/rancher/v2.5/en/deploy-across-clusters/fleet/architecture/_index.md
+9
View File
@@ -0,0 +1,9 @@
---
title: Architecture
weight: 1
---
Fleet can manage deployments from git of raw Kubernetes YAML, Helm charts, or Kustomize or any combination of the three. Regardless of the source, all resources are dynamically turned into Helm charts, and Helm is used as the engine to deploy everything in the cluster. This gives you a high degree of control, consistency, and auditability. Fleet focuses not only on the ability to scale, but to give one a high degree of control and visibility to exactly what is installed on the cluster.
![Architecture]({{<baseurl>}}/img/rancher/fleet-architecture.png)
content/rancher/v2.5/en/deploy-across-clusters/fleet/proxy/_index.md
+1 -1
View File
@@ -9,7 +9,7 @@ In this section, you'll learn how to enable Fleet in a setup that has a Rancher
Rancher does not establish connections with registered downstream clusters. The Rancher agent deployed on the downstream cluster must be able to establish the connection with Rancher.
To set up Fleet to work behind a proxy, you will need to set the **Agent Environment Variables* * for the downstream cluster. These are cluster-level configuration options.
To set up Fleet to work behind a proxy, you will need to set the **Agent Environment Variables** for the downstream cluster. These are cluster-level configuration options.
Through the Rancher UI, you can configure these environment variables for any cluster type, including registered and custom clusters. The variables can be added while editing an existing cluster or while provisioning a new cluster.
content/rancher/v2.5/en/deploy-across-clusters/fleet/windows/_index.md
+23
View File
@@ -0,0 +1,23 @@
---
title: Windows Support
weight: 2
---
Prior to Rancher v2.5.6, the `agent` did not have native Windows manifests on downstream clusters with Windows nodes. This would result in a failing `agent` pod for the cluster.
If you are upgrading from an older version of Rancher to v2.5.6+, you can deploy a working `agent` with the following workflow *in the downstream cluster*:
1. Cordon all Windows nodes.
1. Apply the below toleration to the `agent` workload.
1. Uncordon all Windows nodes.
1. Delete all `agent` pods. New pods should be created with the new toleration.
1. Once the `agent` pods are running, and auto-update is enabled for Fleet, they should be updated to a Windows-compatible `agent` version.
```yaml
tolerations:
- effect: NoSchedule
key: cattle.io/os
operator: Equal
value: linux
```
content/rancher/v2.5/en/helm-charts/_index.md
+12 -7
View File
@@ -12,7 +12,7 @@ In this section, you'll learn how to manage Helm chart repositories and applicat
### Changes in Rancher v2.5
In Rancher v2.5, the Apps and Marketplace feature replaced the catalog system.
In Rancher v2.5, the Apps and Marketplace feature replaced the catalog system.
In the cluster manager, Rancher uses a catalog system to import bundles of charts and then uses those charts to either deploy custom helm applications or Rancher's tools such as Monitoring or Istio. The catalog system is still available in the cluster manager in Rancher v2.5, but it is deprecated.
@@ -20,9 +20,9 @@ Now in the Cluster Explorer, Rancher uses a similar but simplified version of th
### Charts
From the top-left menu select _"Apps & Marketplace"_ and you will be taken to the Charts page.
From the top-left menu select _"Apps & Marketplace"_ and you will be taken to the Charts page.
The charts page contains all Rancher, Partner, and Custom Charts.
The charts page contains all Rancher, Partner, and Custom Charts.
* Rancher tools such as Logging or Monitoring are included under the Rancher label
* Partner charts reside under the Partners label
@@ -34,22 +34,27 @@ All three types are deployed and managed in the same way.
### Repositories
From the left sidebar select _"Repositories"_.
From the left sidebar select _"Repositories"_.
These items represent helm repositories, and can be either traditional helm endpoints which have an index.yaml, or git repositories which will be cloned and can point to a specific branch. In order to use custom charts, simply add your repository here and they will become available in the Charts tab under the name of the repository.
### Helm Compatibility
The Cluster Explorer only supports Helm 3 compatible charts.
The Cluster Explorer only supports Helm 3 compatible charts.
### Deployment and Upgrades
From the _"Charts"_ tab select a Chart to install. Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files, but all chart installations can modify the values.yaml and other basic settings. Once you click install, a Helm operation job is deployed, and the console for the job is displayed.
From the _"Charts"_ tab select a Chart to install. Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files, but all chart installations can modify the values.yaml and other basic settings. Once you click install, a Helm operation job is deployed, and the console for the job is displayed.
To view all recent changes, go to the _"Recent Operations"_ tab. From there you can view the call that was made, conditions, events, and logs.
After installing a chart, you can find it in the _"Installed Apps"_ tab. In this section you can upgrade or delete the installation, and see further details. When choosing to upgrade, the form and values presented will be the same as installation.
Most Rancher tools have additional pages located in the toolbar below the _"Apps & Marketplace"_ section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information.
Most Rancher tools have additional pages located in the toolbar below the _"Apps & Marketplace"_ section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information.
> If you are upgrading your chart using _"Customize Helm options before upgrade"_ , please be aware that using the _"--force"_ option may result in errors if your chart has immutable fields. This is because some objects in Kubernetes cannot be changed once they are created. To ensure you do not get this error you can:
* use the default upgrade option ( i.e do not use _"--force"_ option )
* uninstall the existing chart and install the upgraded chart
* delete the resources with immutable fields from the cluster before performing the _"--force"_ upgrade
content/rancher/v2.5/en/installation/install-rancher-on-k8s/_index.md
+6 -18
View File
@@ -122,21 +122,8 @@ This step is only required to use certificates issued by Rancher's generated CA
These instructions are adapted from the [official cert-manager documentation](https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm).
```
# Install the CustomResourceDefinition resources separately
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.0.4/cert-manager.crds.yaml
# **Important:**
# If you are running Kubernetes v1.15 or below, you
# will need to add the `--validate=false` flag to your
# kubectl apply command, or else you will receive a
# validation error relating to the
# x-kubernetes-preserve-unknown-fields field in
# cert-manager’s CustomResourceDefinition resources.
# This is a benign error and occurs due to the way kubectl
# performs resource validation.
# Create the namespace for cert-manager
kubectl create namespace cert-manager
# If you have installed the CRDs manually instead of with the `--set installCRDs=true` option added to your Helm install command, you should upgrade your CRD resources before upgrading the Helm chart:
kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.1/cert-manager.crds.yaml
# Add the Jetstack Helm repository
helm repo add jetstack https://charts.jetstack.io
@@ -145,10 +132,11 @@ helm repo add jetstack https://charts.jetstack.io
helm repo update
# Install the cert-manager Helm chart
helm install \
cert-manager jetstack/cert-manager \
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--version v1.0.4
--create-namespace \
--version v1.5.1 \
--set installCRDs=true
```
Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:
content/rancher/v2.5/en/installation/other-installation-methods/air-gap/install-rancher/_index.md
+3 -3
View File
@@ -102,7 +102,7 @@ helm repo update
Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager).
```plain
helm fetch jetstack/cert-manager --version v1.0.4
helm fetch jetstack/cert-manager --version v1.5.1
```
### 3. Render the cert-manager template
@@ -110,7 +110,7 @@ helm fetch jetstack/cert-manager --version v1.0.4
Render the cert-manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files.
```plain
helm template cert-manager ./cert-manager-v1.0.4.tgz --output-dir . \
helm template cert-manager ./cert-manager-v1.5.1.tgz --output-dir . \
--namespace cert-manager \
--set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller \
--set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook \
@@ -121,7 +121,7 @@ helm template cert-manager ./cert-manager-v1.0.4.tgz --output-dir . \
Download the required CRD file for cert-manager:
```plain
curl -L -o cert-manager/cert-manager-crd.yaml https://github.com/jetstack/cert-manager/releases/download/v1.0.4/cert-manager.crds.yaml
curl -L -o cert-manager/cert-manager-crd.yaml https://github.com/jetstack/cert-manager/releases/download/v1.5.1/cert-manager.crds.yaml
```
### 5. Render the Rancher template
content/rancher/v2.5/en/installation/other-installation-methods/air-gap/populate-private-registry/_index.md
+1 -1
View File
@@ -64,7 +64,7 @@ In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS
```plain
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm fetch jetstack/cert-manager --version v1.0.4
helm fetch jetstack/cert-manager --version v1.5.1
helm template ./cert-manager-<version>.tgz | grep -oP '(?<=image: ").*(?=")' >> ./rancher-images.txt
```
content/rancher/v2.5/en/installation/requirements/installing-docker/_index.md
+2 -2
View File
@@ -9,10 +9,10 @@ There are a couple of options for installing Docker. One option is to refer to t
Another option is to use one of Rancher's Docker installation scripts, which are available for most recent versions of Docker.
For example, this command could be used to install Docker 19.03 on Ubuntu:
For example, this command could be used to install Docker 20.10 on Ubuntu:
```
curl https://releases.rancher.com/install-docker/19.03.sh | sh
curl https://releases.rancher.com/install-docker/20.10.sh | sh
```
Rancher has installation scripts for every version of upstream Docker that Kubernetes supports. To find out whether a script is available for installing a certain Docker version, refer to this [GitHub repository,](https://github.com/rancher/install-docker) which contains all of Rancher's Docker installation scripts.
content/rancher/v2.5/en/monitoring-alerting/_index.md
+53 -182
View File
@@ -9,125 +9,88 @@ aliases:
- /rancher/v2.5/en/cluster-admin/tools/monitoring/
---
Using Rancher, you can quickly deploy leading open-source monitoring alerting solutions onto your cluster.
Using the `rancher-monitoring` application, you can quickly deploy leading open-source monitoring and alerting solutions onto your cluster.
The `rancher-monitoring` operator, introduced in Rancher v2.5, is powered by [Prometheus](https://prometheus.io/), [Grafana](https://grafana.com/grafana/), [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/), the [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator), and the [Prometheus adapter.](https://github.com/DirectXMan12/k8s-prometheus-adapter) This page describes how to enable monitoring and alerting within a cluster using the new monitoring application.
Rancher's solution allows users to:
- Monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments via Prometheus, a leading open-source monitoring solution.
- Define alerts based on metrics collected via Prometheus
- Create custom dashboards to make it easy to visualize collected metrics via Grafana
- Configure alert-based notifications via Email, Slack, PagerDuty, etc. using Prometheus Alertmanager
- Defines precomputed, frequently needed or computationally expensive expressions as new time series based on metrics collected via Prometheus (only available in 2.5)
- Expose collected metrics from Prometheus to the Kubernetes Custom Metrics API via Prometheus Adapter for use in HPA (only available in 2.5)
More information about the resources that get deployed onto your cluster to support this solution can be found in the [`rancher-monitoring`](https://github.com/rancher/charts/tree/main/charts/rancher-monitoring) Helm chart, which closely tracks the upstream [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) Helm chart maintained by the Prometheus community with certain changes tracked in the [CHANGELOG.md](https://github.com/rancher/charts/blob/main/charts/rancher-monitoring/CHANGELOG.md).
> If you previously enabled Monitoring, Alerting, or Notifiers in Rancher before v2.5, there is no upgrade path for switching to the new monitoring/ alerting solution. You will need to disable monitoring/ alerting/notifiers in Cluster Manager before deploying the new monitoring solution via Cluster Explorer.
For more information about upgrading the Monitoring app in Rancher 2.5, please refer to the [migration docs](./migrating).
- [About Prometheus](#about-prometheus)
- [Enable Monitoring](#enable-monitoring)
- [Default Alerts, Targets, and Grafana Dashboards](#default-alerts-targets-and-grafana-dashboards)
- [Features](#features)
- [How Monitoring Works](#how-monitoring-works)
- [Default Components and Deployments](#default-components-and-deployments)
- [Role-based Access Control](#role-based-access-control)
- [Guides](#guides)
- [Windows Cluster Support](#windows-cluster-support)
- [Using Monitoring](#using-monitoring)
- [Grafana UI](#grafana-ui)
- [Prometheus UI](#prometheus-ui)
- [Viewing the Prometheus Targets](#viewing-the-prometheus-targets)
- [Viewing the PrometheusRules](#viewing-the-prometheusrules)
- [Viewing Active Alerts in Alertmanager](#viewing-active-alerts-in-alertmanager)
- [Uninstall Monitoring](#uninstall-monitoring)
- [Setting Resource Limits and Requests](#setting-resource-limits-and-requests)
- [Known Issues](#known-issues)
# About Prometheus
### Features
Prometheus provides a time series of your data, which is, according to the [Prometheus documentation:](https://prometheus.io/docs/concepts/data_model/)
Prometheus lets you view metrics from your Rancher and Kubernetes objects. Using timestamps, Prometheus lets you query and view these metrics in easy-to-read graphs and visuals, either through the Rancher UI or Grafana, which is an analytics viewing platform deployed along with Prometheus.
> A stream of timestamped values belonging to the same metric and the same set of labeled dimensions, along with comprehensive statistics and metrics of the monitored cluster.
By viewing data that Prometheus scrapes from your cluster control plane, nodes, and deployments, you can stay on top of everything happening in your cluster. You can then use these analytics to better run your organization: stop system emergencies before they start, develop maintenance strategies, or restore crashed servers.
In other words, Prometheus lets you view metrics from your different Rancher and Kubernetes objects. Using timestamps, Prometheus lets you query and view these metrics in easy-to-read graphs and visuals, either through the Rancher UI or Grafana, which is an analytics viewing platform deployed along with Prometheus.
The `rancher-monitoring` operator, introduced in Rancher v2.5, is powered by [Prometheus](https://prometheus.io/), [Grafana](https://grafana.com/grafana/), [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/), the [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator), and the [Prometheus adapter.](https://github.com/DirectXMan12/k8s-prometheus-adapter)
By viewing data that Prometheus scrapes from your cluster control plane, nodes, and deployments, you can stay on top of everything happening in your cluster. You can then use these analytics to better run your organization: stop system emergencies before they start, develop maintenance strategies, restore crashed servers, etc.
The monitoring application allows you to:
# Enable Monitoring
- Monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments
- Define alerts based on metrics collected via Prometheus
- Create custom Grafana dashboards
- Configure alert-based notifications via Email, Slack, PagerDuty, etc. using Prometheus Alertmanager
- 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
As an [administrator]({{<baseurl>}}/rancher/v2.5/en/admin-settings/rbac/global-permissions/) or [cluster owner]({{<baseurl>}}/rancher/v2.5/en/admin-settings/rbac/cluster-project-roles/#cluster-roles), you can configure Rancher to deploy Prometheus to monitor your Kubernetes cluster.
# How Monitoring Works
> **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.](#setting-resource-limits-and-requests)
> - When installing monitoring on an RKE cluster using RancherOS or Flatcar Linux nodes, change the etcd node certificate directory to `/opt/rke/etc/kubernetes/ssl`.
For an explanation of how the monitoring components work together, see [this page.](./how-monitoring-works)
{{% tabs %}}
{{% tab "Rancher v2.5.8+" %}}
# Default Components and Deployments
### Enable Monitoring for use without SSL
### Built-in Dashboards
1. In the Rancher UI, go to the cluster where you want to install monitoring and click **Cluster Explorer.**
1. Click **Apps.**
1. Click the `rancher-monitoring` app.
1. Optional: Click **Chart Options** and configure alerting, Prometheus and Grafana. For help, refer to the [configuration reference.](./configuration)
1. Scroll to the bottom of the Helm chart README and click **Install.**
By default, the monitoring application deploys Grafana dashboards (curated by the [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) project) onto a cluster.
**Result:** The monitoring app is deployed in the `cattle-monitoring-system` namespace.
It also deploys an Alertmanager UI and a Prometheus UI. For more information about these tools, see [Built-in Dashboards.](./dashboards)
### Default Metrics Exporters
### Enable Monitoring for use with SSL
By default, Rancher Monitoring deploys exporters (such as [node-exporter](https://github.com/prometheus/node_exporter) and [kube-state-metrics](https://github.com/kubernetes/kube-state-metrics)).
1. Follow the steps on [this page]({{<baseurl>}}/rancher/v2.5/en/k8s-in-rancher/secrets/) to create a secret in order for SSL to be used for alerts.
- The secret should be created in the `cattle-monitoring-system` namespace. If it doesn't exist, create it first.
- Add the `ca`, `cert`, and `key` files to the secret.
1. In the Rancher UI, go to the cluster where you want to install monitoring and click **Cluster Explorer.**
1. Click **Apps.**
1. Click the `rancher-monitoring` app.
1. Click **Alerting**.
1. Click **Additional Secrets** and add the secrets created earlier.
**Result:** The monitoring app is deployed in the `cattle-monitoring-system` namespace.
These default exporters automatically scrape metrics for CPU and memory from all components of your Kubernetes cluster, including your workloads.
When [creating a receiver,]({{<baseurl>}}/rancher/v2.5/en/monitoring-alerting/configuration/alertmanager/#creating-receivers-in-the-rancher-ui) SSL-enabled receivers such as email or webhook will have a **SSL** section with fields for **CA File Path**, **Cert File Path**, and **Key File Path**. Fill in these fields with the paths to each of `ca`, `cert`, and `key`. The path will be of the form `/etc/alertmanager/secrets/name-of-file-in-secret`.
### Default Alerts
For example, if you created a secret with these key-value pairs:
The monitoring application deploys some alerts by default. To see the default alerts, go to the [Alertmanager UI](./dashboard/accessing-the-alertmanager-ui) and click **Expand all groups.**
```yaml
ca.crt=`base64-content`
cert.pem=`base64-content`
key.pfx=`base64-content`
```
### Components Exposed in the Rancher UI
Then **Cert File Path** would be set to `/etc/alertmanager/secrets/cert.pem`.
For a list of monitoring components exposed in the Rancher UI, along with common use cases for editing them, see [this section.](./how-monitoring-works/#components-exposed-in-the-rancher-ui)
{{% /tab %}}
{{% tab "Rancher before v2.5.8" %}}
# Role-based Access Control
1. In the Rancher UI, go to the cluster where you want to install monitoring and click **Cluster Explorer.**
1. Click **Apps.**
1. Click the `rancher-monitoring` app.
1. Optional: Click **Chart Options** and configure alerting, Prometheus and Grafana. For help, refer to the [configuration reference.](./configuration)
1. Scroll to the bottom of the Helm chart README and click **Install.**
For information on configuring access to monitoring, see [this page.](./rbac)
**Result:** The monitoring app is deployed in the `cattle-monitoring-system` namespace.
# Guides
{{% /tab %}}
- [Enable monitoring](./guides/enable-monitoring)
- [Uninstall monitoring](./guides/uninstall)
- [Monitoring workloads](./guides/monitoring-workloads)
- [Customizing Grafana dashboards](./guides/customize-grafana)
- [Persistent Grafana dashboards](./guides/persist-grafana)
- [Debugging high memory usage](./guides/memory-usage)
- [Migrating from Monitoring V1 to V2](./guides/migrating)
{{% /tabs %}}
# Configuration
### Default Alerts, Targets, and Grafana Dashboards
### Configuring Monitoring Resources in Rancher
By default, Rancher Monitoring deploys exporters (such as [node-exporter](https://github.com/prometheus/node_exporter) and [kube-state-metrics](https://github.com/kubernetes/kube-state-metrics)) as well as default Prometheus alerts and Grafana dashboards (curated by the [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) project) onto a cluster.
> The configuration reference assumes familiarity with how monitoring components work together. For more information, see [How Monitoring Works.](./how-monitoring-works)
To see the default alerts, go to the [Alertmanager UI](#viewing-active-alerts-in-alertmanager) and click **Expand all groups.**
- [ServiceMonitor and PodMonitor](./configuration/servicemonitor-podmonitor)
- [Receiver](./configuration/receiver)
- [Route](./configuration/route)
- [PrometheusRule](./configuration/advanced/prometheusrule)
- [Prometheus](./configuration/advanced/prometheus)
- [Alertmanager](./configuration/advanced/alertmanager)
To see what services you are monitoring, you will need to see your targets. To view the default targets, refer to [Viewing the Prometheus Targets.](#viewing-the-prometheus-targets)
### Configuring Helm Chart Options
To see the default dashboards, go to the [Grafana UI.](#grafana-ui) In the left navigation bar, click the icon with four boxes and click **Manage.**
### Next Steps
To configure Prometheus resources from the Rancher UI, click **Apps & Marketplace > Monitoring** in the upper left corner.
For more information on `rancher-monitoring` chart options, including options to set resource limits and requests, see [this page.](./configuration/helm-chart-options)
# Windows Cluster Support
@@ -139,104 +102,12 @@ 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.](./windows-clusters)
# Using Monitoring
Installing `rancher-monitoring` makes the following dashboards available from the Rancher UI.
> **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.
### Grafana UI
[Grafana](https://grafana.com/grafana/) allows you to query, visualize, alert on and understand your metrics no matter where they are stored. Create, explore, and share dashboards with your team and foster a data driven culture.
Rancher allows any users who are authenticated by Kubernetes and have access the Grafana service deployed by the Rancher Monitoring chart to access Grafana via the Rancher Dashboard UI. By default, all users who are able to access Grafana are given the [Viewer](https://grafana.com/docs/grafana/latest/permissions/organization_roles/#viewer-role) role, which allows them to view any of the default dashboards deployed by Rancher.
However, users can choose to log in to Grafana as an [Admin](https://grafana.com/docs/grafana/latest/permissions/organization_roles/#admin-role) if necessary. The default Admin username and password for the Grafana instance will be `admin`/`prom-operator`, but alternative credentials can also be supplied on deploying or upgrading the chart.
> **Persistent Dashboards:** To allow the Grafana dashboard to persist after it restarts, add the dashboard configuration JSON into a ConfigMap. ConfigMaps also allow the dashboards to be deployed with a GitOps or CD based approach. This allows the dashboard to be put under version control. For details, refer to [this section.](./persist-grafana)
To see the Grafana UI, install `rancher-monitoring`. Then go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Grafana.
<figcaption>Cluster Compute Resources Dashboard in Grafana</figcaption>
![Cluster Compute Resources Dashboard in Grafana]({{<baseurl>}}/img/rancher/cluster-compute-resources-dashboard.png)
<figcaption>Default Dashboards in Grafana</figcaption>
![Default Dashboards in Grafana]({{<baseurl>}}/img/rancher/grafana-default-dashboard.png)
### Prometheus UI
To see the Prometheus UI, install `rancher-monitoring`. Then go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Prometheus Graph.**
<figcaption>Prometheus Graph UI</figcaption>
![Prometheus Graph UI]({{<baseurl>}}/img/rancher/prometheus-graph-ui.png)
### Viewing the Prometheus Targets
To see the Prometheus Targets, install `rancher-monitoring`. Then go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Prometheus Targets.**
<figcaption>Targets in the Prometheus UI</figcaption>
![Prometheus Targets UI]({{<baseurl>}}/img/rancher/prometheus-targets-ui.png)
### Viewing the PrometheusRules
To see the PrometheusRules, install `rancher-monitoring`. Then go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Prometheus Rules.**
<figcaption>Rules in the Prometheus UI</figcaption>
![PrometheusRules UI]({{<baseurl>}}/img/rancher/prometheus-rules-ui.png)
For more information on PrometheusRules in Rancher, see [this page.](./configuration/prometheusrules)
### Viewing Active Alerts in Alertmanager
When `rancher-monitoring` is installed, the Prometheus Alertmanager UI is deployed.
The Alertmanager handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct receiver integration such as email, PagerDuty, or OpsGenie. It also takes care of silencing and inhibition of alerts.
In the Alertmanager UI, you can view your alerts and the current Alertmanager configuration.
To see the PrometheusRules, install `rancher-monitoring`. Then go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Alertmanager.**
**Result:** The Alertmanager UI opens in a new tab. For help with configuration, refer to the [official Alertmanager documentation.](https://prometheus.io/docs/alerting/latest/alertmanager/)
For more information on configuring Alertmanager in Rancher, see [this page.](./configuration/alertmanager)
<figcaption>The Alertmanager UI</figcaption>
![Alertmanager UI]({{<baseurl>}}/img/rancher/alertmanager-ui.png)
# Uninstall Monitoring
1. From the **Cluster Explorer,** click Apps & Marketplace.
1. Click **Installed Apps.**
1. Go to the `cattle-monitoring-system` namespace and check the boxes for `rancher-monitoring-crd` and `rancher-monitoring`.
1. Click **Delete.**
1. Confirm **Delete.**
**Result:** `rancher-monitoring` is uninstalled.
> **Note on Persistent Grafana Dashboards:** 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"`. This annotation is added by default in Monitoring V2 v14.5.100+ but can be manually applied on the cattle-dashboards namespace before an uninstall if an older version of the Monitoring chart is currently installed onto your cluster.
# Setting Resource Limits and Requests
The resource requests and limits can be configured when installing `rancher-monitoring`.
The default values are in the [values.yaml](https://github.com/rancher/charts/blob/main/charts/rancher-monitoring/values.yaml) in the `rancher-monitoring` Helm chart. As every environment is different, it is recommended that you set limits higher than the recommended and then tune them down to accomodate what your environment uses after observing it in operation for a week or two. As you scale your clusters, you will need to also scale your requests and limits to accomodate the larger amount of data collected from them.
The default values in the table below are the minimum required resource limits and requests.
| Resource Name | Memory Limit | CPU Limit | Memory Request | CPU Request |
| ------------- | ------------ | ----------- | ---------------- | ------------------ |
| alertmanager | 500Mi | 1000m | 100Mi | 100m |
| grafana | 200Mi | 200m | 100Mi | 100m |
| kube-state-metrics subchart | 200Mi | 100m | 130Mi | 100m |
| prometheus-node-exporter subchart | 50Mi | 200m | 30Mi | 100m |
| prometheusOperator | 500Mi | 200m | 100Mi | 100m |
| prometheus | 2500Mi | 1000m | 1750Mi | 750m |
| **Total** | **3950Mi** | **2700m** | **2210Mi** | **1250m** |
At least 50Gi storage is recommended.
# 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.
For tips on debugging high memory usage, see [this page.](./memory-usage)
It is common that as the amount of metrics and deployments being monitors grows, Prometheus's memory and CPU needs outgrow the limits initially placed on them. If you see Prometheus commonly crashing, try increasing the allocated memory and setting alerts for when resource usage of Monitoring pods approaches limits placed on them.
content/rancher/v2.5/en/monitoring-alerting/configuration/_index.md
+21 -69
View File
@@ -1,96 +1,48 @@
---
title: Configuration
weight: 3
weight: 5
aliases:
- /rancher/v2.5/en/monitoring-alerting/v2.5/configuration
---
This page captures some of the most important options for configuring the custom resources for monitoring.
This page captures some of the most important options for configuring Monitoring V2 in the Rancher UI.
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.
- [Configuring Prometheus](#configuring-prometheus)
- [Configuring Targets with ServiceMonitors and PodMonitors](#configuring-targets-with-servicemonitors-and-podmonitors)
- [ServiceMonitors](#servicemonitors)
- [PodMonitors](#podmonitors)
- [PrometheusRules](#prometheusrules)
- [Alertmanager Config](#alertmanager-config)
- [Trusted CA for Notifiers](#trusted-ca-for-notifiers)
- [Additional Scrape Configurations](#additional-scrape-configurations)
- [Examples](#examples)
# Setting Resource Limits and Requests
# Configuring Prometheus
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.](./helm-chart-options/#configuring-resource-limits-and-requests)
The primary way that users will be able to customize this feature for specific Monitoring and Alerting use cases is by creating and/or modifying ConfigMaps, Secrets, and Custom Resources pertaining to this deployment.
# Prometheus Configuration
Prometheus Operator introduces a set of [Custom Resource Definitions](https://github.com/prometheus-operator/prometheus-operator#customresourcedefinitions) that allow users to deploy and manage Prometheus and Alertmanager instances by creating and modifying those custom resources on a cluster.
It is usually not necessary to directly edit the Prometheus custom resource.
Prometheus Operator will automatically update your Prometheus configuration based on the live state of these custom resources.
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.
There are also certain special types of ConfigMaps/Secrets such as those corresponding to Grafana Dashboards, Grafana Datasources, and Alertmanager Configs that will automatically update your Prometheus configuration via sidecar proxies that observe the live state of those resources within your cluster.
By default, a set of these resources (curated by the [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) project) are deployed onto your cluster as part of installing the Rancher Monitoring Application to set up a basic Monitoring / Alerting stack. For more information how to configure custom targets, alerts, notifiers, and dashboards after deploying the chart, see below.
### ServiceMonitor and PodMonitor Configuration
# Configuring Targets with ServiceMonitors and PodMonitors
For details, see [this page.](./servicemonitor-podmonitor)
Customizing the scrape configuration used by Prometheus to determine which resources to scrape metrics from will primarily involve creating / modifying the following resources within your cluster:
### Advanced Prometheus Configuration
### ServiceMonitors
For more information about directly editing the Prometheus custom resource, which may be helpful in advanced use cases, see [this page.](./advanced/prometheus)
This CRD declaratively specifies how groups of Kubernetes services should be monitored. Any Services in your cluster that match the labels located within the ServiceMonitor `selector` field will be monitored based on the `endpoints` specified on the ServiceMonitor. For more information on what fields can be specified, please look at the [spec](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/api.md#servicemonitor) provided by Prometheus Operator.
# Alertmanager Configuration
For more information about how ServiceMonitors work, refer to the [Prometheus Operator documentation.](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/user-guides/running-exporters.md)
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.
### PodMonitors
Routes and receivers are part of the configuration of the alertmanager custom resource. In the Rancher UI, Routes and Receivers are not true custom resources, but pseudo-custom resources that the Prometheus Operator uses to synchronize your configuration with the Alertmanager custom resource. When routes and receivers are updated, the monitoring application will automatically update Alertmanager to reflect those changes.
This CRD declaratively specifies how group of pods should be monitored. Any Pods in your cluster that match the labels located within the PodMonitor `selector` field will be monitored based on the `podMetricsEndpoints` specified on the PodMonitor. For more information on what fields can be specified, please look at the [spec](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/api.md#podmonitorspec) provided by Prometheus Operator.
For some advanced use cases, you may want to configure alertmanager directly. For more information, refer to [this page.](./advanced/alertmanager)
# PrometheusRules
### Receivers
This CRD defines a group of Prometheus alerting and/or recording rules.
Receivers are used to set up notifications. For details on how to configure receivers, see [this page.](./receiver)
### Routes
For information on configuring PrometheusRules, refer to [this page.](./prometheusrules)
Routes filter notifications before they reach receivers. Each route needs to refer to a receiver that has already been configured. For details on how to configure routes, see [this page.](./route)
# Alertmanager Config
### Advanced
For information on configuring the Alertmanager, refer to [this page.](./alertmanager)
# Trusted CA for Notifiers
If you need to add a trusted CA to your notifier, follow these steps:
1. Create the `cattle-monitoring-system` namespace.
1. Add your trusted CA secret to the `cattle-monitoring-system` namespace.
1. Deploy or upgrade the `rancher-monitoring` Helm chart. In the chart options, reference the secret in **Alerting > Additional Secrets.**
**Result:** The default Alertmanager custom resource will have access to your trusted CA.
# Additional Scrape Configurations
If the scrape configuration you want cannot be specified via a ServiceMonitor or PodMonitor at the moment, you can provide an `additionalScrapeConfigSecret` on deploying or upgrading `rancher-monitoring`.
A [scrape_config section](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) specifies a set of targets and parameters describing how to scrape them. In the general case, one scrape configuration specifies a single job.
An example of where this might be used is with Istio. For more information, see [this section.](https://rancher.com/docs/rancher/v2.5/en/istio/v2.5/configuration-reference/selectors-and-scrape)
# Examples
### ServiceMonitor
An example ServiceMonitor custom resource can be found [here.](https://github.com/prometheus-operator/prometheus-operator/blob/master/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml)
### PodMonitor
An example PodMonitor can be found [here.](https://github.com/prometheus-operator/prometheus-operator/blob/master/example/user-guides/getting-started/example-app-pod-monitor.yaml) An example Prometheus resource that refers to it can be found [here.](https://github.com/prometheus-operator/prometheus-operator/blob/master/example/user-guides/getting-started/prometheus-pod-monitor.yaml)
### PrometheusRule
For users who are familiar with Prometheus, a PrometheusRule contains the alerting and recording rules that you would normally place in a [Prometheus rule file](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/).
For a more fine-grained application of PrometheusRules within your cluster, the ruleSelector field on a Prometheus resource allows you to select which PrometheusRules should be loaded onto Prometheus based on the labels attached to the PrometheusRules resources.
An example PrometheusRule is on [this page.](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/user-guides/alerting.md)
### Alertmanager Config
For an example configuration, refer to [this section.](./alertmanager/#example-alertmanager-config)
For more information about directly editing the Alertmanager custom resource, which may be helpful in advanced use cases, see [this page.](./advanced/alertmanager)
content/rancher/v2.5/en/monitoring-alerting/configuration/advanced/_index.md
+16
View File
@@ -0,0 +1,16 @@
---
title: Advanced Configuration
weight: 500
---
### Alertmanager
For information on configuring the Alertmanager custom resource, see [this page.](./alertmanager)
### Prometheus
For information on configuring the Prometheus custom resource, see [this page.](./prometheus)
### PrometheusRules
For information on configuring the Prometheus custom resource, see [this page.](./prometheusrules)
content/rancher/v2.5/en/monitoring-alerting/configuration/advanced/alertmanager/_index.md
+40
View File
@@ -0,0 +1,40 @@
---
title: Alertmanager Configuration
weight: 1
---
It is usually not necessary to directly edit the Alertmanager custom resource. For most use cases, you will only need to edit the Receivers and Routes to configure notifications.
When Receivers and Routes are updated, the monitoring application will automatically update the Alertmanager custom resource to be consistent with those changes.
> This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../../../how-monitoring-works/#how-alertmanager-works)
# About the Alertmanager Custom Resource
By default, Rancher Monitoring deploys a single Alertmanager onto a cluster that uses a default Alertmanager Config Secret.
You may want to edit the Alertmanager custom resource if you would like to take advantage of advanced options that are not exposed in the Rancher UI forms, such as the ability to create a routing tree structure that is more than two levels deep.
It is also possible to create more than one Alertmanager in a cluster, which may be useful if you want to implement namespace-scoped monitoring. In this case, you should manage the Alertmanager custom resources using the same underlying Alertmanager Config Secret.
### Deeply Nested Routes
While the Rancher UI only supports a routing tree that is two levels deep, you can configure more deeply nested routing structures by editing the Alertmanager YAML.
### Multiple Alertmanager Replicas
As part of the chart deployment options, you can opt to increase the number of replicas of the Alertmanager deployed onto your cluster. The replicas can all be managed using the same underlying Alertmanager Config Secret.
This Secret should be updated or modified any time you want to:
- Add in new notifiers or receivers
- Change the alerts that should be sent to specific notifiers or receivers
- Change the group of alerts that are sent out
By default, you can either choose to supply an existing Alertmanager Config Secret (i.e. any Secret in the `cattle-monitoring-system` namespace) or allow Rancher Monitoring to deploy a default Alertmanager Config Secret onto your cluster.
By default, the Alertmanager Config Secret created by Rancher will never be modified or deleted on an upgrade or uninstall of the `rancher-monitoring` chart. This restriction prevents users from losing or overwriting their alerting configuration when executing operations on the chart.
For more information on what fields can be specified in the Alertmanager Config Secret, please look at the [Prometheus Alertmanager docs.](https://prometheus.io/docs/alerting/latest/alertmanager/)
The full spec for the Alertmanager configuration file and what it takes in can be found [here.](https://prometheus.io/docs/alerting/latest/configuration/#configuration-file)
content/rancher/v2.5/en/monitoring-alerting/configuration/advanced/prometheus/_index.md
+19
View File
@@ -0,0 +1,19 @@
---
title: Prometheus Configuration
weight: 1
aliases:
- /rancher/v2.5/en/monitoring-alerting/v2.5/configuration/prometheusrules
- /rancher/v2.5/en/monitoring-alerting/configuration/prometheusrules
- /rancher/v2.5/en/monitoring-alerting/configuration/advanced/prometheusrules
---
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.](../../../how-monitoring-works/)
# 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.
The Prometheus CR specifies details such as rules and what Alertmanagers are connected to Prometheus. Rancher builds this CR for you.
Monitoring V2 only supports one Prometheus per cluster. However, you might want to edit the Prometheus CR if you want to limit monitoring to certain namespaces.
content/rancher/v2.5/en/monitoring-alerting/configuration/prometheusrules/_index.md → content/rancher/v2.5/en/monitoring-alerting/configuration/advanced/prometheusrules/_index.md
+20 -33
View File
@@ -1,42 +1,12 @@
---
title: PrometheusRules
weight: 2
aliases:
- /rancher/v2.5/en/monitoring-alerting/v2.5/configuration/prometheusrules
title: Configuring PrometheusRules
weight: 3
---
A PrometheusRule defines a group of Prometheus alerting and/or recording rules.
- [About PrometheusRule Custom Resources](#about-prometheusrule-custom-resources)
- [Connecting Routes and PrometheusRules](#connecting-routes-and-prometheusrules)
- [Creating PrometheusRules in the Rancher UI](#creating-prometheusrules-in-the-rancher-ui)
- [Configuration](#configuration)
- [Rule Group](#rule-group)
- [Alerting Rules](#alerting-rules)
- [Recording Rules](#recording-rules)
> This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../how-monitoring-works/#how-alertmanager-works)
### About PrometheusRule Custom Resources
Prometheus rule files are held in PrometheusRule custom resources.
A PrometheusRule allows you to define one or more RuleGroups. Each RuleGroup consists of a set of Rule objects that can each represent either an alerting or a recording rule with the following fields:
- The name of the new alert or record
- A PromQL (Prometheus query language) expression for the new alert or record
- Labels that should be attached to the alert or record that identify it (e.g. cluster name or severity)
- Annotations that encode any additional important pieces of information that need to be displayed on the notification for an alert (e.g. summary, description, message, runbook URL, etc.). This field is not required for recording rules.
Alerting rules define alert conditions based on PromQL queries. Recording rules precompute frequently needed or computationally expensive queries at defined intervals.
For more information on what fields can be specified, please look at the [Prometheus Operator spec.](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/api.md#prometheusrulespec)
Use the label selector field `ruleSelector` in the Prometheus object to define the rule files that you want to be mounted into Prometheus.
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/)
### Connecting Routes and PrometheusRules
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 Prometheus 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.
### Creating PrometheusRules in the Rancher UI
@@ -54,6 +24,23 @@ 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
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.
Prometheus rule files are held in PrometheusRule custom resources. A PrometheusRule allows you to define one or more RuleGroups. Each RuleGroup consists of a set of Rule objects that can each represent either an alerting or a recording rule with the following fields:
- The name of the new alert or record
- A PromQL expression for the new alert or record
- Labels that should be attached to the alert or record that identify it (e.g. cluster name or severity)
- Annotations that encode any additional important pieces of information that need to be displayed on the notification for an alert (e.g. summary, description, message, runbook URL, etc.). This field is not required for recording rules.
For more information on what fields can be specified, please look at the [Prometheus Operator spec.](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/api.md#prometheusrulespec)
Use the label selector field `ruleSelector` in the Prometheus object to define the rule files that you want to be mounted into Prometheus.
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
{{% tabs %}}
content/rancher/v2.5/en/monitoring-alerting/configuration/examples/_index.md
+24
View File
@@ -0,0 +1,24 @@
---
title: Examples
weight: 400
---
### ServiceMonitor
An example ServiceMonitor custom resource can be found [here.](https://github.com/prometheus-operator/prometheus-operator/blob/master/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml)
### PodMonitor
An example PodMonitor can be found [here.](https://github.com/prometheus-operator/prometheus-operator/blob/master/example/user-guides/getting-started/example-app-pod-monitor.yaml) An example Prometheus resource that refers to it can be found [here.](https://github.com/prometheus-operator/prometheus-operator/blob/master/example/user-guides/getting-started/prometheus-pod-monitor.yaml)
### PrometheusRule
For users who are familiar with Prometheus, a PrometheusRule contains the alerting and recording rules that you would normally place in a [Prometheus rule file](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/).
For a more fine-grained application of PrometheusRules within your cluster, the ruleSelector field on a Prometheus resource allows you to select which PrometheusRules should be loaded onto Prometheus based on the labels attached to the PrometheusRules resources.
An example PrometheusRule is on [this page.](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/user-guides/alerting.md)
### Alertmanager Config
For an example configuration, refer to [this section.](./alertmanager/#example-alertmanager-config)
content/rancher/v2.5/en/monitoring-alerting/configuration/helm-chart-options/_index.md
+77
View File
@@ -0,0 +1,77 @@
---
title: Helm Chart Options
weight: 8
---
- [Configuring Resource Limits and Requests](#configuring-resource-limits-and-requests)
- [Trusted CA for Notifiers](#trusted-ca-for-notifiers)
- [Additional Scrape Configurations](#additional-scrape-configurations)
- [Configuring Applications Packaged within Monitoring V2](#configuring-applications-packaged-within-monitoring-v2)
- [Increase the Replicas of Alertmanager](#increase-the-replicas-of-alertmanager)
- [Configuring the Namespace for a Persistent Grafana Dashboard](#configuring-the-namespace-for-a-persistent-grafana-dashboard)
# Configuring Resource Limits and Requests
The resource requests and limits can be configured when installing `rancher-monitoring`.
The default values are in the [values.yaml](https://github.com/rancher/charts/blob/main/charts/rancher-monitoring/values.yaml) in the `rancher-monitoring` Helm chart.
The default values in the table below are the minimum required resource limits and requests.
| Resource Name | Memory Limit | CPU Limit | Memory Request | CPU Request |
| ------------- | ------------ | ----------- | ---------------- | ------------------ |
| alertmanager | 500Mi | 1000m | 100Mi | 100m |
| grafana | 200Mi | 200m | 100Mi | 100m |
| kube-state-metrics subchart | 200Mi | 100m | 130Mi | 100m |
| prometheus-node-exporter subchart | 50Mi | 200m | 30Mi | 100m |
| prometheusOperator | 500Mi | 200m | 100Mi | 100m |
| prometheus | 2500Mi | 1000m | 1750Mi | 750m |
| **Total** | **3950Mi** | **2700m** | **2210Mi** | **1250m** |
At least 50Gi storage is recommended.
# Trusted CA for Notifiers
If you need to add a trusted CA to your notifier, follow these steps:
1. Create the `cattle-monitoring-system` namespace.
1. Add your trusted CA secret to the `cattle-monitoring-system` namespace.
1. Deploy or upgrade the `rancher-monitoring` Helm chart. In the chart options, reference the secret in **Alerting > Additional Secrets.**
**Result:** The default Alertmanager custom resource will have access to your trusted CA.
# Additional Scrape Configurations
If the scrape configuration you want cannot be specified via a ServiceMonitor or PodMonitor at the moment, you can provide an `additionalScrapeConfigSecret` on deploying or upgrading `rancher-monitoring`.
A [scrape_config section](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) specifies a set of targets and parameters describing how to scrape them. In the general case, one scrape configuration specifies a single job.
An example of where this might be used is with Istio. For more information, see [this section.](https://rancher.com/docs/rancher/v2.5/en/istio/v2.5/configuration-reference/selectors-and-scrape)
# Configuring Applications Packaged within Monitoring v2
We deploy kube-state-metrics and node-exporter with monitoring v2. Node exporter are deployed as DaemonSets. In the monitoring v2 helm chart, in the values.yaml, each of the things are deployed as sub charts.
We also deploy grafana which is not managed by prometheus.
If you look at what the helm chart is doing like in kube-state-metrics, there are plenty more values that you can set that aren’t exposed in the top level chart.
But in the top level chart you can add values that override values that exist in the sub chart.
### Increase the Replicas of Alertmanager
As part of the chart deployment options, you can opt to increase the number of replicas of the Alertmanager deployed onto your cluster. The replicas can all be managed using the same underlying Alertmanager Config Secret. For more information on the Alertmanager Config Secret, refer to [this section.](../configuration/advanced/alertmanager/#multiple-alertmanager-replicas)
### Configuring the Namespace for a Persistent Grafana Dashboard
To specify that you would like Grafana to watch for ConfigMaps across all namespaces, set this value in the `rancher-monitoring` Helm chart:
```
grafana.sidecar.dashboards.searchNamespace=ALL
```
Note that the RBAC roles exposed by the Monitoring chart to add Grafana Dashboards are still restricted to giving permissions for users to add dashboards in the namespace defined in `grafana.dashboards.namespace`, which defaults to `cattle-dashboards`.
content/rancher/v2.5/en/monitoring-alerting/configuration/alertmanager/_index.md → content/rancher/v2.5/en/monitoring-alerting/configuration/receiver/_index.md
+17 -62
View File
@@ -1,17 +1,19 @@
---
title: Alertmanager
title: Receiver Configuration
shortTitle: Receivers
weight: 1
aliases:
- /rancher/v2.5/en/monitoring-alerting/v2.5/configuration/alertmanager
- rancher/v2.5/en/monitoring-alerting/legacy/notifiers/
- /rancher/v2.5/en/cluster-admin/tools/notifiers
- /rancher/v2.5/en/cluster-admin/tools/alerts
- /rancher/v2.5/en/monitoring-alerting/configuration/alertmanager
---
The [Alertmanager Config](https://prometheus.io/docs/alerting/latest/configuration/#configuration-file) Secret contains the configuration of an Alertmanager instance that sends out notifications based on alerts it receives from Prometheus.
- [Overview](#overview)
- [Connecting Routes and PrometheusRules](#connecting-routes-and-prometheusrules)
> This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../../how-monitoring-works/#3-how-alertmanager-works)
- [Creating Receivers in the Rancher UI](#creating-receivers-in-the-rancher-ui)
- [Receiver Configuration](#receiver-configuration)
- [Slack](#slack)
@@ -26,30 +28,10 @@ The [Alertmanager Config](https://prometheus.io/docs/alerting/latest/configurati
- [Receiver](#receiver)
- [Grouping](#grouping)
- [Matching](#matching)
- [Example Alertmanager Configs](#example-alertmanager-configs)
- [Configuring Multiple Receivers](#configuring-multiple-receivers)
- [Example Alertmanager Config](../examples/#example-alertmanager-config)
- [Example Route Config for CIS Scan Alerts](#example-route-config-for-cis-scan-alerts)
# Overview
By default, Rancher Monitoring deploys a single Alertmanager onto a cluster that uses a default Alertmanager Config Secret. As part of the chart deployment options, you can opt to increase the number of replicas of the Alertmanager deployed onto your cluster that can all be managed using the same underlying Alertmanager Config Secret.
This Secret should be updated or modified any time you want to:
- Add in new notifiers or receivers
- Change the alerts that should be sent to specific notifiers or receivers
- Change the group of alerts that are sent out
> By default, you can either choose to supply an existing Alertmanager Config Secret (i.e. any Secret in the `cattle-monitoring-system` namespace) or allow Rancher Monitoring to deploy a default Alertmanager Config Secret onto your cluster. By default, the Alertmanager Config Secret created by Rancher will never be modified / deleted on an upgrade / uninstall of the `rancher-monitoring` chart to prevent users from losing or overwriting their alerting configuration when executing operations on the chart.
For more information on what fields can be specified in this secret, please look at the [Prometheus Alertmanager docs.](https://prometheus.io/docs/alerting/latest/alertmanager/)
The full spec for the Alertmanager configuration file and what it takes in can be found [here.](https://prometheus.io/docs/alerting/latest/configuration/#configuration-file)
For more information, refer to the [official Prometheus documentation about configuring routes.](https://www.prometheus.io/docs/alerting/latest/configuration/#route)
### Connecting Routes and PrometheusRules
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 Prometheus 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.
- [Trusted CA for Notifiers](#trusted-ca-for-notifiers)
# Creating Receivers in the Rancher UI
_Available as of v2.5.4_
@@ -248,7 +230,6 @@ url http://rancher-alerting-drivers-sachet.ns-1.svc:9876/alert
<!-- https://github.com/messagebird/sachet -->
{{% /tab %}}
{{% tab "Rancher v2.5.4-2.5.7" %}}
The following types of receivers can be configured in the Rancher UI:
@@ -330,45 +311,14 @@ The Alertmanager must be configured in YAML, as shown in these [examples.](#exam
{{% /tab %}}
{{% /tabs %}}
# Configuring Multiple Receivers
# Route Configuration
By editing the forms in the Rancher UI, you can set up a Receiver resource with all the information Alertmanager needs to send alerts to your notification system.
{{% tabs %}}
{{% tab "Rancher v2.5.4+" %}}
It is also possible to send alerts to multiple notification systems. One way is to configure the Receiver using custom YAML, in which case you can add the configuration for multiple notification systems, as long as you are sure that both systems should receive the same messages.
### Receiver
The route needs to refer to a [receiver](#receiver-configuration) that has already been configured.
You can also set up multiple receivers by using the `continue` option for a route, so that the alerts sent to a receiver continue being evaluated in the next level of the routing tree, which could contain another receiver.
### Grouping
| Field | Default | Description |
|-------|--------------|---------|
| Group By | N/a | The labels by which incoming alerts are grouped together. For example, `[ group_by: '[' <labelname>, ... ']' ]` Multiple alerts coming in for labels such as `cluster=A` and `alertname=LatencyHigh` can be batched into a single group. To aggregate by all possible labels, use the special value `'...'` as the sole label name, for example: `group_by: ['...']` Grouping by `...` effectively disables aggregation entirely, passing through all alerts as-is. This is unlikely to be what you want, unless you have a very low alert volume or your upstream notification system performs its own grouping. |
| Group Wait | 30s | How long to wait to buffer alerts of the same group before sending initially. |
| Group Interval | 5m | How long to wait before sending an alert that has been added to a group of alerts for which an initial notification has already been sent. |
| Repeat Interval | 4h | How long to wait before re-sending a given alert that has already been sent. |
### Matching
The **Match** field refers to a set of equality matchers used to identify which alerts to send to a given Route based on labels defined on that alert. When you add key-value pairs to the Rancher UI, they correspond to the YAML in this format:
```yaml
match:
[ <labelname>: <labelvalue>, ... ]
```
The **Match Regex** field refers to a set of regex-matchers used to identify which alerts to send to a given Route based on labels defined on that alert. When you add key-value pairs in the Rancher UI, they correspond to the YAML in this format:
```yaml
match_re:
[ <labelname>: <regex>, ... ]
```
{{% /tab %}}
{{% tab "Rancher v2.5.0-2.5.3" %}}
The Alertmanager must be configured in YAML, as shown in these [examples.](#example-alertmanager-configs)
{{% /tab %}}
{{% /tabs %}}
# Example Alertmanager Configs
@@ -440,3 +390,8 @@ spec:
```
For more information on enabling alerting for `rancher-cis-benchmark`, see [this section.]({{<baseurl>}}/rancher/v2.5/en/cis-scans/v2.5/#enabling-alerting-for-rancher-cis-benchmark)
# Trusted CA for Notifiers
If you need to add a trusted CA to your notifier, follow the steps in [this section.](../helm-chart-options/#trusted-ca-for-notifiers)
content/rancher/v2.5/en/monitoring-alerting/configuration/route/_index.md
+74
View File
@@ -0,0 +1,74 @@
---
title: Route Configuration
shortTitle: Routes
weight: 5
---
The route configuration is the section of the Alertmanager custom resource that controls how the alerts fired by Prometheus are grouped and filtered before they reach the receiver.
When a Route is changed, the Prometheus Operator regenerates the Alertmanager custom resource to reflect the changes.
For more information about configuring routes, refer to the [official Alertmanager documentation.](https://www.prometheus.io/docs/alerting/latest/configuration/#route)
> This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../../how-monitoring-works/#3-how-alertmanager-works)
- [Route Restrictions](#route-restrictions)
- [Route Configuration](#route-configuration)
- [Receiver](#receiver)
- [Grouping](#grouping)
- [Matching](#matching)
# Route Restrictions
Alertmanager proxies alerts for Prometheus based on its receivers and a routing tree that filters alerts to certain receivers based on labels.
Alerting drivers proxy alerts for Alertmanager to non-native receivers, such as Microsoft Teams and SMS.
In the Rancher UI for configuring routes and receivers, you can configure routing trees with one root and then a depth of one more level, for a tree with a depth of two. But if you use a `continue` route when configuring Alertmanager directly, you can make the tree deeper.
Each receiver is for one or more notification providers. So if you know that every alert for Slack should also go to PagerDuty, you can configure both in the same receiver.
# Route Configuration
### Note on Labels and Annotations
Labels should be used for identifying information that can affect the routing of notifications. Identifying information about the alert could consist of a container name, or the name of the team that should be notified.
Annotations should be used for information that does not affect who receives the alert, such as a runbook url or error message.
{{% tabs %}}
{{% tab "Rancher v2.5.4+" %}}
### Receiver
The route needs to refer to a [receiver](#receiver-configuration) that has already been configured.
### Grouping
| Field | Default | Description |
|-------|--------------|---------|
| Group By | N/a | The labels by which incoming alerts are grouped together. For example, `[ group_by: '[' <labelname>, ... ']' ]` Multiple alerts coming in for labels such as `cluster=A` and `alertname=LatencyHigh` can be batched into a single group. To aggregate by all possible labels, use the special value `'...'` as the sole label name, for example: `group_by: ['...']` Grouping by `...` effectively disables aggregation entirely, passing through all alerts as-is. This is unlikely to be what you want, unless you have a very low alert volume or your upstream notification system performs its own grouping. |
| Group Wait | 30s | How long to wait to buffer alerts of the same group before sending initially. |
| Group Interval | 5m | How long to wait before sending an alert that has been added to a group of alerts for which an initial notification has already been sent. |
| Repeat Interval | 4h | How long to wait before re-sending a given alert that has already been sent. |
### Matching
The **Match** field refers to a set of equality matchers used to identify which alerts to send to a given Route based on labels defined on that alert. When you add key-value pairs to the Rancher UI, they correspond to the YAML in this format:
```yaml
match:
[ <labelname>: <labelvalue>, ... ]
```
The **Match Regex** field refers to a set of regex-matchers used to identify which alerts to send to a given Route based on labels defined on that alert. When you add key-value pairs in the Rancher UI, they correspond to the YAML in this format:
```yaml
match_re:
[ <labelname>: <regex>, ... ]
```
{{% /tab %}}
{{% tab "Rancher v2.5.0-2.5.3" %}}
The Alertmanager must be configured in YAML, as shown in this [example.](./examples/#alertmanager-config)
{{% /tab %}}
{{% /tabs %}}
content/rancher/v2.5/en/monitoring-alerting/configuration/servicemonitor-podmonitor/_index.md
+31
View File
@@ -0,0 +1,31 @@
---
title: ServiceMonitor and PodMonitor Configuration
shortTitle: ServiceMonitors and PodMonitors
weight: 7
---
ServiceMonitors and PodMonitors are both pseudo-CRDs that map the scrape configuration of the Prometheus custom resource.
These configuration objects declaratively specify the endpoints that Prometheus will scrape metrics from.
ServiceMonitors are more commonly used than PodMonitors, and we recommend them for most use cases.
> This section assumes familiarity with how monitoring components work together. For more information, see [this section.](../../how-monitoring-works/)
### ServiceMonitors
This pseudo-CRD maps to a section of the Prometheus custom resource configuration. It declaratively specifies how groups of Kubernetes services should be monitored.
When a ServiceMonitor is created, the Prometheus Operator updates the Prometheus scrape configuration to include the ServiceMonitor configuration. Then Prometheus begins scraping metrics from the endpoint defined in the ServiceMonitor.
Any Services in your cluster that match the labels located within the ServiceMonitor `selector` field will be monitored based on the `endpoints` specified on the ServiceMonitor. For more information on what fields can be specified, please look at the [spec](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/api.md#servicemonitor) provided by Prometheus Operator.
For more information about how ServiceMonitors work, refer to the [Prometheus Operator documentation.](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/user-guides/running-exporters.md)
### PodMonitors
This pseudo-CRD maps to a section of the Prometheus custom resource configuration. It declaratively specifies how group of pods should be monitored.
When a PodMonitor is created, the Prometheus Operator updates the Prometheus scrape configuration to include the PodMonitor configuration. Then Prometheus begins scraping metrics from the endpoint defined in the ServiceMonitor.
Any Pods in your cluster that match the labels located within the PodMonitor `selector` field will be monitored based on the `podMetricsEndpoints` specified on the PodMonitor. For more information on what fields can be specified, please look at the [spec](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/api.md#podmonitorspec) provided by Prometheus Operator.
content/rancher/v2.5/en/monitoring-alerting/dashboards/_index.md
+86
View File
@@ -0,0 +1,86 @@
---
title: Built-in Dashboards
weight: 3
---
- [Grafana UI](#grafana-ui)
- [Alertmanager UI](#alertmanager-ui)
- [Prometheus UI](#prometheus-ui)
# Grafana UI
[Grafana](https://grafana.com/grafana/) allows you to query, visualize, alert on and understand your metrics no matter where they are stored. Create, explore, and share dashboards with your team and foster a data driven culture.
To see the default dashboards for time series data visualization, go to the Grafana UI.
### Customizing Grafana
To view and customize the PromQL queries powering the Grafana dashboard, see [this page.](./customize-grafana)
### Persistent Grafana Dashboards
To create a persistent Grafana dashboard, see [this page.](./persist-grafana)
### Access to Grafana
For information about role-based access control for Grafana, see [this section.](./rbac/#role-based-access-control-for-grafana)
# Alertmanager UI
When `rancher-monitoring` is installed, the Prometheus Alertmanager UI is deployed, allowing you to view your alerts and the current Alertmanager configuration.
> This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../how-monitoring-works/#how-alertmanager-works)
### Accessing the Alertmanager UI
The Alertmanager UI lets you see the most recently fired alerts.
> **Prerequisite:** The `rancher-monitoring` application must be installed.
To see the Alertmanager UI, go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Alertmanager.**
**Result:** The Alertmanager UI opens in a new tab. For help with configuration, refer to the [official Alertmanager documentation.](https://prometheus.io/docs/alerting/latest/alertmanager/)
For more information on configuring Alertmanager in Rancher, see [this page.](./configuration/alertmanager)
<figcaption>The Alertmanager UI</figcaption>
![Alertmanager UI]({{<baseurl>}}/img/rancher/alertmanager-ui.png)
### Viewing Default Alerts
To see alerts that are fired by default, go to the [Alertmanager UI](./alertmanager-ui) and click **Expand all groups.**
# Prometheus UI
By default, the [kube-state-metrics service](https://github.com/kubernetes/kube-state-metrics) provides a wealth of information about CPU and memory utilization to the monitoring application. These metrics cover Kubernetes resources across namespaces. This means that in order to see resource metrics for a service, you don't need to create a new ServiceMonitor for it. Because the data is already in the time series database, you can go to the Prometheus UI and run a PromQL query to get the information. The same query can be used to configure a Grafana dashboard to show a graph of those metrics over time.
To see the Prometheus UI, install `rancher-monitoring`. Then go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Prometheus Graph.**
<figcaption>Prometheus Graph UI</figcaption>
![Prometheus Graph UI]({{<baseurl>}}/img/rancher/prometheus-graph-ui.png)
### Viewing the Prometheus Targets
To see what services you are monitoring, you will need to see your targets. Targets are set up by ServiceMonitors and PodMonitors as sources to scrape metrics from. You won't need to directly edit targets, but the Prometheus UI can be useful for giving you an overview of all of the sources of metrics that are being scraped.
To see the Prometheus Targets, install `rancher-monitoring`. Then go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Prometheus Targets.**
<figcaption>Targets in the Prometheus UI</figcaption>
![Prometheus Targets UI]({{<baseurl>}}/img/rancher/prometheus-targets-ui.png)
### Viewing the PrometheusRules
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 a certain Alert.
To see the PrometheusRules, install `rancher-monitoring`. Then go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Prometheus Rules.**
You can also see the rules in the Prometheus UI:
<figcaption>Rules in the Prometheus UI</figcaption>
![PrometheusRules UI]({{<baseurl>}}/img/rancher/prometheus-rules-ui.png)
For more information on configuring PrometheusRules in Rancher, see [this page.](./configuration/prometheusrules)
content/rancher/v2.5/en/monitoring-alerting/configuration/expression/_index.md → content/rancher/v2.5/en/monitoring-alerting/expression/_index.md
+4 -3
View File
@@ -1,16 +1,17 @@
---
title: Prometheus Expressions
weight: 4
title: PromQL Expression Reference
weight: 6
aliases:
- /rancher/v2.5/en/project-admin/tools/monitoring/expression
- /rancher/v2.5/en/cluster-admin/tools/monitoring/expression
- /rancher/v2.5/en/monitoring-alerting/legacy/monitoring/cluster-monitoring/expression
- /rancher/v2.5/en/monitoring-alerting/v2.5/configuration/expression
- /rancher/v2.5/en/monitoring/alerting/configuration/expression
---
The PromQL expressions in this doc can be used to configure alerts.
For more information about querying Prometheus, refer to the official [Prometheus documentation.](https://prometheus.io/docs/prometheus/latest/querying/basics/)
For more information about querying the Prometheus time series database, refer to the official [Prometheus documentation.](https://prometheus.io/docs/prometheus/latest/querying/basics/)
<!-- TOC -->
content/rancher/v2.5/en/monitoring-alerting/guides/_index.md
+13
View File
@@ -0,0 +1,13 @@
---
title: Monitoring Guides
shortTitle: Guides
weight: 4
---
- [Enable monitoring](./enable-monitoring)
- [Uninstall monitoring](./uninstall)
- [Monitoring workloads](./monitoring-workloads)
- [Customizing Grafana dashboards](./customize-grafana)
- [Persistent Grafana dashboards](./persist-grafana)
- [Debugging high memory usage](./memory-usage)
- [Migrating from Monitoring V1 to V2](./migrating)
content/rancher/v2.5/en/monitoring-alerting/guides/customize-grafana/_index.md
+41
View File
@@ -0,0 +1,41 @@
---
title: Customizing Grafana Dashboards
weight: 5
---
In this section, you'll learn how to customize the Grafana dashboard to show metrics that apply to a certain container.
### Prerequisites
Before you can customize a Grafana dashboard, the `rancher-monitoring` application must be installed.
To see the links to the external monitoring UIs, including Grafana dashboards, you will need at least a [project-member role.]({{<baseurl>}}/rancher/v2.5/en/monitoring-alerting/rbac/#users-with-rancher-cluster-manager-based-permissions)
### Signing in to Grafana
1. In the Rancher UI, go to the cluster that has the dashboard you want to customize.
1. In the left navigation menu, click **Monitoring.**
1. Click **Grafana.** The Grafana dashboard should open in a new tab.
1. Go to the log in icon in the lower left corner and click **Sign In.**
1. Log in to Grafana. The default Admin username and password for the Grafana instance is `admin/prom-operator`. (Regardless of who has the password, cluster administrator permission in Rancher is still required access the Grafana instance.) Alternative credentials can also be supplied on deploying or upgrading the chart.
### Getting the PromQL Query Powering a Grafana Panel
For any panel, you can click the title and click **Explore** to get the PromQL queries powering the graphic.
For this example, we would like to get the CPU usage for the Alertmanager container, so we click **CPU Utilization > Inspect.**
The **Data** tab shows the underlying data as a time series, with the time in first column and the PromQL query result in the second column. Copy the PromQL query.
```
(1 - (avg(irate({__name__=~"node_cpu_seconds_total|windows_cpu_time_total",mode="idle"}[5m])))) * 100
```
You can then modify the query in the Grafana panel or create a new Grafana panel using the query.
See also:
- [Grafana docs on editing a panel](https://grafana.com/docs/grafana/latest/panels/panel-editor/)
- [Grafana docs on adding a panel to a dashboard](https://grafana.com/docs/grafana/latest/panels/add-a-panel/)
content/rancher/v2.5/en/monitoring-alerting/guides/enable-monitoring/_index.md
+79
View File
@@ -0,0 +1,79 @@
---
title: Enable Monitoring
weight: 1
---
As an [administrator]({{<baseurl>}}/rancher/v2.5/en/admin-settings/rbac/global-permissions/) or [cluster owner]({{<baseurl>}}/rancher/v2.5/en/admin-settings/rbac/cluster-project-roles/#cluster-roles), you can configure Rancher to deploy Prometheus to monitor your Kubernetes cluster.
This page describes how to enable monitoring and alerting within a cluster using the new monitoring application.
You can enable monitoring with or without SSL.
# 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.](./configuration/helm-chart-options/#setting-resource-limits-and-requests)
- When installing monitoring on an RKE cluster using RancherOS or Flatcar Linux nodes, change the etcd node certificate directory to `/opt/rke/etc/kubernetes/ssl`.
> **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
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.](./configuration/helm-chart-options/#setting-resource-limits-and-requests)
# Install the Monitoring Application
{{% tabs %}}
{{% tab "Rancher v2.5.8" %}}
### Enable Monitoring for use without SSL
1. In the Rancher UI, go to the cluster where you want to install monitoring and click **Cluster Explorer.**
1. Click **Apps.**
1. Click the `rancher-monitoring` app.
1. Optional: Click **Chart Options** and configure alerting, Prometheus and Grafana. For help, refer to the [configuration reference.](./configuration)
1. Scroll to the bottom of the Helm chart README and click **Install.**
**Result:** The monitoring app is deployed in the `cattle-monitoring-system` namespace.
### Enable Monitoring for use with SSL
1. Follow the steps on [this page]({{<baseurl>}}/rancher/v2.5/en/k8s-in-rancher/secrets/) to create a secret in order for SSL to be used for alerts.
- The secret should be created in the `cattle-monitoring-system` namespace. If it doesn't exist, create it first.
- Add the `ca`, `cert`, and `key` files to the secret.
1. In the Rancher UI, go to the cluster where you want to install monitoring and click **Cluster Explorer.**
1. Click **Apps.**
1. Click the `rancher-monitoring` app.
1. Click **Alerting**.
1. Click **Additional Secrets** and add the secrets created earlier.
**Result:** The monitoring app is deployed in the `cattle-monitoring-system` namespace.
When [creating a receiver,]({{<baseurl>}}/rancher/v2.5/en/monitoring-alerting/configuration/alertmanager/#creating-receivers-in-the-rancher-ui) SSL-enabled receivers such as email or webhook will have a **SSL** section with fields for **CA File Path**, **Cert File Path**, and **Key File Path**. Fill in these fields with the paths to each of `ca`, `cert`, and `key`. The path will be of the form `/etc/alertmanager/secrets/name-of-file-in-secret`.
For example, if you created a secret with these key-value pairs:
```yaml
ca.crt=`base64-content`
cert.pem=`base64-content`
key.pfx=`base64-content`
```
Then **Cert File Path** would be set to `/etc/alertmanager/secrets/cert.pem`.
{{% /tab %}}
{{% tab "Rancher v2.5.0-2.5.7" %}}
1. In the Rancher UI, go to the cluster where you want to install monitoring and click **Cluster Explorer.**
1. Click **Apps.**
1. Click the `rancher-monitoring` app.
1. Optional: Click **Chart Options** and configure alerting, Prometheus and Grafana. For help, refer to the [configuration reference.](./configuration)
1. Scroll to the bottom of the Helm chart README and click **Install.**
**Result:** The monitoring app is deployed in the `cattle-monitoring-system` namespace.
{{% /tab %}}
{{% /tabs %}}
content/rancher/v2.5/en/monitoring-alerting/guides/memory-usage/_index.md
+20
View File
@@ -0,0 +1,20 @@
---
title: Debugging High Memory Usage
weight: 8
---
Every time series in Prometheus is uniquely identified by its [metric name](https://prometheus.io/docs/practices/naming/#metric-names) and optional key-value pairs called [labels.](https://prometheus.io/docs/practices/naming/#labels)
The labels allow the ability to filter and aggregate the time series data, but they also multiply the amount of data that Prometheus collects.
Each time series has a defined set of labels, and Prometheus generates a new time series for all unique combinations of labels. If a metric has two labels attached, two time series are generated for that metric. Changing any label value, including adding or removing a label, will create a new time series.
Prometheus is optimized to store data that is index-based on series. It is designed for a relatively consistent number of time series and a relatively large number of samples that need to be collected from the exporters over time.
Inversely, Prometheus is not optimized to accommodate a rapidly changing number of time series. For that reason, large bursts of memory usage can occur when monitoring is installed on clusters where many resources are being created and destroyed, especially on multi-tenant clusters.
### Reducing Memory Bursts
To reduce memory consumption, Prometheus can be configured to store fewer time series, by scraping fewer metrics or by attaching fewer labels to the time series. To see which series use the most memory, you can check the TSDB (time series database) status page in the Prometheus UI.
Distributed Prometheus solutions such as [Thanos](https://thanos.io/) and [Cortex](https://cortexmetrics.io/) use an alternate architecture in which multiple small Prometheus instances are deployed. In the case of Thanos, the metrics from each Prometheus are aggregated into the common Thanos deployment, and then those metrics are exported to a persistent store, such as S3. This more robust architecture avoids burdening any single Prometheus instance with too many time series, while also preserving the ability to query metrics on a global level.
content/rancher/v2.5/en/monitoring-alerting/migrating/_index.md → content/rancher/v2.5/en/monitoring-alerting/guides/migrating/_index.md
+27 -13
View File
@@ -1,13 +1,22 @@
---
title: Migrating to Rancher v2.5 Monitoring
weight: 5
weight: 9
aliases:
- /rancher/v2.5/en/monitoring-alerting/v2.5/migrating
---
If you previously enabled Monitoring, Alerting, or Notifiers in Rancher before v2.5, there is no automatic upgrade path for switching to the new monitoring/alerting solution. Before deploying the new monitoring solution via Cluster Explore, you will need to disable and remove all existing custom alerts, notifiers and monitoring installations for the whole cluster and in all projects.
### Monitoring Before Rancher v2.5
- [Monitoring Before Rancher v2.5](#monitoring-before-rancher-v2-5)
- [Monitoring and Alerting via Cluster Explorer in Rancher v2.5](#monitoring-and-alerting-via-cluster-explorer-in-rancher-v2-5)
- [Changes to Role-based Access Control](#changes-to-role-based-access-control)
- [Migrating from Monitoring V1 to Monitoring V2](#migrating-from-monitoring-v1-to-monitoring-v2)
- [Migrating Grafana Dashboards](#migrating-grafana-dashboards)
- [Migrating Alerts](#migrating-alerts)
- [Migrating Notifiers](#migrating-notifiers)
- [Migrating for RKE Template Users](#migrating-for-rke-template-users)
# Monitoring Before Rancher v2.5
As of v2.2.0, Rancher's Cluster Manager allowed users to enable Monitoring & Alerting V1 (both powered by [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator)) independently within a cluster.
@@ -17,7 +26,7 @@ Monitoring V1 could be configured on both a cluster-level and on a project-level
When Alerts or Notifiers are enabled, Alerting V1 deploys [Prometheus Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) and a set of Rancher controllers onto a cluster that allows users to define alerts and configure alert-based notifications via Email, Slack, PagerDuty, etc. Users can choose to create different types of alerts depending on what needs to be monitored (e.g. System Services, Resources, CIS Scans, etc.); however, PromQL Expression-based alerts can only be created if Monitoring V1 is enabled.
### Monitoring/Alerting via Cluster Explorer in Rancher 2.5
# Monitoring and Alerting via Cluster Explorer in Rancher 2.5
As of v2.5.0, Rancher's Cluster Explorer now allows users to enable Monitoring & Alerting V2 (both powered by [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator)) together within a cluster.
@@ -27,28 +36,28 @@ Monitoring V2 can only be configured on the cluster level. Project-level monitor
For more information on how to configure Monitoring & Alerting V2, see [this page.]({{<baseurl>}}/rancher/v2.5/en/monitoring-alerting/v2.5/configuration)
### Changes to Role-based Access Control
# Changes to Role-based Access Control
Project owners and members no longer get access to Grafana or Prometheus by default. If view-only users had access to Grafana, they would be able to see data from any namespace. For Kiali, any user can edit things they don’t own in any namespace.
For more information about role-based access control in `rancher-monitoring`, refer to [this page.](../rbac)
### Migrating from Monitoring V1 to Monitoring V2
# Migrating from Monitoring V1 to Monitoring V2
While there is no automatic migration available, it is possible to manually migrate custom Grafana dashboards and alerts that were created in Monitoring V1 to Monitoring V2.
Before you can install Monitoring V2, Monitoring V1 needs to be uninstalled completely. In order to uninstall Monitoring V1:
* Remove all cluster and project specific alerts and alerts groups
* Remove all notifiers
* Disable all project monitoring installations under Cluster -> Project -> Tools -> Monitoring
* Remove all cluster and project specific alerts and alerts groups.
* Remove all notifiers.
* Disable all project monitoring installations under Cluster -> Project -> Tools -> Monitoring.
* Ensure that all project-monitoring apps in all projects have been removed and are not recreated after a few minutes
* Disable the cluster monitoring installation under Cluster -> Tools -> Monitoring
* Ensure that the cluster-monitoring app and the monitoring-operator app in the System project have been removed and are not recreated after a few minutes
* Disable the cluster monitoring installation under Cluster -> Tools -> Monitoring.
* Ensure that the cluster-monitoring app and the monitoring-operator app in the System project have been removed and are not recreated after a few minutes.
#### RKE Template Clusters
To prevent v1 monitoring from being re-enabled, disable monitoring and in future RKE template revisions via modification of the RKE template yaml:
To prevent V1 monitoring from being re-enabled, disable monitoring and in future RKE template revisions via modification of the RKE template yaml:
```yaml
enable_cluster_alerting: false
@@ -86,7 +95,7 @@ data:
Once this ConfigMap is created, the dashboard will automatically be added to Grafana.
#### Migrating Alerts
### Migrating Alerts
It is only possible to directly migrate expression-based alerts to Monitoring V2. Fortunately, the event-based alerts that could be set up to alert on system component, node or workload events, are already covered out-of-the-box by the alerts that are part of Monitoring V2. So it is not necessary to migrate them.
@@ -121,6 +130,11 @@ or add the Prometheus Rule through the Cluster Explorer
For more details on how to configure PrometheusRules in Monitoring V2 see [Monitoring Configuration]({{<baseurl>}}/rancher/v2.5/en/monitoring-alerting/v2.5/configuration#prometheusrules).
#### Migrating notifiers
### Migrating Notifiers
There is no direct equivalent for how notifiers work in Monitoring V1. Instead you have to replicate the desired setup with [Routes and Receivers]({{<baseurl>}}/rancher/v2.5/en/monitoring-alerting/v2.5/configuration#alertmanager-config) in Monitoring V2.
### Migrating for RKE Template Users
If the cluster is managed using an RKE template, you will need to disable monitoring in future RKE template revisions to prevent legacy monitoring from being re-enabled.
content/rancher/v2.5/en/monitoring-alerting/guides/monitoring-workloads/_index.md
+31
View File
@@ -0,0 +1,31 @@
---
title: Setting up Monitoring for a Workload
weight: 4
---
- [Display CPU and Memory Metrics for a Workload](#display-cpu-and-memory-metrics-for-a-workload)
- [Setting up Metrics Beyond CPU and Memory](#setting-up-metrics-beyond-cpu-and-memory)
If you only need CPU and memory time series for the workload, you don't need to deploy a ServiceMonitor or PodMonitor because the monitoring application already collects metrics data on resource usage by default.
The steps for setting up monitoring for workloads depend on whether you want basic metrics such as CPU and memory for the workload, or whether you want to scrape custom metrics from the workload.
If you only need CPU and memory time series for the workload, you don't need to deploy a ServiceMonitor or PodMonitor because the monitoring application already collects metrics data on resource usage by default. The resource usage time series data is in Prometheus's local time series database.
Grafana shows the data in aggregate, but you can see the data for the individual workload by using a PromQL query that extracts the data for that workload. Once you have the PromQL query, you can execute the query individually in the Prometheus UI and see the time series visualized there, or you can use the query to customize a Grafana dashboard to display the workload metrics. For examples of PromQL queries for workload metrics, see [this section.](https://rancher.com/docs/rancher/v2.5/en/monitoring-alerting/configuration/expression/#workload-metrics)
To set up custom metrics for your workload, you will need to set up an exporter and create a new ServiceMonitor custom resource to configure Prometheus to scrape metrics from your exporter.
### Display CPU and Memory Metrics for a Workload
By default, the monitoring application already scrapes CPU and memory.
To get some fine-grained detail for a particular workload, you can customize a Grafana dashboard to display the metrics for a particular workload.
### Setting up Metrics Beyond CPU and Memory
For custom metrics, you will need to expose the metrics on your application in a format supported by Prometheus.
Then we recommend that you should create a new ServiceMonitor custom resource. When this resource is created, the Prometheus custom resource will be automatically updated so that its scrape configuration includes the new custom metrics endpoint. Then Prometheus will begin scraping metrics from the endpoint.
You can also create a PodMonitor to expose the custom metrics endpoint, but ServiceMonitors are more appropriate for the majority of use cases.
content/rancher/v2.5/en/monitoring-alerting/persist-grafana/_index.md → content/rancher/v2.5/en/monitoring-alerting/guides/persist-grafana/_index.md
+2 -2
View File
@@ -1,6 +1,6 @@
---
title: Persistent Grafana Dashboards
weight: 4
weight: 6
aliases:
- /rancher/v2.5/en/monitoring-alerting/v2.5/persist-grafana
---
@@ -75,7 +75,7 @@ If you attempt to delete the dashboard in the Grafana UI, you will see the error
### Configuring Namespaces for the Grafana Dashboard ConfigMap
To specify that you would like Grafana to watch for ConfigMaps across all namespaces, set:
To specify that you would like Grafana to watch for ConfigMaps across all namespaces, set this value in the `rancher-monitoring` Helm chart:
```
grafana.sidecar.dashboards.searchNamespace=ALL
content/rancher/v2.5/en/monitoring-alerting/guides/uninstall/_index.md
+14
View File
@@ -0,0 +1,14 @@
---
title: Uninstall Monitoring
weight: 2
---
1. From the **Cluster Explorer,** click Apps & Marketplace.
1. Click **Installed Apps.**
1. Go to the `cattle-monitoring-system` namespace and check the boxes for `rancher-monitoring-crd` and `rancher-monitoring`.
1. Click **Delete.**
1. Confirm **Delete.**
**Result:** `rancher-monitoring` is uninstalled.
> **Note on Persistent Grafana Dashboards:** 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"`. This annotation is added by default in Monitoring V2 v14.5.100+ but can be manually applied on the cattle-dashboards namespace before an uninstall if an older version of the Monitoring chart is currently installed onto your cluster.
content/rancher/v2.5/en/monitoring-alerting/how-monitoring-works/_index.md
+251
View File
@@ -0,0 +1,251 @@
---
title: How Monitoring Works
weight: 1
---
1. [Architecture Overview](#1-architecture-overview)
2. [How Prometheus Works](#2-how-prometheus-works)
3. [How Alertmanager Works](#3-how-alertmanager-works)
4. [Monitoring V2 Specific Components](#4-monitoring-v2-specific-components)
5. [Scraping and Exposing Metrics](#5-scraping-and-exposing-metrics)
# 1. Architecture Overview
This diagram shows how data flows through the Monitoring V2 application:
{{% row %}}
{{% column %}}
![How data flows through the monitoring application]({{<baseurl>}}/img/rancher/monitoring-v2-architecture-overview.svg)
{{% /column %}}
{{% column %}}
1. Rules define what Prometheus metrics or time series database queries should result in alerts being fired.
2. ServiceMonitors and PodMonitors declaratively specify how services and pods should be monitored. They use labels to scrape metrics from pods.
3. Prometheus Operator observes ServiceMonitors, PodMonitors and PrometheusRules being created.
4. When the Prometheus configuration resources are created, Prometheus Operator calls the Prometheus API to sync the new configuration.
5. Recording Rules are not directly used for alerting. They create new time series of precomputed queries. These new time series data can then be queried to generate alerts.
6. Prometheus scrapes all targets in the scrape configuration on a recurring schedule based on the scrape interval, storing the results in its time series database.Depending on the Kubernetes master component and Kubernetes distribution, the metrics from a certain Kubernetes component could be directly exposed to Prometheus, proxied through PushProx, or not available. For details, see Scraping and Exposing Metrics.
7. Prometheus evaluates the alerting rules against the time series database. It fires alerts to Alertmanager whenever an alerting rule evaluates to a positive number.
8. Alertmanager uses routes to group, label and filter the fired alerts to translate them into useful notifications.
9. Alertmanager uses the Receiver configuration to send notifications to Slack, PagerDuty, SMS, or other types of receivers.
{{% /column %}}
{{% /row %}}
# 2. How Prometheus Works
### 2.1. Storing Time Series Data
After collecting metrics from exporters, Prometheus stores the time series in a local on-disk time series database. Prometheus optionally integrates with remote systems, but `rancher-monitoring` uses local storage for the time series database.
The database can then be queried using PromQL, the query language for Prometheus. Grafana dashboards use PromQL queries to generate data visualizations.
### 2.2. Querying the Time Series Database
The PromQL query language is the primary tool to query Prometheus for time series data.
In Grafana, you can right-click a CPU utilization and click Inspect. This opens a panel that shows the [raw query results.](https://grafana.com/docs/grafana/latest/panels/inspect-panel/#inspect-raw-query-results)The raw results demonstrate how each dashboard is powered by PromQL queries.
### 2.3. Defining Rules for when Alerts Should be Fired
Rules define the conditions for Prometheus to fire alerts. When PrometheusRule custom resources are created or updated, the Prometheus Operator observes the change and calls the Prometheus API to synchronize the rule configuration with the Alerting Rules and Recording Rules in Prometheus.
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.
A PrometheusRule allows you to define one or more RuleGroups. Each RuleGroup consists of a set of Rule objects that can each represent either an alerting or a recording rule with the following fields:
- The name of the new alert or record
- A PromQL expression for the new alert or record
- Labels that should be attached to the alert or record that identify it (e.g. cluster name or severity)
- Annotations that encode any additional important pieces of information that need to be displayed on the notification for an alert (e.g. summary, description, message, runbook URL, etc.). This field is not required for recording rules.
### 2.4. Firing Alerts
Prometheus doesn't maintain the state of whether alerts are active. It fires alerts repetitively at every evaluation interval, relying on Alertmanager to group and filter the alerts into meaningful notifications.
The `evaluation_interval` constant defines how often Prometheus evaluates its alerting rules against the time series database. Similar to the `scrape_interval`, the `evaluation_interval` also defaults to one minute.
The rules are contained in a set of rule files. Rule files include both alerting rules and recording rules, but only alerting rules result in alerts being fired after their evaluation.
For recording rules, Prometheus runs a query, then stores it as a time series. This synthetic time series is useful for storing the results of an expensive or time-consuming query so that it can be queried more quickly in the future.
Alerting rules are more commonly used. Whenever an alerting rule evaluates to a positive number, Prometheus fires an alert.
The Rule file adds labels and annotations to alerts before firing them, depending on the use case:
- Labels indicate information that identifies the alert and could affect the routing of the alert. For example, if when sending an alert about a certain container, the container ID could be used as a label.
- Annotations denote information that doesn't affect where an alert is routed, for example, a runbook or an error message.
# 3. How Alertmanager Works
The Alertmanager handles alerts sent by client applications such as the Prometheus server. It takes care of the following tasks:
- Deduplicating, grouping, and routing alerts to the correct receiver integration such as email, PagerDuty, or OpsGenie
- Silencing and inhibition of alerts
- Tracking alerts that fire over time
- Sending out the status of whether an alert is currently firing, or if it is resolved
### 3.1. Routing Alerts to Receivers
Alertmanager coordinates where alerts are sent. It allows you to group alerts based on labels and fire them based on whether certain labels are matched. One top-level route accepts all alerts. From there, Alertmanager continues routing alerts to receivers based on whether they match the conditions of the next route.
While the Rancher UI forms only allow editing a routing tree that is two levels deep, you can configure more deeply nested routing structures by editing the Alertmanager custom resource YAML.
### 3.2. Configuring Multiple Receivers
By editing the forms in the Rancher UI, you can set up a Receiver resource with all the information Alertmanager needs to send alerts to your notification system.
By editing custom YAML in the Alertmanager or Receiver configuration, you can also send alerts to multiple notification systems. For more information, see the section on configuring [Receivers.](./configuration/receiver/#configuring-multiple-receivers)
# 4. Monitoring V2 Specific Components
Prometheus Operator introduces a set of [Custom Resource Definitions](https://github.com/prometheus-operator/prometheus-operator#customresourcedefinitions) that allow users to deploy and manage Prometheus and Alertmanager instances by creating and modifying those custom resources on a cluster.
Prometheus Operator will automatically update your Prometheus configuration based on the live state of the resources and configuration options that are edited in the Rancher UI.
### 4.1. Resources Deployed by Default
By default, a set of resources curated by the [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) project are deployed onto your cluster as part of installing the Rancher Monitoring Application to set up a basic Monitoring/Alerting stack.
The resources that get deployed onto your cluster to support this solution can be found in the [`rancher-monitoring`](https://github.com/rancher/charts/tree/main/charts/rancher-monitoring) Helm chart, which closely tracks the upstream [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) Helm chart maintained by the Prometheus community with certain changes tracked in the [CHANGELOG.md](https://github.com/rancher/charts/blob/main/charts/rancher-monitoring/CHANGELOG.md).
There are also certain special types of ConfigMaps and Secrets such as those corresponding to Grafana Dashboards, Grafana Datasources, and Alertmanager Configs that will automatically update your Prometheus configuration via sidecar proxies that observe the live state of those resources within your cluster.
### 4.2. PushProx
PushProx enhances the security of the monitoring application, allowing it to be installed on hardened Kubernetes clusters.
To expose Kubernetes metrics, PushProxes use a client proxy model to expose specific ports within default Kubernetes components. Node exporters expose metrics to PushProx through an outbound connection.
The proxy allows `rancher-monitoring` to scrape metrics from processes on the hostNetwork, such as the `kube-api-server`, without opening up node ports to inbound connections.
PushProx is a DaemonSet that listens for clients that seek to register. Once registered, it proxies scrape requests through the established connection. Then the client executes the request to etcd.
All of the default ServiceMonitors, such as `rancher-monitoring-kube-controller-manager`, are configured to hit the metrics endpoint of the client using this proxy.
For more details about how PushProx works, refer to [Scraping Metrics with PushProx.](#5-5-scraping-metrics-with-pushprox)
### 4.3. Default Exporters
`rancher-monitoring` deploys two exporters to expose metrics to prometheus: `node-exporter` and `windows-exporter`. Both are deployed as DaemonSets.
`node-exporter` exports container, pod and node metrics for CPU and memory from each Linux node. `windows-exporter` does the same, but for Windows nodes.
For more information on `node-exporter`, refer to the [upstream documentation.](https://prometheus.io/docs/guides/node-exporter/)
[kube-state-metrics](https://github.com/kubernetes/kube-state-metrics) is also useful because it exports metrics for Kubernetes components.
### 4.4. Components Exposed in the Rancher UI
When the monitoring application is installed, you will be able to edit the following components in the Rancher UI:
| Component | Type of Component | Purpose and Common Use Cases for Editing |
|--------------|------------------------|---------------------------|
| ServiceMonitor | Custom resource | Set up targets to scrape custom metrics from. Automatically updates the scrape configuration in the Prometheus custom resource. |
| PodMonitor | Custom resource | Set up targets to scrape custom metrics from. Automatically updates the scrape configuration in the Prometheus custom resource. |
| Receiver | Configuration block (part of Alertmanager) | Set up a notification system to receive alerts. Automatically updates the Alertmanager custom resource. |
| Route | Configuration block (part of Alertmanager) | Add identifying information to make alerts more meaningful and direct them to individual teams. Automatically updates the Alertmanager custom resource. |
| PrometheusRule | Custom resource | For more advanced use cases, you may want to define what Prometheus metrics or time series database queries should result in alerts being fired. Automatically updates the Prometheus custom resource. |
| Alertmanager | Custom resource | Edit this custom resource only if you need more advanced configuration options beyond what the Rancher UI exposes in the Routes and Receivers sections. For example, you might want to edit this resource to add a routing tree with more than two levels. |
| Prometheus | Custom resource | Edit this custom resource only if you need more advanced configuration beyond what can be configured using ServiceMonitors, PodMonitors, or [Rancher monitoring Helm chart options.](./configuration/helm-chart-options) |
# 5. Scraping and Exposing Metrics
### 5.1. Defining what Metrics are Scraped
ServiceMonitors define targets that are intended for Prometheus to scrape. The [Prometheus custom resource tells](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/design.md#prometheus) Prometheus which ServiceMonitors it should use to find out where to scrape metrics from.
The Prometheus Operator observes the ServiceMonitors. When it observes that ServiceMonitors are created or updated, it calls the Prometheus API to update the scrape configuration in the Prometheus custom resource and keep it in sync with the scrape configuration in the ServiceMonitors. This scrape configuration tells Prometheus which endpoints to scrape metrics from and how it will label the metrics from those endpoints.
Prometheus scrapes all of the metrics defined in its scrape configuration at every `scrape_interval`, which is one minute by default.
The scrape configuration can be viewed as part of the Prometheus custom resource that is exposed in the Rancher UI.
### 5.2. How the Prometheus Operator Sets up Metrics Scraping
The Prometheus Deployment or StatefulSet scrapes metrics, and the configuration of Prometheus is controlled by the Prometheus custom resources. The Prometheus Operator watches for Prometheus and Alertmanager resources, and when they are created, the Prometheus Operator creates a Deployment or StatefulSet for Prometheus or Alertmanager with the user-defined configuration.
<figcaption>How the Prometheus Operator Sets up Metrics Scraping</figcaption>
![How the Prometheus Operator sets up metrics scraping]({{<baseurl>}}/img/rancher/set-up-scraping.svg)
When the Prometheus Operator observes ServiceMonitors, PodMonitors and PrometheusRules being created, it knows that the scrape configuration needs to be updated in Prometheus. It updates Prometheus by first updating the configuration and rules files in the volumes of Prometheus's Deployment or StatefulSet. Then it calls the Prometheus API to sync the new configuration, resulting in the Prometheus Deployment or StatefulSet to be modified in place.
![How the Prometheus Operator Updates Scrape Configuration]({{<baseurl>}}/img/rancher/update-scrape-config.svg)
### 5.3. How Kubernetes Component Metrics are Exposed
Prometheus scrapes metrics from deployments known as [exporters,](https://prometheus.io/docs/instrumenting/exporters/) which export the time series data in a format that Prometheus can ingest. In Prometheus, time series consist of streams of timestamped values belonging to the same metric and the same set of labeled dimensions.
To allow monitoring to be installed on hardened Kubernetes clusters, `rancher-monitoring` application proxies the communication between Prometheus and the exporter through PushProx for some Kubernetes master components.
### 5.4. Scraping Metrics without PushProx
The Kubernetes components that directly expose metrics to Prometheus are the following:
- kubelet
- ingress-nginx*
- coreDns/kubeDns
- kube-api-server
\* For RKE and RKE2 clusters, ingress-nginx is deployed by default and treated as an internal Kubernetes component.
### 5.5. Scraping Metrics with PushProx
The purpose of this architecture is to allow us to scrape internal Kubernetes components without exposing those ports to inbound requests. As a result, Prometheus can scrape metrics across a network boundary.
The Kubernetes components that expose metrics to Prometheus through PushProx are the following:
- kube-controller-manager
- kube-scheduler
- etcd
- kube-proxy
For each PushProx exporter, we deploy one PushProx client onto all target nodes. For example, a PushProx client is deployed onto all controlplane nodes for kube-controller-manager, all etcd nodes for kube-etcd, and all nodes for kubelet. We deploy exactly one PushProx proxy per exporter.
The process for exporting metrics is as follows:
1. The PushProx Client establishes an outbound connection with the PushProx Proxy.
2. The client then polls the proxy for scrape requests that have come into the proxy.
3. When the proxy receives a scrape request from Prometheus, the client sees it as a result of the poll.
4. The client scrapes the internal component.
5. The internal component responds by pushing metrics back to the proxy.
<figcaption>Process for Exporting Metrics with PushProx</figcaption>
![Process for Exporting Metrics with PushProx]({{<baseurl>}}/img/rancher/pushprox-process.svg)
Metrics are scraped differently based on the Kubernetes distribution. For help with terminology, see Terminology(#terminology). For details, see the table below:
<figcaption>How Metrics are Exposed to Prometheus</figcaption>
| Kubernetes Component | RKE | RKE2 | KubeADM | K3s |
|-----|-----|-----|-----|-----|
| kube-controller-manager | rkeControllerManager.enabled |rke2ControllerManager.enabled | kubeAdmControllerManager.enabled | k3sServer.enabled |
| kube-scheduler | rkeScheduler.enabled | rke2Scheduler.enabled |kubeAdmScheduler.enabled | k3sServer.enabled |
| etcd | rkeEtcd.enabled | rke2Etcd.enabled | kubeAdmEtcd.enabled | Not available |
| kube-proxy | rkeProxy.enabled | rke2Proxy.enabled | kubeAdmProxy.enabled | k3sServer.enabled |
| kubelet | Collects metrics directly exposed by kubelet | Collects metrics directly exposed by kubelet | Collects metrics directly exposed by kubelet | Collects metrics directly exposed by kubelet |
| ingress-nginx* | Collects metrics directly exposed by kubelet, exposed by rkeIngressNginx.enabled | Collects metrics directly exposed by kubelet, Exposed by rke2IngressNginx.enabled | Not available | Not available |
| coreDns/kubeDns | Collects metrics directly exposed by coreDns/kubeDns | Collects metrics directly exposed by coreDns/kubeDns | Collects metrics directly exposed by coreDns/kubeDns | Collects metrics directly exposed by coreDns/kubeDns |
| kube-api-server | Collects metrics directly exposed by kube-api-server |Collects metrics directly exposed by kube-api-server | Collects metrics directly exposed by kube-appi-server | Collects metrics directly exposed by kube-api-server |
\* For RKE and RKE2 clusters, ingress-nginx is deployed by default and treated as an internal Kubernetes component.
### 5.6. Terminology
- **kube-scheduler:** The internal Kubernetes component that uses information in the pod spec to decide on which node to run a pod.
- **kube-controller-manager:** The internal Kubernetes component that is responsible for node management (detecting if a node fails), pod replication and endpoint creation.
- **etcd:** The internal Kubernetes component that is the distributed key/value store which Kubernetes uses for persistent storage of all cluster information.
- **kube-proxy:** The internal Kubernetes component that watches the API server for pods/services changes in order to maintain the network up to date.
- **kubelet:** The internal Kubernetes component that watches the API server for pods on a node and makes sure they are running.
- **ingress-nginx:** An Ingress controller for Kubernetes using NGINX as a reverse proxy and load balancer.
- **coreDns/kubeDns:** The internal Kubernetes component responsible for DNS.
- **kube-api-server:** The main internal Kubernetes component that is responsible for exposing APIs for the other master components.
content/rancher/v2.5/en/monitoring-alerting/rbac/_index.md
+21 -2
View File
@@ -1,9 +1,11 @@
---
title: RBAC
weight: 3
title: Role-based Access Control
shortTitle: RBAC
weight: 2
aliases:
- /rancher/v2.5/en/cluster-admin/tools/monitoring/rbac
- /rancher/v2.5/en/monitoring-alerting/v2.5/rbac
- /rancher/v2.5/en/monitoring-alerting/grafana
---
This section describes the expectations for RBAC for Rancher Monitoring.
@@ -17,6 +19,7 @@ This section describes the expectations for RBAC for Rancher Monitoring.
- [Users with Rancher Cluster Manager Based Permissions](#users-with-rancher-cluster-manager-based-permissions)
- [Differences in 2.5.x](#differences-in-2-5-x)
- [Assigning Additional Access](#assigning-additional-access)
- [Role-based Access Control for Grafana](#role-based-access-control-for-grafana)
# Cluster Admins
@@ -131,3 +134,19 @@ If cluster-admins would like to provide additional admin/edit access to users ou
|----------------------------| ------| ------| ----------------------------|
| <ul><li>`secrets`</li><li>`configmaps`</li></ul>| `cattle-monitoring-system` | Yes, Configs and Secrets in this namespace can impact the entire monitoring / alerting pipeline. | User will be able to create or edit Secrets / ConfigMaps such as the Alertmanager Config, Prometheus Adapter Config, TLS secrets, additional Grafana datasources, etc. This can have broad impact on all cluster monitoring / alerting. |
| <ul><li>`secrets`</li><li>`configmaps`</li></ul>| `cattle-dashboards` | Yes, Configs and Secrets in this namespace can create dashboards that make queries on all metrics collected at a cluster-level. | User will be able to create Secrets / ConfigMaps that persist new Grafana Dashboards only. |
# Role-based Access Control for Grafana
Rancher allows any users who are authenticated by Kubernetes and have access the Grafana service deployed by the Rancher Monitoring chart to access Grafana via the Rancher Dashboard UI. By default, all users who are able to access Grafana are given the [Viewer](https://grafana.com/docs/grafana/latest/permissions/organization_roles/#viewer-role) role, which allows them to view any of the default dashboards deployed by Rancher.
However, users can choose to log in to Grafana as an [Admin](https://grafana.com/docs/grafana/latest/permissions/organization_roles/#admin-role) if necessary. The default Admin username and password for the Grafana instance will be `admin`/`prom-operator`, but alternative credentials can also be supplied on deploying or upgrading the chart.
To see the Grafana UI, install `rancher-monitoring`. Then go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Grafana.
<figcaption>Cluster Compute Resources Dashboard in Grafana</figcaption>
![Cluster Compute Resources Dashboard in Grafana]({{<baseurl>}}/img/rancher/cluster-compute-resources-dashboard.png)
<figcaption>Default Dashboards in Grafana</figcaption>
![Default Dashboards in Grafana]({{<baseurl>}}/img/rancher/grafana-default-dashboard.png)
content/rancher/v2.5/en/monitoring-alerting/windows-clusters/_index.md
+1 -1
View File
@@ -1,6 +1,6 @@
---
title: Windows Cluster Support for Monitoring V2
shortTitle: Windows Clusters
shortTitle: Windows Support
weight: 5
---
content/rancher/v2.5/en/pipelines/_index.md
+1 -1
View File
@@ -19,7 +19,7 @@ After configuring Rancher and GitHub, you can deploy containers running Jenkins
- Run unit tests.
- Run regression tests.
>**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.
>**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.
This section covers the following topics:
content/rancher/v2.6/_index.md
+5
View File
@@ -0,0 +1,5 @@
---
title: v2.6.x
weight: 1
showBreadcrumb: false
---
content/rancher/v2.6/en/_index.md
+21
View File
@@ -0,0 +1,21 @@
---
title: "Rancher 2.6"
shortTitle: "Rancher 2.6 (Latest)"
description: "Rancher adds significant value on top of Kubernetes: managing hundreds of clusters from one interface, centralizing RBAC, enabling monitoring and alerting. Read more."
metaTitle: "Rancher 2.x Docs: What is New?"
metaDescription: "Rancher 2 adds significant value on top of Kubernetes: managing hundreds of clusters from one interface, centralizing RBAC, enabling monitoring and alerting. Read more."
insertOneSix: false
weight: 1
ctaBanner: 0
---
Rancher was originally built to work with multiple orchestrators, and it included its own orchestrator called Cattle. With the rise of Kubernetes in the marketplace, Rancher 2 exclusively deploys and manages Kubernetes clusters running anywhere, on any provider.
Rancher can provision Kubernetes from a hosted provider, provision compute nodes and then install Kubernetes onto them, or import existing Kubernetes clusters running anywhere.
One Rancher server installation can manage thousands of Kubernetes clusters and thousands of nodes from the same user interface.
Rancher adds significant value on top of Kubernetes, first by centralizing authentication and role-based access control (RBAC) for all of the clusters, giving global admins the ability to control cluster access from one location.
It then enables detailed monitoring and alerting for clusters and their resources, ships logs to external providers, and integrates directly with Helm via the Application Catalog. If you have an external CI/CD system, you can plug it into Rancher, but if you don't, Rancher even includes Fleet to help you automatically deploy and upgrade workloads.
Rancher is a _complete_ container management platform for Kubernetes, giving you the tools to successfully run Kubernetes anywhere.
content/rancher/v2.6/en/admin-settings/_index.md
+50
View File
@@ -0,0 +1,50 @@
---
title: Authentication, Permissions and Global Configuration
weight: 6
---
After installation, the [system administrator]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) should configure Rancher to configure authentication, authorization, security, default settings, security policies, drivers and global DNS entries.
## First Log In
After you log into Rancher for the first time, Rancher will prompt you for a **Rancher Server URL**.You should set the URL to the main entry point to the Rancher Server. When a load balancer sits in front a Rancher Server cluster, the URL should resolve to the load balancer. The system will automatically try to infer the Rancher Server URL from the IP address or host name of the host running the Rancher Server. This is only correct if you are running a single node Rancher Server installation. In most cases, therefore, you need to set the Rancher Server URL to the correct value yourself.
>**Important!** After you set the Rancher Server URL, we do not support updating it. Set the URL with extreme care.
## Authentication
One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows to set up local users and/or connect to an external authentication provider. By connecting to an external authentication provider, you can leverage that provider's user and groups.
For more information how authentication works and how to configure each provider, see [Authentication]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/).
## Authorization
Within Rancher, each person authenticates as a _user_, which is a login that grants you access to Rancher. Once the user logs in to Rancher, their _authorization_, or their access rights within the system, is determined by the user's role. Rancher provides built-in roles to allow you to easily configure a user's permissions to resources, but Rancher also provides the ability to customize the roles for each Kubernetes resource.
For more information how authorization works and how to customize roles, see [Roles Based Access Control (RBAC)]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/).
## Pod Security Policies
_Pod Security Policies_ (or PSPs) are objects that control security-sensitive aspects of pod specification, e.g. root privileges. If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message.
For more information how to create and use PSPs, see [Pod Security Policies]({{<baseurl>}}/rancher/v2.6/en/admin-settings/pod-security-policies/).
## Provisioning Drivers
Drivers in Rancher allow you to manage which providers can be used to provision [hosted Kubernetes clusters]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes.
For more information, see [Provisioning Drivers]({{<baseurl>}}/rancher/v2.6/en/admin-settings/drivers/).
## Adding Kubernetes Versions into Rancher
With this feature, you can upgrade to the latest version of Kubernetes as soon as it is released, without upgrading Rancher. This feature allows you to easily upgrade Kubernetes patch versions (i.e. `v1.15.X`), but not intended to upgrade Kubernetes minor versions (i.e. `v1.X.0`) as Kubernetes tends to deprecate or add APIs between minor versions.
The information that Rancher uses to provision [RKE clusters]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/) is now located in the Rancher Kubernetes Metadata. For details on metadata configuration and how to change the Kubernetes version used for provisioning RKE clusters, see [Rancher Kubernetes Metadata.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/k8s-metadata/)
Rancher Kubernetes Metadata contains Kubernetes version information which Rancher uses to provision [RKE clusters]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/).
For more information on how metadata works and how to configure metadata config, see [Rancher Kubernetes Metadata]({{<baseurl>}}/rancher/v2.6/en/admin-settings/k8s-metadata/).
## Enabling Experimental Features
Rancher includes some features that are experimental and disabled by default. Feature flags were introduced to allow you to try these features. For more information, refer to the section about [feature flags.]({{<baseurl>}}/rancher/v2.6/en/installation/options/feature-flags/)
content/rancher/v2.6/en/admin-settings/authentication/_index.md
+93
View File
@@ -0,0 +1,93 @@
---
title: Authentication
weight: 10
---
One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows your users to use one set of credentials to authenticate with any of your Kubernetes clusters.
This centralized user authentication is accomplished using the Rancher authentication proxy, which is installed along with the rest of Rancher. This proxy authenticates your users and forwards their requests to your Kubernetes clusters using a service account.
## External vs. Local Authentication
The Rancher authentication proxy integrates with the following external authentication services.
| Auth Service |
| ------------------------------------------------------------------------------------------------ |
| [Microsoft Active Directory]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/ad/) |
| [GitHub]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/github/) |
| [Microsoft Azure AD]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/azure-ad/) |
| [FreeIPA]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/freeipa/) |
| [OpenLDAP]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/openldap/) |
| [Microsoft AD FS]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/) |
| [PingIdentity]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/ping-federate/) |
| [Keycloak (OIDC)]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/keycloak-oidc/) |
| [Keycloak (SAML)]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/keycloak-saml/) |
| [Okta]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/okta/) |
| [Google OAuth]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/google/) |
| [Shibboleth]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/shibboleth) |
<br/>
However, Rancher also provides [local authentication]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/local/).
In most cases, you should use an external authentication service over local authentication, as external authentication allows user management from a central location. However, you may want a few local authentication users for managing Rancher under rare circumstances, such as if your external authentication provider is unavailable or undergoing maintenance.
## Users and Groups
Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When authenticating with an external provider, groups are provided from the external provider based on the user. These users and groups are given specific roles to resources like clusters, projects, multi-cluster apps, and global DNS providers and entries. When you give access to a group, all users who are a member of that group in the authentication provider will be able to access the resource with the permissions that you've specified. For more information on roles and permissions, see [Role Based Access Control]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/).
> **Note:** Local authentication does not support creating or managing groups.
For more information, see [Users and Groups]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/user-groups/)
## Scope of Rancher Authorization
After you configure Rancher to allow sign on using an external authentication service, you should configure who should be allowed to log in and use Rancher. The following options are available:
| Access Level | Description |
|----------------------------------------------|-------------|
| Allow any valid Users | _Any_ user in the authorization service can access Rancher. We generally discourage use of this setting! |
| Allow members of Clusters, Projects, plus Authorized Users and Organizations | Any user in the authorization service and any group added as a **Cluster Member** or **Project Member** can log in to Rancher. Additionally, any user in the authentication service or group you add to the **Authorized Users and Organizations** list may log in to Rancher. |
| Restrict access to only Authorized Users and Organizations | Only users in the authentication service or groups added to the Authorized Users and Organizations can log in to Rancher. |
To set the Rancher access level for users in the authorization service, follow these steps:
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Auth Provider**.
1. After setting up the configuration details for an auth provider, use the **Site Access** options to configure the scope of user authorization. The table above explains the access level for each option.
1. Optional: If you choose an option other than **Allow any valid Users,** you can add users to the list of authorized users and organizations by searching for them in the text field that appears.
1. Click **Save**.
**Result:** The Rancher access configuration settings are applied.
{{< saml_caveats >}}
## External Authentication Configuration and Principal Users
Configuration of external authentication requires:
- A local user assigned the administrator role, called hereafter the _local principal_.
- An external user that can authenticate with your external authentication service, called hereafter the _external principal_.
Configuration of external authentication affects how principal users are managed within Rancher. Follow the list below to better understand these effects.
1. Sign into Rancher as the local principal and complete configuration of external authentication.
![Sign In]({{<baseurl>}}/img/rancher/sign-in.png)
2. Rancher associates the external principal with the local principal. These two users share the local principal's user ID.
![Principal ID Sharing]({{<baseurl>}}/img/rancher/principal-ID.png)
3. After you complete configuration, Rancher automatically signs out the local principal.
![Sign Out Local Principal]({{<baseurl>}}/img/rancher/sign-out-local.png)
4. Then, Rancher automatically signs you back in as the external principal.
![Sign In External Principal]({{<baseurl>}}/img/rancher/sign-in-external.png)
5. Because the external principal and the local principal share an ID, no unique object for the external principal displays on the Users page.
![Sign In External Principal]({{<baseurl>}}/img/rancher/users-page.png)
6. The external principal and the local principal share the same access rights.
content/rancher/v2.6/en/admin-settings/authentication/ad/_index.md
+200
View File
@@ -0,0 +1,200 @@
---
title: Configuring Active Directory (AD)
weight: 1112
---
If your organization uses Microsoft Active Directory as central user repository, you can configure Rancher to communicate with an Active Directory server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the Active Directory, while allowing end-users to authenticate with their AD credentials when logging in to the Rancher UI.
Rancher uses LDAP to communicate with the Active Directory server. The authentication flow for Active Directory is therefore the same as for the [OpenLDAP authentication]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/openldap) integration.
> **Note:**
>
> Before you start, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
## Prerequisites
You'll need to create or obtain from your AD administrator a new AD user to use as service account for Rancher. This user must have sufficient permissions to perform LDAP searches and read attributes of users and groups under your AD domain.
Usually a (non-admin) **Domain User** account should be used for this purpose, as by default such user has read-only privileges for most objects in the domain partition.
Note however, that in some locked-down Active Directory configurations this default behaviour may not apply. In such case you will need to ensure that the service account user has at least **Read** and **List Content** permissions granted either on the Base OU (enclosing users and groups) or globally for the domain.
> **Using TLS?**
>
> If the certificate used by the AD server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
## Configuration Steps
### Open Active Directory Configuration
1. Log into the Rancher UI using the initial local `admin` account.
1. In the top left corner, click **☰ > Users & Authentication**.
1. In the left navigation menu, click **Auth Provider**.
1. Click **ActiveDirectory**. The **Authentication Provider: ActiveDirectory** form will be displayed.
1. Fill out the form. For help, refer to the details on configuration options below.
1. Click **Enable**.
### Configure Active Directory Server Settings
In the section titled `1. Configure an Active Directory server`, complete the fields with the information specific to your Active Directory server. Please refer to the following table for detailed information on the required values for each parameter.
> **Note:**
>
> If you are unsure about the correct values to enter in the user/group Search Base field, please refer to [Identify Search Base and Schema using ldapsearch](#annex-identify-search-base-and-schema-using-ldapsearch).
**Table 1: AD Server parameters**
| Parameter | Description |
|:--|:--|
| Hostname | Specify the hostname or IP address of the AD server |
| Port | Specify the port at which the Active Directory server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.|
| TLS | Check this box to enable LDAP over SSL/TLS (commonly known as LDAPS).|
| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the AD server unreachable. |
| Service Account Username | Enter the username of an AD account with read-only access to your domain partition (see [Prerequisites](#prerequisites)). The username can be entered in NetBIOS format (e.g. "DOMAIN\serviceaccount") or UPN format (e.g. "serviceaccount@domain.com"). |
| Service Account Password | The password for the service account. |
| Default Login Domain | When you configure this field with the NetBIOS name of your AD domain, usernames entered without a domain (e.g. "jdoe") will automatically be converted to a slashed, NetBIOS logon (e.g. "LOGIN_DOMAIN\jdoe") when binding to the AD server. If your users authenticate with the UPN (e.g. "jdoe@acme.com") as username then this field **must** be left empty. |
| User Search Base | 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 it empty. For example: "ou=groups,dc=acme,dc=com".|
---
### Configure User/Group Schema
In the section titled `2. Customize Schema` you must provide Rancher with a correct mapping of user and group attributes corresponding to the schema used in your directory.
Rancher uses LDAP queries to search for and retrieve information about users and groups within the Active Directory. The attribute mappings configured in this section are used to construct search filters and resolve group membership. It is therefore paramount that the provided settings reflect the reality of your AD domain.
> **Note:**
>
> If you are unfamiliar with the schema used in your Active Directory domain, please refer to [Identify Search Base and Schema using ldapsearch](#annex-identify-search-base-and-schema-using-ldapsearch) to determine the correct configuration values.
#### User Schema
The table below details the parameters for the user schema section configuration.
**Table 2: User schema configuration parameters**
| Parameter | Description |
|:--|:--|
| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
| Username Attribute | The user attribute whose value is suitable as a display name. |
| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. If your users authenticate with their UPN (e.g. "jdoe@acme.com") as username then this field must normally be set to `userPrincipalName`. Otherwise for the old, NetBIOS-style logon names (e.g. "jdoe") it's usually `sAMAccountName`. |
| User Member Attribute | The attribute containing the groups that a user is a member of. |
| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the AD server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. To match UPN usernames (e.g. jdoe@acme.com) you should usually set the value of this field to `userPrincipalName`. |
| Search Filter | This filter gets applied to the list of users that is searched when Rancher attempts to add users to a site access list or tries to add members to clusters or projects. For example, a user search filter could be <code>(&#124;(memberOf=CN=group1,CN=Users,DC=testad,DC=rancher,DC=io)(memberOf=CN=group2,CN=Users,DC=testad,DC=rancher,DC=io))</code>. Note: If the search filter does not use [valid AD search syntax,](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) the list of users will be empty. |
| User Enabled Attribute | The attribute containing an integer value representing a bitwise enumeration of user account flags. Rancher uses this to determine if a user account is disabled. You should normally leave this set to the AD standard `userAccountControl`. |
| Disabled Status Bitmask | This is the value of the `User Enabled Attribute` designating a disabled user account. You should normally leave this set to the default value of "2" as specified in the Microsoft Active Directory schema (see [here](https://docs.microsoft.com/en-us/windows/desktop/adschema/a-useraccountcontrol#remarks)). |
---
#### Group Schema
The table below details the parameters for the group schema configuration.
**Table 3: Group schema configuration parameters**
| Parameter | Description |
|:--|:--|
| Object Class | The name of the object class used for group objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
| Name Attribute | The group attribute whose value is suitable for a display name. |
| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. |
| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. |
| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects. See description of user schema `Search Attribute`. |
| Search Filter | This filter gets applied to the list of groups that is searched when Rancher attempts to add groups to a site access list or tries to add groups to clusters or projects. For example, a group search filter could be <code>(&#124;(cn=group1)(cn=group2))</code>. Note: If the search filter does not use [valid AD search syntax,](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) the list of groups will be empty. |
| Group DN Attribute | The name of the group attribute whose format matches the values in the user attribute describing a the user's memberships. See `User Member Attribute`. |
| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organisation makes use of these nested memberships (ie. you have groups that contain other groups as members. We advise avoiding nested groups when possible). |
---
### Test Authentication
Once you have completed the configuration, proceed by testing the connection to the AD server **using your AD admin account**. If the test is successful, authentication with the configured Active Directory will be enabled implicitly with the account you test with set as admin.
> **Note:**
>
> The AD user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which AD account you use to perform this step.
1. Enter the **username** and **password** for the AD account that should be mapped to the local principal account.
2. Click **Authenticate with Active Directory** to finalise the setup.
**Result:**
- Active Directory authentication has been enabled.
- You have been signed into Rancher as administrator using the provided AD credentials.
> **Note:**
>
> You will still be able to login using the locally configured `admin` account and password in case of a disruption of LDAP services.
## Annex: Identify Search Base and Schema using ldapsearch
In order to successfully configure AD authentication it is crucial that you provide the correct configuration pertaining to the hierarchy and schema of your AD server.
The [`ldapsearch`](http://manpages.ubuntu.com/manpages/artful/man1/ldapsearch.1.html) tool allows you to query your AD server to learn about the schema used for user and group objects.
For the purpose of the example commands provided below we will assume:
- The Active Directory server has a hostname of `ad.acme.com`
- The server is listening for unencrypted connections on port `389`
- The Active Directory domain is `acme`
- You have a valid AD account with the username `jdoe` and password `secret`
### Identify Search Base
First we will use `ldapsearch` to identify the Distinguished Name (DN) of the parent node(s) for users and groups:
```
$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
-h ad.acme.com -b "dc=acme,dc=com" -s sub "sAMAccountName=jdoe"
```
This command performs an LDAP search with the search base set to the domain root (`-b "dc=acme,dc=com"`) and a filter targeting the user account (`sAMAccountNam=jdoe`), returning the attributes for said user:
{{< img "/img/rancher/ldapsearch-user.png" "LDAP User">}}
Since in this case the user's DN is `CN=John Doe,CN=Users,DC=acme,DC=com` [5], we should configure the **User Search Base** with the parent node DN `CN=Users,DC=acme,DC=com`.
Similarly, based on the DN of the group referenced in the **memberOf** attribute [4], the correct value for the **Group Search Base** would be the parent node of that value, ie. `OU=Groups,DC=acme,DC=com`.
### Identify User Schema
The output of the above `ldapsearch` query also allows to determine the correct values to use in the user schema configuration:
- `Object Class`: **person** [1]
- `Username Attribute`: **name** [2]
- `Login Attribute`: **sAMAccountName** [3]
- `User Member Attribute`: **memberOf** [4]
> **Note:**
>
> If the AD users in our organisation were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the `Login Attribute` to **userPrincipalName** instead.
We'll also set the `Search Attribute` parameter to **sAMAccountName|name**. That way users can be added to clusters/projects in the Rancher UI either by entering their username or full name.
### Identify Group Schema
Next, we'll query one of the groups associated with this user, in this case `CN=examplegroup,OU=Groups,DC=acme,DC=com`:
```
$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
-h ad.acme.com -b "ou=groups,dc=acme,dc=com" \
-s sub "CN=examplegroup"
```
This command will inform us on the attributes used for group objects:
{{< img "/img/rancher/ldapsearch-group.png" "LDAP Group">}}
Again, this allows us to determine the correct values to enter in the group schema configuration:
- `Object Class`: **group** [1]
- `Name Attribute`: **name** [2]
- `Group Member Mapping Attribute`: **member** [3]
- `Search Attribute`: **sAMAccountName** [4]
Looking at the value of the **member** attribute, we can see that it contains the DN of the referenced user. This corresponds to the **distinguishedName** attribute in our user object. Accordingly will have to set the value of the `Group Member User Attribute` parameter to this attribute.
In the same way, we can observe that the value in the **memberOf** attribute in the user object corresponds to the **distinguishedName** [5] of the group. We therefore need to set the value for the `Group DN Attribute` parameter to this attribute.
## Annex: Troubleshooting
If you are experiencing issues while testing the connection to the Active Directory 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]({{<baseurl>}}/rancher/v2.6/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
content/rancher/v2.6/en/admin-settings/authentication/azure-ad/_index.md
+205
View File
@@ -0,0 +1,205 @@
---
title: Configuring Azure AD
weight: 1115
---
If you have an instance of Active Directory (AD) hosted in Azure, you can configure Rancher to allow your users to log in using their AD accounts. Configuration of Azure AD external authentication requires you to make configurations in both Azure and Rancher.
>**Note:** Azure AD integration only supports Service Provider initiated logins.
>**Prerequisite:** Have an instance of Azure AD configured.
>**Note:** Most of this procedure takes place from the [Microsoft Azure Portal](https://portal.azure.com/).
## Azure Active Directory Configuration Outline
Configuring Rancher to allow your users to authenticate with their Azure AD accounts involves multiple procedures. Review the outline below before getting started.
<a id="tip"></a>
>**Tip:** Before you start, we recommend creating an empty text file. You can use this file to copy values from Azure that you'll paste into Rancher later.
<!-- TOC -->
- [1. Register Rancher with Azure](#1-register-rancher-with-azure)
- [2. Create a new client secret](#2-create-a-new-client-secret)
- [3. Set Required Permissions for Rancher](#3-set-required-permissions-for-rancher)
- [4. Add a Reply URL](#4-add-a-reply-url)
- [5. Copy Azure Application Data](#5-copy-azure-application-data)
- [6. Configure Azure AD in Rancher](#6-configure-azure-ad-in-rancher)
<!-- /TOC -->
### 1. Register Rancher with Azure
Before enabling Azure AD within Rancher, you must register Rancher with Azure.
1. Log in to [Microsoft Azure](https://portal.azure.com/) as an administrative user. Configuration in future steps requires administrative access rights.
1. Use search to open the **App registrations** service.
![Open App Registrations]({{<baseurl>}}/img/rancher/search-app-registrations.png)
1. Click **New registrations** and complete the **Create** form.
![New App Registration]({{<baseurl>}}/img/rancher/new-app-registration.png)
1. Enter a **Name** (something like `Rancher`).
1. From **Supported account types**, select "Accounts in this organizational directory only (AzureADTest only - Single tenant)" This corresponds to the legacy app registration options.
1. In the **Redirect URI** section, make sure **Web** is selected from the dropdown and enter the URL of your Rancher Server in the text box next to the dropdown. This Rancher server URL should be appended with the verification path: `<MY_RANCHER_URL>/verify-auth-azure`.
>**Tip:** You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD).
1. Click **Register**.
>**Note:** It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.
### 2. Create a new client secret
From the Azure portal, create a client secret. Rancher will use this key to authenticate with Azure AD.
1. Use search to open **App registrations** services. Then open the entry for Rancher that you created in the last procedure.
![Open Rancher Registration]({{<baseurl>}}/img/rancher/open-rancher-app.png)
1. From the navigation pane on left, click **Certificates and Secrets**.
1. Click **New client secret**.
![Create new client secret]({{< baseurl >}}/img/rancher/select-client-secret.png)
1. Enter a **Description** (something like `Rancher`).
1. Select duration for the key from the options under **Expires**. This drop-down sets the expiration date for the key. Shorter durations are more secure, but require you to create a new key after expiration.
1. Click **Add** (you don't need to enter a value—it will automatically populate after you save).
<a id="secret"></a>
1. Copy the key value and save it to an [empty text file](#tip).
You'll enter this key into the Rancher UI later as your **Application Secret**.
You won't be able to access the key value again within the Azure UI.
### 3. Set Required Permissions for Rancher
Next, set API permissions for Rancher within Azure.
1. From the navigation pane on left, select **API permissions**.
![Open Required Permissions]({{<baseurl>}}/img/rancher/select-required-permissions.png)
1. Click **Add a permission**.
1. From the **Azure Active Directory Graph**, select the following **Delegated Permissions**:
![Select API Permissions]({{< baseurl >}}/img/rancher/select-required-permissions-2.png)
<br/>
<br/>
- **Access the directory as the signed-in user**
- **Read directory data**
- **Read all groups**
- **Read all users' full profiles**
- **Read all users' basic profiles**
- **Sign in and read user profile**
1. Click **Add permissions**.
1. From **API permissions**, click **Grant admin consent**. Then click **Yes**.
>**Note:** You must be signed in as an Azure administrator to successfully save your permission settings.
### 4. Add a Reply URL
To use Azure AD with Rancher you must whitelist Rancher with Azure. You can complete this whitelisting by providing Azure with a reply URL for Rancher, which is your Rancher Server URL followed with a verification path.
1. From the **Setting** blade, select **Reply URLs**.
![Azure: Enter Reply URL]({{<baseurl>}}/img/rancher/enter-azure-reply-url.png)
1. From the **Reply URLs** blade, enter the URL of your Rancher Server, appended with the verification path: `<MY_RANCHER_URL>/verify-auth-azure`.
>**Tip:** You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD).
1. Click **Save**.
**Result:** Your reply URL is saved.
>**Note:** It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.
### 5. Copy Azure Application Data
As your final step in Azure, copy the data that you'll use to configure Rancher for Azure AD authentication and paste it into an empty text file.
1. Obtain your Rancher **Tenant ID**.
1. Use search to open the **Azure Active Directory** service.
![Open Azure Active Directory]({{<baseurl>}}/img/rancher/search-azure-ad.png)
1. From the left navigation pane, open **Overview**.
2. Copy the **Directory ID** and paste it into your [text file](#tip).
You'll paste this value into Rancher as your **Tenant ID**.
1. Obtain your Rancher **Application ID**.
1. Use search to open **App registrations**.
![Open App Registrations]({{<baseurl>}}/img/rancher/search-app-registrations.png)
1. Find the entry you created for Rancher.
1. Copy the **Application ID** and paste it to your [text file](#tip).
1. Obtain your Rancher **Graph Endpoint**, **Token Endpoint**, and **Auth Endpoint**.
1. From **App registrations**, click **Endpoints**.
![Click Endpoints]({{<baseurl>}}/img/rancher/click-endpoints.png)
2. Copy the following endpoints to your clipboard and paste them into your [text file](#tip) (these values will be your Rancher endpoint values).
- **Microsoft Graph API endpoint** (Graph Endpoint)
- **OAuth 2.0 token endpoint (v1)** (Token Endpoint)
- **OAuth 2.0 authorization endpoint (v1)** (Auth Endpoint)
>**Note:** Copy the v1 version of the endpoints
### 6. Configure Azure AD in Rancher
From the Rancher UI, enter information about your AD instance hosted in Azure to complete configuration.
Enter the values that you copied to your [text file](#tip).
1. Log into Rancher.
1. In the top left corner, click **☰ > Users & Authentication**.
1. In the left navigation menu, click **Auth Provider**.
1. Click **AzureAD**.
1. Complete the **Configure Azure AD Account** form using the information you copied while completing [Copy Azure Application Data](#5-copy-azure-application-data).
>**Important:** When entering your Graph Endpoint, remove the tenant ID from the URL, like below.
>
><code>http<span>s://g</span>raph.windows.net/<del>abb5adde-bee8-4821-8b03-e63efdc7701c</del></code>
The following table maps the values you copied in the Azure portal to the fields in Rancher.
| Rancher Field | Azure Value |
| ------------------ | ------------------------------------- |
| Tenant ID | Directory ID |
| Application ID | Application ID |
| Application Secret | Key Value |
| Endpoint | https://login.microsoftonline.com/ |
| Graph Endpoint | Microsoft Azure AD Graph API Endpoint |
| Token Endpoint | OAuth 2.0 Token Endpoint |
| Auth Endpoint | OAuth 2.0 Authorization Endpoint |
1. Click **Enable**.
**Result:** Azure Active Directory authentication is configured.
content/rancher/v2.6/en/admin-settings/authentication/freeipa/_index.md
+51
View File
@@ -0,0 +1,51 @@
---
title: Configuring FreeIPA
weight: 1114
---
If your organization uses FreeIPA for user authentication, you can configure Rancher to allow your users to login using their FreeIPA credentials.
>**Prerequisites:**
>
>- You must have a [FreeIPA Server](https://www.freeipa.org/) configured.
>- Create a service account in FreeIPA with `read-only` access. Rancher uses this account to verify group membership when a user makes a request using an API key.
>- Read [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
1. Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_).
1. In the top left corner, click **☰ > Users & Authentication**.
1. In the left navigation menu, click **Auth Provider**.
1. Click **FreeIPA**.
1. Complete the **Configure an FreeIPA server** form.
You may need to log in to your domain controller to find the information requested in the form.
>**Using TLS?**
>If the certificate is self-signed or not from a recognized certificate authority, make sure you provide the complete chain. That chain is needed to verify the server's certificate.
<br/>
<br/>
>**User Search Base vs. Group Search Base**
>
>Search base allows Rancher to search for users and groups that are in your FreeIPA. These fields are only for search bases and not for search filters.
>
>* If your users and groups are in the same search base, complete only the User Search Base.
>* If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required.
1. If your FreeIPA deviates from the standard AD schema, complete the **Customize Schema** form to match it. Otherwise, skip this step.
>**Search Attribute** The Search Attribute field defaults with three specific values: `uid|sn|givenName`. After FreeIPA is configured, when a user enters text to add users or groups, Rancher automatically queries the FreeIPA server and attempts to match fields by user id, last name, or first name. Rancher specifically searches for users/groups that begin with the text entered in the search field.
>
>The default field value `uid|sn|givenName`, but you can configure this field to a subset of these fields. The pipe (`|`) between the fields separates these fields.
>
> * `uid`: User ID
> * `sn`: Last Name
> * `givenName`: First Name
>
> With this search attribute, Rancher creates search filters for users and groups, but you *cannot* add your own search filters in this field.
1. Enter your FreeIPA username and password in **Authenticate with FreeIPA** to confirm that Rancher is configured to use FreeIPA authentication.
1. Click **Enable**.
**Result:**
- FreeIPA authentication is configured.
- You are signed into Rancher with your FreeIPA account (i.e., the _external principal_).
content/rancher/v2.6/en/admin-settings/authentication/github/_index.md
+49
View File
@@ -0,0 +1,49 @@
---
title: Configuring GitHub
weight: 1116
---
In environments using GitHub, you can configure Rancher to allow sign on using GitHub credentials.
>**Prerequisites:** Read [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
1. Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_).
1. In the top left corner, click **☰ > Users & Authentication**.
1. In the left navigation menu, click **Auth Provider**.
1. Click **GitHub**.
1. Follow the directions displayed to set up a GitHub Application. Rancher redirects you to GitHub to complete registration.
>**What's an Authorization Callback URL?**
>
>The Authorization Callback URL is the URL where users go to begin using your application (i.e. the splash screen).
>When you use external authentication, authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authentication completes successfully, the Authorization Callback URL is the location where the user re-enters your application.
1. From GitHub, copy the **Client ID** and **Client Secret**. Paste them into Rancher.
>**Where do I find the Client ID and Client Secret?**
>
>From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently.
1. Click **Authenticate with GitHub**.
1. Use the **Site Access** options to configure the scope of user authorization.
- **Allow any valid Users**
_Any_ GitHub user can access Rancher. We generally discourage use of this setting!
- **Allow members of Clusters, Projects, plus Authorized Users and Organizations**
Any GitHub user or group added as a **Cluster Member** or **Project Member** can log in to Rancher. Additionally, any GitHub user or group you add to the **Authorized Users and Organizations** list may log in to Rancher.
- **Restrict access to only Authorized Users and Organizations**
Only GitHub users or groups added to the Authorized Users and Organizations can log in to Rancher.
<br/>
1. Click **Enable**.
**Result:**
- GitHub authentication is configured.
- You are signed into Rancher with your GitHub account (i.e., the _external principal_).
content/rancher/v2.6/en/admin-settings/authentication/google/_index.md
+112
View File
@@ -0,0 +1,112 @@
---
title: Configuring Google OAuth
weight: 10
---
If your organization uses G Suite for user authentication, you can configure Rancher to allow your users to log in using their G Suite credentials.
Only admins of the G Suite domain have access to the Admin SDK. Therefore, only G Suite admins can configure Google OAuth for Rancher.
Within Rancher, only administrators or users with the **Manage Authentication** [global role]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) can configure authentication.
# 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)
After the Admin SDK API is enabled, your G Suite domain's API screen should look like this:
![Enable Admin APIs]({{<baseurl>}}/img/rancher/Google-Enable-APIs-Screen.png)
# 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)
1. [Generate OAuth2 credentials for the Rancher server](#2-creating-oauth2-credentials-for-the-rancher-server)
1. [Create service account credentials for the Rancher server](#3-creating-service-account-credentials)
1. [Register the service account key as an OAuth Client](#4-register-the-service-account-key-as-an-oauth-client)
### 1. Adding Rancher as an Authorized Domain
1. Click [here](https://console.developers.google.com/apis/credentials) to go to credentials page of your Google domain.
1. Select your project and click **OAuth consent screen**.
![OAuth Consent Screen]({{<baseurl>}}/img/rancher/Google-OAuth-consent-screen-tab.png)
1. Go to **Authorized Domains** and enter the top private domain of your Rancher server URL in the list. The top private domain is the rightmost superdomain. So for example, www.foo.co.uk a top private domain of foo.co.uk. For more information on top-level domains, refer to [this article.](https://github.com/google/guava/wiki/InternetDomainNameExplained#public-suffixes-and-private-domains)
1. Go to **Scopes for Google APIs** and make sure **email,** **profile** and **openid** are enabled.
**Result:** Rancher has been added as an authorized domain for the Admin SDK API.
### 2. Creating OAuth2 Credentials for the Rancher Server
1. Go to the Google API console, select your project, and go to the [credentials page.](https://console.developers.google.com/apis/credentials)
![Credentials]({{<baseurl>}}/img/rancher/Google-Credentials-tab.png)
1. On the **Create Credentials** dropdown, select **OAuth client ID**.
1. Click **Web application**.
1. Provide a name.
1. Fill out the **Authorized JavaScript origins** and **Authorized redirect URIs**. Note: The Rancher UI page for setting up Google OAuth (available from the Global view under **Security > Authentication > Google**) provides you the exact links to enter for this step.
- Under **Authorized JavaScript origins,** enter your Rancher server URL.
- Under **Authorized redirect URIs,** enter your Rancher server URL appended with the path `verify-auth`. For example, if your URI is `https://rancherServer`, you will enter `https://rancherServer/verify-auth`.
1. Click on **Create**.
1. After the credential is created, you will see a screen with a list of your credentials. Choose the credential you just created, and in that row on rightmost side, click **Download JSON**. Save the file so that you can provide these credentials to Rancher.
**Result:** Your OAuth credentials have been successfully created.
### 3. Creating Service Account Credentials
Since the Google Admin SDK is available only to admins, regular users cannot use it to retrieve profiles of other users or their groups. Regular users cannot even retrieve their own groups.
Since Rancher provides group-based membership access, we require the users to be able to get their own groups, and look up other users and groups when needed.
As a workaround to get this capability, G Suite recommends creating a service account and delegating authority of your G Suite domain to that service account.
This section describes how to:
- Create a service account
- Create a key for the service account and download the credentials as JSON
1. Click [here](https://console.developers.google.com/iam-admin/serviceaccounts) and select your project for which you generated OAuth credentials.
1. Click on **Create Service Account**.
1. Enter a name and click **Create**.
![Service account creation Step 1]({{<baseurl>}}/img/rancher/Google-svc-acc-step1.png)
1. Don't provide any roles on the **Service account permissions** page and click **Continue**
![Service account creation Step 2]({{<baseurl>}}/img/rancher/Google-svc-acc-step2.png)
1. Click on **Create Key** and select the JSON option. Download the JSON file and save it so that you can provide it as the service account credentials to Rancher.
![Service account creation Step 3]({{<baseurl>}}/img/rancher/Google-svc-acc-step3-key-creation.png)
**Result:** Your service account is created.
### 4. Register the Service Account Key as an OAuth Client
You will need to grant some permissions to the service account you created in the last step. Rancher requires you to grant only read-only permissions for users and groups.
Using the Unique ID of the service account key, register it as an Oauth Client using the following steps:
1. Get the Unique ID of the key you just created. If it's not displayed in the list of keys right next to the one you created, you will have to enable it. To enable it, click **Unique ID** and click **OK**. This will add a **Unique ID** column to the list of service account keys. Save the one listed for the service account you created. NOTE: This is a numeric key, not to be confused with the alphanumeric field **Key ID**.
![Service account Unique ID]({{<baseurl>}}/img/rancher/Google-Select-UniqueID-column.png)
1. Go to the [**Manage OAuth Client Access** page.](https://admin.google.com/AdminHome?chromeless=1#OGX:ManageOauthClients)
1. Add the Unique ID obtained in the previous step in the **Client Name** field.
1. In the **One or More API Scopes** field, add the following scopes:
```
openid,profile,email,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly
```
1. Click **Authorize**.
**Result:** The service account is registered as an OAuth client in your G Suite account.
# Configuring Google OAuth in Rancher
1. Sign into Rancher using a local user assigned the [administrator]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions) role. This user is also called the local principal.
1. In the top left corner, click **☰ > Users & Authentication**.
1. In the left navigation menu, click **Auth Provider**.
1. Click **Google**. The instructions in the UI cover the steps to set up authentication with Google OAuth.
1. Admin Email: Provide the email of an administrator account from your GSuite setup. In order to perform user and group lookups, google apis require an administrator's email in conjunction with the service account key.
1. Domain: Provide the domain on which you have configured GSuite. Provide the exact domain and not any aliases.
1. Nested Group Membership: Check this box to enable nested group memberships. Rancher admins can disable this at any time after configuring auth.
- **Step One** is about adding Rancher as an authorized domain, which we already covered in [this section.](#1-adding-rancher-as-an-authorized-domain)
- For **Step Two,** provide the OAuth credentials JSON that you downloaded after completing [this section.](#2-creating-oauth2-credentials-for-the-rancher-server) You can upload the file or paste the contents into the **OAuth Credentials** field.
- For **Step Three,** provide the service account credentials JSON that downloaded at the end of [this section.](#3-creating-service-account-credentials) The credentials will only work if you successfully [registered the service account key](#4-register-the-service-account-key-as-an-oauth-client) as an OAuth client in your G Suite account.
1. Click **Authenticate with Google**.
1. Click **Enable**.
**Result:** Google authentication is successfully configured.
content/rancher/v2.6/en/admin-settings/authentication/keycloak-oidc/_index.md
+137
View File
@@ -0,0 +1,137 @@
---
title: Configuring Keycloak (OIDC)
description: Create a Keycloak OpenID Connect (OIDC) client and configure Rancher to work with Keycloak. By the end your users will be able to sign into Rancher using their Keycloak logins
weight: 1200
---
If your organization uses [Keycloak Identity Provider (IdP)](https://www.keycloak.org) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials. Rancher supports integration with Keycloak using the OpenID Connect (OIDC) protocol and the SAML protocol. Both implementations are functionally equivalent when used with Rancher. This page describes the process to configure Rancher to work with Keycloak using the OIDC protocol.
If you prefer to use Keycloak with the SAML protocol instead, refer to [this page]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/keycloak-saml/).
If you have an existing configuration using the SAML protocol and want to switch to the OIDC protocol, refer to [this section](#migrating-from-saml-to-oidc).
## Prerequisites
- On Rancher, Keycloak (SAML) is disabled.
- You must have a [Keycloak IdP Server](https://www.keycloak.org/docs/latest/server_installation/) configured.
- In Keycloak, create a [new OIDC client](https://www.keycloak.org/docs/latest/server_admin/#oidc-clients), with the settings below. See the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#oidc-clients) for help.
Setting | Value
------------|------------
`Client ID` | &lt;CLIENT_ID> (e.g. `rancher`)
`Name` | &lt;CLIENT_NAME> (e.g. `rancher`)
`Client Protocol` | `openid-connect`
`Access Type` | `confidential`
`Valid Redirect URI` | `https://yourRancherHostURL/verify-auth`
- In the new OIDC client, create [Mappers](https://www.keycloak.org/docs/latest/server_admin/#_protocol-mappers) to expose the users fields.
- Create a new "Groups Mapper" with the settings below.
Setting | Value
------------|------------
`Name` | `Groups Mapper`
`Mapper Type` | `Group Membership`
`Token Claim Name` | `groups`
`Add to ID token` | `OFF`
`Add to access token` | `OFF`
`Add to user info` | `ON`
- Create a new "Client Audience" with the settings below.
Setting | Value
------------|------------
`Name` | `Client Audience`
`Mapper Type` | `Audience`
`Included Client Audience` | &lt;CLIENT_NAME>
`Add to access token` | `ON`
- Create a new "Groups Path" with the settings below.
Setting | Value
------------|------------
`Name` | `Group Path`
`Mapper Type` | `Group Membership`
`Token Claim Name` | `full_group_path`
`Full group path` | `ON`
`Add to user info` | `ON`
## Configuring Keycloak in Rancher
1. In the Rancher UI, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Auth Provider**.
1. Select **Keycloak (OIDC)**.
1. Complete the **Configure a Keycloak OIDC account** form. For help with filling the form, see the [configuration reference](#configuration-reference).
1. After you complete the **Configure a Keycloak OIDC account** form, click **Enable**.
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration.
>**Note:** You may need to disable your popup blocker to see the IdP login page.
**Result:** Rancher is configured to work with Keycloak using the OIDC protocol. Your users can now sign into Rancher using their Keycloak logins.
## Configuration Reference
| Field | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client ID | The `Client ID` of your Keycloak client. |
| Client Secret | The generated `Secret` of your Keycloak client. In the Keycloak console, select **Clients**, select the client you created, select the **Credentials** tab and copy the value of the `Secret` field. |
| Private Key / Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP. Required if HTTPS/SSL is enabled on your Keycloak server. |
| Endpoints | Choose whether to use the generated values for the `Rancher URL`, `Issue`, and `Auth Endpoint` fields or to provide manual overrides if incorrect. |
| Keycloak URL | The URL for your Keycloak server. |
| Keycloak Realm | The name of the realm in which the Keycloak client was created in. |
| Rancher URL | The URL for your Rancher Server. |
| Issuer | The URL of your IdP. |
| Auth Endpoint | The URL where users are redirected to authenticate. |
## Migrating from SAML to OIDC
This section describes the process to transition from using Rancher with Keycloak (SAML) to Keycloak (OIDC).
### Reconfigure Keycloak
1. Change the existing client to use the OIDC protocol. In the Keycloak console, select **Clients**, select the SAML client to migrate, select the **Settings** tab, change `Client Protocol` from `saml` to `openid-connect`, and click **Save**
1. Verify the `Valid Redirect URIs` are still valid.
1. Select the **Mappers** tab and create a new Mapper with the settings below.
Setting | Value
------------|------------
`Name` | `Groups Mapper`
`Mapper Type` | `Group Membership`
`Token Claim Name` | `groups`
`Add to ID token` | `ON`
`Add to access token` | `ON`
`Add to user info` | `ON`
### Reconfigure Rancher
Before configuring Rancher to use Keycloak (OIDC), Keycloak (SAML) must be first disabled.
1. In the Rancher UI, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Auth Provider**.
1. Select **Keycloak (SAML)**.
1. Click **Disable**.
Configure Rancher to use Keycloak (OIDC) by following the steps in [this section](#configuring-keycloak-in-rancher).
> **Note:** After configuration is completed, Rancher user permissions will need to be reapplied as they are not automatically migrated.
## Annex: Troubleshooting
If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration options of your OIDC client. You may also inspect the Rancher logs to help pinpoint what's causing issues. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{<baseurl>}}/rancher/v2.6/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
All Keycloak related log entries will be prepended with either `[generic oidc]` or `[keycloak oidc]`.
### You are not redirected to Keycloak
When you fill the **Configure a Keycloak OIDC account** form and click on **Enable**, you are not redirected to your IdP.
* Verify your Keycloak client configuration.
### The generated `Issuer` and `Auth Endpoint` are incorrect
* On the **Configure a Keycloak OIDC account** form, change **Endpoints** to `Specify (advanced)` and override the `Issuer` and `Auth Endpoint` values. To find the values, go to the Keycloak console and select **Realm Settings**, select the **General** tab, and click **OpenID Endpoint Configuration**. The JSON output will display values for `issuer` and `authorization_endpoint`.
### Keycloak Error: "Invalid grant_type"
* In some cases, this error message may be misleading and is actually caused by setting the `Valid Redirect URI` incorrectly.
content/rancher/v2.6/en/admin-settings/authentication/keycloak-saml/_index.md
+123
View File
@@ -0,0 +1,123 @@
---
title: Configuring Keycloak (SAML)
description: Create a Keycloak SAML client and configure Rancher to work with Keycloak. By the end your users will be able to sign into Rancher using their Keycloak logins
weight: 1200
---
If your organization uses Keycloak Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
## Prerequisites
- You must have a [Keycloak IdP Server](https://www.keycloak.org/docs/latest/server_installation/) configured.
- In Keycloak, create a [new SAML client](https://www.keycloak.org/docs/latest/server_admin/#saml-clients), with the settings below. See the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#saml-clients) for help.
Setting | Value
------------|------------
`Sign Documents` | `ON` <sup>1</sup>
`Sign Assertions` | `ON` <sup>1</sup>
All other `ON/OFF` Settings | `OFF`
`Client ID` | Either `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata` or the value configured in the `Entry ID Field` of the Rancher Keycloak configuration<sup>2</sup>
`Client Name` | <CLIENT_NAME> (e.g. `rancher`)
`Client Protocol` | `SAML`
`Valid Redirect URI` | `https://yourRancherHostURL/v1-saml/keycloak/saml/acs`
><sup>1</sup>: Optionally, you can enable either one or both of these settings.
><sup>2</sup>: Rancher SAML metadata won't be generated until a SAML provider is configured and saved.
{{< img "/img/rancher/keycloak/keycloak-saml-client-configuration.png" "">}}
- In the new SAML client, create Mappers to expose the users fields
- Add all "Builtin Protocol Mappers"
{{< img "/img/rancher/keycloak/keycloak-saml-client-builtin-mappers.png" "">}}
- Create a new "Group list" mapper to map the member attribute to a user's groups
{{< img "/img/rancher/keycloak/keycloak-saml-client-group-mapper.png" "">}}
- Export a `metadata.xml` file from your Keycloak client:
From the `Installation` tab, choose the `SAML Metadata IDPSSODescriptor` format option and download your file.
>**Note**
> Keycloak versions 6.0.0 and up no longer provide the IDP metadata under the `Installation` tab.
> You can still get the XML from the following url:
>
> `https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}/protocol/saml/descriptor`
>
> The XML obtained from this URL contains `EntitiesDescriptor` as the root element. Rancher expects the root element to be `EntityDescriptor` rather than `EntitiesDescriptor`. So before passing this XML to Rancher, follow these steps to adjust it:
>
> * Copy all the attributes from `EntitiesDescriptor` to the `EntityDescriptor` that are not present.
> * Remove the `<EntitiesDescriptor>` tag from the beginning.
> * Remove the `</EntitiesDescriptor>` from the end of the xml.
>
> You are left with something similar as the example below:
>
> ```
> <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" entityID="https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}">
> ....
> </EntityDescriptor>
> ```
## Configuring Keycloak in Rancher
1. In the top left corner, click **☰ > Users & Authentication**.
1. In the left navigation menu, click **Auth Provider**.
1. Click **Keycloak SAML**.
1. Complete the **Configure Keycloak Account** form. For help with filling the form, see the [configuration reference](#configuration-reference).
1. After you complete the **Configure a Keycloak Account** form, click **Enable**.
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration.
>**Note:** You may have to disable your popup blocker to see the IdP login page.
**Result:** Rancher is configured to work with Keycloak. Your users can now sign into Rancher using their Keycloak logins.
{{< saml_caveats >}}
## Configuration Reference
| Field | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Display Name Field | The attribute that contains the display name of users. <br/><br/>Example: `givenName` |
| User Name Field | The attribute that contains the user name/given name. <br/><br/>Example: `email` |
| UID Field | An attribute that is unique to every user. <br/><br/>Example: `email` |
| Groups Field | Make entries for managing group memberships. <br/><br/>Example: `member` |
| Entity ID Field | The ID that needs to be configured as a client ID in the Keycloak client. <br/><br/>Default: `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata` |
| Rancher API Host | The URL for your Rancher Server. |
| Private Key / Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP. |
| IDP-metadata | The `metadata.xml` file that you exported from your IdP server. |
>**Tip:** You can generate a key/certificate pair using an openssl command. For example:
>
> openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert
## Annex: Troubleshooting
If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration option of your SAML client. 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]({{<baseurl>}}/rancher/v2.6/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
### You are not redirected to Keycloak
When you click on **Authenticate with Keycloak**, you are not redirected to your IdP.
* Verify your Keycloak client configuration.
* Make sure `Force Post Binding` set to `OFF`.
### Forbidden message displayed after IdP login
You are correctly redirected to your IdP login page and you are able to enter your credentials, however you get a `Forbidden` message afterwards.
* Check the Rancher debug log.
* If the log displays `ERROR: either the Response or Assertion must be signed`, make sure either `Sign Documents` or `Sign assertions` is set to `ON` in your Keycloak client.
### HTTP 502 when trying to access /v1-saml/keycloak/saml/metadata
This is usually due to the metadata not being created until a SAML provider is configured.
Try configuring and saving keycloak as your SAML provider and then accessing the metadata.
### Keycloak Error: "We're sorry, failed to process response"
* Check your Keycloak log.
* If the log displays `failed: org.keycloak.common.VerificationException: Client does not have a public key`, set `Encrypt Assertions` to `OFF` in your Keycloak client.
### Keycloak Error: "We're sorry, invalid requester"
* Check your Keycloak log.
* If the log displays `request validation failed: org.keycloak.common.VerificationException: SigAlg was null`, set `Client Signature Required` to `OFF` in your Keycloak client.
content/rancher/v2.6/en/admin-settings/authentication/local/_index.md
+16
View File
@@ -0,0 +1,16 @@
---
title: Local Authentication
weight: 1111
---
Local authentication is the default until you configure an external authentication provider. Local authentication is where Rancher stores the user information, i.e. names and passwords, of who can log in to Rancher. By default, the `admin` user that logs in to Rancher for the first time is a local user.
## Adding Local Users
Regardless of whether you use external authentication, you should create a few local authentication users so that you can continue using Rancher if your external authentication service encounters issues.
1. In the top left corner, click **☰ > Users & Authentication**.
1. In the left navigation menu, click **Users**.
1. Click **Create**.
1. Complete the **Add User** form.
1. Click **Create**.
content/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/_index.md
+30
View File
@@ -0,0 +1,30 @@
---
title: Configuring Microsoft Active Directory Federation Service (SAML)
weight: 1205
---
If your organization uses Microsoft Active Directory Federation Services (AD FS) for user authentication, you can configure Rancher to allow your users to log in using their AD FS credentials.
## Prerequisites
You must have Rancher installed.
- Obtain your Rancher Server URL. During AD FS configuration, substitute this URL for the `<RANCHER_SERVER>` placeholder.
- You must have a global administrator account on your Rancher installation.
You must have a [Microsoft AD FS Server](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) configured.
- Obtain your AD FS Server IP/DNS name. During AD FS configuration, substitute this IP/DNS name for the `<AD_SERVER>` placeholder.
- You must have access to add [Relying Party Trusts](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) on your AD FS Server.
## Setup Outline
Setting up Microsoft AD FS with Rancher Server requires configuring AD FS on your Active Directory server, and configuring Rancher to utilize your AD FS server. The following pages serve as guides for setting up Microsoft AD FS authentication on your Rancher installation.
- [1. Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
- [2. Configuring Rancher for Microsoft AD FS]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup)
{{< saml_caveats >}}
### [Next: Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
content/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup/_index.md
+82
View File
@@ -0,0 +1,82 @@
---
title: 1. Configuring Microsoft AD FS for Rancher
weight: 1205
---
Before configuring Rancher to support AD FS users, you must add Rancher as a [relying party trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/technical-reference/understanding-key-ad-fs-concepts) in AD FS.
1. Log into your AD server as an administrative user.
1. Open the **AD FS Management** console. Select **Add Relying Party Trust..**. from the **Actions** menu and click **Start**.
{{< img "/img/rancher/adfs/adfs-overview.png" "">}}
1. Select **Enter data about the relying party manually** as the option for obtaining data about the relying party.
{{< img "/img/rancher/adfs/adfs-add-rpt-2.png" "">}}
1. Enter your desired **Display name** for your Relying Party Trust. For example, `Rancher`.
{{< img "/img/rancher/adfs/adfs-add-rpt-3.png" "">}}
1. Select **AD FS profile** as the configuration profile for your relying party trust.
{{< img "/img/rancher/adfs/adfs-add-rpt-4.png" "">}}
1. Leave the **optional token encryption certificate** empty, as Rancher AD FS will not be using one.
{{< img "/img/rancher/adfs/adfs-add-rpt-5.png" "">}}
1. Select **Enable support for the SAML 2.0 WebSSO protocol**
and enter `https://<rancher-server>/v1-saml/adfs/saml/acs` for the service URL.
{{< img "/img/rancher/adfs/adfs-add-rpt-6.png" "">}}
1. Add `https://<rancher-server>/v1-saml/adfs/saml/metadata` as the **Relying party trust identifier**.
{{< img "/img/rancher/adfs/adfs-add-rpt-7.png" "">}}
1. This tutorial will not cover multi-factor authentication; please refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/configure-additional-authentication-methods-for-ad-fs) if you would like to configure multi-factor authentication.
{{< img "/img/rancher/adfs/adfs-add-rpt-8.png" "">}}
1. From **Choose Issuance Authorization RUles**, you may select either of the options available according to use case. However, for the purposes of this guide, select **Permit all users to access this relying party**.
{{< img "/img/rancher/adfs/adfs-add-rpt-9.png" "">}}
1. After reviewing your settings, select **Next** to add the relying party trust.
{{< img "/img/rancher/adfs/adfs-add-rpt-10.png" "">}}
1. Select **Open the Edit Claim Rules..**. and click **Close**.
{{< img "/img/rancher/adfs/adfs-add-rpt-11.png" "">}}
1. On the **Issuance Transform Rules** tab, click **Add Rule..**..
{{< img "/img/rancher/adfs/adfs-edit-cr.png" "">}}
1. Select **Send LDAP Attributes as Claims** as the **Claim rule template**.
{{< img "/img/rancher/adfs/adfs-add-tcr-1.png" "">}}
1. Set the **Claim rule name** to your desired name (for example, `Rancher Attributes`) and select **Active Directory** as the **Attribute store**. Create the following mapping to reflect the table below:
| LDAP Attribute | Outgoing Claim Type |
| -------------------------------------------- | ------------------- |
| Given-Name | Given Name |
| User-Principal-Name | UPN |
| Token-Groups - Qualified by Long Domain Name | Group |
| SAM-Account-Name | Name |
<br/>
{{< img "/img/rancher/adfs/adfs-add-tcr-2.png" "">}}
1. Download the `federationmetadata.xml` from your AD server at:
```
https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml
```
**Result:** You've added Rancher as a relying trust party. Now you can configure Rancher to leverage AD.
### [Next: Configuring Rancher for Microsoft AD FS]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/)
content/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup/_index.md
+45
View File
@@ -0,0 +1,45 @@
---
title: 2. Configuring Rancher for Microsoft AD FS
weight: 1205
---
After you complete [Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup/), enter your AD FS information into Rancher to allow AD FS users to authenticate with Rancher.
>**Important Notes For Configuring Your ADFS Server:**
>
>- The SAML 2.0 WebSSO Protocol Service URL is: `https://<RANCHER_SERVER>/v1-saml/adfs/saml/acs`
>- The Relying Party Trust identifier URL is: `https://<RANCHER_SERVER>/v1-saml/adfs/saml/metadata`
>- You must export the `federationmetadata.xml` file from your AD FS server. This can be found at: `https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml`
1. In the top left corner, click **☰ > Users & Authentication**.
1. In the left navigation menu, click **Auth Provider**.
1. Click **ADFS**.
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 **Enable**.
Rancher redirects you to the AD FS login page. Enter credentials that authenticate with Microsoft AD FS to validate your Rancher AD FS configuration.
>**Note:** You may have to disable your popup blocker to see the AD FS login page.
**Result:** Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins.
# Configuration
| Field | Description |
|---------------------------|-----------------|
| Display Name Field | The AD attribute that contains the display name of users. <br/><br/>Example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` |
| User Name Field | The AD attribute that contains the user name/given name. <br/><br/>Example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` |
| UID Field | An AD attribute that is unique to every user. <br/><br/>Example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn` |
| Groups Field | Make entries for managing group memberships. <br/><br/>Example: `http://schemas.xmlsoap.org/claims/Group` |
| Rancher API Host | The URL for your Rancher Server. |
| Private Key / Certificate | This is a key-certificate pair to create a secure shell between Rancher and your AD FS. Ensure you set the Common Name (CN) to your Rancher Server URL.<br/><br/>[Certificate creation command](#cert-command) |
| Metadata XML | The `federationmetadata.xml` file exported from your AD FS server. <br/><br/>You can find this file at `https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml`. |
<a id="cert-command"></a>
**Tip:** You can generate a certificate using an openssl command. For example:
```
openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
```
content/rancher/v2.6/en/admin-settings/authentication/okta/_index.md
+50
View File
@@ -0,0 +1,50 @@
---
title: Configuring Okta (SAML)
weight: 1210
---
If your organization uses Okta Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
>**Note:** Okta integration only supports Service Provider initiated logins.
## Prerequisites
In Okta, create a SAML Application with the settings below. See the [Okta documentation](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta) for help.
Setting | Value
------------|------------
`Single Sign on URL` | `https://yourRancherHostURL/v1-saml/okta/saml/acs`
`Audience URI (SP Entity ID)` | `https://yourRancherHostURL/v1-saml/okta/saml/metadata`
## Configuring Okta in Rancher
1. In the top left corner, click **☰ > Users & Authentication**.
1. In the left navigation menu, click **Auth Provider**.
1. Click **Okta**.
1. Complete the **Configure Okta Account** form. The examples below describe how you can map Okta attributes from attribute statements to fields within Rancher.
| Field | Description |
| ------------------------- | ----------------------------------------------------------------------------- |
| Display Name Field | The attribute name from an attribute statement that contains the display name of users. |
| User Name Field | The attribute name from an attribute statement that contains the user name/given name. |
| UID Field | The attribute name from an attribute statement that is unique to every user. |
| Groups Field | The attribute name in a group attribute statement that exposes your groups. |
| Rancher API Host | The URL for your Rancher Server. |
| Private Key / Certificate | A key/certificate pair used for Assertion Encryption. |
| Metadata XML | The `Identity Provider metadata` file that you find in the application `Sign On` section. |
>**Tip:** You can generate a key/certificate pair using an openssl command. For example:
>
> openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.crt
1. After you complete the **Configure Okta Account** form, click **Enable**.
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Okta IdP to validate your Rancher Okta configuration.
>**Note:** If nothing seems to happen, it's likely because your browser blocked the pop-up. Make sure you disable the pop-up blocker for your rancher domain and whitelist it in any other extensions you might utilize.
**Result:** Rancher is configured to work with Okta. Your users can now sign into Rancher using their Okta logins.
{{< saml_caveats >}}
content/rancher/v2.6/en/admin-settings/authentication/openldap/_index.md
+49
View File
@@ -0,0 +1,49 @@
---
title: Configuring OpenLDAP
weight: 1113
---
If your organization uses LDAP for user authentication, you can configure Rancher to communicate with an OpenLDAP server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the organisation's central user repository, while allowing end-users to authenticate with their LDAP credentials when logging in to the Rancher UI.
## Prerequisites
Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).
> **Using TLS?**
>
> If the certificate used by the OpenLDAP server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
## Configure OpenLDAP in Rancher
Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the [configuration reference.](./openldap-config)
> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
1. In the top left corner, click **☰ > Users & Authentication**.
1. In the left navigation menu, click **Auth Provider**.
1. Click **OpenLDAP**. Fill out the **Configure an OpenLDAP server** form.
1. Click **Enable**.
### Test Authentication
Once you have completed the configuration, proceed by testing the connection to the OpenLDAP server. Authentication with OpenLDAP will be enabled implicitly if the test is successful.
> **Note:**
>
> The OpenLDAP user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which LDAP account you use to perform this step.
1. Enter the **username** and **password** for the OpenLDAP account that should be mapped to the local principal account.
2. Click **Authenticate With OpenLDAP** to test the OpenLDAP connection and finalise the setup.
**Result:**
- OpenLDAP authentication is configured.
- The LDAP user pertaining to the entered credentials is mapped to the local principal (administrative) account.
> **Note:**
>
> You will still be able to login using the locally configured `admin` account and password in case of a disruption of LDAP services.
## Annex: 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]({{<baseurl>}}/rancher/v2.6/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
content/rancher/v2.6/en/admin-settings/authentication/openldap/openldap-config/_index.md
+86
View File
@@ -0,0 +1,86 @@
---
title: OpenLDAP Configuration Reference
weight: 2
---
This section is intended to be used as a reference when setting up an OpenLDAP authentication provider in Rancher.
For further details on configuring OpenLDAP, refer to the [official documentation.](https://www.openldap.org/doc/)
> Before you proceed with the configuration, please familiarize yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
- [Background: OpenLDAP Authentication Flow](#background-openldap-authentication-flow)
- [OpenLDAP server configuration](#openldap-server-configuration)
- [User/group schema configuration](#user-group-schema-configuration)
- [User schema configuration](#user-schema-configuration)
- [Group schema configuration](#group-schema-configuration)
## Background: OpenLDAP Authentication Flow
1. When a user attempts to login with LDAP credentials, Rancher creates an initial bind to the LDAP server using a service account with permissions to search the directory and read user/group attributes.
2. Rancher then searches the directory for the user by using a search filter based on the provided username and configured attribute mappings.
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
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.
> **Using TLS?**
>
> If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation.
<figcaption>OpenLDAP Server Parameters</figcaption>
| Parameter | Description |
|:--|:--|
| Hostname | Specify the hostname or IP address of the OpenLDAP server |
| Port | Specify the port at which the OpenLDAP server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.|
| TLS | Check this box to enable LDAP over SSL/TLS (commonly known as LDAPS). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate. |
| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the server unreachable. |
| Service Account Distinguished Name | Enter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries. |
| Service Account Password | The password for the service account. |
| 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
If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the **Customize Schema** section to match it.
Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP.
If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation.
### User Schema Configuration
The table below details the parameters for the user schema configuration.
<figcaption>User Schema Configuration Parameters</figcaption>
| Parameter | Description |
|:--|:--|
| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
| Username Attribute | The user attribute whose value is suitable as a display name. |
| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. This is typically `uid`. |
| User Member Attribute | The user attribute containing the Distinguished Name of groups a user is member of. Usually this is one of `memberOf` or `isMemberOf`. |
| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the LDAP server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. |
| User Enabled Attribute | If the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty. |
| Disabled Status Bitmask | This is the value for a disabled/locked user account. The parameter is ignored if `User Enabled Attribute` is empty. |
### Group Schema Configuration
The table below details the parameters for the group schema configuration.
<figcaption>Group Schema Configuration Parameters<figcaption>
| Parameter | Description |
|:--|:--|
| Object Class | The name of the object class used for group entries in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
| Name Attribute | The group attribute whose value is suitable for a display name. |
| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. |
| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. |
| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema `Search Attribute`. |
| Group DN Attribute | The name of the group attribute whose format matches the values in the user's group membership attribute. See `User Member Attribute`. |
| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (ie. you have groups that contain other groups as members). This option is disabled if you are using Shibboleth. |
content/rancher/v2.6/en/admin-settings/authentication/ping-federate/_index.md
+50
View File
@@ -0,0 +1,50 @@
---
title: Configuring PingIdentity (SAML)
weight: 1200
---
If your organization uses Ping Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
>**Prerequisites:**
>
>- You must have a [Ping IdP Server](https://www.pingidentity.com/) configured.
>- Following are the Rancher Service Provider URLs needed for configuration:
Metadata URL: `https://<rancher-server>/v1-saml/ping/saml/metadata`
Assertion Consumer Service (ACS) URL: `https://<rancher-server>/v1-saml/ping/saml/acs`
Note that these URLs will not return valid data until the authentication configuration is saved in Rancher.
>- Export a `metadata.xml` file from your IdP Server. For more information, see the [PingIdentity documentation](https://documentation.pingidentity.com/pingfederate/pf83/index.shtml#concept_exportingMetadata.html).
1. In the top left corner, click **☰ > Users & Authentication**.
1. In the left navigation menu, click **Auth Provider**.
1. Click **Ping Identity**.
1. Complete the **Configure a Ping Account** form. Ping IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.
1. **Display Name Field**: Enter the AD attribute that contains the display name of users (example: `displayName`).
1. **User Name Field**: Enter the AD attribute that contains the user name/given name (example: `givenName`).
1. **UID Field**: Enter an AD attribute that is unique to every user (example: `sAMAccountName`, `distinguishedName`).
1. **Groups Field**: Make entries for managing group memberships (example: `memberOf`).
1. **Rancher API Host**: Enter the URL for your Rancher Server.
1. **Private Key** and **Certificate**: This is a key-certificate pair to create a secure shell between Rancher and your IdP.
You can generate one using an openssl command. For example:
```
openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
```
1. **IDP-metadata**: The `metadata.xml` file that you [exported from your IdP server](https://documentation.pingidentity.com/pingfederate/pf83/index.shtml#concept_exportingMetadata.html).
1. After you complete the **Configure Ping Account** form, click **Enable**.
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Ping IdP to validate your Rancher PingIdentity configuration.
>**Note:** You may have to disable your popup blocker to see the IdP login page.
**Result:** Rancher is configured to work with PingIdentity. Your users can now sign into Rancher using their PingIdentity logins.
{{< saml_caveats >}}
content/rancher/v2.6/en/admin-settings/authentication/shibboleth/_index.md
+108
View File
@@ -0,0 +1,108 @@
---
title: Configuring Shibboleth (SAML)
weight: 1210
---
If your organization uses Shibboleth Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in to Rancher using their Shibboleth credentials.
In this configuration, when Rancher users log in, they will be redirected to the Shibboleth IdP to enter their credentials. After authentication, they will be redirected back to the Rancher UI.
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 the authenticated user will be able to access resources in Rancher that their groups have permissions for.
> 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.](./about)
This section covers the following topics:
- [Setting up Shibboleth in Rancher](#setting-up-shibboleth-in-rancher)
- [Shibboleth Prerequisites](#shibboleth-prerequisites)
- [Configure Shibboleth in Rancher](#configure-shibboleth-in-rancher)
- [SAML Provider Caveats](#saml-provider-caveats)
- [Setting up OpenLDAP in Rancher](#setting-up-openldap-in-rancher)
- [OpenLDAP Prerequisites](#openldap-prerequisites)
- [Configure OpenLDAP in Rancher](#configure-openldap-in-rancher)
- [Troubleshooting](#troubleshooting)
# Setting up Shibboleth in Rancher
### Shibboleth Prerequisites
>
>- You must have a Shibboleth IdP Server configured.
>- Following are the Rancher Service Provider URLs needed for configuration:
Metadata URL: `https://<rancher-server>/v1-saml/shibboleth/saml/metadata`
Assertion Consumer Service (ACS) URL: `https://<rancher-server>/v1-saml/shibboleth/saml/acs`
>- Export a `metadata.xml` file from your IdP Server. For more information, see the [Shibboleth documentation.](https://wiki.shibboleth.net/confluence/display/SP3/Home)
### Configure Shibboleth in Rancher
If your organization uses Shibboleth for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
1. In the top left corner, click **☰ > Users & Authentication**.
1. In the left navigation menu, click **Auth Provider**.
1. Click **Shibboleth**.
1. Complete the **Configure Shibboleth Account** form. Shibboleth IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.
1. **Display Name Field**: Enter the AD attribute that contains the display name of users (example: `displayName`).
1. **User Name Field**: Enter the AD attribute that contains the user name/given name (example: `givenName`).
1. **UID Field**: Enter an AD attribute that is unique to every user (example: `sAMAccountName`, `distinguishedName`).
1. **Groups Field**: Make entries for managing group memberships (example: `memberOf`).
1. **Rancher API Host**: Enter the URL for your Rancher Server.
1. **Private Key** and **Certificate**: This is a key-certificate pair to create a secure shell between Rancher and your IdP.
You can generate one using an openssl command. For example:
```
openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
```
1. **IDP-metadata**: The `metadata.xml` file that you exported from your IdP server.
1. After you complete the **Configure Shibboleth Account** form, click **Enable**.
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Shibboleth IdP to validate your Rancher Shibboleth configuration.
>**Note:** You may have to disable your popup blocker to see the IdP login page.
**Result:** Rancher is configured to work with Shibboleth. Your users can now sign into Rancher using their Shibboleth logins.
### SAML Provider Caveats
If you configure Shibboleth without OpenLDAP, the following caveats apply due to the fact that SAML Protocol does not support search or lookup for users or groups.
- There is no validation on users or groups when assigning permissions to them in Rancher.
- When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
- The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.
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
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.
### OpenLDAP Prerequisites
Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).
> **Using TLS?**
>
> If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
### Configure OpenLDAP in Rancher
Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the [configuration reference.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/openldap/openldap-config) Note that nested group membership is not available for Shibboleth.
> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/#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 left navigation menu, click **Auth Provider**.
1. Click **OpenLDAP**. The **Configure an OpenLDAP server** form will be displayed.
# 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]({{<baseurl>}}/rancher/v2.6/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
content/rancher/v2.6/en/admin-settings/authentication/shibboleth/about/_index.md
+32
View File
@@ -0,0 +1,32 @@
---
title: Group Permissions with Shibboleth and OpenLDAP
weight: 1
---
This page provides background information and context for Rancher users who intend to set up the Shibboleth authentication provider in Rancher.
Because Shibboleth is a SAML provider, it does not support searching for groups. While a Shibboleth integration can validate user credentials, it can't be used to assign permissions to groups in Rancher without additional configuration.
One solution to this problem is to configure an OpenLDAP identity provider. With an OpenLDAP back end for Shibboleth, you will be able to search for groups in Rancher and assign them to resources such as clusters, projects, or namespaces from the Rancher UI.
### Terminology
- **Shibboleth** is a single sign-on log-in system for computer networks and the Internet. It allows people to sign in using just one identity to various systems. It validates user credentials, but does not, on its own, handle group memberships.
- **SAML:** Security Assertion Markup Language, an open standard for exchanging authentication and authorization data between an identity provider and a service provider.
- **OpenLDAP:** a free, open-source implementation of the Lightweight Directory Access Protocol (LDAP). It is used to manage an organization’s computers and users. OpenLDAP is useful for Rancher users because it supports groups. In Rancher, it is possible to assign permissions to groups so that they can access resources such as clusters, projects, or namespaces, as long as the groups already exist in the identity provider.
- **IdP or IDP:** An identity provider. OpenLDAP is an example of an identity provider.
### Adding OpenLDAP Group Permissions to Rancher Resources
The diagram below illustrates how members of an OpenLDAP group can access resources in Rancher that the group has permissions for.
For example, a cluster owner could add an OpenLDAP group to a cluster so that they have permissions view most cluster level resources and create new projects. Then the OpenLDAP group members will have access to the cluster as soon as they log in to Rancher.
In this scenario, OpenLDAP allows the cluster owner to search for groups when assigning persmissions. Without OpenLDAP, the functionality to search for groups would not be supported.
When a member of the OpenLDAP group logs in to Rancher, she is redirected to Shibboleth and enters her username and password.
Shibboleth validates her credentials, and retrieves user attributes from OpenLDAP, including groups. Then Shibboleth sends a SAML assertion to Rancher including the user attributes. Rancher uses the group data so that she can access all of the resources and permissions that her groups have permissions for.
![Adding OpenLDAP Group Permissions to Rancher Resources]({{<baseurl>}}/img/rancher/shibboleth-with-openldap-groups.svg)
content/rancher/v2.6/en/admin-settings/authentication/user-groups/_index.md
+65
View File
@@ -0,0 +1,65 @@
---
title: Users and Groups
weight: 1
---
Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When you configure an external authentication provider, users from that provider will be able to log in to your Rancher server. When a user logs in, the authentication provider will supply your Rancher server with a list of groups to which the user belongs.
Access to clusters, projects, multi-cluster apps, and global DNS providers and entries can be controlled by adding either individual users or groups to these resources. When you add a group to a resource, all users who are members of that group in the authentication provider, will be able to access the resource with the permissions that you've specified for the group. For more information on roles and permissions, see [Role Based Access Control]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/).
## Managing Members
When adding a user or group to a resource, you can search for users or groups by beginning to type their name. The Rancher server will query the authentication provider to find users and groups that match what you've entered. Searching is limited to the authentication provider that you are currently logged in with. For example, if you've enabled GitHub authentication but are logged in using a [local]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/local/) user account, you will not be able to search for GitHub users or groups.
All users, whether they are local users or from an authentication provider, can be viewed and managed. In the upper left corner, click **☰ > Users & Authentication**. In the left navigation bar, click **Users**.
{{< saml_caveats >}}
## User Information
Rancher maintains information about each user that logs in through an authentication provider. This information includes whether the user is allowed to access your Rancher server and the list of groups that the user belongs to. Rancher keeps this user information so that the CLI, API, and kubectl can accurately reflect the access that the user has based on their group membership in the authentication provider.
Whenever a user logs in to the UI using an authentication provider, Rancher automatically updates this user information.
### Automatically Refreshing User Information
Rancher will periodically refresh the user information even before a user logs in through the UI. You can control how often Rancher performs this refresh.
Two settings control this behavior:
- **`auth-user-info-max-age-seconds`**
This setting controls how old a user's information can be before Rancher refreshes it. If a user makes an API call (either directly or by using the Rancher CLI or kubectl) and the time since the user's last refresh is greater than this setting, then Rancher will trigger a refresh. This setting defaults to `3600` seconds, i.e. 1 hour.
- **`auth-user-info-resync-cron`**
This setting controls a recurring schedule for resyncing authentication provider information for all users. Regardless of whether a user has logged in or used the API recently, this will cause the user to be refreshed at the specified interval. This setting defaults to `0 0 * * *`, i.e. once a day at midnight. See the [Cron documentation](https://en.wikipedia.org/wiki/Cron) for more information on valid values for this setting.
To change these settings,
1. In the upper left corner, click **☰ > Global Settings**.
1. Go to the setting you want to configure and click **⋮ > Edit Setting**.
> **Note:** Since SAML does not support user lookup, SAML-based authentication providers do not support periodically refreshing user information. User information will only be refreshed when the user logs into the Rancher UI.
### Manually Refreshing User Information
If you are not sure the last time Rancher performed an automatic refresh of user information, you can perform a manual refresh of all users.
1. In the upper left corner, click **☰ > Users & Authentication**.
1. On the **Users** page, click on **Refresh Group Memberships**.
**Results:** Rancher refreshes the user information for all users. Requesting this refresh will update which users can access Rancher as well as all the groups that each user belongs to.
>**Note:** Since SAML does not support user lookup, SAML-based authentication providers do not support the ability to manually refresh user information. User information will only be refreshed when the user logs into the Rancher UI.
## Session Length
The default length (TTL) of each user session is adjustable. The default session length is 16 hours.
1. In the upper left corner, click **☰ > Global Settings**.
1. Go to **`auth-user-session-ttl-minutes`** and click **⋮ > Edit Setting**.
1. Enter the amount of time in minutes a session length should last and click **Save**.
**Result:** Users are automatically logged out of Rancher after the set number of minutes.
content/rancher/v2.6/en/admin-settings/branding/_index.md
+192
View File
File diff suppressed because one or more lines are too long
content/rancher/v2.6/en/admin-settings/cluster-templates/_index.md
+98
View File
@@ -0,0 +1,98 @@
---
title: Cluster Templates
weight: 100
---
Cluster templates encompass both Kubernetes configuration and node pool configuration, allowing a single template to contain all the information Rancher needs to provision new nodes in a cloud provider and install Kubernetes on those nodes.
- [Overview](#overview)
- [RKE2 Cluster Template](#rke2-cluster-template)
- [Adding a Cluster Template to Rancher](#adding-a-cluster-template-to-rancher)
- [Creating a Cluster from a Cluster Template](#creating-a-cluster-from-a-cluster-template)
- [Uninstalling Cluster Templates](#uninstalling-cluster-templates)
- [Configuration Options](#configuration-options)
# Overview
Cluster templates are provided as Helm charts. To use them, you will need to clone and fork the templates, change them according to your use case, and then install the Helm charts on the Rancher management cluster. When the Helm chart is installed on the Rancher management cluster, a new cluster resource is created, which Rancher uses to provision the new cluster.
After the cluster is provisioned using the template, no changes to the template will affect the cluster. After the cluster is created from the cluster template, its configuration and infrastructure can change, because no restrictions are enforced by cluster templates.
### Kubernetes Distribution
Cluster templates can use any Kubernetes distribution. For now, we provide an example with an RKE2 Kubernetes cluster. We may provide more examples in the future using other Kubernetes distributions.
### Versioning
Rancher doesn't manage version control for cluster templates. Version control is handled in the repository containing the template's Helm chart.
# RKE2 Cluster Template
The example repository for an RKE2 cluster template is [here](https://github.com/rancher/cluster-template-examples). As of Rancher v2.6.0, we provide an RKE2 cluster template and may add more in the future.
# Adding a Cluster Template to Rancher
> **Prerequisite:** You will need permission to configure a Helm chart repository in Rancher.
1. Go to a cluster template example repository. Rancher's examples are in [this GitHub repository.](https://github.com/rancher/cluster-template-examples) As of Rancher v2.6.0, we provide an RKE2 cluster template and add to more in the future.
1. Fork the repository.
1. Optional: Edit the cluster options by editing the `values.yaml` file. For help editing the file, see the cluster template's Helm chart README. Note that in order for the chart to appear in the form for creating new clusters, the chart must have the annotation `catalog.cattle.io/type: cluster-template`.
1. Add the chart repository to Rancher. Click **☰ > Cluster Management**.
1. Go to the `local` cluster and click **Explore.**
1. In the left navigation bar, click **Apps & Marketplace > Chart Repositories.**
1. Click **Create.**
1. Enter a name for the cluster template repository.
1. Click **Git Repository containing Helm chart definitions.**
1. In the **Git Repo URL** field, enter the URL for the repository. For example, `https://github.com/rancher/cluster-template-examples.git`.
1. In the **Git Branch** field, enter the branch to use as the source for the template. Rancher's example repository uses `main`.
1. Click **Create.**
**Result:** The cluster template available from the **Apps & Marketplace** in Rancher's `local` cluster. It can now be used to deploy clusters.
# Creating a Cluster from a Cluster Template
> **Prerequisites:**
>
> - You will need permission to provision new Kubernetes clusters.
> - You will need permission to install Helm charts on the `local` Kubernetes cluster that the Rancher management server is installed on.
> - In order to use a template as part of continuous delivery/GitOps, the cluster template needs to be deployed in the `fleet-local` namespace of the `local` cluster.
> - In order to show in the form for creating new clusters, the cluster template's Helm chart must have the `catalog.cattle.io/type: cluster-template` annotation.
1. Click **☰ > Cluster Management**.
1. On the **Clusters** page, click **Create.**
1. Click **Create Cluster from Template.**
**Result:** After Rancher provisions the new cluster, it is managed in the same way as any other Rancher-launched Kubernetes cluster.
# Uninstalling Cluster Templates
1. Click **☰ > Cluster Management**.
1. Go to the `local` cluster and click **Apps & Marketplace > Chart Repositories.**
1. Go to the chart repository for your cluster template and click **⋮ > Delete.**
1. Confirm the deletion.
**Result:** The cluster template is uninstalled. This action does not affect clusters created with the cluster template.
# Configuration Options
Cluster templates are flexible enough that they can be used to configure all of the following options:
- Node configuration
- Node pools
- Pre-specified cloud credentials
- Enable/configure an authorized cluster endpoint to get kubectl access to the cluster without using Rancher as a proxy
- Install Rancher V2 monitoring
- Kubernetes version
- Assign cluster members
- Infrastructure configuration such as AWS VPC/subnets or vSphere data center
- Cloud provider options
- Pod security options
- Network providers
- Ingress controllers
- Network security configuration
- Network plugins
- Private registry URL and credentials
- Add-ons
- Kubernetes options, including configurations for Kubernetes components such as kube-api, kube-controller, kubelet, and services
For details on how to configure the template, refer to the cluster template's Helm chart README.
content/rancher/v2.6/en/admin-settings/config-private-registry/_index.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Configuring a Global Default Private Registry
weight: 40
---
You might want to use a private Docker registry to share your custom base images within your organization. With a private registry, you can keep a private, consistent, and centralized source of truth for the container images that are used in your clusters.
There are two main ways to set up private registries in Rancher: by setting up the global default registry through the **Settings** tab in the global view, and by setting up a private registry in the advanced options in the cluster-level settings. The global default registry is intended to be used for air-gapped setups, for registries that do not require credentials. The cluster-level private registry is intended to be used in all setups in which the private registry requires credentials.
This section is about configuring the global default private registry, and focuses on how to configure the registry from the Rancher UI after Rancher is installed.
For instructions on setting up a private registry with command line options during the installation of Rancher, refer to the [air gapped Docker installation]({{<baseurl>}}/rancher/v2.6/en/installation/air-gap-single-node) or [air gapped Kubernetes installation]({{<baseurl>}}/rancher/v2.6/en/installation/air-gap-high-availability) instructions.
If your private registry requires credentials, it cannot be used as the default registry. There is no global way to set up a private registry with authorization for every Rancher-provisioned cluster. Therefore, if you want a Rancher-provisioned cluster to pull images from a private registry with credentials, you will have to [pass in the registry credentials through the advanced cluster options](#setting-a-private-registry-with-credentials-when-deploying-a-cluster) every time you create a new cluster.
# Setting a Private Registry with No Credentials as the Default Registry
1. Log into Rancher and configure the default administrator password.
1. Click **☰ > Global Settings**.
1. Go to the setting called `system-default-registry` and choose **⋮ > Edit Setting**.
1. Change the value to your registry (e.g. `registry.yourdomain.com:port`). Do not prefix the registry with `http://` or `https://`.
**Result:** Rancher will use your private registry to pull system images.
# Setting a Private Registry with Credentials when Deploying a Cluster
You can follow these steps to configure a private registry when you create a cluster:
1. Click **☰ > Cluster Management**.
1. On the **Clusters** page, click **Create**.
1. Choose a cluster type.
1. In the **Cluster Configuration** go to the **Registries** tab and click **Pull images for Rancher from a private registry**.
1. Enter the registry hostname and credentials.
1. Click **Create**.
**Result:** The new cluster will be able to pull images from the private registry.
The private registry cannot be configured after the cluster is created.
content/rancher/v2.6/en/admin-settings/drivers/_index.md
+44
View File
@@ -0,0 +1,44 @@
---
title: Provisioning Drivers
weight: 70
---
Drivers in Rancher allow you to manage which providers can be used to deploy [hosted Kubernetes clusters]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes.
### Rancher Drivers
With Rancher drivers, you can enable/disable existing built-in drivers that are packaged in Rancher. Alternatively, you can add your own driver if Rancher has not yet implemented it.
There are two types of drivers within Rancher:
* [Cluster Drivers](#cluster-drivers)
* [Node Drivers](#node-drivers)
### Cluster Drivers
Cluster drivers are used to provision [hosted Kubernetes clusters]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/), such as GKE, EKS, AKS, etc.. The availability of which cluster driver to display when creating a cluster is defined based on the cluster driver's status. Only `active` cluster drivers will be displayed as an option for creating clusters for hosted Kubernetes clusters. By default, Rancher is packaged with several existing cluster drivers, but you can also create custom cluster drivers to add to Rancher.
By default, Rancher has activated several hosted Kubernetes cloud providers including:
* [Amazon EKS]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/eks/)
* [Google GKE]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/gke/)
* [Azure AKS]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/aks/)
There are several other hosted Kubernetes cloud providers that are disabled by default, but are packaged in Rancher:
* [Alibaba ACK]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/ack/)
* [Huawei CCE]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/cce/)
* [Tencent]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/tke/)
### Node Drivers
Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. A node driver is the same as a [Docker Machine driver](https://docs.docker.com/machine/drivers/). The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only `active` node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher.
If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers.
Rancher supports several major cloud providers, but by default, these node drivers are active and available for deployment:
* [Amazon EC2]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/ec2/)
* [Azure]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/azure/)
* [Digital Ocean]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/)
* [vSphere]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/)
content/rancher/v2.6/en/admin-settings/drivers/cluster-drivers/_index.md
+39
View File
@@ -0,0 +1,39 @@
---
title: Cluster Drivers
weight: 1
---
Cluster drivers are used to create clusters in a [hosted Kubernetes provider]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/hosted-kubernetes-clusters/), such as Google GKE. The availability of which cluster driver to display when creating clusters is defined by the cluster driver's status. Only `active` cluster drivers will be displayed as an option for creating clusters. By default, Rancher is packaged with several existing cloud provider cluster drivers, but you can also add custom cluster drivers to Rancher.
If there are specific cluster drivers that you do not want to show your users, you may deactivate those cluster drivers within Rancher and they will not appear as an option for cluster creation.
### Managing Cluster Drivers
>**Prerequisites:** To create, edit, or delete cluster drivers, you need _one_ of the following permissions:
>
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/)
>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Cluster Drivers]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) role assigned.
## Activating/Deactivating Cluster Drivers
By default, Rancher only activates drivers for the most popular cloud providers, Google GKE, Amazon EKS and Azure AKS. If you want to show or hide any node driver, you can change its status.
1. In the upper left corner, click **☰ > Cluster Management**.
2. In the left navigation menu, click **Drivers**.
3. On the **Cluster Drivers** tab, select the driver that you wish to activate or deactivate and click **⋮ > Activate** or **⋮ > Deactivate**.
## Adding Custom Cluster Drivers
If you want to use a cluster driver that Rancher doesn't support out-of-the-box, you can add the provider's driver in order to start using them to create _hosted_ kubernetes clusters.
1. In the upper left corner, click **☰ > Cluster Management**.
1. In the left navigation menu, click **Drivers**.
1. On the **Cluster Drivers** tab, click **Add Cluster Driver**.
1. Complete the **Add Cluster Driver** form. Then click **Create**.
### Developing your own Cluster Driver
In order to develop cluster driver to add to Rancher, please refer to our [example](https://github.com/rancher-plugins/kontainer-engine-driver-example).
content/rancher/v2.6/en/admin-settings/drivers/node-drivers/_index.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Node Drivers
weight: 2
---
Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. A node driver is the same as a [Docker Machine driver](https://docs.docker.com/machine/drivers/). The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only `active` node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher.
If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers.
#### Managing Node Drivers
>**Prerequisites:** To create, edit, or delete drivers, you need _one_ of the following permissions:
>
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/)
>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Node Drivers]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) role assigned.
## Activating/Deactivating Node Drivers
By default, Rancher only activates drivers for the most popular cloud providers, Amazon EC2, Azure, DigitalOcean and vSphere. If you want to show or hide any node driver, you can change its status.
1. In the upper left corner, click **☰ > Cluster Management**.
2. In the left navigation menu, click **Drivers**.
2. On the **Node Drivers** tab, select the driver that you wish to activate or deactivate and click **⋮ > Activate** or **⋮ > Deactivate**.
## Adding Custom Node Drivers
If you want to use a node driver that Rancher doesn't support out-of-the-box, you can add that provider's driver in order to start using them to create node templates and eventually node pools for your Kubernetes cluster.
1. In the upper left corner, click **☰ > Cluster Management**.
1. In the left navigation menu, click **Drivers**.
1. On **Node Drivers** tab, click **Add Node Driver**.
1. Complete the **Add Node Driver** form. Then click **Create**.
### Developing your own node driver
Node drivers are implemented with [Docker Machine](https://docs.docker.com/machine/).
content/rancher/v2.6/en/admin-settings/k8s-metadata/_index.md
+77
View File
@@ -0,0 +1,77 @@
---
title: Upgrading Kubernetes without Upgrading Rancher
weight: 30
---
The RKE metadata feature allows you to provision clusters with new versions of Kubernetes as soon as they are released, without upgrading Rancher. This feature is useful for taking advantage of patch versions of Kubernetes, for example, if you want to upgrade to Kubernetes v1.14.7 when your Rancher server originally supported v1.14.6.
> **Note:** The Kubernetes API can change between minor versions. Therefore, we don't support introducing minor Kubernetes versions, such as introducing v1.15 when Rancher currently supports v1.14. You would need to upgrade Rancher to add support for minor Kubernetes versions.
Rancher's Kubernetes metadata contains information specific to the Kubernetes version that Rancher uses to provision [RKE clusters]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/). Rancher syncs the data periodically and creates custom resource definitions (CRDs) for **system images,** **service options** and **addon templates**. Consequently, when a new Kubernetes version is compatible with the Rancher server version, the Kubernetes metadata makes the new version available to Rancher for provisioning clusters. The metadata gives you an overview of the information that the [Rancher Kubernetes Engine]({{<baseurl>}}/rke/latest/en/) (RKE) uses for deploying various Kubernetes versions.
This table below describes the CRDs that are affected by the periodic data sync.
> **Note:** Only administrators can edit metadata CRDs. It is recommended not to update existing objects unless explicitly advised.
| Resource | Description | Rancher API URL |
|----------|-------------|-----------------|
| System Images | List of system images used to deploy Kubernetes through RKE. | `<RANCHER_SERVER_URL>/v3/rkek8ssystemimages` |
| Service Options | Default options passed to Kubernetes components like `kube-api`, `scheduler`, `kubelet`, `kube-proxy`, and `kube-controller-manager` | `<RANCHER_SERVER_URL>/v3/rkek8sserviceoptions` |
| Addon Templates | YAML definitions used to deploy addon components like Canal, Calico, Flannel, Weave, Kube-dns, CoreDNS, `metrics-server`, `nginx-ingress` | `<RANCHER_SERVER_URL>/v3/rkeaddons` |
Administrators might configure the RKE metadata settings to do the following:
- Refresh the Kubernetes metadata, if a new patch version of Kubernetes comes out and they want Rancher to provision clusters with the latest version of Kubernetes without having to upgrade Rancher
- Change the metadata URL that Rancher uses to sync the metadata, which is useful for air gap setups if you need to sync Rancher locally instead of with GitHub
- Prevent Rancher from auto-syncing the metadata, which is one way to prevent new and unsupported Kubernetes versions from being available in Rancher
### Refresh Kubernetes Metadata
The option to refresh the Kubernetes metadata is available for administrators by default, or for any user who has the **Manage Cluster Drivers** [global role.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/)
To force Rancher to refresh the Kubernetes metadata, a manual refresh action is available:
1. In the upper left corner, click **☰ > Cluster Management**.
1. In the left navigation menu, click **Drivers**.
1. Click **Refresh Kubernetes Metadata**.
You can configure Rancher to only refresh metadata when desired by setting `refresh-interval-minutes` to `0` (see below) and using this button to perform the metadata refresh manually when desired.
### Configuring the Metadata Synchronization
> Only administrators can change these settings.
The RKE metadata config controls how often Rancher syncs metadata and where it downloads data from. You can configure the metadata from the settings in the Rancher UI, or through the Rancher API at the endpoint `v3/settings/rke-metadata-config`.
The way that the metadata is configured depends on the Rancher version.
To edit the metadata config in Rancher,
1. In the upper left corner, click **☰ > Global Settings**.
1. Go to the **rke-metadata-config** section. Click **⋮ > Edit Setting**.
1. You can optionally fill in the following parameters:
- `refresh-interval-minutes`: This is the amount of time that Rancher waits to sync the metadata. To disable the periodic refresh, set `refresh-interval-minutes` to 0.
- `url`: This is the HTTP path that Rancher fetches data from. The path must be a direct path to a JSON file. For example, the default URL for Rancher v2.4 is `https://releases.rancher.com/kontainer-driver-metadata/release-v2.4/data.json`.
1. Click **Save**.
If you don't have an air gap setup, you don't need to specify the URL where Rancher gets the metadata, because the default setting is to pull from [Rancher's metadata Git repository.](https://github.com/rancher/kontainer-driver-metadata/blob/dev-v2.5/data/data.json)
However, if you have an [air gap setup,](#air-gap-setups) you will need to mirror the Kubernetes metadata repository in a location available to Rancher. Then you need to change the URL to point to the new location of the JSON file.
### Air Gap Setups
Rancher relies on a periodic refresh of the `rke-metadata-config` to download new Kubernetes version metadata if it is supported with the current version of the Rancher server. For a table of compatible Kubernetes and Rancher versions, refer to the [service terms section.](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.2.8/)
If you have an air gap setup, you might not be able to get the automatic periodic refresh of the Kubernetes metadata from Rancher's Git repository. In that case, you should disable the periodic refresh to prevent your logs from showing errors. Optionally, you can configure your metadata settings so that Rancher can sync with a local copy of the RKE metadata.
To sync Rancher with a local mirror of the RKE metadata, an administrator would configure the `rke-metadata-config` settings to point to the mirror. For details, refer to [Configuring the Metadata Synchronization.](#configuring-the-metadata-synchronization)
After new Kubernetes versions are loaded into the Rancher setup, additional steps would be required in order to use them for launching clusters. Rancher needs access to updated system images. While the metadata settings can only be changed by administrators, any user can download the Rancher system images and prepare a private Docker registry for them.
1. To download the system images for the private registry, click the Rancher server version at the bottom left corner of the Rancher UI.
1. Download the OS specific image lists for Linux or Windows.
1. Download `rancher-images.txt`.
1. Prepare the private registry using the same steps during the [air gap install]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/populate-private-registry), but instead of using the `rancher-images.txt` from the releases page, use the one obtained from the previous steps.
**Result:** The air gap installation of Rancher can now sync the Kubernetes metadata. If you update your private registry when new versions of Kubernetes are released, you can provision clusters with the new version without having to upgrade Rancher.
content/rancher/v2.6/en/admin-settings/pod-security-policies/_index.md
+81
View File
@@ -0,0 +1,81 @@
---
title: Pod Security Policies
weight: 60
---
_Pod Security Policies_ (or PSPs) are objects that control security-sensitive aspects of pod specification (like root privileges).
If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message of `Pod <NAME> is forbidden: unable to validate...`.
- [How PSPs Work](#how-psps-work)
- [Default PSPs](#default-psps)
- [Restricted](#restricted)
- [Unrestricted](#unrestricted)
- [Creating PSPs](#creating-psps)
- [Requirements](#requirements)
- [Creating PSPs in the Rancher UI](#creating-psps-in-the-rancher-ui)
- [Configuration](#configuration)
# How PSPs Work
You can assign PSPs at the cluster or project level.
PSPs work through inheritance:
- By default, PSPs assigned to a cluster are inherited by its projects, as well as any namespaces added to those projects.
- **Exception:** Namespaces that are not assigned to projects do not inherit PSPs, regardless of whether the PSP is assigned to a cluster or project. Because these namespaces have no PSPs, workload deployments to these namespaces will fail, which is the default Kubernetes behavior.
- You can override the default PSP by assigning a different PSP directly to the project.
Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked if it complies with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP.
Read more about Pod Security Policies in the [Kubernetes Documentation](https://kubernetes.io/docs/concepts/policy/pod-security-policy/).
# Default PSPs
Rancher ships with two default Pod Security Policies (PSPs): the `restricted` and `unrestricted` policies.
### Restricted
This policy is based on the Kubernetes [example restricted policy](https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/policy/restricted-psp.yaml). It significantly restricts what types of pods can be deployed to a cluster or project. This policy:
- Prevents pods from running as a privileged user and prevents escalation of privileges.
- Validates that server-required security mechanisms are in place (such as restricting what volumes can be mounted to only the core volume types and preventing root supplemental groups from being added.
### Unrestricted
This policy is equivalent to running Kubernetes with the PSP controller disabled. It has no restrictions on what pods can be deployed into a cluster or project.
# Creating PSPs
Using Rancher, you can create a Pod Security Policy using our GUI rather than creating a YAML file.
### Requirements
Rancher can only assign PSPs for clusters that are [launched using RKE.]({{< baseurl >}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/)
You must enable PSPs at the cluster level before you can assign them to a project. This can be configured by [editing the cluster.]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/editing-clusters/)
It is a best practice to set PSP at the cluster level.
We recommend adding PSPs during cluster and project creation instead of adding it to an existing one.
### Creating PSPs in the Rancher UI
1. In the upper left corner, click **☰ > Cluster Management**.
1. In the left navigation bar, click **Pod Security Policies**.
1. Click **Add policy**.
1. Name the policy.
1. Complete each section of the form. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) for more information on what each policy does.
1. Click **Create**.
# Configuration
The Kubernetes documentation on PSPs is [here.](https://kubernetes.io/docs/concepts/policy/pod-security-policy/)
<!-- links -->
[1]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#volumes-and-file-systems
[2]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#host-namespaces
[3]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#users-and-groups
content/rancher/v2.6/en/admin-settings/rbac/_index.md
+26
View File
@@ -0,0 +1,26 @@
---
title: Role-Based Access Control (RBAC)
weight: 20
---
Within Rancher, each person authenticates as a _user_, which is a login that grants you access to Rancher. As mentioned in [Authentication]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/), users can either be local or external.
After you configure external authentication, the users that display on the **Users** page changes.
- If you are logged in as a local user, only local users display.
- If you are logged in as an external user, both external and local users display.
## Users and Roles
Once the user logs in to Rancher, their _authorization_, or their access rights within the system, is determined by _global permissions_, and _cluster and project roles_.
- [Global Permissions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/):
Define user authorization outside the scope of any particular cluster.
- [Cluster and Project Roles]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/cluster-project-roles/):
Define user authorization inside the specific cluster or project where they are assigned the role.
Both global permissions and cluster and project roles are implemented on top of [Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). Therefore, enforcement of permissions and roles is performed by Kubernetes.
content/rancher/v2.6/en/admin-settings/rbac/cluster-project-roles/_index.md
+203
View File
@@ -0,0 +1,203 @@
---
title: Cluster and Project Roles
weight: 1127
---
Cluster and project roles define user authorization inside a cluster or project.
To manage these roles,
1. Click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Roles** and go to the **Cluster** or **Project/Namespaces** tab.
### Membership and Role Assignment
The projects and clusters accessible to non-administrative users is determined by _membership_. Membership is a list of users who have access to a specific cluster or project based on the roles they were assigned in that cluster or project. Each cluster and project includes a tab that a user with the appropriate permissions can use to manage membership.
When you create a cluster or project, Rancher automatically assigns you as the `Owner` for it. Users assigned the `Owner` role can assign other users roles in the cluster or project.
> **Note:** Non-administrative users cannot access any existing projects/clusters by default. A user with appropriate permissions (typically the owner) must explicitly assign the project and cluster membership.
### Cluster Roles
_Cluster roles_ are roles that you can assign to users, granting them access to a cluster. There are two primary cluster roles: `Owner` and `Member`.
- **Cluster Owner:**
These users have full control over the cluster and all resources in it.
- **Cluster Member:**
These users can view most cluster level resources and create new projects.
#### Custom Cluster Roles
Rancher lets you assign _custom cluster roles_ to a standard user instead of the typical `Owner` or `Member` roles. These roles can be either a built-in custom cluster role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a cluster. See the table below for a list of built-in custom cluster roles.
#### Cluster Role Reference
The following table lists each built-in custom cluster role available and whether that level of access is included in the default cluster-level permissions, `Cluster Owner` and `Cluster Member`.
| Built-in Cluster Role | Owner | Member <a id="clus-roles"></a> |
| ---------------------------------- | ------------- | --------------------------------- |
| Create Projects | ✓ | ✓ |
| Manage Cluster Backups             | ✓ | |
| Manage Cluster Catalogs | ✓ | |
| Manage Cluster Members | ✓ | |
| Manage Nodes [(see table below)](#Manage-Nodes-Permissions)| ✓ | |
| Manage Storage | ✓ | |
| View All Projects | ✓ | |
| View Cluster Catalogs | ✓ | ✓ |
| View Cluster Members | ✓ | ✓ |
| View Nodes | ✓ | ✓ |
#### Manage Nodes Permissions
The following table lists the permissions available for the `Manage Nodes` role in RKE and RKE2.
| Manage Nodes Permissions | RKE | RKE2 |
|-----------------------------|-------- |--------- |
| SSH Access | ✓ | ✓ |
| Delete Nodes | ✓ | ✓ |
| Scale Clusters Up and Down | ✓ | * |
***In RKE2, you must have permission to edit a cluster to be able to scale clusters up and down.**
<br />
For details on how each cluster role can access Kubernetes resources, you can look them up in the Rancher UI:
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Roles**.
1. Click the **Cluster** tab.
1. Click the name of an individual role. The table shows all of the operations and resources that are permitted by the role.
> **Note:**
>When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
### Giving a Custom Cluster Role to a Cluster Member
After an administrator [sets up a custom cluster role,]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/default-custom-roles/) cluster owners and admins can then assign those roles to cluster members.
To assign a custom role to a new cluster member, you can use the Rancher UI. To modify the permissions of an existing member, you will need to use the Rancher API view.
To assign the role to a new cluster member,
1. Click **☰ > Cluster Management**.
1. Go to the cluster where you want to assign a role to a member and click **Explore**.
1. Click **RBAC > Cluster Members**.
1. Click **Add**.
1. In the **Cluster Permissions** section, choose the custom cluster role that should be assigned to the member.
1. Click **Create**.
**Result:** The member has the assigned role.
To assign any custom role to an existing cluster member,
1. Click **☰ > Users & Authentication**.
1. Go to the member you want to give the role to. Click the **⋮ > Edit Config**.
1. If you have added custom roles, they will show in the **Custom** section. Choose the role you want to assign to the member.
1. Click **Save**.
**Result:** The member has the assigned role.
### Project Roles
_Project roles_ are roles that can be used to grant users access to a project. There are three primary project roles: `Owner`, `Member`, and `Read Only`.
- **Project Owner:**
These users have full control over the project and all resources in it.
- **Project Member:**
These users can manage project-scoped resources like namespaces and workloads, but cannot manage other project members.
- **Read Only:**
These users can view everything in the project but cannot create, update, or delete anything.
>**Caveat:**
>
>Users assigned the `Owner` or `Member` role for a project automatically inherit the `namespace creation` role. However, this role is a [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole), meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the `owner` or `member` role for a project can create namespaces in other projects they're assigned to, even with only the `Read Only` role assigned.
#### Custom Project Roles
Rancher lets you assign _custom project roles_ to a standard user instead of the typical `Owner`, `Member`, or `Read Only` roles. These roles can be either a built-in custom project role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a project. See the table below for a list of built-in custom project roles.
#### Project Role Reference
The following table lists each built-in custom project role available in Rancher and whether it is also granted by the `Owner`, `Member`, or `Read Only` role.
| Built-in Project Role | Owner | Member<a id="proj-roles"><a/> | Read Only |
| ---------------------------------- | ------------- | ----------------------------- | ------------- |
| Manage Project Members | ✓ | | |
| Create Namespaces | ✓ | ✓ | |
| Manage Config Maps | ✓ | ✓ | |
| Manage Ingress | ✓ | ✓ | |
| Manage Project Catalogs | ✓ | | |
| Manage Secrets | ✓ | ✓ | |
| Manage Service Accounts | ✓ | ✓ | |
| Manage Services | ✓ | ✓ | |
| Manage Volumes | ✓ | ✓ | |
| Manage Workloads | ✓ | ✓ | |
| View Secrets | ✓ | ✓ | |
| View Config Maps | ✓ | ✓ | ✓ |
| View Ingress | ✓ | ✓ | ✓ |
| View Project Members | ✓ | ✓ | ✓ |
| View Project Catalogs | ✓ | ✓ | ✓ |
| View Service Accounts | ✓ | ✓ | ✓ |
| View Services | ✓ | ✓ | ✓ |
| View Volumes | ✓ | ✓ | ✓ |
| View Workloads | ✓ | ✓ | ✓ |
> **Notes:**
>
>- Each project role listed above, including `Owner`, `Member`, and `Read Only`, is comprised of multiple rules granting access to various resources. You can view the roles and their rules on the Global > Security > Roles page.
>- When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
>- The `Manage Project Members` role allows the project owner to manage any members of the project **and** grant them any project scoped role regardless of their access to the project resources. Be cautious when assigning this role out individually.
### Defining Custom Roles
As previously mentioned, custom roles can be defined for use at the cluster or project level. The context field defines whether the role will appear on the cluster member page, project member page, or both.
When defining a custom role, you can grant access to specific resources or specify roles from which the custom role should inherit. A custom role can be made up of a combination of specific grants and inherited roles. All grants are additive. This means that defining a narrower grant for a specific resource **will not** override a broader grant defined in a role that the custom role is inheriting from.
### Default Cluster and Project Roles
By default, when a standard user creates a new cluster or project, they are automatically assigned an ownership role: either [cluster owner](#cluster-roles) or [project owner](#project-roles). However, in some organizations, these roles may overextend administrative access. In this use case, you can change the default role to something more restrictive, such as a set of individual roles or a custom role.
There are two methods for changing default cluster/project roles:
- **Assign Custom Roles**: Create a [custom role]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/default-custom-roles) for either your [cluster](#custom-cluster-roles) or [project](#custom-project-roles), and then set the custom role as default.
- **Assign Individual Roles**: Configure multiple [cluster](#cluster-role-reference)/[project](#project-role-reference) roles as default for assignment to the creating user.
For example, instead of assigning a role that inherits other roles (such as `cluster owner`), you can choose a mix of individual roles (such as `manage nodes` and `manage storage`).
>**Note:**
>
>- Although you can [lock]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/locked-roles/) a default role, the system still assigns the role to users who create a cluster/project.
>- Only users that create clusters/projects inherit their roles. Users added to the cluster/project membership afterward must be explicitly assigned their roles.
### Configuring Default Roles for Cluster and Project Creators
You can change the cluster or project role(s) that are automatically assigned to the creating user.
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Roles**.
1. Click the **Cluster** or **Project/Namespaces** tab.
1. Find the custom or individual role that you want to use as default. Then edit the role by selecting **⋮ > Edit Config**.
1. In the **Cluster Creator Default** or **Project Creator Default** section, enable the role as the default.
1. Click **Save**.
**Result:** The default roles are configured based on your changes. Roles assigned to cluster/project creators display a check in the **Cluster/Project Creator Default** column.
If you want to remove a default role, edit the permission and select **No** from the default roles option.
### Cluster Membership Revocation Behavior
When you revoke the cluster membership for a standard user that's explicitly assigned membership to both the cluster _and_ a project within the cluster, that standard user [loses their cluster roles](#clus-roles) but [retains their project roles](#proj-roles). In other words, although you have revoked the user's permissions to access the cluster and its nodes, the standard user can still:
- Access the projects they hold membership in.
- Exercise any [individual project roles](#project-role-reference) they are assigned.
If you want to completely revoke a user's access within a cluster, revoke both their cluster and project memberships.
content/rancher/v2.6/en/admin-settings/rbac/default-custom-roles/_index.md
+121
View File
@@ -0,0 +1,121 @@
---
title: Custom Roles
weight: 1128
---
Within Rancher, _roles_ determine what actions a user can make within a cluster or project.
Note that _roles_ are different from _permissions_, which determine what clusters and projects you can access.
> It is possible for a custom role to enable privilege escalation. For details, see [this section.](#privilege-escalation)
This section covers the following topics:
- [Prerequisites](#prerequisites)
- [Creating a custom role](#creating-a-custom-role)
- [Creating a custom role that inherits from another role](#creating-a-custom-role-that-inherits-from-another-role)
- [Deleting a custom role](#deleting-a-custom-role)
- [Assigning a custom role to a group](#assigning-a-custom-role-to-a-group)
- [Privilege escalation](#privilege-escalation)
# Prerequisites
To complete the tasks on this page, one of the following permissions are required:
- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/).
- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Roles]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) role assigned.
# Creating A Custom Role
While Rancher comes out-of-the-box with a set of default user roles, you can also create default custom roles to provide users with very specific permissions within Rancher.
The steps to add custom roles differ depending on the version of Rancher.
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Roles**.
1. Select a tab to determine the scope of the role you're adding. The tabs are:
- **Global:** The role is valid for allowing members to manage global scoped resources.
- **Cluster:** The role is valid for assignment when adding/managing members to clusters.
- **Project/Namespaces:** The role is valid for assignment when adding/managing members to projects or namespaces.
1. Click **Create Global Role,** **Create Cluster Role** or **Create Project/Namespaces Role,** depending on the scope.
1. Enter a **Name** for the role.
1. Optional: Choose the **Cluster/Project Creator Default** option to assign this role to a user when they create a new cluster or project. Using this feature, you can expand or restrict the default roles for cluster/project creators.
> Out of the box, the Cluster Creator Default and the Project Creator Default roles are `Cluster Owner` and `Project Owner` respectively.
1. Use the **Grant Resources** options to assign individual [Kubernetes API endpoints](https://kubernetes.io/docs/reference/) to the role.
> When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
> The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or `(Custom)` resource must be selected from the dropdown, after entering a resource name into this field.
You can also choose the individual cURL methods (`Create`, `Delete`, `Get`, etc.) available for use with each endpoint you assign.
1. Use the **Inherit from** options to assign individual Rancher roles to your custom roles. Note: When a custom role inherits from a parent role, the parent role cannot be deleted until the child role is deleted.
1. Click **Create**.
# Creating a Custom Role that Inherits from Another Role
If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom role in which all of the rules from another role, such as the administrator role, are copied into a new role. This allows you to only configure the variations between the existing role and the new role.
The custom role can then be assigned to a user or group so that the role takes effect the first time the user or users sign into Rancher.
To create a custom role based on an existing role,
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Roles**.
1. Click the **Cluster** or **Project/Namespaces** tab. Click **Create Cluster Role** or **Create Project/Namespaces Role** depending on the scope. Note: Only cluster roles and project/namespace roles can inherit from another role.
1. Enter a name for the role.
1. In the **Inherit From** tab, select the role(s) that the custom role will inherit permissions from.
1. In the **Grant Resources** tab, select the Kubernetes resource operations that will be enabled for users with the custom role.
> The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or `(Custom)` resource must be selected from the dropdown, after entering a resource name into this field.
1. Optional: Assign the role as default.
1. Click **Create**.
# Deleting a Custom Role
When deleting a custom role, all global role bindings with this custom role are deleted.
If a user is only assigned one custom role, and the role is deleted, the user would lose access to Rancher. For the user to regain access, an administrator would need to edit the user and apply new global permissions.
Custom roles can be deleted, but built-in roles cannot be deleted.
To delete a custom role,
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Roles**.
2. Go to the custom global role that should be deleted and click **⋮ (…) > Delete**.
3. Click **Delete**.
# Assigning a Custom Role to a Group
If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom role. When the role is assigned to a group, the users in the group have the appropriate level of access the first time they sign into Rancher.
When a user in the group logs in, they get the built-in Standard User global role by default. They will also get the permissions assigned to their groups.
If a user is removed from the external authentication provider group, they would lose their permissions from the custom role that was assigned to the group. They would continue to have their individual Standard User role.
> **Prerequisites:** You can only assign a global role to a group if:
>
> * You have set up an [external authentication provider]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/#external-vs-local-authentication)
> * The external authentication provider supports [user groups]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/user-groups/)
> * You have already set up at least one user group with the authentication provider
To assign a custom role to a group, follow these steps:
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Groups**.
1. Go to the existing group that will be assigned the custom role and click **⋮ > Edit Config**.
1. If you have created roles, they will show in the **Custom** section. Choose any custom role that will be assigned to the group.
1. Optional: In the **Global Permissions** or **Built-in** sections, select any additional permissions that the group should have.
1. Click **Save.**.
**Result:** The custom role will take effect when the users in the group log into Rancher.
# Privilege Escalation
The `Configure Catalogs` custom permission is powerful and should be used with caution. When an admin assigns the `Configure Catalogs` permission to a standard user, it could result in privilege escalation in which the user could give themselves admin access to Rancher provisioned clusters. Anyone with this permission should be considered equivalent to an admin.
content/rancher/v2.6/en/admin-settings/rbac/global-permissions/_index.md
+254
View File
@@ -0,0 +1,254 @@
---
title: Global Permissions
weight: 1126
---
_Permissions_ are individual access rights that you can assign when selecting a custom permission for a user.
Global Permissions define user authorization outside the scope of any particular cluster. Out-of-the-box, there are four default global permissions: `Administrator`, `Restricted Admin`,`Standard User` and `User-base`.
- **Administrator:** These users have full control over the entire Rancher system and all clusters within it.
- **Restricted Admin:** These users have full control over downstream clusters, but cannot alter the local Kubernetes cluster.
- <a id="user"></a>**Standard User:** These users can create new clusters and use them. Standard users can also assign other users permissions to their clusters.
- **User-Base:** User-Base users have login-access only.
You cannot update or delete the built-in Global Permissions.
This section covers the following topics:
- [Restricted Admin](#restricted-admin)
- [Global permission assignment](#global-permission-assignment)
- [Global permissions for new local users](#global-permissions-for-new-local-users)
- [Global permissions for users with external authentication](#global-permissions-for-users-with-external-authentication)
- [Custom global permissions](#custom-global-permissions)
- [Custom global permissions reference](#custom-global-permissions-reference)
- [Configuring default global permissions for new users](#configuring-default-global-permissions)
- [Configuring global permissions for existing individual users](#configuring-global-permissions-for-existing-individual-users)
- [Configuring global permissions for groups](#configuring-global-permissions-for-groups)
- [Refreshing group memberships](#refreshing-group-memberships)
# 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.
The `restricted-admin` can create other `restricted-admin` users with an equal level of access.
A new setting was added to Rancher to set the initial bootstrapped administrator to have the `restricted-admin` role. This applies to the first user created when the Rancher server is started for the first time. If the environment variable is set, then no global administrator would be created, and it would be impossible to create the global administrator through Rancher.
To bootstrap Rancher with the `restricted-admin` as the initial user, the Rancher server should be started with the following environment variable:
```
CATTLE_RESTRICTED_DEFAULT_ADMIN=true
```
### List of `restricted-admin` Permissions
The following table lists the permissions and actions that a `restricted-admin` should have in comparison with the `Administrator` and `Standard User` roles:
| Category | Action | Global Admin | Standard User | Restricted Admin | Notes for Restricted Admin role |
| -------- | ------ | ------------ | ------------- | ---------------- | ------------------------------- |
| Local Cluster functions | Manage Local Cluster (List, Edit, Import Host) | Yes | No | No | |
| | Create Projects/namespaces | Yes | No | No | |
| | Add cluster/project members | Yes | No | No | |
| | Deploy MulticlusterApp in local cluster | Yes | No | No | |
| | Global DNS | Yes | No | No | |
| | Access to management cluster for CRDs and CRs | Yes | No | Yes | |
| | Save as RKE Template | Yes | No | No | |
| Security | | | | | |
| Enable auth | Configure Authentication | Yes | No | Yes | |
| Roles | Create/Assign GlobalRoles | Yes | No (Can list) | Yes | Auth webhook allows creating globalrole for perms already present |
| | Create/Assign ClusterRoles | Yes | No (Can list) | Yes | Not in local cluster |
| | Create/Assign ProjectRoles | Yes | No (Can list) | Yes | Not in local cluster |
| Users | Add User/Edit/Delete/Deactivate User | Yes | No | Yes | |
| Groups | Assign Global role to groups | Yes | No | Yes | As allowed by the webhook |
| | Refresh Groups | Yes | No | Yes | |
| PSP's | Manage PSP templates | Yes | No (Can list) | Yes | Same privileges as Global Admin for PSPs |
| Tools | | | | | |
| | Manage RKE Templates | Yes | No | Yes | |
| | Manage Global Catalogs | Yes | No | Yes | Cannot edit/delete built-in system catalog. Can manage Helm library |
| | Cluster Drivers | Yes | No | Yes | |
| | Node Drivers | Yes | No | Yes | |
| | GlobalDNS Providers | Yes | Yes (Self) | Yes | |
| | GlobalDNS Entries | Yes | Yes (Self) | Yes | |
| Settings | | | | | |
| | Manage Settings | Yes | No (Can list) | No (Can list) | |
| Apps | | | | | |
| | Launch Multicluster Apps | Yes | Yes | Yes | Not in local cluster |
| User | | | | | |
| | Manage API Keys | Yes (Manage all) | Yes (Manage self) | Yes (Manage self) | |
| | Manage Node Templates | Yes | Yes (Manage self) | Yes (Manage self) | Can only manage their own node templates and not those created by other users |
| | Manage Cloud Credentials | Yes | Yes (Manage self) | Yes (Manage self) | Can only manage their own cloud credentials and not those created by other users |
| Downstream Cluster | Create Cluster | Yes | Yes | Yes | |
| | Edit Cluster | Yes | Yes | Yes | |
| | Rotate Certificates | Yes | | Yes | |
| | Snapshot Now | Yes | | Yes | |
| | Restore Snapshot | Yes | | Yes | |
| | Save as RKE Template | Yes | No | Yes | |
| | Run CIS Scan | Yes | Yes | Yes | |
| | Add Members | Yes | Yes | Yes | |
| | Create Projects | Yes | Yes | Yes | |
| Feature Charts since v2.5 | | | | | |
| | Install Fleet | Yes | | Yes | Should not be able to run Fleet in local cluster |
| | Deploy EKS cluster | Yes | Yes | Yes | |
| | Deploy GKE cluster | Yes | Yes | Yes | |
| | Deploy AKS cluster | Yes | Yes | Yes | |
### Changing Global Administrators to Restricted Admins
If Rancher already has a global administrator, they should change all global administrators over to the new `restricted-admin` role.
This can be done through **Security > Users** and moving any Administrator role over to Restricted Administrator.
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 permissions for local users are assigned differently than users who log in to Rancher using external authentication.
### Global Permissions for New Local Users
When you create a new local user, you assign them a global permission as you complete the **Add User** form.
To see the default permissions for new users,
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Roles**.
1. The **Roles** page has tabs for roles grouped by scope. Each table lists the roles in that scope. In the **Global** tab, in the **New User Default** column, the permissions given to new users by default are indicated with a checkmark.
You can [change the default global permissions to meet your needs.](#configuring-default-global-permissions)
### Global Permissions for Users with External Authentication
When a user logs into Rancher using an external authentication provider for the first time, they are automatically assigned the **New User Default** global permissions. By default, Rancher assigns the **Standard User** permission for new users.
To see the default permissions for new users,
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Roles**.
1. The **Roles** page has tabs for roles grouped by scope. Each table lists the roles in that scope. In the **New User Default** column on each page, the permissions given to new users by default are indicated with a checkmark.
You can [change the default permissions to meet your needs.](#configuring-default-global-permissions)
Permissions can be assigned to an individual user with [these steps.](#configuring-global-permissions-for-existing-individual-users)
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
Using custom permissions is convenient for providing users with narrow or specialized access to Rancher.
When a user from an [external authentication source]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/) signs into Rancher for the first time, they're automatically assigned a set of global permissions (hereafter, permissions). By default, after a user logs in for the first time, they are created as a user and assigned the default `user` permission. The standard `user` permission allows users to login and create clusters.
However, in some organizations, these permissions may extend too much access. Rather than assigning users the default global permissions of `Administrator` or `Standard User`, you can assign them a more restrictive set of custom global permissions.
The default roles, Administrator and Standard User, each come with multiple global permissions built into them. The Administrator role includes all global permissions, while the default user role includes three global permissions: Create Clusters, Use Catalog Templates, and User Base, which is equivalent to the minimum permission to log in to Rancher. In other words, the custom global permissions are modularized so that if you want to change the default user role permissions, you can choose which subset of global permissions are included in the new default user role.
Administrators can enforce custom global permissions in multiple ways:
- [Changing the default permissions for new users](#configuring-default-global-permissions)
- [Configuring global permissions for individual users](#configuring-global-permissions-for-individual-users)
- [Configuring global permissions for groups](#configuring-global-permissions-for-groups)
### Custom Global Permissions Reference
The following table lists each custom global permission available and whether it is included in the default global permissions, `Administrator`, `Standard User` and `User-Base`.
| Custom Global Permission | Administrator | Standard User | User-Base |
| ---------------------------------- | ------------- | ------------- |-----------|
| Create Clusters | ✓ | ✓ | |
| Create RKE Templates | ✓ | ✓ | |
| Manage Authentication | ✓ | | |
| Manage Catalogs | ✓ | | |
| Manage Cluster Drivers | ✓ | | |
| Manage Node Drivers | ✓ | | |
| Manage PodSecurityPolicy Templates | ✓ | | |
| Manage Roles | ✓ | | |
| Manage Settings | ✓ | | |
| Manage Users | ✓ | | |
| Use Catalog Templates | ✓ | ✓ | |
| User-Base (Basic log-in access) | ✓ | ✓ | |
For details on which Kubernetes resources correspond to each global permission,
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Roles**.
1. If you click the name of an individual role, a table shows all of the operations and resources that are permitted by the role.
> **Notes:**
>
> - Each permission listed above is comprised of multiple individual permissions not listed in the Rancher UI. For a full list of these permissions and the rules they are comprised of, access through the API at `/v3/globalRoles`.
> - When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
### Configuring Default Global Permissions
If you want to restrict the default permissions for new users, you can remove the `user` permission as default role and then assign multiple individual permissions as default instead. Conversely, you can also add administrative permissions on top of a set of other standard permissions.
> **Note:** Default roles are only assigned to users added from an external authentication provider. For local users, you must explicitly assign global permissions when adding a user to Rancher. You can customize these global permissions when adding the user.
To change the default global permissions that are assigned to external users upon their first log in, follow these steps:
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Roles**. On the **Roles** page, make sure the **Global** tab is selected.
1. Find the permissions set that you want to add or remove as a default. Then edit the permission by selecting **⋮ > Edit Config**.
1. If you want to add the permission as a default, Select **Yes: Default role for new users** and then click **Save**. If you want to remove a default permission, edit the permission and select **No**.
**Result:** The default global permissions are configured based on your changes. Permissions assigned to new users display a check in the **New User Default** column.
### Configuring Global Permissions for Individual Users
To configure permission for a user,
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Users**.
1. Go to the user whose access level you want to change and click **⋮ > Edit Config**.
1. In the **Global Permissions** and **Built-in** sections, check the boxes for each permission you want the user to have. If you have created roles from the **Roles** page, they will appear in the **Custom** section and you can choose from them as well.
1. Click **Save**.
> **Result:** The user's global permissions have been updated.
### Configuring Global Permissions for Groups
If you have a group of individuals that need the same level of access in Rancher, it can save time to assign permissions to the entire group at once, so that the users in the group have the appropriate level of access the first time they sign into Rancher.
After you assign a custom global role to a group, the custom global role will be assigned to a user in the group when they log in to Rancher.
For existing users, the new permissions will take effect when the users log out of Rancher and back in again, or when an administrator [refreshes the group memberships.](#refreshing-group-memberships)
For new users, the new permissions take effect when the users log in to Rancher for the first time. New users from this group will receive the permissions from the custom global role in addition to the **New User Default** global permissions. By default, the **New User Default** permissions are equivalent to the **Standard User** global role, but the default permissions can be [configured.](#configuring-default-global-permissions)
If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have any remaining roles that were assigned to them, which would typically include the roles marked as **New User Default**. Rancher will remove the permissions that are associated with the group when the user logs out, or when an administrator [refreshes group memberships,](#refreshing-group-memberships) whichever comes first.
> **Prerequisites:** You can only assign a global role to a group if:
>
> * You have set up an [external authentication provider]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/#external-vs-local-authentication)
> * The external authentication provider supports [user groups]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/user-groups/)
> * You have already set up at least one user group with the authentication provider
To assign a custom global role to a group, follow these steps:
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Groups**.
1. Go to the group you want to assign a custom global role to and click **⋮ > Edit Config**.
1. In the **Global Permissions,** **Custom,** and/or **Built-in** sections, select the permissions that the group should have.
1. Click **Create**.
**Result:** The custom global role will take effect when the users in the group log into Rancher.
### Refreshing Group Memberships
When an administrator updates the global permissions for a group, the changes take effect for individual group members after they log out of Rancher and log in again.
To make the changes take effect immediately, an administrator or cluster owner can refresh group memberships.
An administrator might also want to refresh group memberships if a user is removed from a group in the external authentication service. In that case, the refresh makes Rancher aware that the user was removed from the group.
To refresh group memberships,
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Users**.
1. Click **Refresh Group Memberships**.
**Result:** Any changes to the group members' permissions will take effect.
content/rancher/v2.6/en/admin-settings/rbac/locked-roles/_index.md
+39
View File
@@ -0,0 +1,39 @@
---
title: Locked Roles
weight: 1129
---
You can set roles to a status of `locked`. Locking roles prevent them from being assigned to users in the future.
Locked roles:
- Cannot be assigned to users that don't already have it assigned.
- Are not listed in the **Member Roles** drop-down when you are adding a user to a cluster or project.
- Do not affect users assigned the role before you lock the role. These users retain access that the role provides.
**Example:** let's say your organization creates an internal policy that users assigned to a cluster are prohibited from creating new projects. It's your job to enforce this policy.
To enforce it, before you add new users to the cluster, you should lock the following roles: `Cluster Owner`, `Cluster Member`, and `Create Projects`. Then you could create a new custom role that includes the same permissions as a __Cluster Member__, except the ability to create projects. Then, you use this new custom role when adding users to a cluster.
Roles can be locked by the following users:
- Any user assigned the `Administrator` global permission.
- Any user assigned the `Custom Users` permission, along with the `Manage Roles` role.
## Locking/Unlocking Roles
If you want to prevent a role from being assigned to users, you can set it to a status of `locked`.
You can lock roles in two contexts:
- When you're [adding a custom role]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/default-custom-roles/).
- When you editing an existing role (see below).
Cluster roles and project/namespace roles can be locked, but global roles cannot.
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Roles**.
1. Go to the **Cluster** tab or the **Project/Namespaces** tab.
1. From the role that you want to lock (or unlock), select **⋮ > Edit Config**.
1. From the **Locked** option, choose the **Yes** or **No** radio button. Then click **Save**.
content/rancher/v2.6/en/admin-settings/rke-templates/_index.md
+127
View File
@@ -0,0 +1,127 @@
---
title: RKE Templates
weight: 80
---
RKE templates are designed to allow DevOps and security teams to standardize and simplify the creation of Kubernetes clusters.
RKE is the [Rancher Kubernetes Engine,]({{<baseurl>}}/rke/latest/en/) which is the tool that Rancher uses to provision Kubernetes clusters.
With Kubernetes increasing in popularity, there is a trend toward managing a larger number of smaller clusters. When you want to create many clusters, it’s more important to manage them consistently. Multi-cluster management comes with challenges to enforcing security and add-on configurations that need to be standardized before turning clusters over to end users.
RKE templates help standardize these configurations. Regardless of whether clusters are created with the Rancher UI, the Rancher API, or an automated process, Rancher will guarantee that every cluster it provisions from an RKE template is uniform and consistent in the way it is produced.
Admins control which cluster options can be changed by end users. RKE templates can also be shared with specific users and groups, so that admins can create different RKE templates for different sets of users.
If a cluster was created with an RKE template, you can't change it to a different RKE template. You can only update the cluster to a new revision of the same template.
You can [save the configuration of an existing cluster as an RKE template.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/applying-templates/#converting-an-existing-cluster-to-use-an-rke-template) Then the cluster's settings can only be changed if the template is updated. The new template can also be used to launch new clusters.
The core features of RKE templates allow DevOps and security teams to:
- Standardize cluster configuration and ensure that Rancher-provisioned clusters are created following best practices
- Prevent less technical users from making uninformed choices when provisioning clusters
- Share different templates with different sets of users and groups
- Delegate ownership of templates to users who are trusted to make changes to them
- Control which users can create templates
- Require users to create clusters from a template
# Configurable Settings
RKE templates can be created in the Rancher UI or defined in YAML format. They can define all the same parameters that can be specified when you use Rancher to provision custom nodes or nodes from an infrastructure provider:
- Cloud provider options
- Pod security options
- Network providers
- Ingress controllers
- Network security configuration
- Network plugins
- Private registry URL and credentials
- Add-ons
- Kubernetes options, including configurations for Kubernetes components such as kube-api, kube-controller, kubelet, and services
The [add-on section](#add-ons) of an RKE template is especially powerful because it allows a wide range of customization options.
# Scope of RKE Templates
RKE templates are supported for Rancher-provisioned clusters. The templates can be used to provision custom clusters or clusters that are launched by an infrastructure provider.
RKE templates are for defining Kubernetes and Rancher settings. Node templates are responsible for configuring nodes. For tips on how to use RKE templates in conjunction with hardware, refer to [RKE Templates and Hardware]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/rke-templates-and-hardware).
RKE templates can be created from scratch to pre-define cluster configuration. They can be applied to launch new clusters, or templates can also be exported from existing running clusters.
The settings of an existing cluster can be [saved as an RKE template.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/applying-templates/#converting-an-existing-cluster-to-use-an-rke-template) This creates a new template and binds the cluster settings to the template, so that the cluster can only be upgraded if the [template is updated]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/#updating-a-template), and the cluster is upgraded to [use a newer version of the template.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/#upgrading-a-cluster-to-use-a-new-template-revision) The new template can also be used to create new clusters.
# Example Scenarios
When an organization has both basic and advanced Rancher users, administrators might want to give the advanced users more options for cluster creation, while restricting the options for basic users.
These [example scenarios]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/example-scenarios) describe how an organization could use templates to standardize cluster creation.
Some of the example scenarios include the following:
- **Enforcing templates:** Administrators might want to [enforce one or more template settings for everyone]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/example-scenarios/#enforcing-a-template-setting-for-everyone) if they want all new Rancher-provisioned clusters to have those settings.
- **Sharing different templates with different users:** Administrators might give [different templates to basic and advanced users,]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/example-scenarios/#templates-for-basic-and-advanced-users) so that basic users can have more restricted options and advanced users can use more discretion when creating clusters.
- **Updating template settings:** If an organization's security and DevOps teams decide to embed best practices into the required settings for new clusters, those best practices could change over time. If the best practices change, [a template can be updated to a new revision]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/example-scenarios/#updating-templates-and-clusters-created-with-them) and clusters created from the template can [upgrade to the new version]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/#upgrading-a-cluster-to-use-a-new-template-revision) of the template.
- **Sharing ownership of a template:** When a template owner no longer wants to maintain a template, or wants to share ownership of the template, this scenario describes how [template ownership can be shared.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/example-scenarios/#allowing-other-users-to-control-and-share-a-template)
# Template Management
When you create an RKE template, it is available in the Rancher UI from the **Cluster Management** view under **RKE Templates**. When you create a template, you become the template owner, which gives you permission to revise and share the template. You can share the RKE templates with specific users or groups, and you can also make it public.
Administrators can turn on template enforcement to require users to always use RKE templates when creating a cluster. This allows administrators to guarantee that Rancher always provisions clusters with specific settings.
RKE template updates are handled through a revision system. If you want to change or update a template, you create a new revision of the template. Then a cluster that was created with the older version of the template can be upgraded to the new template revision.
In an RKE template, settings can be restricted to what the template owner chooses, or they can be open for the end user to select the value. The difference is indicated by the **Allow User Override** toggle over each setting in the Rancher UI when the template is created.
For the settings that cannot be overridden, the end user will not be able to directly edit them. In order for a user to get different options of these settings, an RKE template owner would need to create a new revision of the RKE template, which would allow the user to upgrade and change that option.
The documents in this section explain the details of RKE template management:
- [Getting permission to create templates]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creator-permissions/)
- [Creating and revising templates]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/)
- [Enforcing template settings](./enforcement/#requiring-new-clusters-to-use-an-rke-template)
- [Overriding template settings]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/overrides/)
- [Sharing templates with cluster creators]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-templates-with-specific-users-or-groups)
- [Sharing ownership of a template]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-ownership-of-templates)
An [example YAML configuration file for a template]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/example-yaml) is provided for reference.
# Applying Templates
You can [create a cluster from a template]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/applying-templates/#creating-a-cluster-from-an-rke-template) that you created, or from a template that has been [shared with you.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/template-access-and-sharing)
If the RKE template owner creates a new revision of the template, you can [upgrade your cluster to that revision.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/applying-templates/#updating-a-cluster-created-with-an-rke-template)
RKE templates can be created from scratch to pre-define cluster configuration. They can be applied to launch new clusters, or templates can also be exported from existing running clusters.
You can [save the configuration of an existing cluster as an RKE template.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/applying-templates/#converting-an-existing-cluster-to-use-an-rke-template) Then the cluster's settings can only be changed if the template is updated.
# Standardizing Hardware
RKE templates are designed to standardize Kubernetes and Rancher settings. If you want to standardize your infrastructure as well, one option is to use RKE templates [in conjunction with other tools]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/rke-templates-and-hardware).
Another option is to use [cluster templates,](../../cluster-templates) which include node pool configuration options, but don't provide configuration enforcement. For details on the differences between cluster templates and RKE templates, see [this page.](../../cluster-templates/template-differences)
# YAML Customization
If you define an RKE template as a YAML file, you can modify this [example RKE template YAML]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/example-yaml). The YAML in the RKE template uses the same customization that Rancher uses when creating an RKE cluster, but since the YAML is located within the context of a Rancher provisioned cluster, you will need to nest the RKE template customization under the `rancher_kubernetes_engine_config` directive in the YAML.
The RKE documentation also has [annotated]({{<baseurl>}}/rke/latest/en/example-yamls/) `cluster.yml` files that you can use for reference.
For guidance on available options, refer to the RKE documentation on [cluster configuration.]({{<baseurl>}}/rke/latest/en/config-options/)
### Add-ons
The add-on section of the RKE template configuration file works the same way as the [add-on section of a cluster configuration file]({{<baseurl>}}/rke/latest/en/config-options/add-ons/).
The user-defined add-ons directive allows you to either call out and pull down Kubernetes manifests or put them inline directly. If you include these manifests as part of your RKE template, Rancher will provision those in the cluster.
Some things you could do with add-ons include:
- Install applications on the Kubernetes cluster after it starts
- Install plugins on nodes that are deployed with a Kubernetes daemonset
- Automatically set up namespaces, service accounts, or role binding
The RKE template configuration must be nested within the `rancher_kubernetes_engine_config` directive. To set add-ons, when creating the template, you will click **Edit as YAML**. Then use the `addons` directive to add a manifest, or the `addons_include` directive to set which YAML files are used for the add-ons. For more information on custom add-ons, refer to the [user-defined add-ons documentation.]({{<baseurl>}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/)
content/rancher/v2.6/en/admin-settings/rke-templates/applying-templates/_index.md
+61
View File
@@ -0,0 +1,61 @@
---
title: Applying Templates
weight: 50
---
You can create a cluster from an RKE template that you created, or from a template that has been [shared with you.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/template-access-and-sharing)
RKE templates can be applied to new clusters.
You can [save the configuration of an existing cluster as an RKE template.](#converting-an-existing-cluster-to-use-an-rke-template) Then the cluster's settings can only be changed if the template is updated.
You can't change a cluster to use a different RKE template. You can only update the cluster to a new revision of the same template.
This section covers the following topics:
- [Creating a cluster from an RKE template](#creating-a-cluster-from-an-rke-template)
- [Updating a cluster created with an RKE template](#updating-a-cluster-created-with-an-rke-template)
- [Converting an existing cluster to use an RKE template](#converting-an-existing-cluster-to-use-an-rke-template)
### Creating a Cluster from an RKE Template
To add a cluster [hosted by an infrastructure provider]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters) using an RKE template, use these steps:
1. In the upper left corner, click **☰ > Cluster Management**.
1. On the **Clusters** page, click **Create** and choose the infrastructure provider.
1. Provide the cluster name and node template details as usual.
1. To use an RKE template, under the **Cluster Options**, check the box for **Use an existing RKE template and revision**.
1. Choose an RKE template and revision from the dropdown menu.
1. Optional: You can edit any settings that the RKE template owner marked as **Allow User Override** when the template was created. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template. Then you will need to edit the cluster to upgrade it to the new revision.
1. Click **Create** to launch the cluster.
### Updating a Cluster Created with an RKE Template
When the template owner creates a template, each setting has a switch in the Rancher UI that indicates if users can override the setting.
- If the setting allows a user override, you can update these settings in the cluster by [editing the cluster.]({{<baseurl>}}/rancher/v2.6/en/cluster-admin/editing-clusters/)
- If the switch is turned off, you cannot change these settings unless the cluster owner creates a template revision that lets you override them. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template.
If a cluster was created from an RKE template, you can edit the cluster to update the cluster to a new revision of the template.
An existing cluster's settings can be [saved as an RKE template.](#converting-an-existing-cluster-to-use-an-rke-template) In that situation, you can also edit the cluster to update the cluster to a new revision of the template.
> **Note:** You can't change the cluster to use a different RKE template. You can only update the cluster to a new revision of the same template.
### Converting an Existing Cluster to Use an RKE Template
This section describes how to create an RKE template from an existing cluster.
RKE templates cannot be applied to existing clusters, except if you save an existing cluster's settings as an RKE template. This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the [template is updated,]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/#updating-a-template) and the cluster is upgraded to [use a newer version of the template.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/#upgrading-a-cluster-to-use-a-new-template-revision)
To convert an existing cluster to use an RKE template,
1. In the upper left corner, click **☰ > Cluster Management**.
1. On the **Clusters** page, go to the cluster that will be converted to use an RKE template. Click **⋮ > Save as RKE Template**.
1. Enter a name for the template in the form that appears, and click **Create**.
**Results:**
- A new RKE template is created.
- The cluster is converted to use the new template.
- New clusters can be [created from the new template.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/applying-templates/#creating-a-cluster-from-an-rke-template)
content/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/_index.md
+171
View File
@@ -0,0 +1,171 @@
---
title: Creating and Revising RKE Templates
weight: 32
---
This section describes how to manage RKE templates and revisions. You an create, share, update, and delete templates from the **Cluster Management** view under **RKE1 Configuration > RKE Templates**.
Template updates are handled through a revision system. When template owners want to change or update a template, they create a new revision of the template. Individual revisions cannot be edited. However, if you want to prevent a revision from being used to create a new cluster, you can disable it.
Template revisions can be used in two ways: to create a new cluster, or to upgrade a cluster that was created with an earlier version of the template. The template creator can choose a default revision, but when end users create a cluster, they can choose any template and any template revision that is available to them. After the cluster is created from a specific revision, it cannot change to another template, but the cluster can be upgraded to a newer available revision of the same template.
The template owner has full control over template revisions, and can create new revisions to update the template, delete or disable revisions that should not be used to create clusters, and choose which template revision is the default.
This section covers the following topics:
- [Prerequisites](#prerequisites)
- [Creating a template](#creating-a-template)
- [Updating a template](#updating-a-template)
- [Deleting a template](#deleting-a-template)
- [Creating a revision based on the default revision](#creating-a-revision-based-on-the-default-revision)
- [Creating a revision based on a cloned revision](#creating-a-revision-based-on-a-cloned-revision)
- [Disabling a template revision](#disabling-a-template-revision)
- [Re-enabling a disabled template revision](#re-enabling-a-disabled-template-revision)
- [Setting a template revision as default](#setting-a-template-revision-as-default)
- [Deleting a template revision](#deleting-a-template-revision)
- [Upgrading a cluster to use a new template revision](#upgrading-a-cluster-to-use-a-new-template-revision)
- [Exporting a running cluster to a new RKE template and revision](#exporting-a-running-cluster-to-a-new-rke-template-and-revision)
### Prerequisites
You can create RKE templates if you have the **Create RKE Templates** permission, which can be [given by an administrator.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creator-permissions)
You can revise, share, and delete a template if you are an owner of the template. For details on how to become an owner of a template, refer to [the documentation on sharing template ownership.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-ownership-of-templates)
### Creating a Template
1. In the upper left corner, click **☰ > Cluster Management**.
1. Click **RKE1 configuration > Node Templates**.
1. Click **Add Template**.
1. Provide a name for the template. An auto-generated name is already provided for the template' first version, which is created along with this template.
1. Optional: Share the template with other users or groups by [adding them as members.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-templates-with-specific-users-or-groups) You can also make the template public to share with everyone in the Rancher setup.
1. Then follow the form on screen to save the cluster configuration parameters as part of the template's revision. The revision can be marked as default for this template.
**Result:** An RKE template with one revision is configured. You can use this RKE template revision later when you [provision a Rancher-launched cluster]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters). After a cluster is managed by an RKE template, it cannot be disconnected and the option to uncheck **Use an existing RKE Template and Revision** will be unavailable.
### Updating a Template
When you update an RKE template, you are creating a revision of the existing template. Clusters that were created with an older version of the template can be updated to match the new revision.
You can't edit individual revisions. Since you can't edit individual revisions of a template, in order to prevent a revision from being used, you can [disable it.](#disabling-a-template-revision)
When new template revisions are created, clusters using an older revision of the template are unaffected.
1. In the upper left corner, click **☰ > Cluster Management**.
1. In the left navigation menu, click **RKE1 Configuration > RKE Templates**.
1. Go to the template that you want to edit and click the **⋮ > Edit**.
1. Edit the required information and click **Save**.
1. Optional: You can change the default revision of this template and also change who it is shared with.
**Result:** The template is updated. To apply it to a cluster using an older version of the template, refer to the section on [upgrading a cluster to use a new revision of a template.](#upgrading-a-cluster-to-use-a-new-template-revision)
### Deleting a Template
When you no longer use an RKE template for any of your clusters, you can delete it.
1. In the upper left corner, click **☰ > Cluster Management**.
1. Click **RKE1 configuration > RKE Templates**.
1. Go to the RKE template that you want to delete and click the **⋮ > Delete**.
1. Confirm the deletion.
**Result:** The template is deleted.
### Creating a Revision Based on the Default Revision
You can clone the default template revision and quickly update its settings rather than creating a new revision from scratch. Cloning templates saves you the hassle of re-entering the access keys and other parameters needed for cluster creation.
1. In the upper left corner, click **☰ > Cluster Management**.
1. In the left navigation menu, click **RKE1 Configuration > RKE Templates**.
1. Go to the RKE template that you want to clone and click the **⋮ > New Revision from Default**.
1. Complete the rest of the form to create a new revision.
**Result:** The RKE template revision is cloned and configured.
### Creating a Revision Based on a Cloned Revision
When creating new RKE template revisions from your user settings, you can clone an existing revision and quickly update its settings rather than creating a new one from scratch. Cloning template revisions saves you the hassle of re-entering the cluster parameters.
1. In the upper left corner, click **☰ > Cluster Management**.
1. Under **RKE1 configuration**, click **RKE Templates**.
1. Go to the template revision you want to clone. Then select **⋮ > Clone Revision**.
1. Complete the rest of the form.
**Result:** The RKE template revision is cloned and configured. You can use the RKE template revision later when you provision a cluster. Any existing cluster using this RKE template can be upgraded to this new revision.
### Disabling a Template Revision
When you no longer want an RKE template revision to be used for creating new clusters, you can disable it. A disabled revision can be re-enabled.
You can disable the revision if it is not being used by any cluster.
1. In the upper left corner, click **☰ > Cluster Management**.
1. In the left navigation menu, click **RKE1 Configuration > RKE Templates**.
1. Go to the template revision you want to disable. Then select **⋮ > Disable**.
**Result:** The RKE template revision cannot be used to create a new cluster.
### Re-enabling a Disabled Template Revision
If you decide that a disabled RKE template revision should be used to create new clusters, you can re-enable it.
1. In the upper left corner, click **☰ > Cluster Management**.
1. Under **RKE1 configuration**, click **RKE Templates**.
1. Go to the template revision you want to re-enable. Then select **⋮ > Enable**.
**Result:** The RKE template revision can be used to create a new cluster.
### Setting a Template Revision as Default
When end users create a cluster using an RKE template, they can choose which revision to create the cluster with. You can configure which revision is used by default.
To set an RKE template revision as default,
1. In the upper left corner, click **☰ > Cluster Management**.
1. In the left navigation menu, click **RKE1 Configuration > RKE templates**.
1. Go to the RKE template revision that should be default and click the **⋮ > Set as Default**.
**Result:** The RKE template revision will be used as the default option when clusters are created with the template.
### Deleting a Template Revision
You can delete all revisions of a template except for the default revision.
To permanently delete a revision,
1. In the upper left corner, click **☰ > Cluster Management**.
1. In the left navigation menu, click **RKE1 Configuration > RKE templates**.
1. Go to the RKE template revision that should be deleted and click the **⋮ > Delete**.
**Result:** The RKE template revision is deleted.
### Upgrading a Cluster to Use a New Template Revision
> This section assumes that you already have a cluster that [has an RKE template applied.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/applying-templates)
> This section also assumes that you have [updated the template that the cluster is using](#updating-a-template) so that a new template revision is available.
To upgrade a cluster to use a new template revision,
1. In the upper left corner, click **☰ > Cluster Management**.
1. Go to the cluster that you want to upgrade and click **⋮ > Edit Config**.
1. In the **Cluster Options** section, click the dropdown menu for the template revision, then select the new template revision.
1. Click **Save**.
**Result:** The cluster is upgraded to use the settings defined in the new template revision.
### Exporting a Running Cluster to a New RKE Template and Revision
You can save an existing cluster's settings as an RKE template.
This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the [template is updated,]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/#updating-a-template) and the cluster is upgraded to [use a newer version of the template.]
To convert an existing cluster to use an RKE template,
1. In the upper left corner, click **☰ > Cluster Management**.
1. Go to the cluster that will be converted to use an RKE template and **⋮ > Save as RKE Template**.
1. Enter a name for the RKE template in the form that appears, and click **Create**.
**Results:**
- A new RKE template is created.
- The cluster is converted to use the new template.
- New clusters can be [created from the new template and revision.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/applying-templates/#creating-a-cluster-from-an-rke-template)
content/rancher/v2.6/en/admin-settings/rke-templates/creator-permissions/_index.md
+58
View File
@@ -0,0 +1,58 @@
---
title: Template Creator Permissions
weight: 10
---
Administrators have the permission to create RKE templates, and only administrators can give that permission to other users.
For more information on administrator permissions, refer to the [documentation on global permissions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/).
# Giving Users Permission to Create Templates
Templates can only be created by users who have the global permission **Create RKE Templates**.
Administrators have the global permission to create templates, and only administrators can give that permission to other users.
For information on allowing users to modify existing templates, refer to [Sharing Templates.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/template-access-and-sharing)
Administrators can give users permission to create RKE templates in two ways:
- By editing the permissions of an [individual user](#allowing-a-user-to-create-templates)
- By changing the [default permissions of new users](#allowing-new-users-to-create-templates-by-default)
### Allowing a User to Create Templates
An administrator can individually grant the role **Create RKE Templates** to any existing user by following these steps:
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Users**.
1. Choose the user you want to edit and click **⋮ > Edit Config**.
1. In the **Built-in** section, check the box for **Create new RKE Cluster Templates** role along with any other roles the user should have. You may want to also check the box for **Create RKE Template Revisions**.
1. Click **Save**.
**Result:** The user has permission to create RKE templates.
### Allowing New Users to Create Templates by Default
Alternatively, the administrator can give all new users the default permission to create RKE templates by following the following steps. This will not affect the permissions of existing users.
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Roles**.
1. Go to the role named **Create new RKE Cluster Templates and click **⋮ > Edit Config**.
1. Select the option **Yes: Default role for new users**.
1. Click **Save**.
1. If you would like new users to also be able to create RKE template revisions, enable that role as default as well.
**Result:** Any new user created in this Rancher installation will be able to create RKE templates. Existing users will not get this permission.
### Revoking Permission to Create Templates
Administrators can remove a user's permission to create templates with the following steps. Note: Administrators have full control over all resources regardless of whether fine-grained permissions are selected.
1. In the upper left corner, click **☰ > Users & Authentication**.
1. In the left navigation bar, click **Users**.
1. Choose the user you want to edit permissions for and click **⋮ > Edit Config**.
1. In the **Built-in** section, un-check the box for **Create RKE Templates** and **Create RKE Template Revisions,** if applicable. In this section, you can change the user back to a standard user, or give the user a different set of permissions.
1. Click **Save**.
**Result:** The user cannot create RKE templates.
content/rancher/v2.6/en/admin-settings/rke-templates/enforcement/_index.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Template Enforcement
weight: 32
---
This section describes how template administrators can enforce templates in Rancher, restricting the ability of users to create clusters without a template.
By default, any standard user in Rancher can create clusters. But when RKE template enforcement is turned on,
- Only an administrator has the ability to create clusters without a template.
- All standard users must use an RKE template to create a new cluster.
- Standard users cannot create a cluster without using a template.
Users can only create new templates if the administrator [gives them permission.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creator-permissions/#allowing-a-user-to-create-templates)
After a cluster is created with an RKE template, the cluster creator cannot edit settings that are defined in the template. The only way to change those settings after the cluster is created is to [upgrade the cluster to a new revision]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/applying-templates/#updating-a-cluster-created-with-an-rke-template) of the same template. If cluster creators want to change template-defined settings, they would need to contact the template owner to get a new revision of the template. For details on how template revisions work, refer to the [documentation on revising templates.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/#updating-a-template)
# Requiring New Clusters to Use an RKE Template
You might want to require new clusters to use a template to ensure that any cluster launched by a [standard user]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) will use the Kubernetes and/or Rancher settings that are vetted by administrators.
To require new clusters to use an RKE template, administrators can turn on RKE template enforcement with the following steps:
1. Click **☰ > Global Settings**.
1. Go to the `cluster-template-enforcement` setting. Click **⋮ > Edit Setting**.
1. Set the value to **True** and click **Save**.
**Result:** All clusters provisioned by Rancher must use a template, unless the creator is an administrator.
# Disabling RKE Template Enforcement
To allow new clusters to be created without an RKE template, administrators can turn off RKE template enforcement with the following steps:
1. Click **☰ > Global Settings**.
1. Go to the `cluster-template-enforcement` setting. Click **⋮ > Edit Setting**.
1. Set the value to **False** and click **Save**.
**Result:** When clusters are provisioned by Rancher, they don't need to use a template.
content/rancher/v2.6/en/admin-settings/rke-templates/example-scenarios/_index.md
+71
View File
@@ -0,0 +1,71 @@
---
title: Example Scenarios
weight: 5
---
These example scenarios describe how an organization could use templates to standardize cluster creation.
- **Enforcing templates:** Administrators might want to [enforce one or more template settings for everyone](#enforcing-a-template-setting-for-everyone) if they want all new Rancher-provisioned clusters to have those settings.
- **Sharing different templates with different users:** Administrators might give [different templates to basic and advanced users,](#templates-for-basic-and-advanced-users) so that basic users have more restricted options and advanced users have more discretion when creating clusters.
- **Updating template settings:** If an organization's security and DevOps teams decide to embed best practices into the required settings for new clusters, those best practices could change over time. If the best practices change, [a template can be updated to a new revision](#updating-templates-and-clusters-created-with-them) and clusters created from the template can upgrade to the new version of the template.
- **Sharing ownership of a template:** When a template owner no longer wants to maintain a template, or wants to delegate ownership of the template, this scenario describes how [template ownership can be shared.](#allowing-other-users-to-control-and-share-a-template)
# Enforcing a Template Setting for Everyone
Let's say there is an organization in which the administrators decide that all new clusters should be created with Kubernetes version 1.14.
1. First, an administrator creates a template which specifies the Kubernetes version as 1.14 and marks all other settings as **Allow User Override**.
1. The administrator makes the template public.
1. The administrator turns on template enforcement.
**Results:**
- All Rancher users in the organization have access to the template.
- All new clusters created by [standard users]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) with this template will use Kubernetes 1.14 and they are unable to use a different Kubernetes version. By default, standard users don't have permission to create templates, so this template will be the only template they can use unless more templates are shared with them.
- All standard users must use a cluster template to create a new cluster. They cannot create a cluster without using a template.
In this way, the administrators enforce the Kubernetes version across the organization, while still allowing end users to configure everything else.
# Templates for Basic and Advanced Users
Let's say an organization has both basic and advanced users. Administrators want the basic users to be required to use a template, while the advanced users and administrators create their clusters however they want.
1. First, an administrator turns on [RKE template enforcement.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/enforcement/#requiring-new-clusters-to-use-an-rke-template) This means that every [standard user]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/global-permissions/) in Rancher will need to use an RKE template when they create a cluster.
1. The administrator then creates two templates:
- One template for basic users, with almost every option specified except for access keys
- One template for advanced users, which has most or all options has **Allow User Override** turned on
1. The administrator shares the advanced template with only the advanced users.
1. The administrator makes the template for basic users public, so the more restrictive template is an option for everyone who creates a Rancher-provisioned cluster.
**Result:** All Rancher users, except for administrators, are required to use a template when creating a cluster. Everyone has access to the restrictive template, but only advanced users have permission to use the more permissive template. The basic users are more restricted, while advanced users have more freedom when configuring their Kubernetes clusters.
# Updating Templates and Clusters Created with Them
Let's say an organization has a template that requires clusters to use Kubernetes v1.14. However, as time goes on, the administrators change their minds. They decide they want users to be able to upgrade their clusters to use newer versions of Kubernetes.
In this organization, many clusters were created with a template that requires Kubernetes v1.14. Because the template does not allow that setting to be overridden, the users who created the cluster cannot directly edit that setting.
The template owner has several options for allowing the cluster creators to upgrade Kubernetes on their clusters:
- **Specify Kubernetes v1.15 on the template:** The template owner can create a new template revision that specifies Kubernetes v1.15. Then the owner of each cluster that uses that template can upgrade their cluster to a new revision of the template. This template upgrade allows the cluster creator to upgrade Kubernetes to v1.15 on their cluster.
- **Allow any Kubernetes version on the template:** When creating a template revision, the template owner can also mark the the Kubernetes version as **Allow User Override** using the switch near that setting on the Rancher UI. This will allow clusters that upgrade to this template revision to use any version of Kubernetes.
- **Allow the latest minor Kubernetes version on the template:** The template owner can also create a template revision in which the Kubernetes version is defined as **Latest v1.14 (Allows patch version upgrades)**. This means clusters that use that revision will be able to get patch version upgrades, but major version upgrades will not be allowed.
# Allowing Other Users to Control and Share a Template
Let's say Alice is a Rancher administrator. She owns an RKE template that reflects her organization's agreed-upon best practices for creating a cluster.
Bob is an advanced user who can make informed decisions about cluster configuration. Alice trusts Bob to create new revisions of her template as the best practices get updated over time. Therefore, she decides to make Bob an owner of the template.
To share ownership of the template with Bob, Alice [adds Bob as an owner of her template.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-ownership-of-templates)
The result is that as a template owner, Bob is in charge of version control for that template. Bob can now do all of the following:
- [Revise the template]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/#updating-a-template) when the best practices change
- [Disable outdated revisions]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/#disabling-a-template-revision) of the template so that no new clusters can be created with it
- [Delete the whole template]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/#deleting-a-template) if the organization wants to go in a different direction
- [Set a certain revision as default]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising/#setting-a-template-revision-as-default) when users create a cluster with it. End users of the template will still be able to choose which revision they want to create the cluster with.
- [Share the template]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/template-access-and-sharing) with specific users, make the template available to all Rancher users, or share ownership of the template with another user.
content/rancher/v2.6/en/admin-settings/rke-templates/example-yaml/_index.md
+112
View File
@@ -0,0 +1,112 @@
---
title: Example YAML
weight: 60
---
Below is an example RKE template configuration file for reference.
The YAML in the RKE template uses the same customization that is used when you create an RKE cluster. However, since the YAML is within the context of a Rancher provisioned RKE cluster, the customization from the RKE docs needs to be nested under the `rancher_kubernetes_engine` directive.
```yaml
#
# Cluster Config
#
docker_root_dir: /var/lib/docker
enable_cluster_alerting: false
# This setting is not enforced. Clusters
# created with this sample template
# would have alerting turned off by default,
# but end users could still turn alerting
# on or off.
enable_cluster_monitoring: true
# This setting is not enforced. Clusters
# created with this sample template
# would have monitoring turned on
# by default, but end users could still
# turn monitoring on or off.
enable_network_policy: false
local_cluster_auth_endpoint:
enabled: true
#
# Rancher Config
#
rancher_kubernetes_engine_config: # Your RKE template config goes here.
addon_job_timeout: 30
authentication:
strategy: x509
ignore_docker_version: true
#
# # Currently only nginx ingress provider is supported.
# # To disable ingress controller, set `provider: none`
# # To enable ingress on specific nodes, use the node_selector, eg:
# provider: nginx
# node_selector:
# app: ingress
#
ingress:
provider: nginx
kubernetes_version: v1.15.3-rancher3-1
monitoring:
provider: metrics-server
#
# If you are using calico on AWS
#
# network:
# plugin: calico
# calico_network_provider:
# cloud_provider: aws
#
# # To specify flannel interface
#
# network:
# plugin: flannel
# flannel_network_provider:
# iface: eth1
#
# # To specify flannel interface for canal plugin
#
# network:
# plugin: canal
# canal_network_provider:
# iface: eth1
#
network:
options:
flannel_backend_type: vxlan
plugin: canal
#
# services:
# kube-api:
# service_cluster_ip_range: 10.43.0.0/16
# kube-controller:
# cluster_cidr: 10.42.0.0/16
# service_cluster_ip_range: 10.43.0.0/16
# kubelet:
# cluster_domain: cluster.local
# cluster_dns_server: 10.43.0.10
#
services:
etcd:
backup_config:
enabled: true
interval_hours: 12
retention: 6
safe_timestamp: false
creation: 12h
extra_args:
election-timeout: 5000
heartbeat-interval: 500
gid: 0
retention: 72h
snapshot: false
uid: 0
kube_api:
always_pull_images: false
pod_security_policy: false
service_node_port_range: 30000-32767
ssh_agent_auth: false
windows_prefered_cluster: false
```
content/rancher/v2.6/en/admin-settings/rke-templates/overrides/_index.md
+15
View File
@@ -0,0 +1,15 @@
---
title: Overriding Template Settings
weight: 33
---
When a user creates an RKE template, each setting in the template has a switch in the Rancher UI that indicates if users can override the setting. This switch marks those settings as **Allow User Override**.
After a cluster is created with a template, end users can't update any of the settings defined in the template unless the template owner marked them as **Allow User Override**. However, if the template is [updated to a new revision]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising) that changes the settings or allows end users to change them, the cluster can be upgraded to a new revision of the template and the changes in the new revision will be applied to the cluster.
When any parameter is set as **Allow User Override** on the RKE template, it means that end users have to fill out those fields during cluster creation and they can edit those settings afterward at any time.
The **Allow User Override** model of the RKE template is useful for situations such as:
- Administrators know that some settings will need the flexibility to be frequently updated over time
- End users will need to enter their own access keys or secret keys, for example, cloud credentials or credentials for backup snapshots
content/rancher/v2.6/en/admin-settings/rke-templates/rke-templates-and-hardware/_index.md
+70
View File
@@ -0,0 +1,70 @@
---
title: RKE Templates and Infrastructure
weight: 90
---
In Rancher, RKE templates are used to provision Kubernetes and define Rancher settings, while node templates are used to provision nodes.
Therefore, even if RKE template enforcement is turned on, the end user still has flexibility when picking the underlying hardware when creating a Rancher cluster. The end users of an RKE template can still choose an infrastructure provider and the nodes they want to use.
If you want to standardize the hardware in your clusters, use RKE templates conjunction with node templates or with a server provisioning tool such as Terraform.
### Node Templates
[Node templates]({{<baseurl>}}/rancher/v2.6/en/user-settings/node-templates) are responsible for node configuration and node provisioning in Rancher. From your user profile, you can set up node templates to define which templates are used in each of your node pools. With node pools enabled, you can make sure you have the required number of nodes in each node pool, and ensure that all nodes in the pool are the same.
### Terraform
Terraform is a server provisioning tool. It uses infrastructure-as-code that lets you create almost every aspect of your infrastructure with Terraform configuration files. It can automate the process of server provisioning in a way that is self-documenting and easy to track in version control.
This section focuses on how to use Terraform with the [Rancher 2 Terraform provider](https://www.terraform.io/docs/providers/rancher2/), which is a recommended option to standardize the hardware for your Kubernetes clusters. If you use the Rancher Terraform provider to provision hardware, and then use an RKE template to provision a Kubernetes cluster on that hardware, you can quickly create a comprehensive, production-ready cluster.
Terraform allows you to:
- Define almost any kind of infrastructure-as-code, including servers, databases, load balancers, monitoring, firewall settings, and SSL certificates
- Leverage catalog apps and multi-cluster apps
- Codify infrastructure across many platforms, including Rancher and major cloud providers
- Commit infrastructure-as-code to version control
- Easily repeat configuration and setup of infrastructure
- Incorporate infrastructure changes into standard development practices
- Prevent configuration drift, in which some servers become configured differently than others
# How Does Terraform Work?
Terraform is written in files with the extension `.tf`. It is written in HashiCorp Configuration Language, which is a declarative language that lets you define the infrastructure you want in your cluster, the cloud provider you are using, and your credentials for the provider. Then Terraform makes API calls to the provider in order to efficiently create that infrastructure.
To create a Rancher-provisioned cluster with Terraform, go to your Terraform configuration file and define the provider as Rancher 2. You can set up your Rancher 2 provider with a Rancher API key. Note: The API key has the same permissions and access level as the user it is associated with.
Then Terraform calls the Rancher API to provision your infrastructure, and Rancher calls the infrastructure provider. As an example, if you wanted to use Rancher to provision infrastructure on AWS, you would provide both your Rancher API key and your AWS credentials in the Terraform configuration file or in environment variables so that they could be used to provision the infrastructure.
When you need to make changes to your infrastructure, instead of manually updating the servers, you can make changes in the Terraform configuration files. Then those files can be committed to version control, validated, and reviewed as necessary. Then when you run `terraform apply`, the changes would be deployed.
# Tips for Working with Terraform
- There are examples of how to provide most aspects of a cluster in the [documentation for the Rancher 2 provider.](https://www.terraform.io/docs/providers/rancher2/)
- In the Terraform settings, you can install Docker Machine by using the Docker Machine node driver.
- You can also modify auth in the Terraform provider.
- You can reverse engineer how to do define a setting in Terraform by changing the setting in Rancher, then going back and checking your Terraform state file to see how it maps to the current state of your infrastructure.
- If you want to manage Kubernetes cluster settings, Rancher settings, and hardware settings all in one place, use [Terraform modules](https://github.com/rancher/terraform-modules). You can pass a cluster configuration YAML file or an RKE template configuration file to a Terraform module so that the Terraform module will create it. In that case, you could use your infrastructure-as-code to manage the version control and revision history of both your Kubernetes cluster and its underlying hardware.
# Tip for Creating CIS Benchmark Compliant Clusters
This section describes one way that you can make security and compliance-related config files standard in your clusters.
When you create a [CIS benchmark compliant cluster,]({{<baseurl>}}/rancher/v2.6/en/security/) you have an encryption config file and an audit log config file.
Your infrastructure provisioning system can write those files to disk. Then in your RKE template, you would specify where those files will be, then add your encryption config file and audit log config file as extra mounts to the `kube-api-server`.
Then you would make sure that the `kube-api-server` flag in your RKE template uses your CIS-compliant config files.
In this way, you can create flags that comply with the CIS benchmark.
# Resources
- [Terraform documentation](https://www.terraform.io/docs/)
- [Rancher2 Terraform provider documentation](https://www.terraform.io/docs/providers/rancher2/)
- [The RanchCast - Episode 1: Rancher 2 Terraform Provider](https://youtu.be/YNCq-prI8-8): In this demo, Director of Community Jason van Brackel walks through using the Rancher 2 Terraform Provider to provision nodes and create a custom cluster.
content/rancher/v2.6/en/admin-settings/rke-templates/template-access-and-sharing/_index.md
+65
View File
@@ -0,0 +1,65 @@
---
title: Access and Sharing
weight: 31
---
If you are an RKE template owner, you can share it with users or groups of users, who can then use the template to create clusters.
Since RKE templates are specifically shared with users and groups, owners can share different RKE templates with different sets of users.
When you share a template, each user can have one of two access levels:
- **Owner:** This user can update, delete, and share the templates that they own. The owner can also share the template with other users.
- **User:** These users can create clusters using the template. They can also upgrade those clusters to new revisions of the same template. When you share a template as **Make Public (read-only),** all users in your Rancher setup have the User access level for the template.
If you create a template, you automatically become an owner of that template.
If you want to delegate responsibility for updating the template, you can share ownership of the template. For details on how owners can modify templates, refer to the [documentation about revising templates.]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rke-templates/creating-and-revising)
There are several ways to share templates:
- Add users to a new RKE template during template creation
- Add users to an existing RKE template
- Make the RKE template public, sharing it with all users in the Rancher setup
- Share template ownership with users who are trusted to modify the template
### Sharing Templates with Specific Users or Groups
To allow users or groups to create clusters using your template, you can give them the basic **User** access level for the template.
1. In the upper left corner, click **☰ > Cluster Management**.
1. Under **RKE1 configuration**, click **RKE Templates**.
1. Go to the template that you want to share and click the **⋮ > Edit**.
1. In the **Share Template** section, click on **Add Member**.
1. Search in the **Name** field for the user or group you want to share the template with.
1. Choose the **User** access type.
1. Click **Save**.
**Result:** The user or group can create clusters using the template.
### Sharing Templates with All Users
1. In the upper left corner, click **☰ > Cluster Management**.
1. In the left navigation menu, click **RKE1 Configuration > RKE Templates**.
1. Go to the template that you want to share and click the **⋮ > Edit**.
1. Under **Share Template,** check the box for **Make Public (read-only)**.
1. Click **Save**.
**Result:** All users in the Rancher setup can create clusters using the template.
### Sharing Ownership of Templates
If you are the creator of a template, you might want to delegate responsibility for maintaining and updating a template to another user or group.
In that case, you can give users the Owner access type, which allows another user to update your template, delete it, or share access to it with other users.
To give Owner access to a user or group,
1. In the upper left corner, click **☰ > Cluster Management**.
1. Under **RKE1 configuration**, click **RKE Templates**.
1. Go to the RKE template that you want to share and click the **⋮ > Edit**.
1. Under **Share Template**, click on **Add Member** and search in the **Name** field for the user or group you want to share the template with.
1. In the **Access Type** field, click **Owner**.
1. Click **Save**.
**Result:** The user or group has the Owner access type, and can modify, share, or delete the template.
content/rancher/v2.6/en/api/_index.md
+52
View File
@@ -0,0 +1,52 @@
---
title: API
weight: 24
---
## How to use the API
The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it, click on your user avatar in the upper right corner. Under **API & Keys**, you can find the URL endpoint as well as create [API keys]({{<baseurl>}}/rancher/v2.6/en/user-settings/api-keys/).
## Authentication
API requests must include authentication information. Authentication is done with HTTP basic authentication using [API Keys]({{<baseurl>}}/rancher/v2.6/en/user-settings/api-keys/). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles]({{<baseurl>}}/rancher/v2.6/en/admin-settings/rbac/cluster-project-roles/) apply to these keys and restrict what clusters and projects the account can see and what actions they can take.
By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page]({{<baseurl>}}/rancher/v2.6/en/api/api-tokens).
## Making requests
The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see here](https://github.com/rancher/api-spec/blob/master/specification.md).
- Every type has a Schema which describes:
- The URL to get to the collection of this type of resources
- Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc.
- Every action that is possible on this type of resource, with their inputs and outputs (also as schemas).
- Every field that filtering is allowed on
- What HTTP verb methods are available for the collection itself, or for individual resources in the collection.
- So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and other `links` inside of the returned resources to get any other information.
- In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/<type>`) or get a specific resource (`/v3/<type>/<id>`). Anything deeper than that is subject to change in future releases.
- Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL to retrieve that information. Again you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself.
- Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP `POST` to the URL in the `actions` map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information.
- To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored.
- To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource.
- To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/<type>`).
## Filtering
Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, e.g. `field_gt=42` for "field is greater than 42". See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details.
## Sorting
Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified.
## Pagination
API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, e.g. `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not.
content/rancher/v2.6/en/api/api-tokens/_index.md
+57
View File
@@ -0,0 +1,57 @@
---
title: API Tokens
weight: 1
---
By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password.
You can deactivate API tokens by deleting them or by deactivating the user account.
### Deleting tokens
To delete a token,
1. Go to the list of all tokens in the Rancher API view at `https://<Rancher-Server-IP>/v3/tokens`.
1. Access the token you want to delete by its ID. For example, `https://<Rancher-Server-IP>/v3/tokens/kubectl-shell-user-vqkqt`
1. Click **Delete**.
Here is the complete list of tokens that are generated with `ttl=0`:
| Token | Description |
|-------|-------------|
| `kubeconfig-*` | Kubeconfig token |
| `kubectl-shell-*` | Access to `kubectl` shell in the browser |
| `agent-*` | Token for agent deployment |
| `compose-token-*` | Token for compose |
| `helm-token-*` | Token for Helm chart deployment |
| `*-pipeline*` | Pipeline token for project |
| `telemetry-*` | Telemetry token |
| `drain-node-*` | Token for drain (we use `kubectl` for drain because there is no native Kubernetes API) |
### Setting TTL on Kubeconfig Tokens
Admins can set a global TTL on Kubeconfig tokens. Once the token expires the kubectl command will require the user to authenticate to Rancher.
1. Disable the kubeconfig-generate-token setting in the Rancher API view at `https://<Rancher-Server-IP/v3/settings/kubeconfig-generate-token`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. The kubeconfig file will now provide a command to login to Rancher.
2. Edit the setting and set the value to `false`.
3. Go to setting kubeconfig-token-ttl-minutes in the Rancher API view at `https://<Rancher-Server-IP/v3/settings/kubeconfig-token-ttl-minutes`. By default, kubeconfig-token-ttl-minutes is 960 (16 hours).
4. Edit the setting and set the value to desired duration in minutes.
_**Note:**_ This value cannot exceed max-ttl of API tokens.(`https://<Rancher-Server-IP/v3/settings/auth-token-max-ttl-minutes`). `auth-token-max-ttl-minutes` is set to 1440 (24 hours) by default. `auth-token-max-ttl-minutes would default to 0 allowing tokens to never expire`.
### Token Hashing
Users can enable token hashing, where tokens will undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process, once enabled, this feature cannot be disabled. It is advisable to take backups prior to enabling and/or evaluated in a test environment first.
To enable token hashing, refer to [this section]({{<baseurl>}}/rancher/v2.6/en/installation/resources/feature-flags).
This feature will affect all tokens which include, but are not limited to, the following:
- Kubeconfig tokens
- Bearer tokens API keys/calls
- Tokens used by internal operations

Some files were not shown because too many files have changed in this diff Show More