RATATOSK
← All releases

etcdv3.7.4

Breaking changes 1Important fixes 2Other changes 6

Get etcd alerts

Email is sent weekly only when there are changes to check; critical security advisories are sent immediately.

Check before upgrading

Upgrade guide1
Upgrade guidance for etcd v3.7.4
16 items from linked documents
  • Zero-downtime etcd v3.6-to-v3.7 upgrade guidance
  • Guide to preparing for an upgrade
  • Updated 3.6 members required for a 3.7 upgradeBefore upgrading, all cluster members must be on 3.6.11 or later; earlier 3.6 patch releases may not be compatible with a rolling upgrade to 3.7.
  • v2 data migration guide for older releases
  • CHANGELOG covering upgrades for etcd embedders, clientv3 users, and internal-package dependents
  • v3.5-to-v3.6 guide to removed flag replacements
  • v3.7 upgrade requires etcd v3.6.11 or laterClusters on versions older than v3.6 must first be upgraded to v3.6; etcd supports upgrading only one minor version at a time.
  • Healthy-cluster prerequisite for rolling upgradesA healthy cluster is required for a smooth rolling upgrade; the note names etcdctl endpoint health as the health check.
  • Staging validation for etcd-dependent servicesThe note places these tests in staging, before the upgrade is deployed to production.
  • Snapshot backup for etcd upgrade rollbackA snapshot backup taken before the upgrade can be used to roll back to the existing etcd version if the upgrade goes wrong.
  • Upgrade guide covers cluster snapshots and rollback
  • Binary rollback unavailable after all members reach v3.7Recovery options are restoring the pre-upgrade snapshot or following the official downgrade guide.
  • Cluster health and version checksThe procedure uses etcdctl ... endpoint health and curl .../version to check that the cluster is healthy and running v3.6.11 or later. The sample output shows all three endpoints healthy, with etcdserver 3.6.12, etcdcluster 3.6.0, and storage 3.6.0.
  • Leader snapshot backup for downgrades
  • Upgrade procedure for stopping an existing etcd serverOther members may report errors while the server is temporarily disconnected. If it is the leader, it transfers leadership before exiting.
  • Upgrade guide covers endpoint status checks for members and the cluster
Original release notes
Please check out [CHANGELOG](https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.7.md) for a full list of changes. And make sure to read [upgrade guide](https://etcd.io/docs/v3.7/upgrades/upgrade_3_7/) before upgrading etcd (there may be breaking changes).
github.com/etcd-io/etcd/releases/tag/v3.7.4

Breaking changes1

Deprecated etcd --experimental-* startup flags removed

Affectsetcd deployments whose startup configuration sets any of the listed --experimental-* flags
Action requiredReplace any listed --experimental-* flags with their v3.6 equivalents before rolling to v3.7.

In v3.6, each deprecated flag was replaced by a non-experimental flag of the same name or a --feature-gates entry. In v3.7, etcd fails to start if any removed flag remains configured.

Show release-note lines
All deprecated --experimental-* flags have been removed in v3.7 ( #19959 ). In v3.6 each of these was replaced either by a non-experimental flag of the same name or by a --feature-gates entry. If you still have any of these set, replace them with the v3.6 equivalent before rolling to v3.7, otherwise the v3.7 process will fail to start.
-etcd --experimental-bootstrap-defrag-threshold-megabytes
-etcd --experimental-compact-hash-check-enabled
-etcd --experimental-compact-hash-check-time
-etcd --experimental-compaction-batch-limit
-etcd --experimental-compaction-sleep-interval
-etcd --experimental-corrupt-check-time
-etcd --experimental-distributed-tracing-address
-etcd --experimental-distributed-tracing-instance-id
-etcd --experimental-distributed-tracing-sampling-rate
-etcd --experimental-distributed-tracing-service-name
-etcd --experimental-downgrade-check-time
-etcd --experimental-enable-distributed-tracing
-etcd --experimental-enable-lease-checkpoint
-etcd --experimental-enable-lease-checkpoint-persist
-etcd --experimental-initial-corrupt-check
-etcd --experimental-memory-mlock
-etcd --experimental-peer-skip-client-san-verification
-etcd --experimental-snapshot-catchup-entries
-etcd --experimental-stop-grpc-service-on-defrag
-etcd --experimental-txn-mode-write-with-shared-buffer
-etcd --experimental-warning-apply-duration
-etcd --experimental-warning-unary-request-duration
-etcd --experimental-watch-progress-notify-interval
Flags removed
etcd.io/docs/v3.7/upgrades/upgrade_3_7/

Important fixes2

  • --force-new-cluster bootstrap rejects commit indexes beyond the WAL
    Affectsmembers using --force-new-cluster

    When the backend consistent index was ahead of the last WAL entry, bootstrap could panic and permanently brick the member. It now returns an error instead of proceeding with an adjusted commit index beyond the last WAL entry.

    - Fix [`--force-new-cluster` permanently bricking a member whose backend consistent index is ahead of its WAL](https://github.com/etcd-io/etcd/pull/22685)
    github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.7.md
  • Legacy v2 WAL replay panic fixed
    Affectsetcd members with legacy v2 member-attribute or cluster-version metadata entries in their WALs

    Startup replay could panic on legacy v2 member-attribute entries. Replay now drops legacy v2 member-attribute and cluster-version metadata entries, republishes member attributes before serving requests, and newer members maintain the cluster version.

    - Fix [etcd panics on startup replaying legacy v2 member-attribute WAL entries](https://github.com/etcd-io/etcd/pull/22804)
    github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.7.md
Other changes6
  • Race condition in alarmStore access fixed
    - [Define `alarmStore` as an `atomic.Pointer` to avoid race condition](https://github.com/etcd-io/etcd/pull/22705)
    github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.7.md
  • etcd v2 store and related capabilities removed
    The v2 store has been fully removed in v3.7. The v2 HTTP API ( --enable-v2 ), the v2-on-v3 emulation ( --experimental-enable-v2v3 ), the v2 discovery service, the client/v2 package, and the loading of v2 snapshot files are all gone. See the breaking-change references in CHANGELOG-3.7 .
    etcd.io/docs/v3.7/upgrades/upgrade_3_7/
  • etcd's protobuf code migrates to google.golang.org/protobuf
    - Migration from gogo/protobuf to standard google.golang.org/protobuf (tracked in #14533 ).
    etcd.io/docs/v3.7/upgrades/upgrade_3_7/
  • gRPC proxy logging and tags switch to go-grpc-middleware v2
    - Migration of the deprecated go-grpc-middleware v1 logging and tags libraries to the v2 interceptors ( #20420 ).
    etcd.io/docs/v3.7/upgrades/upgrade_3_7/
  • etcd gRPC tracing migrates to NewServerHandler
    - The OpenTelemetry gRPC interceptors were updated to otelgrpc v0.61.0, replacing the deprecated UnaryServerInterceptor and StreamServerInterceptor with NewServerHandler ( #20017 ).
    etcd.io/docs/v3.7/upgrades/upgrade_3_7/
  • Mixed-version etcd cluster upgrade support
    While upgrading, an etcd cluster supports mixed versions of etcd members, and operates with the protocol of the lowest common version. The cluster is only considered upgraded once all of its members are upgraded to version v3.7. Internally, etcd members negotiate with each other to determine the overall cluster version, which controls the reported version and the supported features.
    etcd.io/docs/v3.7/upgrades/upgrade_3_7/

Summaries are produced by AI, so they can be wrong, and they are provided without warranty.