카나리 배포, 헬스체크, 에러율, 롤백 | 5% 트래픽에서 잡힌 회귀는?

서비스는 쿠버네티스 Deployment 2개(stable / canary) 앞에 인그레스 가중치 라우팅을 둔 구조였다. 새 버전은 이미지 태그 한 칸, 환경 변수 두 개, 결제 벤더 SDK 마이너 업데이트가 묶여 있었다. 카나리 비율은 5% 고정, 승격은 수동 승인 한 번이었다.

전체 트래픽 기준으로 보면 5xx 상승폭은 "살짝 빨간" 정도였다. 카나리 5%에 몰린 실패가 평균에 희석된 탓이다. 고객 티켓은 평균보다 먼저 왔다.

레디니스 프로브는 프로세스 기동과 DB 핑만 봤다. 결제 벤더 SDK 초기화 경로의 타임아웃·서명 헤더 변경은 프로브 범위 밖이었다. 포스트모템에서 묶은 원인은 네 갈래다.

• 관측 단위 오류 — 성공률·지연·에러를 Deployment 전체 평균으로만 알림. canary 라벨 슬라이스가 대시보드에 없었다.
• 라벨·트레이스 누락 — 일부 미들웨어가 version 라벨을 응답 메트릭에 안 붙였다. 카나리 실패를 stable로 오인하는 구간이 생겼다.
• 스티키·캐시 혼선 — 세션 스티키가 있는 경로에서 같은 사용자가 stable과 canary를 오가며 서명 키 불일치 4xx가 났다.
• 승격 기준이 기술 헬스뿐 — "파드 Ready + 5분간 전체 5xx < 1%" 만 있으면 수동 승격 가능. 결제 성공률·특정 엔드포인트·테넌트 슬라이스가 기준에 없었다.

기능 플래그로 코드 경로만 나누는 롤아웃과 겹치는 교훈이다. 트래픽 비율을 나눈 뒤에는 그 비율 안에서의 실패를 따로 봐야 한다. 관련: 기능 플래그 롤아웃 체크리스트, Unleash 기능 플래그 도입 케이스.

당일 응급 조치는 단순했다. 인그레스 가중치를 0/100으로 돌리고 canary Deployment 레플리카를 0으로 내렸다. 에러율은 4분 안에 정상대로 돌아왔다. 이미지는 이전 태그로 고정했고, 벤더 SDK 업데이트가 들어간 커밋은 release 브랜치에서 분리했다.

롤백 자체는 성공했다. 다만 사후에 보면 롤백 결정까지 40분이 걸렸다. 그 사이 온콜은 전체 로그를 뒤졌고, 카나리만 필터하는 쿼리가 런북에 없었다. "배포 직후 이상이면 가중치 0" 한 줄이 런북 맨 위에 없었던 것이 1차 교훈이다.

프로덕션 배포 전 점검 목록에 카나리 롤백 한 줄 명령을 넣어 두라는 조언과 맞닿는다. 참고: 프로덕션 배포 체크리스트.

다음 주 스프린트에서 관측을 손봤다. 응답 메트릭·로그·트레이스에 deploy_group=stable|canary 라벨을 강제했고, 대시보드에 카나리 전용 패널 네 개를 고정했다.

알림도 바꿨다. 전체 5xx 임계값만 있던 채널에 canary_error_budget_burn 을 추가했다. 카나리 실패율이 stable 대비 벌어지면 배포 채널에 바로 멘션된다. 구조화 로그에 deploy_group이 들어가면 온콜 쿼리 시간이 크게 줄었다. 관련: 프로덕션 구조화 로깅 체크리스트, Sentry 런타임 에러 모니터링.

3주차에는 비율을 5% 고정에서 5% → 20% → 50% → 100% 단계로 바꿨다. 각 단계는 게이트 통과 시간이 필요하다. 한 단계라도 실패하면 가중치를 0으로 돌리고 canary 파드를 스케일 다운한다. 도구는 팀 인프라에 맞춰 인그레스 가중치 + 간단한 분석 잡(cron)으로 시작했고, 이후 프로그레시브 딜리버리 컨트롤러 도입을 검토했다.

자동 중단 조건은 공격적으로 잡았다. 표본이 부족할 때는 승격하지 않고 기다린다. 트래픽이 적은 심야 카나리는 "에러 0건"이 곧 안전이 아니다. 최소 요청 수(이 팀은 단계당 200)를 못 채우면 다음 영업일 피크로 연다.

쿠버네티스 운영에서 롤아웃·프로브·HPA를 같이 볼 때와 같은 방향이다. 배포 객체만 초록이라고 끝이 아니다. 참고: 쿠버네티스 프로덕션 운영 가이드, 매니지드 쿠버네티스 비교.

코드보다 중요한 합의는 제품·CS와의 문구다. 카나리 중단은 "장애"가 아니라 의도된 안전 장치로 공유했다. 배포 채널에 실패 사유 코드(error_budget, latency, business_success)를 남기면 다음 핫픽스 범위가 좁아진다.

