New to KubeDB? Please start here.
Branch MySQL Across Clusters
Cross-cluster branching creates an independent MySQL 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
kubectlcontexts namedhub,source, andtarget. The OCM ManagedCluster names in this tutorial aresourceandtarget. - Install compatible branching-capable KubeDB and database images with valid licenses on both database clusters. MySQL version
8.4.8must 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-mysql.yaml. It creates a three-replica Group Replication MySQL source named mysql-source:
apiVersion: kubedb.com/v1
kind: MySQL
metadata:
name: mysql-source
namespace: demo
spec:
version: "8.4.8"
replicas: 3
topology:
mode: GroupReplication
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-mysql.yaml
kubectl --context source -n demo wait mysql/mysql-source \
--for=jsonpath='{.status.phase}'=Ready --timeout=15m
Read the source database’s auth Secret name from your terminal:
kubectl --context source -n demo get mysql mysql-source -o jsonpath='{.spec.authSecret.name}{"\n"}'
Example output:
mysql-source-auth
Use the returned Secret name below if it differs. Decode its password:
kubectl --context source -n demo get secret mysql-source-auth -o jsonpath='{.data.password}' | base64 -d
Keep this password for the source connections below. The MySQL root username is root.
Seed and inspect the source data
From your terminal, open the source pod shell:
kubectl --context source -n demo exec -it mysql-source-0 -c mysql -- bash
Inside the pod, start the MySQL client and enter the source password at the prompt:
mysql -u root -p
At the mysql> 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 mysql 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: mysql-cross
namespace: demo
spec:
source:
databaseRef:
apiGroup: kubedb.com
kind: MySQL
name: mysql-source
namespace: demo
target:
clusterName: target
namespace: dev
name: mysql-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 MySQL resource, and KubeDB provisions the database using those PVCs.
spec.target.storageClassName selects the target Ceph class; spec.target.resources sets target MySQL container requests. See the MySQL 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/mysql-cross \
--for=jsonpath='{.status.phase}'=Ready --timeout=20m
kubectl --context source -n demo get branch mysql-cross
Representative output:
NAME PHASE MODE TARGET FRESHNESS AGE
mysql-cross Ready Initiator mysql-cross 2s 3m
Inspect the target resources on the target cluster:
kubectl --context target -n dev get mysql mysql-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
Read the branch database’s auth Secret name from your terminal:
kubectl --context target -n dev get mysql mysql-cross -o jsonpath='{.spec.authSecret.name}{"\n"}'
Example output:
mysql-cross-auth
Use the returned Secret name below if it differs. Decode its password:
kubectl --context target -n dev get secret mysql-cross-auth -o jsonpath='{.data.password}' | base64 -d
Keep this password for the branch connections below. The MySQL root username is root.
Open the branch pod shell from your terminal:
kubectl --context target -n dev exec -it mysql-cross-0 -c mysql -- bash
Inside the pod, start the MySQL client and enter the branch password at the prompt:
mysql -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 mysql 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 mysql session, update customer 5:
UPDATE customers SET full_name = 'Branch-only Customer 5' WHERE id = 5;
Expected output:
Query OK, 1 row affected
Leave mysql with \q, then run exit to return to your terminal.
Change and inspect the source
kubectl --context source -n demo exec -it mysql-source-0 -c mysql -- bash
Inside the pod, start the MySQL client and enter the source password at the prompt:
mysql -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 mysql with \q, then run exit to return to your terminal.
Check the branch again
kubectl --context target -n dev exec -it mysql-cross-0 -c mysql -- bash
Inside the pod, start the MySQL client and enter the branch password at the prompt:
mysql -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 mysql 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 mysql-cross --wait=true --timeout=15m
kubectl --context target -n dev get mysql,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 mysql mysql-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 MySQL 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.

































