# 0003. etcd 배포 방식 — `groundhog2k/etcd` 단일 차트 채택, replicas=1(SPOF 수용)

- 날짜: 2026-07-31
- 상태: 확정
- 원본: security-catalog ADR 0006 — dip-catalog 맥락으로 다시 썼다([README](README.md) 참고)

## 결정

카탈로그의 etcd 배포 방식으로 `groundhog2k/etcd` 차트(오퍼레이터 없는 단일 StatefulSet
차트)를 채택한다. 용도는 **단일 APISIX 인스턴스의 설정 저장소**이며, 쿼럼 HA 대신
`replicas: 1` 로 배포한다 — **단일 장애점을 의도적으로 수용한다.** 기존 `bitnami/etcd` 기반
배포는 이 차트로 교체한다.

카탈로그 위치는 [manifests/helm/etcd/1.1.12/](../../manifests/helm/etcd/1.1.12/)다.
`replicas: 1` 은 `custom-values.yaml`(APISIX 용도), 쿼럼이 필요한 다른 소비자를 위한
`replicas: 3` 프로파일은 `dip-values.yaml` 에 있다.

## 배경

dev 클러스터 `apisix` 네임스페이스에 이미 `data-apisix-etcd-0` PVC 가 있었다 — `bitnami/etcd`
기반 APISIX 배포가 떠 있었다는 뜻이다. 이를 카탈로그 방식으로 정식 편입하며 이미지 출처를
재검토했다. 후보는 `groundhog2k/etcd`(채택), `bitnami/etcd`(기존), `aenix-io/etcd-operator`
류의 오퍼레이터 방식이다.

## 근거

**Bitnami 이미지 카탈로그 정책 변경(2025-08)이 결정적이었다.** `docker.io/bitnami/etcd` 는
2025-08-28 부로 `bitnamilegacy/etcd` 로 이전되어 **동결**됐고(이후 보안 패치 없음),
2025-09-29 공개 카탈로그 삭제 이후 신규 무료 티어는 44개 "development-only" 이미지로
한정되며 그마저도 **버전 고정 없이 `latest` 태그만 제공**한다. 계속 패치를 받으려면 유료
구독이 필요하다.

이는 카탈로그 목표와 두 지점에서 정면 충돌한다.

1. 패치가 멈춘 이미지는 시간이 지날수록 미수정 CVE 가 구조적으로 누적된다 —
   "CRITICAL/HIGH 0건" 을 유지 가능한 상태로 지속할 수 없다.
2. 버전 고정 없는 `latest`-only 배포는 **롤링 태그 금지** 규칙과 애초에 양립하지 않는다
   ([.claude/image-authoring.md](../../.claude/image-authoring.md)).

`groundhog2k/etcd` 는 업스트림 etcd 프로젝트의 원본 이미지(`quay.io/coreos/etcd`)를 그대로
쓰므로 이 문제가 없다 — 다른 카탈로그 항목과 동일한 "업스트림 원본 이미지 + 버전 고정 태그"
모델이다.

**오퍼레이터 방식은 측정 없이 정성적으로 배제했다.** 단일 APISIX 인스턴스에 쿼럼 HA 가
불필요하다고 판단해, CRD·컨트롤러·RBAC 을 추가로 들이는 비용이 이득보다 크다고 봤다. 실측
비교는 하지 않았다 — 이 판단은 근거가 정성적이라는 것을 명시해 둔다.

## 받아들인 비용

- **단일 장애점(SPOF)** — `replicas: 1` 이라 etcd Pod/노드 장애 시 APISIX 설정 조회·변경이
  즉시 불가능해진다. 쿼럼 기반 자동 복구가 없다.
- **자동 백업이 없다** — 차트에 백업 기능이 없고, SPOF 상태에서 장애가 데이터 손실로 이어질
  수 있다. 스냅샷은 수동(`etcdctl snapshot save`)이다.
- **Bitnami 가 기본 제공하던 부가 기능**(메트릭 익스포터 등 번들 구성)을 잃는다. 필요하면
  `serviceMonitor` 설정으로 별도 구성한다.
- **쿼럼 HA 로 전환하려면 데이터 마이그레이션을 동반한 재배포가 필요하다** — `replicas` 는
  최초 배포 후 변경 불가다(차트 제약).

## 재검토 조건

- APISIX 를 다중 인스턴스로 확장해 etcd 쿼럼 HA 가 실제로 필요해지면.
- etcd Pod 장애로 인한 SPOF 위험이 운영상 수용 불가능한 빈도로 발생하면.
- `groundhog2k/etcd` 유지보수가 중단되거나, 이 결정의 근거였던 문제(패치 중단·롤링 태그
  강제)가 이 차트에서도 재현되면.