Documentation OnCall Setup Migrate to IRM

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-specific resources—including integrations, escalation chains, routes, and on-call schedules—using the OSS Migrator tool, Terraform, or the OnCall API.

Before you begin

Before starting migration, ensure you have the following:

• A Grafana Cloud account with access to Grafana Cloud IRM
• Admin access to your Grafana OnCall OSS instance
• An API token from your OnCall OSS instance (created from the Settings tab)
• An API token from your Grafana Cloud IRM instance

Migration approaches for OnCall resources

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

Migrate OnCall resources

Use the OSS Migrator tool

The OSS Migrator tool is purpose-built for migrating OnCall resources from OSS to Grafana Cloud IRM. This tool automates the export and import of OnCall configurations, including integrations, escalation chains, routes, and schedules.

For detailed usage instructions and configuration options, refer to the OSS Migrator documentation.

Use 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.

Set up Terraform providers

Configure separate Terraform providers for your source (OSS) and destination (Cloud) instances:

hcl Copy

# For OSS (Source)
provider "grafana" {
  alias               = "oncall_source"
  oncall_access_token = "<OSS_API_TOKEN>"
  oncall_url          = "https://<ONCALL_OSS_INSTANCE>/api"
}

# For Cloud (Destination)
provider "grafana" {
  alias               = "oncall_destination"
  oncall_access_token = "<CLOUD_API_TOKEN>"
}

Replace the following:

• <OSS_API_TOKEN>: Your OnCall OSS API token
• <ONCALL_OSS_INSTANCE>: The URL of your OnCall OSS instance
• <CLOUD_API_TOKEN>: Your Grafana Cloud IRM API token

Migrate integrations

Integrations handle alerts from monitoring systems. Export existing integrations from OnCall OSS and define them in Grafana Cloud:

hcl Copy

resource "grafana_oncall_integration" "example_integration" {
  provider = grafana.oncall_destination
  name     = "Example Integration"
  type     = "webhook"
}

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" "critical_escalation" {
     provider = grafana.oncall_destination
     name     = "Critical Alerts Escalation"
   }

2. Connect integrations to escalation chains using routes:

   hcl Copy

   resource "grafana_oncall_route" "database_critical_route" {
     provider             = grafana.oncall_destination
     integration_id       = grafana_oncall_integration.example_integration.id
     escalation_chain_id  = grafana_oncall_escalation.critical_escalation.id
     routing_regex        = "payload.severity == \"critical\""
   }

Migrate on-call schedules

For iCal-based schedules, export the iCal URL from your OSS instance and import it in Grafana Cloud IRM.

For web-based schedules, recreate schedules using Terraform:

hcl Copy

resource "grafana_oncall_schedule" "team_schedule" {
  provider = grafana.oncall_destination
  name     = "Team On-Call Rotation"
  type     = "web"
}

Use 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.