Migrate PMM 2 to PMM 3¶

PMM 3 introduces significant architectural changes that require gradual transition from PMM 2.

You can migrate to PMM 3 either automatically using the automated migration script (recommended), or manually by following step-by-step instructions.

To graduallly migrate to PMM 3:

Step 1: Upgrade PMM 2 Server to the latest version¶

Before migrating PMM 2 to PMM 3, ensure your PMM 2 Server is running the latest version:

From the Home page, scroll to the PMM Upgrade panel and click the Refresh button to manually check for updates.
If an update is available, click the Update button to install the latest PMM 2 version.
Verify the update was successful by checking the version number after the update completes.

Step 2: Migrate PMM 2 Server to PMM 3¶

Automated Docker migration (Recommended)Manual migration (Docker/Kubernetes/Podman/AMI/OVF)

Use this upgrade script for a simplified migration process:

Download and run the automated migration script to start the migration. The -b flag creates a backup of your PMM2 instance to ensure that your data is backed up before the migration.
```
./get-pmm.sh -n <container-name> -b
```
Note the backup volume name displayed during the migration (e.g., pmm-data-2025-01-16-165135) so that you can restore this backup if needed.
Check additional script options:
```
./get-pmm.sh -h
```

Restore PMM 2 backup

If you need to revert to the PMM 2 instance, restore the backup created above:

Stop the PMM 3 container:
```
docker stop pmm-server
```
Start a PMM 2 container using the backup volume, replacing <backup-volume-name> (e.g., pmm-data-2025-01-16-165135) with your actual backup volume name:
```
docker run -d -p 443:443 --volume <backup-volume-name>:/srv --name pmm-server --restart always percona/pmm-server:2.44.0
```
Verify that your PMM 2 instance is running correctly and all your data is accessible.

Docker with volumeDocker with data containerHelmPodmanAMI/OVF instance

Follow these manual steps to migrate your PMM 2 Server to PMM 3:

Stop all PMM Server services:

docker exec -t <pmm-server> supervisorctl stop all

Transfer /srv directory ownership:

docker exec -t <pmm-server> chown -R pmm:pmm /srv

List and note down your Docker volume:

docker inspect -f '{{ range .Mounts }}{{ if eq .Type "volume" }}{{ .Name }}{{ "\n" }}{{ end }}{{ end }}' <pmm-server>

Stop and remove existing container:

docker stop pmm-server && docker rm pmm-server

Pull PMM 3 Server image:
```
docker pull percona/pmm-server:3
```

Run new new version of PMM Server with the existing volume:

docker run -d -v pmm-server-data:/srv -p 443:8443 --name pmm-server --restart always percona/pmm-server:3

Follow these manual steps to upgrade your PMM 2 Server to PMM 3:

Stop all PMM Server services:

docker exec -t <pmm-server> supervisorctl stop all

Transfer /srv directory ownership:

docker exec -t <pmm-server> chown -R pmm:pmm /srv

Identify the data container using either:

docker ps -a --filter "status=created"

OR

docker inspect -f '{{ range .Mounts }}{{ if eq .Type "volume" }}{{ .Name }}{{ "\n" }}{{ end }}{{ end }}' <pmm-server>

Stop and remove the existing container:

docker stop pmm-server && docker rm pmm-server

Pull PMM 3 Server image:
```
docker pull percona/pmm-server:3
```

Run the new version of PMM Server with the existing data container:

docker run -d --volumes-from pmm-server-data -p 443:8443 --name pmm-server --restart always percona/pmm-server:3

Follow these steps to migrate your PMM 2 Server deployed with Helm to PMM 3:

Update the Percona Helm repository:
```
helm repo update percona
```

Export current values to a file:

helm show values percona/pmm > values.yaml

Update the values.yaml file to match your PMM 2 configuration

Stop all PMM Server services:

kubectl exec pmm-0 -- supervisorctl stop all

Transfer /srv directory ownership:

kubectl exec pmm-0 -- chown -R pmm:pmm /srv

Upgrade PMM using Helm:

helm upgrade pmm -f values.yaml --set podSecurityContext.runAsGroup=null --set podSecurityContext.fsGroup=null percona/pmm

If Kubernetes did not trigger the upgrade automatically, delete the pod to force recreation:
```
kubectl delete pod pmm-0
```

Follow these steps to migrate to PMM 3 a PMM 2 Server deployed with Podman:

Pull the PMM 3 Server image:
```
podman pull percona/pmm-server:3
```

Stop all PMM Server services:

podman exec pmm-server supervisorctl stop all

Transfer /srv directory ownership:

podman exec pmm-server chown -R pmm:pmm /srv

Remove the existing systemd service file:

rm ~/.config/systemd/user/pmm-server.service

