From 5701e3d627db8b53f3a96223e4b22f48aeef7f16 Mon Sep 17 00:00:00 2001
From: Sk Ali Arman <arman@appscode.com>
Date: Fri, 24 Jul 2026 06:53:43 +0000
Subject: [PATCH 1/4] docs/mysql: split mode transform into remote-replica and
 topology-mode-change guides

The replication-mode-transform guide mixed two unrelated workflows. Split
it into two sibling guides under the same section:

- Rename the existing guide to "MySQL Remote/Read Only Replica Mode
  Transfer" and scope it to the Remote Replica workflow.
- Add a new "MySQL Topology Mode Change" guide covering every mode change
  that is implemented and tested: standalone to GroupReplication
  (Single-Primary and Multi-Primary), InnoDBCluster and SemiSync;
  GroupReplication to InnoDBCluster; InnoDBCluster to GroupReplication;
  GroupReplication to SemiSync. Includes the not-supported-yet directions
  and the Router RBAC caveat, with example manifests for each. It is named
  "Topology Mode" rather than just "Mode" to avoid confusion with the
  sql_mode server variable; it changes spec.topology.mode.
- Update the overview with the full support matrix, the data-preservation
  guarantee and links to both guides.

Also fix mode-transform-ops-request.yaml, which used an unsupported
Multi-Primary mode.

Signed-off-by: Sk Ali Arman <arman@appscode.com>
---
 .../overview/index.md                         |  38 +-
 .../examples/mode-transform-ops-request.yaml  |   3 +-
 .../replication-mode-transform/index.md       |  32 +-
 .../examples/gr-to-innodb-cluster.yaml        |  14 +
 .../examples/gr-to-semisync.yaml              |  13 +
 .../examples/innodb-cluster-to-gr.yaml        |  14 +
 .../examples/my-cluster.yaml                  |  18 +
 .../examples/my-standalone.yaml               |  16 +
 .../promote-to-group-replication.yaml         |  14 +
 .../examples/promote-to-innodb-cluster.yaml   |  14 +
 .../examples/promote-to-multi-primary.yaml    |  14 +
 .../examples/promote-to-semisync.yaml         |  13 +
 .../topology-mode-change/index.md             | 346 ++++++++++++++++++
 13 files changed, 540 insertions(+), 9 deletions(-)
 create mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml
 create mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml
 create mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml
 create mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-cluster.yaml
 create mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-standalone.yaml
 create mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-group-replication.yaml
 create mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-innodb-cluster.yaml
 create mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-multi-primary.yaml
 create mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-semisync.yaml
 create mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md

diff --git a/docs/guides/mysql/replication-mode-transform/overview/index.md b/docs/guides/mysql/replication-mode-transform/overview/index.md
index 763666c8c7..28cfa9e601 100644
--- a/docs/guides/mysql/replication-mode-transform/overview/index.md
+++ b/docs/guides/mysql/replication-mode-transform/overview/index.md
@@ -14,7 +14,43 @@ section_menu_id: guides
 
 # MySQL Replication Mode Transform
 
-This guide will give an overview on how KubeDB Ops Manager transform replication mode of `MySQL`. Currently, you can transform `remote replica` to `group replication`.
+This guide will give an overview on how KubeDB Ops Manager transforms the replication mode of a `MySQL` database — including **promoting a standalone MySQL into a clustered topology** and switching an existing cluster from one topology to another.
+
+Two step-by-step guides build on this overview:
+
+- [MySQL Topology Mode Change](/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md) — change the mode of an
+  existing database: standalone → `GroupReplication` (Single-Primary or Multi-Primary) /
+  `InnoDBCluster` / `SemiSync`, and changes between clustered topologies.
+- [MySQL Remote/Read Only Replica Mode Transfer](/docs/guides/mysql/replication-mode-transform/replication-mode-transform/index.md) —
+  transform a Remote Replica into a standalone or clustered database.
+
+## Supported Transformations
+
+The target topology is selected with `spec.replicationModeTransformation.targetMode`, which accepts
+`GroupReplication` (default), `InnoDBCluster` or `SemiSync`.
+
+| From (source) | To `GroupReplication` | To `InnoDBCluster` | To `SemiSync` |
+|---------------|:---------------------:|:------------------:|:-------------:|
+| **Standalone** (no `spec.topology`) | ✅ | ✅ | ✅ |
+| **RemoteReplica** | ✅ | ✅ | ✅ |
+| **GroupReplication** | — | ✅ | ✅ |
+| **InnoDBCluster** | ✅ | — | ❌ not supported yet |
+| **SemiSync** | ❌ not supported yet | ❌ not supported yet | — |
+
+Notes:
+
+- **Your data is preserved.** Promotions and transformations never delete a volume. When a new
+  replica has to be seeded, it is seeded in place with MySQL's `CLONE INSTANCE`, which overwrites
+  the data directory while the `PersistentVolumeClaim` is retained.
+- **Transformations between clustered topologies happen in place.** `GroupReplication` ⇄
+  `InnoDBCluster` keeps the running group and simply hands over management (adopting the group into
+  an InnoDB Cluster, or releasing it back to plain Group Replication) — no teardown and no re-clone.
+- A standalone database is scaled up to at least 3 members when it is promoted, since a clustered
+  topology needs a quorum.
+- `spec.replicationModeTransformation.mode` selects the Group Replication primary mode —
+  **`Single-Primary`** (default) or **`Multi-Primary`** (multi-master, every member accepts writes).
+  It applies to the group-based targets; it is ignored for `SemiSync`.
+- Replication Mode Transformation requires MySQL **8.4.2 or newer**.
 
 ## Before You Begin
 
diff --git a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mode-transform-ops-request.yaml b/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mode-transform-ops-request.yaml
index 7dcd827116..ba900c8ca1 100644
--- a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mode-transform-ops-request.yaml
+++ b/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mode-transform-ops-request.yaml
@@ -8,7 +8,8 @@ spec:
   databaseRef:
     name: mysql-london
   replicationModeTransformation:
-    mode: Multi-Primary
+    targetMode: GroupReplication
+    mode: Single-Primary
     requireSSL: true
     issuerRef:
       apiGroup: cert-manager.io
diff --git a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/index.md b/docs/guides/mysql/replication-mode-transform/replication-mode-transform/index.md
index ecd2f43970..3b0400c5be 100644
--- a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/index.md
+++ b/docs/guides/mysql/replication-mode-transform/replication-mode-transform/index.md
@@ -1,9 +1,9 @@
 ---
-title: MySQL Replication Mode Transform
+title: MySQL Remote/Read Only Replica Mode Transfer
 menu:
   docs_{{ .version }}:
-    identifier: guides-mysql-replication-mode-transform
-    name: MySQL Replication Mode Transform
+    identifier: guides-mysql-remote-replica-mode-transfer
+    name: Remote/Read Only Replica Mode Transfer
     parent: guides-mysql-mode-transform
     weight: 12
 menu_name: docs_{{ .version }}
@@ -12,9 +12,22 @@ section_menu_id: guides
 
 > New to KubeDB? Please start [here](/docs/README.md).
 
-## MySQL Replication Mode Transform
+## MySQL Remote/Read Only Replica Mode Transfer
 
