Run PMM Client as a Docker container¶

The PMM Client Docker image provides a convenient way to run PMM Client as a pre-configured container without installing software directly on your host system.

Using the Docker container approach offers several advantages:

consistent environment across different operating systems
simplified setup and configuration process
automatic architecture detection (x86_64/ARM64)
centralized configuration management through PMM Server environment variables

Prerequisites¶

Complete these essential steps before installation:

Install Docker Engine.
Check system requirements to ensure your environment meets the minimum criteria.
Install and configure PMM Server as you’ll need its IP address or hostname to configure the Client.
Set up firewall rules to allow communication between PMM Client and PMM Server.
Create database monitoring users with appropriate permissions for the databases you plan to monitor.
Use PMM Client 3.10.0 or later. Earlier versions register the Node again on every container start, and PMM Server responds by removing the Node together with every service on it, so services are lost on restart regardless of the volume you give it.

Installation and setup¶

Deploy and register PMM Client¶

Deploy PMM Client with a fixed node name and a mounted volume for its configuration file so PMM Server can identify it across restarts, container re-creations, and image upgrades. Without these, a re-created container loses its identity and its monitored services.

PMM supports two authentication methods for registration: service account tokens (recommended) and username/password credentials.

To deploy and register PMM Client using Docker:

Pull the PMM Client Docker image:
```
docker pull percona/pmm-client:3
```
Start the PMM Client container and register it with PMM Server using the pmm-agent Setup mode. Replace X.X.X.X with the external IP address of your PMM Server:

Important

Do not use the --detach option with this command. The pmm-agent outputs logs directly to the console, and detaching would prevent you from seeing important setup information and potential errors.
Using Service accounts (Recommended)Standard authentication (Not recommended)
Service accounts provide secure, token-based authentication for registering nodes with PMM Server. Unlike standard user credentials, service account tokens can be easily rotated, revoked, or scoped to specific permissions without affecting user access to PMM.

To register with service accounts, create a service account then generate an authentication token that you can use to register the PMM Client:
1. Log into PMM web interface.
2. Navigate to Users and access > Service accounts.
3. Click Add service account.
4. Enter a descriptive name (e.g.: pmm-client-prod-db01). Keep in mind that PMM automatically shortens names exceeding 200 characters using a {prefix}_{hash} pattern.
5. Select the Admin role from the drop-down. For detailed information about what each role can do, see Role types in PMM.
6. Click Create > Add service account token.
7. (Optional) Name your token or leave blank for auto-generated name.
8. (Optional) Set expiration date for enhanced security. Expired tokens require manual rotation. Permanent tokens remain valid until revoked.
9. Click Generate Token.
10. Save your token immediately. It starts with glsa_ and won’t be shown again!
11. Run the container using the token:
  
  docker run \ --name pmm-client \ -e PMM_AGENT_SETUP_NODE_NAME=my_node_name \ -e PMM_AGENT_SETUP_NODE_TYPE=container \ -e PMM_AGENT_SERVER_ADDRESS=X.X.X.X:443 \ -e PMM_AGENT_SERVER_USERNAME=service_token \ -e PMM_AGENT_SERVER_PASSWORD=YOUR_GLSA_TOKEN \ -e PMM_AGENT_SERVER_INSECURE_TLS=1 \ -e PMM_AGENT_SETUP=1 \ -e PMM_AGENT_CONFIG_FILE=config/pmm-agent.yaml \ -v pmm-client-config:/usr/local/percona/pmm/config \ percona/pmm-client:3
  
  Parameters explained:
  
  PMM_AGENT_SETUP_NODE_NAME: name of the Node in PMM. Keep it fixed: it defaults to the hostname, which a re-created container does not keep, and pmm-agent setup stops if PMM Server has the pmm-agent registered under another name
  
  pmm-client-config: named volume holding pmm-agent.yaml with the identity PMM Server issued to the pmm-agent. Without it a re-created container has nothing to keep, and registering the same Node name again fails
  
  PMM_AGENT_SETUP_NODE_TYPE - (Optional) Node type: generic, container, etc.
  
  PMM_AGENT_SERVER_ADDRESS - Your PMM Server’s IP address or hostname
  
  service_token - Use this exact string as the username (not a placeholder!)
  
  YOUR_GLSA_TOKEN - The token you copied (starts with glsa_)
  
  PMM_AGENT_SERVER_INSECURE_TLS - Skip certificate validation (remove for production with valid certificates)
  
  You can find a complete list of compatible environment variables here.
