From 57aa50be3a29b34aa63cb922da3f306010e347d7 Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Tue, 22 Jul 2025 22:42:13 +0000 Subject: [PATCH 01/13] etcd-website: Update migration process with etcdctl v3.4 Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- .../v3.6/tasks/operator/how-to-migrate.md | 71 ++++++++++++++++++- 1 file changed, 69 insertions(+), 2 deletions(-) diff --git a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md index 80bd29acf..4a8250cb9 100644 --- a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md +++ b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md @@ -4,10 +4,71 @@ description: etcd v2 to v3 migration guide weight: 1200 --- -`migrate` to transform etcd v2 to v3 data: +`migrate` to transform etcd v2 data model to v3 data model. -![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) +> [!Warning] **Deprecated functionality:** +> +> The `etcdctl migrate` command was removed in etcd v3.5.0 ([pull/12971](https://github.com/etcd-io/etcd/pull/12971)). If your etcd cluster is already running v3.5 or higher, you can no longer migrate v2 data to v3 using this method. +> +> You **must use etcdctl v3.4 or earlier** to perform the migration ([CHANGELOG-3.5](https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.5.md#etcdctl-v3-3)). However please take appropriate precautions when using it, as it is no longer officially supported or tested in recent releases. + + + +## Pre-requisites + +Before migrating from etcd v2 to v3, ensure the following: +- A currently running etcd v2 cluster. +- The `etcdctl` CLI tool version <= v3.4. +- Access to each etcd node and their data directories. +- A working backup of your etcd data before performing the migration. + +## Migrate a cluster + +The following steps show how to migrate your etcd data from v2 to v3 using `etcdctl migrate`. + +### Variables and Flags Used + +- `--endpoints`: Specifies the etcd cluster endpoint(s). +- `--output`: Output format (e.g., `"json"`). +- `--data-dir`: Path to the data directory (default: `default.etcd`). View more at [etcd flags](https://etcd.io/docs/v3.6/op-guide/configuration/#member). +- `--wal-dir`: The write-ahead log directory inside `data-dir` (default: `default.etcd/member/wal`). View more at [etcd flags](https://etcd.io/docs/v3.6/op-guide/configuration/#member). +- `set`: Command to set a key-value pair in etcd v2 (View [READMEv2](https://github.com/etcd-io/etcd/blob/main/etcdctl/READMEv2.md#setting-key-values). In v3 we're using `put` command rather than `set`, view [READMEv3](https://github.com/etcd-io/etcd/tree/main/etcdctl#key-value-commands)). +- `get`: Command to retrieve a key-value pair (View [Read keys](https://etcd.io/docs/v3.6/dev-guide/interacting_v3/#read-keys)) + +### Migration Process + +1. Set up test key using v2 API + +```sh +export ETCDCTL_API=2 +etcdctl --endpoints=http://$ENDPOINT set foo bar +etcdctl --endpoints=http://$ENDPOINT --output="json" get foo +``` + +2. Stop each etcd node (one at a time) +Before running the migration, stop your etcd node to ensure data consistency. + +3. Run the migration tool + +Switch to API v3 and use etcdctl migrate to transform the v2 store. +```sh +export ETCDCTL_API=3 +etcdctl --endpoints=http://$ENDPOINT migrate \ + --data-dir="default.etcd" \ + --wal-dir="default.etcd/member/wal" +``` + +4. Restart etcd node after migrate +Repeat steps 2–4 for each etcd node one at a time in your cluster. + +5. Confirm the data is accessible via v3 API + +```sh +etcdctl --endpoints=$ENDPOINTS get /foo +``` + +Summary full process: ```shell # write key in etcd version 2 store @@ -28,3 +89,9 @@ etcdctl --endpoints=$ENDPOINT migrate --data-dir="default.etcd" --wal-dir="defau # confirm that the key got migrated etcdctl --endpoints=$ENDPOINTS get /foo ``` + + +## Visual guide for reference + +![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) + From a4b37544093658d2774185f7920033511b20256e Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Tue, 22 Jul 2025 22:51:38 +0000 Subject: [PATCH 02/13] etcd-website: fix lints failed Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- .../en/docs/v3.6/tasks/operator/how-to-migrate.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md index 4a8250cb9..7a096d38a 100644 --- a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md +++ b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md @@ -6,17 +6,16 @@ weight: 1200 `migrate` to transform etcd v2 data model to v3 data model. -> [!Warning] **Deprecated functionality:** -> +> [!Warning] **Deprecated functionality:** +> > The `etcdctl migrate` command was removed in etcd v3.5.0 ([pull/12971](https://github.com/etcd-io/etcd/pull/12971)). If your etcd cluster is already running v3.5 or higher, you can no longer migrate v2 data to v3 using this method. -> +> > You **must use etcdctl v3.4 or earlier** to perform the migration ([CHANGELOG-3.5](https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.5.md#etcdctl-v3-3)). However please take appropriate precautions when using it, as it is no longer officially supported or tested in recent releases. - - ## Pre-requisites Before migrating from etcd v2 to v3, ensure the following: + - A currently running etcd v2 cluster. - The `etcdctl` CLI tool version <= v3.4. - Access to each etcd node and their data directories. @@ -52,6 +51,7 @@ Before running the migration, stop your etcd node to ensure data consistency. 3. Run the migration tool Switch to API v3 and use etcdctl migrate to transform the v2 store. + ```sh export ETCDCTL_API=3 etcdctl --endpoints=http://$ENDPOINT migrate \ @@ -90,8 +90,6 @@ etcdctl --endpoints=$ENDPOINT migrate --data-dir="default.etcd" --wal-dir="defau etcdctl --endpoints=$ENDPOINTS get /foo ``` - ## Visual guide for reference -![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) - +![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) \ No newline at end of file From d52a79af80566d05e0f6b3eb9fccb2455abe224b Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Tue, 22 Jul 2025 22:54:36 +0000 Subject: [PATCH 03/13] etcd-website: revise the set command for clearer Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- content/en/docs/v3.6/tasks/operator/how-to-migrate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md index 7a096d38a..a8ea55d1d 100644 --- a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md +++ b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md @@ -31,7 +31,7 @@ The following steps show how to migrate your etcd data from v2 to v3 using `etcd - `--output`: Output format (e.g., `"json"`). - `--data-dir`: Path to the data directory (default: `default.etcd`). View more at [etcd flags](https://etcd.io/docs/v3.6/op-guide/configuration/#member). - `--wal-dir`: The write-ahead log directory inside `data-dir` (default: `default.etcd/member/wal`). View more at [etcd flags](https://etcd.io/docs/v3.6/op-guide/configuration/#member). -- `set`: Command to set a key-value pair in etcd v2 (View [READMEv2](https://github.com/etcd-io/etcd/blob/main/etcdctl/READMEv2.md#setting-key-values). In v3 we're using `put` command rather than `set`, view [READMEv3](https://github.com/etcd-io/etcd/tree/main/etcdctl#key-value-commands)). +- `set`: Command to set a key-value pair in etcd v2 (View [READMEv2](https://github.com/etcd-io/etcd/blob/main/etcdctl/READMEv2.md#setting-key-values) for more details. In etcd v3, the equivalent command is `put` instead of `set`, see the [READMEv3](https://github.com/etcd-io/etcd/tree/main/etcdctl#key-value-commands)) for reference. - `get`: Command to retrieve a key-value pair (View [Read keys](https://etcd.io/docs/v3.6/dev-guide/interacting_v3/#read-keys)) ### Migration Process From b5a7dcbba27ef991bbaa47447c650a3db38f7e15 Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Tue, 22 Jul 2025 22:59:37 +0000 Subject: [PATCH 04/13] etcd-website: fix lint failed with order list Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- .../en/docs/v3.6/tasks/operator/how-to-migrate.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md index a8ea55d1d..afbe76653 100644 --- a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md +++ b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md @@ -36,7 +36,7 @@ The following steps show how to migrate your etcd data from v2 to v3 using `etcd ### Migration Process -1. Set up test key using v2 API +- Step 1: Set up test key using v2 API ```sh export ETCDCTL_API=2 @@ -44,11 +44,11 @@ etcdctl --endpoints=http://$ENDPOINT set foo bar etcdctl --endpoints=http://$ENDPOINT --output="json" get foo ``` -2. Stop each etcd node (one at a time) +- Step 2: Stop each etcd node (one at a time) Before running the migration, stop your etcd node to ensure data consistency. -3. Run the migration tool +- Step 3: Run the migration tool Switch to API v3 and use etcdctl migrate to transform the v2 store. @@ -59,10 +59,10 @@ etcdctl --endpoints=http://$ENDPOINT migrate \ --wal-dir="default.etcd/member/wal" ``` -4. Restart etcd node after migrate +- Step 4: Restart etcd node after migrate Repeat steps 2–4 for each etcd node one at a time in your cluster. -5. Confirm the data is accessible via v3 API +- Step 5: Confirm the data is accessible via v3 API ```sh etcdctl --endpoints=$ENDPOINTS get /foo @@ -92,4 +92,4 @@ etcdctl --endpoints=$ENDPOINTS get /foo ## Visual guide for reference -![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) \ No newline at end of file +![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) From 8434658bb3a82714c821d3908842ecb2dcc365f7 Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Tue, 22 Jul 2025 23:00:35 +0000 Subject: [PATCH 05/13] etcd-website: fix DCO Sign check failed Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- content/en/docs/v3.6/tasks/operator/how-to-migrate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md index afbe76653..8a373f5c8 100644 --- a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md +++ b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md @@ -32,7 +32,7 @@ The following steps show how to migrate your etcd data from v2 to v3 using `etcd - `--data-dir`: Path to the data directory (default: `default.etcd`). View more at [etcd flags](https://etcd.io/docs/v3.6/op-guide/configuration/#member). - `--wal-dir`: The write-ahead log directory inside `data-dir` (default: `default.etcd/member/wal`). View more at [etcd flags](https://etcd.io/docs/v3.6/op-guide/configuration/#member). - `set`: Command to set a key-value pair in etcd v2 (View [READMEv2](https://github.com/etcd-io/etcd/blob/main/etcdctl/READMEv2.md#setting-key-values) for more details. In etcd v3, the equivalent command is `put` instead of `set`, see the [READMEv3](https://github.com/etcd-io/etcd/tree/main/etcdctl#key-value-commands)) for reference. -- `get`: Command to retrieve a key-value pair (View [Read keys](https://etcd.io/docs/v3.6/dev-guide/interacting_v3/#read-keys)) +- `get`: Command to retrieve a key-value pair (View [Read keys](https://etcd.io/docs/v3.6/dev-guide/interacting_v3/#read-keys)). ### Migration Process From 417a148999bc5e0a8a7028022b60fdf5409f67c8 Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Tue, 22 Jul 2025 23:08:39 +0000 Subject: [PATCH 06/13] etcd-website: fix alerts panel Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- .../en/docs/v3.6/tasks/operator/how-to-migrate.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md index 8a373f5c8..51fdd5385 100644 --- a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md +++ b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md @@ -6,11 +6,13 @@ weight: 1200 `migrate` to transform etcd v2 data model to v3 data model. -> [!Warning] **Deprecated functionality:** -> -> The `etcdctl migrate` command was removed in etcd v3.5.0 ([pull/12971](https://github.com/etcd-io/etcd/pull/12971)). If your etcd cluster is already running v3.5 or higher, you can no longer migrate v2 data to v3 using this method. -> -> You **must use etcdctl v3.4 or earlier** to perform the migration ([CHANGELOG-3.5](https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.5.md#etcdctl-v3-3)). However please take appropriate precautions when using it, as it is no longer officially supported or tested in recent releases. +{{% alert color="warning" %}} + **Deprecated functionality:** + +The `etcdctl migrate` command was removed in etcd v3.5.0 ([pull/12971](https://github.com/etcd-io/etcd/pull/12971)). If your etcd cluster is already running v3.5 or higher, you can no longer migrate v2 data to v3 using this method. + +You **must use etcdctl v3.4 or earlier** to perform the migration ([CHANGELOG-3.5](https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.5.md#etcdctl-v3-3)). However please take appropriate precautions when using it, as it is no longer officially supported or tested in recent releases. +{{% /alert %}} ## Pre-requisites From aef6bc4e386fdc53a66abbe9d6c3674ed3ee7dc5 Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Tue, 22 Jul 2025 23:11:06 +0000 Subject: [PATCH 07/13] etcd-website: fix lint failed Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- content/en/docs/v3.6/tasks/operator/how-to-migrate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md index 51fdd5385..506f82c64 100644 --- a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md +++ b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md @@ -7,7 +7,7 @@ weight: 1200 `migrate` to transform etcd v2 data model to v3 data model. {{% alert color="warning" %}} - **Deprecated functionality:** +**Deprecated functionality:** The `etcdctl migrate` command was removed in etcd v3.5.0 ([pull/12971](https://github.com/etcd-io/etcd/pull/12971)). If your etcd cluster is already running v3.5 or higher, you can no longer migrate v2 data to v3 using this method. From 92050f3b1eff1f567830a577cc4104e479112805 Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Tue, 22 Jul 2025 23:18:04 +0000 Subject: [PATCH 08/13] etcd-website: add emoji warning Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- content/en/docs/v3.6/tasks/operator/how-to-migrate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md index 506f82c64..8faf439c8 100644 --- a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md +++ b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md @@ -7,7 +7,7 @@ weight: 1200 `migrate` to transform etcd v2 data model to v3 data model. {{% alert color="warning" %}} -**Deprecated functionality:** +⚠️ **Deprecated functionality:** The `etcdctl migrate` command was removed in etcd v3.5.0 ([pull/12971](https://github.com/etcd-io/etcd/pull/12971)). If your etcd cluster is already running v3.5 or higher, you can no longer migrate v2 data to v3 using this method. From cbab8dea4acdbaef7aa98f920023c3c9f99c1f50 Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Sat, 9 Aug 2025 13:54:44 +0000 Subject: [PATCH 09/13] etcd-website fix: moving how to migrate to v3.4 Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- content/en/docs/v3.4/how-to-migrate.md | 30 +++++++++++++++++++ .../v3.6/tasks/operator/how-to-migrate.md | 2 +- 2 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 content/en/docs/v3.4/how-to-migrate.md diff --git a/content/en/docs/v3.4/how-to-migrate.md b/content/en/docs/v3.4/how-to-migrate.md new file mode 100644 index 000000000..0773ee86f --- /dev/null +++ b/content/en/docs/v3.4/how-to-migrate.md @@ -0,0 +1,30 @@ +--- +title: How to migrate etcd from v2 to v3 +description: etcd v2 to v3 migration guide +weight: 1200 +--- + +`migrate` to transform etcd v2 to v3 data format: + +![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) + + +```shell +# write key in etcd version 2 store +export ETCDCTL_API=2 +etcdctl --endpoints=http://$ENDPOINT set foo bar + +# read key in etcd v2 +etcdctl --endpoints=$ENDPOINTS --output="json" get foo + +# stop etcd node to migrate, one by one + +# migrate v2 data +export ETCDCTL_API=3 +etcdctl --endpoints=$ENDPOINT migrate --data-dir="default.etcd" --wal-dir="default.etcd/member/wal" + +# restart etcd node after migrate, one by one + +# confirm that the key got migrated +etcdctl --endpoints=$ENDPOINTS get /foo +``` diff --git a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md index 8faf439c8..6f8c4119e 100644 --- a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md +++ b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md @@ -4,7 +4,7 @@ description: etcd v2 to v3 migration guide weight: 1200 --- -`migrate` to transform etcd v2 data model to v3 data model. +`migrate` to transform etcd v2 data model to v3 data format. {{% alert color="warning" %}} ⚠️ **Deprecated functionality:** From 08ccc458bf7b8399fb99a1dc838c384351710ac9 Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Wed, 13 Aug 2025 21:51:06 +0000 Subject: [PATCH 10/13] etcd-website: fix: Remove how to migrate in v3.5, 3.6, 3.7 and update docs for v3.4 Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- content/en/docs/v3.4/how-to-migrate.md | 69 +++++++++++-- .../en/docs/v3.5/tutorials/how-to-migrate.md | 30 ------ .../v3.6/tasks/operator/how-to-migrate.md | 97 ------------------- .../v3.7/tasks/operator/how-to-migrate.md | 30 ------ 4 files changed, 60 insertions(+), 166 deletions(-) delete mode 100644 content/en/docs/v3.5/tutorials/how-to-migrate.md delete mode 100644 content/en/docs/v3.6/tasks/operator/how-to-migrate.md delete mode 100644 content/en/docs/v3.7/tasks/operator/how-to-migrate.md diff --git a/content/en/docs/v3.4/how-to-migrate.md b/content/en/docs/v3.4/how-to-migrate.md index 0773ee86f..1098c722f 100644 --- a/content/en/docs/v3.4/how-to-migrate.md +++ b/content/en/docs/v3.4/how-to-migrate.md @@ -4,27 +4,78 @@ description: etcd v2 to v3 migration guide weight: 1200 --- -`migrate` to transform etcd v2 to v3 data format: +`migrate` to transform etcd v2 data model to v3 data format. ![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) +{{% alert color="warning" %}} +⚠️ **Deprecated functionality:** +The `etcdctl migrate` command was removed in etcd v3.5.0 ([pull/12971](https://github.com/etcd-io/etcd/pull/12971)). If your etcd cluster is already running v3.5 or higher, you can no longer migrate v2 data to v3 using this method. -```shell -# write key in etcd version 2 store +You **must use etcdctl v3.4 or earlier** to perform the migration ([CHANGELOG-3.5](https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.5.md#etcdctl-v3-3)). However please take appropriate precautions when using it, as it is no longer officially supported or tested in recent releases. +{{% /alert %}} + +## Pre-requisites + +Before migrating from etcd v2 to v3, ensure the following: + +- A currently running etcd v2 cluster. +- The `etcdctl` CLI tool version <= v3.4. +- Access to each etcd node and their data directories. +- A working backup of your etcd data before performing the migration. + +## Migrate a cluster + +The following steps show how to migrate your etcd data from v2 to v3 using `etcdctl migrate`. + +### Variables and Flags Used + +- `--endpoints`: Specifies the etcd cluster endpoint(s). +- `--output`: Output format (e.g., `"json"`). +- `--data-dir`: Path to the data directory (default: `default.etcd`). View more at [etcd flags](https://etcd.io/docs/v3.6/op-guide/configuration/#member). +- `--wal-dir`: The write-ahead log directory inside `data-dir` (default: `default.etcd/member/wal`). View more at [etcd flags](https://etcd.io/docs/v3.6/op-guide/configuration/#member). +- `set`: Command to set a key-value pair in etcd v2 (View [READMEv2](https://github.com/etcd-io/etcd/blob/main/etcdctl/READMEv2.md#setting-key-values) for more details. In etcd v3, the equivalent command is `put` instead of `set`, see the [READMEv3](https://github.com/etcd-io/etcd/tree/main/etcdctl#key-value-commands)) for reference. +- `get`: Command to retrieve a key-value pair (View [Read keys](https://etcd.io/docs/v3.6/dev-guide/interacting_v3/#read-keys)). + +### Migration Process + +- Step 1: Set up test key using v2 API + +```sh export ETCDCTL_API=2 etcdctl --endpoints=http://$ENDPOINT set foo bar +etcdctl --endpoints=http://$ENDPOINT --output="json" get foo +``` + +- Step 2: Stop each etcd node (one at a time) + +Before running the migration, stop your etcd node to ensure data consistency. -# read key in etcd v2 -etcdctl --endpoints=$ENDPOINTS --output="json" get foo +- Step 3: Run the migration tool -# stop etcd node to migrate, one by one +Switch to API v3 and use etcdctl migrate to transform the v2 store. -# migrate v2 data +```sh export ETCDCTL_API=3 -etcdctl --endpoints=$ENDPOINT migrate --data-dir="default.etcd" --wal-dir="default.etcd/member/wal" +etcdctl --endpoints=http://$ENDPOINT migrate \ + --data-dir="default.etcd" \ + --wal-dir="default.etcd/member/wal" +``` + +- Step 4: Restart etcd node after migrate +Repeat steps 2–4 for each etcd node one at a time in your cluster. -# restart etcd node after migrate, one by one +- Step 5: Confirm the data is accessible via v3 API +```sh +etcdctl --endpoints=$ENDPOINTS get /foo +``` + +Summary full process: + +```shell +# write key in etcd version 2 store +@@ -28,3 +91,7 @@ etcdctl --endpoints=$ENDPOINT migrate --data-dir="default.etcd" --wal-dir="defau # confirm that the key got migrated etcdctl --endpoints=$ENDPOINTS get /foo ``` diff --git a/content/en/docs/v3.5/tutorials/how-to-migrate.md b/content/en/docs/v3.5/tutorials/how-to-migrate.md deleted file mode 100644 index 80bd29acf..000000000 --- a/content/en/docs/v3.5/tutorials/how-to-migrate.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: How to migrate etcd from v2 to v3 -description: etcd v2 to v3 migration guide -weight: 1200 ---- - -`migrate` to transform etcd v2 to v3 data: - -![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) - - -```shell -# write key in etcd version 2 store -export ETCDCTL_API=2 -etcdctl --endpoints=http://$ENDPOINT set foo bar - -# read key in etcd v2 -etcdctl --endpoints=$ENDPOINTS --output="json" get foo - -# stop etcd node to migrate, one by one - -# migrate v2 data -export ETCDCTL_API=3 -etcdctl --endpoints=$ENDPOINT migrate --data-dir="default.etcd" --wal-dir="default.etcd/member/wal" - -# restart etcd node after migrate, one by one - -# confirm that the key got migrated -etcdctl --endpoints=$ENDPOINTS get /foo -``` diff --git a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md b/content/en/docs/v3.6/tasks/operator/how-to-migrate.md deleted file mode 100644 index 6f8c4119e..000000000 --- a/content/en/docs/v3.6/tasks/operator/how-to-migrate.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: How to migrate etcd from v2 to v3 -description: etcd v2 to v3 migration guide -weight: 1200 ---- - -`migrate` to transform etcd v2 data model to v3 data format. - -{{% alert color="warning" %}} -⚠️ **Deprecated functionality:** - -The `etcdctl migrate` command was removed in etcd v3.5.0 ([pull/12971](https://github.com/etcd-io/etcd/pull/12971)). If your etcd cluster is already running v3.5 or higher, you can no longer migrate v2 data to v3 using this method. - -You **must use etcdctl v3.4 or earlier** to perform the migration ([CHANGELOG-3.5](https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.5.md#etcdctl-v3-3)). However please take appropriate precautions when using it, as it is no longer officially supported or tested in recent releases. -{{% /alert %}} - -## Pre-requisites - -Before migrating from etcd v2 to v3, ensure the following: - -- A currently running etcd v2 cluster. -- The `etcdctl` CLI tool version <= v3.4. -- Access to each etcd node and their data directories. -- A working backup of your etcd data before performing the migration. - -## Migrate a cluster - -The following steps show how to migrate your etcd data from v2 to v3 using `etcdctl migrate`. - -### Variables and Flags Used - -- `--endpoints`: Specifies the etcd cluster endpoint(s). -- `--output`: Output format (e.g., `"json"`). -- `--data-dir`: Path to the data directory (default: `default.etcd`). View more at [etcd flags](https://etcd.io/docs/v3.6/op-guide/configuration/#member). -- `--wal-dir`: The write-ahead log directory inside `data-dir` (default: `default.etcd/member/wal`). View more at [etcd flags](https://etcd.io/docs/v3.6/op-guide/configuration/#member). -- `set`: Command to set a key-value pair in etcd v2 (View [READMEv2](https://github.com/etcd-io/etcd/blob/main/etcdctl/READMEv2.md#setting-key-values) for more details. In etcd v3, the equivalent command is `put` instead of `set`, see the [READMEv3](https://github.com/etcd-io/etcd/tree/main/etcdctl#key-value-commands)) for reference. -- `get`: Command to retrieve a key-value pair (View [Read keys](https://etcd.io/docs/v3.6/dev-guide/interacting_v3/#read-keys)). - -### Migration Process - -- Step 1: Set up test key using v2 API - -```sh -export ETCDCTL_API=2 -etcdctl --endpoints=http://$ENDPOINT set foo bar -etcdctl --endpoints=http://$ENDPOINT --output="json" get foo -``` - -- Step 2: Stop each etcd node (one at a time) - -Before running the migration, stop your etcd node to ensure data consistency. - -- Step 3: Run the migration tool - -Switch to API v3 and use etcdctl migrate to transform the v2 store. - -```sh -export ETCDCTL_API=3 -etcdctl --endpoints=http://$ENDPOINT migrate \ - --data-dir="default.etcd" \ - --wal-dir="default.etcd/member/wal" -``` - -- Step 4: Restart etcd node after migrate -Repeat steps 2–4 for each etcd node one at a time in your cluster. - -- Step 5: Confirm the data is accessible via v3 API - -```sh -etcdctl --endpoints=$ENDPOINTS get /foo -``` - -Summary full process: - -```shell -# write key in etcd version 2 store -export ETCDCTL_API=2 -etcdctl --endpoints=http://$ENDPOINT set foo bar - -# read key in etcd v2 -etcdctl --endpoints=$ENDPOINTS --output="json" get foo - -# stop etcd node to migrate, one by one - -# migrate v2 data -export ETCDCTL_API=3 -etcdctl --endpoints=$ENDPOINT migrate --data-dir="default.etcd" --wal-dir="default.etcd/member/wal" - -# restart etcd node after migrate, one by one - -# confirm that the key got migrated -etcdctl --endpoints=$ENDPOINTS get /foo -``` - -## Visual guide for reference - -![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) diff --git a/content/en/docs/v3.7/tasks/operator/how-to-migrate.md b/content/en/docs/v3.7/tasks/operator/how-to-migrate.md deleted file mode 100644 index 80bd29acf..000000000 --- a/content/en/docs/v3.7/tasks/operator/how-to-migrate.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: How to migrate etcd from v2 to v3 -description: etcd v2 to v3 migration guide -weight: 1200 ---- - -`migrate` to transform etcd v2 to v3 data: - -![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) - - -```shell -# write key in etcd version 2 store -export ETCDCTL_API=2 -etcdctl --endpoints=http://$ENDPOINT set foo bar - -# read key in etcd v2 -etcdctl --endpoints=$ENDPOINTS --output="json" get foo - -# stop etcd node to migrate, one by one - -# migrate v2 data -export ETCDCTL_API=3 -etcdctl --endpoints=$ENDPOINT migrate --data-dir="default.etcd" --wal-dir="default.etcd/member/wal" - -# restart etcd node after migrate, one by one - -# confirm that the key got migrated -etcdctl --endpoints=$ENDPOINTS get /foo -``` From fcd421bf35065591a1ad1cebd12ab770fa9e3bfb Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Wed, 13 Aug 2025 22:12:13 +0000 Subject: [PATCH 11/13] etcd-website: fix: Update more details for the process and bring GIF reference back Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- content/en/docs/v3.4/how-to-migrate.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/content/en/docs/v3.4/how-to-migrate.md b/content/en/docs/v3.4/how-to-migrate.md index 1098c722f..5b6e65528 100644 --- a/content/en/docs/v3.4/how-to-migrate.md +++ b/content/en/docs/v3.4/how-to-migrate.md @@ -6,13 +6,12 @@ weight: 1200 `migrate` to transform etcd v2 data model to v3 data format. -![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) {{% alert color="warning" %}} ⚠️ **Deprecated functionality:** The `etcdctl migrate` command was removed in etcd v3.5.0 ([pull/12971](https://github.com/etcd-io/etcd/pull/12971)). If your etcd cluster is already running v3.5 or higher, you can no longer migrate v2 data to v3 using this method. -You **must use etcdctl v3.4 or earlier** to perform the migration ([CHANGELOG-3.5](https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.5.md#etcdctl-v3-3)). However please take appropriate precautions when using it, as it is no longer officially supported or tested in recent releases. +You **must use etcdctl v3.4 or earlier** to perform the migration (View note from [CHANGELOG-3.5](https://github.com/ahrtr/etcd/blob/main/CHANGELOG/CHANGELOG-3.5.md#etcdctl-v3-3)). However please take appropriate precautions when using it, as it is no longer officially supported or tested in recent releases. {{% /alert %}} ## Pre-requisites @@ -53,7 +52,7 @@ Before running the migration, stop your etcd node to ensure data consistency. - Step 3: Run the migration tool -Switch to API v3 and use etcdctl migrate to transform the v2 store. +Switch to API v3 and use `etcdctl migrate` command to transform the v2 store. Please review the deprecation alert on top of the page, you must use etcdctl v3.4 or earlier to be able to perform this command. ```sh export ETCDCTL_API=3 @@ -63,6 +62,7 @@ etcdctl --endpoints=http://$ENDPOINT migrate \ ``` - Step 4: Restart etcd node after migrate + Repeat steps 2–4 for each etcd node one at a time in your cluster. - Step 5: Confirm the data is accessible via v3 API @@ -75,7 +75,24 @@ Summary full process: ```shell # write key in etcd version 2 store -@@ -28,3 +91,7 @@ etcdctl --endpoints=$ENDPOINT migrate --data-dir="default.etcd" --wal-dir="defau +export ETCDCTL_API=2 +etcdctl --endpoints=http://$ENDPOINT set foo bar + +# read key in etcd v2 +etcdctl --endpoints=$ENDPOINTS --output="json" get foo + +# stop etcd node to migrate, one by one + +# migrate v2 data +export ETCDCTL_API=3 +etcdctl --endpoints=$ENDPOINT migrate --data-dir="default.etcd" --wal-dir="default.etcd/member/wal" + +# restart etcd node after migrate, one by one + # confirm that the key got migrated etcdctl --endpoints=$ENDPOINTS get /foo ``` + +## Visual guide for reference + +![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) \ No newline at end of file From 1fedbf521ea0ecdcfaa89dd0491629c1812e09a1 Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Wed, 13 Aug 2025 22:21:06 +0000 Subject: [PATCH 12/13] etcd-website: fix: minor fix wording Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- content/en/docs/v3.4/how-to-migrate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/v3.4/how-to-migrate.md b/content/en/docs/v3.4/how-to-migrate.md index 5b6e65528..eb61e616c 100644 --- a/content/en/docs/v3.4/how-to-migrate.md +++ b/content/en/docs/v3.4/how-to-migrate.md @@ -4,7 +4,7 @@ description: etcd v2 to v3 migration guide weight: 1200 --- -`migrate` to transform etcd v2 data model to v3 data format. +`migrate` to transform etcd v2 to v3 data. {{% alert color="warning" %}} ⚠️ **Deprecated functionality:** From 9c0e06667761a04b915894953238a0aa97b9114a Mon Sep 17 00:00:00 2001 From: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> Date: Wed, 13 Aug 2025 22:32:59 +0000 Subject: [PATCH 13/13] etcd-webiste: fix: fix lint failed Signed-off-by: Wendy Ha <139814343+wendy-ha18@users.noreply.github.com> --- content/en/docs/v3.4/how-to-migrate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/v3.4/how-to-migrate.md b/content/en/docs/v3.4/how-to-migrate.md index eb61e616c..a41cd2fa8 100644 --- a/content/en/docs/v3.4/how-to-migrate.md +++ b/content/en/docs/v3.4/how-to-migrate.md @@ -95,4 +95,4 @@ etcdctl --endpoints=$ENDPOINTS get /foo ## Visual guide for reference -![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif) \ No newline at end of file +![12_etcdctl_migrate_2016061602](https://storage.googleapis.com/etcd/demo/12_etcdctl_migrate_2016061602.gif)