-This guide will show you how to use the `KubeDB` OpsRequest operator to transform the replication mode of a MySQL database. Currently, transforming from Remote Replica to Group Replication is supported. 
+This guide shows how to use the `KubeDB` OpsRequest operator to transform a **Remote Replica
+(read-only replica)** into a clustered topology — for example when the primary cluster is gone and
+you want to promote the remote replica into a self-standing cluster.
+
+> Looking to change the mode of an existing database (standalone → cluster, or between clustered
+> topologies)? See [MySQL Topology Mode Change](/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md).
+
+The target topology is chosen with `spec.replicationModeTransformation.targetMode`. See the
+[overview](/docs/guides/mysql/replication-mode-transform/overview/index.md) for the full support
+matrix.
+
+> **Note:** Replication Mode Transformation requires MySQL **8.4.2 or newer**.
+> `spec.replicationModeTransformation.mode` supports both **`Single-Primary`** (default) and
+> **`Multi-Primary`** (multi-master).
 
 ### MySQL Remote Replica
 
@@ -393,7 +406,8 @@ spec:
   databaseRef:
     name: mysql-london
   replicationModeTransformation:
-    mode: Multi-Primary
+    targetMode: GroupReplication
+    mode: Single-Primary
     requireSSL: true
     issuerRef:
       apiGroup: cert-manager.io
@@ -416,8 +430,12 @@ Here,
 
 - `spec.databaseRef.name` specifies that we are performing Replication Mode Transformation operation on `mysql-london` database.
 - `spec.type` specifies that we are performing `ReplicationModeTransformation` on our database.
+- `spec.replicationModeTransformation.targetMode` specifies the topology to transform into —
+  `GroupReplication` (default), `InnoDBCluster` or `SemiSync`.
 - `spec.replicationModeTransformation.requireSSL` or `issuerRef` specifies tls or ssl enable group replication which is a optional field.
