diff --git a/docs/sources/alerting/alerting-rules/alerting-migration/_index.md b/docs/sources/alerting/alerting-rules/alerting-migration/_index.md new file mode 100644 index 00000000000..50654a58f1d --- /dev/null +++ b/docs/sources/alerting/alerting-rules/alerting-migration/_index.md @@ -0,0 +1,78 @@ +--- +description: Use the Grafana Alerting import tool to convert your datasource managed alert rules into Grafana managed alert rules +labels: + products: + - cloud + - enterprise + - oss +title: Import data source-managed alert rules +menuTitle: Import to Grafana-managed alert rules +weight: 600 +refs: +--- + +# Import data source-managed alert rules + +Grafana provides an internal tool in Alerting which allows you to import Prometheus and Loki alert rules into Grafana-managed alert rules. + +## Before you begin + +The `alertingMigrationUI` and `grafanaManagedRecordingRulesDatasources` [feature flags](/docs/grafana/latest/setup-grafana/configure-grafana/feature-toggles/) needs to be enabled to use this feature. + +To use the migration tool, you need the following [RBAC permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/): + +- Alerting: Rules Writer +- Alerting: Set provisioning status +- Datasources: Reader +- Folders: Creator + {{< admonition type="note" >}} + The Folders permission is optional and only necessary if you want to create new folders for your target namespace. If your account doesn't have permissions to view a namespace, the tool creates a new one. It is a best practice to prepare an import plan before you convert all your alert rules. + {{< /admonition >}} + +## How it works + +When you use the import tool, a folder of data source-managed rules is copied to another folder as Grafana-managed alert rules, preserving the behavior of the rules, and the original alert rules are kept in their original location. + +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. +- The `missing_series_evals_to_resolve` is set to 1 for the new rules. +- The newly created rules are given unique UIDs. + +{{< admonition type="note" >}} +Plugin rules that have the label `__grafana_origin` are not included on alert rule imports. +{{< /admonition >}} + +## Import alert rules + +To convert data source-managed alert rules to Grafana managed alerts: + +1. Go to **Alerting > Alert rules**. + +1. Navigate to the Data source-managed alert rules section and click **Import to Grafana-managed rules**. + + The import alert rules page opens. + +1. In the Data source dropdown, select the Loki or Prometheus data source of the alert rules. + +1. In Additional settings, select a target folder or designate a new folder to import the rules into. + + If you import the rules into an existing folder, don't chose a folder with existing alert rules, as they could get overwritten. + +1. (Optional) Select a Namespace and/or Group to determine which rules are imported. + +1. (Optional) Turn on **Pause imported alerting rules**. + + Pausing stops alert rule evaluation and doesn’t create any alert instances for the newly created Grafana-managed alert rules. + +1. (Optional) Turn on **Pause imported recording rules**. + + Pausing stops alert rule evaluation behavior for the newly created Grafana-managed alert rules. + +1. Select which target data source the new recording rule is written to. + +1. Click **Import**. + + A preview shows the rules that will be imported. If your target folder contains folders with the same name of the imported folders, a warning displays to inform you. You can explore the warning to see a list of folders that might be overwritten. + + Click **Yes, import** to import the rules. diff --git a/docs/sources/alerting/alerting-rules/alerting-migration/migration-api.md b/docs/sources/alerting/alerting-rules/alerting-migration/migration-api.md new file mode 100644 index 00000000000..4a623513094 --- /dev/null +++ b/docs/sources/alerting/alerting-rules/alerting-migration/migration-api.md @@ -0,0 +1,113 @@ +--- +description: Use the Grafana Alerting API import tool to convert your datasource managed alert rules into Grafana managed alert rules +labels: + products: + - cloud + - enterprise + - oss +title: Import data source-managed alert rules with Grafana Mimirtool +menuTitle: API alert rules import +weight: 601 +refs: +--- + +# 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 + +The `grafanaManagedRecordingRulesDatasources` [feature flag](/docs/grafana/latest/setup-grafana/configure-grafana/feature-toggles/) needs to be enabled to use this feature. + +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](/docs/grafana/latest/administration/roles-and-permissions/access-control/): + +- 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](/docs/grafana/latest/administration/service-accounts/) + +## 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 coretextool + +You can use either [Mimirtool](/docs/mimir/latest/manage/tools/mimirtool/) or [`cortextool`](https://github.com/grafana/cortex-tools) (version `0.11.3` or later) to import your alert rules. For more information about Mimirtool commands, see the [Mimirtool documentation](/docs/mimir/latest/manage/tools/mimirtool/#rules). + +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-dev.net/api/convert/ MIMIR_AUTH_TOKEN= MIMIR_TENANT_ID=1 +``` + +For coretextool, you need to set `--backend=loki` to import Loki alert rules. For example: + +```bash +CORTEX_ADDRESS=/api/convert/ CORTEX_AUTH_TOKEN= CORTEX_TENANT_ID=1 cortextool rules --backend=loki list +``` + +Headers can be passed to the `mimirtool` or `coretextool` via `--extra-headers`. + +For more information about the Rule API points and examples of Mimirtool commands, see the [Mimir HTTP API documentation](/docs/mimir/latest/references/http-api/#ruler-rules:~:text=config/v1/rules-,Get%20rule%20groups%20by%20namespace,DELETE%20%3Cprometheus%2Dhttp%2Dprefix%3E/config/v1/rules/%7Bnamespace%7D,-Delete%20tenant%20configuration) for more information about the Rule API points and examples of Mimirtool commands. + +{{< admonition type="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. +{{< /admonition >}} + +### 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/ - Get rule groups in a specific namespace +GET /convert/prometheus/config/v1/rules// - 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/ - Create/update a single rule group in a namespace +``` + +Post rules also require the following header: +When posting rules: +`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` - Enter the UID of the target data source. +- `X-Grafana-Alerting-Folder-UID` - Enter the UID of the target destination folder for imported rules.