Documentation Grafana Cloud Account management Migrate from Grafana OSS/Enterprise to Grafana Cloud

Migrate from Grafana OSS/Enterprise to Grafana Cloud

This migration guide is designed to assist Grafana OSS/Enterprise users in seamlessly transitioning to Grafana Cloud.

Grafana Cloud Migration Assistant

The Grafana Cloud Migration Assistant is available in Grafana 11.2+ as a public preview feature that automatically migrates data sources, dashboards, and folders from your Grafana OSS/Enterprise instance to Grafana Cloud.

To use the feature on your local instance:

1. Enable the feature toggle onPremToCloudMigrations.

   For more information on how to enable a feature toggle, refer to Configure feature toggles.

2. Navigate to Administration > General > Migrate to Grafana Cloud on your local or cloud instance and follow the steps there.

3. (Optional) If your local instance is running in Windows, some extra setup may be required.

After you connect your local stack to Grafana Cloud, click the Build Snapshot button to create an encrypted extract of your on-premise Grafana data. The snapshot ensures your migration data always remains protected at rest. After it’s created, only Grafana Cloud services can read its contents. Click Upload Snapshot to send the snapshot to Grafana Cloud and migrate those resources to your cloud stack.

During a migration, resource UIDs are preserved, allowing you to correlate your local and cloud resources. If you perform the same migration multiple times, resources in your Grafana Cloud stack that were previously migrated are updated. The assistant never modifies your on-prem resources or cloud resources that didn’t come from a snapshot.

Because the Grafana Cloud Migration Assistant does not yet migrate organizations or teams, your resources are migrated with default permissions. Ensure that you reconfigure permissions in your cloud stack as needed following a migration. Refer to Grafana Cloud user roles and permissions.

Workaround for “Access is denied” errors in Windows setups

Some Grafana instances running in Windows can encounter an access denied error when writing a snapshot. You can work around this by running Grafana as a docker container and connecting it to your local instance database. First, look at your Grafana Configuration and search for the [database]type property to determine if you are using SQLite, MySQL, or PostgreSQL.

If using SQLite

You can mount the directory containing your Grafana database file (called grafana.db by default) to the container, for example:

shell Copy

docker run --name=grafana -d -p 3000:3000 \
  -e "GF_FEATURE_TOGGLES_ENABLE=onPremToCloudMigrations" \
  -v <grafana_data_directory>:/var/lib/grafana \
  -e "GF_DATABASE_USER=root" \
  -e "GF_DATABASE_PASSWORD=password" \
  grafana/grafana-oss

If your grafana_data_directory is in Program Files or another write-protected directory, you may need to copy it to a different directory with write permissions.

If using MySQL or PostgreSQL

You can run the Grafana docker container with your database configuration passed in, for example:

shell Copy

docker run --name=grafana -d -p 3000:3000 \
        -e "GF_FEATURE_TOGGLES_ENABLE=onPremToCloudMigrations" \
        -e "GF_DATABASE_TYPE=mysql" \
        -e "GF_DATABASE_HOST=host.docker.internal:3306" \
        -e "GF_DATABASE_NAME=grafana" \
        -e "GF_DATABASE_USER=root" \
        -e "GF_DATABASE_PASSWORD=password" \
        grafana/grafana-oss

Make sure the database host is reachable from the docker container. If your database is running on the same host as Docker Desktop, use host.docker.internal instead of localhost.

Plan and perform a manual migration

If you need to migrate resources beyond what is supported by the Grafana Cloud Migration Assistant, you can migrate them manually with this guide. Moving your team from Grafana OSS/Enterprise to Grafana Cloud manually involves some coordination and communication in addition to the technical migration in the following documentation.

If you are an existing Grafana OSS/Enterprise customer, contact your account team at Grafana Labs to plan a transition period, arrange licenses, and learn how much your Grafana Cloud subscription costs in comparison to Grafana OSS/Enterprise. The account team can also offer specific guidance and arrange professional services to assist with your migration if needed.

