Run PMM Client as a Kubernetes pod¶

Deploy the PMM Client Docker image as a Kubernetes pod to monitor your databases without installing software on your host system.

This deployment approach provides:

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

Prerequisites¶

Before deploying PMM Client:

Install kubectl.
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.

Installation and setup¶

Deploy PMM Client¶

Choose your deployment approach:

Standalone: Deploy PMM Client as a dedicated pod to monitor external databases
Sidecar: Deploy PMM Client alongside a database in the same pod

Deploy PMM Client as a Standalone containerDeploy PMM Client as a Sidecar container

Follow these steps to deploy PMM Client using kubectl:

(Optional) Create a namespace for the deployment and set it as the default namespace:

kubectl create namespace pmm-client-test
kubectl config set-context --current --namespace=pmm-client-test

Create pmm-client-volume.yaml to define persistent storage for PMM Client data between pod restarts:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pmm-client-pv
  labels:
    type: local
spec:
  storageClassName: manual
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: "/mnt/data"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pmm-client-pvc
spec:
  storageClassName: manual
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

Create the resources defined in pmm-client-volume.yaml
```
kubectl apply -f pmm-client-volume.yaml
```

Create a Secret to store PMM Server credentials. Replace admin password if you changed it during PMM Server setup:

kubectl create secret generic pmm-secret \
--from-literal=PMM_AGENT_SERVER_USERNAME=admin \
--from-literal=PMM_AGENT_SERVER_PASSWORD=admin

Create pmm-client-pod.yaml to define a Pod running PMM Client. Replace X.X.X.X with the IP address of your PMM Server:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: pmm-client
spec:
  selector:
    matchLabels:
      app: pmm-client
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: pmm-client
    spec:
      containers:
        - name: pmm-client
          image: percona/pmm-client:3
          volumeMounts:
            - name: pmm-client-storage
              mountPath: /usr/local/percona/pmm/tmp
          env:
            - name: PMM_AGENT_SERVER_ADDRESS
              value: X.X.X.X:443
            - name: PMM_AGENT_SERVER_USERNAME
              valueFrom:
                secretKeyRef:
                  name: pmm-secret
                  key: PMM_AGENT_SERVER_USERNAME
            - name: PMM_AGENT_SERVER_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: pmm-secret
                  key: PMM_AGENT_SERVER_PASSWORD
            - name: PMM_AGENT_SERVER_INSECURE_TLS
              value: "1"
            - name: PMM_AGENT_CONFIG_FILE
              value: config/pmm-agent.yaml
            - name: PMM_AGENT_SETUP
              value: "1"
            - name: PMM_AGENT_SETUP_FORCE
              value: "1"
      volumes:
        - name: pmm-client-storage
          persistentVolumeClaim:
            claimName: pmm-client-pvc

Security note

The PMM_AGENT_SERVER_INSECURE_TLS=1 setting disables TLS certificate verification. For production environments, configure proper TLS certificates and remove this setting.

Deploy PMM Client pod and configure the pmm-agent in Setup mode to connect to PMM Server:
```
kubectl apply -f pmm-client-pod.yaml
```

Important

You can set the container environment variable PMM_AGENT_PRERUN_SCRIPT to a shell script to automatically add services to PMM for monitoring.

Follow these steps to deploy PMM Client as a Sidecar container to a MySQL container using kubectl:

(Optional) Create a namespace named pmm-client-test for the deployment and set it as the default namespace:

kubectl create namespace pmm-client-test
kubectl config set-context --current --namespace=pmm-client-test

Create mysql-pmm-client-volume.yaml to define persistent storage for storing PMM Client and MySQL data between pod restarts:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pmm-client-pv
  labels:
    type: local
spec:
  storageClassName: manual
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: "/mnt/data/pmm-client"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pmm-client-pvc
spec:
  storageClassName: manual
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: mysql-pv-volume
  labels:
    type: local
