Grafana Cloud Enterprise Open source

Import Alertmanager configuration to Grafana-managed notifications

You can import an existing Prometheus or Mimir Alertmanager configuration into Grafana Alerting. Grafana runs the imported receivers as Mimir Alertmanager v0 integrations and surfaces the configuration as Grafana notification resources: contact points, a notification policy tree, notification templates, time intervals, and inhibition rules. You operate your notification setup from Grafana.

Importing is a safe operation. The source Alertmanager keeps its configuration, and Grafana never writes back to it.

The import happens in two stages:

  • Stage: Grafana keeps the imported configuration as a unit of its own and combines it with your Grafana resources at runtime.
  • Promote: Grafana merges the imported configuration permanently into your Grafana configuration. Every imported resource becomes a normal, editable Grafana resource, and you can no longer revert the import in one action.

Because Grafana keeps the staged configuration separate, you can revert or re-import it all at once instead of resource by resource. Its resources are read-only, and no Grafana resource can reference them. The imported policy tree is the exception: an alert rule can route to it by name. Until a rule does, your existing notifications are unchanged.

Note

Importing Alertmanager configuration is in public preview. The API is behind the alertingImportAlertmanagerAPI feature toggle and the user interface is behind alertingMigrationWizardUI. Both are disabled by default. In Grafana Cloud, contact Support to enable them.

Before you begin

Before you import an Alertmanager configuration, make sure you have the following:

  • A source Grafana can read: A configuration YAML file with its template files, or a configured Mimir Alertmanager data source. Prometheus Alertmanager data sources aren’t supported.
  • Permissions: Creating, reading, updating, or deleting an import requires the corresponding scoped Alertmanager import permissions. Promoting an import requires read and delete permissions for the import, create permissions for contact points and notification policy trees, and write permissions for any notification templates, time intervals, and inhibition rules in the configuration. The Admin role has these permissions by default. For more details, refer to RBAC permissions.

Not every Alertmanager configuration can be imported as-is. Refer to limitations before you start.

How it works

Grafana imports the configuration as it is and evaluates it the way your source Alertmanager does, for configurations from supported versions. Receivers keep their Alertmanager fields, and they notify with the same logic and message format, because Grafana runs them as Mimir-compatible integrations instead of rewriting them into native Grafana ones.

Mimir-compatible integrations don’t offer what a native Grafana integration adds on top, such as images in notifications. To use those features, promote the import and then rebuild the contact point as a Grafana one.

What gets imported

Grafana imports every field of the configuration: receivers, the routing tree, template files, time intervals, and inhibition rules. Fields keep their names and values, apart from the renames described in name conflicts. Both time_intervals and the deprecated mute_time_intervals become time intervals.

The global section is the one part with no place of its own. Grafana resolves its values into the settings of each integration that relies on them as the configuration is parsed, so the defaults you set globally still apply.

Routing

Grafana adds the imported routing tree as a named policy tree of its own, alongside your default notification policy and any other named policy trees. Alerts reach it only when an alert rule routes to it by name. The matchers inside the imported tree then route those alerts the way they did in your source Alertmanager. For more details on serving more than one policy tree, refer to manage multiple notification policies.

If the imported root route leaves group_wait, group_interval, or repeat_interval unset, Grafana uses the default notification timing values.

You choose the tree name when you import. This name is also the identifier of the import, so pick something you recognize, such as mimir-prod. The name can’t be default or match another named policy tree. It must be a valid DNS subdomain name and is length-limited; for more details, refer to limitations.

Name conflicts

Contact points, time intervals, and notification templates are identified by name, and the imported configuration may reuse names that already exist. Rather than fail or overwrite, Grafana renames the incoming resource:

  1. Grafana appends _ and the import identifier to the name, for example default becomes default_mimir-prod.
  2. If that name is also taken, Grafana appends a number, for example default_mimir-prod_01.

All references to a renamed resource are updated throughout the imported configuration, so routing still points at the right contact point.

