New to KubeDB? Please start here.

Branch PostgreSQL Across Clusters

Cross-cluster branching creates an independent PostgreSQL database on another Kubernetes cluster from a point-in-time snapshot of an existing database. This lets you prepare development, testing, or data analysis environments on a separate cluster using existing data.

The branch accepts independent reads and writes without changing the source database. Source changes are not continuously replicated; you can configure scheduled refreshes to replace branch data with a fresh source snapshot.

Before You Begin

  • Read the branching overview to understand how branches work.
  • Complete Courier cross-cluster setup in an existing OCM environment.
  • Have kubectl contexts named hub, source, and target. The OCM ManagedCluster names in this tutorial are source and target.
  • Install compatible branching-capable KubeDB and database images with valid licenses on both database clusters. PostgreSQL version 18.3 must be available in both installed KubeDB catalogs.
  • Configure compatible Ceph RBD storage and snapshot classes on both clusters. Source snapshots must be resolvable on the target against the shared backend. See snapshot configuration.

Using two independent Ceph backends does not satisfy the storage requirement. Confirm CSI/backend compatibility before creating the source.

The manifests use the StorageClass name ceph-rbd; substitute your Ceph RBD class consistently. Your account must be able to create databases and Branches, inspect their resources, and open a shell in the database pods. Commands identify the cluster with --context source, --context target, or --context hub.

Create the namespaces if they do not already exist:

kubectl --context source create namespace demo
kubectl --context target create namespace dev

Deploy the source database

Save the following as source-postgres.yaml. It creates a three-replica PostgreSQL source named prod-pg:

apiVersion: kubedb.com/v1
kind: Postgres
metadata:
  name: prod-pg
  namespace: demo
spec:
  version: "18.3"
  replicas: 3
  standbyMode: Hot
  storageType: Durable
  storage:
    storageClassName: ceph-rbd
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 2Gi
  deletionPolicy: WipeOut

Apply it on the source cluster and wait for readiness:

kubectl --context source apply -f source-postgres.yaml
kubectl --context source -n demo wait postgres/prod-pg \
  --for=jsonpath='{.status.phase}'=Ready --timeout=15m

Find the elected primary:

kubectl --context source -n demo get pods -l app.kubernetes.io/instance=prod-pg,kubedb.com/role=primary -o jsonpath='{.items[0].metadata.name}{"\n"}'

Example output:

prod-pg-0

Use the returned pod name below if it differs. Pod names, ages, and durations in this guide are illustrative.

Seed and inspect the source data

From your terminal, open a shell in the source primary:

kubectl --context source -n demo exec -it prod-pg-0 -c postgres -- bash

Inside the pod, connect to database postgres. Local socket connections in this setup use trust authentication, so no password is required:

psql -U postgres -d postgres

At the postgres=# create five customer records:

CREATE TABLE customers (
    id integer PRIMARY KEY,
    full_name text NOT NULL,
    email text NOT NULL
);
INSERT INTO customers (id, full_name, email) VALUES
    (1, 'Customer 1', '[email protected]'),
    (2, 'Customer 2', '[email protected]'),
    (3, 'Customer 3', '[email protected]'),
    (4, 'Customer 4', '[email protected]'),
    (5, 'Customer 5', '[email protected]');

Inspect the source data:

SELECT * FROM customers ORDER BY id;

Expected result:

 id | full_name  |         email
----+------------+-----------------------
  1 | Customer 1 | [email protected]
  2 | Customer 2 | [email protected]
  3 | Customer 3 | [email protected]
  4 | Customer 4 | [email protected]
  5 | Customer 5 | [email protected]
(5 rows)

Leave psql with \q, then run exit in the pod shell to return to your terminal.

Create the cross-cluster Branch

Save the following as branch-cross-cluster.yaml:

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

spec.target.clusterName is the target’s OCM ManagedCluster name, which can differ from a kubeconfig context name. Apply the original Branch on the source cluster. Courier routes the request through the hub; on the target, Courier prepares cloned PVCs and the PostgreSQL resource, and KubeDB provisions the database using those PVCs.

spec.target.storageClassName selects the target Ceph class; spec.target.resources sets target PostgreSQL container requests. See the PostgreSQL Branch specification for field details.

Apply the manifest and wait for the Branch to become ready:

kubectl --context source apply -f branch-cross-cluster.yaml
kubectl --context source -n demo wait branch/pg-cross \
  --for=jsonpath='{.status.phase}'=Ready --timeout=20m
kubectl --context source -n demo get branch pg-cross

Representative output:

NAME       PHASE   MODE        TARGET     FRESHNESS   AGE
pg-cross   Ready   Initiator   pg-cross   2s          3m

Inspect the target resources on the target cluster:

kubectl --context target -n dev get postgres pg-cross
kubectl --context target -n dev get pvc,volumesnapshot

To inspect delivery and target execution from your terminal:

kubectl --context hub -n source get branchwork
kubectl --context hub -n target get manifestwork
kubectl --context target -n dev get branch

Manage the branch through its original source resource. Courier owns the delivered target resources.

Verify the copied data

From your terminal, find the branch primary on the target cluster:

kubectl --context target -n dev get pods -l app.kubernetes.io/instance=pg-cross,kubedb.com/role=primary -o jsonpath='{.items[0].metadata.name}{"\n"}'

Example output:

pg-cross-0

Use the returned name to open its pod shell:

kubectl --context target -n dev exec -it pg-cross-0 -c postgres -- bash

Inside the pod, start psql:

psql -U postgres -d postgres

Query the copied data:

SELECT * FROM customers ORDER BY id;

The branch should contain the same five rows:

 id | full_name  |         email
----+------------+-----------------------
  1 | Customer 1 | [email protected]
  2 | Customer 2 | [email protected]
  3 | Customer 3 | [email protected]
  4 | Customer 4 | [email protected]
  5 | Customer 5 | [email protected]
(5 rows)

Keep this psql session open for the next step. These local connections verify data; password-isolation checks are covered in the root password reset tutorial.

Verify independent writes

Change the branch

In the same branch psql session, update customer 5:

UPDATE customers SET full_name = 'Branch-only Customer 5' WHERE id = 5;

Expected output:

UPDATE 1

Leave psql with \q, then run exit to return to your terminal.

Change and inspect the source

Find the source primary again in case a failover occurred:

kubectl --context source -n demo get pods -l app.kubernetes.io/instance=prod-pg,kubedb.com/role=primary -o jsonpath='{.items[0].metadata.name}{"\n"}'

Open its pod shell, substituting the returned name if different:

kubectl --context source -n demo exec -it prod-pg-0 -c postgres -- bash

Inside the pod, start psql:

psql -U postgres -d postgres

Update customer 1 and inspect all five rows:

UPDATE customers SET full_name = 'Updated Customer 1' WHERE id = 1;
SELECT * FROM customers ORDER BY id;

Expected result:

UPDATE 1
 id |     full_name      |         email
----+--------------------+-----------------------
  1 | Updated Customer 1 | [email protected]
  2 | Customer 2         | [email protected]
  3 | Customer 3         | [email protected]
  4 | Customer 4         | [email protected]
  5 | Customer 5         | [email protected]
(5 rows)

Customer 5 retains its original value on the source: the branch-only edit did not affect it.

Leave psql with \q, then run exit to return to your terminal.

Check the branch again

From your terminal, find the current branch primary:

kubectl --context target -n dev get pods -l app.kubernetes.io/instance=pg-cross,kubedb.com/role=primary -o jsonpath='{.items[0].metadata.name}{"\n"}'

Open its pod shell using the returned name:

kubectl --context target -n dev exec -it pg-cross-0 -c postgres -- bash

Inside the pod, start psql:

psql -U postgres -d postgres

Query all five customers:

SELECT * FROM customers ORDER BY id;

Expected result:

 id |       full_name        |         email
----+------------------------+-----------------------
  1 | Customer 1             | [email protected]
  2 | Customer 2             | [email protected]
  3 | Customer 3             | [email protected]
  4 | Customer 4             | [email protected]
  5 | Branch-only Customer 5 | [email protected]
(5 rows)

Customer 1 still has its original value, and customer 5 retains the branch-only edit. The branch and source accept independent writes. A refresh replaces branch data with a new source snapshot; source changes are not continuously replicated to the branch.

Leave psql with \q, then run exit to return to your terminal.

Cleanup

Delete the original Branch on the source cluster while the hub, agents, and storage backend remain available:

kubectl --context source -n demo delete branch pg-cross --wait=true --timeout=15m
kubectl --context target -n dev get postgres,pvc,volumesnapshot

With deletionPolicy: Delete, Courier removes the target database and managed storage. The source remains available. See deletion policies to retain a branch independently.

Remove the tutorial source when finished. Its WipeOut policy deletes its data:

kubectl --context source -n demo delete postgres prod-pg --wait=true --timeout=15m

These commands leave the demo and dev namespaces available for other resources. Each feature tutorial below deploys its own source database.

Next Steps