-- `spec.replicationModeTransformation.mode` specifies the desired Group Replication Primary Mode (`Multi-Primary` or `Single-Primary`).
+- `spec.replicationModeTransformation.mode` specifies the desired Group Replication Primary Mode —
+  **`Single-Primary`** (default; one writable primary) or **`Multi-Primary`** (multi-master; every
+  member accepts writes). This field is ignored when `targetMode` is `SemiSync`.
 
 Let's create the `MySQLOpsRequest` CR we have shown above,
 
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml
new file mode 100644
index 0000000000..7608316440
--- /dev/null
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml
@@ -0,0 +1,14 @@
+apiVersion: ops.kubedb.com/v1alpha1
+kind: MySQLOpsRequest
+metadata:
+  name: gr-to-innodb
+  namespace: demo
+spec:
+  type: ReplicationModeTransformation
+  databaseRef:
+    name: my-cluster
+  replicationModeTransformation:
+    targetMode: InnoDBCluster
+    mode: Single-Primary
+  timeout: 20m
+  apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml
new file mode 100644
index 0000000000..53333b204d
--- /dev/null
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml
@@ -0,0 +1,13 @@
+apiVersion: ops.kubedb.com/v1alpha1
+kind: MySQLOpsRequest
+metadata:
+  name: gr-to-semisync
+  namespace: demo
+spec:
+  type: ReplicationModeTransformation
+  databaseRef:
+    name: my-cluster
+  replicationModeTransformation:
+    targetMode: SemiSync
+  timeout: 20m
+  apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml
new file mode 100644
index 0000000000..c090dd8b40
--- /dev/null
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml
@@ -0,0 +1,14 @@
+apiVersion: ops.kubedb.com/v1alpha1
+kind: MySQLOpsRequest
+metadata:
+  name: innodb-to-gr
+  namespace: demo
+spec:
+  type: ReplicationModeTransformation
+  databaseRef:
+    name: my-cluster
+  replicationModeTransformation:
+    targetMode: GroupReplication
+    mode: Single-Primary
+  timeout: 20m
+  apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-cluster.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-cluster.yaml
new file mode 100644
index 0000000000..7a75648961
--- /dev/null
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-cluster.yaml
@@ -0,0 +1,18 @@
+apiVersion: kubedb.com/v1
+kind: MySQL
+metadata:
+  name: my-cluster
+  namespace: demo
+spec:
+  version: "8.4.8"
+  replicas: 3
+  topology:
+    mode: GroupReplication
+  storageType: Durable
+  storage:
+    accessModes:
+      - ReadWriteOnce
+    resources:
+      requests:
+        storage: 1Gi
+  deletionPolicy: WipeOut
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-standalone.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-standalone.yaml
new file mode 100644
index 0000000000..c3efc2331d
--- /dev/null
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-standalone.yaml
@@ -0,0 +1,16 @@
+apiVersion: kubedb.com/v1
+kind: MySQL
+metadata:
+  name: my-standalone
+  namespace: demo
+spec:
+  version: "8.4.8"
+  replicas: 1
+  storageType: Durable
+  storage:
+    accessModes:
+      - ReadWriteOnce
+    resources:
+      requests:
+        storage: 1Gi
+  deletionPolicy: WipeOut
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-group-replication.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-group-replication.yaml
new file mode 100644
index 0000000000..5219a9702e
--- /dev/null
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-group-replication.yaml
@@ -0,0 +1,14 @@
+apiVersion: ops.kubedb.com/v1alpha1
+kind: MySQLOpsRequest
+metadata:
+  name: promote-to-gr
+  namespace: demo
+spec:
+  type: ReplicationModeTransformation
+  databaseRef:
+    name: my-standalone
+  replicationModeTransformation:
+    targetMode: GroupReplication
+    mode: Single-Primary
+  timeout: 15m
+  apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-innodb-cluster.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-innodb-cluster.yaml
new file mode 100644
index 0000000000..d5efe6e854
--- /dev/null
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-innodb-cluster.yaml
@@ -0,0 +1,14 @@
+apiVersion: ops.kubedb.com/v1alpha1
+kind: MySQLOpsRequest
+metadata:
+  name: promote-to-innodb
+  namespace: demo
+spec:
+  type: ReplicationModeTransformation
+  databaseRef:
+    name: my-standalone
+  replicationModeTransformation:
+    targetMode: InnoDBCluster
+    mode: Single-Primary
+  timeout: 15m
+  apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-multi-primary.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-multi-primary.yaml
new file mode 100644
index 0000000000..c1676c4574
--- /dev/null
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-multi-primary.yaml
@@ -0,0 +1,14 @@
+apiVersion: ops.kubedb.com/v1alpha1
+kind: MySQLOpsRequest
+metadata:
+  name: promote-to-multi-primary
+  namespace: demo
+spec:
+  type: ReplicationModeTransformation
+  databaseRef:
+    name: my-standalone
+  replicationModeTransformation:
+    targetMode: GroupReplication
+    mode: Multi-Primary
+  timeout: 15m
+  apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-semisync.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-semisync.yaml
new file mode 100644
index 0000000000..1dffacd391
--- /dev/null
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-semisync.yaml
@@ -0,0 +1,13 @@
+apiVersion: ops.kubedb.com/v1alpha1
+kind: MySQLOpsRequest
+metadata:
+  name: promote-to-semisync
+  namespace: demo
+spec:
+  type: ReplicationModeTransformation
+  databaseRef:
+    name: my-standalone
+  replicationModeTransformation:
+    targetMode: SemiSync
+  timeout: 15m
+  apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md b/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md
new file mode 100644
index 0000000000..29b12fad58
--- /dev/null
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md
@@ -0,0 +1,346 @@
+---
+title: MySQL Topology Mode Change
+menu:
+  docs_{{ .version }}:
+    identifier: guides-mysql-topology-mode-change
+    name: Topology Mode Change
+    parent: guides-mysql-mode-transform
+    weight: 13
+menu_name: docs_{{ .version }}
+section_menu_id: guides
+---
+
+> New to KubeDB? Please start [here](/docs/README.md).
+
+## MySQL Topology Mode Change
+
+This guide shows how to change the **mode (topology)** of an existing MySQL database with a
+`ReplicationModeTransformation` `MySQLOpsRequest` — promoting a **standalone** MySQL into a cluster,
+and switching an existing cluster between clustered topologies.
+
+The target topology is selected with `spec.replicationModeTransformation.targetMode`:
+`GroupReplication`, `InnoDBCluster` or `SemiSync`.
+
+> Transforming a **Remote Replica** is covered separately in
+> [Remote/Read Only Replica Mode Transfer](/docs/guides/mysql/replication-mode-transform/replication-mode-transform/index.md).
+
+### Supported Mode Changes
+
+| From (source) | → `GroupReplication` | → `InnoDBCluster` | → `SemiSync` |
+|---------------|:--------------------:|:-----------------:|:------------:|
+| **Standalone** (no `spec.topology`) | ✅ | ✅ | ✅ |
+| **GroupReplication** | — | ✅ | ✅ |
+| **InnoDBCluster** | ✅ | — | ❌ not supported yet |
+| **SemiSync** | ❌ not supported yet | ❌ not supported yet | — |
+
+Key guarantees:
+
+- **Your data is preserved.** A mode change never deletes a volume. When a new member has to be
+  seeded it is seeded in place with MySQL's `CLONE INSTANCE`, which overwrites the data directory
+  while the `PersistentVolumeClaim` is retained.
+- **Cluster → cluster happens in place.** `GroupReplication` ⇄ `InnoDBCluster` keeps the running
+  group and only hands over management — no teardown, no re-clone.
+- A standalone database is scaled up to at least **3 members**, since a clustered topology needs a
+  quorum.
+- Requires MySQL **8.4.2 or newer**.
+
+### Before You Begin
+
+- You need a Kubernetes cluster with the KubeDB operator installed — see [here](/docs/setup/README.md).
+- This tutorial uses the `demo` namespace:
+
+```bash
+$ kubectl create ns demo
+namespace/demo created
+```
+
+## Promote a Standalone MySQL
+
+### Deploy a standalone MySQL
+
+```yaml
+apiVersion: kubedb.com/v1
+kind: MySQL
+metadata:
+  name: my-standalone
+  namespace: demo
+spec:
+  version: "8.4.8"
+  replicas: 1
+  storageType: Durable
+  storage:
+    accessModes:
+      - ReadWriteOnce
+    resources:
+      requests:
+        storage: 1Gi
+  deletionPolicy: WipeOut
+```
+
+```bash
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-standalone.yaml
+mysql.kubedb.com/my-standalone created
+
+$ kubectl get mysql -n demo my-standalone
+NAME            VERSION   STATUS   AGE
+my-standalone   8.4.8     Ready    2m
+```
+
+Insert some data so you can confirm it survives the mode change:
+
+```bash
+$ kubectl exec -it -n demo my-standalone-0 -c mysql -- mysql -uroot -p'pass' \
+    -e "CREATE DATABASE playground; CREATE TABLE playground.t(id INT PRIMARY KEY); INSERT INTO playground.t VALUES(1),(2),(3);"
+```
+
+### Standalone → GroupReplication
+
+```yaml
+apiVersion: ops.kubedb.com/v1alpha1
+kind: MySQLOpsRequest
+metadata:
+  name: promote-to-gr
+  namespace: demo
+spec:
+  type: ReplicationModeTransformation
+  databaseRef:
+    name: my-standalone
+  replicationModeTransformation:
+    targetMode: GroupReplication
+    mode: Single-Primary
+  timeout: 15m
+  apply: Always
+```
+
+```bash
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-group-replication.yaml
+mysqlopsrequest.ops.kubedb.com/promote-to-gr created
+
+$ kubectl get mysqlopsrequest -n demo promote-to-gr
+NAME            TYPE                            STATUS       AGE
+promote-to-gr   ReplicationModeTransformation   Successful   3m
+```
+
+The standalone is scaled to a 3-member group and the pre-existing data is on every member:
+
+```bash
+$ kubectl exec -it -n demo my-standalone-0 -c mysql -- mysql -uroot -p'pass' \
+    -e "SELECT MEMBER_HOST, MEMBER_STATE, MEMBER_ROLE FROM performance_schema.replication_group_members;"
++-----------------------------------------+--------------+-------------+
+| MEMBER_HOST                             | MEMBER_STATE | MEMBER_ROLE |
++-----------------------------------------+--------------+-------------+
+| my-standalone-0.my-standalone-pods.demo | ONLINE       | PRIMARY     |
+| my-standalone-1.my-standalone-pods.demo | ONLINE       | SECONDARY   |
+| my-standalone-2.my-standalone-pods.demo | ONLINE       | SECONDARY   |
++-----------------------------------------+--------------+-------------+
+```
+
+#### Multi-Primary (multi-master)
+
+Set `mode: Multi-Primary` to get a multi-master group where **every member accepts writes**:
+
+```yaml
+  replicationModeTransformation:
+    targetMode: GroupReplication
+    mode: Multi-Primary
+```
+
+```bash
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-multi-primary.yaml
+mysqlopsrequest.ops.kubedb.com/promote-to-multi-primary created
+
+$ kubectl exec -it -n demo my-standalone-0 -c mysql -- mysql -uroot -p'pass' \
+    -e "SELECT MEMBER_HOST, MEMBER_ROLE FROM performance_schema.replication_group_members;"
++-----------------------------------------+-------------+
+| MEMBER_HOST                             | MEMBER_ROLE |
++-----------------------------------------+-------------+
+| my-standalone-0.my-standalone-pods.demo | PRIMARY     |
+| my-standalone-1.my-standalone-pods.demo | PRIMARY     |
+| my-standalone-2.my-standalone-pods.demo | PRIMARY     |
++-----------------------------------------+-------------+
+```
+
+All three members report `PRIMARY` and have `super_read_only=0`, so writes issued on any member are
+accepted and replicated to the rest.
+
+### Standalone → InnoDBCluster
+
+```yaml
+  replicationModeTransformation:
+    targetMode: InnoDBCluster
+    mode: Single-Primary
+```
+
+```bash
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-innodb-cluster.yaml
+mysqlopsrequest.ops.kubedb.com/promote-to-innodb created
+```
+
+In addition to the 3 database members, a **MySQL Router** is provisioned:
+
+```bash
+$ kubectl get pods -n demo | grep my-standalone
+my-standalone-0          2/2     Running   0   4m
+my-standalone-1          2/2     Running   0   4m
+my-standalone-2          2/2     Running   0   4m
+my-standalone-router-0   1/1     Running   0   4m
+```
+
+### Standalone → SemiSync
+
+```yaml
+  replicationModeTransformation:
+    targetMode: SemiSync
+```
+
+```bash
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-semisync.yaml
+mysqlopsrequest.ops.kubedb.com/promote-to-semisync created
+```
+
+This produces a semi-synchronous **primary** with standby replicas. The `mode` field does not apply
+here (SemiSync has no group), and the pod holding the existing data is elected as the primary:
+
+```bash
+$ kubectl get pods -n demo -L kubedb.com/role | grep my-standalone
+my-standalone-0   2/2   Running   0   3m   primary
+my-standalone-1   2/2   Running   0   3m   standby
+my-standalone-2   2/2   Running   0   3m   standby
+```
+
+## Change the Mode of an Existing Cluster
+
+Cluster-to-cluster changes are performed **in place**: the running group is kept and only its
+management changes, so there is no teardown, no re-clone and no data movement.
+
+Deploy a 3-member Group Replication cluster to work with:
+
+```yaml
+apiVersion: kubedb.com/v1
+kind: MySQL
+metadata:
+  name: my-cluster
+  namespace: demo
+spec:
+  version: "8.4.8"
+  replicas: 3
+  topology:
+    mode: GroupReplication
+  storageType: Durable
+  storage:
+    accessModes:
+      - ReadWriteOnce
+    resources:
+      requests:
+        storage: 1Gi
+  deletionPolicy: WipeOut
+```
+
+```bash
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-cluster.yaml
+mysql.kubedb.com/my-cluster created
+```
+
+### GroupReplication → InnoDBCluster
+
+The live Group Replication group is **adopted** into an InnoDB Cluster and a MySQL Router is added.
+
+```yaml
+apiVersion: ops.kubedb.com/v1alpha1
+kind: MySQLOpsRequest
+metadata:
+  name: gr-to-innodb
+  namespace: demo
+spec:
+  type: ReplicationModeTransformation
+  databaseRef:
+    name: my-cluster
+  replicationModeTransformation:
+    targetMode: InnoDBCluster
+    mode: Single-Primary
+  timeout: 20m
+  apply: Always
+```
+
+```bash
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml
+mysqlopsrequest.ops.kubedb.com/gr-to-innodb created
+
+$ kubectl get mysqlopsrequest -n demo gr-to-innodb
+NAME           TYPE                            STATUS       AGE
+gr-to-innodb   ReplicationModeTransformation   Successful   1m
+```
+
+Because the group is adopted rather than rebuilt, the members never restart and the change completes
+in well under a minute.
+
+### InnoDBCluster → GroupReplication
+
+The InnoDB Cluster management and its Router are removed, and the same group continues as plain
+Group Replication.
+
+```yaml
+  replicationModeTransformation:
+    targetMode: GroupReplication
+    mode: Single-Primary
+```
+
+```bash
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml
+mysqlopsrequest.ops.kubedb.com/innodb-to-gr created
+```
+
+> **Note:** removing the Router requires the KubeDB ops-manager ServiceAccount to be able to delete
+> `apps/deployments`. If that permission is missing the mode change still succeeds and the Router is
+> simply left behind, to be removed manually.
+
+### GroupReplication → SemiSync
+
+```yaml
+  replicationModeTransformation:
+    targetMode: SemiSync
+```
+
+```bash
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml
+mysqlopsrequest.ops.kubedb.com/gr-to-semisync created
+```
+
+### Not supported yet
+
+`SemiSync` → `GroupReplication`/`InnoDBCluster` and `InnoDBCluster` → `SemiSync` are not supported
+yet. SemiSync is asynchronous replication rather than a group, so those directions require forming
+or tearing down a real group and are still being worked on.
+
+## Verify
+
+After any mode change, confirm the new topology and that your data is intact on every member:
+
+```bash
+$ kubectl get mysql -n demo my-standalone -o jsonpath='{.spec.topology.mode}{"\n"}'
+GroupReplication
+
+$ for i in 0 1 2; do
+    kubectl exec -n demo my-standalone-$i -c mysql -- \
+      mysql -uroot -p'pass' -N -e "SELECT COUNT(*) FROM playground.t;"
+  done
+3
+3
+3
+```
+
+## Cleaning up
+
+```bash
+kubectl delete -n demo my/my-standalone my/my-cluster
+kubectl delete -n demo myops/promote-to-gr myops/promote-to-multi-primary
+kubectl delete -n demo myops/promote-to-innodb myops/promote-to-semisync
+kubectl delete -n demo myops/gr-to-innodb myops/innodb-to-gr myops/gr-to-semisync
+kubectl delete ns demo
+```
+
+## Next Steps
+
+- Detail concepts of [MySQL object](/docs/guides/mysql/concepts/database/index.md).
+- Detail concepts of [MySQLOpsRequest object](/docs/guides/mysql/concepts/opsrequest.md).
+- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md).

