---
title: "loki.rules.kubernetes | Grafana Alloy documentation"
description: "Learn about loki.rules.kubernetes"
---

# `loki.rules.kubernetes`

`loki.rules.kubernetes` discovers `PrometheusRule` Kubernetes resources and loads them into a Loki instance.

- You can specify multiple `loki.rules.kubernetes` components 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 Loki, 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 set up in Kubernetes for Alloy to access it via the Kubernetes REST API.

## Usage

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
loki.rules.kubernetes "<LABEL>" {
  address = "<LOKI_RULER_URL>"
}
```

## Arguments

You can use the following arguments with `loki.rules.kubernetes`:

Expand table

| Name                    | Type                | Description                                                                             | Default   | Required |
|-------------------------|---------------------|-----------------------------------------------------------------------------------------|-----------|----------|
| `address`               | `string`            | URL of the Loki ruler.                                                                  |           | yes      |
| `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       |
| `http_headers`          | `map(list(secret))` | Custom HTTP headers to be sent along with each request. The map key is the header name. |           | no       |
| `loki_namespace_prefix` | `string`            | Prefix used to differentiate multiple Alloy deployments.                                | `"alloy"` | no       |
| `proxy_url`             | `string`            | HTTP proxy to proxy requests through.                                                   |           | no       |
| `sync_interval`         | `duration`          | Amount of time between reconciliations with Loki.                                       | `"30s"`   | no       |
| `tenant_id`             | `string`            | Loki tenant ID.                                                                         |           | no       |
| `use_legacy_routes`     | `bool`              | Whether to use deprecated ruler API endpoints.                                          | `false`   | no       |

At most, one of the following can be provided:

- [`authorization`](#authorization) block
- [`basic_auth`](#basic_auth) block
- [`bearer_token_file`](#arguments) argument
- [`bearer_token`](#arguments) argument
- [`oauth2`](#oauth2) block

If no `tenant_id` is provided, the component assumes that the Loki instance at `address` is running in single-tenant mode and no `X-Scope-OrgID` header is sent.

The `sync_interval` argument determines how often the Loki ruler API is accessed to reload the current state. Interaction with the Kubernetes API works differently. Updates are processed as events from the Kubernetes API server according to the informer pattern.

You can use the `loki_namespace_prefix` argument to separate the rules managed by multiple Alloy deployments across your infrastructure. You should set the prefix to a unique value for each deployment.

## Blocks

You can use the following blocks with `loki.rules.kubernetes`:

No valid configuration blocks found.

### `authorization`

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.

> Warning
> 
> Using `credentials_file` causes the file to be read on every outgoing request. Use the `local.file` component with the `credentials` attribute instead to avoid unnecessary reads.

### `basic_auth`

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.

> Warning
> 
> Using `password_file` causes the file to be read on every outgoing request. Use the `local.file` component with the `password` attribute instead to avoid unnecessary reads.

### `extra_query_matchers`

The `extra_query_matchers` block has no attributes. It contains zero or more \[matcher]\[] blocks. These blocks allow you to add extra label matchers to all queries that are discovered by the `loki.rules.kubernetes` component. The algorithm for adding the label matchers to queries is the same as the one used by the [`promtool promql label-matchers set` command](https://prometheus.io/docs/prometheus/latest/command-line/promtool/#promtool-promql). It’s adapted to work with the LogQL parser.

### `matcher`

The `matcher` block describes a label matcher that’s added to each query found in `PrometheusRule` CRDs.

The following arguments are supported:

Expand table

| Name         | Type     | Description                                        | Default | Required |
|--------------|----------|----------------------------------------------------|---------|----------|
| `match_type` | `string` | The type of match. One of `=`, `!=`, `=~` or `!~`. |         | yes      |
| `name`       | `string` | Name of the label to match.                        |         | yes      |
| `value`      | `string` | Value of the label to match.                       |         | yes      |

### `rule_selector` and `rule_namespace_selector`

The `rule_selector` and `rule_namespace_selector` blocks describe 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 are matched.

You can also use the `match_expression` block to define more complex label expressions.

### `match_expression`

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"`

### `oauth2`

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       |
| `no_proxy`               | `string`            | Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying. |         | no       |
| `proxy_connect_header`   | `map(list(secret))` | Specifies headers to send to proxies during CONNECT requests.                                    |         | no       |
| `proxy_from_environment` | `bool`              | Use the proxy URL indicated by environment variables.                                            | `false` | no       |
| `proxy_url`              | `string`            | HTTP proxy to send requests through.                                                             |         | 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.

> Warning
> 
> Using `client_secret_file` causes the file to be read on every outgoing request. Use the `local.file` component with the `client_secret` attribute instead to avoid unnecessary reads.

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`

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` isn’t 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

`loki.rules.kubernetes` doesn’t export any fields.

## Component health

`loki.rules.kubernetes` is reported as unhealthy if given an invalid configuration or an error occurs during reconciliation.

## Debug information

`loki.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 Loki 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                                                              |
|----------------------------------------------|-------------|--------------------------------------------------------------------------|
| `loki_rules_config_updates_total`            | `counter`   | Number of times the configuration has been updated.                      |
| `loki_rules_events_total`                    | `counter`   | Number of events processed, partitioned by event type.                   |
| `loki_rules_events_failed_total`             | `counter`   | Number of events that failed to be processed, partitioned by event type. |
| `loki_rules_events_retried_total`            | `counter`   | Number of events that were retried, partitioned by event type.           |
| `loki_rules_client_request_duration_seconds` | `histogram` | Duration of requests to the Loki API.                                    |

## Example

This example creates a `loki.rules.kubernetes` component that loads discovered rules to a local Loki instance under the `team-a` tenant. Only namespaces and rules with the `alloy` label set to `yes` are included.

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
loki.rules.kubernetes "local" {
    address = "loki:3100"
    tenant_id = "team-a"

    rule_namespace_selector {
        match_labels = {
            alloy = "yes",
        }
    }

    rule_selector {
        match_labels = {
            alloy = "yes",
        }
    }
}
```

This example creates a `loki.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
loki.rules.kubernetes "default" {
    address = "<GRAFANA_CLOUD_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>"
    }
}
```

Replace the following:

- *`<GRAFANA_CLOUD_URL>`* : The Grafana Cloud URL.
- *`<GRAFANA_CLOUD_USER>`* : Your Grafana Cloud user name.
- *`<GRAFANA_CLOUD_API_KEY>`* : Your Grafana Cloud API key.
- *`<GRAFANA_CLOUD_API_KEY_PATH>`* : The path to the Grafana Cloud API key.

This example adds label matcher `{cluster=~"prod-.*"}` to all the queries discovered by `loki.rules.kubernetes`.

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
loki.rules.kubernetes "default" {
    address = "loki:3100"
    extra_query_matchers {
        matcher {
            name = "cluster"
            match_type = "=~"
            value = "prod-.*"
        }
    }
}
```

If a query in the form of `{app="my-app"}` is found in `PrometheusRule` CRDs, it will be modified to `{app="my-app", cluster=~"prod-.*"}` before sending it to Loki.

The following example is an RBAC configuration for Kubernetes. It authorizes Alloy 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: alloy
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: alloy
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: alloy
subjects:
- kind: ServiceAccount
  name: alloy
  namespace: default
roleRef:
  kind: ClusterRole
  name: alloy
  apiGroup: rbac.authorization.k8s.io
```