New to KubeDB? Please start here.

Resetting a PostgreSQL Branch Root Password

Set spec.resetRootPassword: true to give a PostgreSQL branch its own root credential. Giving the branch its own root password reduces the risk of exposing or reusing production credentials in development and test environments. The source database retains its original credential.

This tutorial demonstrates a same-cluster PostgreSQL branch in a different namespace. You will deploy and seed the source, create a Branch with password reset enabled, compare both passwords, and verify authentication through the database Services. No database from another tutorial is required.

Before You Begin

  • Read the branching overview to understand how branches work.
  • Complete the single-cluster Courier installation, including KubeDB and the Branch CRD.
  • Have a working Ceph RBD StorageClass supporting copy-on-write cloning and a compatible snapshot class. See snapshot configuration.
  • Ensure PostgreSQL version 18.3 is available in the installed KubeDB catalog, and use branching-capable KubeDB and database images.
  • Run the commands against the same Kubernetes context. Your account must be able to create databases and Branches, read auth Secrets, inspect pods, and open a shell in database pods.
  • Allow the source pod to connect to the source and branch database Services on port 5432 for the authentication checks.

The manifests use the StorageClass name ceph-rbd. Substitute your Ceph RBD class consistently in both manifests. The source lives in demo and the target in dev; reserve the database names below for this tutorial.

Create the namespaces if they do not already exist:

kubectl create namespace demo
kubectl create namespace dev

Deploy the source database

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

apiVersion: kubedb.com/v1
kind: Postgres
metadata:
  name: reset-source
  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 and wait for the source to become ready:

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

Find the source primary:

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

Example output:

reset-source-0

Use the returned pod name in the following commands; this example uses reset-source-0.

Seed and inspect the source data

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

kubectl -n demo exec -it reset-source-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 for seeding:

psql -U postgres -d postgres

At the postgres=# prompt, 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.

Record the source password

Read the auth Secret name from the source database:

kubectl -n demo get postgres reset-source -o jsonpath='{.spec.authSecret.name}{"\n"}'

Example output:

reset-source-auth

Use the returned Secret name below if it differs. Decode the password:

kubectl -n demo get secret reset-source-auth -o jsonpath='{.data.password}' | base64 -d

Illustrative output:

source-example-password

Keep the actual value available for the comparison and authentication checks. The passwords shown here are illustrative; KubeDB generates your installation’s values.

Create a Branch with password reset enabled

Save the following as branch-reset-root-password.yaml. The Branch lives in demo and creates dev/reset-branch:

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

Omitting spec.target.clusterName keeps this branch in the same cluster (Local mode). resetRootPassword: true requests a separate root credential for the target.

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

kubectl apply -f branch-reset-root-password.yaml
kubectl -n demo wait branch/reset-branch \
  --for=jsonpath='{.status.phase}'=Ready --timeout=20m
kubectl -n demo get branch reset-branch

Illustrative output:

NAME           PHASE   MODE    TARGET         FRESHNESS   AGE
reset-branch   Ready   Local   reset-branch   2s          3m

Check the conditions:

kubectl -n demo get branch reset-branch \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\n"}{end}'

Successful completion includes these conditions; their order may vary:

SnapshotReady           True
TargetCreated           True
TargetReady             True
RootPasswordReset       True
Ready                   True

RootPasswordReset: True records completion of credential isolation. The following checks compare the Secrets and verify that the database accepts the intended password.

Compare source and branch passwords

From your terminal, discover both databases’ auth Secret names:

kubectl -n demo get postgres reset-source -o jsonpath='{.spec.authSecret.name}{"\n"}'
kubectl -n dev get postgres reset-branch -o jsonpath='{.spec.authSecret.name}{"\n"}'

Example output, in command order:

reset-source-auth
reset-branch-auth

Use those returned names in the commands below. Read the source password again:

kubectl -n demo get secret reset-source-auth -o jsonpath='{.data.password}' | base64 -d

It should match the value recorded before creating the Branch:

source-example-password

Read the branch password:

kubectl -n dev get secret reset-branch-auth -o jsonpath='{.data.password}' | base64 -d

It should differ from the source password:

branch-example-password

This comparison demonstrates that the branch has a different password and the source password remains unchanged. Applications connecting to the branch should use the target database’s auth Secret after the Branch reaches Ready.

Verify authentication through the Services

Use TCP connections through the database Services for password checks. The earlier local socket connection used trust authentication and cannot demonstrate password isolation. -h selects the Service, and -W makes psql prompt for a password without putting it in a command.

From your terminal, find the source primary again in case a failover occurred:

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

Open a shell in that pod, substituting the returned name if different:

kubectl -n demo exec -it reset-source-0 -c postgres -- bash

Run the following authentication checks from this pod shell. The example uses PostgreSQL’s generated root user, postgres.

Connect to the branch with its own password

Connect through the branch Service in dev:

psql -h reset-branch.dev.svc -p 5432 -U postgres -d postgres -W

At Password for user postgres:, enter the branch password decoded above. It is not echoed. Once connected, query the copied 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)

The branch password authenticates successfully, and all five source rows are present. Run \q to return to the pod shell; keep this shell open for the next check.

Confirm the source password is rejected by the branch

From the same pod shell, repeat the connection:

psql -h reset-branch.dev.svc -p 5432 -U postgres -d postgres -W

This time, enter the source password at the prompt. The connection should fail with an error containing:

FATAL:  password authentication failed for user "postgres"

The failed command returns to the pod shell. A DNS error, connection timeout, or connection refusal does not establish password isolation; the expected result is a password-authentication rejection from PostgreSQL.

Confirm the source credential and data still work

From the same pod shell, connect through the source Service:

psql -h reset-source.demo.svc -p 5432 -U postgres -d postgres -W

Enter the original source password at the prompt. Once connected, 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)

The original password still authenticates to the source, and its data is unchanged. Leave psql with \q, then run exit to return to your terminal.

For the option’s default and behavior, see the common root password reset field reference.

Using password reset with other branch features

A scheduled refresh replaces branch data and reapplies credential isolation when enabled. Wait for the refreshed Branch to return to Ready, then read its current auth Secret before connecting.

Post-actions run after credential isolation and receive the branch’s current connection credentials automatically.

Cleanup

Delete this tutorial’s Branch and wait for Courier to finish cleanup:

kubectl -n demo delete branch reset-branch --wait=true --timeout=15m

With deletionPolicy: Delete, Courier removes the target database, cloned volumes, auth Secret, and managed snapshots. The source remains available.

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

kubectl -n demo delete postgres reset-source --wait=true --timeout=15m

These commands leave the demo and dev namespaces available for other resources.