From e2c408f12ac253275aa9089d913ae0f25dd5e644 Mon Sep 17 00:00:00 2001
From: Sk Ali Arman <arman@appscode.com>
Date: Fri, 24 Jul 2026 07:02:22 +0000
Subject: [PATCH 2/4] docs/mysql: rename replication-mode-transform subdir to
 remote-replica-mode-transfer

The inner directory still carried the old section name, so the page URL
did not match its title. Rename it to remote-replica-mode-transfer and
update the cross-links from the overview and topology-mode-change guides.

Signed-off-by: Sk Ali Arman <arman@appscode.com>
---
 .../replication-mode-transform/overview/index.md   |  2 +-
 .../examples/issuer.yaml                           |  0
 .../examples/mode-transform-ops-request.yaml       |  0
 .../examples/mysql-ingress.yaml                    |  0
 .../examples/mysql-london-auth.yaml                |  0
 .../examples/mysql-london.yaml                     |  0
 .../examples/mysql-singapore-auth.yaml             |  0
 .../examples/mysql-singapore.yaml                  |  0
 .../index.md                                       | 14 +++++++-------
 .../topology-mode-change/index.md                  |  2 +-
 10 files changed, 9 insertions(+), 9 deletions(-)
 rename docs/guides/mysql/replication-mode-transform/{replication-mode-transform => remote-replica-mode-transfer}/examples/issuer.yaml (100%)
 rename docs/guides/mysql/replication-mode-transform/{replication-mode-transform => remote-replica-mode-transfer}/examples/mode-transform-ops-request.yaml (100%)
 rename docs/guides/mysql/replication-mode-transform/{replication-mode-transform => remote-replica-mode-transfer}/examples/mysql-ingress.yaml (100%)
 rename docs/guides/mysql/replication-mode-transform/{replication-mode-transform => remote-replica-mode-transfer}/examples/mysql-london-auth.yaml (100%)
 rename docs/guides/mysql/replication-mode-transform/{replication-mode-transform => remote-replica-mode-transfer}/examples/mysql-london.yaml (100%)
 rename docs/guides/mysql/replication-mode-transform/{replication-mode-transform => remote-replica-mode-transfer}/examples/mysql-singapore-auth.yaml (100%)
 rename docs/guides/mysql/replication-mode-transform/{replication-mode-transform => remote-replica-mode-transfer}/examples/mysql-singapore.yaml (100%)
 rename docs/guides/mysql/replication-mode-transform/{replication-mode-transform => remote-replica-mode-transfer}/index.md (98%)