Templates count conflicts differently. An imported template never conflicts with a Grafana-managed template of the same name, only with a template from another imported configuration. For more details, refer to limitations.

Staged resources are read-only

While an import is staged, its resources appear with an Imported status in the Grafana Alerting user interface and in the notification APIs, and you can’t edit or delete them individually. The deprecated provisioning API is the exception: it doesn’t return them at all.

You also can’t reference an imported resource from a Grafana resource. For example, you can’t pick an imported contact point in a Grafana notification policy. The imported policy tree is the exception: an alert rule can route to it by name while the import is staged.

To make imported resources editable and available for reference, promote the import.

One import at a time

Grafana stores one imported configuration per organization. Before you stage another configuration, promote or revert the existing one. You can also explicitly replace the existing configuration during import.

Import with the Grafana Alerting user interface

The Grafana Alerting user interface imports notification configuration and rules in one flow. It requires the alertingMigrationWizardUI feature toggle. Importing notification configuration also requires the alertingImportAlertmanagerAPI feature toggle. Without it, the notification configuration step is unavailable, and you can only import rules.

The import wizard is on the Import tab of the Grafana Alerting settings, which requires the Organization administrator role.

  1. Go to Alerting > Settings.

  2. Click the Import tab.

  3. On the Import notification configuration step, choose the Import source:

    • YAML file uploads a configuration file. Optionally, upload the template files the configuration references. Each file is imported as a template named after the file.
    • Data source reads the configuration from a configured Alertmanager data source.
  4. Enter a Policy tree name.

    Grafana validates the configuration as you fill in the form and reports any conflicts. The form lists the resources that Grafana renames before you import.

  5. Click Continue. On the Rules step, either configure the rules import or click Skip.

  6. Review the summary, then click Start import.

If a configuration is already staged, the Import notification configuration step shows it instead of the import form. Promote or revert it before you import another one, or click Continue to import rules only.

Auto-sync an Alertmanager configuration

Auto-sync keeps a staged notification configuration up to date with a Mimir or Cortex Alertmanager data source. Grafana periodically reads the source configuration and applies changes to the staged resources without writing back to the source. Auto-sync doesn’t import or synchronize alert rules.

Note

Auto-sync is in private preview. The alerting.syncExternalAlertmanager feature toggle is disabled by default and requires a Grafana restart when enabled. To access Settings > Import, also enable alertingMigrationWizardUI and alertingImportAlertmanagerAPI. In Grafana Cloud, contact Support to request access.

Enable auto-sync

Before you begin, configure a Mimir or Cortex Alertmanager data source. Auto-sync supports only these data sources. If a staged configuration with a different identifier already exists, promote or revert it first.

You need the following permissions, scoped to configs:uid:default:

  • notifications.alerting.grafana.app/configs:get to read the configuration and sync status.
  • notifications.alerting.grafana.app/configs:update to enable or disable auto-sync.

Organization administrators have these permissions by default. You can also grant them through RBAC.

  1. Go to Alerting > Settings.
  2. Click the Import tab.
  3. On the Import notification configuration step, select Data source as the Import source, and then select the Alertmanager data source.
  4. Select Auto-sync.
  5. Click Continue. Configure the rules import or click Skip.
  6. Review the summary, then click Enable auto-sync.

Grafana names the import, and the notification policy tree it creates, after the data source, for example mimir-prod for a data source called Mimir Prod. Grafana cuts the name to 40 characters. If a policy tree already uses that name, or the name is reserved for the default policy, the sync fails with identifier_taken and imports nothing. Rename the data source or the policy tree. The next sync then continues. The name doesn’t change if you rename the data source later. Configurations that started syncing before this naming use the data source UID instead. The imported resources remain read-only while staged. To send notifications through the imported policy tree, route your Grafana-managed alert rules to that tree.

