New to KubeDB? Please start here.
Branch MariaDB into Another Namespace
Same-cluster branching creates an independent MariaDB database from a point-in-time snapshot of an existing database within the same Kubernetes cluster. You can place the branch in another namespace to prepare development, testing, or data analysis environments 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 setup, 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 MariaDB version
12.3.2is available in the installed KubeDB catalog and use branching-capable KubeDB and database images. - Run the commands against the same Kubernetes context.
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. The source lives in demo, and the target lives in dev.
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 source-mariadb.yaml. It creates a three-replica Galera MariaDB source named mariadb-source:
apiVersion: kubedb.com/v1
kind: MariaDB
metadata:
name: mariadb-source
namespace: demo
spec:
version: "12.3.2"
replicas: 3
topology:
mode: GaleraCluster
storageType: Durable
storage:
storageClassName: ceph-rbd
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 2Gi
deletionPolicy: WipeOut
Apply it and wait for readiness:
kubectl apply -f source-mariadb.yaml
kubectl -n demo wait mariadb/mariadb-source \
--for=jsonpath='{.status.phase}'=Ready --timeout=15m
Read the source database’s auth Secret name from your terminal:
kubectl -n demo get mariadb mariadb-source -o jsonpath='{.spec.authSecret.name}{"\n"}'
Example output:
mariadb-source-auth
Use the returned Secret name below if it differs. Decode its password:
kubectl -n demo get secret mariadb-source-auth -o jsonpath='{.data.password}' | base64 -d
Keep this password for the source connections below. The MariaDB root username is root.
Seed and inspect the source data
From your terminal, open the source pod shell:
kubectl -n demo exec -it mariadb-source-0 -c mariadb -- bash
Inside the pod, start the MariaDB client and enter the source password at the prompt:
mariadb -u root -p
At the MariaDB prompt, create five customer records:
CREATE DATABASE branchdb;
USE branchdb;
CREATE TABLE customers (
id integer PRIMARY KEY,
full_name varchar(100) NOT NULL,
email varchar(255) 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 in set
Leave mariadb with \q, then run exit in the pod shell to return to your terminal.
Create the Branch
Save the following as branch-same-cluster.yaml:
apiVersion: courier.kubedb.com/v1alpha1
kind: Branch
metadata:
name: mariadb-dev
namespace: demo
spec:
source:
databaseRef:
apiGroup: kubedb.com
kind: MariaDB
name: mariadb-source
namespace: demo
target:
namespace: dev
name: mariadb-dev
storageClassName: ceph-rbd
resources:
requests:
cpu: 500m
memory: 1Gi
deletionPolicy: Delete
The Branch lives in demo, references mariadb-source, and creates mariadb-dev in dev. Omitting spec.target.clusterName selects the same-cluster workflow. Courier imports source snapshot references into dev before creating target PVCs, because a PVC references snapshots within its own namespace.
spec.target.storageClassName selects the target Ceph class; spec.target.resources sets target MariaDB container requests. See the MariaDB Branch specification for field details.
Apply the manifest and wait for the Branch to become ready:
kubectl apply -f branch-same-cluster.yaml
kubectl -n demo wait branch/mariadb-dev \
--for=jsonpath='{.status.phase}'=Ready --timeout=15m
kubectl -n demo get branch mariadb-dev
Representative output:
NAME PHASE MODE TARGET FRESHNESS AGE
mariadb-dev Ready Local mariadb-dev 2s 3m
Inspect the target resources:
kubectl -n dev get mariadb mariadb-dev
kubectl -n dev get pvc,volumesnapshot
Verify the copied data
Read the branch database’s auth Secret name from your terminal:
kubectl -n dev get mariadb mariadb-dev -o jsonpath='{.spec.authSecret.name}{"\n"}'
Example output:
mariadb-dev-auth
Use the returned Secret name below if it differs. Decode its password:
kubectl -n dev get secret mariadb-dev-auth -o jsonpath='{.data.password}' | base64 -d
Keep this password for the branch connections below. The MariaDB root username is root.
Open the branch pod shell from your terminal:
kubectl -n dev exec -it mariadb-dev-0 -c mariadb -- bash
Inside the pod, start the MariaDB client and enter the branch password at the prompt:
mariadb -u root -p branchdb
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 in set
Keep this mariadb session open for the next step. These connections verify copied data; password-isolation checks are covered in the root password reset tutorial.
Verify independent writes
Change the branch
In the same branch mariadb session, update customer 5:
UPDATE customers SET full_name = 'Branch-only Customer 5' WHERE id = 5;
Expected output:
Query OK, 1 row affected
Leave mariadb with \q, then run exit to return to your terminal.
Change and inspect the source
kubectl -n demo exec -it mariadb-source-0 -c mariadb -- bash
Inside the pod, start the MariaDB client and enter the source password at the prompt:
mariadb -u root -p branchdb
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:
Query OK, 1 row affected
+----+--------------------+-----------------------+
| 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 in set
Customer 5 retains its original value on the source: the branch-only edit did not affect it.
Leave mariadb with \q, then run exit to return to your terminal.
Check the branch again
kubectl -n dev exec -it mariadb-dev-0 -c mariadb -- bash
Inside the pod, start the MariaDB client and enter the branch password at the prompt:
mariadb -u root -p branchdb
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 in set
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 mariadb with \q, then run exit to return to your terminal.
Cleanup
Delete the Branch first and wait for Courier to finish cleanup:
kubectl -n demo delete branch mariadb-dev --wait=true --timeout=15m
kubectl -n dev get mariadb,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 -n demo delete mariadb mariadb-source --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
- Refresh a MariaDB branch on a schedule and verify how replacement affects branch data.
- Reset the branch root password and verify that source credentials cannot authenticate to the branch.
- Run post-actions to anonymize customer data and remove a sensitive table before the branch becomes ready.

































