Mirroristas/etcd
2
0
Fork 0
mirror of https://github.com/etcd-io/etcd.git synced 2024-09-27 06:25:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation/upgrades: update guides with latest logger change

Browse Source 
Signed-off-by: Gyuho Lee <gyuhox@gmail.com>
This commit is contained in:
Gyuho Lee 2018-04-26 11:34:28 -07:00
parent dca3f5e3ad
commit fd227254ef
4 changed files with 103 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
Documentation/upgrades/upgrade_3_2.md
View File

@ -12,17 +12,17 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
Highlighted breaking changes in 3.2.
#### Change in default `snapshot-count` value
#### Changed default `snapshot-count` value
Higher `--snapshot-count` holds more Raft entries in memory until snapshot, thus causing [recurrent higher memory usage](https://github.com/kubernetes/kubernetes/issues/60589#issuecomment-371977156). Since leader retains latest Raft entries for longer, a slow follower has more time to catch up before leader snapshot. `--snapshot-count` is a tradeoff between higher memory usage and better availabilities of slow followers.
Since v3.2, the default value of `--snapshot-count` has [changed from from 10,000 to 100,000](https://github.com/coreos/etcd/pull/7160).
#### Change in gRPC dependency (>=3.2.10)
#### Changed gRPC dependency (>=3.2.10)
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`).
##### Deprecate `grpclog.Logger`
##### Deprecated `grpclog.Logger`
`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`.
@ -43,7 +43,7 @@ clientv3.SetLogger(grpclog.NewLoggerV2(os.Stderr, os.Stderr, os.Stderr))
// log.New above cannot be used (not implement grpclog.LoggerV2 interface)
```
##### Deprecate `grpc.ErrClientConnTimeout`
##### Deprecated `grpc.ErrClientConnTimeout`
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)).
@ -72,7 +72,7 @@ if err == context.DeadlineExceeded {
}
```
#### Change in maximum request size limits (>=3.2.10)
#### Changed maximum request size limits (>=3.2.10)
3.2.10 and 3.2.11 allow custom request size limits in server side. >=3.2.12 allows custom request size limits for both server and **client side**. In previous versions(v3.2.10, v3.2.11), client response size was limited to only 4 MiB.
@ -145,7 +145,7 @@ err.Error() == "rpc error: code = ResourceExhausted desc = grpc: received messag
**If not specified, client-side send limit defaults to 2 MiB (1.5 MiB + gRPC overhead bytes) and receive limit to `math.MaxInt32`**. Please see [clientv3 godoc](https://godoc.org/github.com/coreos/etcd/clientv3#Config) for more detail.
#### Change in raw gRPC client wrappers
#### Changed raw gRPC client wrappers
3.2.12 or later changes the function signatures of `clientv3` gRPC client wrapper. This change was needed to support [custom `grpc.CallOption` on message size limits](https://github.com/coreos/etcd/pull/9047).
@ -168,7 +168,7 @@ Before and after
+func NewWatchFromWatchClient(wc pb.WatchClient, c *Client) Watcher {
```
#### Change in `clientv3.Lease.TimeToLive` API
#### Changed `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)).
@ -190,7 +190,7 @@ resp.TTL == -1
err == nil
```
#### Change in `clientv3.NewFromConfigFile`
#### Moved `clientv3.NewFromConfigFile` to `clientv3.yaml.NewConfig`
`clientv3.NewFromConfigFile` is moved to `yaml.NewConfig`.

32
Documentation/upgrades/upgrade_3_3.md
View File

@ -12,7 +12,7 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
Highlighted breaking changes in 3.3.
#### Change in `--auto-compaction-retention` flag
#### Changed value type of `etcd --auto-compaction-retention` flag to `string`
Changed `--auto-compaction-retention` flag to [accept string values](https://github.com/coreos/etcd/pull/8563) with [finer granularity](https://github.com/coreos/etcd/issues/8503). Now that `--auto-compaction-retention` accepts string values, etcd configuration YAML file `auto-compaction-retention` field must be changed to `string` type. Previously, `--config-file etcd.config.yaml` can have `auto-compaction-retention: 24` field, now must be `auto-compaction-retention: "24"` or `auto-compaction-retention: "24h"`. If configured as `--auto-compaction-mode periodic --auto-compaction-retention "24h"`, the time duration value for `--auto-compaction-retention` flag must be valid for [`time.ParseDuration`](https://golang.org/pkg/time/#ParseDuration) function in Go.
@ -25,7 +25,7 @@ Changed `--auto-compaction-retention` flag to [accept string values](https://git
+# auto-compaction-retention: "24h"
```
#### Change in `etcdserver.EtcdServer` struct
#### Changed `etcdserver.EtcdServer.ServerConfig` to `*etcdserver.EtcdServer.ServerConfig`
`etcdserver.EtcdServer` has changed the type of its member field `*etcdserver.ServerConfig` to `etcdserver.ServerConfig`. And `etcdserver.NewServer` now takes `etcdserver.ServerConfig`, instead of `*etcdserver.ServerConfig`.
@ -55,7 +55,9 @@ func (e *EtcdServer) Start() error {
...
```
#### Change in `embed.EtcdServer` struct
#### Added `embed.Config.LogOutput` struct
**Note that this field has been renamed to `embed.Config.LogOutputs` in `[]string` type in v3.4. Please see [v3.4 upgrade guide](https://github.com/coreos/etcd/blob/master/Documentation/upgrades/upgrade_3_4.md) for more details.**
Field `LogOutput` is added to `embed.Config`:
@ -78,6 +80,8 @@ WARNING: 2017/11/02 11:35:51 grpc: addrConn.resetTransport failed to create clie
From v3.3, gRPC server logs are disabled by default.
**Note that `embed.Config.SetupLogging` method has been deprecated in v3.4. Please see [v3.4 upgrade guide](https://github.com/coreos/etcd/blob/master/Documentation/upgrades/upgrade_3_4.md) for more details.**
```go
import "github.com/coreos/etcd/embed"
@ -87,7 +91,7 @@ cfg.SetupLogging()
Set `embed.Config.Debug` field to `true` to enable gRPC server logs.
#### Change in `/health` endpoint response
#### Changed `/health` endpoint response
Previously, `[endpoint]:[client-port]/health` returned manually marshaled JSON value. 3.3 now defines [`etcdhttp.Health`](https://godoc.org/github.com/coreos/etcd/etcdserver/api/etcdhttp#Health) struct.
@ -98,7 +102,7 @@ $ curl http://localhost:2379/health
{"health":"true"}
```
#### Change in gRPC gateway HTTP endpoints (replaced `/v3alpha` with `/v3beta`)
#### Changed gRPC gateway HTTP endpoints (replaced `/v3alpha` with `/v3beta`)
Before
@ -116,7 +120,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.
#### Change in maximum request size limits
#### Changed maximum request size limits
3.3 now allows custom request size limits for both server and **client side**. In previous versions(v3.2.10, v3.2.11), client response size was limited to only 4 MiB.
@ -189,7 +193,7 @@ err.Error() == "rpc error: code = ResourceExhausted desc = grpc: received messag
**If not specified, client-side send limit defaults to 2 MiB (1.5 MiB + gRPC overhead bytes) and receive limit to `math.MaxInt32`**. Please see [clientv3 godoc](https://godoc.org/github.com/coreos/etcd/clientv3#Config) for more detail.
#### Change in raw gRPC client wrappers
#### Changed raw gRPC client wrapper function signatures
3.3 changes the function signatures of `clientv3` gRPC client wrapper. This change was needed to support [custom `grpc.CallOption` on message size limits](https://github.com/coreos/etcd/pull/9047).
@ -212,7 +216,7 @@ Before and after
+func NewWatchFromWatchClient(wc pb.WatchClient, c *Client) Watcher {
```
#### Change in clientv3 `Snapshot` API error type
#### Changed 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.
@ -258,7 +262,7 @@ _, err = io.Copy(f, rc)
err == context.DeadlineExceeded
```
#### Change in `etcdctl lease timetolive` command output
#### Changed `etcdctl lease timetolive` command output
Previously, `lease timetolive LEASE_ID` command on expired lease prints `-1s` for remaining seconds. 3.3 now outputs clearer messages.
@ -275,7 +279,7 @@ After
lease 2d8257079fa1bc0c already expired
```
#### Change in `golang.org/x/net/context` imports
#### Changed `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.
@ -293,11 +297,11 @@ import "context"
cli.Put(context.Background(), "f", "v")
```
#### Change in gRPC dependency
#### Changed gRPC dependency
3.3 now requires [grpc/grpc-go](https://github.com/grpc/grpc-go/releases) `v1.7.5`.
##### Deprecate `grpclog.Logger`
##### Deprecated `grpclog.Logger`
`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`.
@ -318,7 +322,7 @@ clientv3.SetLogger(grpclog.NewLoggerV2(os.Stderr, os.Stderr, os.Stderr))
// log.New above cannot be used (not implement grpclog.LoggerV2 interface)
```
##### Deprecate `grpc.ErrClientConnTimeout`
##### Deprecated `grpc.ErrClientConnTimeout`
Previously, `grpc.ErrClientConnTimeout` error is returned on client dial time-outs. 3.3 instead returns `context.DeadlineExceeded` (see [#8504](https://github.com/coreos/etcd/issues/8504)).
@ -347,7 +351,7 @@ if err == context.DeadlineExceeded {
}
```
#### Change in official container registry
#### Changed 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.

77
Documentation/upgrades/upgrade_3_4.md
View File

@ -12,7 +12,7 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
Highlighted breaking changes in 3.4.
#### Change in `etcd` flags
#### Deprecated `etcd --ca-file` and `etcd --peer-ca-file` flags
`--ca-file` and `--peer-ca-file` flags are deprecated; they have been deprecated since v2.1.
@ -26,16 +26,42 @@ Highlighted breaking changes in 3.4.
+etcd --peer-trusted-ca-file ca-peer.crt
```
Rename [`etcd --log-output` to `--log-outputs`](https://github.com/coreos/etcd/pull/9624) to support multiple log outputs.
#### Deprecating `etcd --log-output` flag (now `--log-outputs`)
**`etcd --log-output`** will be deprecated in v3.5.
Rename [`etcd --log-output` to `--log-outputs`](https://github.com/coreos/etcd/pull/9624) to support multiple log outputs. **`etcd --logger=capnslog` does not support multiple log outputs.**
**`etcd --log-output`** will be deprecated in v3.5. **`etcd --logger=capnslog` will be deprecated in v3.5**.
```diff
-etcd --log-output stderr
+etcd --log-outputs stderr,a.log
```
#### Change in `pkg/transport`
v3.4 adds `etcd --logger zap` support for structured logging and multiple log outputs. Main motivation is to promote automated etcd monitoring, rather than looking back server logs when it starts breaking. Future development will make etcd log as few as possible, and make etcd easier to monitor with metrics and alerts. **`etcd --logger=capnslog` will be deprecated in v3.5**.
#### Changed `log-outputs` field type in `etcd --config-file` to `[]string`
Now that `log-outputs` (old field name `log-output`) accepts multiple writers, etcd configuration YAML file `log-outputs` field must be changed to `[]string` type as below:
```diff
# Specify 'stdout' or 'stderr' to skip journald logging even when running under systemd.
-log-output: default
+log-outputs: [default]
```
#### Renamed `embed.Config.LogOutput` to `embed.Config.LogOutputs`
Renamed [**`embed.Config.LogOutput`** to **`embed.Config.LogOutputs`**](https://github.com/coreos/etcd/pull/9624) to support multiple log outputs. And changed [`embed.Config.LogOutput` type from `string` to `[]string`](https://github.com/coreos/etcd/pull/9579) to support multiple log outputs.
```diff
import "github.com/coreos/etcd/embed"
cfg := &embed.Config{Debug: false}
-cfg.LogOutput = "stderr"
+cfg.LogOutputs = []string{"stderr"}
```
#### Deprecated `pkg/transport.TLSInfo.CAFile` field
Deprecated `pkg/transport.TLSInfo.CAFile` field.
@ -54,7 +80,7 @@ if err != nil {
}
```
#### Change in `wal`
#### Changed function signature in package `wal`
Changed `wal` function signatures to support structured logger.
@ -77,7 +103,7 @@ import "github.com/coreos/etcd/wal"
+wal.Create(lg, dirpath, metadata)
```
#### Change in `embed.Etcd`
#### Deprecated `embed.Config.SetupLogging`
`embed.Config.SetupLogging` has been removed in order to prevent wrong logging configuration, and now set up automatically.
@ -88,42 +114,23 @@ cfg := &embed.Config{Debug: false}
-cfg.SetupLogging()
```
Renamed [**`embed.Config.LogOutput`** to **`embed.Config.LogOutputs`**](https://github.com/coreos/etcd/pull/9624) to support multiple log outputs. And changed [`embed.Config.LogOutput` type from `string` to `[]string`](https://github.com/coreos/etcd/pull/9579) to support multiple log outputs.
#### Changed gRPC gateway HTTP endpoints (replaced `/v3beta` with `/v3`)
```diff
import "github.com/coreos/etcd/embed"
Before
cfg := &embed.Config{Debug: false}
-cfg.LogOutput = "stderr"
+cfg.LogOutputs = []string{"stderr"}
```bash
curl -L http://localhost:2379/v3beta/kv/put \
-X POST -d '{"key": "Zm9v", "value": "YmFy"}'
```
#### Change in `etcd --log-output` (now `--log-outputs`)
After
Rename [`etcd --log-output` to `--log-outputs`](https://github.com/coreos/etcd/pull/9624) to support multiple log outputs.
**`etcd --log-output`** will be deprecated in v3.5.
```diff
-etcd --log-output stderr
+etcd --log-outputs stderr,a.log
```bash
curl -L http://localhost:2379/v3/kv/put \
-X POST -d '{"key": "Zm9v", "value": "YmFy"}'
```
```diff
# Specify 'stdout' or 'stderr' to skip journald logging even when running under systemd.
-log-output: [default]
+log-outputs: [default]
```
#### Change in `etcd --config-file`
Now that `log-outputs` (old field name `log-output`) accepts multiple writers, etcd configuration YAML file `log-outputs` field must be changed to `[]string` type as below:
```diff
# Specify 'stdout' or 'stderr' to skip journald logging even when running under systemd.
-log-output: default
+log-outputs: [default]
```
Requests to `/v3beta` endpoints will redirect to `/v3`, and `/v3beta` will be removed in 3.5 release.
### Server upgrade checklists

41
Documentation/upgrades/upgrade_3_5.md
View File

@ -12,17 +12,46 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
Highlighted breaking changes in 3.5.
#### Deprecated in `etcd --log-output`
#### Deprecated in `etcd --logger capnslog`
Rename [`etcd --log-output` to `--log-outputs`](https://github.com/coreos/etcd/pull/9624) to support multiple log outputs.
**`etcd --log-output`** is deprecated in v3.5.
v3.4 adds `--logger=zap` to support multiple log outputs and structured logging. **`etcd --logger=capnslog` has been deprecated in v3.5**, and now `--logger=zap` is the default.
```diff
-$ etcd --log-output stderr
+$ etcd --log-outputs stderr,a.log
-etcd --logger capnslog
+etcd --logger zap --log-outputs stderr,a.log
```
TODO(add more monitoring guides); v3.4 adds `etcd --logger zap` support for structured logging and multiple log outputs. Main motivation is to promote automated etcd monitoring, rather than looking back server logs when it starts breaking. Future development will make etcd log as few as possible, and make etcd easier to monitor with metrics and alerts. **`etcd --logger=capnslog` will be deprecated in v3.5**.
#### Deprecated in `etcd --log-output`
v3.4 renamed [`etcd --log-output` to `--log-outputs`](https://github.com/coreos/etcd/pull/9624) to support multiple log outputs.
**`etcd --log-output` has been deprecated in v3.5**.
```diff
-etcd --log-output stderr
+etcd --log-outputs stderr,a.log
```
#### Changed gRPC gateway HTTP endpoints (deprecated `/v3beta`)
Before
```bash
curl -L http://localhost:2379/v3beta/kv/put \
-X POST -d '{"key": "Zm9v", "value": "YmFy"}'
```
After
```bash
curl -L http://localhost:2379/v3/kv/put \
-X POST -d '{"key": "Zm9v", "value": "YmFy"}'
```
`/v3beta` has been removed in 3.5 release.
### Server upgrade checklists
#### Upgrade requirements