diff --git a/docs/guides/mysql/replication-mode-transform/overview/index.md b/docs/guides/mysql/replication-mode-transform/overview/index.md
index 28cfa9e601..758618ec1c 100644
--- a/docs/guides/mysql/replication-mode-transform/overview/index.md
+++ b/docs/guides/mysql/replication-mode-transform/overview/index.md
@@ -21,7 +21,7 @@ Two step-by-step guides build on this overview:
 - [MySQL Topology Mode Change](/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md) — change the mode of an
   existing database: standalone → `GroupReplication` (Single-Primary or Multi-Primary) /
   `InnoDBCluster` / `SemiSync`, and changes between clustered topologies.
-- [MySQL Remote/Read Only Replica Mode Transfer](/docs/guides/mysql/replication-mode-transform/replication-mode-transform/index.md) —
+- [MySQL Remote/Read Only Replica Mode Transfer](/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/index.md) —
   transform a Remote Replica into a standalone or clustered database.
 
 ## Supported Transformations
diff --git a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/issuer.yaml b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/issuer.yaml
similarity index 100%
rename from docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/issuer.yaml
rename to docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/issuer.yaml
diff --git a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mode-transform-ops-request.yaml b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mode-transform-ops-request.yaml
similarity index 100%
rename from docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mode-transform-ops-request.yaml
rename to docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mode-transform-ops-request.yaml
diff --git a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-ingress.yaml b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-ingress.yaml
similarity index 100%
rename from docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-ingress.yaml
rename to docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-ingress.yaml
diff --git a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-london-auth.yaml b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-london-auth.yaml
similarity index 100%
rename from docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-london-auth.yaml
rename to docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-london-auth.yaml
diff --git a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-london.yaml b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-london.yaml
similarity index 100%
rename from docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-london.yaml
rename to docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-london.yaml
diff --git a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-singapore-auth.yaml b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-singapore-auth.yaml
similarity index 100%
rename from docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-singapore-auth.yaml
rename to docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-singapore-auth.yaml
diff --git a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-singapore.yaml b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-singapore.yaml
similarity index 100%
rename from docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-singapore.yaml
rename to docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-singapore.yaml
diff --git a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/index.md b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/index.md
similarity index 98%
rename from docs/guides/mysql/replication-mode-transform/replication-mode-transform/index.md
rename to docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/index.md
index 3b0400c5be..d477c2d99d 100644
--- a/docs/guides/mysql/replication-mode-transform/replication-mode-transform/index.md
+++ b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/index.md
@@ -97,7 +97,7 @@ spec:
 Let’s create the `Issuer` cr we have shown above,
 
 ```bash
-kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/issuer.yaml
+kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/issuer.yaml
 issuer.cert-manager.io/mysql-issuer created
 ```
 
@@ -115,7 +115,7 @@ metadata:
 type: kubernetes.io/basic-auth
 ```
 ```bash 
-$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-singapore-auth.yaml
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-singapore-auth.yaml
 secret/mysql-singapore-auth created
 ```
 ### Deploy MySQL with TLS/SSL configuration
@@ -161,7 +161,7 @@ spec:
 ```
 
 ```bash
-$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-singapore.yaml
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-singapore.yaml
 mysql.kubedb.com/mysql created
 ```
 
@@ -249,7 +249,7 @@ spec:
         pathType: Prefix
 ```
 ```bash
-$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-ingress.yaml
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-ingress.yaml
 ingress.networking.k8s.io/mysql-singapore created
 $ kubectl get ingress -n demo
 NAME              CLASS   HOSTS                           ADDRESS          PORTS   AGE
@@ -297,7 +297,7 @@ type: kubernetes.io/basic-auth
 ```
 
 ```bash
-kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-london-auth.yaml
+kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-london-auth.yaml
 ```
 
 ```yaml
