Merge branch 'main' into copilot/clarify-cluster-management-capabilities

Merge pull request #2223 from LucasSaintarbor/increase-max-old-space-size
Increase max-old-space-size in test deployment
2026-09-29 14:38:50 +00:00 · 2026-03-09 16:05:17 +01:00 · 2026-03-06 15:08:06 -08:00 · 2026-03-06 13:32:27 -08:00 · 2026-03-06 12:40:53 -08:00 · 2026-03-06 12:04:46 -08:00
8941 changed files with 515498 additions and 294860 deletions
@@ -0,0 +1,18 @@
+---
+name: Release Maintenance Task Checklist
+about: Track tasks that need to be done every release.
+title: '<VERSION> - Rancher Manager Release Maintenance Task Checklist'
+---
+
+This issue is to track tasks that need to be done every release regardless of whether the release has new feature content or not.
+
+- [ ] Create a new branch for the release. Release-specific updates should use this branch as its base
+- [ ] Update the [versions table](https://ranchermanager.docs.rancher.com/versions)
+- [ ] Update the [Rancher:webhook version mapping table](https://ranchermanager.docs.rancher.com/reference-guides/rancher-webhook)
+- [ ] Update the [CNI popularity table](https://ranchermanager.docs.rancher.com/faq/container-network-interface-providers#cni-community-popularity)
+- [ ] Update the [CSP adapter compatibility matrix](https://ranchermanager.docs.rancher.com/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter#rancher-vs-adapter-compatibility-matrix)
+- [ ] Update the [deprecated features table](https://ranchermanager.docs.rancher.com/faq/deprecated-features)
+- [ ] Update the swagger-<VERSION>.json file
+- [ ] Create a PR merging the release branch back into the main branch
+- [ ] Create a new [release](https://github.com/rancher/rancher-docs/releases)
+- [ ] Update Algolia search index
@@ -1,9 +1,6 @@
 ---
 name: Request a New Feature
 about: For requesting new feature(s) to be added to the docs.
-title: ''
-labels: ''
-assignees: ''
 ---

 ## Related Issues
@@ -1,9 +1,6 @@
 ---
 name: Request an Update
 about: For fixing docs errors/typos, adding needed/missing information, updating verbiage, deleting outdated info, etc.
-title: ''
-labels: ''
-assignees: ''
 ---

 ## Related Issues
@@ -0,0 +1 @@
+f288d286db3b7c65e02cb6635d0c048f0f7a88fa
@@ -6,6 +6,7 @@ on:
      - main
    paths-ignore:
      - '**/README.md'
+      - '**/.github/ISSUE_TEMPLATE/**'

 jobs:
  build:
@@ -24,7 +25,7 @@ jobs:
        run: yarn install --frozen-lockfile
      - name: Build website
        env:
-          NODE_OPTIONS: "--max_old_space_size=7168"
+          NODE_OPTIONS: "--max_old_space_size=10240"
        run: yarn build --no-minify

      - name: Upload Build Artifact
@@ -4,6 +4,7 @@ on:
  pull_request:
    paths-ignore:
      - '**/README.md'
+      - '**/.github/ISSUE_TEMPLATE/**'

 jobs:
  test-deploy:
@@ -26,5 +27,5 @@ jobs:
        run: yarn run remark --quiet --use remark-lint-no-dead-urls ./docs
      - name: Test build website
        env:
-          NODE_OPTIONS: "--max_old_space_size=7168"
+          NODE_OPTIONS: "--max_old_space_size=10240"
        run: yarn build --no-minify
@@ -1 +1 @@
-* @btat @LucasSaintarbor @sunilarjun
+* @btat @LucasSaintarbor @pmkovar @sunilarjun
@@ -15,7 +15,7 @@ To get started, [fork](https://github.com/rancher/rancher-docs/fork) and clone t

 Our repository doesn't allow you to make changes directly to the `main` branch. Create a working branch and make pull requests from your fork to [rancher/rancher-docs](https://github.com/rancher/rancher-docs).

-For most updates, you'll need to edit a file in the `/docs` directory, which represents the ["Latest"](https://ranchermanager.docs.rancher.com/) version of our published documentation. The "Latest" version is a mirror of the most recently released version of Rancher. As of August 2024, the most recently released version of Rancher is 2.9.
+For most updates, you'll need to edit a file in the `/docs` directory, which represents the ["Latest"](https://ranchermanager.docs.rancher.com/) version of our published documentation. The "Latest" version is a mirror of the most recently released version of Rancher. As of July 2025, the most recently released version of Rancher is 2.12.

 Whenever an update is made to `/docs`, you should apply the same change to the corresponding file in `/versioned_docs/version-2.9`. If a change only affects older versions, you don't need to mirror it to the `/docs` directory.

@@ -93,7 +93,7 @@ Subsequent executions will check for updated dependencies, if there are none, it

 License
 =======
-Copyright (c) 2014-2024 [Rancher Labs, Inc.](https://rancher.com)
+Copyright (c) 2014-2026 [SUSE, LLC.](https://www.suse.com/)

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -52,7 +52,7 @@ As an [administrator](../../../how-to-guides/advanced-user-guides/authentication
 > | 10252 | Controlplane | Kube controller manager |
 > | 2379 | Etcd | Etcd server |

-> Monitoring V1 requires a Kubernetes verison less than or equal to v1.20.x. To install monitoring on Kubernetes v1.21+, you will need to [migrate to Monitoring V2.](/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5%2B-monitoring.md)
+> Monitoring V1 requires a Kubernetes verison less than or equal to v1.20.x. To install monitoring on Kubernetes v1.21+, you will need to [migrate to Monitoring V2.](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5%2B-monitoring.md)

 1. From the **Global** view, navigate to the cluster that you want to configure cluster monitoring.

@@ -41,7 +41,7 @@ Prometheus RemoteRead and RemoteWrite can be configured as custom answers in the

 For more information on remote endpoints and storage, refer to the [Prometheus documentation.](https://prometheus.io/docs/operating/integrations/#remote-endpoints-and-storage)

-The Prometheus operator documentation contains the full [RemoteReadSpec](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/api.md#remotereadspec) and [RemoteWriteSpec.](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/api.md#remotewritespec)
+The Prometheus operator documentation contains the full [RemoteReadSpec](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#remotereadspec) and [RemoteWriteSpec.](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#remotewritespec)

 An example configuration would be:

@@ -155,15 +155,32 @@ You may terminate the SSL/TLS on a L7 load balancer external to the Rancher clus

 Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly.

-#### Configuring Ingress for External TLS when Using NGINX v0.25
+### Configuring Ingress for External TLS when Using NGINX v0.22

-In NGINX v0.25, the behavior of NGINX has [changed](https://github.com/kubernetes/ingress-nginx/blob/main/Changelog.md#0220) regarding forwarding headers and external TLS termination. Therefore, in the scenario that you are using external TLS termination configuration with NGINX v0.25, you must edit the `cluster.yml` to enable the `use-forwarded-headers` option for ingress:
+In NGINX v0.22, the behavior of NGINX has [changed](https://github.com/kubernetes/ingress-nginx/blob/06efac9f0b6f8f84b553f58ccecf79dc42c75cc6/Changelog.md) regarding forwarding headers and external TLS termination. Therefore, in the scenario that you are using external TLS termination configuration with NGINX v0.22, you must enable the `use-forwarded-headers` option for ingress:

+For RKE installations, edit the `cluster.yml` to add the following settings.
 ```yaml
 ingress:
  provider: nginx
  options:
-    use-forwarded-headers: "true"
+    use-forwarded-headers: 'true'
+```
+
+For RKE2 installations, you can create a custom `rke2-ingress-nginx-config.yaml` file at `/var/lib/rancher/rke2/server/manifests/rke2-ingress-nginx-config.yaml` containing this required setting to enable using forwarded headers with external TLS termination. Without this required setting applied, the external LB will continuously respond with redirect loops it receives from the ingress controller. (This can be created before or after rancher is installed, rke2 server agent will notice this addition and automatically apply it.)
+
+```yaml
+---
+apiVersion: helm.cattle.io/v1
+kind: HelmChartConfig
+metadata:
+  name: rke2-ingress-nginx
+  namespace: kube-system
+spec:
+  valuesContent: |-
+    controller:
+      config:
+        use-forwarded-headers: "true"
 ```

 #### Required Headers
@@ -121,7 +121,7 @@ To test the overlay network, you can launch the following `DaemonSet` definition
          - image: alpine
            imagePullPolicy: Always
            name: alpine
-            command: ["sh", "-c", "tail -f /dev/null"]
+            command: ["sleep", "infinity"]
            terminationMessagePath: /dev/termination-log
    ```

@@ -41,7 +41,7 @@ Note that upgrades _to_ or _from_ any chart in the [rancher-alpha repository](..

 The upgrade instructions assume you are using Helm 3.

-For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) The [Helm 2 upgrade page here](helm2.md)provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
+For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) The [Helm 2 upgrade page here](helm2.md) provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

 ### For air gap installs: Populate private registry

@@ -16,12 +16,13 @@ The following steps quickly deploy a Rancher Server with a single node cluster a
 - [Virtualbox](https://www.virtualbox.org): The virtual machines that Vagrant provisions need to be provisioned to VirtualBox.
 - At least 4GB of free RAM.

-### Note
- Vagrant will require plugins to create VirtualBox VMs. Install them with the following commands:
+:::note 

-  `vagrant plugin install vagrant-vboxmanage`
+Vagrant requires plugins to create VirtualBox VMs. Install them with the following commands: 
+- `vagrant plugin install vagrant-vboxmanage` 
+- `vagrant plugin install vagrant-vbguest` 

-  `vagrant plugin install vagrant-vbguest`
+:::

 ## Getting Started

@@ -111,7 +111,7 @@ If you are experiencing issues while testing the connection to the Keycloak serv
 When you click on **Authenticate with Keycloak**, your are not redirected to your IdP.

  * Verify your Keycloak client configuration.
-  * Make sure `Force Post Binding` set to `OFF`.
+  * Make sure `Force Post Binding` is set to `OFF`.


 ### Forbidden message displayed after IdP login
@@ -10,7 +10,7 @@ After installation, the [system administrator](manage-role-based-access-control-

 ## First Log In

-After you log into Rancher for the first time, Rancher will prompt you for a **Rancher Server URL**.You should set the URL to the main entry point to the Rancher Server. When a load balancer sits in front a Rancher Server cluster, the URL should resolve to the load balancer. The system will automatically try to infer the Rancher Server URL from the IP address or host name of the host running the Rancher Server. This is only correct if you are running a single node Rancher Server installation. In most cases, therefore, you need to set the Rancher Server URL to the correct value yourself.
+After you log into Rancher for the first time, Rancher will prompt you for a **Rancher Server URL**. You should set the URL to the main entry point to the Rancher Server. When a load balancer sits in front a Rancher Server cluster, the URL should resolve to the load balancer. The system will automatically try to infer the Rancher Server URL from the IP address or host name of the host running the Rancher Server. This is only correct if you are running a single node Rancher Server installation. In most cases, therefore, you need to set the Rancher Server URL to the correct value yourself.

 >**Important!** After you set the Rancher Server URL, we do not support updating it. Set the URL with extreme care.

@@ -38,7 +38,7 @@ These methods of communicating with downstream Kubernetes clusters are also expl

 ### About the kube-api-auth Authentication Webhook

-The `kube-api-auth` microservice is deployed to provide the user authentication functionality for the [authorized cluster endpoint,](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) which is only available for [RKE clusters.](../../../new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) When you access the user cluster using `kubectl`, the cluster's Kubernetes API server authenticates you by using the `kube-api-auth` service as a webhook.
+The `kube-api-auth` microservice is deployed to provide the user authentication functionality for the [authorized cluster endpoint](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) which is only available for [RKE clusters.](../../../new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) When you access the user cluster using `kubectl`, the cluster's Kubernetes API server authenticates you by using the `kube-api-auth` service as a webhook.

 During cluster provisioning, the file `/etc/kubernetes/kube-api-authn-webhook.yaml` is deployed and `kube-apiserver` is configured with `--authentication-token-webhook-config-file=/etc/kubernetes/kube-api-authn-webhook.yaml`. This configures the `kube-apiserver` to query `http://127.0.0.1:6440/v1/authenticate` to determine authentication for bearer tokens.

@@ -23,7 +23,5 @@ For information on how Rancher works, regardless of the installation method, ref
 - The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443.
 - The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment.

-<figcaption>Kubernetes Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers</figcaption>
-
 ![High-availability Kubernetes Installation of Rancher](/img/ha/rancher2ha.svg)
 <sup>Kubernetes Rancher install with Layer 4 load balancer (TCP), depicting SSL termination at ingress controllers</sup>
@@ -100,7 +100,7 @@ If you want to check resolving of domain names on all of the hosts, execute the
          - image: busybox:1.28
            imagePullPolicy: Always
            name: alpine
-            command: ["sh", "-c", "tail -f /dev/null"]
+            command: ["sleep", "infinity"]
            terminationMessagePath: /dev/termination-log
    ```

@@ -43,7 +43,7 @@ To test the overlay network, you can launch the following `DaemonSet` definition
          - image: rancherlabs/swiss-army-knife
            imagePullPolicy: Always
            name: overlaytest
-            command: ["sh", "-c", "tail -f /dev/null"]
+            command: ["sleep", "infinity"]
            terminationMessagePath: /dev/termination-log

    ```
@@ -0,0 +1,92 @@
+---
+title: Continuous Delivery with Fleet
+---
+
+<head>
+  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet"/>
+</head>
+
+_Available as of Rancher v2.5_
+
+## What is Continuous Delivery with Fleet?
+
+Continuous Delivery is Rancher's GitOps functionality, which is provided via integration with Fleet.
+
+ - *Cluster engine*: Fleet is a container management and deployment engine designed to offer users more control on the local cluster and constant monitoring through GitOps. Fleet focuses not only on the ability to scale, but it also gives users a high degree of control and visibility to monitor exactly what is installed on the cluster.
+
+ - *Deployment management*: Fleet can manage deployments from git of raw Kubernetes YAML, Helm charts, Kustomize, or any combination of the three. Regardless of the source, all resources are dynamically turned into Helm charts, and Helm is used as the engine to deploy all resources in the cluster. As a result, users can enjoy a high degree of control, consistency, and auditability of their clusters.
+
+## Architecture
+
+For information about how Fleet works, see [this page](architecture.md).
+
+## Accessing Fleet in the Rancher UI
+
+Fleet comes preinstalled in Rancher v2.5. Users can leverage continuous delivery to deploy their applications to the Kubernetes clusters in the git repository without any manual operation by following **gitops** practice. For additional information on Continuous Delivery and other Fleet troubleshooting tips, refer [here](https://fleet.rancher.io/troubleshooting).
+
+Follow the steps below to access Continuous Delivery in the Rancher UI:
+
+1. Click **Cluster Explorer** in the Rancher UI.
+
+1. In the top left dropdown menu, click **Cluster Explorer > Continuous Delivery**.
+
+1. Select your namespace at the top of the menu, noting the following:
+
+    - By default, **fleet-default** is selected which includes all downstream clusters that are registered through Rancher.
+
+    - You may switch to **fleet-local**, which only contains the **local** cluster, or you may create your own workspace to which you may assign and move clusters.
+
+    - You can then manage clusters by clicking on **Clusters** on the left navigation bar.
+
+1. Click on **Gitrepos** on the left navigation bar to deploy the gitrepo into your clusters in the current workspace.
+
+1. Select your [git repository](https://fleet.rancher.io/gitrepo-add) and [target clusters/cluster group](https://fleet.rancher.io/gitrepo-targets). You can also create the cluster group in the UI by clicking on **Cluster Groups** from the left navigation bar.
+
+1. Once the gitrepo is deployed, you can monitor the application through the Rancher UI.
+
+## Windows Support
+
+_Available as of v2.5.6_
+
+For details on support for clusters with Windows nodes, see [this page](windows-support.md).
+
+## GitHub Repository
+
+The Fleet Helm charts are available [here](https://github.com/rancher/fleet/releases/tag/v0.3.10).
+
+## Using Fleet Behind a Proxy
+
+_Available as of v2.5.8_
+
+For details on using Fleet behind a proxy, see [this page](use-fleet-behind-a-proxy.md).
+
+## Helm Chart Dependencies
+
+In order for Helm charts with dependencies to deploy successfully, you must run a manual command (as listed below), as it is up to the user to fulfill the dependency list. If you do not do this and proceed to clone your repository and run `helm install`, your installation will fail because the dependencies will be missing.
+
+The Helm chart in the git repository must include its dependencies in the charts subdirectory. You must either manually run `helm dependencies update $chart` or run `helm dependencies build $chart` locally, then commit the complete charts directory to your git repository. Note that you will update your commands with the applicable parameters
+
+## Troubleshooting
+
+- **Known Issue**: Fleet becomes inoperable after a restore using the [backup-restore-operator](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md#1-install-the-rancher-backup-operator). We will update the community once a permanent solution is in place.
+
+- **Temporary Workaround**:
+
+    1. Find the two service account tokens listed in the fleet-controller and the fleet-controller-bootstrap service accounts. These are under the fleet-system namespace of the local cluster.
+    1. Remove the non-existent token secret. Doing so allows for only one entry to be present for the service account token secret that actually exists.
+    1. Delete the fleet-controller Pod in the fleet-system namespace to reschedule.
+    1. After the service account token issue is resolved, you can force redeployment of the fleet-agents. In the Rancher UI, go to **☰ > Cluster Management**, click on **Clusters** page, then click **Force Update**.
+    1. If the fleet-agent bundles remain in a `Modified` state after Step 4, update the field `spec.forceSyncGeneration` for the fleet-agent bundle to force re-creation.
+
+---
+
+- **Known Issue**: clientSecretName and helmSecretName secrets for Fleet gitrepos are not included in the backup nor restore created by the [backup-restore-operator](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md#1-install-the-rancher-backup-operator). We will update the community once a permanent solution is in place.
+
+- **Temporary Workaround**: By default, user-defined secrets are not backed up in Fleet. It is necessary to recreate secrets if performing a disaster recovery restore or migration of Rancher into a fresh cluster. To modify resourceSet to include extra resources you want to backup, refer to docs [here](https://github.com/rancher/backup-restore-operator#user-flow).
+
+## Documentation
+
+The Fleet documentation is at https://fleet.rancher.io/.
+
+
+
@@ -0,0 +1,85 @@
+---
+title: Built-in Dashboards
+---
+
+<head>
+  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards"/>
+</head>
+
+## Grafana UI
+
+[Grafana](https://grafana.com/grafana/) allows you to query, visualize, alert on and understand your metrics no matter where they are stored. Create, explore, and share dashboards with your team and foster a data driven culture.
+
+To see the default dashboards for time series data visualization, go to the Grafana UI.
+
+### Customizing Grafana
+
+To view and customize the PromQL queries powering the Grafana dashboard, see [this page.](../../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.md)
+
+### Persistent Grafana Dashboards
+
+To create a persistent Grafana dashboard, see [this page.](../../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md)
+
+### Access to Grafana
+
+For information about role-based access control for Grafana, see [this section.](rbac-for-monitoring.md#role-based-access-control-for-grafana)
+
+
+## Alertmanager UI
+
+When `rancher-monitoring` is installed, the Prometheus Alertmanager UI is deployed, allowing you to view your alerts and the current Alertmanager configuration.
+
+> This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [How Alertmanager Works.](how-monitoring-works.md#3-how-alertmanager-works)
+
+
+### Accessing the Alertmanager UI
+
+The Alertmanager UI lets you see the most recently fired alerts.
+
+> **Prerequisite:** The `rancher-monitoring` application must be installed.
+
+To see the Alertmanager UI, go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Alertmanager.**
+
+**Result:** The Alertmanager UI opens in a new tab. For help with configuration, refer to the [official Alertmanager documentation.](https://prometheus.io/docs/alerting/latest/alertmanager/)
+
+<figcaption>The Alertmanager UI</figcaption>
+
+![Alertmanager UI](/img/alertmanager-ui.png)
+
+
+### Viewing Default Alerts
+
+To see alerts that are fired by default, go to the Alertmanager UI and click **Expand all groups.**
+
+
+## Prometheus UI
+
+By default, the [kube-state-metrics service](https://github.com/kubernetes/kube-state-metrics) provides a wealth of information about CPU and memory utilization to the monitoring application. These metrics cover Kubernetes resources across namespaces. This means that in order to see resource metrics for a service, you don't need to create a new ServiceMonitor for it. Because the data is already in the time series database, you can go to the Prometheus UI and run a PromQL query to get the information. The same query can be used to configure a Grafana dashboard to show a graph of those metrics over time.
+
+To see the Prometheus UI, install `rancher-monitoring`. Then go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Prometheus Graph.**
+
+<figcaption>Prometheus Graph UI</figcaption>
+
+![Prometheus Graph UI](/img/prometheus-graph-ui.png)
+
+### Viewing the Prometheus Targets
+
+To see what services you are monitoring, you will need to see your targets. Targets are set up by ServiceMonitors and PodMonitors as sources to scrape metrics from. You won't need to directly edit targets, but the Prometheus UI can be useful for giving you an overview of all of the sources of metrics that are being scraped.
+
+To see the Prometheus Targets, install `rancher-monitoring`. Then go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Prometheus Targets.**
+
+<figcaption>Targets in the Prometheus UI</figcaption>
+
+![Prometheus Targets UI](/img/prometheus-targets-ui.png)
+
+### Viewing the PrometheusRules
+
+When you define a Rule (which is declared within a RuleGroup in a PrometheusRule resource), the [spec of the Rule itself](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#rule) contains labels that are used by Alertmanager to figure out which Route should receive a certain Alert.
+
+To see the PrometheusRules, install `rancher-monitoring`. Then go to the **Cluster Explorer.** In the top left corner, click **Cluster Explorer > Monitoring.** Then click **Prometheus Rules.**
+
+You can also see the rules in the Prometheus UI:
+
+<figcaption>Rules in the Prometheus UI</figcaption>
+
+![PrometheusRules UI](/img/prometheus-rules-ui.png)
@@ -0,0 +1,250 @@
+---
+title: How Monitoring Works
+---
+
+<head>
+  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works"/>
+</head>
+
+## 1. Architecture Overview
+
+_**The following sections describe how data flows through the Monitoring V2 application:**_
+
+### Prometheus Operator
+
+Prometheus Operator observes ServiceMonitors, PodMonitors, and PrometheusRules being created. When the Prometheus configuration resources are created, Prometheus Operator calls the Prometheus API to sync the new configuration. As the diagram at the end of this section shows, the Prometheus Operator acts as the intermediary between Prometheus and Kubernetes, calling the Prometheus API to synchronize Prometheus with the monitoring-related resources in Kubernetes.
+
+### ServiceMonitors and PodMonitors
+
+ServiceMonitors and PodMonitors declaratively specify targets, such as Services and Pods, that need to be monitored.
+
+- Targets are scraped on a recurring schedule based on the configured Prometheus scrape interval, and the metrics that are scraped are stored into the Prometheus Time Series Database (TSDB).
+
+- In order to perform the scrape, ServiceMonitors and PodMonitors are defined with label selectors that determine which Services or Pods should be scraped and endpoints that determine how the scrape should happen on the given target, e.g., scrape/metrics in TCP 10252, proxying through IP addr x.x.x.x.
+
+- Out of the box, Monitoring V2 comes with certain pre-configured exporters that are deployed based on the type of Kubernetes cluster that it is deployed on. For more information, see [Scraping and Exposing Metrics](#5-scraping-and-exposing-metrics).
+
+### How PushProx Works
+
+- Certain internal Kubernetes components are scraped via a proxy deployed as part of Monitoring V2 called **PushProx**. The Kubernetes components that expose metrics to Prometheus through PushProx are the following:
+`kube-controller-manager`, `kube-scheduler`, `etcd`, and `kube-proxy`.
+
+- For each PushProx exporter, we deploy one PushProx client onto all target nodes. For example, a PushProx client is deployed onto all controlplane nodes for kube-controller-manager, all etcd nodes for kube-etcd, and all nodes for kubelet.
+
+- We deploy exactly one PushProx proxy per exporter. The process for exporting metrics is as follows:
+
+1. The PushProx Client establishes an outbound connection with the PushProx Proxy.
+1. The client then polls the proxy for scrape requests that have come into the proxy.
+1. When the proxy receives a scrape request from Prometheus, the client sees it as a result of the poll.
+1. The client scrapes the internal component.
+1. The internal component responds by pushing metrics back to the proxy.
+
+
+<figcaption><br/>Process for Exporting Metrics with PushProx:<br/></figcaption>
+
+![Process for Exporting Metrics with PushProx](/img/pushprox-process.svg)
+
+### PrometheusRules
+
+PrometheusRules allow users to define rules for what metrics or time series database queries should result in alerts being fired. Rules are evaluated on an interval.
+
+- **Recording rules** create a new time series based on existing series that have been collected. They are frequently used to precompute complex queries.
+- **Alerting rules** run a particular query and fire an alert from Prometheus if the query evaluates to a non-zero value.
+
+### Alert Routing
+
+Once Prometheus determines that an alert needs to be fired, alerts are forwarded to **Alertmanager**.
+
+- Alerts contain labels that come from the PromQL query itself and additional labels and annotations that can be provided as part of specifying the initial PrometheusRule.
+
+- Before receiving any alerts, Alertmanager will use the **routes** and **receivers** specified in its configuration to form a routing tree on which all incoming alerts are evaluated. Each node of the routing tree can specify additional grouping, labeling, and filtering that needs to happen based on the labels attached to the Prometheus alert. A node on the routing tree (usually a leaf node) can also specify that an alert that reaches it needs to be sent out to a configured Receiver, e.g., Slack, PagerDuty, SMS, etc. Note that Alertmanager will send an alert first to **alertingDriver**, then alertingDriver will send or forward alert to the proper destination.
+
+- Routes and receivers are also stored in the Kubernetes API via the Alertmanager Secret. When the Secret is updated, Alertmanager is also updated automatically. Note that routing occurs via labels only (not via annotations, etc.).
+
+## 2. How Prometheus Works
+
+### Storing Time Series Data
+
+After collecting metrics from exporters, Prometheus stores the time series in a local on-disk time series database. Prometheus optionally integrates with remote systems, but `rancher-monitoring` uses local storage for the time series database.
+
+Once stored, users can query this TSDB using PromQL, the query language for Prometheus.
+
+PromQL queries can be visualized in one of two ways:
+
+1. By supplying the query in Prometheus's Graph UI, which will show a simple graphical view of the data.
+1. By creating a Grafana Dashboard that contains the PromQL query and additional formatting directives that label axes, add units, change colors, use alternative visualizations, etc.
+
+### Defining Rules for Prometheus
+
+Rules define queries that Prometheus needs to execute on a regular `evaluationInterval` to perform certain actions, such as firing an alert (alerting rules) or precomputing a query based on others existing in its TSDB (recording rules). These rules are encoded in PrometheusRules custom resources. When PrometheusRule custom resources are created or updated, the Prometheus Operator observes the change and calls the Prometheus API to synchronize the set of rules that Prometheus is currently evaluating on a regular interval.
+
+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.
+
+Upon evaluating a [rule](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#rule), Prometheus runs the provided PromQL query, adds the provided labels, and runs the appropriate action for the rule. If the rule triggers an alert, Prometheus also adds the provided annotations. For example, an Alerting Rule that adds `team: front-end` as a label to the provided PromQL query will append that label to the fired alert, which will allow Alertmanager to forward the alert to the correct Receiver.
+
+### Alerting and Recording Rules
+
+Prometheus doesn't maintain the state of whether alerts are active. It fires alerts repetitively at every evaluation interval, relying on Alertmanager to group and filter the alerts into meaningful notifications.
+
+The `evaluation_interval` constant defines how often Prometheus evaluates its alerting rules against the time series database. Similar to the `scrape_interval`, the `evaluation_interval` also defaults to one minute.
+
+The rules are contained in a set of rule files. Rule files include both alerting rules and recording rules, but only alerting rules result in alerts being fired after their evaluation.
+
+For recording rules, Prometheus runs a query, then stores it as a time series. This synthetic time series is useful for storing the results of an expensive or time-consuming query so that it can be queried more quickly in the future.
+
+Alerting rules are more commonly used. Whenever an alerting rule evaluates to a positive number, Prometheus fires an alert.
+
+The Rule file adds labels and annotations to alerts before firing them, depending on the use case:
+
+- Labels indicate information that identifies the alert and could affect the routing of the alert. For example, if when sending an alert about a certain container, the container ID could be used as a label.
+
+- Annotations denote information that doesn't affect where an alert is routed, for example, a runbook or an error message.
+
+## 3. How Alertmanager Works
+
+The Alertmanager handles alerts sent by client applications such as the Prometheus server. It takes care of the following tasks:
+
+- Deduplicating, grouping, and routing alerts to the correct receiver integration such as email, PagerDuty, or OpsGenie
+
+- Silencing and inhibition of alerts
+
+- Tracking alerts that fire over time
+
+- Sending out the status of whether an alert is currently firing, or if it is resolved
+
+### Alerts Forwarded by alertingDrivers
+
+When alertingDrivers are installed, this creates a `Service` that can be used as the receiver's URL for Teams or SMS, based on the alertingDriver's configuration. The URL in the Receiver points to the alertingDrivers; so the Alertmanager sends alert first to alertingDriver, then alertingDriver forwards or sends alert to the proper destination.
+
+### Routing Alerts to Receivers
+
+Alertmanager coordinates where alerts are sent. It allows you to group alerts based on labels and fire them based on whether certain labels are matched. One top-level route accepts all alerts. From there, Alertmanager continues routing alerts to receivers based on whether they match the conditions of the next route.
+
+While the Rancher UI forms only allow editing a routing tree that is two levels deep, you can configure more deeply nested routing structures by editing the Alertmanager Secret.
+
+### Configuring Multiple Receivers
+
+By editing the forms in the Rancher UI, you can set up a Receiver resource with all the information Alertmanager needs to send alerts to your notification system.
+
+By editing custom YAML in the Alertmanager or Receiver configuration, you can also send alerts to multiple notification systems. For more information, see the section on configuring [Receivers.](../../../reference-guides/monitoring-v2-configuration/receivers.md#configuring-multiple-receivers)
+
+## 4. Monitoring V2 Specific Components
+
+Prometheus Operator introduces a set of [Custom Resource Definitions](https://github.com/prometheus-operator/prometheus-operator#customresourcedefinitions) that allow users to deploy and manage Prometheus and Alertmanager instances by creating and modifying those custom resources on a cluster.
+
+Prometheus Operator will automatically update your Prometheus configuration based on the live state of the resources and configuration options that are edited in the Rancher UI.
+
+### Resources Deployed by Default
+
+By default, a set of resources curated by the [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) project are deployed onto your cluster as part of installing the Rancher Monitoring Application to set up a basic Monitoring/Alerting stack.
+
+The resources that get deployed onto your cluster to support this solution can be found in the [`rancher-monitoring`](https://github.com/rancher/charts/tree/main/charts/rancher-monitoring) Helm chart, which closely tracks the upstream [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) Helm chart maintained by the Prometheus community with certain changes tracked in the [CHANGELOG.md](https://github.com/rancher/charts/blob/main/charts/rancher-monitoring/CHANGELOG.md).
+
+### Default Exporters
+
+Monitoring V2 deploys three default exporters that provide additional metrics for Prometheus to store:
+
+1. `node-exporter`: exposes hardware and OS metrics for Linux hosts. For more information on `node-exporter`, refer to the [upstream documentation](https://prometheus.io/docs/guides/node-exporter/).
+
+1. `windows-exporter`: exposes hardware and OS metrics for Windows hosts (only deployed on Windows clusters). For more information on `windows-exporter`, refer to the [upstream documentation](https://github.com/prometheus-community/windows_exporter).
+
+1. `kube-state-metrics`: expose additional metrics that track the state of resources contained in the Kubernetes API (e.g., pods, workloads, etc.). For more information on `kube-state-metrics`, refer to the [upstream documentation](https://github.com/kubernetes/kube-state-metrics/tree/master/docs).
+
+ServiceMonitors and PodMonitors will scrape these exporters, as defined [here](#defining-what-metrics-are-scraped). Prometheus stores these metrics, and you can query the results via either Prometheus's UI or Grafana.
+
+See the [architecture](#1-architecture-overview) section for more information on recording rules, alerting rules, and Alertmanager.
+
+### Components Exposed in the Rancher UI
+
+When the monitoring application is installed, you will be able to edit the following components in the Rancher UI:
+
+| Component | Type of Component | Purpose and Common Use Cases for Editing |
+|--------------|------------------------|---------------------------|
+| ServiceMonitor | Custom resource | Sets up Kubernetes Services to scrape custom metrics from. Automatically updates the scrape configuration in the Prometheus custom resource. |
+| PodMonitor | Custom resource | Sets up Kubernetes Pods to scrape custom metrics from. Automatically updates the scrape configuration in the Prometheus custom resource. |
+| Receiver | Configuration block (part of Alertmanager) | Modifies information on where to send an alert (e.g., Slack, PagerDuty, etc.) and any necessary information to send the alert (e.g., TLS certs, proxy URLs, etc.). Automatically updates the Alertmanager custom resource. |
+| Route | Configuration block (part of Alertmanager) | Modifies the routing tree that is used to filter, label, and group alerts based on labels and send them to the appropriate Receiver. Automatically updates the Alertmanager custom resource. |
+| PrometheusRule | Custom resource | Defines additional queries that need to trigger alerts or define materialized views of existing series that are within Prometheus's TSDB.  Automatically updates the Prometheus custom resource. |
+
+### PushProx
+
+PushProx allows Prometheus to scrape metrics across a network boundary, which prevents users from having to expose metrics ports for internal Kubernetes components on each node in a Kubernetes cluster.
+
+Since the metrics for Kubernetes components are generally exposed on the host network of nodes in the cluster, PushProx deploys a DaemonSet of clients that sit on the hostNetwork of each node and make an outbound connection to a single proxy that is sitting on the Kubernetes API. Prometheus can then be configured to proxy scrape requests through the proxy to each client, which allows it to scrape metrics from the internal Kubernetes components without requiring any inbound node ports to be open.
+
+Refer to [Scraping Metrics with PushProx](#scraping-metrics-with-pushprox) for more.
+
+## 5. Scraping and Exposing Metrics
+
+### Defining what Metrics are Scraped
+
+ServiceMonitors and PodMonitors define targets that are intended for Prometheus to scrape. The [Prometheus custom resource](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/getting-started/design.md#prometheus) tells Prometheus which ServiceMonitors or PodMonitors it should use to find out where to scrape metrics from.
+
+The Prometheus Operator observes the ServiceMonitors and PodMonitors. When it observes that they are created or updated, it calls the Prometheus API to update the scrape configuration in the Prometheus custom resource and keep it in sync with the scrape configuration in the ServiceMonitors or PodMonitors. This scrape configuration tells Prometheus which endpoints to scrape metrics from and how it will label the metrics from those endpoints.
+
+Prometheus scrapes all of the metrics defined in its scrape configuration at every `scrape_interval`, which is one minute by default.
+
+The scrape configuration can be viewed as part of the Prometheus custom resource that is exposed in the Rancher UI.
+
+### How the Prometheus Operator Sets up Metrics Scraping
+
+The Prometheus Deployment or StatefulSet scrapes metrics, and the configuration of Prometheus is controlled by the Prometheus custom resources. The Prometheus Operator watches for Prometheus and Alertmanager resources, and when they are created, the Prometheus Operator creates a Deployment or StatefulSet for Prometheus or Alertmanager with the user-defined configuration.
+
+When the Prometheus Operator observes ServiceMonitors, PodMonitors, and PrometheusRules being created, it knows that the scrape configuration needs to be updated in Prometheus. It updates Prometheus by first updating the configuration and rules files in the volumes of Prometheus's Deployment or StatefulSet. Then it calls the Prometheus API to sync the new configuration, resulting in the Prometheus Deployment or StatefulSet to be modified in place.
+
+### How Kubernetes Component Metrics are Exposed
+
+Prometheus scrapes metrics from deployments known as [exporters,](https://prometheus.io/docs/instrumenting/exporters/) which export the time series data in a format that Prometheus can ingest. In Prometheus, time series consist of streams of timestamped values belonging to the same metric and the same set of labeled dimensions.
+
+### Scraping Metrics with PushProx
+
+Certain internal Kubernetes components are scraped via a proxy deployed as part of Monitoring V2 called PushProx. For detailed information on PushProx, refer [here](#how-pushprox-works) and to the above [architecture](#1-architecture-overview) section.
+
+### Scraping Metrics
+
+The following Kubernetes components are directly scraped by Prometheus:
+
+- kubelet*
+- ingress-nginx**
+- coreDns/kubeDns
+- kube-api-server
+
+\* You can optionally use `hardenedKubelet.enabled` to use a PushProx, but that is not the default.
+
+** For RKE and RKE2 clusters, ingress-nginx is deployed by default and treated as an internal Kubernetes component.
+
+
+### Scraping Metrics Based on Kubernetes Distribution
+
+Metrics are scraped differently based on the Kubernetes distribution. For help with terminology, refer [here](#terminology). For details, see the table below:
+
+<figcaption>How Metrics are Exposed to Prometheus</figcaption>
+
+| Kubernetes Component | RKE | RKE2 | KubeADM | K3s |
+|-----|-----|-----|-----|-----|
+| kube-controller-manager	| rkeControllerManager.enabled	|rke2ControllerManager.enabled |	kubeAdmControllerManager.enabled |	k3sServer.enabled |
+| kube-scheduler	| rkeScheduler.enabled |	rke2Scheduler.enabled	|kubeAdmScheduler.enabled	| k3sServer.enabled |
+| etcd	| rkeEtcd.enabled	| rke2Etcd.enabled	| kubeAdmEtcd.enabled |	Not available |
+| kube-proxy	| rkeProxy.enabled	| rke2Proxy.enabled	| kubeAdmProxy.enabled |	k3sServer.enabled |
+| kubelet	| Collects metrics directly exposed by kubelet	| Collects metrics directly exposed by kubelet	| Collects metrics directly exposed by kubelet	| Collects metrics directly exposed by kubelet |
+| ingress-nginx*	| Collects metrics directly exposed by kubelet, exposed by rkeIngressNginx.enabled	| Collects metrics directly exposed by kubelet, Exposed by rke2IngressNginx.enabled	| Not available	| Not available |
+| coreDns/kubeDns	| Collects metrics directly exposed by coreDns/kubeDns	| Collects metrics directly exposed by coreDns/kubeDns	| Collects metrics directly exposed by coreDns/kubeDns	| Collects metrics directly exposed by coreDns/kubeDns |
+| kube-api-server	| Collects metrics directly exposed by kube-api-server	|Collects metrics directly exposed by kube-api-server	| Collects metrics directly exposed by kube-appi-server	| Collects metrics directly exposed by kube-api-server |
+
+\* For RKE and RKE2 clusters, ingress-nginx is deployed by default and treated as an internal Kubernetes component.
+
+### Terminology
+
+- **kube-scheduler:** The internal Kubernetes component that uses information in the pod spec to decide on which node to run a pod.
+- **kube-controller-manager:** The internal Kubernetes component that is responsible for node management (detecting if a node fails), pod replication and endpoint creation.
+- **etcd:** The internal Kubernetes component that is the distributed key/value store which Kubernetes uses for persistent storage of all cluster information.
+- **kube-proxy:** The internal Kubernetes component that watches the API server for pods/services changes in order to maintain the network up to date.
+- **kubelet:** The internal Kubernetes component that watches the API server for pods on a node and makes sure they are running.
+- **ingress-nginx:** An Ingress controller for Kubernetes using NGINX as a reverse proxy and load balancer.
+- **coreDns/kubeDns:** The internal Kubernetes component responsible for DNS.
+- **kube-api-server:** The main internal Kubernetes component that is responsible for exposing APIs for the other master components.
--- a/Show More
+++ b/Show More