After auto-sync is enabled, the Import notification configuration step shows the data source, the sync status, and any errors from the last sync attempt in one card, together with the resources the sync staged. If Grafana can’t fetch or validate an update, it keeps the configuration from the last successful sync.

While auto-sync is enabled, you can’t select a different data source. To sync from another data source, disable auto-sync, promote or revert the staged configuration, and then select the new data source.

Stop auto-sync or promote the configuration

While auto-sync is configured, you can’t manually import another notification configuration, and the user interface hides Revert for the sync-managed configuration. You can still import rules. The Import notification configuration step shows the synced configuration and its sync status. Click Continue to go to the rules import.

To stop synchronization, click Disable sync on the staged configuration and confirm. Disabling sync doesn’t delete the staged configuration. You can then review, promote, or revert it.

Promoting the sync-managed configuration stops synchronization from that data source.

If the staged configuration shows Managed by operator, you can’t change the setting through the user interface. In Grafana Cloud, contact Support to change or disable auto-sync.

Import with the API

The Alertmanager import endpoints are compatible with the Mimir Alertmanager HTTP API, so you can use mimirtool or plain HTTP requests.

In these endpoints, an import is addressed by its identifier, which is set with the X-Grafana-Alerting-Config-Identifier header and defaults to imported.

MethodEndpointSummary
POST/api/convert/api/v1/alertsImport an Alertmanager configuration, optionally promoting it in the same request.
GET/api/convert/api/v1/alertsGet the staged configuration. Secrets are masked.
DELETE/api/convert/api/v1/alertsDelete the staged configuration. The Grafana configuration is unaffected.
POST/api/convert/api/v1/alerts/{Identifier}/promotePromote a staged configuration into the Grafana configuration.

The POST endpoint accepts YAML and JSON. If no media type is specified, YAML is assumed. The request body has the same shape as the Mimir Alertmanager configuration API:

YAML
template_files:
  default.tmpl: '{{ define "custom" }}Custom message{{ end }}'
alertmanager_config: |
  route:
    receiver: webhook
  receivers:
    - name: webhook
      webhook_configs:
        - url: 'https://example.com/webhook'

Configuration validation errors

Grafana validates the submitted Alertmanager configuration before it stages or promotes it. Validation is strict:

  • Grafana rejects configurations that contain unknown fields instead of ignoring those fields. A single error response can report multiple unknown fields.
  • Grafana rejects unsupported integration types. The error response identifies the unsupported integration configuration field, such as its *_configs field.
  • Error responses identify the offending fields or integration types and include YAML line numbers when they are available.

For example, the following configuration contains an unknown email field and an unsupported integration type:

YAML
route:
  receiver: email
receivers:
  - name: email
    email_configs:
      - to: alerts@example.com
        typo_field: value
    foo_configs: [{}]

The error message reports both problems:

text
yaml: unmarshal errors:
  line 7: field typo_field not found in type config.plain
  line 8: field foo_configs not found in type config.plain

Alertmanager also performs semantic validation while it parses the configuration. As a result, a semantic validation error can appear before errors for unknown fields. Fix the reported error and submit the configuration again to find any remaining errors.

If validation fails, Grafana doesn’t stage or promote the submitted configuration. Existing staged and active configurations remain unchanged. Valid configurations that use supported fields and integration types continue to import as before.

A successful import returns the merge result:

JSON
{
  "status": "success",
  "stats": {
    "added_route": "mimir-prod",
    "added_receivers": ["webhook"],
    "added_templates": ["default.tmpl"]
  }
}

Configure auto-sync and read its status

Auto-sync uses a dedicated notification configuration API. Use credentials with the auto-sync permissions.

Note

Enable the alerting.syncExternalAlertmanager feature toggle before using this API. For availability and restart requirements, refer to Auto-sync an Alertmanager configuration.

The configuration is a per-organization resource named default. Grafana creates it automatically.

Read the configuration and status with GET /apis/notifications.alerting.grafana.app/v0alpha1/namespaces/{namespace}/configs/default:

