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 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. MySQL version 8.4.8 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-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