Grafana dashboards migration reduce manual steps

[DavidQuan-vmware]

Proposal

Is it possible to enhance the migration tool to make the migration process smoother and reduce manual steps, such as modifying datasource name and changing metadata names.

[AntoineThebaud]

Could you detail how you imagine we could automate the filling of datasource name & adjusting metadata, as today we are expecting user inputs for these?

Btw if you have a mass migration to achieve, you should probably look at scripting something: I just saw we are lacking a proper documentation for the /migrate API, sorry for that, so putting the information there:

• if you are using Golang, you can rely on the client we provide https://github.com/perses/perses/blob/main/pkg/client/api/client.go#L29
• for anything else: the API endpoint is /api/migrate, POST call, and the expected body format is the following:

{
    "grafanaDashboard": {
        // full grafana dashboard, JSON format
    }
}

[szuecs]

I don't know if I should open another issue but it somehow also fits here.

I don't understand the migration from grafana guide at all. https://perses.dev/perses/docs/migration/ Something I miss, but what?

My steps

I have a super basic, empty config:

/perses# cat config.yaml
api_prefix: /api
security:
  encryption_key_file: ./secret.key
database:
  file:
    folder: "./data"
    extension: "json"
dashboard:
schemas:
provisioning:
datasource:
variable:
ephemeral_dashboards_cleanup_interval:
ephemeral_dashboard:
frontend:
plugin:

I started perses

perses --config config.yaml
..
⇨ http server started on 0.0.0.0:8080

steps to migrate:

percli login http://localhost:8080

# grafana dump dashboard to json
cat >grafana-dashboard.json
<paste grafana.json>

mkdir dashboards
percli migrate -f grafana-dashboard.json --online -o json > dashboards/perses-dashboard.json
percli apply -f dashboards/perses-dashboard.json
-> INFO[2025-06-19T11:47:11+02:00]                                               method=POST status=405 uri=/api/v1/dashboards

All steps worked but server said 405 Method Not Allowed.

[Nexucis]

Hi @szuecs , do you mind to try again without the api_prefix please ? I am suspecting the CLI doesn't consider the api_prefix configuration

[szuecs]

Without I get:

Error: something wrong happened with the request to the API.  Message: bad request: metadata.project cannot be empty StatusCode: 400

Browsing the UI works in both cases, if I start from localhost:8080/

[Nexucis]

ok great, thank you @szuecs.

So indeed the UI is much more advance to handle the api_prefix than the CLI.

And for the last issue you have, that's because the command migrate doesn't provide a way to set the project in the metadata. That's probably something we should propose. Like that it would avoid this kind of issue.

[szuecs]

I did not create a project in the UI, so if I created a project named "router" and then use --project router :

./percli apply -f data/dashboards/perses-dashboard.json  --project router

The import worked, but now I have a dashboard full of these errors:

No datasource found for kind 'PrometheusDatasource' and name '2WMX9zw7k'

I tried to configure a datasource in the config.yaml, but the keys like kind and name do not exist, but the json snippets show it (see also the json below).

I read again the migration docs and it says:

For example:

{
  "datasource": {
    "kind": "PrometheusDatasource",
    "name": "$datasource"
  }
}

You can transform it like this:

{
  "datasource": {
    "kind": "PrometheusDatasource"
  }
}

Maybe I miss understood and I have to modify the import file? So I did a little vim magic to modify the data/dashboards/perses-dashboard.json before import. Run the same again and I get this error: No datasource found for kind 'PrometheusDatasource' and name 'undefined'

I am a bit lost. What do I have to do to connect to my Prometheus process?

[Nexucis]

So here, it says there is no Prometheus Datasource configured.

The datasource is another object in Perses that should be created. That's not something you can create/configure using the config file config.yaml. See https://perses.dev/perses/docs/concepts/datasources/

In the UI, you create a datasource at project level or at global level.