sh
curl \
  -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>" \
  "<GRAFANA_BASE_URL>/apis/notifications.alerting.grafana.app/v0alpha1/namespaces/<NAMESPACE>/configs/default"

Replace the following placeholders in these examples:

  • <GRAFANA_BASE_URL>: The base URL of your Grafana instance.
  • <SERVICE_ACCOUNT_TOKEN>: A service account token with the required configuration permissions.
  • <NAMESPACE>: The API namespace for your Grafana organization.
  • <DATASOURCE_UID>: The UID of the Mimir or Cortex Alertmanager data source to synchronize.

Enable auto-sync with PATCH /apis/notifications.alerting.grafana.app/v0alpha1/namespaces/{namespace}/configs/default. Set spec.externalAlertmanagerSync.datasourceUid with a JSON patch:

sh
curl -X PATCH \
  -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>" \
  -H "Content-Type: application/json-patch+json" \
  "<GRAFANA_BASE_URL>/apis/notifications.alerting.grafana.app/v0alpha1/namespaces/<NAMESPACE>/configs/default" \
  --data '[{"op":"add","path":"/spec/externalAlertmanagerSync","value":{"datasourceUid":"<DATASOURCE_UID>"}}]'

A successful patch saves the setting; it doesn’t mean the first sync has completed. Read the resource again to inspect these status fields:

  • status.externalAlertmanagerSync.datasourceUid: The data source UID used on the last sync attempt.
  • status.externalAlertmanagerSync.origin: Whether the source is configured through the API or managed by an operator. For an operator-managed source in Grafana Cloud, contact Support to change or disable it.
  • status.conditions: Find the condition with type set to ExternalAlertmanagerSynced. Its status is True after a successful sync, False after a failed attempt, or Unknown when no sync is configured. Read reason and message for details. The MergeCommitted reason means the configuration was promoted and synchronization has stopped.

Status updates are asynchronous and can lag behind configuration changes.

To disable an API-configured sync, clear the setting with the same PATCH endpoint:

sh
curl -X PATCH \
  -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>" \
  -H "Content-Type: application/json-patch+json" \
  "<GRAFANA_BASE_URL>/apis/notifications.alerting.grafana.app/v0alpha1/namespaces/<NAMESPACE>/configs/default" \
  --data '[{"op":"add","path":"/spec/externalAlertmanagerSync","value":{}}]'

Clearing the setting stops future synchronization but doesn’t delete the staged notification resources. It doesn’t override an operator-managed source. Read the status again to confirm that synchronization is no longer configured. Don’t delete the default configuration resource or write its status; Grafana manages both its lifecycle and status.

Optional headers

Use these headers for more granular import control:

X-Grafana-Alerting-Config-Identifier

The identifier of the import, which is also the name of the notification policy tree it creates. It must be a valid DNS subdomain name of at most 40 characters, using only lowercase alphanumeric characters, -, and .. Defaults to imported.

X-Grafana-Alerting-Dry-Run

Set to true to validate the configuration and report the merge result without saving anything. Use this to preview renames before importing.

X-Grafana-Alerting-Promote

Set to true to promote the configuration in the same request instead of staging it. Combine it with X-Grafana-Alerting-Dry-Run to preview what a promotion merges into the live configuration.

X-Grafana-Alerting-Config-Force-Replace

Set to true to replace an existing staged configuration that has a different identifier. Without it, importing a second configuration fails.

mimirtool

Use mimirtool alertmanager load to import a configuration and its template files:

Bash
MIMIR_ADDRESS=<GRAFANA_BASE_URL>/api/convert/ \
MIMIR_AUTH_TOKEN=<SERVICE_ACCOUNT_TOKEN> \
MIMIR_TENANT_ID=1 \
mimirtool alertmanager load alertmanager.yaml default.tmpl \
  --extra-headers "X-Grafana-Alerting-Config-Identifier=mimir-prod"

