Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentation Grafana Alloy Reference Components mimir mimir.rules.kubernetes

mimir.rules.kubernetes

mimir.rules.kubernetes discovers PrometheusRule Kubernetes resources and loads them into a Mimir instance.

It can also federate rules from different source tenants into a target Mimir tenant by interpreting the monitoring.grafana.com/source_tenants annotation on PrometheusRule resources.

• You can specify multiple mimir.rules.kubernetes components by giving them different labels.
• Kubernetes label selectors let you limit the Namespace and PrometheusRule resources the component considers 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.
• This component accesses the Kubernetes REST API from within a Pod.

Usage

Alloy Copy

mimir.rules.kubernetes "<LABEL>" {
  address = "<MIMIR_RULER_URL>"
}

Arguments

You can use the following arguments with mimir.rules.kubernetes:

You can provide at most one of the following:

• authorization block
• basic_auth block
• bearer_token_file argument
• bearer_token argument
• oauth2 block

If you don’t provide tenant_id, the component assumes the Mimir instance at address runs in single-tenant mode. The component doesn’t send an X-Scope-OrgID header.

The sync_interval argument determines how often the component accesses the Mimir ruler API to reload the current state of rules. The Kubernetes API delivers updates as events using the informer pattern.

Use the mimir_namespace_prefix argument to separate the rules that multiple Alloy deployments manage across your infrastructure. Set it to a unique value for each deployment.

If you set use_legacy_routes to true, mimir.rules.kubernetes contacts Mimir on a /api/v1/rules endpoint.

If you set prometheus_http_prefix 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 for its Prometheus endpoints than the default one.

The component ignores prometheus_http_prefix if you set use_legacy_routes to true.

external_labels overrides label values if labels with the same names already exist inside the rule.

Blocks

You can use the following blocks with mimir.rules.kubernetes:

The > symbol indicates deeper levels of nesting. For example, oauth2 > tls_config refers to a tls_config block defined inside an oauth2 block.

authorization

basic_auth

extra_query_matchers

The extra_query_matchers block has no attributes. It contains zero or more matcher blocks. These blocks let you add extra label matchers to all queries that the mimir.rules.kubernetes component discovers. The algorithm of adding the label matchers to queries is the same as the one provided by the promtool promql label-matchers set command.

matcher

The matcher block describes a label matcher that the component adds to each query in PrometheusRule CRDs.

You can use the following arguments:

Use only one of value or value_from_label.

rule_selector and rule_namespace_selector

The rule_selector and rule_namespace_selector blocks describe a Kubernetes label selector for rule or namespace discovery.

You can use the following arguments:

When the match_labels argument is empty, the component matches all resources.

match_expression

The match_expression block describes a Kubernetes label match expression for rule or namespace discovery.

You can use the following arguments:

The operator argument should be one of the following strings:

• "In"
• "NotIn"
• "Exists"
• "DoesNotExist"

Don’t provide the values argument when you set operator to "Exists" or "DoesNotExist".

oauth2

tls_config

Exported fields

mimir.rules.kubernetes doesn’t export any fields.

Component health

mimir.rules.kubernetes reports as unhealthy when given an invalid configuration or when an error occurs during reconciliation.

Debug information

mimir.rules.kubernetes exposes resource-level debug information.

The component exposes the following per discovered PrometheusRule resource:

• The Kubernetes namespace.
• The resource name.
• The resource UID.
• The number of rule groups.

The component exposes the following per discovered Mimir rule namespace resource:

• The namespace name.
• The number of rule groups.

The component only exposes resources it manages, regardless of how many actually exist.

Debug metrics

Examples

This example creates a mimir.rules.kubernetes component that loads discovered rules to a local Mimir instance under the team-a tenant. The component only includes namespaces and rules with the alloy label set to yes.

Alloy Copy

mimir.rules.kubernetes "local" {
    address = "mimir:8080"
    tenant_id = "team-a"

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

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

This example creates a mimir.rules.kubernetes component that loads discovered rules to Grafana Cloud. It also adds a "label1" label to each rule. If that label already exists, the component overwrites it with "value1".

Alloy Copy

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>"
    }
    external_labels = {"label1" = "value1"}
}

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

Alloy Copy

mimir.rules.kubernetes "default" {
    address = "<GRAFANA_CLOUD_METRICS_URL>"
    extra_query_matchers {
        matcher {
            name = "cluster"
            match_type = "=~"
            value = "prod-.*"
        }
    }
}

If the component finds a query in the form of up != 1 in PrometheusRule CRDs, it modifies the query to up{cluster=~"prod-.*"} != 1 before sending it to Mimir.

This example shows a PrometheusRule with a label set to application.kubernetes.io/name=my-app.

YAML Copy

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  labels:
    application.kubernetes.io/name: my-app

The following configuration extracts the value from the PrometheusRules CR label application.kubernetes.io/name and adds a label matcher with the value {app=~"extracted_value"} to all the queries discovered by the mimir.rules.kubernetes component.

Alloy Copy

mimir.rules.kubernetes "default" {
    address = "<GRAFANA_CLOUD_METRICS_URL>"
    extra_query_matchers {
        matcher {
            name = "app"
            match_type = "="
            value_from_label = "application.kubernetes.io/name"
        }
    }
}

If the component finds a query in the form of up != 1 in PrometheusRule CRDs, it modifies the query to up{app="my-app"} != 1 before sending it to Mimir.

This example demonstrates tenant federation. The component treats rules defined in the PrometheusRule CR as originating from source-tenant-alpha and source-tenant-beta. The mimir.rules.kubernetes component syncs these rules to the target-tenant-main in the configured Mimir instance.

Alloy Copy

// config.alloy
mimir.rules.kubernetes "federated_rules" {
    address   = "mimir-ruler.example.com:8080"
    tenant_id = "target-tenant-main" // Target tenant in Mimir

    rule_selector {
        match_labels = {
            "federation-group" = "group1"
        }
    }
}

YAML Copy

# prometheus-rule-federated.yaml
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: federated-app-rules
  namespace: my-apps
  labels:
    federation-group: "group1"
  annotations:
    monitoring.grafana.com/source_tenants: "source-tenant-alpha,source-tenant-beta"
spec:
  groups:
  - name: my.app.rules
    rules:
    - alert: HighErrorRateFederated
      expr: job:request_latency_seconds:mean5m{job="my-federated-app"} > 0.5
      for: 10m
      labels:
        severity: critical
      annotations:
        summary: High request error rate for my-federated-app

The following example is an RBAC configuration for Kubernetes. It authorizes Alloy to query the Kubernetes REST API:

YAML Copy

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