Skip to content

Commit

Permalink
op-guide/v2-migration: endpoint hash post migration
Browse files Browse the repository at this point in the history
Signed-off-by: Gyu-Ho Lee <gyuhox@gmail.com>
  • Loading branch information
gyuho committed Aug 3, 2017
1 parent 146ef3e commit 518a6f7
Showing 1 changed file with 8 additions and 2 deletions.
10 changes: 8 additions & 2 deletions Documentation/op-guide/v2-migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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.
Expand All @@ -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.

Expand Down

0 comments on commit 518a6f7

Please sign in to comment.