같은 유형의 회귀(벤더 SDK 헤더 불일치)를 스테이징 카나리 재현과, 이후 실제 소규모 카나리 실패 1건을 기준으로 방향을 비교했다. 절대값은 트래픽·스택마다 다르다.

카나리가 "버그를 없애 준" 것은 아니다. 달라진 것은 나쁜 버전이 받는 트래픽 상한과 발견 속도다. 회로 차단기가 실패의 형태를 바꾸는 것과 비슷한 역할이다. 외부 의존성 격리 사례: 외부 API 회로 차단기 도입 케이스.

1. 표본 없이 초록 판정 — 심야 5% 카나리에서 요청 40건·에러 0으로 승격했다가, 아침 피크에 같은 버전이 터질 뻔했다. 최소 표본 게이트를 넣기 전이다.

2. 4xx를 전부 무시 — 초기에 5xx만 봤다. 서명 오류·스키마 오류는 4xx로 떨어져 카나리가 "건강"해 보였다. 결제 경로의 4xx 중 서버 귀책 코드를 별도 집계했다.

3. 스티키 세션과 가중치 충돌 — 쿠키 스티키가 있는 경로에서 사용자가 버전을 오가며 상태 머신이 깨졌다. 카나리 구간에는 스티키를 끄거나, 버전 고정 헤더를 강제했다.

4. 스테이징 카나리 생략 — "스테이징에 이미 올렸으니 프로덕션 5%면 충분"이 함정이었다. 스테이징 트래픽 패턴이 프로덕션 테넌트 분포와 달랐다. 이후 프로덕션 카나리 전에 섀도·리플레이 짧은 구간을 추가했다.

5. 웹훅·비동기 경로 제외 — HTTP 동기 API만 게이트에 넣고, 웹훅 재처리 워커는 카나리 밖에서 돌렸다. 비동기 중복·재시도 이슈는 다른 날 터졌다. 관련: 웹훅 재시도 폭주·멱등 키 케이스.

모든 변경에 카나리가 답은 아니다. 이 팀이 사내 가이드에 남긴 기준이다.

• 잘 맞는 경우 — 무상태 API, 수평 확장 파드, 메트릭 라벨이 이미 있는 서비스, 롤백이 가중치 한 줄로 끝나는 구조.
• 추가 설계가 필요한 경우 — 스키마 마이그레이션 동반 배포, 스티키 세션, 장시간 워크플로, 웹훅·큐 컨슈머. DB 변경은 expand-contract와 순서를 맞춰야 한다. 참고: 무중단 DB 스키마 마이그레이션 체크리스트.
• 카나리보다 플래그가 나은 경우 — UI 카피·권한 매트릭스처럼 코드 경로만 갈라도 되는 변경. 트래픽 미러링 비용 없이 킬스위치가 가능하다.
• 같이 써야 하는 것 — 구조화 로그, 에러 트래킹, 배포 주석(누가·무엇·왜), 롤백 한 줄 런북.

블루그린은 "한 번에 전환"에 가깝고, 카나리는 "비율로 검증"에 가깝다. 트래픽이 아주 낮으면 카나리 표본이 안 나와 블루그린 + 짧은 검증 창이 나을 수도 있다. 팀 트래픽과 관측 성숙도를 먼저 적고 고르는 편이 안전하다.

배포 직후 이상이 의심될 때 보는 순서다. 문서 문장을 거의 그대로 옮겼다.

1. 지금 카나리 가중치와 canary 파드 수를 확인한다. 불확실하면 가중치 0이 기본값이다.
2. 대시보드에서 deploy_group=canary 에러율·p95·결제 성공률을 stable과 나란히 본다. 전체 평균만 보지 않는다.
3. 최근 배포 diff에서 외부 SDK·환경 변수·피처 플래그 기본값을 확인한다.
4. 게이트 실패 사유 코드가 있으면 그 코드로 이슈를 연다. "일단 스케일 아웃"은 마지막이다.
5. 롤백 후 15분 동안 웹훅·큐 적체를 확인한다. 동기 API만 정상인 착시를 막는다.
6. 포스트모템 초안에 타임라인·영향 테넌트·미탐 이유를 남기고, 게이트 임계값 조정이 필요한지 한 줄로 적는다.

고객 공지는 "전체 결제 장애" 대신 "일부 트래픽 경로에서 결제 확인 오류, 해당 경로 차단 완료"처럼 범위를 적는다. 지원 분류 시간이 줄었다.

• Martin Fowler — CanaryRelease (카나리 릴리스 개념)
• Kubernetes Docs — Deployments (롤아웃·프로브와 배포 객체)
• Argo Rollouts 문서 (프로그레시브 딜리버리·분석 템플릿)
• Flagger 문서 (메트릭 기반 카나리 자동화)

패턴 이름과 도구 용어는 위 문서를 기준으로 했고, 본문 수치·타임라인은 익명 팀 포스트모템 재구성이다.