New to KubeDB? Please start here.

PostgreSQL Branch Configuration

This page covers PostgreSQL branch overrides, snapshot selection, TLS, and deletion policies. Start with the Branch overview and one of the creation tutorials.

The examples below use the same HA source demo/prod-pg, Ceph RBD storage, and target namespace dev. They show same-cluster configuration. For cross-cluster use, set spec.target.clusterName to the target ManagedCluster name, apply the Branch on the source, and inspect the database resources on the target.

Storage and resource overrides

spec.target.storageClassName selects the target StorageClass. It must be compatible with the source snapshot’s CSI driver and backend. The tutorials use ceph-rbd on both sides, including for same-cluster branching.

spec.target.resources sets PostgreSQL container CPU/memory requests and limits. It does not resize storage. Ensure that any resource limits you add are at least the corresponding requests.

Select a snapshot class

Use an explicit volumeSnapshotClassName when your cluster has multiple classes:

apiVersion: courier.kubedb.com/v1alpha1
kind: Branch
metadata:
  name: pg-snapshot
  namespace: demo
spec:
  source:
    databaseRef:
      apiGroup: kubedb.com
      kind: Postgres
      name: prod-pg
    namespace: demo
  target:
    namespace: dev
    name: pg-snapshot
    storageClassName: ceph-rbd
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
  volumeSnapshotClassName: ceph-rbd-snapclass
  deletionPolicy: Delete

Create ceph-rbd-snapclass with settings appropriate for your CSI installation before applying this example. For another namespace, the importing snapshots use that class too. For another cluster, the named class must exist on both clusters and use compatible driver/backend settings. See snapshot configuration.

kubectl apply -f https://github.com/kubedb/docs/raw/v2026.11.15/docs/examples/postgres/branch/branch-snapshot-class.yaml
kubectl -n demo wait branch/pg-snapshot \
  --for=jsonpath='{.status.phase}'=Ready --timeout=15m
kubectl -n demo get volumesnapshot
kubectl -n dev get volumesnapshot

TLS-enabled sources

Before applying this example, configure TLS on source prod-pg following the PostgreSQL TLS guide. Prepare cert-manager on the target and an issuer named branch-ca in dev, with its required signing Secret available there.

When the source has TLS enabled, supply spec.target.issuerRef so KubeDB can issue certificates for the branch’s own Service names:

apiVersion: courier.kubedb.com/v1alpha1
kind: Branch
metadata:
  name: pg-tls
  namespace: demo
spec:
  source:
    databaseRef:
      apiGroup: kubedb.com
      kind: Postgres
      name: prod-pg
    namespace: demo
  target:
    namespace: dev
    name: pg-tls
    storageClassName: ceph-rbd
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
    issuerRef:
      apiGroup: cert-manager.io
      kind: Issuer
      name: branch-ca
  deletionPolicy: Delete

Use kind: ClusterIssuer when referencing a cluster-scoped issuer. The issuer must exist on the target cluster. A namespaced Issuer and its supporting Secrets must be in the target namespace.

kubectl -n dev get issuer branch-ca
kubectl apply -f https://github.com/kubedb/docs/raw/v2026.11.15/docs/examples/postgres/branch/branch-tls.yaml
kubectl -n demo wait branch/pg-tls \
  --for=jsonpath='{.status.phase}'=Ready --timeout=15m
kubectl -n dev get certificates,secrets
kubectl -n dev get postgres pg-tls -o yaml

Check that the branch’s certificates are ready and use the issuer’s CA for client verification. Configure client TLS parameters as described in the PostgreSQL TLS guide; the plaintext connection commands from the creation tutorials need to be adapted for the source’s TLS and authentication policy.

Deletion policies

The Branch’s spec.deletionPolicy controls what happens when you delete the Branch resource. Keep the source cluster, target cluster, Courier agents, OCM hub when used, and storage backend available until cleanup completes.

PolicyBehavior
Delete (default)Delete the target database, cloned PVCs, managed auth/config Secrets, and action Jobs; clean up branch snapshot resources.
OrphanRetain the target database, cloned PVCs, and required auth/config Secrets as independent resources; stop refresh and remove Courier’s branch management and action Jobs.

Both policies retain the source database and the target namespace. Cleanup uses finalizers and can take time while CSI resources and backend clone dependencies are released. Let the controller complete this ordering before uninstalling Courier.

Retain a branch with Orphan

apiVersion: courier.kubedb.com/v1alpha1
kind: Branch
metadata:
  name: pg-kept
  namespace: demo
spec:
  source:
    databaseRef:
      apiGroup: kubedb.com
      kind: Postgres
      name: prod-pg
    namespace: demo
  target:
    namespace: dev
    name: pg-kept
    storageClassName: ceph-rbd
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
  deletionPolicy: Orphan
kubectl apply -f https://github.com/kubedb/docs/raw/v2026.11.15/docs/examples/postgres/branch/branch-orphan.yaml
kubectl -n demo wait branch/pg-kept \
  --for=jsonpath='{.status.phase}'=Ready --timeout=15m
kubectl -n demo delete branch pg-kept --wait=true --timeout=15m
kubectl -n dev get postgres pg-kept
kubectl -n dev get pvc,secrets

The database and its data remain usable after the Branch is gone. Read its auth Secret and verify a query through Service pg-kept, following the Service connection steps in the same-cluster tutorial. Retain the original Secret; it contains the credential for the preserved data.

To remove the retained database and its durable data later, choose the database’s own deletion policy explicitly:

kubectl -n dev patch postgres pg-kept --type=merge \
  -p '{"spec":{"deletionPolicy":"WipeOut"}}'
kubectl -n dev delete postgres pg-kept --wait=true --timeout=10m

This final step removes the retained database’s data.

Cleanup optional examples

Delete any Branches created by the snapshot and TLS examples before deleting their namespaces:

kubectl -n demo delete branch pg-snapshot pg-tls --ignore-not-found --wait=true --timeout=15m

For cross-cluster variants, run Branch cleanup on the source cluster and inspect remaining resources on the target.