This method exposes credentials in command history, process lists, and logs! Use only for testing or migration scenarios:
docker run \ --name pmm-client \ -e PMM_AGENT_SETUP_NODE_NAME=my_node_name \ -e PMM_AGENT_SETUP_NODE_TYPE=container \ -e PMM_AGENT_SERVER_ADDRESS=X.X.X.X:443 \ -e PMM_AGENT_SERVER_USERNAME=admin \ -e PMM_AGENT_SERVER_PASSWORD=admin \ -e PMM_AGENT_SERVER_INSECURE_TLS=1 \ -e PMM_AGENT_SETUP=1 \ -e PMM_AGENT_CONFIG_FILE=config/pmm-agent.yaml \ -v pmm-client-config:/usr/local/percona/pmm/config \ percona/pmm-client:3
Parameters explained:
- PMM_AGENT_SETUP_NODE_NAME - Name of the Node in PMM. Keep it fixed: it defaults to the hostname, which a re-created container does not keep, and pmm-agent setup stops when PMM Server has the pmm-agent registered under another name
- pmm-client-config - Named volume holding pmm-agent.yaml with the identity PMM Server issued to the pmm-agent. Without it a re-created container has nothing to keep, and registering the same Node name again fails
- PMM_AGENT_SETUP_NODE_TYPE - (Optional) Node type: generic, container, etc.
- PMM_AGENT_SERVER_ADDRESS - Your PMM Server’s IP address or hostname
- admin/admin - Default PMM Server username and password (change this immediately after first login)
You can find a complete list of compatible environment variables here.

To migrate to service accounts:
1. Create service accounts while still using standard authentication.
2. Test service account tokens on non-critical nodes.
3. Gradually migrate all nodes to token authentication.
4. Change the admin password from default.
5. Consider restricting or disabling direct admin account usage for node registration.

Important

If you get Failed to register pmm-agent on PMM Server: connection refused, this typically means that the IP address is incorrect or the PMM Server is unreachable.

Recovering a Node after losing the volume

If the volume is deleted while the Node still exists in PMM, the Client cannot register that Node name again and the container exits. Add -e PMM_AGENT_SETUP_FORCE=1 for one start to take the name over. PMM Server then removes the old Node together with every Service on it, so drop the variable again afterwards.

Verify the connection¶

Run the following command to check that PMM Client is properly connected and registered:

docker exec -t pmm-client pmm-admin status

If the connection is successful, you should also see an increased number of monitored nodes in the PMM user interface.

View your monitored node¶

To confirm your node is being monitored:

Go to the main menu and select Operating System > Overview.
In the Node Names drop-down menu, select the node you recently registered.
Modify the time range to view the relevant data for your selected node.

Add monitoring services¶

After installing PMM Client, you add database services to monitor with the pmm-admin command. Run it in the container once; the Node keeps the Services you add across restarts:

docker exec -t pmm-client pmm-admin add mysql --username=pmm --password=pass --query-source=perfschema --host=mysql-host

If you would rather declare the Services together with the container, use the PMM_AGENT_PRERUN_SCRIPT argument to pass a script with the pmm-admin add DATABASE [FLAGS] [NAME] [ADDRESS] commands. pmm-agent runs the script on every start, after setup. pmm-admin add reports a Service which exists already as an error, and a failing script stops the container, so make the script tolerate the Services it added on an earlier start, for example by appending || true to each command.

 docker run \
 --name pmm-client \
 -e PMM_AGENT_SETUP_NODE_NAME=my_node_name \
 -e PMM_AGENT_SETUP_NODE_TYPE=container \
 -e PMM_AGENT_SERVER_ADDRESS=X.X.X.X:443 \
 -e PMM_AGENT_SERVER_USERNAME=service_token \
 -e PMM_AGENT_SERVER_PASSWORD=YOUR_GLSA_TOKEN \
 -e PMM_AGENT_SERVER_INSECURE_TLS=1 \
 -e PMM_AGENT_SETUP=1 \
 -e PMM_AGENT_CONFIG_FILE=config/pmm-agent.yaml \
 -v pmm-client-config:/usr/local/percona/pmm/config \
 -e PMM_AGENT_PRERUN_SCRIPT=/opt/percona/pmm-prerun.sh \
 -v ./pmm-prerun.sh:/opt/percona/pmm-prerun.sh \
 percona/pmm-client:3

Tips for Docker configuration¶

Ensure your host’s firewall and routing rules are configured to allow Docker communications. This is crucial for Docker containers to communicate properly. For more details, see the troubleshooting checklist.
To view available pmm-agent command-line options, run: docker run --rm percona/pmm-client:3 --help