Documentation Grafana Cloud Alerts and IRM IRM Set up Migrate Migrate from OnCall OSS

Migrate from Grafana OnCall OSS to Grafana Cloud IRM

This guide provides instructions for migrating your self-managed Grafana OnCall OSS instance to Grafana Cloud IRM. You’ll learn how to migrate OnCall resources—including integrations, escalation chains, routes, and on-call schedules—using Terraform or the OnCall API.

Before you begin

Ensure you have the following:

• A Grafana Cloud account with access to Grafana Cloud IRM.
• Admin access to your Grafana OnCall OSS instance to document your current configuration.
• An API token from your Grafana Cloud IRM instance (created from the Settings page in the IRM plugin).
• For API-based migration: an API token from your OnCall OSS instance (created from the Settings tab in OnCall) to export resources programmatically.

Migration approaches

There are two recommended approaches for migrating OnCall configurations to Grafana Cloud IRM:

Migrate with Terraform

Terraform provides a structured and repeatable approach to migrating OnCall configurations. This method is ideal if you already manage infrastructure as code or want version-controlled migration.

The general workflow is:

1. Document your existing OnCall OSS configuration (integrations, escalation chains, routes, schedules).
2. Define equivalent resources in Terraform targeting your Grafana Cloud IRM instance.
3. Apply the Terraform configuration to create resources in IRM.
4. Update your alert sources to point to the new IRM integration URLs.

Set up the Terraform provider

Configure the Grafana Terraform provider to connect to your Grafana Cloud IRM instance:

hcl Copy

provider "grafana" {
  oncall_access_token = "<CLOUD_API_TOKEN>"
}

Replace <CLOUD_API_TOKEN> with your Grafana Cloud IRM API token.

Migrate integrations

Integrations handle alerts from monitoring systems. Recreate each integration from your OSS instance in Grafana Cloud IRM:

hcl Copy

resource "grafana_oncall_integration" "example_integration" {
  name = "Example Integration"
  type = "webhook"

  default_route {}
}

The default_route block is required. You can optionally set an escalation_chain_id inside it to define the default escalation behavior.

After creating the integration, update your monitoring systems to send alerts to the new integration URL.

Migrate escalation chains and routes

Escalation chains define how alerts are processed and who gets notified.

1. Define escalation chains:

   hcl Copy

   resource "grafana_oncall_escalation_chain" "critical_escalation" {
     name = "Critical Alerts Escalation"
   }

2. Connect integrations to escalation chains using routes:

   hcl Copy

   resource "grafana_oncall_route" "database_critical_route" {
     integration_id      = grafana_oncall_integration.example_integration.id
     escalation_chain_id = grafana_oncall_escalation_chain.critical_escalation.id
     routing_type        = "jinja2"
     routing_regex       = "{{ payload.severity == \"critical\" }}"
     position            = 0
   }

   The routing_type can be jinja2 (recommended) or regex (default). With Jinja2, you can write expressions like {{ payload.severity == "critical" and payload.service == "database" }}.

Migrate on-call schedules

For iCal-based schedules, export the iCal URL from your OSS instance and import it in Grafana Cloud IRM using the grafana_oncall_schedule resource with type = "ical" and your iCal URL.

For web-based schedules, recreate schedules using Terraform:

hcl Copy

resource "grafana_oncall_schedule" "team_schedule" {
  name      = "Team On-Call Rotation"
  type      = "web"
  time_zone = "America/New_York"
}

Web-based schedules also require on-call shifts defined using the grafana_oncall_on_call_shift resource to define rotation details (start time, duration, frequency, and assigned users).

For more Terraform examples, refer to the terraform/examples/ directory in the irm-tooling repository.

Migrate with the OnCall API

If Terraform isn’t suitable for your workflow, you can migrate using the OnCall HTTP API directly.

1. Export resources from your OSS instance: Use the API to list and export integrations, escalation chains, schedules, and routes.

2. Import resources into Grafana Cloud IRM: Create resources in this order to maintain dependencies:

   1. Integrations
   2. Escalation chains
   3. Routes
   4. Schedules

For API reference documentation, refer to OnCall API reference.

Migrate teams and users

Grafana Teams manage user access and permissions. When migrating teams and users to Grafana Cloud, you have several options:

Manually recreate teams

Recreate teams in Grafana Cloud and assign appropriate permissions to maintain your security policies.

Use SCIM provisioning

If your organization uses an identity provider that supports SCIM (System for Cross-domain Identity Management), you can automate user and team provisioning in Grafana Cloud. SCIM synchronizes users and groups from your identity provider to Grafana Cloud automatically.

For more information, refer to Configure SCIM provisioning.

Use Team Sync

If you use an identity provider for authentication, consider using Team Sync to automatically manage team membership based on your identity provider groups.

For more information, refer to Team sync.

Migrate other Grafana resources

If you’re also migrating dashboards, data sources, or other Grafana resources alongside OnCall, the Grafana Cloud Migration Assistant can help.

The Grafana Cloud Migration Assistant is available in Grafana 11.2+ as a public preview, with the feature enabled by default in Grafana 11.5 and later.

The Migration Assistant supports transferring:

• Dashboards
• Folders
• Data sources
• App and panel plugins
• Library panels
• Grafana Alerting resources

Migration best practices

• Test in a staging environment before migrating production resources.
• Plan for a cutover period during which you don’t create new alerts or schedules in the OSS instance.
• Migrate resources in order: integrations first, then escalation chains, routes, and finally schedules.
• Communicate the migration plan with your team and stakeholders.
• Verify migrated resources in Grafana Cloud IRM before decommissioning your OSS instance.
• Update alert sources: After migration, update your monitoring systems to point to the new Grafana Cloud IRM integration URLs.

Next steps

• Migrate to Grafana IRM manually for general Terraform or UI-based migration guidance
• Configure integrations
• Create on-call schedules
• Set up notifications
• Infrastructure as code for Grafana IRM