apecloud/kubeblocks-addon-postgresql

Deploy PostgreSQL on KubeBlocks

Overview

Deploy highly-available PostgreSQL clusters using KubeBlocks. Uses the Spilo image with Patroni for automatic leader election and failover.

Official docs: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-postgresql/cluster-management/create-and-connect-a-postgresql-cluster Full doc index: https://kubeblocks.io/llms-full.txt

Prerequisites

• A running Kubernetes cluster with KubeBlocks installed (see install-kubeblocks)
• For first-time rollout or unknown environment readiness, run kubeblocks-preflight first and carry its recommendation bundle into this skill.
• The PostgreSQL addon must be enabled:

# Check if postgresql addon is installed
helm list -n kb-system | grep postgresql

# Install if missing
helm install kb-addon-postgresql kubeblocks/postgresql --namespace kb-system --version 1.0.0

Cluster Architecture

• clusterDef: postgresql
• topology: replication
• HA Engine: Patroni (embedded in Spilo image)
• Components: postgresql (primary + read replicas)

Keep these decisions visible in this engine-entry skill:

• topology: replication
• serviceVersion
• storageClassName from preflight
• demo vs production sizing

Patroni handles automatic leader election, failover, and replica management. A primary is elected among replicas, and streaming replication keeps replicas in sync.

Supported Versions

| Major Version | serviceVersion Examples | |---|---| | PostgreSQL 12 | 12.14.0, 12.14.1, 12.15.0 | | PostgreSQL 14 | 14.7.2, 14.8.0 | | PostgreSQL 15 | 15.7.0 | | PostgreSQL 16 | 16.4.0 | | PostgreSQL 17 | 17.4.0 | | PostgreSQL 18 | 18.0.0 |

Workflow

- [ ] Step 1: Ensure addon is installed
- [ ] Step 2: Create namespace
- [ ] Step 3: Create cluster
- [ ] Step 4: Wait for cluster to be ready
- [ ] Step 5: Connect to PostgreSQL

Step 1: Ensure Addon Is Installed

helm list -n kb-system | grep postgresql

If not found, install it:

helm install kb-addon-postgresql kubeblocks/postgresql --namespace kb-system --version 1.0.0

Step 2: Create Namespace

kubectl create namespace demo --dry-run=client -o yaml | kubectl apply -f -

Step 3: Create Cluster

Replication Cluster (Standard)

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: pg-cluster
  namespace: demo
spec:
  clusterDef: postgresql
  topology: replication
  terminationPolicy: Delete
  componentSpecs:
    - name: postgresql
      serviceVersion: "14.7.2"
      replicas: 2
      disableExporter: false
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            storageClassName: <storageClassName-from-preflight>
            resources: {requests: {storage: 20Gi}}

Apply:

kubectl apply -f pg-cluster.yaml

Key fields:

• disableExporter: false — enables the metrics exporter sidecar for monitoring
• replicas: 2 — one primary + one streaming replica (Patroni elects the leader)

Production Configuration

For production, increase resources and replicas:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: pg-production
  namespace: demo
spec:
  clusterDef: postgresql
  topology: replication
  terminationPolicy: Halt
  componentSpecs:
    - name: postgresql
      serviceVersion: "16.4.0"
      replicas: 3
      disableExporter: false
      resources:
        limits: {cpu: "2", memory: "4Gi"}
        requests: {cpu: "2", memory: "4Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            storageClassName: <storageClassName-from-preflight>
            resources: {requests: {storage: 100Gi}}

Step 4: Wait for Cluster Ready

kubectl -n demo get cluster pg-cluster -w

Wait until STATUS shows Running. Typical startup time: 1-3 minutes.

Check pods:

kubectl -n demo get pods -l app.kubernetes.io/instance=pg-cluster

Step 5: Connect to PostgreSQL

Get Credentials

# Secret name format: <cluster>-postgresql-account-postgres
kubectl -n demo get secret pg-cluster-postgresql-account-postgres -o jsonpath='{.data.password}' | base64 -d

Connect via kubectl exec

kubectl -n demo exec -it pg-cluster-postgresql-0 -- bash -c 'psql -U postgres'

Connect via Port-Forward

kubectl -n demo port-forward svc/pg-cluster-postgresql 5432:5432
# Then from another terminal:
psql -h 127.0.0.1 -p 5432 -U postgres

Backup

PostgreSQL supports three backup methods:

| Method | ActionSet | Use Case | |---|---|---| | pg-basebackup | pg-basebackup | Logical base backup | | Volume Snapshot | postgresql-volumesnapshot | Storage-level snapshots, fastest | | WAL Archive | wal-archive | Continuous archiving for PITR |

Example backup:

apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: pg-backup
  namespace: demo
spec:
  backupMethod: pg-basebackup
  backupPolicyName: pg-cluster-postgresql-backup-policy

For point-in-time recovery (PITR), enable WAL archiving first, then restore to a specific timestamp.

Troubleshooting

Cluster stuck in Creating:

kubectl -n demo describe cluster pg-cluster
kubectl -n demo get events --sort-by='.lastTimestamp'

Patroni issues:

# Check Patroni status
kubectl -n demo exec -it pg-cluster-postgresql-0 -- patronictl list

Replication lag:

kubectl -n demo exec -it pg-cluster-postgresql-0 -- psql -U postgres -c "SELECT * FROM pg_stat_replication;"

Day-2 Operations

| Operation | Skill | External Docs | |---|---|---| | Stop / Start / Restart | cluster-lifecycle | Docs | | Scale CPU / Memory | vertical-scaling | Docs | | Add / Remove replicas | horizontal-scaling | Docs | | Expand storage | volume-expansion | Docs | | Change parameters | reconfigure-parameters | Docs | | Switchover primary | switchover | Docs | | Upgrade engine version | minor-version-upgrade | Docs | | Expose externally | expose-service | Docs | | Backup | backup | Docs | | Restore | restore | Docs |

Safety Patterns

Follow safety-patterns.md for dry-run before apply, status confirmation after watch, and pre-deletion checklist.

Next Steps

• For detailed YAML examples and the vanilla-postgresql variant, see reference.md