Documentation OnCall Setup Migrate to IRM

Migrate from Grafana OnCall OSS to Grafana Cloud IRM

This guide provides step-by-step instructions for migrating from a self-managed Grafana OnCall OSS instance to Grafana Cloud IRM. You’ll learn how to migrate OnCall configurations, including integrations, escalation chains, routes, and on-call schedules, as well as guidance on using Terraform and the OnCall API for migration.

Migration approaches

There are two primary approaches for migrating from Grafana OnCall OSS to Grafana Cloud:

Automated migration with the Grafana Cloud Migration Assistant

The Grafana Cloud Migration Assistant provides the most streamlined migration option. It is available as a public preview in Grafana 11.2+, with the feature enabled by default in Grafana 11.5 and later. This tool automates the migration process by securely connecting your self-managed instance to Grafana Cloud.

The Migration Assistant supports transferring various resources, including:

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

This approach eliminates the need for coding expertise and provides real-time updates on migration status.

Manual migration

For users with earlier Grafana versions or those requiring more control over the migration process, a manual migration approach is available. This method requires exporting and reconfiguring OnCall resources in Grafana Cloud and is supported in all versions of Grafana OSS and Enterprise.

Migrating Grafana OnCall from OSS to Grafana Cloud

The recommended method for migrating OnCall configurations is Terraform, as it allows you to manage your resources as code. Alternatively, you can use the OnCall API for manual migration.

Using Terraform for OnCall migration

Terraform provides a structured and repeatable approach to migrating OnCall configurations between OSS and Cloud.

Set up Terraform for Grafana OnCall migration

1. Authenticate:

   • For OnCall OSS, create an API token from the Settings tab in your OSS instance.
   • Configure the Terraform provider with the token and specify the OnCall URL.

2. Define the Provider Configuration:

   • For OSS: Include the OnCall API URL.
   • For Grafana Cloud: No oncall_url parameter is needed.

hcl Copy

# For OSS (Source)
provider "grafana" {
  alias               = "oncall_source"
  oncall_access_token = "YOUR_OSS_API_TOKEN"
  oncall_url          = "https://your-oncall-oss-instance.com/api"
}

# For Cloud (Destination)
provider "grafana" {
  alias               = "oncall_destination"
  oncall_access_token = "YOUR_CLOUD_API_TOKEN"
}

Migrating OnCall components with Terraform

1. Migrating integrations

Integrations handle alerts from monitoring systems. To migrate:

1. Export existing integrations from OnCall OSS using Terraform’s data sources or the OnCall API.
2. Define new integrations in Grafana Cloud.

hcl Copy

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

2. Migrating escalation chains and routes

Escalation chains define how alerts are processed. To migrate:

1. Define escalation chains in Terraform.

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\""
}

3. Migrating on-call schedules

• For iCal-based schedules: Export the iCal URL and re-import it in Grafana Cloud.
• 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"
}

Manual migration using the OnCall API

If Terraform is not an option, you can manually migrate using the OnCall HTTP API.

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
   • Create resources in order: integrations → escalation chains → routes → schedules.

Migrating teams and users

Migrating Grafana teams

Grafana Teams manage user access and permissions. When migrating:

• Recreate teams in Grafana Cloud.
• Assign appropriate permissions to maintain security policies.
• If using identity providers, consider Team Sync for automated user management.

Migration best practices

• Test in a staging environment before migrating production resources.
• Plan for a cutover period where new alerts and schedules should not be created.
• Communicate the migration plan with stakeholders.
• Evaluate security considerations by reviewing Grafana Cloud’s security policies.

For additional migration tools and guidance, see our OSS Migrator.