Evaluate Grafana Cloud’s security and compliance policies at the Grafana Labs Trust Center.

You may choose to test Grafana Cloud for some time before migrating your entire organization. To do so, set up a “test” stack in Cloud and migrate resources there first. If you use Grafana Alerting, make sure to set up a different contact point so that alerts do not fire twice.

When you decide to migrate, set aside a day of cutover during which users should not create new dashboards or alerts. Migrate any newly-created resources, turn on your production Alerting contact points and notification policies in Cloud and turn them off in Grafana OSS/Enterprise, and notify your users. You may also choose to redirect the Grafana OSS/Enterprise URL to your Grafana Cloud URL.

Prerequisites

Before starting the migration, ensure you have the following:

• A Grafana Cloud Stack and access to a Linux Machine (or a working WSL2 installation) to run the code snippets in this guide.
• Administrator access to a Grafana Cloud stack. To check you access level, Go to https://grafana.com/orgs/<your-org-name>/members
• Administrator access to your existing Grafana OSS/Enterprise instance. To check your access level, Go to https://<grafana-onprem-url>/admin/users
• Access to the credentials used to connect to your data sources. For example, API keys or usernames and passwords. Since this information is encrypted, it cannot be copied from one instance to the other.
• If some of your data sources are only available from inside your network, refer to the requirements for Private Data Source Connect
• For Plugins, Reports and Playlists only: The curl and jq command line tools

Upgrade Grafana OSS/Enterprise to the latest version

Grafana Cloud stacks generally run the latest version of Grafana. In order to avoid issues during migration, upgrade Grafana by following our guides here.

Migrate Grafana resources

In this guide, the term “resources” refers to things you create in Grafana, like dashboards, folders, alerts, data sources, and permissions.

The process of migration works by pulling the existing resources (like dashboards and folders) from the old Grafana instance, modifying them if necessary, and then pushing them to the new Grafana Cloud instance.

In the provided code snippets throughout this migration guide, you need to substitute specific placeholders with your actual credentials and instance URLs. Make the following replacements before executing the scripts:

• $GRAFANA_SOURCE_TOKEN with the access token from your Grafana OSS/Enterprise instance.
• $GRAFANA_DEST_TOKEN with the access token from your Grafana Cloud instance.
• $GRAFANA_ONPREM_INSTANCE_URL with the URL of your Grafana OSS/Enterprise instance. For example: https://grafana.mydomain.com
• $GRAFANA_CLOUD_INSTANCE_URL with the URL of your Grafana Cloud instance. For example: https://myorganization.grafana.net

Migrate Grafana Plugins

Migration of plugins is the first step when transitioning from Grafana OSS/Enterprise to Grafana Cloud, given that plugins are integral components that influence the functionality and display of other Grafana resources, such as dashboards.

1. To retrieve the Plugins installed in your Grafana OSS/Enterprise instance, issue an HTTP GET request to the /api/plugins endpoint. Use the following shell command:

   shell Copy

   response=$(curl -s -H "Accept: application/json" -H "Authorization: Bearer $GRAFANA_SOURCE_TOKEN" "${GRAFANA_ONPREM_INSTANCE_URL}/api/plugins")
   
   plugins=$(echo $response | jq '[.[] | select(.signatureType == "community" or (.signatureType != "internal" and .signatureType != "")) | {name: .id, version: .info.version}]')
   
   echo "$plugins" > plugins.json

   The command provided above will carry out an HTTP request to this endpoint and accomplish several tasks:

   • It issues a GET request to the /api/plugins endpoint of your Grafana OSS/Enterprise instance to retrieve a list of installed plugins.
   • It filters out the list to only include community plugins and those signed by external parties.
   • It extracts the plugin ID and version before storing them in a plugins.json file.

