This is documentation for the next version of Alloy. For the latest stable release, go to the latest version.
mimir.rules.kubernetes
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 can be used to limit the
Namespace
andPrometheusRule
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. - This component accesses the Kubernetes REST API from within a Pod.
Note
This component requires Role-based access control (RBAC) to be set up in Kubernetes in order for Alloy to access it via the Kubernetes REST API.
Note
Alloy version 1.1 and higher supports clustered mode in this component. When you use this component as part of a cluster of Alloy instances, only a single instance from the cluster will update rules using the Mimir API.
Usage
mimir.rules.kubernetes "LABEL" {
address = MIMIR_RULER_URL
}
Arguments
mimir.rules.kubernetes
supports the following arguments:
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 Alloy deployments. | “alloy” | 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 | |
external_labels | map(string) | Labels to add to each rule. | {} | no |
At most, one of the following can be provided:
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 Alloy 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
.
external_labels
will override label values if labels with the same names already exist inside the rule.
Blocks
The following blocks are supported inside the definition of
mimir.rules.kubernetes
:
Hierarchy | Block | Description | Required |
---|---|---|---|
extra_query_matchers | extra_query_matchers | Additional label matchers to add to each query. | no |
extra_query_matchers > matcher | matcher | A label matcher to add to query. | no |
rule_namespace_selector | label_selector | Label selector for Namespace resources. | no |
rule_namespace_selector > match_expression | match_expression | Label match expression for Namespace resources. | no |
rule_selector | label_selector | Label selector for PrometheusRule resources. | no |
rule_selector > match_expression | match_expression | Label match expression for PrometheusRule resources. | no |
basic_auth | basic_auth | Configure basic_auth for authenticating to the endpoint. | no |
authorization | authorization | Configure generic authorization to the endpoint. | no |
oauth2 | oauth2 | Configure OAuth2 for authenticating to the endpoint. | no |
oauth2 > tls_config | tls_config | Configure TLS settings for connecting to the endpoint. | no |
tls_config | tls_config | 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.
extra_query_matchers block
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 mimir.rules.kubernetes
component. The algorithm of adding the label matchers to queries is the same as the one provided by
promtool promql label-matchers set
command in promtool.
matcher block
The matcher
block describes a label matcher that will be added to each query found in PrometheusRule
CRDs.
The following arguments are supported:
Name | Type | Description | Default | Required |
---|---|---|---|---|
name | string | Name of the label to match. | yes | |
match_type | string | The type of match. One of = , != , =~ and !~ . | yes | |
value | string | Value of the label to match. | yes |
label_selector block
The label_selector
block describes a Kubernetes label selector for rule or namespace discovery.
The following arguments are supported:
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:
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
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
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
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
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
andca_file
cert_pem
andcert_file
key_pem
andkey_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
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 alloy
label set to yes
are included.
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, it is overwritten with "value1"
.
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
.
mimir.rules.kubernetes "default" {
address = "GRAFANA_CLOUD_METRICS_URL"
extra_query_matchers {
matcher {
name = "cluster"
match_type = "=~"
value = "prod-.*"
}
}
}
If a query in the form of up != 1
is found in PrometheusRule
CRDs,
it will be modified to up{cluster=~"prod-.*"} != 1
before sending it to Mimir.
The following example is an RBAC configuration for Kubernetes. It authorizes Alloy to query the Kubernetes REST API:
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