mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-26 04:58:07 +00:00
Add v2.14 preview docs (#2212)
This commit is contained in:
Lucas Saintarbor
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: Advanced User Guides
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides"/>
|
||||
</head>
|
||||
|
||||
Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they they have encountered while working.
|
||||
|
||||
It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem.
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: Compliance Scan Guides
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/compliance-scan-guides"/>
|
||||
</head>
|
||||
|
||||
- [Install rancher-compliance](install-rancher-compliance.md)
|
||||
- [Uninstall rancher-compliance](uninstall-rancher-compliance.md)
|
||||
- [Run a Scan](run-a-scan.md)
|
||||
- [Run a Scan Periodically on a Schedule](run-a-scan-periodically-on-a-schedule.md)
|
||||
- [View Reports](view-reports.md)
|
||||
- [Enable Alerting for rancher-compliance](enable-alerting-for-rancher-compliance.md)
|
||||
- [Configure Alerts for Periodic Scan on a Schedule](configure-alerts-for-periodic-scan-on-a-schedule.md)
|
||||
- [Create a Custom Benchmark Version to Run](create-a-custom-compliance-version-to-run.md)
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Configure Alerts for Periodic Scan on a Schedule
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/compliance-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule"/>
|
||||
</head>
|
||||
|
||||
It is possible to run a ClusterScan on a schedule.
|
||||
|
||||
A scheduled scan can also specify if you should receive alerts when the scan completes.
|
||||
|
||||
Alerts are supported only for a scan that runs on a schedule.
|
||||
|
||||
The compliance application supports two types of alerts:
|
||||
|
||||
- Alert on scan completion: This alert is sent out when the scan run finishes. The alert includes details including the ClusterScan's name and the ClusterScanProfile name.
|
||||
- Alert on scan failure: This alert is sent out if there are some test failures in the scan run or if the scan is in a `Fail` state.
|
||||
|
||||
:::note Prerequisite
|
||||
|
||||
Before enabling alerts for `rancher-compliance`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.](../../../reference-guides/monitoring-v2-configuration/receivers.md)
|
||||
|
||||
While configuring the routes for `rancher-compliance` alerts, you can specify the matching using the key-value pair `job: rancher-compliance-scan`. An example route configuration is [here.](../../../reference-guides/monitoring-v2-configuration/receivers.md#example-route-config-for-compliance-scan-alerts)
|
||||
|
||||
:::
|
||||
|
||||
To configure alerts for a scan that runs on a schedule,
|
||||
|
||||
1. Please enable alerts on the `rancher-compliance` application. For more information, see [this page](../../../how-to-guides/advanced-user-guides/compliance-scan-guides/enable-alerting-for-rancher-compliance.md).
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a Compliance scan and click **Explore**.
|
||||
1. Click **compliance > Scan**.
|
||||
1. Click **Create**.
|
||||
1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the Compliance Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
|
||||
1. Choose the option **Run scan on a schedule**.
|
||||
1. Enter a valid [cron schedule expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) in the field **Schedule**.
|
||||
1. Check the boxes next to the Alert types under **Alerting**.
|
||||
1. Optional: Choose a **Retention Count**, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** The scan runs and reschedules to run according to the cron schedule provided. Alerts are sent out when the scan finishes if routes and receiver are configured under `rancher-monitoring` application.
|
||||
|
||||
A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears.
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Create a Custom Compliance Version for Running a Cluster Scan
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/compliance-scan-guides/create-a-custom-compliance-version-to-run"/>
|
||||
</head>
|
||||
|
||||
There could be some Kubernetes cluster setups that require custom configurations of the Compliance tests. For example, the path to the Kubernetes config files or certs might be different than the standard location where the upstream Compliance look for them.
|
||||
|
||||
It is now possible to create a custom compliance version for running a cluster scan using the `rancher-compliance` application.
|
||||
|
||||
For details, see [this page.](../../../integrations-in-rancher/compliance-scans/custom-benchmark.md)
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Enable Alerting for Rancher Compliance
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/compliance-scan-guides/enable-alerting-for-rancher-compliance"/>
|
||||
</head>
|
||||
|
||||
Alerts can be configured to be sent out for a scan that runs on a schedule.
|
||||
|
||||
:::note Prerequisite:
|
||||
|
||||
Before enabling alerts for `rancher-compliance`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.](../../../reference-guides/monitoring-v2-configuration/receivers.md)
|
||||
|
||||
While configuring the routes for `rancher-compliance` alerts, you can specify the matching using the key-value pair `job: rancher-compliance-scan`. An example route configuration is [here.](../../../reference-guides/monitoring-v2-configuration/receivers.md#example-route-config-for-compliance-scan-alerts)
|
||||
|
||||
:::
|
||||
|
||||
While installing or upgrading the `rancher-compliance` Helm chart, set the following flag to `true` in the `values.yaml`:
|
||||
|
||||
```yaml
|
||||
alerts:
|
||||
enabled: true
|
||||
```
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Install Rancher Compliance
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/compliance-scan-guides/install-rancher-compliance"/>
|
||||
</head>
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to install Compliance and click **Explore**.
|
||||
1. In the left navigation bar, click **Apps > Charts**.
|
||||
1. Click **Compliance**
|
||||
1. Click **Install**.
|
||||
|
||||
**Result:** The compliance scan application is deployed on the Kubernetes cluster.
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Run a Scan Periodically on a Schedule
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/compliance-scan-guides/run-a-scan-periodically-on-a-schedule"/>
|
||||
</head>
|
||||
|
||||
To run a ClusterScan on a schedule,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a Compliance scan and click **Explore**.
|
||||
1. Click **Compliance > Scan**.
|
||||
1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the Compliance Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
|
||||
1. Choose the option **Run scan on a schedule**.
|
||||
1. Enter a valid <a href="https://en.wikipedia.org/wiki/Cron#CRON_expression" target="_blank">cron schedule expression</a> in the field **Schedule**.
|
||||
1. Choose a **Retention** count, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** The scan runs and reschedules to run according to the cron schedule provided. The **Next Scan** value indicates the next time this scan will run again.
|
||||
|
||||
A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears.
|
||||
|
||||
You can also see the previous reports by choosing the report from the **Reports** dropdown on the scan detail page.
|
||||
+26
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: Run a Scan
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/compliance-scan-guides/run-a-scan"/>
|
||||
</head>
|
||||
|
||||
When a ClusterScan custom resource is created, it launches a new compliance scan on the cluster for the chosen ClusterScanProfile.
|
||||
|
||||
:::note
|
||||
|
||||
There is currently a limitation of running only one compliance scan at a time for a cluster. If you create multiple ClusterScan custom resources, they will be run one after the other by the operator, and until one scan finishes, the rest of the ClusterScan custom resources will be in the "Pending" state.
|
||||
|
||||
:::
|
||||
|
||||
To run a scan,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a compliance scan and click **Explore**.
|
||||
1. Click **Compliance > Scan**.
|
||||
1. Click **Create**.
|
||||
1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the Compliance Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** A report is generated with the scan results. To see the results, click the name of the scan that appears.
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Uninstall Rancher Compliance
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/compliance-scan-guides/uninstall-rancher-compliance"/>
|
||||
</head>
|
||||
|
||||
1. From the **Cluster Dashboard,** go to the left navigation bar and click **Apps > Installed Apps**.
|
||||
1. Go to the `compliance-operator-system` namespace and check the boxes next to `rancher-compliance-crd` and `rancher-compliance`.
|
||||
1. Click **Delete** and confirm **Delete**.
|
||||
|
||||
**Result:** The `rancher-compliance` application is uninstalled.
|
||||
+23
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: View Reports
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/compliance-scan-guides/view-reports"/>
|
||||
</head>
|
||||
|
||||
To view the generated Compliance scan reports,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to run a Compliance scan and click **Explore**.
|
||||
1. Click **Compliance > Scan**.
|
||||
1. The **Scans** page will show the generated reports. To see a detailed report, go to a scan report and click the name.
|
||||
|
||||
One can download the report from the Scans list or from the scan detail page.
|
||||
|
||||
To get the verbose version of the compliance scan results, run the following command on the cluster that was scanned. Note that the scan must be completed before this can be done.
|
||||
|
||||
```console
|
||||
export REPORT="scan-report-name"
|
||||
kubectl get clusterscanreports.compliance.cattle.io $REPORT -o json |jq ".spec.reportJSON | fromjson" | jq -r ".actual_value_map_data" | base64 -d | gunzip | jq .
|
||||
```
|
||||
+265
@@ -0,0 +1,265 @@
|
||||
---
|
||||
title: Docker Install with TLS Termination at Layer-7 NGINX Load Balancer
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer"/>
|
||||
</head>
|
||||
|
||||
For development and testing environments that have a special requirement to terminate TLS/SSL at a load balancer instead of your Rancher Server container, deploy Rancher and configure a load balancer to work with it conjunction.
|
||||
|
||||
A layer-7 load balancer can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with.
|
||||
|
||||
This install procedure walks you through deployment of Rancher using a single container, and then provides a sample configuration for a layer-7 NGINX load balancer.
|
||||
|
||||
## Requirements for OS, Docker, Hardware, and Networking
|
||||
|
||||
Make sure that your node fulfills the general [installation requirements.](../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md)
|
||||
|
||||
## Installation Outline
|
||||
|
||||
|
||||
## 1. Provision Linux Host
|
||||
|
||||
Provision a single Linux host according to our [Requirements](../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md) to launch your Rancher Server.
|
||||
|
||||
## 2. Choose an SSL Option and Install Rancher
|
||||
|
||||
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
|
||||
|
||||
:::note Do you want to..
|
||||
|
||||
- Complete an Air Gap Installation?
|
||||
- Record all transactions with the Rancher API?
|
||||
|
||||
See [Advanced Options](#advanced-options) below before continuing.
|
||||
|
||||
:::
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
<details id="option-a">
|
||||
<summary>Option A-Bring Your Own Certificate: Self-Signed</summary>
|
||||
|
||||
If you elect to use a self-signed certificate to encrypt communication, you must install the certificate on your load balancer (which you'll do later) and your Rancher container. Run the Docker command to deploy Rancher, pointing it toward your certificate.
|
||||
|
||||
:::note Prerequisites:
|
||||
|
||||
Create a self-signed certificate.
|
||||
|
||||
- The certificate files must be in PEM format.
|
||||
|
||||
:::
|
||||
|
||||
**To Install Rancher Using a Self-Signed Cert:**
|
||||
|
||||
1. While running the Docker command to deploy Rancher, point Docker toward your CA certificate file.
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-v /etc/your_certificate_directory/cacerts.pem:/etc/rancher/ssl/cacerts.pem \
|
||||
rancher/rancher:latest
|
||||
```
|
||||
|
||||
</details>
|
||||
<details id="option-b">
|
||||
<summary>Option B-Bring Your Own Certificate: Signed by Recognized CA</summary>
|
||||
|
||||
If your cluster is public facing, it's best to use a certificate signed by a recognized CA.
|
||||
|
||||
:::note Prerequisites:
|
||||
|
||||
- The certificate files must be in PEM format.
|
||||
|
||||
:::
|
||||
|
||||
**To Install Rancher Using a Cert Signed by a Recognized CA:**
|
||||
|
||||
If you use a certificate signed by a recognized CA, installing your certificate in the Rancher container isn't necessary. We do have to make sure there is no default CA certificate generated and stored, you can do this by passing the `--no-cacerts` parameter to the container.
|
||||
|
||||
1. Enter the following command.
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
rancher/rancher:latest --no-cacerts
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## 3. Configure Load Balancer
|
||||
|
||||
When using a load balancer in front of your Rancher container, there's no need for the container to redirect port communication from port 80 or port 443. By passing the header `X-Forwarded-Proto: https` header, this redirect is disabled.
|
||||
|
||||
The load balancer or proxy has to be configured to support the following:
|
||||
|
||||
- **WebSocket** connections
|
||||
- **SPDY** / **HTTP/2** protocols
|
||||
- Passing / setting the following headers:
|
||||
|
||||
| Header | Value | Description |
|
||||
|--------|-------|-------------|
|
||||
| `Host` | Hostname used to reach Rancher. | To identify the server requested by the client.
|
||||
| `X-Forwarded-Proto` | `https` | To identify the protocol that a client used to connect to the load balancer or proxy.<br /><br/>**Note:** If this header is present, `rancher/rancher` does not redirect HTTP to HTTPS.
|
||||
| `X-Forwarded-Port` | Port used to reach Rancher. | To identify the protocol that client used to connect to the load balancer or proxy.
|
||||
| `X-Forwarded-For` | IP of the client connection. | To identify the originating IP address of a client.
|
||||
### Example NGINX configuration
|
||||
|
||||
This NGINX configuration is tested on NGINX 1.14.
|
||||
|
||||
:::note
|
||||
|
||||
This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - HTTP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/).
|
||||
|
||||
:::
|
||||
|
||||
- Replace `rancher-server` with the IP address or hostname of the node running the Rancher container.
|
||||
- Replace both occurrences of `FQDN` to the DNS name for Rancher.
|
||||
- Replace `/certs/fullchain.pem` and `/certs/privkey.pem` to the location of the server certificate and the server certificate key respectively.
|
||||
|
||||
```
|
||||
worker_processes 4;
|
||||
worker_rlimit_nofile 40000;
|
||||
|
||||
events {
|
||||
worker_connections 8192;
|
||||
}
|
||||
|
||||
http {
|
||||
upstream rancher {
|
||||
server rancher-server:80;
|
||||
}
|
||||
|
||||
map $http_upgrade $connection_upgrade {
|
||||
default Upgrade;
|
||||
'' close;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name FQDN;
|
||||
ssl_certificate /certs/fullchain.pem;
|
||||
ssl_certificate_key /certs/privkey.pem;
|
||||
|
||||
location / {
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header X-Forwarded-Port $server_port;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_pass http://rancher;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection $connection_upgrade;
|
||||
# This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
|
||||
proxy_read_timeout 900s;
|
||||
proxy_buffering off;
|
||||
}
|
||||
}
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
server_name FQDN;
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
## What's Next?
|
||||
|
||||
- **Recommended:** Review Single Node [Backup](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md) and [Restore](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md). Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use.
|
||||
- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters](../new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<br/>
|
||||
|
||||
## FAQ and Troubleshooting
|
||||
|
||||
For help troubleshooting certificates, see [this section.](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md)
|
||||
|
||||
## Advanced Options
|
||||
|
||||
### API Auditing
|
||||
|
||||
If you want to record all transactions with the Rancher API, enable the [API Auditing](enable-api-audit-log.md) feature by adding the flags below into your install command.
|
||||
|
||||
-e AUDIT_LEVEL=1 \
|
||||
-e AUDIT_LOG_ENABLED=true \
|
||||
-e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \
|
||||
-e AUDIT_LOG_MAXAGE=20 \
|
||||
-e AUDIT_LOG_MAXBACKUP=20 \
|
||||
-e AUDIT_LOG_MAXSIZE=100 \
|
||||
|
||||
### Air Gap
|
||||
|
||||
If you are visiting this page to complete an [Air Gap Installation](../../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md), you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `<REGISTRY.DOMAIN.COM:PORT>` with your private registry URL in front of `rancher/rancher:latest`.
|
||||
|
||||
**Example:**
|
||||
|
||||
<REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest
|
||||
|
||||
### Persistent Data
|
||||
|
||||
Rancher uses etcd as a datastore. When Rancher is installed with Docker, the embedded etcd is being used. The persistent data is at the following path in the container: `/var/lib/rancher`.
|
||||
|
||||
You can bind mount a host volume to this location to preserve data on the host it is running on:
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-v /opt/rancher:/var/lib/rancher \
|
||||
--privileged \
|
||||
rancher/rancher:latest
|
||||
```
|
||||
|
||||
This operation requires [privileged access](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher).
|
||||
|
||||
This layer 7 NGINX configuration is tested on NGINX version 1.13 (mainline) and 1.14 (stable).
|
||||
|
||||
:::note
|
||||
|
||||
This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - TCP and UDP Load Balancer](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/).
|
||||
|
||||
:::
|
||||
|
||||
```
|
||||
upstream rancher {
|
||||
server rancher-server:80;
|
||||
}
|
||||
|
||||
map $http_upgrade $connection_upgrade {
|
||||
default Upgrade;
|
||||
'' close;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name rancher.yourdomain.com;
|
||||
ssl_certificate /etc/your_certificate_directory/fullchain.pem;
|
||||
ssl_certificate_key /etc/your_certificate_directory/privkey.pem;
|
||||
|
||||
location / {
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header X-Forwarded-Port $server_port;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_pass http://rancher;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection $connection_upgrade;
|
||||
# This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
|
||||
proxy_read_timeout 900s;
|
||||
proxy_buffering off;
|
||||
}
|
||||
}
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
server_name rancher.yourdomain.com;
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
+138
@@ -0,0 +1,138 @@
|
||||
---
|
||||
title: Configure Rancher as an OIDC provider
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/configure-oidc-provider"/>
|
||||
</head>
|
||||
|
||||
Rancher can function as a standard OpenID Connect (OIDC) provider, allowing external applications to use Rancher for authentication.
|
||||
This can be used for enabling single sign-on (SSO) across Rancher Prime components. For example, see the [documentation](https://documentation.suse.com/cloudnative/suse-observability/latest/en/setup/security/authentication/oidc.html) for configuring the OIDC provider for SUSE Observability.
|
||||
|
||||
The OIDC provider can be enabled with the `oidc-provider` feature flag. When this flag is on the following endpoints are available:
|
||||
|
||||
- `https://{rancher-url}/oidc/authorize`: This endpoint initiates the authentication flow. If a user is already logged into Rancher, it returns an authorization code. Otherwise, it redirects the user to the Rancher login page. Authorization codes and related request information are securely stored in session secrets. Codes are single-use and expire after 10 minutes.
|
||||
|
||||
- `https://{rancher-url}/oidc/token`: This endpoint exchanges an authorization code for an `id_token`, `access_token`, and `refresh_token`.
|
||||
|
||||
- `https://{rancher-url}/oidc/.well-known/openid-configuration`: This endpoint returns a JSON document containing the OIDC provider's configuration, including endpoint URLs, supported scopes, claims, and other relevant details.
|
||||
|
||||
- `https://{rancher-url}/oidc/userinfo`: This endpoint provides information about the authenticated user.
|
||||
|
||||
The OIDC provider supports the OIDC Authentication Code Flow with PKCE.
|
||||
|
||||
## Configure OIDCClient
|
||||
|
||||
An `OIDCClient` represents an external application that will be authenticating against Rancher.
|
||||
|
||||
### Programmatically
|
||||
|
||||
Create an `OIDCClient`:
|
||||
|
||||
```yaml
|
||||
apiVersion: management.cattle.io/v3
|
||||
kind: OIDCClient
|
||||
metadata:
|
||||
name: oidc-client-test
|
||||
spec:
|
||||
tokenExpirationSeconds: 600 # expiration of the id_token and access_token
|
||||
refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token
|
||||
redirectURIs:
|
||||
- "https://myredirecturl.com" # replace with your redirect url
|
||||
```
|
||||
Rancher automatically generates a client ID and client secret for each `OIDCClient`.
|
||||
Once the resource is created, Rancher populates the status field with the client id:
|
||||
|
||||
```yaml
|
||||
apiVersion: management.cattle.io/v3
|
||||
kind: OIDCClient
|
||||
metadata:
|
||||
name: oidc-client-test
|
||||
spec:
|
||||
tokenExpirationSeconds: 600 # expiration of the id_token and access_token
|
||||
refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token
|
||||
redirectURIs:
|
||||
- "https://myredirecturl.com" # replace with your redirect url
|
||||
status:
|
||||
clientID: client-xxx
|
||||
clientSecrets:
|
||||
client-secret-1:
|
||||
createdAt: "xxx"
|
||||
lastFiveCharacters: xxx
|
||||
```
|
||||
|
||||
Rancher automatically generates a Kubernetes `Secret` in the `cattle-oidc-client-secrets` namespace for each `OIDCClient` resource. The Secret's name matches the `OIDCClient` client ID.
|
||||
Initially, the `Secret` contains a single client secret.
|
||||
|
||||
To retrieve the client secret:
|
||||
|
||||
```
|
||||
kubectl get secret client-xxx -n cattle-oidc-client-secrets -o jsonpath="{.data.client-secret-1}" | base64 -d
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
secret-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
You can now use this client ID and client secret in your OIDC client application.
|
||||
|
||||
#### Managing Client Secrets
|
||||
|
||||
You can manage multiple client secrets per `OIDCClient`. Use annotations on the `OIDCClient` resource to perform secret operations:
|
||||
|
||||
- Creation: Adding the `cattle.io/oidc-client-secret-create: true` annotation triggers the creation of a new client secret.
|
||||
- Removal: Adding the `cattle.io/oidc-client-secret-remove:client-secret-1` annotation removes the specified client secrets.
|
||||
- Regeneration: Adding the `cattle.io/oidc-client-secret-regenerate:client-secret-1` annotation regenerates the specified client secrets.
|
||||
|
||||
### Rancher UI
|
||||
|
||||
Create an OIDCClient:
|
||||
|
||||
1. In the top left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, click **OIDC Apps**.
|
||||
1. Click **Add Application**. Fill out the **Create OIDC App** form.
|
||||
1. Click **Add Application**.
|
||||
|
||||
#### Managing Client Secrets
|
||||
|
||||
In the OIDC App page:
|
||||
|
||||
- Creation: Click **Add new secret**.
|
||||
- Removal: Click **⋮ > Delete**
|
||||
- Regeneration: Click **⋮ > Regenerate**
|
||||
|
||||
## Signing key
|
||||
|
||||
A default key pair for signing the `id_token`, `access_token`, and `refresh_token` tokens is created by Rancher in a `Secret` called `oidc-signing-key` in the `cattle-system` namespace. Only one key will be used for signing, but multiple public keys can be returned in the jwks endpoint in order to avoid disruption when doing a key rotation.
|
||||
|
||||
### Rotation without disruption
|
||||
|
||||
In order to create a new key pair for signing you need to manually create a new keypair and add it to the `oidc-signing-key` `Secret`
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: oidc-signing-key
|
||||
type: Opaque
|
||||
data:
|
||||
key2.pem: <base64-encoded-new-private-key>
|
||||
key1.pub: <base64-encoded-old-public-key>
|
||||
key2.pub: <base64-encoded-new-public-key>
|
||||
```
|
||||
|
||||
Rancher will sign tokens using `key2.pem`, while the JWKS endpoint will serve both `key1.pub` and `key2.pub`. This ensures a smooth
|
||||
key rotation from `key1` to `key2` without disrupting existing token verification. Note that only one private key (.pem) can be stored in the
|
||||
secret at a time, and each key pair must share the same base name, differing only by their suffix: .pem for the private key and .pub for the public key.
|
||||
|
||||
### Rotation with disruption
|
||||
|
||||
Removing the `oidc-signing-key` `Secret` will cause Rancher to regenerate the signing key on the next restart.
|
||||
|
||||
:::warning
|
||||
This will invalidate all previously issued `id_token`, `access_token`, and `refresh_token` tokens making them unusable.
|
||||
:::
|
||||
+204
@@ -0,0 +1,204 @@
|
||||
---
|
||||
title: Enabling the API Audit Log in Downstream Clusters
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-api-audit-log-in-downstream-clusters"/>
|
||||
</head>
|
||||
|
||||
Kubernetes auditing provides a security-relevant chronological set of records about a cluster. Kube-apiserver performs auditing. Requests generate an event at each stage of its execution, which is then preprocessed according to a certain policy and written to a backend. The policy determines what’s recorded and the backend persists the records.
|
||||
|
||||
You might want to configure the audit log as part of compliance with the Center for Internet Security (CIS) Kubernetes Benchmark controls.
|
||||
|
||||
For configuration details, refer to the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/).
|
||||
|
||||
|
||||
<Tabs groupId="k8s-distro">
|
||||
<TabItem value="RKE2" default>
|
||||
|
||||
### Method 1 (Recommended): Set `audit-policy-file` in `machineGlobalConfig` or `machineSelectorConfig`
|
||||
|
||||
You can set `audit-policy-file` in the configuration file using either `machineGlobalConfig` or `machineSelectorConfig`.
|
||||
|
||||
When using `machineGlobalConfig`, Rancher delivers the file to the path `/var/lib/rancher/rke2/etc/config-files/audit-policy-file` on **all nodes** (both control plane and worker nodes), and sets the proper options in the RKE2 server. This may cause unwanted worker node reconciliation when the audit policy is modified.
|
||||
|
||||
To avoid worker node reconciliation, use `machineSelectorConfig` with a label selector to target only control plane nodes. This ensures that the audit policy file is only delivered to control plane nodes.
|
||||
|
||||
Example using `machineGlobalConfig`:
|
||||
```yaml
|
||||
apiVersion: provisioning.cattle.io/v1
|
||||
kind: Cluster
|
||||
spec:
|
||||
rkeConfig:
|
||||
machineGlobalConfig:
|
||||
audit-policy-file: |
|
||||
apiVersion: audit.k8s.io/v1
|
||||
kind: Policy
|
||||
rules:
|
||||
- level: RequestResponse
|
||||
resources:
|
||||
- group: ""
|
||||
resources:
|
||||
- pods
|
||||
```
|
||||
|
||||
Example using `machineSelectorConfig` (recommended to avoid worker node reconciliation):
|
||||
```yaml
|
||||
apiVersion: provisioning.cattle.io/v1
|
||||
kind: Cluster
|
||||
spec:
|
||||
rkeConfig:
|
||||
machineSelectorConfig:
|
||||
- config:
|
||||
audit-policy-file: |
|
||||
apiVersion: audit.k8s.io/v1
|
||||
kind: Policy
|
||||
rules:
|
||||
- level: RequestResponse
|
||||
resources:
|
||||
- group: ""
|
||||
resources:
|
||||
- pods
|
||||
machineLabelSelector:
|
||||
matchLabels:
|
||||
rke.cattle.io/control-plane-role: 'true'
|
||||
```
|
||||
|
||||
### Method 2: Use the Directives, `machineSelectorFiles` and `machineGlobalConfig`
|
||||
|
||||
:::note
|
||||
|
||||
This feature is available in Rancher v2.7.2 and later.
|
||||
|
||||
:::
|
||||
|
||||
You can use `machineSelectorFiles` to deliver the audit policy file to the control plane nodes, and `machineGlobalConfig` to set the options on kube-apiserver.
|
||||
|
||||
As a prerequisite, you must create a [secret](../new-user-guides/kubernetes-resources-setup/secrets.md) or [configmap](../new-user-guides/kubernetes-resources-setup/configmaps.md) to be the source of the audit policy.
|
||||
|
||||
The secret or configmap must meet the following requirements:
|
||||
|
||||
1. It must be in the `fleet-default` namespace where the Cluster object exists.
|
||||
2. It must have the annotation `rke.cattle.io/object-authorized-for-clusters: <cluster-name1>,<cluster-name2>` which permits the target clusters to use it.
|
||||
|
||||
:::tip
|
||||
|
||||
Rancher Dashboard provides an easy-to-use form for creating the secret or configmap.
|
||||
|
||||
:::
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
data:
|
||||
audit-policy: >-
|
||||
IyBMb2cgYWxsIHJlcXVlc3RzIGF0IHRoZSBNZXRhZGF0YSBsZXZlbC4KYXBpVmVyc2lvbjogYXVkaXQuazhzLmlvL3YxCmtpbmQ6IFBvbGljeQpydWxlczoKLSBsZXZlbDogTWV0YWRhdGE=
|
||||
kind: Secret
|
||||
metadata:
|
||||
annotations:
|
||||
rke.cattle.io/object-authorized-for-clusters: cluster1
|
||||
name: <name1>
|
||||
namespace: fleet-default
|
||||
```
|
||||
|
||||
Enable and configure the audit log by editing the cluster in YAML, and utilizing the `machineSelectorFiles` and `machineGlobalConfig` directives.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
apiVersion: provisioning.cattle.io/v1
|
||||
kind: Cluster
|
||||
spec:
|
||||
rkeConfig:
|
||||
machineGlobalConfig:
|
||||
kube-apiserver-arg:
|
||||
- audit-policy-file=<customized-path>/dev-audit-policy.yaml
|
||||
- audit-log-path=<customized-path>/dev-audit.logs
|
||||
machineSelectorFiles:
|
||||
- fileSources:
|
||||
- configMap:
|
||||
name: ''
|
||||
secret:
|
||||
items:
|
||||
- key: audit-policy
|
||||
path: <customized-path>/dev-audit-policy.yaml
|
||||
name: dev-audit-policy
|
||||
machineLabelSelector:
|
||||
matchLabels:
|
||||
rke.cattle.io/control-plane-role: 'true'
|
||||
```
|
||||
|
||||
For more information about cluster configuration, refer to the [RKE2 cluster configuration reference](../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) pages.
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="K3s">
|
||||
|
||||
:::note
|
||||
|
||||
This feature is available in Rancher v2.7.2 and later.
|
||||
|
||||
:::
|
||||
|
||||
You can use `machineSelectorFiles` to deliver the audit policy file to the control plane nodes, and `machineGlobalConfig` to set the options on kube-apiserver.
|
||||
|
||||
As a prerequisite, you must create a [secret](../new-user-guides/kubernetes-resources-setup/secrets.md) or [configmap](../new-user-guides/kubernetes-resources-setup/configmaps.md) to be the source of the audit policy.
|
||||
|
||||
The secret or configmap must meet the following requirements:
|
||||
|
||||
1. It must be in the `fleet-default` namespace where the Cluster object exists.
|
||||
2. It must have the annotation `rke.cattle.io/object-authorized-for-clusters: <cluster-name1>,<cluster-name2>` which permits the target clusters to use it.
|
||||
|
||||
:::tip
|
||||
|
||||
Rancher Dashboard provides an easy-to-use form for creating the [secret](../new-user-guides/kubernetes-resources-setup/secrets.md) or [configmap](../new-user-guides/kubernetes-resources-setup/configmaps.md).
|
||||
|
||||
:::
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
data:
|
||||
audit-policy: >-
|
||||
IyBMb2cgYWxsIHJlcXVlc3RzIGF0IHRoZSBNZXRhZGF0YSBsZXZlbC4KYXBpVmVyc2lvbjogYXVkaXQuazhzLmlvL3YxCmtpbmQ6IFBvbGljeQpydWxlczoKLSBsZXZlbDogTWV0YWRhdGE=
|
||||
kind: Secret
|
||||
metadata:
|
||||
annotations:
|
||||
rke.cattle.io/object-authorized-for-clusters: cluster1
|
||||
name: <name1>
|
||||
namespace: fleet-default
|
||||
```
|
||||
|
||||
Enable and configure the audit log by editing the cluster in YAML, and utilizing the `machineSelectorFiles` and `machineGlobalConfig` directives.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
apiVersion: provisioning.cattle.io/v1
|
||||
kind: Cluster
|
||||
spec:
|
||||
rkeConfig:
|
||||
machineGlobalConfig:
|
||||
kube-apiserver-arg:
|
||||
- audit-policy-file=<customized-path>/dev-audit-policy.yaml
|
||||
- audit-log-path=<customized-path>/dev-audit.logs
|
||||
machineSelectorFiles:
|
||||
- fileSources:
|
||||
- configMap:
|
||||
name: ''
|
||||
secret:
|
||||
items:
|
||||
- key: audit-policy
|
||||
path: <customized-path>/dev-audit-policy.yaml
|
||||
name: dev-audit-policy
|
||||
machineLabelSelector:
|
||||
matchLabels:
|
||||
rke.cattle.io/control-plane-role: 'true'
|
||||
```
|
||||
|
||||
For more information about cluster configuration, refer to the [K3s cluster configuration reference](../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) pages.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
+685
@@ -0,0 +1,685 @@
|
||||
---
|
||||
title: Enabling the API Audit Log to Record System Events
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-api-audit-log"/>
|
||||
</head>
|
||||
|
||||
You can enable the API audit log to record the sequence of system events initiated by individual users. You can know what happened, when it happened, who initiated it, and what cluster it affected. When you enable this feature, all requests to the Rancher API and all responses from it are written to a log.
|
||||
|
||||
You can enable API Auditing during Rancher installation or upgrade.
|
||||
|
||||
## Enabling API Audit Log
|
||||
|
||||
The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation.
|
||||
|
||||
- [Docker Install](../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log)
|
||||
|
||||
- [Kubernetes Install](../../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md#api-audit-log)
|
||||
|
||||
## API Audit Log Options
|
||||
|
||||
The usage below defines rules about what the audit log should record and what data it should include:
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `AUDIT_LOG_ENABLED` | `false` - Disables the audit log (default setting).<br/>`true` - Enables the audit log. |
|
||||
| `AUDIT_LEVEL` | `0` - Log request and response metadata (default setting).<br/>`1` - Log request and response headers.<br/>`2` - Log request body.<br/>`3` - Log response body. Each log level is cumulative and each subsequent level logs the previous level data. Each log transaction for a request/response pair uses the same `auditID` value.<br/><br/>See [Audit Level Logging](#audit-log-levels) for a table that displays what each setting logs. |
|
||||
| `AUDIT_LOG_PATH` | Log path for Rancher Server API. Default path is `/var/log/auditlog/rancher-api-audit.log`. You can mount the log directory to host. <br/><br/>Usage Example: `AUDIT_LOG_PATH=/my/custom/path/`<br/> |
|
||||
| `AUDIT_LOG_MAXAGE` | Defined the maximum number of days to retain old audit log files. Default is 10 days. |
|
||||
| `AUDIT_LOG_MAXBACKUP` | Defines the maximum number of audit log files to retain. Default is 10. |
|
||||
| `AUDIT_LOG_MAXSIZE` | Defines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M. |
|
||||
|
||||
<br/>
|
||||
|
||||
### Audit Log Levels
|
||||
|
||||
The following table displays what parts of API transactions are logged for each [`AUDIT_LEVEL`](#api-audit-log-options) setting.
|
||||
|
||||
|
||||
| `AUDIT_LEVEL` Setting | Metadata | Request Headers | Response Headers | Request Body | Response Body |
|
||||
|--------------------------------|----------------|---------------------------|-----------------------------|----------------------|-----------------------|
|
||||
| 0 | ✓ |
|
||||
| 1 | ✓ | ✓ | ✓
|
||||
| 2 | ✓ | ✓ | ✓ | ✓
|
||||
| 3 | ✓ | ✓ | ✓ | ✓ | ✓
|
||||
|
||||
## Audit Log policies
|
||||
|
||||
Audit log policies allow end users to configure redactions using `AuditPolicy` cluster-scoped CRs in addition to the [default redactions and filters](#default-redactions--filters).
|
||||
|
||||
All configured audit log policies are additive.
|
||||
|
||||
Redaction policies for headers utilize a regular expression (regex) engine to redact headers, while a JSONPath engine is used to redact request/response headers.
|
||||
|
||||
The JSONPath engine does not support the script or filter expressions. For getting started with JSONPath expressions, a good resource to consult is [Stafan Goessner's article on JSONPath](https://goessner.net/articles/JsonPath/).
|
||||
|
||||
The structure of an audit policy CR is as follows:
|
||||
|
||||
```yaml
|
||||
apiVersion: auditlog.cattle.io/v1
|
||||
kind: AuditPolicy
|
||||
spec:
|
||||
enabled : true # true/false
|
||||
# list of API request filters
|
||||
filters:
|
||||
- action: allow # allow/deny
|
||||
# would allow logs sent to "/foo/some/endpoint" but not "/foo" or "/foobar".
|
||||
requestURI: "/foo/.*"
|
||||
# additionalRedactions allows configuration of redactions on headers using `jsonpath` expressions
|
||||
additionalRedactions:
|
||||
# redacts headers based on regex expressions
|
||||
- headers:
|
||||
- "Cache.*"
|
||||
# paths redacts information from request and response bodies based on json path expressions
|
||||
paths:
|
||||
- "$.gitCommit"
|
||||
verbosity:
|
||||
level : 0 # matches the levels in the above audit log table
|
||||
# request allows fine-grained control over which request data
|
||||
# gets included. This overrides the behaviour of the generic verbosity.level
|
||||
request:
|
||||
headers : true # true/false
|
||||
body : true # true/false
|
||||
# response allows fine-grained control over which response data
|
||||
# gets included. This overrides the behaviour of the generic verbosity.level
|
||||
response:
|
||||
headers : true # true/false
|
||||
body: true # true/false
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
The following example shows only logging requests containing `login` in the request path to the audit log path:
|
||||
|
||||
```yaml
|
||||
apiVersion: auditlog.cattle.io/v1
|
||||
kind: AuditPolicy
|
||||
metadata:
|
||||
name: filters
|
||||
spec:
|
||||
filters:
|
||||
- action: deny
|
||||
requestUri: ".*"
|
||||
- action: allow
|
||||
requestUri: ".*login.*"
|
||||
```
|
||||
|
||||
The following example shows how to redact specific fields containing `gitCommint` in request/response bodies:
|
||||
|
||||
```yaml
|
||||
apiVersion: auditlog.cattle.io/v1
|
||||
kind: AuditPolicy
|
||||
metadata:
|
||||
name: redactions
|
||||
spec:
|
||||
additionalRedactions:
|
||||
- paths:
|
||||
- "$.gitCommit"
|
||||
```
|
||||
|
||||
### Default redactions & filters
|
||||
|
||||
The audit log controller comes with default built-in redactions for common sensitive information.
|
||||
|
||||
#### Redacted headers
|
||||
|
||||
Generic headers:
|
||||
- `Cookie`
|
||||
- `Set-Cookie`
|
||||
- `X-Api-Set-Cookie-Header`
|
||||
- `Authorization`
|
||||
- `X-Api-Tunnel-Params`
|
||||
- `X-Api-Tunnel-Token`
|
||||
- `X-Api-Auth-Header`
|
||||
- `X-Amz-Security-Token`
|
||||
|
||||
|
||||
#### Redacted body fields
|
||||
|
||||
Generic body fields:
|
||||
|
||||
- `credentials`
|
||||
- `applicationSecret`
|
||||
- `oauthCredential`
|
||||
- `serviceAccountCredential`
|
||||
- `spKey`
|
||||
- `spCert`
|
||||
- `certificate`
|
||||
- `privateKey`
|
||||
- `secretsEncryptionConfig`
|
||||
- `manifestUrl`
|
||||
- `insecureWindowsNodeCommand`
|
||||
- `insecureNodeCommand`
|
||||
- `insecureCommand`
|
||||
- `command`
|
||||
- `nodeCommand`
|
||||
- `windowsNodeCommand`
|
||||
- `clientRandom`
|
||||
|
||||
Generic body regex redactor:
|
||||
- `".*([pP]assword|[Kk]ube[Cc]onfig|[Tt]oken).*"`
|
||||
|
||||
#### Cluster Driver
|
||||
|
||||
By default, any API request with fields tied to cluster drivers will have any non `public*` or `optional*` fields redacted by the audit log controller.
|
||||
|
||||
#### Redacted URIs
|
||||
|
||||
Any endpoint containing `secrets` or `configmaps` will have relevant fields stripped from both the request and response bodies. Additionally, any endpoint containing `/v3/imports/*` will have its URI redacted.
|
||||
|
||||
|
||||
## Viewing API Audit Logs
|
||||
|
||||
### Docker Install
|
||||
|
||||
Share the `AUDIT_LOG_PATH` directory (Default: `/var/log/auditlog`) with the host system. The log can be parsed by standard CLI tools or forwarded on to a log collection tool like Fluentd, Filebeat, Logstash, etc.
|
||||
|
||||
### Kubernetes Install
|
||||
|
||||
Enabling the API Audit Log with the Helm chart install will create a `rancher-audit-log` sidecar container in the Rancher pod. This container will stream the log to standard output (stdout). You can view the log as you would any container log.
|
||||
|
||||
The `rancher-audit-log` container is part of the `rancher` pod in the `cattle-system` namespace.
|
||||
|
||||
#### CLI
|
||||
|
||||
```bash
|
||||
kubectl -n cattle-system logs -f rancher-84d886bdbb-s4s69 rancher-audit-log
|
||||
```
|
||||
|
||||
#### Shipping the Audit Log
|
||||
|
||||
You can enable Rancher's built in log collection and shipping for the cluster to ship the audit and other services logs to a supported collection endpoint. See [Rancher Tools - Logging](../../integrations-in-rancher/logging/logging.md) for details.
|
||||
|
||||
## Audit Log Samples
|
||||
|
||||
After you enable auditing, each API request or response is logged by Rancher in the form of JSON. Each of the following code samples provide examples of how to identify each API transaction.
|
||||
|
||||
### Metadata Level
|
||||
|
||||
If you set your `AUDIT_LEVEL` to `0`, Rancher logs the metadata header for every API request, but neither the body nor the request and response headers. The metadata provides basic information about the API transaction, such as the transaction ID, the initiator of the transaction, the time it occurred, etc.
|
||||
|
||||
```json
|
||||
{
|
||||
"auditID": "40bd4e40-875b-4020-933e-4c4f4c4db366",
|
||||
"requestURI": "/v3/schemas",
|
||||
"user": {
|
||||
"name": "user-6j5s6",
|
||||
"group": [
|
||||
"system:authenticated",
|
||||
"system:cattle:authenticated"
|
||||
],
|
||||
"extra": {
|
||||
"principalid": [
|
||||
"local://user-6j5s6"
|
||||
],
|
||||
"requesthost": [
|
||||
"localhost:8443"
|
||||
],
|
||||
"requesttokenid": [
|
||||
"token-zs42h"
|
||||
],
|
||||
"username": [
|
||||
"admin"
|
||||
]
|
||||
}
|
||||
},
|
||||
"method": "GET",
|
||||
"remoteAddr": "127.0.0.1:58652",
|
||||
"responseCode": 200,
|
||||
"requestTimestamp": "2025-06-30T11:13:25-04:00",
|
||||
"responseTimestamp": "2025-06-30T11:13:25-04:00"
|
||||
}
|
||||
```
|
||||
|
||||
### Metadata and headers level
|
||||
|
||||
If you set your `AUDIT_LEVEL` to `1`, Rancher logs the metadata and the request and response headers for every API request.
|
||||
|
||||
```json
|
||||
{
|
||||
"auditID": "f8c83dc6-a080-4e2e-ab43-552bddf01716",
|
||||
"requestURI": "/v1/apps.deployments?page=1&pagesize=100&sort=metadata.name&filter=metadata.namespace!=p-npsl5&filter=metadata.namespace!=p-nzp6c&filter=metadata.namespace!=cattle-fleet-clusters-system&filter=metadata.namespace!=cattle-fleet-system&filter=metadata.namespace!=cattle-global-data&filter=metadata.namespace!=cattle-impersonation-system&filter=metadata.namespace!=cattle-provisioning-capi-system&filter=metadata.namespace!=cattle-system&filter=metadata.namespace!=cattle-ui-plugin-system&filter=metadata.namespace!=cluster-fleet-local-local-1a3d67d0a899&filter=metadata.namespace!=fleet-default&filter=metadata.namespace!=fleet-local&filter=metadata.namespace!=kube-node-lease&filter=metadata.namespace!=kube-public&filter=metadata.namespace!=kube-system&exclude=metadata.managedFields",
|
||||
"user": {
|
||||
"name": "user-6j5s6",
|
||||
"group": [
|
||||
"system:authenticated",
|
||||
"system:cattle:authenticated"
|
||||
],
|
||||
"extra": {
|
||||
"principalid": [
|
||||
"local://user-6j5s6"
|
||||
],
|
||||
"requesthost": [
|
||||
"localhost:8443"
|
||||
],
|
||||
"requesttokenid": [
|
||||
"token-zs42h"
|
||||
],
|
||||
"username": [
|
||||
"admin"
|
||||
]
|
||||
}
|
||||
},
|
||||
"method": "GET",
|
||||
"remoteAddr": "127.0.0.1:58833",
|
||||
"responseCode": 200,
|
||||
"requestTimestamp": "2025-06-30T11:17:04-04:00",
|
||||
"responseTimestamp": "2025-06-30T11:17:04-04:00",
|
||||
"requestHeader": {
|
||||
"Accept": [
|
||||
"application/json"
|
||||
],
|
||||
"Accept-Encoding": [
|
||||
"gzip, deflate, br, zstd"
|
||||
],
|
||||
"Accept-Language": [
|
||||
"en-US,en;q=0.5"
|
||||
],
|
||||
"Connection": [
|
||||
"keep-alive"
|
||||
],
|
||||
"Cookie": [
|
||||
"[redacted]"
|
||||
],
|
||||
"Referer": [
|
||||
"https://localhost:8443/dashboard/c/local/explorer/apps.deployment"
|
||||
],
|
||||
"Sec-Fetch-Dest": [
|
||||
"empty"
|
||||
],
|
||||
"Sec-Fetch-Mode": [
|
||||
"cors"
|
||||
],
|
||||
"Sec-Fetch-Site": [
|
||||
"same-origin"
|
||||
],
|
||||
"User-Agent": [
|
||||
"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0"
|
||||
],
|
||||
"X-Api-Csrf": [
|
||||
"fccc690cab7b0c169b3fc6527edadef3"
|
||||
]
|
||||
},
|
||||
"responseHeader": {
|
||||
"Cache-Control": [
|
||||
"no-cache, no-store, must-revalidate"
|
||||
],
|
||||
"Content-Encoding": [
|
||||
"gzip"
|
||||
],
|
||||
"Content-Type": [
|
||||
"application/json"
|
||||
],
|
||||
"Expires": [
|
||||
"Wed 24 Feb 1982 18:42:00 GMT"
|
||||
],
|
||||
"X-Api-Cattle-Auth": [
|
||||
"true"
|
||||
],
|
||||
"X-Api-Schemas": [
|
||||
"https://localhost:8443/v1/schemas"
|
||||
],
|
||||
"X-Content-Type-Options": [
|
||||
"nosniff"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Metadata, headers and Request Body Level
|
||||
|
||||
If you set your `AUDIT_LEVEL` to `2`, Rancher logs the metadata, the request and response headers and the request body for every API request.
|
||||
|
||||
The code sample below depicts an API request, with both its metadata, headers and request body.
|
||||
|
||||
```json
|
||||
{
|
||||
"auditID": "d1088a09-2a13-4450-970e-0d44bd2c49ee",
|
||||
"requestURI": "/v3/projects",
|
||||
"user": {
|
||||
"name": "user-6j5s6",
|
||||
"group": [
|
||||
"system:authenticated",
|
||||
"system:cattle:authenticated"
|
||||
],
|
||||
"extra": {
|
||||
"principalid": [
|
||||
"local://user-6j5s6"
|
||||
],
|
||||
"requesthost": [
|
||||
"localhost:8443"
|
||||
],
|
||||
"requesttokenid": [
|
||||
"token-zs42h"
|
||||
],
|
||||
"username": [
|
||||
"admin"
|
||||
]
|
||||
}
|
||||
},
|
||||
"method": "POST",
|
||||
"remoteAddr": "127.0.0.1:49966",
|
||||
"responseCode": 201,
|
||||
"requestTimestamp": "2025-06-30T12:32:13-04:00",
|
||||
"responseTimestamp": "2025-06-30T12:32:13-04:00",
|
||||
"requestHeader": {
|
||||
"Accept": [
|
||||
"application/json"
|
||||
],
|
||||
"Accept-Encoding": [
|
||||
"gzip, deflate, br, zstd"
|
||||
],
|
||||
"Accept-Language": [
|
||||
"en-US,en;q=0.5"
|
||||
],
|
||||
"Connection": [
|
||||
"keep-alive"
|
||||
],
|
||||
"Content-Length": [
|
||||
"214"
|
||||
],
|
||||
"Content-Type": [
|
||||
"application/json"
|
||||
],
|
||||
"Cookie": [
|
||||
"[redacted]"
|
||||
],
|
||||
"Impersonate-Extra-Principalid": [
|
||||
"local://user-6j5s6"
|
||||
],
|
||||
"Impersonate-Extra-Requesthost": [
|
||||
"localhost:8443"
|
||||
],
|
||||
"Impersonate-Extra-Requesttokenid": [
|
||||
"token-zs42h"
|
||||
],
|
||||
"Impersonate-Extra-Username": [
|
||||
"admin"
|
||||
],
|
||||
"Impersonate-Group": [
|
||||
"system:authenticated",
|
||||
"system:cattle:authenticated"
|
||||
],
|
||||
"Impersonate-User": [
|
||||
"user-6j5s6"
|
||||
],
|
||||
"Origin": [
|
||||
"https://localhost:8443"
|
||||
],
|
||||
"Priority": [
|
||||
"u=0"
|
||||
],
|
||||
"Referer": [
|
||||
"https://localhost:8443/dashboard/c/local/explorer/management.cattle.io.project/create"
|
||||
],
|
||||
"Sec-Fetch-Dest": [
|
||||
"empty"
|
||||
],
|
||||
"Sec-Fetch-Mode": [
|
||||
"cors"
|
||||
],
|
||||
"Sec-Fetch-Site": [
|
||||
"same-origin"
|
||||
],
|
||||
"User-Agent": [
|
||||
"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0"
|
||||
],
|
||||
"X-Api-Csrf": [
|
||||
"fccc690cab7b0c169b3fc6527edadef3"
|
||||
]
|
||||
},
|
||||
"responseHeader": {
|
||||
"Cache-Control": [
|
||||
"no-cache, no-store, must-revalidate"
|
||||
],
|
||||
"Content-Encoding": [
|
||||
"gzip"
|
||||
],
|
||||
"Content-Type": [
|
||||
"application/json"
|
||||
],
|
||||
"Expires": [
|
||||
"Wed 24 Feb 1982 18:42:00 GMT"
|
||||
],
|
||||
"X-Api-Cattle-Auth": [
|
||||
"true"
|
||||
],
|
||||
"X-Api-Schemas": [
|
||||
"https://localhost:8443/v3/project/schemas"
|
||||
],
|
||||
"X-Content-Type-Options": [
|
||||
"nosniff"
|
||||
]
|
||||
},
|
||||
"requestBody": {
|
||||
"annotations": {},
|
||||
"clusterId": "local",
|
||||
"containerDefaultResourceLimit": {},
|
||||
"creatorId": "local://user-6j5s6",
|
||||
"labels": {},
|
||||
"name": "example-project",
|
||||
"namespaceDefaultResourceQuota": {},
|
||||
"resourceQuota": {},
|
||||
"type": "project"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Metadata, Headers, Request Body and Response Body Level
|
||||
|
||||
If you set your `AUDIT_LEVEL` to `3`, Rancher logs the metadata, request and response headers and request body and response.
|
||||
|
||||
The code sample below depicts an example of an API request with that information logged.
|
||||
|
||||
```json
|
||||
{
|
||||
"auditID": "a9549a5b-4351-4bd5-adcd-12f7ec667a6b",
|
||||
"requestURI": "/v3/projects",
|
||||
"user": {
|
||||
"name": "user-6j5s6",
|
||||
"group": [
|
||||
"system:authenticated",
|
||||
"system:cattle:authenticated"
|
||||
],
|
||||
"extra": {
|
||||
"principalid": [
|
||||
"local://user-6j5s6"
|
||||
],
|
||||
"requesthost": [
|
||||
"localhost:8443"
|
||||
],
|
||||
"requesttokenid": [
|
||||
"token-zs42h"
|
||||
],
|
||||
"username": [
|
||||
"admin"
|
||||
]
|
||||
}
|
||||
},
|
||||
"method": "POST",
|
||||
"remoteAddr": "127.0.0.1:50454",
|
||||
"responseCode": 201,
|
||||
"requestTimestamp": "2025-06-30T12:42:24-04:00",
|
||||
"responseTimestamp": "2025-06-30T12:42:24-04:00",
|
||||
"requestHeader": {
|
||||
"Accept": [
|
||||
"application/json"
|
||||
],
|
||||
"Accept-Encoding": [
|
||||
"gzip, deflate, br, zstd"
|
||||
],
|
||||
"Accept-Language": [
|
||||
"en-US,en;q=0.5"
|
||||
],
|
||||
"Connection": [
|
||||
"keep-alive"
|
||||
],
|
||||
"Content-Length": [
|
||||
"214"
|
||||
],
|
||||
"Content-Type": [
|
||||
"application/json"
|
||||
],
|
||||
"Cookie": [
|
||||
"[redacted]"
|
||||
],
|
||||
"Impersonate-Extra-Principalid": [
|
||||
"local://user-6j5s6"
|
||||
],
|
||||
"Impersonate-Extra-Requesthost": [
|
||||
"localhost:8443"
|
||||
],
|
||||
"Impersonate-Extra-Requesttokenid": [
|
||||
"token-zs42h"
|
||||
],
|
||||
"Impersonate-Extra-Username": [
|
||||
"admin"
|
||||
],
|
||||
"Impersonate-Group": [
|
||||
"system:authenticated",
|
||||
"system:cattle:authenticated"
|
||||
],
|
||||
"Impersonate-User": [
|
||||
"user-6j5s6"
|
||||
],
|
||||
"Origin": [
|
||||
"https://localhost:8443"
|
||||
],
|
||||
"Priority": [
|
||||
"u=0"
|
||||
],
|
||||
"Referer": [
|
||||
"https://localhost:8443/dashboard/c/local/explorer/management.cattle.io.project/create"
|
||||
],
|
||||
"Sec-Fetch-Dest": [
|
||||
"empty"
|
||||
],
|
||||
"Sec-Fetch-Mode": [
|
||||
"cors"
|
||||
],
|
||||
"Sec-Fetch-Site": [
|
||||
"same-origin"
|
||||
],
|
||||
"User-Agent": [
|
||||
"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0"
|
||||
],
|
||||
"X-Api-Csrf": [
|
||||
"fccc690cab7b0c169b3fc6527edadef3"
|
||||
]
|
||||
},
|
||||
"responseHeader": {
|
||||
"Cache-Control": [
|
||||
"no-cache, no-store, must-revalidate"
|
||||
],
|
||||
"Content-Encoding": [
|
||||
"gzip"
|
||||
],
|
||||
"Content-Type": [
|
||||
"application/json"
|
||||
],
|
||||
"Expires": [
|
||||
"Wed 24 Feb 1982 18:42:00 GMT"
|
||||
],
|
||||
"X-Api-Cattle-Auth": [
|
||||
"true"
|
||||
],
|
||||
"X-Api-Schemas": [
|
||||
"https://localhost:8443/v3/project/schemas"
|
||||
],
|
||||
"X-Content-Type-Options": [
|
||||
"nosniff"
|
||||
]
|
||||
},
|
||||
"requestBody": {
|
||||
"annotations": {},
|
||||
"clusterId": "local",
|
||||
"containerDefaultResourceLimit": {},
|
||||
"creatorId": "local://user-6j5s6",
|
||||
"labels": {},
|
||||
"name": "example-project",
|
||||
"namespaceDefaultResourceQuota": {},
|
||||
"resourceQuota": {},
|
||||
"type": "project"
|
||||
},
|
||||
"responseBody": {
|
||||
"actions": {
|
||||
"exportYaml": "https://localhost:8443/v3/projects/local:p-qt6tq?action=exportYaml"
|
||||
},
|
||||
"annotations": {
|
||||
"authz.management.cattle.io/creator-role-bindings": "{\"required\":[\"project-owner\"]}"
|
||||
},
|
||||
"backingNamespace": "local-p-qt6tq",
|
||||
"baseType": "project",
|
||||
"clusterId": "local",
|
||||
"containerDefaultResourceLimit": {
|
||||
"type": "/v3/schemas/containerResourceLimit"
|
||||
},
|
||||
"created": "2025-06-30T16:42:24Z",
|
||||
"createdTS": 1751301744000,
|
||||
"creatorId": "user-6j5s6",
|
||||
"id": "local:p-qt6tq",
|
||||
"labels": {
|
||||
"cattle.io/creator": "norman"
|
||||
},
|
||||
"links": {
|
||||
"basicAuths": "https://localhost:8443/v3/projects/local:p-qt6tq/basicauths",
|
||||
"certificates": "https://localhost:8443/v3/projects/local:p-qt6tq/certificates",
|
||||
"configMaps": "https://localhost:8443/v3/projects/local:p-qt6tq/configmaps",
|
||||
"cronJobs": "https://localhost:8443/v3/projects/local:p-qt6tq/cronjobs",
|
||||
"daemonSets": "https://localhost:8443/v3/projects/local:p-qt6tq/daemonsets",
|
||||
"deployments": "https://localhost:8443/v3/projects/local:p-qt6tq/deployments",
|
||||
"dnsRecords": "https://localhost:8443/v3/projects/local:p-qt6tq/dnsrecords",
|
||||
"dockerCredentials": "https://localhost:8443/v3/projects/local:p-qt6tq/dockercredentials",
|
||||
"horizontalPodAutoscalers": "https://localhost:8443/v3/projects/local:p-qt6tq/horizontalpodautoscalers",
|
||||
"ingresses": "https://localhost:8443/v3/projects/local:p-qt6tq/ingresses",
|
||||
"jobs": "https://localhost:8443/v3/projects/local:p-qt6tq/jobs",
|
||||
"namespacedBasicAuths": "https://localhost:8443/v3/projects/local:p-qt6tq/namespacedbasicauths",
|
||||
"namespacedCertificates": "https://localhost:8443/v3/projects/local:p-qt6tq/namespacedcertificates",
|
||||
"namespacedDockerCredentials": "https://localhost:8443/v3/projects/local:p-qt6tq/namespaceddockercredentials",
|
||||
"namespacedSecrets": "https://localhost:8443/v3/projects/local:p-qt6tq/namespacedsecrets",
|
||||
"namespacedServiceAccountTokens": "[redacted]",
|
||||
"namespacedSshAuths": "https://localhost:8443/v3/projects/local:p-qt6tq/namespacedsshauths",
|
||||
"persistentVolumeClaims": "https://localhost:8443/v3/projects/local:p-qt6tq/persistentvolumeclaims",
|
||||
"pods": "https://localhost:8443/v3/projects/local:p-qt6tq/pods",
|
||||
"projectNetworkPolicies": "https://localhost:8443/v3/projects/local:p-qt6tq/projectnetworkpolicies",
|
||||
"projectRoleTemplateBindings": "https://localhost:8443/v3/projects/local:p-qt6tq/projectroletemplatebindings",
|
||||
"remove": "https://localhost:8443/v3/projects/local:p-qt6tq",
|
||||
"replicaSets": "https://localhost:8443/v3/projects/local:p-qt6tq/replicasets",
|
||||
"replicationControllers": "https://localhost:8443/v3/projects/local:p-qt6tq/replicationcontrollers",
|
||||
"secrets": "https://localhost:8443/v3/projects/local:p-qt6tq/secrets",
|
||||
"self": "https://localhost:8443/v3/projects/local:p-qt6tq",
|
||||
"serviceAccountTokens": "[redacted]",
|
||||
"services": "https://localhost:8443/v3/projects/local:p-qt6tq/services",
|
||||
"sshAuths": "https://localhost:8443/v3/projects/local:p-qt6tq/sshauths",
|
||||
"statefulSets": "https://localhost:8443/v3/projects/local:p-qt6tq/statefulsets",
|
||||
"subscribe": "https://localhost:8443/v3/projects/local:p-qt6tq/subscribe",
|
||||
"update": "https://localhost:8443/v3/projects/local:p-qt6tq",
|
||||
"workloads": "https://localhost:8443/v3/projects/local:p-qt6tq/workloads"
|
||||
},
|
||||
"name": "example-project",
|
||||
"namespaceDefaultResourceQuota": {
|
||||
"limit": {
|
||||
"type": "/v3/schemas/resourceQuotaLimit"
|
||||
},
|
||||
"type": "/v3/schemas/namespaceResourceQuota"
|
||||
},
|
||||
"namespaceId": null,
|
||||
"resourceQuota": {
|
||||
"limit": {
|
||||
"type": "/v3/schemas/resourceQuotaLimit"
|
||||
},
|
||||
"type": "/v3/schemas/projectResourceQuota",
|
||||
"usedLimit": {
|
||||
"type": "/v3/schemas/resourceQuotaLimit"
|
||||
}
|
||||
},
|
||||
"state": "active",
|
||||
"transitioning": "no",
|
||||
"transitioningMessage": "",
|
||||
"type": "project",
|
||||
"uuid": "b582603b-7826-4302-8393-792df2611265"
|
||||
}
|
||||
}
|
||||
```
|
||||
+78
@@ -0,0 +1,78 @@
|
||||
---
|
||||
title: Enabling Cluster Agent Scheduling Customization
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-cluster-agent-scheduling-customization"/>
|
||||
</head>
|
||||
|
||||
The `cattle-cluster-agent` allows enabling automatic deployment of a Priority Class and Pod Disruption Budget.
|
||||
|
||||
When this feature is enabled, all newly provisioned Node Driver, Custom, and Imported RKE2 and K3s clusters will automatically deploy a Priority Class and Pod Disruption Budget during the provisioning process. Existing clusters can be gradually updated with this new behavior using the [Rancher UI or by setting a specific annotation](#updating-existing-clusters) on cluster objects.
|
||||
|
||||
This feature is disabled by default.
|
||||
|
||||
## Enabling Cluster Agent Scheduling Customization
|
||||
|
||||
:::info
|
||||
Enabling or disabling this feature only impacts new clusters. Existing downstream clusters will not be automatically updated. See [_Updating Existing Clusters_](#updating-existing-clusters).
|
||||
:::
|
||||
|
||||
1. In the upper left corner, click **☰ > Global Settings**
|
||||
1. Select **Feature Flags**
|
||||
1. Find the `cluster-agent-scheduling-customization` feature and click **⋮ > Activate**
|
||||
|
||||
## Configuring the Global Settings
|
||||
|
||||
You can customize the default Priority Class (PC) and Pod Disruption Budget (PDB) by updating the `cluster-agent-default-priority-class` and `cluster-agent-default-pod-disruption-budget` global settings in the Rancher UI. Note that both the Priority Class and Pod Disruption Budget have configuration restrictions:
|
||||
|
||||
+ The `Value` set for the default PC cannot be less than negative 1 billion, or greater than 1 billion.
|
||||
+ The `PreemptionPolicy` set for the PC must be equal to `PreemptLowerPriority` or `Never`.
|
||||
+ You cannot configure the PDB `minAvailable` and `maxUnavailable` fields to both have a non-zero value.
|
||||
+ The PDB `minAvailable` must either be a non-negative whole number integer, or a non-negative whole number percent (e.g. `1` or `100%`).
|
||||
+ The PDB `maxUnavailable` must either be a non-negative whole number integer, or a non-negative whole number percent (e.g. `1` or `100%`).
|
||||
|
||||
|
||||
## Updating Existing Clusters
|
||||
|
||||
:::info
|
||||
When this feature is disabled, you cannot modify the cluster agent scheduling customization fields for existing clusters. However, you can always remove the configuration, regardless of the feature's status.
|
||||
:::
|
||||
|
||||
After enabling this feature, you can configure scheduling customization for existing clusters in two ways:
|
||||
|
||||
+ **Using the Rancher UI**
|
||||
+ Edit the desired cluster and navigate to the **Cluster Agent** tab within the **Cluster Configuration** section.
|
||||
+ Enable the `Prevent Rancher cluster agent pod eviction` checkbox.
|
||||
+ The necessary fields on the associated `clusters.provisioning.cattle.io` or `clusters.management.cattle.io` object will be automatically configured using the values set in the global settings.
|
||||
+ Save the cluster.
|
||||
+ **Using an annotation**
|
||||
+ The `provisioning.cattle.io/enable-scheduling-customization` annotation can be used to update clusters without requiring the use of the Rancher UI. This annotation will be automatically removed from the cluster after the Priority Class and Pod Disruption Budget are configured.
|
||||
+ The value of this annotation can be either `true` or `false`, to add or remove scheduling customization automatically.
|
||||
+ For Node Driver Provisioned and Custom clusters, apply this annotation on the associated `clusters.provisioning.cattle.io` object.
|
||||
+ For Imported clusters, apply the annotation on the associated `clusters.management.cattle.io` object.
|
||||
|
||||
## Applying Updated Global Settings
|
||||
|
||||
In order to prevent unexpected changes in scheduler behavior, Rancher does not update existing downstream clusters when the `cluster-agent-default-priority-class` and `cluster-agent-default-pod-disruption-budget` global settings are changed. There are two ways to update existing clusters to use the most recent global settings:
|
||||
|
||||
+ **Using the Rancher UI**
|
||||
+ When configuring a cluster, an additional checkbox will be shown in the **Cluster Agent** tab within the **Cluster Configuration** section. Checking the `Apply global settings for Priority Class and Pod Disruption Budget` checkbox will automatically update the Priority Class and Pod Disruption Budget to match the global settings once the cluster is saved.
|
||||
+ **Adjusting the cluster yaml**
|
||||
+ You may manually adjust the relevant fields in the cluster object using `kubectl` or the Rancher UI 'Edit As Yaml' feature. Scheduling customization can be found in the `spec.ClusterAgentDeploymentCustomization.SchedulingCustomization` section of the cluster object.
|
||||
+ Alternatively, the `provisioning.cattle.io/enable-scheduling-customization` annotation can be used to remove and re-add the updated scheduling customization fields set on a specific cluster.
|
||||
|
||||
## Downstream Objects
|
||||
|
||||
When this feature is enabled for a given cluster, two downstream resources will be automatically created by Rancher:
|
||||
|
||||
+ A Pod Disruption Budget will be automatically created in the `cattle-system` namespace, named `cattle-cluster-agent-pod-disruption-budget`.
|
||||
+ A Priority Class will be automatically created, named `cattle-cluster-agent-priority-class`.
|
||||
|
||||
These objects are maintained by Rancher and must not be modified or deleted. The Rancher server will automatically update these objects to match the configuration set on the Cluster object and remove them when they are no longer needed.
|
||||
|
||||
### RBAC considerations
|
||||
|
||||
Before enabling this feature on a downstream cluster, cluster administrators should assess their current RBAC configuration to prevent common access to the `cattle-cluster-agent-priority-class`. In cases where external users have access to a cluster, such as when offering clusters as a service, it is recommended to limit access to the `cattle-cluster-agent-priority-class` object to prevent changes or deletion.
|
||||
|
||||
Similar considerations do not need to be made for the `cattle-cluster-agent-pod-disruption-budget` object, as Pod Disruption Budgets are namespaced objects. Rancher will create the `cattle-cluster-agent-pod-disruption-budget` in the privileged `cattle-system` namespace.
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Continuous Delivery
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery"/>
|
||||
</head>
|
||||
|
||||
[Continuous Delivery with Fleet](../../../integrations-in-rancher/fleet/fleet.md) comes preinstalled in Rancher and can't be fully disabled. However, the Fleet feature for GitOps continuous delivery may be disabled using the `continuous-delivery` feature flag.
|
||||
|
||||
To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.](enable-experimental-features.md)
|
||||
|
||||
Environment Variable Key | Default Value | Description
|
||||
---|---|---
|
||||
`continuous-delivery` | `true` | This flag disables the GitOps continuous delivery feature of Fleet. |
|
||||
|
||||
If Fleet was disabled in Rancher v2.5.x, it will become enabled if Rancher is upgraded to v2.6.x. Only the continuous delivery part of Fleet can be disabled. When `continuous-delivery` is disabled, the `gitjob` deployment is no longer deployed into the Rancher server's local cluster, and `continuous-delivery` is not shown in the Rancher UI.
|
||||
+125
@@ -0,0 +1,125 @@
|
||||
---
|
||||
title: Enabling Experimental Features
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-experimental-features"/>
|
||||
</head>
|
||||
|
||||
Rancher includes some features that are experimental and disabled by default. You might want to enable these features, for example, if you decide that the benefits of using an [unsupported storage type](unsupported-storage-drivers.md) outweighs the risk of using an untested feature. Feature flags were introduced to allow you to try these features that are not enabled by default.
|
||||
|
||||
The features can be enabled in three ways:
|
||||
|
||||
- [Enable features when starting Rancher.](#enabling-features-when-starting-rancher) When installing Rancher with a CLI, you can use a feature flag to enable a feature by default.
|
||||
- [Enable features from the Rancher UI](#enabling-features-with-the-rancher-ui) by going to the **Settings** page.
|
||||
- [Enable features with the Rancher API](#enabling-features-with-the-rancher-api) after installing Rancher.
|
||||
|
||||
Each feature has two values:
|
||||
|
||||
- A default value, which can be configured with a flag or environment variable from the command line
|
||||
- A set value, which can be configured with the Rancher API or UI
|
||||
|
||||
If no value has been set, Rancher uses the default value.
|
||||
|
||||
Because the API sets the actual value and the command line sets the default value, that means that if you enable or disable a feature with the API or UI, it will override any value set with the command line.
|
||||
|
||||
For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect. See the [feature flags page](../../../getting-started/installation-and-upgrade/installation-references/feature-flags.md) for more information.
|
||||
|
||||
## Enabling Features when Starting Rancher
|
||||
|
||||
When you install Rancher, enable the feature you want with a feature flag. The command is different depending on whether you are installing Rancher on a single node or if you are doing a Kubernetes Installation of Rancher.
|
||||
|
||||
### Enabling Features for Kubernetes Installs
|
||||
|
||||
:::note
|
||||
|
||||
Values set from the Rancher API will override the value passed in through the command line.
|
||||
|
||||
:::
|
||||
|
||||
When installing Rancher with a Helm chart, use the `--set` option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:
|
||||
|
||||
|
||||
```
|
||||
helm install rancher rancher-latest/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set 'extraEnv[0].name=CATTLE_FEATURES'
|
||||
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true'
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
:::
|
||||
|
||||
### Enabling Features for Air Gap Installs
|
||||
|
||||
To perform an [air gap installation of Rancher](../../../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md), add a Helm chart repository and download a Helm chart, then install Rancher with Helm.
|
||||
|
||||
When you install the Helm chart, you should pass in feature flag names in a comma separated list, as in the following example:
|
||||
|
||||
```
|
||||
helm install rancher ./rancher-<VERSION>.tgz \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Use the packaged Rancher system charts
|
||||
--set 'extraEnv[0].name=CATTLE_FEATURES'
|
||||
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true'
|
||||
```
|
||||
|
||||
### Enabling Features for Docker Installs
|
||||
|
||||
When installing Rancher with Docker, use the `--features` option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:
|
||||
|
||||
```
|
||||
docker run -d -p 80:80 -p 443:443 \
|
||||
--restart=unless-stopped \
|
||||
rancher/rancher:rancher-latest \
|
||||
--features=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true
|
||||
```
|
||||
|
||||
|
||||
## Enabling Features with the Rancher UI
|
||||
|
||||
1. In the upper left corner, click **☰ > Global Settings**.
|
||||
1. Click **Feature Flags**.
|
||||
1. To enable a feature, go to the disabled feature you want to enable and click **⋮ > Activate**.
|
||||
|
||||
**Result:** The feature is enabled.
|
||||
|
||||
### Disabling Features with the Rancher UI
|
||||
|
||||
1. In the upper left corner, click **☰ > Global Settings**.
|
||||
1. Click **Feature Flags**. You will see a list of experimental features.
|
||||
1. To disable a feature, go to the enabled feature you want to disable and click **⋮ > Deactivate**.
|
||||
|
||||
**Result:** The feature is disabled.
|
||||
|
||||
## Enabling Features with the Rancher API
|
||||
|
||||
1. Go to `<RANCHER-SERVER-URL>/v3/features`.
|
||||
1. In the `data` section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the `id` field. Click the name of the feature you want to enable.
|
||||
1. In the upper left corner of the screen, under **Operations,** click **Edit**.
|
||||
1. In the **Value** drop-down menu, click **True**.
|
||||
1. Click **Show Request**.
|
||||
1. Click **Send Request**.
|
||||
1. Click **Close**.
|
||||
|
||||
**Result:** The feature is enabled.
|
||||
|
||||
### Disabling Features with the Rancher API
|
||||
|
||||
1. Go to `<RANCHER-SERVER-URL>/v3/features`.
|
||||
1. In the `data` section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the `id` field. Click the name of the feature you want to enable.
|
||||
1. In the upper left corner of the screen, under **Operations,** click **Edit**.
|
||||
1. In the **Value** drop-down menu, click **False**.
|
||||
1. Click **Show Request**.
|
||||
1. Click **Send Request**.
|
||||
1. Click **Close**.
|
||||
|
||||
**Result:** The feature is disabled.
|
||||
+36
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: UI for Istio Virtual Services and Destination Rules
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features"/>
|
||||
</head>
|
||||
|
||||
This feature enables a UI that lets you create, read, update and delete virtual services and destination rules, which are traffic management features of Istio.
|
||||
|
||||
> **Prerequisite:** Turning on this feature does not enable Istio. A cluster administrator needs to [enable Istio for the cluster](../istio-setup-guide/istio-setup-guide.md) in order to use the feature.
|
||||
|
||||
To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.](enable-experimental-features.md)
|
||||
|
||||
Environment Variable Key | Default Value | Status | Available as of
|
||||
---|---|---|---
|
||||
`istio-virtual-service-ui` |`false` | Experimental | v2.3.0
|
||||
`istio-virtual-service-ui` | `true` | GA | v2.3.2
|
||||
|
||||
## About this Feature
|
||||
|
||||
A central advantage of Istio's traffic management features is that they allow dynamic request routing, which is useful for canary deployments, blue/green deployments, or A/B testing.
|
||||
|
||||
When enabled, this feature turns on a page that lets you configure some traffic management features of Istio using the Rancher UI. Without this feature, you need to use `kubectl` to manage traffic with Istio.
|
||||
|
||||
The feature enables two UI tabs: one tab for **Virtual Services** and another for **Destination Rules**.
|
||||
|
||||
- **Virtual services** intercept and direct traffic to your Kubernetes services, allowing you to direct percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed. For details, refer to the [Istio documentation.](https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service/)
|
||||
- **Destination rules** serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred. For details, refer to the [Istio documentation.](https://istio.io/docs/reference/config/networking/v1alpha3/destination-rule)
|
||||
|
||||
To see these tabs,
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster where Istio is installed and click **Explore**.
|
||||
1. In the left navigation bar, click **Istio**.
|
||||
1. You will see tabs for **Kiali** and **Jaeger**. From the left navigation bar, you can view and configure **Virtual Services** and **Destination Rules**.
|
||||
+27
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: "Running on ARM64 Mixed Architecture (Experimental)"
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-experimental-features/rancher-on-arm64"/>
|
||||
</head>
|
||||
|
||||
:::caution
|
||||
|
||||
Running on an ARM64 mixed architecture platform is currently an experimental feature and is not yet officially supported in Rancher. Therefore, we do not recommend using ARM64 mixed architecture based nodes in a production environment.
|
||||
|
||||
:::
|
||||
|
||||
The following options are available when using an ARM64 platform:
|
||||
|
||||
- Create custom cluster and adding ARM64 based node(s)
|
||||
- Kubernetes cluster version must be 1.12 or higher
|
||||
- Importing clusters that contain ARM64 based nodes
|
||||
- Kubernetes cluster version must be 1.12 or higher
|
||||
|
||||
Depending on your cluster provisioning refer to [RKE2 cluster configuration options](../../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) or [K3s cluster configuration options](../../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) for more information.
|
||||
|
||||
The following features are not tested:
|
||||
|
||||
- Monitoring, alerts, notifiers, pipelines and logging
|
||||
- Launching apps from the catalog
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: RoleTemplate Aggregation
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-experimental-features/role-template-aggregation"/>
|
||||
</head>
|
||||
|
||||
:::caution
|
||||
RoleTemplate aggregation is an experimental feature in v2.13 that changes the RBAC architecture used for RoleTemplates, ClusterRoleTemplateBindings and ProjectRoleTemplateBindings. **It is not supported for production environments**. Breaking changes may occur between v2.13 and v2.14.
|
||||
:::
|
||||
|
||||
RoleTemplate aggregation implements RoleTemplates, ClusterRoleTemplateBindings and ProjectRoleTemplateBindings using the Kubernetes feature [Aggregated ClusterRoles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles). The new architecture results in a net reduction in RBAC objects (Roles, RoleBindings, ClusterRoles and ClusterRoleBindings) both in the Rancher cluster and the downstream clusters.
|
||||
|
||||
For more information on how the feature can improve scalability and performance, please see the [Rancher Blog post](https://www.suse.com/c/rancher_blog/fewer-bindings-more-power-ranchers-rbac-boost-for-enhanced-performance-and-scalability/).
|
||||
|
||||
| Environment Variable Key | Default Value | Description |
|
||||
| --- | --- | --- |
|
||||
| `aggregated-roletemplates` | `false` | [Beta] Make RoleTemplates use aggregation for generated RBAC roles. |
|
||||
|
||||
The value of this feature flag is locked on installation, which shows up in the UI as a lock symbol beside the feature flag. That means the feature can only be set on the first ever installation of Rancher. After that, attempting to modify the value will be denied.
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Allowing Unsupported Storage Drivers
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers"/>
|
||||
</head>
|
||||
|
||||
This feature allows you to use types for storage providers and provisioners that are not enabled by default.
|
||||
|
||||
To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.](enable-experimental-features.md)
|
||||
|
||||
Environment Variable Key | Default Value | Description
|
||||
---|---|---
|
||||
`unsupported-storage-drivers` | `false` | This feature enables types for storage providers and provisioners that are not enabled by default.
|
||||
|
||||
### Types for Persistent Volume Plugins that are Enabled by Default
|
||||
Below is a list of storage types for persistent volume plugins that are enabled by default. When enabling this feature flag, any persistent volume plugins that are not on this list are considered experimental and unsupported:
|
||||
|
||||
Name | Plugin
|
||||
--------|----------
|
||||
Amazon EBS Disk | `aws-ebs`
|
||||
AzureFile | `azure-file`
|
||||
AzureDisk | `azure-disk`
|
||||
Google Persistent Disk | `gce-pd`
|
||||
Longhorn | `flex-volume-longhorn`
|
||||
VMware vSphere Volume | `vsphere-volume`
|
||||
Local | `local`
|
||||
Network File System | `nfs`
|
||||
hostPath | `host-path`
|
||||
|
||||
### Types for StorageClass that are Enabled by Default
|
||||
Below is a list of storage types for a StorageClass that are enabled by default. When enabling this feature flag, any persistent volume plugins that are not on this list are considered experimental and unsupported:
|
||||
|
||||
Name | Plugin
|
||||
--------|--------
|
||||
Amazon EBS Disk | `aws-ebs`
|
||||
AzureFile | `azure-file`
|
||||
AzureDisk | `azure-disk`
|
||||
Google Persistent Disk | `gce-pd`
|
||||
Longhorn | `flex-volume-longhorn`
|
||||
VMware vSphere Volume | `vsphere-volume`
|
||||
Local | `local`
|
||||
+62
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: Enabling User Retention
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-user-retention"/>
|
||||
</head>
|
||||
|
||||
In Rancher v2.8.5 and later, you can enable user retention to automatically disable or delete inactive user accounts after a configurable time period.
|
||||
|
||||
The user retention feature is off by default.
|
||||
|
||||
## Enabling User Retention with kubectl
|
||||
|
||||
To enable user retention, you must set `user-retention-cron`. You must also set at least one of `disable-inactive-user-after` or `delete-inactive-user-after`. You can use `kubectl edit setting <name-of-setting>` to open your editor of choice and set these values.
|
||||
|
||||
## Configuring Rancher to Delete Users, Disable Users, or Combine Operations
|
||||
|
||||
Rancher uses two global user retention settings to determine if and when users are disabled or deleted after a certain period of inactivity. Disabled accounts must be re-enabled before users can log in again. If an account is deleted without being disabled, users may be able to log in through external authentication and the deleted account will be recreated.
|
||||
|
||||
The global settings, `disable-inactive-user-after` and `delete-inactive-user-after`, do not block one another from running.
|
||||
|
||||
For example, you can set both operations to run. If you give `disable-inactive-user-after` a shorter duration than `delete-inactive-user-after`, the user retention process disables inactive accounts before deleting them.
|
||||
|
||||
You can also edit some user retention settings on a specific user's `UserAttribute`. Setting these values overrides the global settings. See [User-specific User Retention Overrides](#user-specific-user-retention-overrides) for more details.
|
||||
|
||||
### Required User Retention Settings
|
||||
|
||||
The following are global settings:
|
||||
|
||||
- `user-retention-cron`: Describes how often the user retention process runs. The value is a cron expression (for example, `0 * * * *` for every hour).
|
||||
- `disable-inactive-user-after`: The amount of time that a user account can be inactive before the process disables an account. Disabling an account forces the user to request that an administrator re-enable the account before they can log in to use it. Values are expressed in [time.Duration units](https://pkg.go.dev/time#ParseDuration) (for example, `720h` for 720 hours or 30 days). The value must be greater than `auth-user-session-ttl-minutes`, which is `16h` by default. If the value is not set, set to the empty string, or is equal to 0, the process does not disable any inactive accounts.
|
||||
- `delete-inactive-user-after`: The amount of time that a user account can be inactive before the process deletes the account. Values are expressed in time.Duration units (for example, `720h` for 720 hours or 30 days). The value must be greater than `auth-user-session-ttl-minutes`, which is `16h` by default. The value should be greater than `336h` (14 days), otherwise it is rejected by the Rancher webhook. If you need the value to be lower than 14 days, you can [bypass the webhook](../../reference-guides/rancher-webhook.md#bypassing-the-webhook). If the value is not set, set to the empty string, or is equal to 0, the process does not delete any inactive accounts.
|
||||
|
||||
### Optional User Retention Settings
|
||||
|
||||
The following are global settings:
|
||||
|
||||
- `user-retention-dry-run`: If set to `true`, the user retention process runs without actually deleting or disabling any user accounts. This can help test user retention behavior before allowing the process to disable or delete user accounts in a production environment.
|
||||
- `user-last-login-default`: If a user does not have `UserAttribute.LastLogin` set on their account, this setting is used instead. The value is expressed as an [RFC 3339 date-time](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) truncated to the last second; for example, `2023-03-01T00:00:00Z`. If the value is set to the empty string or is equal to 0, this setting is not used.
|
||||
|
||||
#### User-specific User Retention Overrides
|
||||
|
||||
The following are user-specific overrides to the global settings for special cases. These settings are applied by editing the `UserAttribute` associated with a given account:
|
||||
|
||||
```
|
||||
kubectl edit userattribute <user-name>
|
||||
```
|
||||
|
||||
- `disableAfter`: The user-specific override for `disable-inactive-user-after`. The value is expressed in [time.Duration units](https://pkg.go.dev/time#ParseDuration) and truncated to the second. If the value is set to `0s` then the account won't be subject to disabling.
|
||||
- `deleteAfter`: The user-specific override for `delete-inactive-user-after`. The value is expressed in [time.Duration units](https://pkg.go.dev/time#ParseDuration) and truncated to the second. If the value is set to `0s` then the account won't be subject to deletion.
|
||||
|
||||
## Viewing User Retention Settings in the Rancher UI
|
||||
|
||||
You can see which user retention settings are applied to which users.
|
||||
|
||||
1. In the upper left corner, click **☰ > Users & Authentication**.
|
||||
1. In the left navigation menu, select **Users**.
|
||||
|
||||
The **Disable After** and **Delete After** columns for each user account indicate how long the account can be inactive before it is disabled or deleted from Rancher. There is also a **Last Login** column roughly indicating when the account was last active.
|
||||
|
||||
The same information is available if you click a user's name in the **Users** table and select the **Detail** tab.
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Enable Istio in the Cluster
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster"/>
|
||||
</head>
|
||||
|
||||
:::warning
|
||||
|
||||
[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions).
|
||||
|
||||
Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043).
|
||||
|
||||
:::
|
||||
|
||||
:::note Prerequisites:
|
||||
|
||||
- Only a user with the `cluster-admin` [Kubernetes default role](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) assigned can configure and install Istio in a Kubernetes cluster.
|
||||
- To install Istio on an RKE2 cluster, additional steps are required. For details, see [this section.](../../../integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.md)
|
||||
- To install Istio in a cluster where project network isolation is enabled, additional steps are required. For details, see [this section.](../../../integrations-in-rancher/istio/configuration-options/project-network-isolation.md)
|
||||
|
||||
:::
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the where you want to enable Istio and click **Explore**.
|
||||
1. Click **Apps**.
|
||||
1. Click **Charts**.
|
||||
1. Click **Istio**.
|
||||
1. If you have not already installed your own monitoring app, you will be prompted to install the rancher-monitoring app. Optional: Set your Selector or Scrape config options on rancher-monitoring app install.
|
||||
1. Optional: Configure member access and [resource limits](../../../integrations-in-rancher/istio/cpu-and-memory-allocations.md) for the Istio components. Ensure you have enough resources on your worker nodes to enable Istio.
|
||||
1. Optional: Make additional configuration changes to values.yaml if needed.
|
||||
1. Optional: Add further resources or configuration via the [overlay file](../../../integrations-in-rancher/istio/configuration-options/configuration-options.md#overlay-file).
|
||||
1. Click **Install**.
|
||||
|
||||
**Result:** Istio is installed at the cluster level.
|
||||
|
||||
## Additional Config Options
|
||||
|
||||
For more information on configuring Istio, refer to the [configuration reference.](../../../integrations-in-rancher/istio/configuration-options/configuration-options.md)
|
||||
+64
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Enable Istio in a Namespace
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace"/>
|
||||
</head>
|
||||
|
||||
:::warning
|
||||
|
||||
[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions).
|
||||
|
||||
Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043).
|
||||
|
||||
:::
|
||||
|
||||
You will need to manually enable Istio in each namespace that you want to be tracked or controlled by Istio. When Istio is enabled in a namespace, the Envoy sidecar proxy will be automatically injected into all new workloads that are deployed in the namespace.
|
||||
|
||||
This namespace setting will only affect new workloads in the namespace. Any preexisting workloads will need to be re-deployed to leverage the sidecar auto injection.
|
||||
|
||||
:::note Prerequisite:
|
||||
|
||||
To enable Istio in a namespace, the cluster must have Istio installed.
|
||||
|
||||
:::
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. Click **Cluster > Projects/Namespaces**.
|
||||
1. Go to the namespace where you want to enable Istio and click **⋮ > Enable Istio Auto Injection**. Alternately, click the namespace, and then on the namespace detail page, click **⋮ > Enable Istio Auto Injection**.
|
||||
|
||||
**Result:** The namespace now has the label `istio-injection=enabled`. All new workloads deployed in this namespace will have the Istio sidecar injected by default.
|
||||
|
||||
### Verifying that Automatic Istio Sidecar Injection is Enabled
|
||||
|
||||
To verify that Istio is enabled, deploy a hello-world workload in the namespace. Go to the workload and click the pod name. In the **Containers** section, you should see the `istio-proxy` container.
|
||||
|
||||
### Excluding Workloads from Being Injected with the Istio Sidecar
|
||||
|
||||
If you need to exclude a workload from getting injected with the Istio sidecar, use the following annotation on the workload:
|
||||
|
||||
```
|
||||
sidecar.istio.io/inject: “false”
|
||||
```
|
||||
|
||||
To add the annotation to a workload,
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. Click **Workload**.
|
||||
1. Go to the workload that should not have the sidecar and edit as yaml
|
||||
1. Add the following key, value `sidecar.istio.io/inject: false` as an annotation on the workload
|
||||
1. Click **Save**.
|
||||
|
||||
**Result:** The Istio sidecar will not be injected into the workload.
|
||||
|
||||
:::note
|
||||
|
||||
If you are having issues with a Job you deployed not completing, you will need to add this annotation to your pod using the provided steps. Since Istio Sidecars run indefinitely, a Job cannot be considered complete even after its task has completed.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
### [Next: Add Deployments with the Istio Sidecar ](use-istio-sidecar.md)
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Generate and View Traffic from Istio
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic"/>
|
||||
</head>
|
||||
|
||||
:::warning
|
||||
|
||||
[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions).
|
||||
|
||||
Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043).
|
||||
|
||||
:::
|
||||
|
||||
## The Kiali Traffic Graph
|
||||
|
||||
The Istio overview page provides a link to the Kiali dashboard. From the Kiali dashboard, you can view graphs for each namespace. The Kiali graph provides a powerful way to visualize the topology of your Istio service mesh. It shows you which services communicate with each other.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To enable traffic to show up in the graph, ensure that you have Prometheus installed in the cluster. `Rancher-istio` installs Kiali, and configures it by default to work with the `rancher-monitoring` chart. You can use `rancher-monitoring` or install your own monitoring solution.
|
||||
|
||||
Additionally, for Istio installations version `103.1.0+up1.19.6` and later, Kiali uses a token value for its authentication strategy. If you are trying to generate or retrieve the token (e.g. for login), note that the name of the Kiali service account in Rancher is `kiali`. For more information, refer to the [Kiali token authentication FAQ](https://kiali.io/docs/faq/authentication/).
|
||||
|
||||
Optional: You can configure which namespaces data scraping occurs in by setting the Helm chart options described in [Selectors & Scrape Configs](../../../integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.md).
|
||||
|
||||
## Traffic Visualization
|
||||
|
||||
To see the traffic graph follow the steps below:
|
||||
|
||||
1. In the cluster where Istio is installed, click **Istio** in the left navigation bar.
|
||||
1. Click the **Kiali** link.
|
||||
1. Click on **Graph** in the side nav.
|
||||
1. Change the namespace in the **Namespace** dropdown to view the traffic for each namespace.
|
||||
|
||||
If you refresh the URL to the BookInfo app several times, you should be able to see green arrows on the Kiali graph showing traffic to `v1` and `v3` of the `reviews` service. The control panel on the right side of the graph lets you configure details including how many minutes of the most recent traffic should be shown on the graph.
|
||||
|
||||
For additional tools and visualizations, you can go to Grafana, and Prometheus dashboards from the **Monitoring** **Overview** page
|
||||
+42
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: Istio Setup Guides
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/istio-setup-guide"/>
|
||||
</head>
|
||||
|
||||
:::warning
|
||||
|
||||
[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions).
|
||||
|
||||
Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043).
|
||||
|
||||
:::
|
||||
|
||||
This section describes how to enable Istio and start using it in your projects.
|
||||
|
||||
If you use Istio for traffic management, you will need to allow external traffic to the cluster. In that case, you will need to follow all of the steps below.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This guide assumes you have already [installed Rancher,](../../../getting-started/installation-and-upgrade/installation-and-upgrade.md) and you have already [provisioned a separate Kubernetes cluster](../../new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) on which you will install Istio.
|
||||
|
||||
The nodes in your cluster must meet the [CPU and memory requirements.](../../../integrations-in-rancher/istio/cpu-and-memory-allocations.md)
|
||||
|
||||
The workloads and services that you want to be controlled by Istio must meet [Istio's requirements.](https://istio.io/docs/setup/additional-setup/requirements/)
|
||||
|
||||
## Install
|
||||
|
||||
:::tip Quick Setup Tip:
|
||||
|
||||
If you don't need external traffic to reach Istio, and you just want to set up Istio for monitoring and tracing traffic within the cluster, skip the steps for [setting up the Istio gateway](set-up-istio-gateway.md) and [setting up Istio's components for traffic management.](set-up-traffic-management.md)
|
||||
|
||||
:::
|
||||
|
||||
1. [Enable Istio in the cluster.](enable-istio-in-cluster.md)
|
||||
1. [Enable Istio in all the namespaces where you want to use it.](enable-istio-in-namespace.md)
|
||||
1. [Add deployments and services that have the Istio sidecar injected.](use-istio-sidecar.md)
|
||||
1. [Set up the Istio gateway. ](set-up-istio-gateway.md)
|
||||
1. [Set up Istio's components for traffic management.](set-up-traffic-management.md)
|
||||
1. [Generate traffic and see Istio in action.](generate-and-view-traffic.md)
|
||||
+158
@@ -0,0 +1,158 @@
|
||||
---
|
||||
title: Set up the Istio Gateway
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway"/>
|
||||
</head>
|
||||
|
||||
:::warning
|
||||
|
||||
[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions).
|
||||
|
||||
Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043).
|
||||
|
||||
:::
|
||||
|
||||
The gateway to each cluster can have its own port or load balancer, which is unrelated to a service mesh. By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster.
|
||||
|
||||
You can use the Nginx Ingress controller with or without Istio installed. If this is the only gateway to your cluster, Istio will be able to route traffic from service to service, but Istio will not be able to receive traffic from outside the cluster.
|
||||
|
||||
To allow Istio to receive external traffic, you need to enable Istio's gateway, which works as a north-south proxy for external traffic. When you enable the Istio gateway, the result is that your cluster will have two Ingresses.
|
||||
|
||||
You will also need to set up a Kubernetes gateway for your services. This Kubernetes resource points to Istio's implementation of the ingress gateway to the cluster.
|
||||
|
||||
You can route traffic into the service mesh with a load balancer or use Istio's NodePort gateway. This section describes how to set up the NodePort gateway.
|
||||
|
||||
For more information on the Istio gateway, refer to the [Istio documentation.](https://istio.io/docs/reference/config/networking/v1alpha3/gateway/)
|
||||
|
||||
|
||||
|
||||
## Enable an Istio Gateway
|
||||
|
||||
The ingress gateway is a Kubernetes service that will be deployed in your cluster. The Istio Gateway allows for more extensive customization and flexibility.
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. In the left navigation bar, click **Istio > Gateways**.
|
||||
1. Click **Create from Yaml**.
|
||||
1. Paste your Istio Gateway yaml, or **Read from File**.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** The gateway is deployed, and will now route traffic with applied rules.
|
||||
|
||||
## Example Istio Gateway
|
||||
|
||||
We add the BookInfo app deployments in services when going through the Workloads example. Next we add an Istio Gateway so that the app is accessible from outside your cluster.
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. In the left navigation bar, click **Istio > Gateways**.
|
||||
1. Click **Create from Yaml**.
|
||||
1. Copy and paste the Gateway yaml provided below.
|
||||
1. Click **Create**.
|
||||
|
||||
```yaml
|
||||
apiVersion: networking.istio.io/v1alpha3
|
||||
kind: Gateway
|
||||
metadata:
|
||||
name: bookinfo-gateway
|
||||
spec:
|
||||
selector:
|
||||
istio: ingressgateway # use istio default controller
|
||||
servers:
|
||||
- port:
|
||||
number: 80
|
||||
name: http
|
||||
protocol: HTTP
|
||||
hosts:
|
||||
- "*"
|
||||
---
|
||||
```
|
||||
|
||||
Then to deploy the VirtualService that provides the traffic routing for the Gateway:
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. In the left navigation bar, click **Istio > VirtualServices**.
|
||||
1. Copy and paste the VirtualService yaml provided below.
|
||||
1. Click **Create**.
|
||||
|
||||
```yaml
|
||||
apiVersion: networking.istio.io/v1alpha3
|
||||
kind: VirtualService
|
||||
metadata:
|
||||
name: bookinfo
|
||||
spec:
|
||||
hosts:
|
||||
- "*"
|
||||
gateways:
|
||||
- bookinfo-gateway
|
||||
http:
|
||||
- match:
|
||||
- uri:
|
||||
exact: /productpage
|
||||
- uri:
|
||||
prefix: /static
|
||||
- uri:
|
||||
exact: /login
|
||||
- uri:
|
||||
exact: /logout
|
||||
- uri:
|
||||
prefix: /api/v1/products
|
||||
route:
|
||||
- destination:
|
||||
host: productpage
|
||||
port:
|
||||
number: 9080
|
||||
```
|
||||
|
||||
**Result:** You have configured your gateway resource so that Istio can receive traffic from outside the cluster.
|
||||
|
||||
Confirm that the resource exists by running:
|
||||
```
|
||||
kubectl get gateway -A
|
||||
```
|
||||
|
||||
The result should be something like this:
|
||||
```
|
||||
NAME AGE
|
||||
bookinfo-gateway 64m
|
||||
```
|
||||
|
||||
### Access the ProductPage Service from a Web Browser
|
||||
|
||||
To test and see if the BookInfo app deployed correctly, the app can be viewed a web browser using the Istio controller IP and port, combined with the request name specified in your Kubernetes gateway resource:
|
||||
|
||||
`http://<IP of Istio controller>:<Port of istio controller>/productpage`
|
||||
|
||||
To get the ingress gateway URL and port,
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. In the left navigation bar, click **Workload**.
|
||||
1. Scroll down to the `istio-system` namespace.
|
||||
1. Within `istio-system`, there is a workload named `istio-ingressgateway`. Under the name of this workload, you should see links, such as `80/tcp`.
|
||||
1. Click one of those links. This should show you the URL of the ingress gateway in your web browser. Append `/productpage` to the URL.
|
||||
|
||||
**Result:** You should see the BookInfo app in the web browser.
|
||||
|
||||
For help inspecting the Istio controller URL and ports, try the commands the [Istio documentation.](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
The [official Istio documentation](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#troubleshooting) suggests `kubectl` commands to inspect the correct ingress host and ingress port for external requests.
|
||||
|
||||
### Confirming that the Kubernetes Gateway Matches Istio's Ingress Controller
|
||||
|
||||
You can try the steps in this section to make sure the Kubernetes gateway is configured properly.
|
||||
|
||||
In the gateway resource, the selector refers to Istio's default ingress controller by its label, in which the key of the label is `istio` and the value is `ingressgateway`. To make sure the label is appropriate for the gateway, do the following:
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. In the left navigation bar, click **Workload**.
|
||||
1. Scroll down to the `istio-system` namespace.
|
||||
1. Within `istio-system`, there is a workload named `istio-ingressgateway`. Click the name of this workload and go to the **Labels and Annotations** section. You should see that it has the key `istio` and the value `ingressgateway`. This confirms that the selector in the Gateway resource matches Istio's default ingress controller.
|
||||
|
||||
### [Next: Set up Istio's Components for Traffic Management](set-up-traffic-management.md)
|
||||
+87
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: Set up Istio's Components for Traffic Management
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management"/>
|
||||
</head>
|
||||
|
||||
:::warning
|
||||
|
||||
[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions).
|
||||
|
||||
Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043).
|
||||
|
||||
:::
|
||||
|
||||
A central advantage of traffic management in Istio is that it allows dynamic request routing. Some common applications for dynamic request routing include canary deployments and blue/green deployments. The two key resources in Istio traffic management are *virtual services* and *destination rules*.
|
||||
|
||||
- [Virtual services](https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service/) intercept and direct traffic to your Kubernetes services, allowing you to divide percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed.
|
||||
- [Destination rules](https://istio.io/docs/reference/config/networking/v1alpha3/destination-rule/) serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred.
|
||||
|
||||
This section describes how to add an example virtual service that corresponds to the `reviews` microservice in the sample BookInfo app. The purpose of this service is to divide traffic between two versions of the `reviews` service.
|
||||
|
||||
In this example, we take the traffic to the `reviews` service and intercept it so that 50 percent of it goes to `v1` of the service and 50 percent goes to `v2`.
|
||||
|
||||
After this virtual service is deployed, we will generate traffic and see from the Kiali visualization that traffic is being routed evenly between the two versions of the service.
|
||||
|
||||
To deploy the virtual service and destination rules for the `reviews` service,
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster where Istio is installed and click **Explore**.
|
||||
1. In the cluster where Istio is installed, click **Istio > DestinationRules** in the left navigation bar.
|
||||
1. Click **Create**.
|
||||
1. Copy and paste the DestinationRule yaml provided below.
|
||||
1. Click **Create**.
|
||||
1. Click **Edit as YAML** and use this configuration:
|
||||
|
||||
```yaml
|
||||
apiVersion: networking.istio.io/v1alpha3
|
||||
kind: DestinationRule
|
||||
metadata:
|
||||
name: reviews
|
||||
spec:
|
||||
host: reviews
|
||||
subsets:
|
||||
- name: v1
|
||||
labels:
|
||||
version: v1
|
||||
- name: v2
|
||||
labels:
|
||||
version: v2
|
||||
- name: v3
|
||||
labels:
|
||||
version: v3
|
||||
```
|
||||
1. Click **Create**.
|
||||
|
||||
Then to deploy the VirtualService that provides the traffic routing that utilizes the DestinationRule:
|
||||
|
||||
1. Click **VirtualService** in the side nav bar.
|
||||
1. Click **Create from Yaml**.
|
||||
1. Copy and paste the VirtualService yaml provided below.
|
||||
1. Click **Create**.
|
||||
|
||||
```yaml
|
||||
apiVersion: networking.istio.io/v1alpha3
|
||||
kind: VirtualService
|
||||
metadata:
|
||||
name: reviews
|
||||
spec:
|
||||
hosts:
|
||||
- reviews
|
||||
http:
|
||||
- route:
|
||||
- destination:
|
||||
host: reviews
|
||||
subset: v1
|
||||
weight: 50
|
||||
- destination:
|
||||
host: reviews
|
||||
subset: v3
|
||||
weight: 50
|
||||
---
|
||||
```
|
||||
|
||||
**Result:** When you generate traffic to this service (for example, by refreshing the ingress gateway URL), the Kiali traffic graph will reflect that traffic to the `reviews` service is divided evenly between `v1` and `v3`.
|
||||
|
||||
### [Next: Generate and View Traffic](generate-and-view-traffic.md)
|
||||
+371
@@ -0,0 +1,371 @@
|
||||
---
|
||||
title: Add Deployments and Services with the Istio Sidecar
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar"/>
|
||||
</head>
|
||||
|
||||
:::warning
|
||||
|
||||
[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions).
|
||||
|
||||
Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043).
|
||||
|
||||
:::
|
||||
|
||||
:::note Prerequisite:
|
||||
|
||||
To enable Istio for a workload, the cluster and namespace must have the Istio app installed.
|
||||
|
||||
:::
|
||||
|
||||
Enabling Istio in a namespace only enables automatic sidecar injection for new workloads. To enable the Envoy sidecar for existing workloads, you need to enable it manually for each workload.
|
||||
|
||||
To inject the Istio sidecar on an existing workload in the namespace,
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to see the visualizations and click **Explore**.
|
||||
1. Click **Workload**.
|
||||
1. Go to the workload where you want to inject the Istio sidecar and click **⋮ > Redeploy**. When the workload is redeployed, it will have the Envoy sidecar automatically injected.
|
||||
|
||||
Wait a few minutes for the workload to upgrade to have the istio sidecar. Click it and go to the Containers section. You should be able to see `istio-proxy` alongside your original workload. This means the Istio sidecar is enabled for the workload. Istio is doing all the wiring for the sidecar envoy. Now Istio can do all the features automatically if you enable them in the yaml.
|
||||
|
||||
### Add Deployments and Services
|
||||
|
||||
There are a few ways to add new **Deployments** in your namespace:
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. Click **Workload**.
|
||||
1. Click **Create**.
|
||||
1. Click **Deployment**.
|
||||
1. Fill out the form, or **Edit as Yaml**.
|
||||
1. Click **Create**.
|
||||
|
||||
To add a **Service** to your namespace:
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. Click **Service Discovery > Services**.
|
||||
1. Click **Create**.
|
||||
1. Select the type of service that you want.
|
||||
1. Fill out the form, or **Edit as Yaml**.
|
||||
1. Click **Create**
|
||||
|
||||
You can also create deployments and services using the kubectl **shell**
|
||||
|
||||
1. Run `kubectl create -f <name of service/deployment file>.yaml` if your file is stored locally in the cluster
|
||||
1. Or run `cat<< EOF | kubectl apply -f -`, paste the file contents into the terminal, then run `EOF` to complete the command.
|
||||
|
||||
### Example Deployments and Services
|
||||
|
||||
Next we add the Kubernetes resources for the sample deployments and services for the BookInfo app in Istio's documentation.
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. In the top navigation bar, open the kubectl shell.
|
||||
1. Run `cat<< EOF | kubectl apply -f -`
|
||||
1. Copy the below resources into the the shell.
|
||||
1. Run `EOF`
|
||||
|
||||
This will set up the following sample resources from Istio's example BookInfo app:
|
||||
|
||||
Details service and deployment:
|
||||
|
||||
- A `details` Service
|
||||
- A ServiceAccount for `bookinfo-details`
|
||||
- A `details-v1` Deployment
|
||||
|
||||
Ratings service and deployment:
|
||||
|
||||
- A `ratings` Service
|
||||
- A ServiceAccount for `bookinfo-ratings`
|
||||
- A `ratings-v1` Deployment
|
||||
|
||||
Reviews service and deployments (three versions):
|
||||
|
||||
- A `reviews` Service
|
||||
- A ServiceAccount for `bookinfo-reviews`
|
||||
- A `reviews-v1` Deployment
|
||||
- A `reviews-v2` Deployment
|
||||
- A `reviews-v3` Deployment
|
||||
|
||||
Productpage service and deployment:
|
||||
|
||||
This is the main page of the app, which will be visible from a web browser. The other services will be called from this page.
|
||||
|
||||
- A `productpage` service
|
||||
- A ServiceAccount for `bookinfo-productpage`
|
||||
- A `productpage-v1` Deployment
|
||||
|
||||
### Resource YAML
|
||||
|
||||
```yaml
|
||||
# Copyright 2017 Istio Authors
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
##################################################################################################
|
||||
# Details service
|
||||
##################################################################################################
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: details
|
||||
labels:
|
||||
app: details
|
||||
service: details
|
||||
spec:
|
||||
ports:
|
||||
- port: 9080
|
||||
name: http
|
||||
selector:
|
||||
app: details
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: bookinfo-details
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: details-v1
|
||||
labels:
|
||||
app: details
|
||||
version: v1
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: details
|
||||
version: v1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: details
|
||||
version: v1
|
||||
spec:
|
||||
serviceAccountName: bookinfo-details
|
||||
containers:
|
||||
- name: details
|
||||
image: docker.io/istio/examples-bookinfo-details-v1:1.15.0
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 9080
|
||||
---
|
||||
##################################################################################################
|
||||
# Ratings service
|
||||
##################################################################################################
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: ratings
|
||||
labels:
|
||||
app: ratings
|
||||
service: ratings
|
||||
spec:
|
||||
ports:
|
||||
- port: 9080
|
||||
name: http
|
||||
selector:
|
||||
app: ratings
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: bookinfo-ratings
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: ratings-v1
|
||||
labels:
|
||||
app: ratings
|
||||
version: v1
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: ratings
|
||||
version: v1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: ratings
|
||||
version: v1
|
||||
spec:
|
||||
serviceAccountName: bookinfo-ratings
|
||||
containers:
|
||||
- name: ratings
|
||||
image: docker.io/istio/examples-bookinfo-ratings-v1:1.15.0
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 9080
|
||||
---
|
||||
##################################################################################################
|
||||
# Reviews service
|
||||
##################################################################################################
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: reviews
|
||||
labels:
|
||||
app: reviews
|
||||
service: reviews
|
||||
spec:
|
||||
ports:
|
||||
- port: 9080
|
||||
name: http
|
||||
selector:
|
||||
app: reviews
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: bookinfo-reviews
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: reviews-v1
|
||||
labels:
|
||||
app: reviews
|
||||
version: v1
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: reviews
|
||||
version: v1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: reviews
|
||||
version: v1
|
||||
spec:
|
||||
serviceAccountName: bookinfo-reviews
|
||||
containers:
|
||||
- name: reviews
|
||||
image: docker.io/istio/examples-bookinfo-reviews-v1:1.15.0
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 9080
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: reviews-v2
|
||||
labels:
|
||||
app: reviews
|
||||
version: v2
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: reviews
|
||||
version: v2
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: reviews
|
||||
version: v2
|
||||
spec:
|
||||
serviceAccountName: bookinfo-reviews
|
||||
containers:
|
||||
- name: reviews
|
||||
image: docker.io/istio/examples-bookinfo-reviews-v2:1.15.0
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 9080
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: reviews-v3
|
||||
labels:
|
||||
app: reviews
|
||||
version: v3
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: reviews
|
||||
version: v3
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: reviews
|
||||
version: v3
|
||||
spec:
|
||||
serviceAccountName: bookinfo-reviews
|
||||
containers:
|
||||
- name: reviews
|
||||
image: docker.io/istio/examples-bookinfo-reviews-v3:1.15.0
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 9080
|
||||
---
|
||||
##################################################################################################
|
||||
# Productpage services
|
||||
##################################################################################################
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: productpage
|
||||
labels:
|
||||
app: productpage
|
||||
service: productpage
|
||||
spec:
|
||||
ports:
|
||||
- port: 9080
|
||||
name: http
|
||||
selector:
|
||||
app: productpage
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: bookinfo-productpage
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: productpage-v1
|
||||
labels:
|
||||
app: productpage
|
||||
version: v1
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: productpage
|
||||
version: v1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: productpage
|
||||
version: v1
|
||||
spec:
|
||||
serviceAccountName: bookinfo-productpage
|
||||
containers:
|
||||
- name: productpage
|
||||
image: docker.io/istio/examples-bookinfo-productpage-v1:1.15.0
|
||||
imagePullPolicy: IfNotPresent
|
||||
ports:
|
||||
- containerPort: 9080
|
||||
---
|
||||
```
|
||||
|
||||
### [Next: Set up the Istio Gateway](set-up-istio-gateway.md)
|
||||
+74
@@ -0,0 +1,74 @@
|
||||
---
|
||||
title: How Resource Quotas Work in Rancher Projects
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas"/>
|
||||
</head>
|
||||
|
||||
Resource quotas in Rancher include the same functionality as the [native version of Kubernetes](https://kubernetes.io/docs/concepts/policy/resource-quotas/). However, in Rancher, resource quotas have been extended so that you can apply them to projects.
|
||||
|
||||
In a standard Kubernetes deployment, resource quotas are applied to individual namespaces. However, you cannot apply the quota to your namespaces simultaneously with a single action. Instead, the resource quota must be applied multiple times.
|
||||
|
||||
In the following diagram, a Kubernetes administrator is trying to enforce a resource quota without Rancher. The administrator wants to apply a resource quota that sets the same CPU and memory limit to every namespace in his cluster (`Namespace 1-4`) . However, in the base version of Kubernetes, each namespace requires a unique resource quota. The administrator has to create four different resource quotas that have the same specs configured (`Resource Quota 1-4`) and apply them individually.
|
||||
|
||||
<sup>Base Kubernetes: Unique Resource Quotas Being Applied to Each Namespace</sup>
|
||||
|
||||
|
||||
|
||||
Resource quotas are a little different in Rancher. In Rancher, you apply a resource quota to the project, and then the quota propagates to each namespace, whereafter Kubernetes enforces your limits using the native version of resource quotas. If you want to change the quota for a specific namespace, you can override it.
|
||||
|
||||
The resource quota includes two limits, which you set while creating or editing a project:
|
||||
<a id="project-limits"></a>
|
||||
|
||||
- **Project Limits:**
|
||||
|
||||
This set of values configures a total limit for each specified resource shared among all namespaces in the project.
|
||||
|
||||
- **Namespace Default Limits:**
|
||||
|
||||
This set of values configures the default quota limit available for each namespace for each specified resource.
|
||||
When a namespace is created in the project without overrides, this limit is automatically bound to the namespace and enforced.
|
||||
|
||||
|
||||
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>
|
||||
|
||||
|
||||
|
||||
Let's highlight some more nuanced functionality for namespaces created **_within_** the Rancher UI. 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.
|
||||
|
||||
Before creating a namespace in a project, Rancher compares the amounts of the project's available resources and requested resources, regardless of whether they come from the default or overridden limits.
|
||||
If the requested resources exceed the remaining capacity in the project for those resources, Rancher will assign the namespace the remaining capacity for that resource.
|
||||
|
||||
However, this is not the case with namespaces created **_outside_** of Rancher's UI. For namespaces created via `kubectl`, Rancher
|
||||
will assign a resource quota that has a **zero** amount for any resource that requested more capacity than what remains in the project.
|
||||
|
||||
To create a namespace in an existing project via `kubectl`, use the `field.cattle.io/projectId` annotation. To override the default
|
||||
requested quota limit, use the `field.cattle.io/resourceQuota` annotation.
|
||||
|
||||
Note that Rancher will only override limits for resources that are defined on the project quota.
|
||||
|
||||
```
|
||||
apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
annotations:
|
||||
field.cattle.io/projectId: [your-cluster-ID]:[your-project-ID]
|
||||
field.cattle.io/resourceQuota: '{"limit":{"limitsCpu":"100m", "configMaps": "50"}}'
|
||||
name: my-ns
|
||||
```
|
||||
In this example, if the project's quota does not include configMaps in its list of resources, then Rancher will ignore `configMaps` in this override.
|
||||
|
||||
Users are advised to create dedicated `ResourceQuota` objects in namespaces to configure additional custom limits for resources not defined on the project.
|
||||
Resource quotas are native Kubernetes objects, and Rancher will ignore user-defined quotas in namespaces belonging to a project with a quota,
|
||||
thus giving users more control.
|
||||
|
||||
The following table explains the key differences between the two quota types.
|
||||
|
||||
| Rancher Resource Quotas | Kubernetes Resource Quotas |
|
||||
| ---------------------------------------------------------- | -------------------------------------------------------- |
|
||||
| Applies to projects and namespace. | Applies to namespaces only. |
|
||||
| Creates resource pool for all namespaces in project. | Applies static resource limits to individual namespaces. |
|
||||
| Applies resource quotas to namespaces through propagation. | Applies only to the assigned namespace.
|
||||
+50
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Project Resource Quotas
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas"/>
|
||||
</head>
|
||||
|
||||
In situations where several teams share a cluster, one team may overconsume the resources available: CPU, memory, storage, services, Kubernetes objects like pods or secrets, and so on. To prevent this overconsumption, you can apply a _resource quota_, which is a Rancher feature that limits the resources available to a project or namespace.
|
||||
|
||||
This page is a how-to guide for creating resource quotas in existing projects.
|
||||
|
||||
Resource quotas can also be set when a new project is created. For details, refer to the section on [creating new projects.](../../../new-user-guides/manage-clusters/projects-and-namespaces.md#creating-projects)
|
||||
|
||||
Resource quotas in Rancher include the same functionality as the [native version of Kubernetes](https://kubernetes.io/docs/concepts/policy/resource-quotas/). In Rancher, resource quotas have been extended so that you can apply them to projects. For details on how resource quotas work with projects in Rancher, refer to [this page.](about-project-resource-quotas.md)
|
||||
|
||||
### Applying Resource Quotas to Existing Projects
|
||||
|
||||
Edit resource quotas when:
|
||||
|
||||
- You want to limit the resources that a project and its namespaces can use.
|
||||
- You want to scale the resources available to a project up or down when a resource quota is already in effect.
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to apply a resource quota and click **Explore**.
|
||||
1. Click **Cluster > Projects/Namespaces**.
|
||||
1. Make sure that the **Projects/Namespaces** page is in **Group by Project** view mode.
|
||||
|
||||
|
||||
1. Find the project that you want to add a resource quota to, and select the **⋮** that's on the same row as the project's name.
|
||||
|
||||
|
||||
1. Select **Edit Config**.
|
||||
|
||||
1. Expand **Resource Quotas** and click **Add Resource**. Alternatively, you can edit existing quotas.
|
||||
|
||||
1. Select a Resource Type. For more information on types, see the [quota type reference.](resource-quota-types.md)
|
||||
|
||||
1. Enter values for the **Project Limit** and the **Namespace Default Limit**.
|
||||
|
||||
| Field | Description |
|
||||
| ----------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| Project Limit | The overall resource limit for the project. |
|
||||
| Namespace Default Limit | The default resource limit available for each namespace. This limit is propagated to each namespace in the project. The combined limit of all project namespaces shouldn't exceed the project limit. |
|
||||
|
||||
1. **Optional:** Add more quotas.
|
||||
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** The resource quota is applied to your project and namespaces. When you add more namespaces in the future, Rancher validates that the project can accommodate the namespace. If the project can't allocate the resources, you may still create namespaces, but they will be given a resource quota of 0. Subsequently, Rancher will not allow you to create any resources restricted by this quota.
|
||||
+38
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Overriding the Default Limit for a Namespace
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces"/>
|
||||
</head>
|
||||
|
||||
Although the **Namespace Default Limit** propagates from the project to each namespace when created, in some cases, you may need to increase (or decrease) the quotas for a specific namespace. In this situation, you can override the default limits by editing the namespace.
|
||||
|
||||
In the diagram below, the Rancher administrator has a resource quota in effect for their project. However, the administrator wants to override the namespace limits for `Namespace 3` so that it has more resources available. Therefore, the administrator [raises the namespace limits](../../../new-user-guides/manage-clusters/projects-and-namespaces.md) for `Namespace 3` so that the namespace can access more resources.
|
||||
|
||||
<sup>Namespace Default Limit Override</sup>
|
||||
|
||||
|
||||
|
||||
How to: [Editing Namespace Resource Quotas](../../../new-user-guides/manage-clusters/projects-and-namespaces.md)
|
||||
|
||||
### Editing Namespace Resource Quotas
|
||||
|
||||
If there is a resource quota configured for a project, you can override the namespace default limit to provide a specific namespace with access to more (or less) project resources.
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to edit a namespace resource quota and click **Explore**.
|
||||
1. Click **Cluster > Projects/Namespaces**.
|
||||
1. Find the namespace for which you want to edit the resource quota. Click **⋮ > Edit Config**.
|
||||
1. Edit the resource limits. These limits determine the resources available to the namespace. The limits must be set within the configured project limits.
|
||||
|
||||
For more information about each **Resource Type**, see [the type reference](resource-quota-types.md).
|
||||
|
||||
:::note
|
||||
|
||||
- If a resource quota is not configured for the project, these options will not be available.
|
||||
- If you enter limits that exceed the configured project limits, Rancher will not let you save your edits.
|
||||
|
||||
:::
|
||||
|
||||
**Result:** Your override is applied to the namespace's resource quota.
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Resource Quota Type Reference
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types"/>
|
||||
</head>
|
||||
|
||||
When you create a resource quota, you are configuring the pool of resources available to the project. You can set the following resource limits for the following resource types.
|
||||
|
||||
| Resource Type | Description |
|
||||
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| CPU Limit* | The maximum amount of CPU (in [millicores](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)) allocated to the project/namespace.<sup>1</sup> |
|
||||
| CPU Reservation* | The minimum amount of CPU (in millicores) guaranteed to the project/namespace.<sup>1</sup> |
|
||||
| Memory Limit* | The maximum amount of memory (in bytes) allocated to the project/namespace.<sup>1</sup> |
|
||||
| Memory Reservation* | The minimum amount of memory (in bytes) guaranteed to the project/namespace.<sup>1</sup> |
|
||||
| Storage Reservation | The minimum amount of storage (in gigabytes) guaranteed to the project/namespace. |
|
||||
| Services Load Balancers | The maximum number of load balancers services that can exist in the project/namespace. |
|
||||
| Services Node Ports | The maximum number of node port services that can exist in the project/namespace. |
|
||||
| Pods | The maximum number of pods that can exist in the project/namespace in a non-terminal state (i.e., pods with a state of `.status.phase in (Failed, Succeeded)` equal to true). |
|
||||
| Services | The maximum number of services that can exist in the project/namespace. |
|
||||
| ConfigMaps | The maximum number of ConfigMaps that can exist in the project/namespace. |
|
||||
| Persistent Volume Claims | The maximum number of persistent volume claims that can exist in the project/namespace. |
|
||||
| Replications Controllers | The maximum number of replication controllers that can exist in the project/namespace. |
|
||||
| Secrets | The maximum number of secrets that can exist in the project/namespace. |
|
||||
|
||||
:::note **<sup>*</sup>**
|
||||
|
||||
When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. A container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required.
|
||||
|
||||
:::
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Setting Container Default Resource Limits
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits"/>
|
||||
</head>
|
||||
|
||||
When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required.
|
||||
|
||||
To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace.
|
||||
|
||||
### Editing the Container Default Resource Limit
|
||||
|
||||
Edit the container default resource limit when:
|
||||
|
||||
- You have a CPU or Memory resource quota set on a project, and want to supply the corresponding default values for a container.
|
||||
- You want to edit the default container resource limit.
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to edit the default resource limit and click **Explore**.
|
||||
1. Click **Cluster > Projects/Namespaces**.
|
||||
1. Find the project that you want to edit the container default resource limit. From that project, select **⋮ > Edit Config**.
|
||||
1. Expand **Container Default Resource Limit** and edit the values.
|
||||
|
||||
### Resource Limit Propagation
|
||||
|
||||
When the default container resource limit is set at a project level, the parameter will be propagated to any namespace created in the project after the limit has been set. For any existing namespace in a project, this limit will not be automatically propagated. You will need to manually set the default container resource limit for any existing namespaces in the project in order for it to be used when creating any containers.
|
||||
|
||||
You can set a default container resource limit on a project and launch any catalog applications.
|
||||
|
||||
Once a container default resource limit is configured on a namespace, the default will be pre-populated for any containers created in that namespace. These limits/reservations can always be overridden during workload creation.
|
||||
|
||||
### Container Resource Quota Types
|
||||
|
||||
The following resource limits can be configured:
|
||||
|
||||
| Resource Type | Description |
|
||||
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| CPU Limit | The maximum amount of CPU (in [millicores](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)) allocated to the container.|
|
||||
| CPU Reservation | The minimum amount of CPU (in millicores) guaranteed to the container. |
|
||||
| Memory Limit | The maximum amount of memory (in bytes) allocated to the container. |
|
||||
| Memory Reservation | The minimum amount of memory (in bytes) guaranteed to the container.
|
||||
| NVIDIA GPU Limit/Reservation | The amount of GPUs allocated to the container. The limit and reservation are always the same for GPUs. |
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Project Administration
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/manage-projects"/>
|
||||
</head>
|
||||
|
||||
_Projects_ are objects introduced in Rancher that help organize namespaces in your Kubernetes cluster. You can use projects to create multi-tenant clusters, which allows a group of users to share the same underlying resources without interacting with each other's applications.
|
||||
|
||||
In terms of hierarchy:
|
||||
|
||||
- Clusters contain projects
|
||||
- Projects contain namespaces
|
||||
|
||||
Within Rancher, projects allow you to manage multiple namespaces as a single entity. In native Kubernetes, which does not include projects, features like role-based access rights or cluster resources are assigned to individual namespaces. In clusters where multiple namespaces require the same set of access rights, assigning these rights to each individual namespace can become tedious. Even though all namespaces require the same rights, there's no way to apply those rights to all of your namespaces in a single action. You'd have to repetitively assign these rights to each namespace!
|
||||
|
||||
Rancher projects resolve this issue by allowing you to apply resources and access rights at the project level. Each namespace in the project then inherits these resources and policies, so you only have to assign them to the project once, rather than assigning them to each individual namespace.
|
||||
|
||||
You can use projects to perform actions like:
|
||||
|
||||
- [Assign users access to a group of namespaces](../../new-user-guides/add-users-to-projects.md)
|
||||
- Assign users [specific roles in a project](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles). A role can be owner, member, read-only, or [custom](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md)
|
||||
- [Set resource quotas](manage-project-resource-quotas/manage-project-resource-quotas.md)
|
||||
- [Manage namespaces](../../new-user-guides/manage-namespaces.md)
|
||||
- [Configure tools](../../../reference-guides/rancher-project-tools.md)
|
||||
|
||||
### Authorization
|
||||
|
||||
Non-administrative users are only authorized for project access after an [administrator](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md), [cluster owner or member](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles), or [project owner](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles) adds them to the project's **Members** tab.
|
||||
|
||||
Whoever creates the project automatically becomes a [project owner](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles).
|
||||
|
||||
## Switching between Projects
|
||||
|
||||
To switch between projects, use the drop-down available in the navigation bar. Alternatively, you can switch between projects directly in the navigation bar.
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to switch projects and click **Explore**.
|
||||
1. In the top navigation bar, select the project that you want to open.
|
||||
+159
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: Persistent Grafana Dashboards
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard"/>
|
||||
</head>
|
||||
|
||||
To allow the Grafana dashboard to persist after the Grafana instance 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.
|
||||
|
||||
- [Creating a Persistent Grafana Dashboard](#creating-a-persistent-grafana-dashboard)
|
||||
- [Known Issues](#known-issues)
|
||||
|
||||
## Creating a Persistent Grafana Dashboard
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher v2.5.8+">
|
||||
|
||||
:::note Prerequisites:
|
||||
|
||||
- The monitoring application needs to be installed.
|
||||
- To create the persistent dashboard, you must have at least the **Manage Config Maps** Rancher RBAC permissions assigned to you in the project or namespace that contains the Grafana Dashboards. This correlates to the `monitoring-dashboard-edit` or `monitoring-dashboard-admin` Kubernetes native RBAC Roles exposed by the Monitoring chart.
|
||||
- To see the links to the external monitoring UIs, including Grafana dashboards, you will need at least a [project-member role.](../../../integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md#users-with-rancher-based-permissions)
|
||||
|
||||
:::
|
||||
|
||||
### 1. Get the JSON model of the dashboard that you want to persist
|
||||
|
||||
To create a persistent dashboard, you will need to get the JSON model of the dashboard you want to persist. You can use a premade dashboard or build your own.
|
||||
|
||||
To use a premade dashboard, go to [https://grafana.com/grafana/dashboards](https://grafana.com/grafana/dashboards), open up its detail page, and click on the **Download JSON** button to get the JSON model for the next step.
|
||||
|
||||
To use your own dashboard:
|
||||
|
||||
1. Click on the link to open Grafana. On the cluster detail page, click **Monitoring**.
|
||||
1. Log in to Grafana. Note: The default Admin username and password for the Grafana instance is `admin/prom-operator`. Alternative credentials can also be supplied on deploying or upgrading the chart.
|
||||
|
||||
:::note
|
||||
|
||||
Regardless of who has the password, in order to access the Grafana instance, you still need at least the <b>Manage Services</b> or <b>View Monitoring</b> permissions in the project that Rancher Monitoring is deployed into. Alternative credentials can also be supplied on deploying or upgrading the chart.
|
||||
|
||||
:::
|
||||
|
||||
1. Create a dashboard using Grafana's UI. Once complete, go to the dashboard's settings by clicking on the gear icon in the top navigation menu. In the left navigation menu, click **JSON Model**.
|
||||
1. Copy the JSON data structure that appears.
|
||||
|
||||
### 2. Create a ConfigMap using the Grafana JSON model
|
||||
|
||||
Create a ConfigMap in the namespace that contains your Grafana Dashboards (e.g. `cattle-dashboards` by default).
|
||||
|
||||
The ConfigMap should look like this:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
labels:
|
||||
grafana_dashboard: "1"
|
||||
name: <dashboard-name>
|
||||
namespace: cattle-dashboards # Change if using a non-default namespace
|
||||
data:
|
||||
<dashboard-name>.json: |-
|
||||
<copied-json>
|
||||
```
|
||||
|
||||
By default, Grafana is configured to watch all ConfigMaps with the `grafana_dashboard` label within the `cattle-dashboards` namespace.
|
||||
|
||||
To specify that you would like Grafana to watch for ConfigMaps across all namespaces, refer to [this section](#configuring-namespaces-for-the-grafana-dashboard-configmap).
|
||||
|
||||
To create the ConfigMap through the Rancher UI, first make sure that you are currently logged in to the Grafana UI, to ensure that dashboards import without encountering permissions issues. Then, return to the Rancher UI and perform the following steps:
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to see the visualizations and click **Explore**.
|
||||
1. Click **More Resources > Core > ConfigMaps**.
|
||||
1. Click **Create**.
|
||||
1. On the **Data** tab, set up the key-value pairs similar to the example above. When entering the value for `<dashboard-name>.json`, click **Read from File** to upload the JSON data model as the value.
|
||||
1. On the **Labels & Annotations** tab, click **Add Label** and enter `grafana_dashboard` as the key, and `1` as the value.
|
||||
1. Click **Create**.
|
||||
|
||||
**Result:** After the ConfigMap is created, it should show up on the Grafana UI and be persisted even if the Grafana pod is restarted.
|
||||
|
||||
:::note
|
||||
|
||||
The actual key-value pair may differ if you have modified the Helm chart to watch a different dashboard label and value.
|
||||
|
||||
:::
|
||||
|
||||
Dashboards that are persisted using ConfigMaps cannot be deleted or edited from the Grafana UI.
|
||||
|
||||
If you attempt to delete the dashboard in the Grafana UI, you will see the error message "Dashboard cannot be deleted because it was provisioned." To delete the dashboard, you will need to delete the ConfigMap.
|
||||
|
||||
### Configuring Namespaces for the Grafana Dashboard ConfigMap
|
||||
|
||||
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`.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher before v2.5.8">
|
||||
|
||||
:::note Prerequisites:
|
||||
|
||||
- The monitoring application needs to be installed.
|
||||
- You must have the cluster-admin ClusterRole permission.
|
||||
|
||||
:::
|
||||
|
||||
1. In the upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to configure the Grafana namespace and click **Explore**.
|
||||
1. In the left navigation bar, click **Monitoring**.
|
||||
1. Click **Grafana**.
|
||||
1. Log in to Grafana. Note: The default Admin username and password for the Grafana instance is `admin/prom-operator`. Alternative credentials can also be supplied on deploying or upgrading the chart.
|
||||
|
||||
:::note
|
||||
|
||||
Regardless of who has the password, cluster administrator permission in Rancher is still required to access the Grafana instance.
|
||||
|
||||
:::
|
||||
|
||||
1. Go to the dashboard that you want to persist. In the top navigation menu, go to the dashboard settings by clicking the gear icon.
|
||||
1. In the left navigation menu, click **JSON Model**.
|
||||
1. Copy the JSON data structure that appears.
|
||||
1. Create a ConfigMap in the `cattle-dashboards` namespace. The ConfigMap needs to have the label `grafana_dashboard: "1"`. Paste the JSON into the ConfigMap in the format shown in the example below:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
labels:
|
||||
grafana_dashboard: "1"
|
||||
name: <dashboard-name>
|
||||
namespace: cattle-dashboards
|
||||
data:
|
||||
<dashboard-name>.json: |-
|
||||
<copied-json>
|
||||
```
|
||||
|
||||
**Result:** After the ConfigMap is created, it should show up on the Grafana UI and be persisted even if the Grafana pod is restarted.
|
||||
|
||||
Dashboards that are persisted using ConfigMaps cannot be deleted from the Grafana UI. If you attempt to delete the dashboard in the Grafana UI, you will see the error message "Dashboard cannot be deleted because it was provisioned." To delete the dashboard, you will need to delete the ConfigMap.
|
||||
|
||||
To prevent the persistent dashboard from being deleted when Monitoring v2 is uninstalled, add the following annotation to the `cattle-dashboards` namespace:
|
||||
|
||||
```
|
||||
helm.sh/resource-policy: "keep"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Known Issues
|
||||
|
||||
For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the `cattle-dashboards` namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation `helm.sh/resource-policy: "keep"`.
|
||||
|
||||
This annotation will be added by default in the new monitoring chart released by Rancher v2.5.8, but it still needs to be manually applied for users of earlier Rancher versions.
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Customizing Grafana Dashboards
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard"/>
|
||||
</head>
|
||||
|
||||
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.](../../../integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md#users-with-rancher-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-visualizations/configure-panel-options/#edit-a-panel)
|
||||
- [Grafana docs on adding a panel to a dashboard](https://grafana.com/docs/grafana/latest/panels-visualizations/panel-editor-overview)
|
||||
+23
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: Debugging High Memory Usage
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage"/>
|
||||
</head>
|
||||
|
||||
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.
|
||||
+147
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: Enable Monitoring
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring"/>
|
||||
</head>
|
||||
|
||||
As an [administrator](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) or [cluster owner](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles), you can configure Rancher to deploy Prometheus to monitor your Kubernetes cluster.
|
||||
|
||||
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
|
||||
|
||||
- Allow traffic on port 9796 for each of your nodes. Prometheus scrapes metrics from these ports.
|
||||
- You may also need to allow traffic on port 10254 for each of your nodes, if [PushProx](../../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md#pushprox) is disabled (`ingressNginx.enabled` set to `false`), or you've upgraded from a previous Rancher version that had v1 monitoring already installed.
|
||||
- Make sure that your cluster fulfills the resource requirements. The cluster should have at least 1950Mi memory available, 2700m CPU, and 50Gi storage. See [Configuring Resource Limits and Requests](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#configuring-resource-limits-and-requests) for a breakdown of the resource limits and requests.
|
||||
|
||||
:::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 > Monitoring** in the upper left corner.
|
||||
|
||||
For more information about the default limits, see [this page.](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#configuring-resource-limits-and-requests)
|
||||
|
||||
## Install the Monitoring Application
|
||||
|
||||
### Enable Monitoring for use without SSL
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. Click **Cluster Tools** (bottom left corner).
|
||||
1. Click **Install** by Monitoring.
|
||||
1. Optional: Customize requests, limits and more for Alerting, Prometheus, and Grafana in the Values step. For help, refer to the [configuration reference.](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md)
|
||||
|
||||
**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](../../new-user-guides/kubernetes-resources-setup/secrets.md) 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 upper left corner, click **☰ > Cluster Management**.
|
||||
1. On the **Clusters** page, go to the cluster where you want to enable monitoring for use with SSL and click **Explore**.
|
||||
1. Click **Apps > Charts**.
|
||||
1. Click **Monitoring**.
|
||||
1. Click **Install** or **Update**, depending on whether you have already installed Monitoring.
|
||||
1. Check the box for **Customize Helm options before install** and click **Next**.
|
||||
1. Click **Alerting**.
|
||||
1. In the **Additional Secrets** field, add the secrets created earlier.
|
||||
|
||||
**Result:** The monitoring app is deployed in the `cattle-monitoring-system` namespace.
|
||||
|
||||
When [creating a receiver,](../../../reference-guides/monitoring-v2-configuration/receivers.md#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`.
|
||||
|
||||
## Rancher Performance Dashboard
|
||||
|
||||
When monitoring is installed on the upstream (local) cluster, you are given basic health metrics about the Rancher pods, such as CPU and memory data. To get advanced metrics for your local Rancher server, you must additionally enable the Rancher Performance Dashboard for Grafana.
|
||||
|
||||
This dashboard provides access to the following advanced metrics:
|
||||
|
||||
- Handler Average Execution Times Over Last 5 Minutes
|
||||
- Rancher API Average Request Times Over Last 5 Minutes
|
||||
- Subscribe Average Request Times Over Last 5 Minutes
|
||||
- Lasso Controller Work Queue Depth (Top 20)
|
||||
- Number of Rancher Requests (Top 20)
|
||||
- Number of Failed Rancher API Requests (Top 20)
|
||||
- K8s Proxy Store Average Request Times Over Last 5 Minutes (Top 20)
|
||||
- K8s Proxy Client Average Request Times Over Last 5 Minutes (Top 20)
|
||||
- Cached Objects by GroupVersionKind (Top 20)
|
||||
- Lasso Handler Executions (Top 20)
|
||||
- Handler Executions Over Last 2 Minutes (Top 20)
|
||||
- Total Handler Executions with Error (Top 20)
|
||||
- Data Transmitted by Remote Dialer Sessions (Top 20)
|
||||
- Errors for Remote Dialer Sessions (Top 20)
|
||||
- Remote Dialer Connections Removed (Top 20)
|
||||
- Remote Dialer Connections Added by Client (Top 20)
|
||||
|
||||
:::note
|
||||
|
||||
Profiling data (such as advanced memory or CPU analysis) is not present as it is a very context-dependent technique that's meant for debugging and not intended for normal observation.
|
||||
|
||||
:::
|
||||
|
||||
### Enabling the Rancher Performance Dashboard
|
||||
|
||||
To enable the Rancher Performance Dashboard:
|
||||
|
||||
<Tabs groupId="UIorCLI">
|
||||
<TabItem value="Helm">
|
||||
|
||||
Use the following options with the Helm CLI:
|
||||
|
||||
```bash
|
||||
--set extraEnv\[0\].name="CATTLE_PROMETHEUS_METRICS" --set-string extraEnv\[0\].value=true
|
||||
```
|
||||
|
||||
You can also include the following snippet in your Rancher Helm chart's values.yaml file:
|
||||
|
||||
```yaml
|
||||
extraEnv:
|
||||
- name: "CATTLE_PROMETHEUS_METRICS"
|
||||
value: "true"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="UI">
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the row of the `local` cluster and click **Explore**.
|
||||
1. Click **Workloads > Deployments**.
|
||||
1. Use the dropdown menu at the top to filter for **All Namespaces**.
|
||||
1. Under the `cattle-system` namespace, go to the `rancher` row and click **⋮ > Edit Config**
|
||||
1. Under **Environment Variables**, click **Add Variable**.
|
||||
1. For **Type**, select `Key/Value Pair`.
|
||||
1. For **Variable Name**, enter `CATTLE_PROMETHEUS_METRICS`.
|
||||
1. For **Value**, enter `true`.
|
||||
1. Click **Save** to apply the change.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Accessing the Rancher Performance Dashboard
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the row of the `local` cluster and click **Explore**.
|
||||
1. Click **Monitoring**
|
||||
1. Select the **Grafana** dashboard.
|
||||
1. From the sidebar, click **Search dashboards**.
|
||||
1. Enter `Rancher Performance Debugging` and select it.
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Monitoring/Alerting Guides
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides"/>
|
||||
</head>
|
||||
|
||||
- [Enable monitoring](enable-monitoring.md)
|
||||
- [Uninstall monitoring](uninstall-monitoring.md)
|
||||
- [Monitoring workloads](set-up-monitoring-for-workloads.md)
|
||||
- [Customizing Grafana dashboards](customize-grafana-dashboard.md)
|
||||
- [Persistent Grafana dashboards](create-persistent-grafana-dashboard.md)
|
||||
- [Debugging high memory usage](debug-high-memory-usage.md)
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: Customizing Grafana Dashboards
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/customize-grafana-dashboards"/>
|
||||
</head>
|
||||
|
||||
Grafana dashboards are customized the same way whether it's for rancher-monitoring or for Prometheus Federator.
|
||||
|
||||
For instructions, refer to [this page](../customize-grafana-dashboard.md).
|
||||
+90
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Enable Prometheus Federator
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/enable-prometheus-federator"/>
|
||||
</head>
|
||||
|
||||
## Requirements
|
||||
|
||||
By default, Prometheus Federator is configured and intended to be deployed alongside [rancher-monitoring](../../../../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md), which deploys Prometheus Operator alongside a Cluster Prometheus that each Project Monitoring Stack is configured to federate namespace-scoped metrics from by default.
|
||||
|
||||
For instructions on installing rancher-monitoring, refer to [this page](../enable-monitoring.md).
|
||||
|
||||
The default configuration should already be compatible with your rancher-monitoring stack. However, to optimize the security and usability of Prometheus Federator in your cluster, we recommend making these additional configurations to rancher-monitoring:
|
||||
|
||||
- [Ensure the cattle-monitoring-system namespace is placed into the System Project](#ensure-the-cattle-monitoring-system-namespace-is-placed-into-the-system-project-or-a-similarly-locked-down-project-that-has-access-to-other-projects-in-the-cluster).
|
||||
- [Configure rancher-monitoring to only watch for resources created by the Helm chart itself](#configure-rancher-monitoring-to-only-watch-for-resources-created-by-the-helm-chart-itself).
|
||||
- [Increase the CPU / memory limits of the Cluster Prometheus](#increase-the-cpu--memory-limits-of-the-cluster-prometheus).
|
||||
|
||||
### Ensure the cattle-monitoring-system namespace is placed into the System Project (or a similarly locked down Project that has access to other Projects in the cluster)
|
||||
|
||||
|
||||
|
||||
Prometheus Operator's security model expects that the namespace it is deployed into (e.g., `cattle-monitoring-system`) has limited access for anyone except Cluster Admins to avoid privilege escalation via execing into Pods (such as the Jobs executing Helm operations). In addition, deploying Prometheus Federator and all Project Prometheus stacks into the System Project ensures that each Project Prometheus is able to reach out to scrape workloads across all Projects, even if Network Policies are defined via Project Network Isolation. It also provides limited access for Project Owners, Project Members, and other users so that they're unable to access data that they shouldn't have access to (i.e., being allowed to exec into pods, set up the ability to scrape namespaces outside of a given Project, etc.).
|
||||
|
||||
1. Open the `System` project to check your namespaces:
|
||||
|
||||
Click **Cluster > Projects/Namespaces** in the Rancher UI. This will display all of the namespaces in the `System` project:
|
||||
|
||||
|
||||
|
||||
1. If you have an existing Monitoring V2 installation within the `cattle-monitoring-system` namespace, but that namespace is not in the `System` project, you may move the `cattle-monitoring-system` namespace into the `System` project or into another project of limited access. To do so, you may either:
|
||||
|
||||
- Drag and drop the namespace into the `System` project or
|
||||
- Select **⋮** to the right of the namespace, click **Move**, then choose `System` from the **Target Project** dropdown
|
||||
|
||||
|
||||
|
||||
### Configure rancher-monitoring to only watch for resources created by the Helm chart itself
|
||||
|
||||
Since each Project Monitoring Stack will watch the other namespaces and collect additional custom workload metrics or dashboards already, it's recommended to configure the following settings on all selectors to ensure that the Cluster Prometheus Stack only monitors resources created by the Helm Chart itself:
|
||||
|
||||
```
|
||||
matchLabels:
|
||||
release: "rancher-monitoring"
|
||||
```
|
||||
|
||||
The following selector fields are recommended to have this value:
|
||||
- `.Values.alertmanager.alertmanagerSpec.alertmanagerConfigSelector`
|
||||
- `.Values.prometheus.prometheusSpec.serviceMonitorSelector`
|
||||
- `.Values.prometheus.prometheusSpec.podMonitorSelector`
|
||||
- `.Values.prometheus.prometheusSpec.ruleSelector`
|
||||
- `.Values.prometheus.prometheusSpec.probeSelector`
|
||||
|
||||
Once this setting is turned on, you can always create ServiceMonitors or PodMonitors that are picked up by the Cluster Prometheus by adding the label `release: "rancher-monitoring"` to them, in which case they will be ignored by Project Monitoring Stacks automatically by default, even if the namespace in which those ServiceMonitors or PodMonitors reside in are not system namespaces.
|
||||
|
||||
:::note
|
||||
|
||||
If you don't want to allow users to be able to create ServiceMonitors and PodMonitors that aggregate into the Cluster Prometheus in Project namespaces, you can additionally set the namespaceSelectors on the chart to only target system namespaces (which must contain `cattle-monitoring-system` and `cattle-dashboards`, where resources are deployed into by default by rancher-monitoring; you will also need to monitor the `default` namespace to get apiserver metrics or create a custom ServiceMonitor to scrape apiserver metrics from the Service residing in the default namespace) to limit your Cluster Prometheus from picking up other Prometheus Operator CRs. In that case, it would be recommended to turn `.Values.prometheus.prometheusSpec.ignoreNamespaceSelectors=true` to allow you to define ServiceMonitors that can monitor non-system namespaces from within a system namespace.
|
||||
|
||||
:::
|
||||
|
||||
### Increase the CPU / memory limits of the Cluster Prometheus
|
||||
|
||||
Depending on a cluster's setup, it's generally recommended to give a large amount of dedicated memory to the Cluster Prometheus to avoid restarts due to out-of-memory errors (OOMKilled) usually caused by churn created in the cluster that causes a large number of high cardinality metrics to be generated and ingested by Prometheus within one block of time. This is one of the reasons why the default Rancher Monitoring stack expects around 4GB of RAM to be able to operate in a normal-sized cluster. However, when introducing Project Monitoring Stacks that are all sending `/federate` requests to the same Cluster Prometheus and are reliant on the Cluster Prometheus being "up" to federate that system data on their namespaces, it's even more important that the Cluster Prometheus has an ample amount of CPU / memory assigned to it to prevent an outage that can cause data gaps across all Project Prometheis in the cluster.
|
||||
|
||||
:::note
|
||||
|
||||
There are no specific recommendations on how much memory the Cluster Prometheus should be configured with since it depends entirely on the user's setup (namely the likelihood of encountering a high churn rate and the scale of metrics that could be generated at that time); it generally varies per setup.
|
||||
|
||||
:::
|
||||
|
||||
## Install the Prometheus Federator Application
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you want to install Prometheus Federator and click **Explore**.
|
||||
1. Click **Apps -> Charts**.
|
||||
1. Click the **Prometheus Federator** chart.
|
||||
1. Click **Install**.
|
||||
1. On the **Metadata** page, click **Next**.
|
||||
1. In the **Namespaces** > **Project Release Namespace Project ID** field, the `System Project` is used as the default but can be overridden with another project with similarly [limited access](#ensure-the-cattle-monitoring-system-namespace-is-placed-into-the-system-project-or-a-similarly-locked-down-project-that-has-access-to-other-projects-in-the-cluster). Project IDs can be found with the following command run in the local upstream cluster:
|
||||
|
||||
```plain
|
||||
kubectl get projects -A -o custom-columns="NAMESPACE":.metadata.namespace,"ID":.metadata.name,"NAME":.spec.displayName
|
||||
```
|
||||
|
||||
1. Click **Install**.
|
||||
|
||||
**Result:** The Prometheus Federator app is deployed in the `cattle-monitoring-system` namespace.
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Installing Project Monitors
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/project-monitors"/>
|
||||
</head>
|
||||
|
||||
Install **Project Monitors** in each project where you want to enable project monitoring.
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
|
||||
1. On the **Clusters** page, go to the cluster where you want to enable monitoring and click **Explore**.
|
||||
|
||||
1. Click **Monitoring > Project Monitors** on the left nav bar. Then click **Create** in the upper right.
|
||||
|
||||
|
||||
|
||||
1. Select your project from the drop-down menu, then click **Create** again.
|
||||
|
||||
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Prometheus Federator Guides
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides"/>
|
||||
</head>
|
||||
|
||||
- [Enable Prometheus Operator](enable-prometheus-federator.md)
|
||||
- [Uninstall Prometheus Operator](uninstall-prometheus-federator.md)
|
||||
- [Customize Grafana Dashboards](customize-grafana-dashboards.md)
|
||||
- [Set Up Workloads](set-up-workloads.md)
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Setting up Prometheus Federator for a Workload
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/set-up-workloads"/>
|
||||
</head>
|
||||
|
||||
### Display CPU and Memory Metrics for a Workload
|
||||
|
||||
Displaying CPU and memory metrics with Prometheus Federator is done the same way as with rancher-monitoring. For instructions, refer [here](../set-up-monitoring-for-workloads.md#display-cpu-and-memory-metrics-for-a-workload).
|
||||
|
||||
### Setting up Metrics Beyond CPU and Memory
|
||||
|
||||
Setting up metrics beyond CPU and memory with Prometheus Federator is done the same way as with rancher-monitoring. For instructions, refer [here](../set-up-monitoring-for-workloads.md#setting-up-metrics-beyond-cpu-and-memory).
|
||||
|
||||
<!-- ### Custom Metrics -->
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Uninstall Prometheus Federator
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/uninstall-prometheus-federator"/>
|
||||
</head>
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. In the left navigation bar, click **Apps**.
|
||||
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:** `prometheus-federator` is uninstalled.
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Setting up Monitoring for a Workload
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads"/>
|
||||
</head>
|
||||
|
||||
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](../../../integrations-in-rancher/monitoring-and-alerting/promql-expressions.md#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.
|
||||
+23
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: Uninstall Monitoring
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring"/>
|
||||
</head>
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster that you created and click **Explore**.
|
||||
1. In the left navigation bar, click **Apps**.
|
||||
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 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.
|
||||
|
||||
:::
|
||||
+19
@@ -0,0 +1,19 @@
|
||||
---
|
||||
title: Advanced Configuration
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration"/>
|
||||
</head>
|
||||
|
||||
### Alertmanager
|
||||
|
||||
For information on configuring the Alertmanager custom resource, see [this page.](alertmanager.md)
|
||||
|
||||
### Prometheus
|
||||
|
||||
For information on configuring the Prometheus custom resource, see [this page.](prometheus.md)
|
||||
|
||||
### PrometheusRules
|
||||
|
||||
For information on configuring the Prometheus custom resource, see [this page.](prometheusrules.md)
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: Alertmanager Configuration
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager"/>
|
||||
</head>
|
||||
|
||||
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.
|
||||
|
||||
:::note
|
||||
|
||||
This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../../../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md#3-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)
|
||||
+23
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: Prometheus Configuration
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus"/>
|
||||
</head>
|
||||
|
||||
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.
|
||||
|
||||
:::note
|
||||
|
||||
This section assumes familiarity with how monitoring components work together. For more information, see [this section.](../../../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md)
|
||||
|
||||
:::
|
||||
|
||||
## 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.
|
||||
+84
@@ -0,0 +1,84 @@
|
||||
---
|
||||
title: Configuring PrometheusRules
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules"/>
|
||||
</head>
|
||||
|
||||
A PrometheusRule defines a group of Prometheus alerting and/or recording rules.
|
||||
|
||||
:::note
|
||||
|
||||
This section assumes familiarity with how monitoring components work together. For more information, see [this section.](../../../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md)
|
||||
|
||||
:::
|
||||
|
||||
### Creating PrometheusRules in the Rancher UI
|
||||
|
||||
:::note Prerequisite:
|
||||
|
||||
The monitoring application needs to be installed.
|
||||
|
||||
:::
|
||||
|
||||
To create rule groups in the Rancher UI,
|
||||
|
||||
1. Go to the cluster where you want to create rule groups. Click **Monitoring > Advanced** and click **Prometheus Rules**.
|
||||
1. Click **Create**.
|
||||
1. Enter a **Group Name**.
|
||||
1. Configure the rules. In Rancher's UI, we expect a rule group to contain either alert rules or recording rules, but not both. For help filling out the forms, refer to the configuration options below.
|
||||
1. Click **Create**.
|
||||
|
||||
**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/main/Documentation/api-reference/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/main/Documentation/api-reference/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
|
||||
|
||||
### Rule Group
|
||||
|
||||
| Field | Description |
|
||||
|-------|----------------|
|
||||
| Group Name | The name of the group. Must be unique within a rules file. |
|
||||
| Override Group Interval | Duration in seconds for how often rules in the group are evaluated. |
|
||||
|
||||
|
||||
### Alerting Rules
|
||||
|
||||
[Alerting rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) allow you to define alert conditions based on PromQL (Prometheus Query Language) expressions and to send notifications about firing alerts to an external service.
|
||||
|
||||
| Field | Description |
|
||||
|-------|----------------|
|
||||
| Alert Name | The name of the alert. Must be a valid label value. |
|
||||
| Wait To Fire For | Duration in seconds. Alerts are considered firing once they have been returned for this long. Alerts which have not yet fired for long enough are considered pending. |
|
||||
| PromQL Expression | The PromQL expression to evaluate. Prometheus will evaluate the current value of this PromQL expression on every evaluation cycle and all resultant time series will become pending/firing alerts. For more information, refer to the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/querying/basics/) or our [example PromQL expressions.](../../../../integrations-in-rancher/monitoring-and-alerting/promql-expressions.md) |
|
||||
| Labels | Labels to add or overwrite for each alert. |
|
||||
| Severity | When enabled, labels are attached to the alert or record that identify it by the severity level. |
|
||||
| Severity Label Value | Critical, warning, or none |
|
||||
| Annotations | Annotations are a set of informational labels that can be used to store longer additional information, such as alert descriptions or runbook links. A [runbook](https://en.wikipedia.org/wiki/Runbook) is a set of documentation about how to handle alerts. The annotation values can be [templated.](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/#templating) |
|
||||
|
||||
### Recording Rules
|
||||
|
||||
[Recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/#recording-rules) allow you to precompute frequently needed or computationally expensive PromQL (Prometheus Query Language) expressions and save their result as a new set of time series.
|
||||
|
||||
| Field | Description |
|
||||
|-------|----------------|
|
||||
| Time Series Name | The name of the time series to output to. Must be a valid metric name. |
|
||||
| PromQL Expression | The PromQL expression to evaluate. Prometheus will evaluate the current value of this PromQL expression on every evaluation cycle and the result will be recorded as a new set of time series with the metric name as given by 'record'. For more information about expressions, refer to the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/querying/basics/) or our [example PromQL expressions.](../../../../integrations-in-rancher/monitoring-and-alerting/promql-expressions.md) |
|
||||
| Labels | Labels to add or overwrite before storing the result. |
|
||||
+55
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Monitoring Configuration Guides
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides"/>
|
||||
</head>
|
||||
|
||||
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/main/Documentation/getting-started/design.md) The Prometheus Operator documentation can help also you set up RBAC, Thanos, or custom configuration.
|
||||
|
||||
## Setting Resource Limits and Requests
|
||||
|
||||
The resource requests and limits for the monitoring application can be configured when installing `rancher-monitoring`. For more information about the default limits, see [this page.](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#configuring-resource-limits-and-requests)
|
||||
|
||||
:::tip
|
||||
|
||||
On an idle cluster, Monitoring may have high CPU usage. To improve performance, turn off the Prometheus adapter.
|
||||
|
||||
:::
|
||||
|
||||
## Prometheus Configuration
|
||||
|
||||
It is usually not necessary to directly edit the Prometheus custom resource.
|
||||
|
||||
Instead, to configure Prometheus to scrape custom metrics, you will only need to create a new ServiceMonitor or PodMonitor to configure Prometheus to scrape additional metrics.
|
||||
|
||||
|
||||
### ServiceMonitor and PodMonitor Configuration
|
||||
|
||||
For details, see [this page.](../../../reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md)
|
||||
|
||||
### Advanced Prometheus Configuration
|
||||
|
||||
For more information about directly editing the Prometheus custom resource, which may be helpful in advanced use cases, see [this page.](advanced-configuration/prometheus.md)
|
||||
|
||||
## Alertmanager Configuration
|
||||
|
||||
The Alertmanager custom resource usually doesn't need to be edited directly. For most common use cases, you can manage alerts by updating Routes and Receivers.
|
||||
|
||||
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.
|
||||
|
||||
For some advanced use cases, you may want to configure alertmanager directly. For more information, refer to [this page.](advanced-configuration/alertmanager.md)
|
||||
|
||||
### Receivers
|
||||
|
||||
Receivers are used to set up notifications. For details on how to configure receivers, see [this page.](../../../reference-guides/monitoring-v2-configuration/receivers.md)
|
||||
### Routes
|
||||
|
||||
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.](../../../reference-guides/monitoring-v2-configuration/routes.md)
|
||||
|
||||
### Advanced
|
||||
|
||||
For more information about directly editing the Alertmanager custom resource, which may be helpful in advanced use cases, see [this page.](advanced-configuration/alertmanager.md)
|
||||
+121
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: Opening Ports with firewalld
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/open-ports-with-firewalld"/>
|
||||
</head>
|
||||
|
||||
:::danger
|
||||
|
||||
Enabling firewalld can cause serious network communication problems.
|
||||
|
||||
For proper network function, firewalld must be disabled on systems running RKE2. [Firewalld conflicts with Canal](https://docs.rke2.io/known_issues#firewalld-conflicts-with-default-networking), RKE2's default networking stack.
|
||||
|
||||
Firewalld must also be disabled on systems running Kubernetes 1.19 and later.
|
||||
|
||||
If you enable firewalld on systems running Kubernetes 1.18 or earlier, understand that this may cause networking issues. CNIs in Kubernetes dynamically update iptables and networking rules independently of any external firewalls, such as firewalld. This can cause unexpected behavior when the CNI and the external firewall conflict.
|
||||
|
||||
:::
|
||||
|
||||
Some distributions of Linux [derived from RHEL,](https://en.wikipedia.org/wiki/Red_Hat_Enterprise_Linux#Rebuilds) including Oracle Linux, may have default firewall rules that block communication with Helm.
|
||||
|
||||
For example, one Oracle Linux image in AWS has REJECT rules that stop Helm from communicating with Tiller:
|
||||
|
||||
```
|
||||
Chain INPUT (policy ACCEPT)
|
||||
target prot opt source destination
|
||||
ACCEPT all -- anywhere anywhere state RELATED,ESTABLISHED
|
||||
ACCEPT icmp -- anywhere anywhere
|
||||
ACCEPT all -- anywhere anywhere
|
||||
ACCEPT tcp -- anywhere anywhere state NEW tcp dpt:ssh
|
||||
REJECT all -- anywhere anywhere reject-with icmp-host-prohibited
|
||||
|
||||
Chain FORWARD (policy ACCEPT)
|
||||
target prot opt source destination
|
||||
REJECT all -- anywhere anywhere reject-with icmp-host-prohibited
|
||||
|
||||
Chain OUTPUT (policy ACCEPT)
|
||||
target prot opt source destination
|
||||
```
|
||||
|
||||
You can check the default firewall rules with this command:
|
||||
|
||||
```
|
||||
sudo iptables --list
|
||||
```
|
||||
|
||||
This section describes how to use `firewalld` to apply the [firewall port rules](../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md#port-requirements) for nodes in a high-availability Rancher server cluster.
|
||||
|
||||
## Prerequisite
|
||||
|
||||
Install v7.x or later ofv`firewalld`:
|
||||
|
||||
```
|
||||
yum install firewalld
|
||||
systemctl start firewalld
|
||||
systemctl enable firewalld
|
||||
```
|
||||
|
||||
## Applying Firewall Port Rules
|
||||
|
||||
In the Rancher high-availability installation instructions, the Rancher server is set up on three nodes that have all three Kubernetes roles: etcd, controlplane, and worker. If your Rancher server nodes have all three roles, run the following commands on each node:
|
||||
|
||||
```
|
||||
firewall-cmd --permanent --add-port=22/tcp
|
||||
firewall-cmd --permanent --add-port=80/tcp
|
||||
firewall-cmd --permanent --add-port=443/tcp
|
||||
firewall-cmd --permanent --add-port=2376/tcp
|
||||
firewall-cmd --permanent --add-port=2379/tcp
|
||||
firewall-cmd --permanent --add-port=2380/tcp
|
||||
firewall-cmd --permanent --add-port=6443/tcp
|
||||
firewall-cmd --permanent --add-port=8472/udp
|
||||
firewall-cmd --permanent --add-port=9099/tcp
|
||||
firewall-cmd --permanent --add-port=10250/tcp
|
||||
firewall-cmd --permanent --add-port=10254/tcp
|
||||
firewall-cmd --permanent --add-port=30000-32767/tcp
|
||||
firewall-cmd --permanent --add-port=30000-32767/udp
|
||||
```
|
||||
If your Rancher server nodes have separate roles, use the following commands based on the role of the node:
|
||||
|
||||
```
|
||||
# For etcd nodes, run the following commands:
|
||||
firewall-cmd --permanent --add-port=2376/tcp
|
||||
firewall-cmd --permanent --add-port=2379/tcp
|
||||
firewall-cmd --permanent --add-port=2380/tcp
|
||||
firewall-cmd --permanent --add-port=8472/udp
|
||||
firewall-cmd --permanent --add-port=9099/tcp
|
||||
firewall-cmd --permanent --add-port=10250/tcp
|
||||
|
||||
# For control plane nodes, run the following commands:
|
||||
firewall-cmd --permanent --add-port=80/tcp
|
||||
firewall-cmd --permanent --add-port=443/tcp
|
||||
firewall-cmd --permanent --add-port=2376/tcp
|
||||
firewall-cmd --permanent --add-port=6443/tcp
|
||||
firewall-cmd --permanent --add-port=8472/udp
|
||||
firewall-cmd --permanent --add-port=9099/tcp
|
||||
firewall-cmd --permanent --add-port=10250/tcp
|
||||
firewall-cmd --permanent --add-port=10254/tcp
|
||||
firewall-cmd --permanent --add-port=30000-32767/tcp
|
||||
firewall-cmd --permanent --add-port=30000-32767/udp
|
||||
|
||||
# For worker nodes, run the following commands:
|
||||
firewall-cmd --permanent --add-port=22/tcp
|
||||
firewall-cmd --permanent --add-port=80/tcp
|
||||
firewall-cmd --permanent --add-port=443/tcp
|
||||
firewall-cmd --permanent --add-port=2376/tcp
|
||||
firewall-cmd --permanent --add-port=8472/udp
|
||||
firewall-cmd --permanent --add-port=9099/tcp
|
||||
firewall-cmd --permanent --add-port=10250/tcp
|
||||
firewall-cmd --permanent --add-port=10254/tcp
|
||||
firewall-cmd --permanent --add-port=30000-32767/tcp
|
||||
firewall-cmd --permanent --add-port=30000-32767/udp
|
||||
```
|
||||
|
||||
After the `firewall-cmd` commands have been run on a node, use the following command to enable the firewall rules:
|
||||
|
||||
```
|
||||
firewall-cmd --reload
|
||||
```
|
||||
|
||||
**Result:** The firewall is updated so that Helm can communicate with the Rancher server nodes.
|
||||
+36
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Tuning etcd for Large Installations
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/tune-etcd-for-large-installs"/>
|
||||
</head>
|
||||
|
||||
When Rancher is used to manage [a large infrastructure](../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md) it is recommended to increase the default keyspace for etcd from the default 2 GB. The maximum setting is 8 GB and the host should have enough RAM to keep the entire dataset in memory. When increasing this value you should also increase the size of the host. The keyspace size can also be adjusted in smaller installations if you anticipate a high rate of change of pods during the garbage collection interval.
|
||||
|
||||
The etcd data set is automatically cleaned up on a five-minute interval by Kubernetes. There are situations, e.g. deployment thrashing, where enough events could be written to etcd and deleted before garbage collection occurs and cleans things up causing the keyspace to fill up. If you see `mvcc: database space exceeded` errors, in the etcd logs or Kubernetes API server logs, you should consider increasing the keyspace size. This can be accomplished by setting the [quota-backend-bytes](https://etcd.io/docs/v3.5/op-guide/maintenance/#space-quota) setting on the etcd servers.
|
||||
|
||||
## Example: This Snippet of the RKE2/K3s config.yaml file Increases the Keyspace Size to 5GB
|
||||
|
||||
```yaml
|
||||
# RKE2/K3s config.yaml
|
||||
---
|
||||
etcd-arg:
|
||||
- "quota-backend-bytes=5368709120"
|
||||
```
|
||||
|
||||
## Scaling etcd Disk Performance
|
||||
|
||||
You can follow the recommendations from [the etcd docs](https://etcd.io/docs/v3.5/tuning/#disk) on how to tune the disk priority on the host.
|
||||
|
||||
Additionally, to reduce IO contention on the disks for etcd, you can use a dedicated device for the data and wal directory. Based on etcd best practices, mirroring RAID configurations are unnecessary because etcd replicates data between the nodes in the cluster. You can use striping RAID configurations to increase available IOPS.
|
||||
|
||||
To implement this solution in an RKE2/K3s cluster, the `/var/lib/etcd/data` and `/var/lib/etcd/wal` directories will need to have disks mounted and formatted on the underlying host. In the `extra_args` directive of the `etcd` service, you must include the `wal_dir` directory. Without specifying the `wal_dir`, etcd process will try to manipulate the underlying `wal` mount with insufficient permissions.
|
||||
|
||||
```yaml
|
||||
# RKE2/K3s config.yaml
|
||||
---
|
||||
etcd-arg:
|
||||
- "data-dir=/var/lib/etcd/data"
|
||||
- "wal-dir=/var/lib/etcd/wal"
|
||||
```
|
||||
+81
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: UI Server-Side Pagination
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/ui-server-side-pagination"/>
|
||||
</head>
|
||||
|
||||
Server-Side Pagination (SSP) is a Rancher feature to provide significant performance improvements across the UI for resources with high counts, restricting the amount of resources browser fetches and stores in memory.
|
||||
|
||||
Note that SSP is optional, **enabled by default**, and it can be disabled via the feature flag `ui-sql-cache`.
|
||||
|
||||
## Disk Space
|
||||
|
||||
:::important
|
||||
It is crucial that you review the available disk space on your nodes and plan accordingly before upgrading to Rancher v2.12.0 and later to avoid potential disk pressure and pod eviction issues.
|
||||
:::
|
||||
|
||||
The SSP relies on a caching mechanism that introduces a new requirement for ephemeral disk space on your cluster nodes. This cache, an internal SQLite database, is stored within the container's file system. This affects the nodes running the **Rancher server pods** (`rancher` in the `cattle-system` namespace on the local cluster) and the nodes running the **Rancher agent pods** (`cattle-cluster-agent` in the `cattle-system` namespace on all downstream clusters).
|
||||
|
||||
The amount of disk space required is dynamic and depends on the quantity and size of Kubernetes resources visualized in the UI. As a guideline, the cache may consume approximately **twice the size of the raw Kubernetes objects** it stores.
|
||||
|
||||
For example, internal tests showed that caching 5000 ConfigMaps, totaling 50 MB, consumed 81 MB of disk space. For a conservative, high-level estimate, you can plan for the available disk space on each relevant node to be at least **twice the size of your etcd snapshot**. For most production environments, ensuring a few extra gigabytes of storage are available on the relevant nodes is a safe starting point.
|
||||
|
||||
Please note this space counts against [ephemeral storage](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#setting-requests-and-limits-for-local-ephemeral-storage) requests and limits you might have set for your Rancher container via the `resource` value in the Helm chart. Make sure those settings provide for abundant available space.
|
||||
|
||||
If you see the error `database or disk is full (13)` in the pod logs, this is a symptom that more space needs to be allocated.
|
||||
|
||||
SQLite-backed caching persists copies of any cached Kubernetes objects to disk. See [Encrypting SQLite-backed Caching](#encrypting-sqlite-backed-caches) if this is a security concern.
|
||||
|
||||
## Enabling Server-Side Pagination
|
||||
|
||||
1. In the upper left corner, click **☰ > Global Settings > Feature Flags**.
|
||||
1. Find **`ui-sql-cache`** and select **⋮ > Activate > Activate**.
|
||||
1. Wait for Rancher to restart. This also restarts agents on all downstream clusters.
|
||||
1. Reload the page with the browser button (or the equivalent keyboard combination, typically `CTRL + R` on Windows and Linux, and `⌘ + R` on macOS).
|
||||
|
||||
## Disabling Server-Side Pagination
|
||||
|
||||
1. In the upper left corner, click **☰ > Global Settings > Feature Flags**.
|
||||
1. Find **`ui-sql-cache`** and select **⋮ > Deactivate > Deactivate**.
|
||||
1. Wait for Rancher to restart. This also restarts agents on all downstream clusters.
|
||||
1. Reload the page with the browser button (or the equivalent keyboard combination, typically `CTRL + R` on Windows and Linux, and `⌘ + R` on macOS).
|
||||
|
||||
## Encrypting SQLite-backed Caches
|
||||
|
||||
UI server-side pagination persists copies of any cached Kubernetes objects to disk. If you're concerned about the safety of this data, you can encrypt all objects before they are persisted to disk, by setting the environment variable `CATTLE_ENCRYPT_CACHE_ALL` to `true` in `rancher` pods in the upstream cluster and `cattle-cluster-agent` pods in the downstream clusters.
|
||||
|
||||
Secrets and security Tokens are always encrypted regardless of the above setting.
|
||||
|
||||
## Known Limitations of UI Server-Side Pagination
|
||||
|
||||
This release improves the performance of most pages used to view, create or edit resources within the `local` or downstream clusters i.e. the Cluster Explorer view. However, RBAC related resources and areas outside the Cluster Explorer are not yet covered by this feature.
|
||||
|
||||
Additionally, the following limitations are present when the feature is enabled. These mainly revolve around different sort or filter behaviors in affected lists:
|
||||
|
||||
- Resources in lists are automatically updated, however, not instantaneously.
|
||||
- All lists that utilize Server-Side Pagination:
|
||||
- `State` column sort and filter features work on the resources `metadata.state.name` field instead of one deduced locally by the UI.
|
||||
- Updates are shown every 5 seconds, rather than instantly.
|
||||
- Cluster Explorer:
|
||||
- Project/Namespace filter does not support filtering namespaces by all namespaces not in a project via the `Not in a Project` entry.
|
||||
- `Cluster` group --> `Nodes` page
|
||||
- The following columns are not sortable or filterable: `Roles`, `External/Internal IP`, `CPU`, `RAM` (logic to determine their value is calculated in the browser)
|
||||
- `Workloads` list:
|
||||
- The `Workloads` list, which showed multiple different resource types has been removed.
|
||||
- Server-Side Pagination of multiple resources is not currently possible.
|
||||
- `Workloads` group --> All lists
|
||||
- `Pod Restarts` and `Workload Health` columns have been removed.
|
||||
- [Re-enable Pod Restart Count and Pod Health columns for Workload lists #14211](https://github.com/rancher/dashboard/issues/14211)
|
||||
- `Workloads` group / `Job` List
|
||||
- `Duration` is not sortable (sorting on a duration).
|
||||
- [Implement more complex server-side pagination sorting #12815](https://github.com/rancher/dashboard/issues/12815)
|
||||
- `Workloads` group / `Pod` List
|
||||
- `Images` is not sortable (sorting on an array).
|
||||
- `Service Discovery` group / `Ingresses`
|
||||
- `Default` is not sortable/filterable (logic to determine their value is calculated in the browser).
|
||||
- `Storage` group / `ConfigMaps`
|
||||
- `Data` is not sortable/filterable (logic to determine their value is calculated in the browser).
|
||||
- `Storage` group / `Secrets`
|
||||
- `Data` is not sortable/filterable (logic to determine their value is calculated in the browser).
|
||||
Reference in New Issue
Block a user