2. To import the plugins in your Grafana Cloud Instance, execute the following command. This command constructs an HTTP POST request to https://grafana.com/api/instances/<stack_slug>/plugins

   shell Copy

   CLOUD_INSTANCE=$GRAFANA_CLOUD_INSTANCE_URL
   
   stack_slug="${CLOUD_INSTANCE#*//}"
   stack_slug="${stack_slug%%.*}"
   jq -c '.[]' plugins.json | while IFS= read -r plugin; do
     name=$(echo "$plugin" | jq -r '.name')
     version=$(echo "$plugin" | jq -r '.version')
     echo "Adding plugin $name with version $version to stack $stack_slug"
     response=$(curl -s -X POST "https://grafana.com/api/instances/$stack_slug/plugins" \
               -H "Authorization: Bearer <GRAFANA_CLOUD_ACCESS_TOKEN>" \
               -H "Content-Type: application/json" \
               -d "{\"plugin\": \"$name\", \"version\": \"$version\"}")
     echo "POST response for plugin $name version $version: $response"
   done

   Replace <GRAFANA_CLOUD_ACCESS_TOKEN> with your Grafana Cloud Access Policy Token. To create a new one, refer Grafana Cloud Access Policies Documentation

   This script iterates through each plugin listed in the plugins.json file:

   • It constructs a POST request for each plugin to add it to the specified Grafana Cloud instance.
   • It reports back the response for each POST request to give you confirmation or information about any issues that occurred.

Migrate resources that are already provisioned as-code

If you already use tools like Terraform, Ansible, or Grafana’s HTTP API to provision resources to Grafana, redirect those to the new Grafana Cloud instance by replacing the Grafana URL and credentials.

Migrate dashboards, folders, data sources, library panels, and alert rules using Grizzly

Grizzly is a command line tool that streamlines working with Grafana resources. Use it to migrate most of the content in your Grafana instance. Follow these steps in your terminal to install Grizzly. If you need to change the os or the architecture, Refer to the Grizzly releases and use the binary according to your needs.

shell Copy

# download the binary (adapt os and arch as needed)
$ curl -fSL -o "/usr/local/bin/grr" "https://github.com/grafana/grizzly/releases/download/v0.3.1/grr-linux-amd64"

# make it executable
$ chmod a+x "/usr/local/bin/grr"

# have fun :)
$ grr --help

First, create a new folder on your computer and navigate to it to keep your work organized.

shell Copy

mkdir grafana-migration
cd grafana-migration

To give grizzly access to your Grafana OSS/Enterprise instance and the Grafana Cloud Instance, you need to create a service account and a corresponding access token on each instance. You can use these tokens to authenticate requests to pull and push resources. Follow these steps on your Grafana OSS/Enterprise instance:

• Navigate to the Administration -> Users and access -> Service Accounts Page within the Grafana OSS/Enterprise instance.
• Click on Add Service Account
• Give the Service account a descriptive name like “grizzly-migration” and apply the Admin role.
• After creating the account, click on Add Service Account Token
• Enter a name for the token
• Select Set expiration date and enter an expiry date for the token
• Click Generate Token and save this token in a password manager or other secure place.

Complete the service account creation and token generation process for your Grafana Cloud Instance by following the same steps outlined above for your Grafana OSS/Enterprise instance. This ensures that Grizzly has the necessary access token for both platforms.

Next, to tell grizzly which instances you’re going to work on, use the following commands:

shell Copy

grr config create-context grafana-onprem
grr config use-context grafana-onprem
grr config set output-format json
grr config set grafana.url $GRAFANA_ENT_INSTANCE_URL
grr config set grafana.token $GRAFANA_SOURCE_TOKEN

grr config create-context grafana-cloud
grr config use-context grafana-cloud
grr config set output-format json
grr config set grafana.url $GRAFANA_CLOUD_INSTANCE_URL
grr config set grafana.token $GRAFANA_DEST_TOKEN

