CloudNativePG (Coming January 2026)

CloudNativePG agent setup

For an overview of how the DBtune agent works, see agent overview.

Prerequisites

Before starting the DBtune agent, there is some setup you are required to complete on your PostgreSQL cluster.

CloudNativePG clusters come with pg_stat_statements pre-installed, but you need to verify it is enabled and properly configured. First, ensure the extension is created:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Next, verify that the pg_stat_statements.track parameter is properly configured. By default this may be set to none, it needs to be set to either top or all for the extension to collect the information DBtune requires. You can check and set this in your CNPG cluster configuration:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: {CLUSTER_NAME}
spec:
  postgresql:
    parameters:
      pg_stat_statements.track: "all"

Once you have setup pg_stat_statements, ensure you have completed the remaining database setup steps.

Kubernetes RBAC permissions

The DBtune agent requires specific Kubernetes permissions to manage CNPG clusters. Create a ServiceAccount with the following permissions:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: dbtune-agent
  namespace: {YOUR_NAMESPACE}
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: dbtune-agent-role
  namespace: {YOUR_NAMESPACE}
rules:
  - apiGroups: ["postgresql.cnpg.io"]
    resources: ["clusters"]
    verbs: ["get", "list", "patch"]
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list"]
  - apiGroups: [""]
    resources: ["pods/log"]
    verbs: ["get"]
  - apiGroups: ["metrics.k8s.io"]
    resources: ["pods"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: dbtune-agent-rolebinding
  namespace: {YOUR_NAMESPACE}
subjects:
  - kind: ServiceAccount
    name: dbtune-agent
    namespace: {YOUR_NAMESPACE}
roleRef:
  kind: Role
  name: dbtune-agent-role
  apiGroup: rbac.authorization.k8s.io

Setting up the agent

Deploy the DBtune agent as a Kubernetes Deployment in the same namespace as your CNPG cluster:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: dbtune-agent
  namespace: {YOUR_NAMESPACE}
spec:
  replicas: 1
  selector:
    matchLabels:
      app: dbtune-agent
  template:
    metadata:
      labels:
        app: dbtune-agent
    spec:
      serviceAccountName: dbtune-agent
      containers:
      - name: agent
        image: public.ecr.aws/dbtune/dbtune/agent:latest
        args: ["--cnpg"]
        env:
        - name: DBT_POSTGRESQL_CONNECTION_URL
          value: "postgresql://dbtune:your-secure-password@{CLUSTER_RW_SERVICE}:5432/{DATABASE_NAME}"
        - name: DBT_CNPG_NAMESPACE
          value: "{YOUR_NAMESPACE}"
        - name: DBT_CNPG_CLUSTER_NAME
          value: "{CLUSTER_NAME}"
        - name: DBT_CNPG_CONTAINER_NAME
          value: "{CONTAINER_NAME}"
        - name: DBT_DBTUNE_SERVER_URL
          value: "https://app.dbtune.com"
        - name: DBT_DBTUNE_API_KEY
          value: "your-dbtune-api-key"
        - name: DBT_DBTUNE_DATABASE_ID
          value: "your-dbtune-database-id"
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "200m"

tip

For sensitive values like passwords and API keys, consider using Kubernetes Secrets instead of plain text in the Deployment manifest.

CloudNativePG-specific environment variables

Variable	Description
DBT_CNPG_NAMESPACE	The Kubernetes namespace where your CNPG cluster is deployed.
DBT_CNPG_CLUSTER_NAME	The name of your CNPG cluster resource.
DBT_CNPG_CONTAINER_NAME	(Optional) The container name within the pod. Defaults to postgres.
DBT_CNPG_POD_NAME	(Optional) By default, the agent automatically detects the current primary pod.
DBT_CNPG_KUBECONFIG_PATH	(Optional) Path to kubeconfig file. Defaults to ~/.kube/config or in-cluster config.

For information about common environment variables — DBT_DBTUNE_* and DBT_POSTGRESQL_* — see agent overview - common environment variables.

Parameters tuned

CloudNativePG manages certain PostgreSQL parameters internally (such as replication settings, SSL configuration, and logging). To prevent conflicts and maintain cluster stability, DBtune detects these CNPG-managed parameters and does not touch them.

For a complete list of parameters managed by CNPG that DBtune will skip, please refer to the CNPG documentation.

The following parameters are tuned by DBtune using a server reload without causing any application downtime:

1. work_mem
2. random_page_cost
3. seq_page_cost
4. checkpoint_completion_target
5. effective_io_concurrency
6. max_parallel_workers_per_gather
7. max_parallel_workers
8. max_wal_size
9. min_wal_size
10. bgwriter_lru_maxpages
11. bgwriter_delay
12. effective_cache_size
13. maintenance_work_mem
14. default_statistics_target
15. max_parallel_maintenance_workers

Failover detection

The DBtune agent automatically detects CNPG failover events during tuning sessions. If a failover occurs while tuning is in progress, the agent prioritizes cluster stability by suspending all tuning activities and metrics collection until recovery is complete.

During this recovery period, the agent will:

1. Wait for the new primary to become healthy and stable (including a 30-second stabilization period).
2. Once the cluster is ready, automatically revert the database to its baseline configuration for safety.
3. Resume standard monitoring and report the failover event to the DBtune platform.

This ensures that operations are not attempted during unstable cluster states and prevents event log flooding with connection errors.