--- title: "mimir.rules.kubernetes | Grafana Agent documentation" description: "Learn about mimir.rules.kubernetes" --- # mimir.rules.kubernetes > **BETA**: This is a [beta](/docs/agent/v0.43/stability/#beta) component. Beta components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case. `mimir.rules.kubernetes` discovers `PrometheusRule` Kubernetes resources and loads them into a Mimir instance. - Multiple `mimir.rules.kubernetes` components can be specified by giving them different labels. - [Kubernetes label selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors) can be used to limit the `Namespace` and `PrometheusRule` resources considered during reconciliation. - Compatible with the Ruler APIs of Grafana Mimir, Grafana Cloud, and Grafana Enterprise Metrics. - Compatible with the `PrometheusRule` CRD from the [prometheus-operator](https://prometheus-operator.dev/). - This component accesses the Kubernetes REST API from [within a Pod](https://kubernetes.io/docs/tasks/run-application/access-api-from-pod/). > **NOTE**: This component requires [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) to be setup in Kubernetes in order for the Agent to access it via the Kubernetes REST API. For an example RBAC configuration please click [here](#example). ## Usage Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy mimir.rules.kubernetes "LABEL" { address = MIMIR_RULER_URL } ``` ## Arguments `mimir.rules.kubernetes` supports the following arguments: Expand table | Name | Type | Description | Default | Required | |--------------------------|---------------------|--------------------------------------------------------------------------------------------------|---------------|----------| | `address` | `string` | URL of the Mimir ruler. | | yes | | `tenant_id` | `string` | Mimir tenant ID. | | no | | `use_legacy_routes` | `bool` | Whether to use \[deprecated]\[gem-2\_2] ruler API endpoints. | false | no | | `prometheus_http_prefix` | `string` | Path prefix for \[Mimir’s Prometheus endpoint]\[gem-path-prefix]. | `/prometheus` | no | | `sync_interval` | `duration` | Amount of time between reconciliations with Mimir. | “5m” | no | | `mimir_namespace_prefix` | `string` | Prefix used to differentiate multiple Grafana Agent Flow deployments. | “agent” | no | | `bearer_token_file` | `string` | File containing a bearer token to authenticate with. | | no | | `bearer_token` | `secret` | Bearer token to authenticate with. | | no | | `enable_http2` | `bool` | Whether HTTP2 is supported for requests. | `true` | no | | `follow_redirects` | `bool` | Whether redirects returned by the server should be followed. | `true` | no | | `proxy_url` | `string` | HTTP proxy to send requests through. | | no | | `no_proxy` | `string` | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. | | no | | `proxy_from_environment` | `bool` | Use the proxy URL indicated by environment variables. | `false` | no | | `proxy_connect_header` | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests. | | no | At most, one of the following can be provided: - [`bearer_token` argument](#arguments). - [`bearer_token_file` argument](#arguments). - [`basic_auth` block](#basic_auth-block). - [`authorization` block](#authorization-block). - [`oauth2` block](#oauth2-block). `no_proxy` can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. `proxy_url` must be configured if `no_proxy` is configured. `proxy_from_environment` uses the environment variables HTTP\_PROXY, HTTPS\_PROXY and NO\_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO\_PROXY. `proxy_url` and `no_proxy` must not be configured if `proxy_from_environment` is configured. `proxy_connect_header` should only be configured if `proxy_url` or `proxy_from_environment` are configured. If no `tenant_id` is provided, the component assumes that the Mimir instance at `address` is running in single-tenant mode and no `X-Scope-OrgID` header is sent. The `sync_interval` argument determines how often Mimir’s ruler API is accessed to reload the current state of rules. Interaction with the Kubernetes API works differently. Updates are processed as events from the Kubernetes API server according to the informer pattern. The `mimir_namespace_prefix` argument can be used to separate the rules managed by multiple Grafana Agent Flow deployments across your infrastructure. It should be set to a unique value for each deployment. If `use_legacy_routes` is set to `true`, `mimir.rules.kubernetes` contacts Mimir on a `/api/v1/rules` endpoint. If `prometheus_http_prefix` is set to `/mimir`, `mimir.rules.kubernetes` contacts Mimir on a `/mimir/config/v1/rules` endpoint. This is useful if you configure Mimir to use a different \[prefix]\[gem-path-prefix] for its Prometheus endpoints than the default one. `prometheus_http_prefix` is ignored if `use_legacy_routes` is set to `true`. ## Blocks The following blocks are supported inside the definition of `mimir.rules.kubernetes`: Expand table | Hierarchy | Block | Description | Required | |--------------------------------------------------|----------------------------------------------|-----------------------------------------------------------|----------| | rule\_namespace\_selector | [label\_selector](#label_selector-block) | Label selector for `Namespace` resources. | no | | rule\_namespace\_selector > match\_expression | [match\_expression](#match_expression-block) | Label match expression for `Namespace` resources. | no | | rule\_selector | [label\_selector](#label_selector-block) | Label selector for `PrometheusRule` resources. | no | | rule\_selector > match\_expression | [match\_expression](#match_expression-block) | Label match expression for `PrometheusRule` resources. | no | | basic\_auth | [basic\_auth](#basic_auth-block) | Configure basic\_auth for authenticating to the endpoint. | no | | authorization | [authorization](#authorization-block) | Configure generic authorization to the endpoint. | no | | oauth2 | [oauth2](#oauth2-block) | Configure OAuth2 for authenticating to the endpoint. | no | | oauth2 > tls\_config | [tls\_config](#tls_config-block) | Configure TLS settings for connecting to the endpoint. | no | | tls\_config | [tls\_config](#tls_config-block) | Configure TLS settings for connecting to the endpoint. | no | The `>` symbol indicates deeper levels of nesting. For example, `oauth2 > tls_config` refers to a `tls_config` block defined inside an `oauth2` block. ### label\_selector block The `label_selector` block describes a Kubernetes label selector for rule or namespace discovery. The following arguments are supported: Expand table | Name | Type | Description | Default | Required | |----------------|---------------|---------------------------------------------------|---------|----------| | `match_labels` | `map(string)` | Label keys and values used to discover resources. | `{}` | yes | When the `match_labels` argument is empty, all resources will be matched. ### match\_expression block The `match_expression` block describes a Kubernetes label match expression for rule or namespace discovery. The following arguments are supported: Expand table | Name | Type | Description | Default | Required | |------------|----------------|------------------------------------|---------|----------| | `key` | `string` | The label name to match against. | | yes | | `operator` | `string` | The operator to use when matching. | | yes | | `values` | `list(string)` | The values used when matching. | | no | The `operator` argument should be one of the following strings: - `"In"` - `"NotIn"` - `"Exists"` - `"DoesNotExist"` The `values` argument must not be provided when `operator` is set to `"Exists"` or `"DoesNotExist"`. ### basic\_auth block Expand table | Name | Type | Description | Default | Required | |-----------------|----------|------------------------------------------|---------|----------| | `password_file` | `string` | File containing the basic auth password. | | no | | `password` | `secret` | Basic auth password. | | no | | `username` | `string` | Basic auth username. | | no | `password` and `password_file` are mutually exclusive, and only one can be provided inside a `basic_auth` block. ### authorization block Expand table | Name | Type | Description | Default | Required | |--------------------|----------|--------------------------------------------|---------|----------| | `credentials_file` | `string` | File containing the secret value. | | no | | `credentials` | `secret` | Secret value. | | no | | `type` | `string` | Authorization type, for example, “Bearer”. | | no | `credential` and `credentials_file` are mutually exclusive, and only one can be provided inside an `authorization` block. ### oauth2 block Expand table | Name | Type | Description | Default | Required | |--------------------------|---------------------|--------------------------------------------------------------------------------------------------|---------|----------| | `client_id` | `string` | OAuth2 client ID. | | no | | `client_secret_file` | `string` | File containing the OAuth2 client secret. | | no | | `client_secret` | `secret` | OAuth2 client secret. | | no | | `endpoint_params` | `map(string)` | Optional parameters to append to the token URL. | | no | | `proxy_url` | `string` | HTTP proxy to send requests through. | | no | | `no_proxy` | `string` | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. | | no | | `proxy_from_environment` | `bool` | Use the proxy URL indicated by environment variables. | `false` | no | | `proxy_connect_header` | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests. | | no | | `scopes` | `list(string)` | List of scopes to authenticate with. | | no | | `token_url` | `string` | URL to fetch the token from. | | no | `client_secret` and `client_secret_file` are mutually exclusive, and only one can be provided inside an `oauth2` block. The `oauth2` block may also contain a separate `tls_config` sub-block. `no_proxy` can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. `proxy_url` must be configured if `no_proxy` is configured. `proxy_from_environment` uses the environment variables HTTP\_PROXY, HTTPS\_PROXY and NO\_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO\_PROXY. `proxy_url` and `no_proxy` must not be configured if `proxy_from_environment` is configured. `proxy_connect_header` should only be configured if `proxy_url` or `proxy_from_environment` are configured. ### tls\_config block Expand table | Name | Type | Description | Default | Required | |------------------------|----------|----------------------------------------------------------|---------|----------| | `ca_pem` | `string` | CA PEM-encoded text to validate the server with. | | no | | `ca_file` | `string` | CA certificate to validate the server with. | | no | | `cert_pem` | `string` | Certificate PEM-encoded text for client authentication. | | no | | `cert_file` | `string` | Certificate file for client authentication. | | no | | `insecure_skip_verify` | `bool` | Disables validation of the server certificate. | | no | | `key_file` | `string` | Key file for client authentication. | | no | | `key_pem` | `secret` | Key PEM-encoded text for client authentication. | | no | | `min_version` | `string` | Minimum acceptable TLS version. | | no | | `server_name` | `string` | ServerName extension to indicate the name of the server. | | no | The following pairs of arguments are mutually exclusive and can’t both be set simultaneously: - `ca_pem` and `ca_file` - `cert_pem` and `cert_file` - `key_pem` and `key_file` When configuring client authentication, both the client certificate (using `cert_pem` or `cert_file`) and the client key (using `key_pem` or `key_file`) must be provided. When `min_version` is not provided, the minimum acceptable TLS version is inherited from Go’s default minimum version, TLS 1.2. If `min_version` is provided, it must be set to one of the following strings: - `"TLS10"` (TLS 1.0) - `"TLS11"` (TLS 1.1) - `"TLS12"` (TLS 1.2) - `"TLS13"` (TLS 1.3) ## Exported fields `mimir.rules.kubernetes` does not export any fields. ## Component health `mimir.rules.kubernetes` is reported as unhealthy if given an invalid configuration or an error occurs during reconciliation. ## Debug information `mimir.rules.kubernetes` exposes resource-level debug information. The following are exposed per discovered `PrometheusRule` resource: - The Kubernetes namespace. - The resource name. - The resource uid. - The number of rule groups. The following are exposed per discovered Mimir rule namespace resource: - The namespace name. - The number of rule groups. Only resources managed by the component are exposed - regardless of how many actually exist. ## Debug metrics Expand table | Metric Name | Type | Description | |-----------------------------------------------|-------------|--------------------------------------------------------------------------| | `mimir_rules_config_updates_total` | `counter` | Number of times the configuration has been updated. | | `mimir_rules_events_total` | `counter` | Number of events processed, partitioned by event type. | | `mimir_rules_events_failed_total` | `counter` | Number of events that failed to be processed, partitioned by event type. | | `mimir_rules_events_retried_total` | `counter` | Number of events that were retried, partitioned by event type. | | `mimir_rules_client_request_duration_seconds` | `histogram` | Duration of requests to the Mimir API. | ## Example This example creates a `mimir.rules.kubernetes` component that loads discovered rules to a local Mimir instance under the `team-a` tenant. Only namespaces and rules with the `agent` label set to `yes` are included. Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy mimir.rules.kubernetes "local" { address = "mimir:8080" tenant_id = "team-a" rule_namespace_selector { match_labels = { agent = "yes", } } rule_selector { match_labels = { agent = "yes", } } } ``` This example creates a `mimir.rules.kubernetes` component that loads discovered rules to Grafana Cloud. Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy mimir.rules.kubernetes "default" { address = "GRAFANA_CLOUD_METRICS_URL" basic_auth { username = "GRAFANA_CLOUD_USER" password = "GRAFANA_CLOUD_API_KEY" // Alternatively, load the password from a file: // password_file = "GRAFANA_CLOUD_API_KEY_PATH" } } ``` The following example is an RBAC configuration for Kubernetes. It authorizes the Agent to query the Kubernetes REST API: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: v1 kind: ServiceAccount metadata: name: grafana-agent namespace: default --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: grafana-agent rules: - apiGroups: [""] resources: ["namespaces"] verbs: ["get", "list", "watch"] - apiGroups: ["monitoring.coreos.com"] resources: ["prometheusrules"] verbs: ["get", "list", "watch"] --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: grafana-agent subjects: - kind: ServiceAccount name: grafana-agent namespace: default roleRef: kind: ClusterRole name: grafana-agent apiGroup: rbac.authorization.k8s.io ```