From 3d924aedc8e63454810493f8baf66ba94d1c024d Mon Sep 17 00:00:00 2001 From: Gyuho Lee Date: Tue, 19 Dec 2017 21:25:52 -0800 Subject: [PATCH] Documentation/upgrades: clean up 3.2, 3.3 guides Make headers consistent. Signed-off-by: Gyuho Lee --- Documentation/upgrades/upgrade_3_2.md | 93 +++++++++++++++++---------- Documentation/upgrades/upgrade_3_3.md | 40 ++++++------ 2 files changed, 80 insertions(+), 53 deletions(-) diff --git a/Documentation/upgrades/upgrade_3_2.md b/Documentation/upgrades/upgrade_3_2.md index f65081478..441a0c482 100644 --- a/Documentation/upgrades/upgrade_3_2.md +++ b/Documentation/upgrades/upgrade_3_2.md @@ -6,57 +6,38 @@ In the general case, upgrading from etcd 3.1 to 3.2 can be a zero-downtime, roll Before [starting an upgrade](#upgrade-procedure), read through the rest of this guide to prepare. -### Server upgrade checklists (breaking change) +### Upgrade checklists -3.2 now rejects domains names for `--listen-peer-urls` and `--listen-client-urls` (3.1 only prints out warnings), since domain name is invalid for network interface binding. Make sure that those URLs are properly formated as `scheme://IP:port`. +Highlighted breaking changes in 3.2. -See [issue #6336](https://github.com/coreos/etcd/issues/6336) for more contexts. +#### Change in gRPC dependency (>=3.2.10) -### Client upgrade checklists (>=3.2.0) +3.2.10 or later now requires [grpc/grpc-go](https://github.com/grpc/grpc-go/releases) `v1.7.5` (<=3.2.9 requires `v1.2.1`). -3.2 introduces two breaking changes. +##### Deprecate `grpclog.Logger` -Previously, `clientv3.Lease.TimeToLive` API returned `lease.ErrLeaseNotFound` on non-existent lease ID. 3.2 instead returns TTL=-1 in its response and no error (see [#7305](https://github.com/coreos/etcd/pull/7305)). - -Before - -```go -// when leaseID does not exist -resp, err := TimeToLive(ctx, leaseID) -resp == nil -err == lease.ErrLeaseNotFound -``` - -After - -```go -// when leaseID does not exist -resp, err := TimeToLive(ctx, leaseID) -resp.TTL == -1 -err == nil -``` - -`clientv3.NewFromConfigFile` is moved to `yaml.NewConfig`. +`grpclog.Logger` has been deprecated in favor of [`grpclog.LoggerV2`](https://github.com/grpc/grpc-go/blob/master/grpclog/loggerv2.go). `clientv3.Logger` is now `grpclog.LoggerV2`. Before ```go import "github.com/coreos/etcd/clientv3" -clientv3.NewFromConfigFile +clientv3.SetLogger(log.New(os.Stderr, "grpc: ", 0)) ``` After ```go -import clientv3yaml "github.com/coreos/etcd/clientv3/yaml" -clientv3yaml.NewConfig +import "github.com/coreos/etcd/clientv3" +import "google.golang.org/grpc/grpclog" +clientv3.SetLogger(grpclog.NewLoggerV2(os.Stderr, os.Stderr, os.Stderr)) + +// log.New above cannot be used (not implement grpclog.LoggerV2 interface) ``` -### Client upgrade checklists (>=3.2.10) +##### Deprecate `grpc.ErrClientConnTimeout` -Note that >=3.2.10 requires `grpc/grpc-go` v1.7.4 (<=3.2.9 with v1.2.1), which introduces some breaking changes. - -Previously, `grpc.ErrClientConnTimeout` error is returned on client dial time-outs. >=3.2.10 instead returns `context.DeadlineExceeded` (see [#8504](https://github.com/coreos/etcd/issues/8504)). +Previously, `grpc.ErrClientConnTimeout` error is returned on client dial time-outs. 3.2 instead returns `context.DeadlineExceeded` (see [#8504](https://github.com/coreos/etcd/issues/8504)). Before @@ -83,6 +64,52 @@ if err == context.DeadlineExceeded { } ``` +#### Change in `--listen-peer-urls` and `--listen-client-urls` + +3.2 now rejects domains names for `--listen-peer-urls` and `--listen-client-urls` (3.1 only prints out warnings), since domain name is invalid for network interface binding. Make sure that those URLs are properly formated as `scheme://IP:port`. + +See [issue #6336](https://github.com/coreos/etcd/issues/6336) for more contexts. + +#### Change in `clientv3.Lease.TimeToLive` API + +Previously, `clientv3.Lease.TimeToLive` API returned `lease.ErrLeaseNotFound` on non-existent lease ID. 3.2 instead returns TTL=-1 in its response and no error (see [#7305](https://github.com/coreos/etcd/pull/7305)). + +Before + +```go +// when leaseID does not exist +resp, err := TimeToLive(ctx, leaseID) +resp == nil +err == lease.ErrLeaseNotFound +``` + +After + +```go +// when leaseID does not exist +resp, err := TimeToLive(ctx, leaseID) +resp.TTL == -1 +err == nil +``` + +#### Change in `clientv3.NewFromConfigFile` + +`clientv3.NewFromConfigFile` is moved to `yaml.NewConfig`. + +Before + +```go +import "github.com/coreos/etcd/clientv3" +clientv3.NewFromConfigFile +``` + +After + +```go +import clientv3yaml "github.com/coreos/etcd/clientv3/yaml" +clientv3yaml.NewConfig +``` + ### Server upgrade checklists #### Upgrade requirements diff --git a/Documentation/upgrades/upgrade_3_3.md b/Documentation/upgrades/upgrade_3_3.md index 77b12b24b..2e724a464 100644 --- a/Documentation/upgrades/upgrade_3_3.md +++ b/Documentation/upgrades/upgrade_3_3.md @@ -111,23 +111,7 @@ curl -L http://localhost:2379/v3beta/kv/put \ Requests to `/v3alpha` endpoints will redirect to `/v3beta`, and `/v3alpha` will be removed in 3.4 release. -#### `gcr.io/etcd-development/etcd` as primary container registry - -etcd uses [`gcr.io/etcd-development/etcd`](https://gcr.io/etcd-development/etcd) as a primary container registry, and [`quay.io/coreos/etcd`](https://quay.io/coreos/etcd) as secondary. - -Before - -```bash -docker pull quay.io/coreos/etcd:v3.2.5 -``` - -After - -```bash -docker pull gcr.io/etcd-development/etcd:v3.3.0 -``` - -#### Change in `Snapshot` API error type +#### Change in clientv3 `Snapshot` API error type Previously, clientv3 `Snapshot` API returned raw [`grpc/*status.statusError`] type error. v3.3 now translates those errors to corresponding public error types, to be consistent with other APIs. @@ -173,7 +157,7 @@ _, err = io.Copy(f, rc) err == context.DeadlineExceeded ``` -#### Deprecate `golang.org/x/net/context` imports +#### Change in `golang.org/x/net/context` imports `clientv3` has deprecated `golang.org/x/net/context`. If a project vendors `golang.org/x/net/context` in other code (e.g. etcd generated protocol buffer code) and imports `github.com/coreos/etcd/clientv3`, it requires Go 1.9+ to compile. @@ -191,9 +175,9 @@ import "context" cli.Put(context.Background(), "f", "v") ``` -#### Upgrade grpc/grpc-go to `v1.7.4` +#### Change in gRPC dependency -3.3 now requires [grpc/grpc-go](https://github.com/grpc/grpc-go/releases) `v1.7.4`. +3.3 now requires [grpc/grpc-go](https://github.com/grpc/grpc-go/releases) `v1.7.5`. ##### Deprecate `grpclog.Logger` @@ -245,6 +229,22 @@ if err == context.DeadlineExceeded { } ``` +#### Change in official container registry + +etcd now uses [`gcr.io/etcd-development/etcd`](https://gcr.io/etcd-development/etcd) as a primary container registry, and [`quay.io/coreos/etcd`](https://quay.io/coreos/etcd) as secondary. + +Before + +```bash +docker pull quay.io/coreos/etcd:v3.2.5 +``` + +After + +```bash +docker pull gcr.io/etcd-development/etcd:v3.3.0 +``` + ### Server upgrade checklists #### Upgrade requirements