Afterward, you will have two contexts set up; one for your local Grafana OSS/Enterprise installation and one for Grafana Cloud. The grr config use-context command allows you to switch between the two instances while using Grizzly.

Export existing resources

Switch to the grafana-onprem context and use the pull command to fetch the resources you want to migrate:

shell Copy

grr config use-context grafana-onprem
grr pull . \
  -t 'Dashboard/*' \
  -t 'Datasource/*' \
  -t 'DashboardFolder/*' \
  -t 'LibraryElement/*' \
  -t 'AlertRuleGroup/*' \
  -t 'AlertContactPoint/*' \
  -t 'AlertNotificationPolicy/*'

This will fetch the specified resources from Grafana and store them in the current directory.

Push the resources to your Grafana Cloud stack

With everything in place, switch to the Grafana cloud context and use the following commands to apply the resources to the configured instance:

shell Copy

grr config use-context grafana-cloud

grr apply . -t 'DashboardFolder/*'
grr apply . -t 'LibraryElement/*'
grr apply . -t 'Datasource/*'
grr apply . -t 'Dashboard/*'
grr apply . -t 'AlertRuleGroup/*'
grr apply . -t 'AlertContactPoint/*'
grr apply . -t 'AlertNotificationPolicy/*'

Fill in data source credentials

After migrating your data sources, you must fill in their credentials, like tokens, usernames, or passwords. For security reasons, grizzly cannot read encrypted data source credentials from the existing Grafana instance.

To fill in the missing authentication information, go to the Connections -> Datasources page in your new Grafana Cloud instance and verify that credentials for all data sources are set. You can skip data sources starting with grafanacloud - These are managed by Grafana Cloud directly and provide access to Grafana Cloud databases.

If one of your data sources can only be accessed from your internal network, take a look at the Private Data Source Connect documentation.

After you have configured the data sources, all your dashboards should be available as they were before.

(Optional) Configure Private Data Source Connect (PDC)

This step only applies if you use Grafana OSS/Enterprise to access network-secured data sources.

Some data sources, like Prometheus or SQL databases, live on private networks or behind firewalls that are not accessible by Grafana Cloud. If your Grafana OSS/Enterprise instance was hosted on the same network as your data source, you might find that Grafana Cloud cannot connect to all of the same data sources that Grafana OSS/Enterprise could access.

To access these data sources from Grafana Cloud, follow our guide to configure PDC in your network, and then configure the applicable Grafana data sources to connect using PDC. Note that PDC is only needed for your network-secured data sources, not for data sources like Splunk or CloudWatch that are accessible over the public internet.

For more information on how PDC works, see our overview document.

Migrate reports and playlists using Grafana’s HTTP API

Grizzly does not currently support Reports and Playlists as a resource, so you can perform this migration using Grafana’s HTTP API using the curl command.

Reports (For Grafana Enterprise only)

1. To export your Reports, you will need to invoke the api/reports endpoint of your Grafana OSS/Enterprise instance. The below shell command accomplishes this by using curl to send a request to the endpoint and then stores the retrieved report configuration into a file named reports.json.

   shell Copy

   curl ${GRAFANA_ONPREM_INSTANCE_URL}/api/reports -H "Authorization: Bearer $GRAFANA_SOURCE_TOKEN" > reports.json

2. To upload the configuration data you have saved in the reports.json file to your new Grafana Cloud instance, run the below command. The command will take the local file reports.json and push its contents to the api/reports endpoint of your Grafana Cloud instance.

   shell Copy

   jq -M -r -c '.[]' < reports.json | while read -r json; do curl -XPOST ${GRAFANA_CLOUD_INSTANCE_URL}/api/reports -H"Authorization: Bearer $GRAFANA_DEST_TOKEN" -d"$json" -H 'Content-Type: application/json'; done

Playlists

