Import data source-managed alert rules with Grafana Mimirtool
Documentationbreadcrumb arrow Grafana documentationbreadcrumb arrow Alertingbreadcrumb arrow Configure alert rulesbreadcrumb arrow Import to Grafana-managed alert rulesbreadcrumb arrow API alert rules import
Grafana Cloud Enterprise Open source

Import data source-managed alert rules with Grafana Mimirtool

You can convert data source-managed alert rules to Grafana-managed alert rules with the Grafana import tool in the Grafana user interface, or you can convert them with the Grafana Mimirtool command-line tool. This guide tells you how to use Mimirtool to import your data source-managed alert rules.

Before you begin

To import recording rules, they must be configured, and the grafanaManagedRecordingRulesDatasources feature flag must be enabled.

To import data source-managed alert rules with Grafana Mimirtool, you need to have the Grafana Mimirtool command-line tool installed.

You need a service account the following RBAC permissions:

  • Alerting: Rules Reader
  • Alerting: Rules Writer
  • Alerting: Set provisioning status
  • Datasources: Reader
  • Folders: Creator
  • Folders: Reader
  • Folders: Writer

You also need to create a service account token with your service account. Refer to the documentation for more information on service accounts and service account tokens

How it works

When data source-managed alert rules are converted to Grafana-managed alert rules, the following are applied to the Grafana-managed alert rules:

  • All rules are given rule_query_offset offset value of 1m.
    Grafana OSS and Enterprise can configure this value in their conf:
    [unified_alerting.prometheus_conversion]
rule_query_offset = 1m
    If this value is set explicitly in a rule group, that value takes precedence over the configuration setting.
  • The missing_series_evals_to_resolve is set to 1 for the new rules.
  • The newly created rules are given unique UIDs.
    If you don’t want the UID to be automatically generated, you can specify a specific UID with the __grafana_alert_rule_uid__ label.

Import alert rules with Mimirtool or cortextool

You can use either Mimirtool or cortextool (version 0.11.3 or later) to import your alert rules. For more information about Mimirtool commands, see the Mimirtool documentation.

To convert your alert rules, use the following command prompt substituting the your URL and your service account token as indicated, followed by your intended Mimirtool command.

bash 
MIMIR_ADDRESS=https://<Grafana URL>.grafana-dev.net/api/convert/ MIMIR_AUTH_TOKEN=<your token ID> MIMIR_TENANT_ID=1

For cortextool, you need to set --backend=loki to import Loki alert rules. For example:

bash 
CORTEX_ADDRESS=<grafana url>/api/convert/ CORTEX_AUTH_TOKEN=<your token> CORTEX_TENANT_ID=1 cortextool rules --backend=loki list

Headers can be passed to the mimirtool or cortextool via --extra-headers.

For more information about the Rule API points and examples of Mimirtool commands, see the Mimir HTTP API documentation for more information about the Rule API points and examples of Mimirtool commands.

Note

To use the mimirtool rules sync command, you need to set the --concurrency parameter to 1 (--concurrency=1). The parameter defaults to 8, which may cause the API to return errors.

Compatible endpoints

The following are compatible API endpoints:

GET

GET /convert/prometheus/config/v1/rules - Get all rule groups across all namespaces
GET /convert/prometheus/config/v1/rules/<NamespaceTitle> - Get rule groups in a specific namespace
GET /convert/prometheus/config/v1/rules/<NamespaceTitle>/<Group> - Get a single rule group

POST

POST /convert/prometheus/config/v1/rules - Create/update multiple rule groups across multiple namespaces
POST /convert/prometheus/config/v1/rules/<NamespaceTitle> - Create/update a single rule group in a namespace

When posting rules, the following header is required: X-Grafana-Alerting-Datasource-UID - Supply the UID of the data source to use for queries.

Delete

DELETE /convert/prometheus/config/v1/rules/{NamespaceTitle} - Delete all alert rules in a namespace
DELETE /convert/prometheus/config/v1/rules/{NamespaceTitle}/{Group} - Delete a specific rule group

Optional Headers

Additional configuration headers for more granular import control include the following:

  • X-Grafana-Alerting-Recording-Rules-Paused - Set to “true” to import recording rules in paused state.
  • X-Grafana-Alerting-Alert-Rules-Paused - Set to “true” to import alert rules in paused state.
  • X-Grafana-Alerting-Target-Datasource-UID - The UID of the target data source for recording rules. If not specified, the value from X-Grafana-Alerting-Datasource-UID is used.
  • X-Grafana-Alerting-Folder-UID - Enter the UID of the target destination folder for imported rules.
  • X-Disable-Provenance - When present, imported rules won’t be marked as provisioned, which allows for them to be edited in the UI. Note that rules imported with this header won’t be visible in the GET endpoints of this API, as these endpoints only return rules that are provisioned and were specifically imported via this API.