diff --git a/Documentation/op-guide/v2-migration.md b/Documentation/op-guide/v2-migration.md index c03a41a3f68a..be6a4e1b6a6f 100644 --- a/Documentation/op-guide/v2-migration.md +++ b/Documentation/op-guide/v2-migration.md @@ -6,7 +6,7 @@ Migrating an application from the API v2 to the API v3 involves two steps: 1) mi ## Migrate client library -API v3 is different from API v2, thus application developers need to use a new client library to send requests to etcd API v3. The documentation of the client v3 is available at https://godoc.org/github.com/coreos/etcd/clientv3. +API v3 is different from API v2, thus application developers need to use a new client library to send requests to etcd API v3. The documentation of the client v3 is available at https://godoc.org/github.com/coreos/etcd/clientv3. There are some notable differences between API v2 and API v3: @@ -28,6 +28,12 @@ Sometimes an etcd cluster will possibly have v3 data which should not be overwri ETCDCTL_API=3 etcdctl get "" --from-key --keys-only --limit 1 | wc -l ``` +In case v2 data was migrated with TTLs, ensure that stores are consistent by checking the hashes: + +```sh +ETCDCTL_API=3 etcdctl endpoint hash --cluster +``` + ### Offline migration Offline migration is very simple but requires etcd downtime. If an etcd downtime window spanning from seconds to minutes is acceptable, offline migration is a good choice and is easy to automate. @@ -44,7 +50,7 @@ If the application cannot tolerate any downtime, then it must migrate online. Th First, write application code using the v3 API. The application must support two modes: a migration mode and a normal mode. The application starts in migration mode. When running in migration mode, the application reads keys using the v3 API first, and, if it cannot find the key, it retries with the API v2. In normal mode, the application only reads keys using the v3 API. The application writes keys over the API v3 in both modes. To acknowledge a switch from migration mode to normal mode, the application watches on a switch mode key. When switch key’s value turns to `true`, the application switches over from migration mode to normal mode. -Second, start a background job to migrate data from the store v2 to the mvcc store by reading keys from the API v2 and writing keys to the API v3. +Second, start a background job to migrate data from the store v2 to the mvcc store by reading keys from the API v2 and writing keys to the API v3. After finishing data migration, the background job writes `true` into the switch mode key to notify the application that it may switch modes.