1. To retrieve the Playlists from your Grafana OSS/Enterprise instance, issue an HTTP GET request to the /api/playlists endpoint. Use the following shell command:

   shell Copy

   mkdir playlists
   curl "${GRAFANA_ONPREM_INSTANCE_URL}/api/playlists" \
   -H "Authorization: Bearer $GRAFANA_SOURCE_TOKEN" \
   | jq -M -r -c '.[] | .uid' \
   | while read -r uid; do \
   curl "${GRAFANA_ONPREM_INSTANCE_URL}/api/playlists/$uid" \
       -H "Authorization: Bearer $GRAFANA_SOURCE_TOKEN" \
       > playlists/$uid.json; \
   done

   The command provided above will carry out an HTTP request to this endpoint and accomplish several tasks:

   • It fetches an array of all the playlists available in the Grafana OSS/Enterprise instance.
   • It then iterates through each playlist to obtain the complete set of details.
   • Finally, it stores each playlist’s specification as separate JSON files within a directory named playlists

2. To import the playlists, execute the following command. This command constructs an HTTP POST request targeting the /api/playlists endpoint of your Grafana Cloud Instance.

   shell Copy

   for playlist in playlists/*; do
     curl -XPOST "${GRAFANA_CLOUD_INSTANCE_URL}/api/playlists" \
       -H "Authorization: Bearer $GRAFANA_DEST_TOKEN" \
       -H "Content-Type: application/json" \
       -d $playlist > /dev/null;
   done

Migrate single sign-on configuration

Grafana Cloud stacks support all of the same authentication and authorization options as Grafana OSS/Enterprise, except for [anonymous authentication])(/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/grafana/#anonymous-authentication) and use of the Auth proxy. However, single sign-on settings cannot be exported and imported like dashboards, alerts, and other resources.

To set up SAML authentication from scratch using Grafana’s UI or API, follow these instructions to Configure SAML authentication in Grafana.

LDAP and OIDC/OAuth2 can only be configured in Grafana Cloud by the Grafana Labs support team. Follow these instructions to request SSO configuration from the support team.

Migrate custom Grafana configuration

You may have customized the configuration of your Grafana OSS/Enterprise instance, for example with feature toggles, custom auth, or embedding options. Since Grafana configuration is stored in environment variables or the filesystem where Grafana runs, Grafana Cloud users do not have access to it. However, you can open a support ticket to ask a Grafana Labs support engineer for customizations.

The following customizations are available via support:

• Enabling feature toggles.
• Single sign-on and team sync using SAML, LDAP, or Oauth.
• Enable embedding Grafana dashboards in other applications for Grafana Cloud contracted customers.
• Audit logging (Usage insights logs and dashboards are available in Grafana Cloud Pro and Advanced by default).

Note that the following custom configurations are not supported in Grafana Cloud:

• Anonymous user access.
• Auth proxy.
• Third-party database encryption and the Hashicorp Vault integration.
• Running self-signed plugins, like custom-built data sources or visualizations. For more information on plugin signing, refer to our developer documentation.

If you have a custom configuration in Grafana OSS/Enterprise that is not listed here, reach out to our support team to find out whether they can help you set it up.

Next steps

After you have successfully migrated resources and configuration from Grafana OSS/Enterprise, consider the following steps to enhance your monitoring experience:

• Get started with Grafana Cloud: learn more about the functionality available in Grafana Cloud, which is not available in the open source or Enterprise editions. Read more in Get started with Grafana Cloud
• AWS PrivateLink for Grafana Cloud: securely transmit telemetry data from your AWS Virtual Private Cloud (VPC) to Grafana Cloud, entirely within the AWS network. Learn how to set this up with AWS PrivateLink Integration.
• Azure PrivateLink for Grafana Cloud, securely transmit telemetry from your Azure Virtual Network to Grafana Cloud while staying on the Azure network, and avoid exposing your traffic to the public internet. Learn how to set this up with AWS PrivateLink Integration.
• Grafana Integrations: ready-made integrations to make monitoring your infrastructure and applications more straightforward.