spec:
  storageClassName: manual
  capacity:
    storage: 20Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: "/mnt/data/mysql"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mysql-pv-claim
spec:
  storageClassName: manual
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi

Create the resources defined in mysql-pmm-client-volume.yaml
```
kubectl apply -f mysql-pmm-client-volume.yaml
```
Create a Secret to store the credentials for PMM Server authentication. Update PMM_AGENT_SERVER_PASSWORD value if you changed the default admin password during setup:
```
kubectl create secret generic pmm-secret \
 --from-literal=PMM_AGENT_SERVER_USERNAME=admin \
 --from-literal=PMM_AGENT_SERVER_PASSWORD=admin
```

Create a Secret to store the MySQL root password:

kubectl create secret generic mysql-secret \
 --from-literal=MYSQL_ROOT_PASSWORD=very_secure_password

Create mysql-pmm-client-pod.yaml to define a Pod running MySQL 9.0 container with a PMM Client container running as Sidecar. Replace X.X.X.X with the IP address of your PMM Server:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mysql
spec:
  selector:
    matchLabels:
      app: mysql
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
        - name: mysql
          image: mysql:9
          resources: {}
          env:
            - name: MYSQL_ROOT_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: mysql-secret
                  key: MYSQL_ROOT_PASSWORD
          ports:
            - containerPort: 3306
              name: mysql
          volumeMounts:
            - name: mysql-persistent-storage
              mountPath: /var/lib/mysql
        - name: pmm-client
          image: percona/pmm-client:3
          env:
            - name: PMM_AGENT_SERVER_ADDRESS
              value: X.X.X.X:443
            - name: PMM_AGENT_SERVER_USERNAME
              valueFrom:
                secretKeyRef:
                  name: pmm-secret
                  key: PMM_AGENT_SERVER_USERNAME
            - name: PMM_AGENT_SERVER_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: pmm-secret
                  key: PMM_AGENT_SERVER_PASSWORD
            - name: MYSQL_ROOT_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: mysql-secret
                  key: MYSQL_ROOT_PASSWORD
            - name: PMM_AGENT_SERVER_INSECURE_TLS
              value: "1"
            - name: PMM_AGENT_CONFIG_FILE
              value: config/pmm-agent.yaml
            - name: PMM_AGENT_SETUP
              value: "1"
            - name: PMM_AGENT_SETUP_FORCE
              value: "1"
            - name: PMM_AGENT_SIDECAR
              value: "1"
            - name: PMM_AGENT_PRERUN_SCRIPT
              value: "pmm-admin status --wait=10s; pmm-admin add mysql --username=root --password=${MYSQL_ROOT_PASSWORD} --query-source=perfschema"
      volumes:
        - name: mysql-persistent-storage
          persistentVolumeClaim:
            claimName: mysql-pv-claim
        - name: pmm-client-storage
          persistentVolumeClaim:
            claimName: pmm-client-pvc

Security note

The PMM_AGENT_SERVER_INSECURE_TLS=1 setting disables TLS certificate verification. For production environments, configure proper TLS certificates and remove this setting.

Deploy MySQL and PMM Client pod:

kubectl apply -f mysql-pmm-client-pod.yaml

View your monitored node¶

To confirm your node is being monitored:

Go to the main menu and select Operating System (OS) > 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.

Danger

pmm-agent.yaml contains sensitive credentials and should not be shared.

Troubleshooting¶

Failed to register pmm-agent on PMM Server: connection refused¶

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. Verify:

The PMM_AGENT_SERVER_ADDRESS value is correct
PMM Server is running and accessible
Firewall rules allow traffic on port 443

Pod stuck in Pending state¶

Check if the PersistentVolume was created successfully:

kubectl get pv
kubectl get pvc
kubectl describe pvc pmm-client-pvc

View PMM Client logs¶

# Standalone deployment
kubectl logs -l app=pmm-client

# Sidecar deployment
kubectl logs -l app=mysql -c pmm-client