website icon indicating copy to clipboard operation
website copied to clipboard

Enhance the v3.5 -> v3.6 upgrade doc to clarify the workaround for cleaning up legacy v2store

Open ahrtr opened this issue 4 weeks ago • 4 comments

We need to enhance the doc https://etcd.io/docs/v3.6/upgrades/upgrade_3_6/ to clarify how to cleanup legacy data in v2store before upgrading to v3.6.

If --enable-v2 is configured in v3.5.x, then users should remove it before upgrading to v3.6. But removing the flag isn't sufficient, they should also ensure there is no v2 data in v2store starting from the latest v2 snapshot.

The high level process should be something like below,

if  flag `--enable-v2` or env `ETCD_ENABLE_V2="true"` is configured {
    if there is some data in v2store which needs to be migrated to v3store {
        follow guide https://etcd.io/docs/v3.4/op-guide/v2-migration/ to migrate the data
    }

    remove flag `--enable-v2` and env `ETCD_ENABLE_V2="true"`

    run `etcdutl check v2store` to verify whether the v2store contains any non-membership (custom) data (use etcdutl version >= 3.5.22)
    if yes {
           apply workaround below to get rid of the legacy data in v2store {
               add flag `--snapshot-count=1` to etcd for each etcd instance which has custom data in v2store
               restart the etcd instances

               remove the flag `--snapshot-count=1` from all the etcd instances (or restore to the original values if any)
               restart the etcd instances
           }
    }
    run `etcdutl check v2store` again to verify whether the v2store contains any non-membership (custom) data
    THERE SHOULD BE NO ANY CUSTOM DATA IN V2STRORE!
}

NOW IT'S SAFE TO UPGRADE TO V3.6.

ahrtr avatar Oct 30 '25 10:10 ahrtr