@@ -340,7 +340,7 @@ Here,
 - `spec.topology.remoteReplica.sourceref` we are referring to source to read. The  mysql instance we previously created.
 - `spec.deletionPolicy` specifies what KubeDB should do when a user try to delete the operation of MySQL CR. *Wipeout* means that the database will be deleted without restrictions. It can also be "Halt", "Delete" and "DoNotTerminate". Learn More about these [HERE](https://kubedb.com/docs/latest/guides/mysql/concepts/database/#specdeletionpolicy).
 ```bash
-$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/replication-mode-transform/examples/mysql-london.yaml
+$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mysql-london.yaml
 mysql.kubedb.com/mysql-london created
 ```
 
@@ -440,7 +440,7 @@ Here,
 Let's create the `MySQLOpsRequest` CR we have shown above,
 
 ```bash
-$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/replication-mode-transform/mode-transform-ops-request.yaml
+$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/mode-transform-ops-request.yaml
 mysqlopsrequest.ops.kubedb.com/mysql-replication-mode-transform created
 ```
 
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md b/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md
index 29b12fad58..2044089288 100644
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md
@@ -22,7 +22,7 @@ The target topology is selected with `spec.replicationModeTransformation.targetM
 `GroupReplication`, `InnoDBCluster` or `SemiSync`.
 
 > Transforming a **Remote Replica** is covered separately in
-> [Remote/Read Only Replica Mode Transfer](/docs/guides/mysql/replication-mode-transform/replication-mode-transform/index.md).
+> [Remote/Read Only Replica Mode Transfer](/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/index.md).
 
 ### Supported Mode Changes
 

From 719b792782bd4a9842fc130df753b25feb9c957e Mon Sep 17 00:00:00 2001
From: Sk Ali Arman <arman@appscode.com>
Date: Thu, 30 Jul 2026 06:48:30 +0000
Subject: [PATCH 3/4] Follow the targetMode -> targetTopologyMode rename

Updates the mode-transform guides and every example manifest to the renamed
ops field. The prose that distinguished it from spec.replicationModeTransformation.mode
now reads unambiguously, which was the point of the rename.

Signed-off-by: Sk Ali Arman <arman@appscode.com>
---
 .../replication-mode-transform/overview/index.md |  2 +-
 .../examples/mode-transform-ops-request.yaml     |  2 +-
 .../remote-replica-mode-transfer/index.md        |  8 ++++----
 .../examples/gr-to-innodb-cluster.yaml           |  2 +-
 .../examples/gr-to-semisync.yaml                 |  2 +-
 .../examples/innodb-cluster-to-gr.yaml           |  2 +-
 .../examples/promote-to-group-replication.yaml   |  2 +-
 .../examples/promote-to-innodb-cluster.yaml      |  2 +-
 .../examples/promote-to-multi-primary.yaml       |  2 +-
 .../examples/promote-to-semisync.yaml            |  2 +-
 .../topology-mode-change/index.md                | 16 ++++++++--------
 11 files changed, 21 insertions(+), 21 deletions(-)

diff --git a/docs/guides/mysql/replication-mode-transform/overview/index.md b/docs/guides/mysql/replication-mode-transform/overview/index.md
index 758618ec1c..a4a8483763 100644
--- a/docs/guides/mysql/replication-mode-transform/overview/index.md
+++ b/docs/guides/mysql/replication-mode-transform/overview/index.md
@@ -26,7 +26,7 @@ Two step-by-step guides build on this overview:
 
 ## Supported Transformations
 
-The target topology is selected with `spec.replicationModeTransformation.targetMode`, which accepts
+The target topology is selected with `spec.replicationModeTransformation.targetTopologyMode`, which accepts
 `GroupReplication` (default), `InnoDBCluster` or `SemiSync`.
 
 | From (source) | To `GroupReplication` | To `InnoDBCluster` | To `SemiSync` |
diff --git a/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mode-transform-ops-request.yaml b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mode-transform-ops-request.yaml
index ba900c8ca1..5417335e27 100644
--- a/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mode-transform-ops-request.yaml
+++ b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/examples/mode-transform-ops-request.yaml
@@ -8,7 +8,7 @@ spec:
   databaseRef:
     name: mysql-london
   replicationModeTransformation:
-    targetMode: GroupReplication
+    targetTopologyMode: GroupReplication
     mode: Single-Primary
     requireSSL: true
     issuerRef:
diff --git a/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/index.md b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/index.md
index d477c2d99d..95eb98464a 100644
--- a/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/index.md
+++ b/docs/guides/mysql/replication-mode-transform/remote-replica-mode-transfer/index.md
@@ -21,7 +21,7 @@ you want to promote the remote replica into a self-standing cluster.
 > Looking to change the mode of an existing database (standalone → cluster, or between clustered
 > topologies)? See [MySQL Topology Mode Change](/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md).
 
-The target topology is chosen with `spec.replicationModeTransformation.targetMode`. See the
+The target topology is chosen with `spec.replicationModeTransformation.targetTopologyMode`. See the
 [overview](/docs/guides/mysql/replication-mode-transform/overview/index.md) for the full support
 matrix.
 
@@ -406,7 +406,7 @@ spec:
   databaseRef:
     name: mysql-london
   replicationModeTransformation:
-    targetMode: GroupReplication
+    targetTopologyMode: GroupReplication
     mode: Single-Primary
     requireSSL: true
     issuerRef:
@@ -430,12 +430,12 @@ Here,
 
 - `spec.databaseRef.name` specifies that we are performing Replication Mode Transformation operation on `mysql-london` database.
 - `spec.type` specifies that we are performing `ReplicationModeTransformation` on our database.
-- `spec.replicationModeTransformation.targetMode` specifies the topology to transform into —
+- `spec.replicationModeTransformation.targetTopologyMode` specifies the topology to transform into —
   `GroupReplication` (default), `InnoDBCluster` or `SemiSync`.
 - `spec.replicationModeTransformation.requireSSL` or `issuerRef` specifies tls or ssl enable group replication which is a optional field.
 - `spec.replicationModeTransformation.mode` specifies the desired Group Replication Primary Mode —
   **`Single-Primary`** (default; one writable primary) or **`Multi-Primary`** (multi-master; every
-  member accepts writes). This field is ignored when `targetMode` is `SemiSync`.
+  member accepts writes). This field is ignored when `targetTopologyMode` is `SemiSync`.
 
 Let's create the `MySQLOpsRequest` CR we have shown above,
 
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml
index 7608316440..1b9a27ffb6 100644
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml
@@ -8,7 +8,7 @@ spec:
   databaseRef:
     name: my-cluster
   replicationModeTransformation:
-    targetMode: InnoDBCluster
+    targetTopologyMode: InnoDBCluster
     mode: Single-Primary
   timeout: 20m
   apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml
index 53333b204d..c5b8868b92 100644
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml
@@ -8,6 +8,6 @@ spec:
   databaseRef:
     name: my-cluster
   replicationModeTransformation:
-    targetMode: SemiSync
+    targetTopologyMode: SemiSync
   timeout: 20m
   apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml
index c090dd8b40..e724e7c0f5 100644
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml
@@ -8,7 +8,7 @@ spec:
   databaseRef:
     name: my-cluster
   replicationModeTransformation:
-    targetMode: GroupReplication
+    targetTopologyMode: GroupReplication
     mode: Single-Primary
   timeout: 20m
   apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-group-replication.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-group-replication.yaml
index 5219a9702e..b62eb93dcc 100644
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-group-replication.yaml
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-group-replication.yaml
@@ -8,7 +8,7 @@ spec:
   databaseRef:
     name: my-standalone
   replicationModeTransformation:
-    targetMode: GroupReplication
+    targetTopologyMode: GroupReplication
     mode: Single-Primary
   timeout: 15m
   apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-innodb-cluster.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-innodb-cluster.yaml
index d5efe6e854..c99b0b62e0 100644
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-innodb-cluster.yaml
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-innodb-cluster.yaml
@@ -8,7 +8,7 @@ spec:
   databaseRef:
     name: my-standalone
   replicationModeTransformation:
-    targetMode: InnoDBCluster
+    targetTopologyMode: InnoDBCluster
     mode: Single-Primary
   timeout: 15m
   apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-multi-primary.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-multi-primary.yaml
index c1676c4574..2ed567793f 100644
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-multi-primary.yaml
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-multi-primary.yaml
@@ -8,7 +8,7 @@ spec:
   databaseRef:
     name: my-standalone
   replicationModeTransformation:
-    targetMode: GroupReplication
+    targetTopologyMode: GroupReplication
     mode: Multi-Primary
   timeout: 15m
   apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-semisync.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-semisync.yaml
index 1dffacd391..c1fcd09196 100644
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-semisync.yaml
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/promote-to-semisync.yaml
@@ -8,6 +8,6 @@ spec:
   databaseRef:
     name: my-standalone
   replicationModeTransformation:
-    targetMode: SemiSync
+    targetTopologyMode: SemiSync
   timeout: 15m
   apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md b/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md
index 2044089288..c295a118b3 100644
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md
@@ -18,7 +18,7 @@ This guide shows how to change the **mode (topology)** of an existing MySQL data
 `ReplicationModeTransformation` `MySQLOpsRequest` — promoting a **standalone** MySQL into a cluster,
 and switching an existing cluster between clustered topologies.
 
-The target topology is selected with `spec.replicationModeTransformation.targetMode`:
+The target topology is selected with `spec.replicationModeTransformation.targetTopologyMode`:
 `GroupReplication`, `InnoDBCluster` or `SemiSync`.
 
 > Transforming a **Remote Replica** is covered separately in
@@ -106,7 +106,7 @@ spec:
   databaseRef:
     name: my-standalone
   replicationModeTransformation:
-    targetMode: GroupReplication
+    targetTopologyMode: GroupReplication
     mode: Single-Primary
   timeout: 15m
   apply: Always
@@ -141,7 +141,7 @@ Set `mode: Multi-Primary` to get a multi-master group where **every member accep
 
 ```yaml
   replicationModeTransformation:
-    targetMode: GroupReplication
+    targetTopologyMode: GroupReplication
     mode: Multi-Primary
 ```
 
@@ -167,7 +167,7 @@ accepted and replicated to the rest.
 
 ```yaml
   replicationModeTransformation:
-    targetMode: InnoDBCluster
+    targetTopologyMode: InnoDBCluster
     mode: Single-Primary
 ```
 
@@ -190,7 +190,7 @@ my-standalone-router-0   1/1     Running   0   4m
 
 ```yaml
   replicationModeTransformation:
-    targetMode: SemiSync
+    targetTopologyMode: SemiSync
 ```
 
 ```bash
@@ -256,7 +256,7 @@ spec:
   databaseRef:
     name: my-cluster
   replicationModeTransformation:
-    targetMode: InnoDBCluster
+    targetTopologyMode: InnoDBCluster
     mode: Single-Primary
   timeout: 20m
   apply: Always
@@ -281,7 +281,7 @@ Group Replication.
 
 ```yaml
   replicationModeTransformation:
-    targetMode: GroupReplication
+    targetTopologyMode: GroupReplication
     mode: Single-Primary
 ```
 
@@ -298,7 +298,7 @@ mysqlopsrequest.ops.kubedb.com/innodb-to-gr created
 
 ```yaml
   replicationModeTransformation:
-    targetMode: SemiSync
+    targetTopologyMode: SemiSync
 ```
 
 ```bash

From 1c699a535004476fe1813b7ae1c80cfc7f0671d5 Mon Sep 17 00:00:00 2001
From: Sk Ali Arman <arman@appscode.com>
Date: Thu, 30 Jul 2026 12:35:34 +0000
Subject: [PATCH 4/4] Scope mode transform to Standalone and RemoteReplica
 sources

Cluster-to-cluster topology change is not supported: a database already running
GroupReplication, InnoDBCluster or SemiSync cannot be transformed into a
different one. Only a Standalone or RemoteReplica source is supported.

Updates both support matrices, replaces the cluster-to-cluster walkthrough with
a not-supported note pointing at backup/restore into a newly provisioned
database, and drops the example manifests for those paths so they cannot be
applied.

Signed-off-by: Sk Ali Arman <arman@appscode.com>
---
 .../overview/index.md                         |  13 +-
 .../examples/gr-to-innodb-cluster.yaml        |  14 --
 .../examples/gr-to-semisync.yaml              |  13 --
 .../examples/innodb-cluster-to-gr.yaml        |  14 --
 .../examples/my-cluster.yaml                  |  18 ---
 .../topology-mode-change/index.md             | 124 +++---------------
 6 files changed, 23 insertions(+), 173 deletions(-)
 delete mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml
 delete mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml
 delete mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml
 delete mode 100644 docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-cluster.yaml

diff --git a/docs/guides/mysql/replication-mode-transform/overview/index.md b/docs/guides/mysql/replication-mode-transform/overview/index.md
index a4a8483763..0cd3a5b8f0 100644
--- a/docs/guides/mysql/replication-mode-transform/overview/index.md
+++ b/docs/guides/mysql/replication-mode-transform/overview/index.md
@@ -29,12 +29,15 @@ Two step-by-step guides build on this overview:
 The target topology is selected with `spec.replicationModeTransformation.targetTopologyMode`, which accepts
 `GroupReplication` (default), `InnoDBCluster` or `SemiSync`.
 
+Transformation is supported **from a `Standalone` or a `RemoteReplica` source**. Transforming one
+clustered topology into another is not supported yet.
+
 | From (source) | To `GroupReplication` | To `InnoDBCluster` | To `SemiSync` |
 |---------------|:---------------------:|:------------------:|:-------------:|
 | **Standalone** (no `spec.topology`) | ✅ | ✅ | ✅ |
 | **RemoteReplica** | ✅ | ✅ | ✅ |
-| **GroupReplication** | — | ✅ | ✅ |
-| **InnoDBCluster** | ✅ | — | ❌ not supported yet |
+| **GroupReplication** | — | ❌ not supported yet | ❌ not supported yet |
+| **InnoDBCluster** | ❌ not supported yet | — | ❌ not supported yet |
 | **SemiSync** | ❌ not supported yet | ❌ not supported yet | — |
 
 Notes:
@@ -42,9 +45,9 @@ Notes:
 - **Your data is preserved.** Promotions and transformations never delete a volume. When a new
   replica has to be seeded, it is seeded in place with MySQL's `CLONE INSTANCE`, which overwrites
   the data directory while the `PersistentVolumeClaim` is retained.
-- **Transformations between clustered topologies happen in place.** `GroupReplication` ⇄
-  `InnoDBCluster` keeps the running group and simply hands over management (adopting the group into
-  an InnoDB Cluster, or releasing it back to plain Group Replication) — no teardown and no re-clone.
+- **Cluster-to-cluster transformation is not supported.** A database that already runs a clustered
+  topology (`GroupReplication`, `InnoDBCluster` or `SemiSync`) cannot be transformed into a
+  different one. Apply the transformation only to a `Standalone` or `RemoteReplica` database.
 - A standalone database is scaled up to at least 3 members when it is promoted, since a clustered
   topology needs a quorum.
 - `spec.replicationModeTransformation.mode` selects the Group Replication primary mode —
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml
deleted file mode 100644
index 1b9a27ffb6..0000000000
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-apiVersion: ops.kubedb.com/v1alpha1
-kind: MySQLOpsRequest
-metadata:
-  name: gr-to-innodb
-  namespace: demo
-spec:
-  type: ReplicationModeTransformation
-  databaseRef:
-    name: my-cluster
-  replicationModeTransformation:
-    targetTopologyMode: InnoDBCluster
-    mode: Single-Primary
-  timeout: 20m
-  apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml
deleted file mode 100644
index c5b8868b92..0000000000
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml
+++ /dev/null
@@ -1,13 +0,0 @@
-apiVersion: ops.kubedb.com/v1alpha1
-kind: MySQLOpsRequest
-metadata:
-  name: gr-to-semisync
-  namespace: demo
-spec:
-  type: ReplicationModeTransformation
-  databaseRef:
-    name: my-cluster
-  replicationModeTransformation:
-    targetTopologyMode: SemiSync
-  timeout: 20m
-  apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml
deleted file mode 100644
index e724e7c0f5..0000000000
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-apiVersion: ops.kubedb.com/v1alpha1
-kind: MySQLOpsRequest
-metadata:
-  name: innodb-to-gr
-  namespace: demo
-spec:
-  type: ReplicationModeTransformation
-  databaseRef:
-    name: my-cluster
-  replicationModeTransformation:
-    targetTopologyMode: GroupReplication
-    mode: Single-Primary
-  timeout: 20m
-  apply: Always
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-cluster.yaml b/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-cluster.yaml
deleted file mode 100644
index 7a75648961..0000000000
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-cluster.yaml
+++ /dev/null
@@ -1,18 +0,0 @@
-apiVersion: kubedb.com/v1
-kind: MySQL
-metadata:
-  name: my-cluster
-  namespace: demo
-spec:
-  version: "8.4.8"
-  replicas: 3
-  topology:
-    mode: GroupReplication
-  storageType: Durable
-  storage:
-    accessModes:
-      - ReadWriteOnce
-    resources:
-      requests:
-        storage: 1Gi
-  deletionPolicy: WipeOut
diff --git a/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md b/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md
index c295a118b3..938b5a3cb1 100644
--- a/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md
+++ b/docs/guides/mysql/replication-mode-transform/topology-mode-change/index.md
@@ -15,8 +15,8 @@ section_menu_id: guides
 ## MySQL Topology Mode Change
 
 This guide shows how to change the **mode (topology)** of an existing MySQL database with a
-`ReplicationModeTransformation` `MySQLOpsRequest` — promoting a **standalone** MySQL into a cluster,
-and switching an existing cluster between clustered topologies.
+`ReplicationModeTransformation` `MySQLOpsRequest` — promoting a **standalone** MySQL into a
+clustered topology.
 
 The target topology is selected with `spec.replicationModeTransformation.targetTopologyMode`:
 `GroupReplication`, `InnoDBCluster` or `SemiSync`.
@@ -26,11 +26,15 @@ The target topology is selected with `spec.replicationModeTransformation.targetT
 
 ### Supported Mode Changes
 
+The source database must be **`Standalone`** (no `spec.topology`) or a **`RemoteReplica`**.
+Changing one clustered topology into another is not supported yet.
+
 | From (source) | → `GroupReplication` | → `InnoDBCluster` | → `SemiSync` |
 |---------------|:--------------------:|:-----------------:|:------------:|
 | **Standalone** (no `spec.topology`) | ✅ | ✅ | ✅ |
-| **GroupReplication** | — | ✅ | ✅ |
-| **InnoDBCluster** | ✅ | — | ❌ not supported yet |
+| **RemoteReplica** | ✅ | ✅ | ✅ |
+| **GroupReplication** | — | ❌ not supported yet | ❌ not supported yet |
+| **InnoDBCluster** | ❌ not supported yet | — | ❌ not supported yet |
 | **SemiSync** | ❌ not supported yet | ❌ not supported yet | — |
 
 Key guarantees:
@@ -38,8 +42,6 @@ Key guarantees:
 - **Your data is preserved.** A mode change never deletes a volume. When a new member has to be
   seeded it is seeded in place with MySQL's `CLONE INSTANCE`, which overwrites the data directory
   while the `PersistentVolumeClaim` is retained.
-- **Cluster → cluster happens in place.** `GroupReplication` ⇄ `InnoDBCluster` keeps the running
-  group and only hands over management — no teardown, no re-clone.
 - A standalone database is scaled up to at least **3 members**, since a clustered topology needs a
   quorum.
 - Requires MySQL **8.4.2 or newer**.
@@ -208,109 +210,14 @@ my-standalone-1   2/2   Running   0   3m   standby
 my-standalone-2   2/2   Running   0   3m   standby
 ```
 
-## Change the Mode of an Existing Cluster
-
-Cluster-to-cluster changes are performed **in place**: the running group is kept and only its
-management changes, so there is no teardown, no re-clone and no data movement.
-
-Deploy a 3-member Group Replication cluster to work with:
-
-```yaml
-apiVersion: kubedb.com/v1
-kind: MySQL
-metadata:
-  name: my-cluster
-  namespace: demo
-spec:
-  version: "8.4.8"
-  replicas: 3
-  topology:
-    mode: GroupReplication
-  storageType: Durable
-  storage:
-    accessModes:
-      - ReadWriteOnce
-    resources:
-      requests:
-        storage: 1Gi
-  deletionPolicy: WipeOut
-```
-
-```bash
-$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/my-cluster.yaml
-mysql.kubedb.com/my-cluster created
-```
-
-### GroupReplication → InnoDBCluster
-
-The live Group Replication group is **adopted** into an InnoDB Cluster and a MySQL Router is added.
-
-```yaml
-apiVersion: ops.kubedb.com/v1alpha1
-kind: MySQLOpsRequest
-metadata:
-  name: gr-to-innodb
-  namespace: demo
-spec:
-  type: ReplicationModeTransformation
-  databaseRef:
-    name: my-cluster
-  replicationModeTransformation:
-    targetTopologyMode: InnoDBCluster
-    mode: Single-Primary
-  timeout: 20m
-  apply: Always
-```
-
-```bash
-$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-innodb-cluster.yaml
-mysqlopsrequest.ops.kubedb.com/gr-to-innodb created
-
-$ kubectl get mysqlopsrequest -n demo gr-to-innodb
-NAME           TYPE                            STATUS       AGE
-gr-to-innodb   ReplicationModeTransformation   Successful   1m
-```
-
-Because the group is adopted rather than rebuilt, the members never restart and the change completes
-in well under a minute.
-
-### InnoDBCluster → GroupReplication
-
-The InnoDB Cluster management and its Router are removed, and the same group continues as plain
-Group Replication.
-
-```yaml
-  replicationModeTransformation:
-    targetTopologyMode: GroupReplication
-    mode: Single-Primary
-```
-
-```bash
-$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/innodb-cluster-to-gr.yaml
-mysqlopsrequest.ops.kubedb.com/innodb-to-gr created
-```
-
-> **Note:** removing the Router requires the KubeDB ops-manager ServiceAccount to be able to delete
-> `apps/deployments`. If that permission is missing the mode change still succeeds and the Router is
-> simply left behind, to be removed manually.
-
-### GroupReplication → SemiSync
-
-```yaml
-  replicationModeTransformation:
-    targetTopologyMode: SemiSync
-```
-
-```bash
-$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/mysql/replication-mode-transform/topology-mode-change/examples/gr-to-semisync.yaml
-mysqlopsrequest.ops.kubedb.com/gr-to-semisync created
-```
+## Changing the Mode of an Existing Cluster
 
-### Not supported yet
+**Not supported yet.** A database that already runs a clustered topology
+(`GroupReplication`, `InnoDBCluster` or `SemiSync`) cannot be transformed into a different one.
+`ReplicationModeTransformation` applies to a **`Standalone`** or **`RemoteReplica`** source only.
 
-`SemiSync` → `GroupReplication`/`InnoDBCluster` and `InnoDBCluster` → `SemiSync` are not supported
-yet. SemiSync is asynchronous replication rather than a group, so those directions require forming
-or tearing down a real group and are still being worked on.
+To move an existing cluster to another topology, take a backup and restore it into a new database
+provisioned with the topology you want.
 
 ## Verify
 
@@ -332,10 +239,9 @@ $ for i in 0 1 2; do
 ## Cleaning up
 
 ```bash
-kubectl delete -n demo my/my-standalone my/my-cluster
+kubectl delete -n demo my/my-standalone
 kubectl delete -n demo myops/promote-to-gr myops/promote-to-multi-primary
 kubectl delete -n demo myops/promote-to-innodb myops/promote-to-semisync
-kubectl delete -n demo myops/gr-to-innodb myops/innodb-to-gr myops/gr-to-semisync
 kubectl delete ns demo
 ```