Replace the following placeholders:

  • <GRAFANA_BASE_URL>: The base URL of your Grafana instance.
  • <SERVICE_ACCOUNT_TOKEN>: A service account token with permission to import notification resources.

When the address points at <GRAFANA_BASE_URL>/api/convert/, mimirtool talks to Grafana rather than to a Mimir instance, so MIMIR_TENANT_ID must always be 1.

mimirtool alertmanager get and mimirtool alertmanager delete read and remove the staged configuration in the same way.

Promote a staged configuration

To promote a configuration that’s already staged, call the promote endpoint with its identifier:

Bash
curl -X POST \
  -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>" \
  <GRAFANA_BASE_URL>/api/convert/api/v1/alerts/mimir-prod/promote

After promotion, the staged configuration no longer exists. Its resources are part of the Grafana configuration. You can edit them through the regular notification APIs and user interface.

Review, promote, or revert a staged configuration

Staged configurations are managed in Grafana Alerting settings.

  1. Go to Alerting > Settings.
  2. Click the Import tab.

On the Import notification configuration step, the Staged configuration section lists the contact points, notification policies, templates, time intervals, and inhibition rules the import contains, and links to each resource so you can inspect it before promoting.

To discard the import and everything it added, click Revert. Your Grafana configuration is unaffected. For a configuration managed by auto-sync, disable auto-sync before reverting. The user interface hides Revert while auto-sync is active. Deleting the staged configuration through the API doesn’t disable auto-sync: Grafana can import it again when the source configuration changes or Grafana restarts.

Warning

Reverting deletes the imported notification policy tree. Alert rules that route to that tree lose their target, and their alerts fall back to the root of your default notification policy. Update those rules to point elsewhere before you revert.

Limitations

Consider the following when you import an Alertmanager configuration:

  • Mimir version: Grafana supports notification configuration imports from Grafana Mimir up to 3.0.x. Later Mimir versions can use integrations and fields that the imported receivers don’t support.
  • Prometheus Alertmanager version: Grafana supports notification configuration imports from Prometheus Alertmanager up to v0.27. Later versions add integrations and fields that the imported receivers don’t support.
  • Unsupported receiver fields: Integration fields that read their values from elsewhere, including every *_file and *_ref variant, have no equivalent in Grafana. Grafana rejects a configuration that contains one, so nothing is imported. Supply the value inline in the matching field instead, and drop the _file or _ref variant.
  • Data source support: Grafana reads a configuration from a Mimir Alertmanager data source. Upstream Prometheus Alertmanager doesn’t expose a configuration API, so those data sources aren’t supported. Import a configuration YAML file instead.
  • Global settings: After you promote an import, the global section no longer exists as a section of its own. Grafana has resolved its values into each integration setting that relies on them, so a promoted contact point carries the resolved value rather than a reference to global.
  • Policy tree name: The name of the imported policy tree, which is also the import identifier, must be a valid DNS subdomain name of at most 40 characters, using only lowercase alphanumeric characters, -, and ..
  • One staged configuration at a time: Grafana stores one staged configuration per organization. Before you stage another configuration, promote or revert the existing one. You can also explicitly replace the existing configuration during import.
  • Template name conflicts across imports: Grafana renames colliding template files, but the templates defined inside those files share one namespace. Say an earlier import defines a template called default.email that renders X, and a new import defines default.email again, in a file under a different name, rendering Y. Which definition wins isn’t deterministic, and every contact point that uses that template gets the winner. As a result, contact points from the earlier import can start sending the wrong content. Check the names of the templates you define, not just the filenames, before you import a second configuration.
  • Deprecated provisioning API: A staged configuration isn’t visible in the deprecated provisioning API, which doesn’t return its contact points, templates, or time intervals. Use the Grafana Alerting notification API (notifications.alerting.grafana.app) instead.
  • Inhibition rules: Imported inhibition rules are supported through the API only. There’s no user interface for creating or editing them. For more details, refer to configure inhibition rules.

Next steps

After you import your notification configuration: