# etcd v3.7.4

2026-11-19 · [릴리스 노트 원문](https://github.com/etcd-io/etcd/releases/tag/v3.7.4) · [전체 정리](https://ratatosk.io/ko/releases/etcd/v3.7.4)

호환성 변경 1 · 중요 수정 2 · 기타 6

## 업그레이드 전 확인

### 업그레이드 안내

- **etcd v3.7.4 업그레이드 안내**
  > 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).

  - etcd v3.6에서 v3.7로 무중단 업그레이드 안내
  - 업그레이드 준비 가이드
  - 3.7 업그레이드에 필요한 최신 3.6 멤버: 업그레이드 전에 클러스터의 모든 멤버가 3.6.11 이상이어야 합니다. 이전 3.6 패치 릴리스는 3.7로 롤링 업그레이드할 때 호환되지 않을 수 있습니다.
  - 이전 릴리스용 v2 데이터 마이그레이션 가이드
  - etcd 임베더, `clientv3` 사용자 및 내부 패키지 의존자를 위한 업그레이드 변경 로그
  - v3.5에서 v3.6으로 업그레이드할 때 제거된 플래그 대체 안내
  - v3.7 업그레이드에 etcd v3.6.11 이상 필요: v3.6보다 오래된 버전을 사용하는 클러스터는 먼저 v3.6으로 업그레이드해야 합니다. etcd는 한 번에 마이너 버전 하나씩만 업그레이드할 수 있도록 지원합니다.
  - 롤링 업그레이드를 위한 클러스터 정상 상태 요건: 원활한 롤링 업그레이드를 위해서는 클러스터가 정상 상태여야 합니다. 안내에는 상태 확인 명령으로 `etcdctl endpoint health`가 명시되어 있습니다.
  - etcd 의존 서비스의 스테이징 검증: 이 테스트는 업그레이드를 프로덕션에 배포하기 전에 스테이징에서 수행하도록 안내합니다.
  - etcd 업그레이드 롤백을 위한 스냅샷 백업: 업그레이드 전에 생성한 스냅샷 백업을 사용하면 업그레이드에 문제가 생겼을 때 기존 etcd 버전으로 롤백할 수 있습니다.
  - 클러스터 스냅샷과 롤백을 다루는 업그레이드 가이드
  - 모든 멤버가 v3.7에 도달한 뒤 바이너리 롤백 불가: 복구하려면 업그레이드 전 스냅샷을 복원하거나 공식 다운그레이드 가이드를 따라야 합니다.
  - 클러스터 상태 및 버전 확인: 절차에서는 `etcdctl ... endpoint health`와 `curl .../version`을 사용해 클러스터가 정상 상태이며 v3.6.11 이상을 실행 중인지 확인합니다. 예시 출력에서는 세 엔드포인트가 모두 정상이며, etcdserver는 3.6.12, etcdcluster와 storage는 각각 3.6.0입니다.
  - 다운그레이드를 위한 리더 스냅샷 백업
  - 기존 etcd 서버를 중지하는 업그레이드 절차: 서버가 일시적으로 연결이 끊긴 동안 다른 멤버에서 오류가 보고될 수 있습니다. 해당 서버가 리더라면 종료 전에 리더십을 이전합니다.
  - 멤버와 클러스터의 엔드포인트 상태 확인을 다루는 업그레이드 가이드

## 호환성 변경 (1)

### etcd의 지원 중단 예정 `--experimental-*` 시작 플래그 제거

- 영향 대상: 시작 구성에서 나열된 `--experimental-*` 플래그 중 하나라도 설정한 etcd 배포
- 필요 조치: v3.7로 롤링 업데이트하기 전에 나열된 `--experimental-*` 플래그를 v3.6에 해당하는 플래그로 모두 대체

v3.6에서는 지원 중단 예정인 각 플래그를 같은 이름의 비실험 플래그나 `--feature-gates` 항목으로 대체했습니다. v3.7에서는 제거된 플래그가 하나라도 구성에 남아 있으면 etcd가 시작되지 않습니다.

> 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

https://etcd.io/docs/v3.7/upgrades/upgrade_3_7/

## 중요 수정 (2)

### `--force-new-cluster` 부트스트랩에서 WAL 마지막 항목을 초과하는 커밋 인덱스 거부

- 영향 대상: `--force-new-cluster`를 사용하는 멤버

백엔드 일관성 인덱스가 마지막 WAL 항목보다 크면 부트스트랩 중 패닉이 발생해 멤버를 영구적으로 사용할 수 없게 만들 수 있었습니다. 이제는 마지막 WAL 항목보다 큰 값으로 커밋 인덱스를 조정해 진행하는 대신 오류를 반환합니다.

> - 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)

https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.7.md

### 레거시 v2 WAL 재생 패닉 수정

- 영향 대상: WAL에 레거시 v2 멤버 속성 또는 클러스터 버전 메타데이터 항목이 있는 etcd 멤버

시작 시 WAL 재생 과정에서 레거시 v2 멤버 속성 항목 때문에 패닉이 발생할 수 있었습니다. 이제 재생 과정에서 레거시 v2 멤버 속성 및 클러스터 버전 메타데이터 항목을 버리고, 요청을 처리하기 전에 멤버 속성을 다시 게시하며, 더 최신인 멤버가 클러스터 버전을 유지합니다.

> - Fix [etcd panics on startup replaying legacy v2 member-attribute WAL entries](https://github.com/etcd-io/etcd/pull/22804)

https://github.com/etcd-io/etcd/blob/main/CHANGELOG/CHANGELOG-3.7.md

## 기타 (6)

- `alarmStore` 접근 시 경쟁 상태 수정
- etcd v2 스토어 및 관련 기능 제거
- etcd의 protobuf 코드, `google.golang.org/protobuf`로 마이그레이션
- gRPC 프록시 로깅 및 태그의 `go-grpc-middleware` v2 전환
- etcd gRPC 트레이싱, `NewServerHandler`로 전환
- 서로 다른 버전의 etcd 클러스터 업그레이드 지원

---

정리 내용은 AI가 작성하므로 틀릴 수 있으며, 보증 없이 제공합니다.
