Migrate alerting rules and receivers from Prometheus

This page describes how to migrate Prometheus alerting rules to Cloud Monitoring alerting policies with a PromQL query. The migration process is useful if you use PromQL in environments outside Google Cloud. By migrating your Prometheus alerting rules to Cloud Monitoring, you can manage all of your alerting policies in one environment.

For general information, see Alerting policies with PromQL.

Migrate alert rules and receivers from Prometheus

The Google Cloud CLI lets you migrate your Prometheus alerting rules to PromQL-based Monitoring alerting policies by using the gcloud alpha monitoring policies migrate command. The command also lets you migrate your Prometheus receivers to Monitoring notification channels.

To migrate an alerting rule, you must have a YAML or JSON Prometheus rule file file that contains the alerting rule.
To migrate a receiver, you must a YAML or JSON Prometheus Alertmanager file that contains the receiver.

Note: You can migrate an AlertManager receiver only when Cloud Monitoring supports the same type of notification channel. For example, Cloud Monitoring doesn't support Jira receivers, so they can't be migrated from a Prometheus AlertManager file. If you try to migrate an incompatible receiver, then the gcloud CLI ignores the receiver. If you want to use a receiver that Cloud Monitoring doesn't support, then create a notification channel that uses Webhook for private endpoints or Pub/Sub for private endpoints.

Create an alerting policy from a Prometheus configuration file

To create an alerting policy from a Prometheus configuration file, run the following command. You can create multiple alerting policies by providing multiple file paths:

gcloud alpha monitoring policies migrate \
--policy-from-alert-rules-yaml=PATH_TO_FILE_1,PATH_TO_FILE_2

Create notification channels from a Prometheus Alertmanager configuration file

To create notification channels from a Prometheus Alertmanager configuration file, run the following command:

gcloud alpha monitoring policies migrate \
--channels-from-alertmanager-yaml=PATH_TO_FILE

Create alerting policies and notification channels at the same time

To create alerting policies from Prometheus configuration files and to create notification channels from a Prometheus Alertmanager configuration file at the same time, run the following command:

gcloud alpha monitoring policies migrate \
--policies-from-prometheus-alert-rules-yaml=PATH_TO_FILE_1,PATH_TO_FILE_2 \
--channels-from-prometheus-alertmanager-yaml=PATH_TO_FILE

Example

You have a Prometheus configuration file with an alert rule that sends out an alert when CPU utilization stays above 75% for one minute. The alert rule is configured as follows:

groups:
- name: Utilization_Alerts
  interval: 30s
  rules:
  - alert: CPU_Utilization_Over_75
    expr: compute_googleapis_com:instance_cpu_utilization > 75
    for: 60s
    labels:
      severity: page
    annotations:
      subject: "Subject: ${metric.label.value}"
      description: "CPU utilization is over 75%"

You also have a Prometheus AlertManager file that contains email, PagerDuty, and webhook receivers.

receivers:
- name: 'team-emails'
  email_configs:
  - to: EMAIL_ADDRESS
- name: 'team-pager'
  pagerduty_configs:
  - service_key: SERVICE_KEY
- name: 'team-webhook'
  webhook_configs:
  - url: WEBHOOK_ADDRESS

To create the alerting policy and notification channel, run the following command:

gcloud alpha monitoring policies migrate \
--policies-from-prometheus-alert-rules-yaml=PATH_TO_CONFIG_FILE \
--channels-from-alertmanager-yaml=PATH_TO_ALERTMANAGER_FILE

The gcloud CLI then creates an alerting policy like the following example:

  {
  "name": "projects/PROJECT_ID/alertPolicies/POLICY_ID",
  "displayName": "Utilization_Alerts/CPU_Utilization_Over_75",
  "documentation": {
    "content": "CPU utilization is over 75%",
    "mimeType": "text/markdown",
    "subject": "Subject: ${metric.label.value}"
  },
  "userLabels": {},
  "conditions": [
    {
      "name": "projects/PROJECT_ID/alertPolicies/POLICY_ID/conditions/CONDITION_ID",
      "displayName": "CPU_Utilization_Over_75"
    }
  ],
  "alertStrategy": {},
  "combiner": "OR",
  "enabled": true,
  "notificationChannels": [
    "projects/google.com:PROJECT_ID/notificationChannels/CHANNEL_ID_1",
    "projects/google.com:PROJECT_ID/notificationChannels/CHANNEL_ID_2",
    "projects/google.com:PROJECT_ID/notificationChannels/CHANNEL_ID_3"
  ]
}