Follow the installation steps from the PMM 3 Podman installation guide to complete the upgrade.

Follow these steps to migrate a PMM 2 Server deployed as an AMI/OVF instance to PMM 3:

Back up your current instance and keep your PMM 2 instance running until confirm a successful migration.
Deploy a new PMM 3 AMI/OVF instance.
On the new instance, stop the Podman service:
```
systemctl --user stop pmm-server
```
Clear the service volume directory:
```
rm -rf /home/admin/volume/srv/*
```
On the old instance, stop all services:
```
sudo supervisorctl stop all
```

Transfer data from old to new instance:

sudo scp -r /srv/* admin@newhost:/home/admin/volume/srv

Set proper permissions on the new instance:

chown -R admin:admin /home/admin/volume/srv/

Start the PMM service on the new instance:
```
systemctl --user start pmm-server
```
Verify that PMM 3 is working correctly with the migrated data.
Update PMM Client configurations by editing the /usr/local/percona/pmm2/config/pmm-agent.yml with the new server address, then restart the PMM Client.

Revert AMI/OVF instance to PMM 2

If you need to restore to the PMM 2 instance after the migration:

Access old instance via SSH.
Start services: supervisorctl start all.
Update client configurations to point to old instance.

Step 3: Migrate PMM 2 Clients to PMM 3¶

Important

PMM 3 Server provides limited support for PMM 2 Clients (metrics and Query Analytics only). This support will be removed in PMM 3.3.

Depending on your initial installation method, update PMM Clients using your operating system’s package manager or using a tarball. For detailed instructions, see the Upgrade PMM Client topic.

Step 4: Migrate your API keys to service accounts¶

PMM 3 replaces API keys with service accounts to enhance security and simplify access management. You can trigger this API key conversion from the UI or from the CLI.

From the UI¶

PMM automatically migrates existing API keys to service accounts when you first log in as an Admin user. The migration results are displayed in a popup dialog box.

If no popup appears, it likely means there are no API keys to migrate—this is typical for PMM Servers without connected services.

From CLI¶

You can also initiate the conversion using the following command. Be sure to replace admin:admin with your credentials and update the server address (localhost or 127.0.0.1) and port number (3000) if they differ from the defaults:

curl -X POST http://localhost:3000/api/serviceaccounts/migrate \
-u admin:admin \
-H "Content-Type: application/json

The response will display the migration details:

Expected output

{"total":3,"migrated":3,"failed":0,"failedApikeyIDs":[],"failedDetails":[]}

Verify the conversion¶

To verify the that API keys were successfully migrated, go to Administration > Users and Access > Service Accounts where you can check the list of service accounts available and confirm that the API Keys menu is no longer displayed.

If any API keys fail to migrate, you can either:

delete the problematic API keys and create new service accounts
keep using the existing API keys until you’re ready to replace them

Post-migration steps¶

After you finish migrating PMM:

Verify that all PMM Clients are up to date by checking PMM Configuration > Updates.
Confirm all previously monitored services are reporting correctly to the new PMM 3 Server by reviewing Configuration > PMM Inventory > Services.
Check the dashboards to make sure you’re receiving the metrics and QAN data.

Variables for migrating from PMM v2 to PMM v3¶

When migrating from PMM v2 to PMM v3, you’ll need to update your environment variables to match the new naming convention. This is because PMM v3 introduces several important changes to improve consistency and clarity:

environment variables now use PMM_ prefix
some boolean flags reversed (e.g., DISABLE_ → ENABLE_)
removed deprecated variables

Examples¶

# PMM v2
-e DISABLE_UPDATES=true -e DATA_RETENTION=720h

# PMM v3 equivalent
-e PMM_ENABLE_UPDATES=false -e PMM_DATA_RETENTION=720h

Migration reference table¶

The following table lists all the environment variable changes between PMM v2 and PMM v3. Make sure to review this table when updating your deployment configurations.

Click to expand migration reference table

Configuration variables¶

PMM 2	PMM 3	Comments
`DATA_RETENTION`	`PMM_DATA_RETENTION`
`DISABLE_ALERTING`	`PMM_ENABLE_ALERTING`
`DISABLE_UPDATES`	`PMM_ENABLE_UPDATES`
`DISABLE_TELEMETRY`	`PMM_ENABLE_TELEMETRY`
`DISABLE_BACKUP_MANAGEMENT`	`PMM_ENABLE_BACKUP_MANAGEMENT`	Note the reverted boolean
`ENABLE_AZUREDISCOVER`	`PMM_ENABLE_AZURE_DISCOVER`
`ENABLE_RBAC`	`PMM_ENABLE_ACCESS_CONTROL`
`LESS_LOG_NOISE`		Removed in PMM v3

Metrics configuration¶

PMM 2	PMM 3
`METRICS_RESOLUTION`	`PMM_METRICS_RESOLUTION`
`METRICS_RESOLUTION_HR`	`PMM_METRICS_RESOLUTION_HR`
`METRICS_RESOLUTION_LR`	`PMM_METRICS_RESOLUTION_LR`
`METRICS_RESOLUTION_MR`	`PMM_METRICS_RESOLUTION_MR`

ClickHouse configuration¶

PMM 2	PMM 3	Comments
`PERCONA_TEST_PMM_CLICKHOUSE_ADDR`	`PMM_CLICKHOUSE_ADDR`
`PERCONA_TEST_PMM_CLICKHOUSE_DATABASE`	`PMM_CLICKHOUSE_DATABASE`
`PERCONA_TEST_PMM_CLICKHOUSE_DATASOURCE`	`PMM_CLICKHOUSE_DATASOURCE`
`PERCONA_TEST_PMM_CLICKHOUSE_HOST`	`PMM_CLICKHOUSE_HOST`
`PERCONA_TEST_PMM_CLICKHOUSE_PORT`	`PMM_CLICKHOUSE_PORT`
`PERCONA_TEST_PMM_DISABLE_BUILTIN_CLICKHOUSE`	`PMM_DISABLE_BUILTIN_CLICKHOUSE`
`PERCONA_TEST_PMM_CLICKHOUSE_BLOCK_SIZE`		Removed in PMM v3, new version
`PERCONA_TEST_PMM_CLICKHOUSE_POOL_SIZE`		Removed in PMM v3, new version

PostgreSQL configuration¶

PMM 2	PMM 3
`PERCONA_TEST_POSTGRES_ADDR`	`PMM_POSTGRES_ADDR`
`PERCONA_TEST_POSTGRES_DBNAME`	`PMM_POSTGRES_DBNAME`
`PERCONA_TEST_POSTGRES_USERNAME`	`PMM_POSTGRES_USERNAME`
`PERCONA_TEST_POSTGRES_DBPASSWORD`	`PMM_POSTGRES_DBPASSWORD`
`PERCONA_TEST_POSTGRES_SSL_CA_PATH`	`PMM_POSTGRES_SSL_CA_PATH`
`PERCONA_TEST_POSTGRES_SSL_CERT_PATH`	`PMM_POSTGRES_SSL_CERT_PATH`
`PERCONA_TEST_POSTGRES_SSL_KEY_PATH`	`PMM_POSTGRES_SSL_KEY_PATH`
`PERCONA_TEST_POSTGRES_SSL_MODE`	`PMM_POSTGRES_SSL_MODE`
`PERCONA_TEST_PMM_DISABLE_BUILTIN_POSTGRES`	`PMM_DISABLE_BUILTIN_POSTGRES`

Telemetry & development¶

PMM 2	PMM 3
`PMM_TEST_TELEMETRY_DISABLE_SEND`	`PMM_DEV_TELEMETRY_DISABLE_SEND`
`PERCONA_TEST_TELEMETRY_DISABLE_START_DELAY`	`PMM_DEV_TELEMETRY_DISABLE_START_DELAY`
`PMM_TEST_TELEMETRY_FILE`	`PMM_DEV_TELEMETRY_FILE`
`PERCONA_TEST_TELEMETRY_HOST`	`PMM_DEV_TELEMETRY_HOST`
`PERCONA_TEST_TELEMETRY_INTERVAL`	`PMM_DEV_TELEMETRY_INTERVAL`
`PERCONA_TEST_TELEMETRY_RETRY_BACKOFF`	`PMM_DEV_TELEMETRY_RETRY_BACKOFF`
`PERCONA_TEST_VERSION_SERVICE_URL`	`PMM_DEV_VERSION_SERVICE_URL`
`PERCONA_TEST_STARLARK_ALLOW_RECURSION`	`PMM_DEV_ADVISOR_STARLARK_ALLOW_RECURSION`

Removed variables¶

PMM 2	PMM 3	Comments
`PERCONA_TEST_AUTH_HOST`		Removed, use `PMM_DEV_PERCONA_PLATFORM_ADDRESS`
`PERCONA_TEST_CHECKS_HOST`		Removed, use `PMM_DEV_PERCONA_PLATFORM_ADDRESS`
`PERCONA_TEST_CHECKS_INTERVAL`		Removed, not used
`PERCONA_TEST_CHECKS_PUBLIC_KEY`		Removed, use `PMM_DEV_PERCONA_PLATFORM_PUBLIC_KEY`
`PERCONA_TEST_NICER_API`		Removed in PMM v3
`PERCONA_TEST_SAAS_HOST`		Removed, use `PMM_DEV_PERCONA_PLATFORM_ADDRESS`