Argo Rollouts로 카나리 배포와 Prometheus 메트릭 기반 자동 롤백 붙이기
기본 Deployment 롤링 업데이트가 못 보는 것부터, Argo Rollouts CRD로 트래픽을 단계적으로 흘리는 카나리 배포, Nginx Ingress 트래픽 분할, AnalysisTemplate으로 Prometheus 메트릭을 봐서 자동 롤백하는 절차, 블루그린 옵션까지.
목표
지금까지 이 시리즈는 ArgoCD로 GitOps 배포까지는 갖췄지만(시리즈 2), 배포 전략 자체는 기본 Kubernetes Deployment의 롤링 업데이트에 머물러 있었다. 이 시리즈는 그 위 단계를 다룬다 - 새 버전에 트래픽을 조금씩만 흘려보고, 문제가 있으면 사람이 알아채기 전에 메트릭 기준으로 자동으로 되돌리는 배포를 만든다.
개념: Deployment 롤링 업데이트가 못 보는 것
기본 Deployment의 롤링 업데이트는 단순하다 - 새 파드를 하나씩 늘리고 옛 파드를 하나씩 줄인다. 이때 유일한 판단 기준은 헬스체크(liveness/readiness)를 통과하는가다. 문제는 헬스체크 통과와 "서비스가 제대로 동작하는가"가 다른 질문이라는 점이다 - 프로세스는 떠 있고 /healthz도 200을 반환하는데, 특정 API의 에러율만 조용히 올라가는 배포는 롤링 업데이트가 절대 잡아내지 못한다. 롤링 업데이트는 "파드가 살아있는지"만 보고, "트래픽을 받은 결과가 정상인지"는 보지 않는다.
Argo Rollouts는 Deployment를 대체하는 CRD(Rollout)로, 배포 과정에 단계·대기·검증을 끼워 넣을 수 있게 해준다. 핵심 개념 세 가지:
| 개념 | 설명 |
|---|---|
| 카나리(Canary) | 새 버전에 트래픽을 5%→20%→50%→100%처럼 단계적으로 흘리고, 각 단계 사이에 대기 시간이나 수동 승인을 둘 수 있음 |
| AnalysisTemplate | 각 단계에서 Prometheus 등 메트릭을 쿼리해 기준(에러율, p99 레이턴시 등)을 정의 - 기준을 넘으면 사람 개입 없이 자동으로 이전 버전으로 롤백 |
| 블루그린(Blue-Green) | 새 버전을 통째로 띄워두고 스위치 한 번으로 트래픽을 전환, 문제 시 즉시 원복 |
| 트래픽 미러링(Mirroring) | 실사용자에게는 여전히 기존 버전이 응답하고, 같은 요청을 복제해서 신버전에 "그림자"로만 보냄 - 응답은 버려지므로 신버전이 잘못 응답해도 사용자는 영향받지 않음 |
이 시리즈는 이미 ArgoCD·Prometheus·Nginx Ingress를 갖추고 있으므로(시리즈 2, 6), 트래픽 분할은 서비스 메시 없이 Nginx Ingress 애노테이션 기반 분할로 가장 간단하게 시작한다.
실제 구축 절차
1. Argo Rollouts 설치
kubectl create namespace argo-rollouts
kubectl apply -n argo-rollouts -f https://github.com/argoproj/argo-rollouts/releases/latest/download/install.yaml
# kubectl 플러그인 - Rollout 상태를 실시간으로 보기 위함
curl -LO https://github.com/argoproj/argo-rollouts/releases/latest/download/kubectl-argo-rollouts-linux-amd64
chmod +x kubectl-argo-rollouts-linux-amd64
sudo mv kubectl-argo-rollouts-linux-amd64 /usr/local/bin/kubectl-argo-rollouts
2. Deployment → Rollout 전환
기존 api-server Deployment를 Rollout 오브젝트로 바꾼다. apiVersion과 kind만 바뀌고 spec.template 이하는 거의 동일하다 - 대신 strategy 아래에 카나리 단계를 정의한다.
# api-server-rollout.yaml
apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
name: api-server
spec:
replicas: 5
selector:
matchLabels: { app: api-server }
template:
metadata:
labels: { app: api-server }
spec:
containers:
- name: api-server
image: harbor.local/proxy-cache/api-server:latest
strategy:
canary:
canaryService: api-server-canary
stableService: api-server-stable
trafficRouting:
nginx:
stableIngress: api-server-ingress
steps:
- setWeight: 5
- pause: { duration: 2m }
- analysis:
templates:
- templateName: error-rate-check
- setWeight: 20
- pause: { duration: 2m }
- setWeight: 50
- pause: { duration: 5m }
- setWeight: 100
canaryService/stableService는 같은 파드 셀렉터를 가리키지만 각각 신규/기존 버전으로 라우팅되는 별도 Service다. trafficRouting.nginx.stableIngress에 지정한 Ingress의 애노테이션을 Argo Rollouts가 컨트롤러 대신 자동으로 조작해 트래픽 비율을 나눈다 - 즉 사람이 직접 nginx.ingress.kubernetes.io/canary-weight를 고칠 필요가 없다.
kubectl apply -f api-server-rollout.yaml
kubectl argo-rollouts get rollout api-server --watch # 단계별 진행 상황을 실시간으로 확인
왜 5% → 20% → 50% → 100%인가. 이 숫자는 임의로 정한 게 아니라 두 가지를 동시에 만족시키려는 절충이다.
- 초반 스텝(5%)은 최대한 작게, blast radius를 줄이는 목적이다. 배포 초기가 결함이 발견될 확률이 제일 높은 구간이므로, 문제가 있는 버전이라도 전체 트래픽의 5%만 잠깐 나쁜 응답을 받고 끝나야 한다. 5%보다 더 낮출 수도 있지만, 그러면 아래에서 다룰 통계적 유의성 문제가 커진다.
- 중반 이후 스텝(20% → 50%)은 간격을 넓혀 검증 속도를 높이는 목적이다. 5%에서 이미 한 번 안전하다는 신호를 받았다면, 남은 위험은 "저트래픽 구간에서는 안 보이던 문제가 고트래픽에서 드러나는가"(리소스 한계, 커넥션 풀 고갈, 캐시 스탬피드 등)로 좁혀진다. 이 구간에서는 스텝을 촘촘하게 나눠도 얻는 정보가 크지 않으므로 20%→50%처럼 크게 뛰어도 된다.
- 각 단계 사이
pause시간은 "이 단계에서 이상 신호가 나타나기까지 걸리는 시간"을 기준으로 정한다. 에러율처럼 즉시 나타나는 지표는 2분이면 충분하지만, 메모리 누수나 커넥션 누수처럼 누적돼야 드러나는 문제는 짧은 pause로는 절대 못 잡는다. 그래서 트래픽 비중이 커지는 뒷단계(50%)의 pause를 앞단계보다 길게(5분) 잡는 것이 합리적이다 - 트래픽이 커질수록 누적성 문제가 더 빨리, 더 뚜렷하게 드러나기 때문이다. - 트래픽이 적은 서비스에서는 5%가 통계적으로 무의미할 수 있다. 하루 요청이 10만 건인 서비스라면 5% 단계에서도 30초당 수십~수백 건이 들어오므로 에러율 계산이 신뢰할 만하지만, 하루 1,000건짜리 내부 서비스라면 5% 단계의 30초 구간에는 요청이 아예 0건일 수도 있다. 이 경우
setWeight숫자를 낮추는 게 아니라 분석 구간(pause.duration,analysis스텝의interval)을 늘려서 표본을 충분히 모으는 방향으로 조정해야 한다 - 트래픽이 적은 서비스는 시간을 사서 표본 크기를 확보하는 것이지, 비율을 조정해서 해결되는 문제가 아니다.
3. AnalysisTemplate - Prometheus 메트릭 기준 자동 롤백
카나리 단계 사이에 끼워 넣은 analysis 스텝이 바로 이 부분이다. 5% 트래픽을 받는 동안 에러율을 Prometheus에 쿼리해서, 기준을 넘으면 그 자리에서 자동으로 롤백한다.
# analysis-template.yaml
apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
name: error-rate-check
spec:
metrics:
- name: error-rate
interval: 30s
count: 4 # 30초씩 4번 반복 측정
successCondition: result[0] < 0.05 # 5% 미만이어야 통과
failureLimit: 1 # 1번이라도 실패하면 즉시 중단
provider:
prometheus:
address: http://prometheus-operated.monitoring:9090
query: |
sum(rate(http_requests_total{app="api-server-canary", status=~"5.."}[1m]))
/
sum(rate(http_requests_total{app="api-server-canary"}[1m]))
successCondition을 만족하지 못하는 순간 Argo Rollouts는 남은 카나리 단계를 진행하지 않고 트래픽 비중을 즉시 0으로 되돌린다 - "배포 후 대시보드를 지켜보다 이상하면 수동으로 롤백"하던 걸 기계가 대신하는 지점이 정확히 여기다.
3-1. 메트릭 하나로는 부족하다 - 다중 메트릭 AND 조건
에러율만 보면 놓치는 실패 유형이 있다. 대표적으로 응답은 200을 반환하지만 레이턴시만 조용히 튀는 배포 - 예를 들어 N+1 쿼리가 섞여 들어간 버전은 에러율 기준으로는 완벽하게 통과하지만 p99 레이턴시는 몇 배로 뛴다. 반대로 레이턴시만 보면 순간적인 5xx 폭증은 평균 레이턴시에 잘 안 잡힐 수 있다. 그래서 AnalysisTemplate의 metrics는 배열이고, 여러 메트릭을 동시에 등록하면 모든 메트릭이 각자의 successCondition을 만족해야 승격이 진행된다 - 즉 기본 동작이 이미 AND 조건이다.
# analysis-template.yaml (다중 메트릭)
apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata:
name: error-rate-and-latency-check
spec:
metrics:
- name: error-rate
interval: 30s
count: 4
successCondition: result[0] < 0.05
failureLimit: 1
provider:
prometheus:
address: http://prometheus-operated.monitoring:9090
query: |
sum(rate(http_requests_total{app="api-server-canary", status=~"5.."}[1m]))
/
sum(rate(http_requests_total{app="api-server-canary"}[1m]))
- name: p99-latency
interval: 30s
count: 4
successCondition: result[0] < 0.3 # p99 300ms 미만
failureLimit: 1
provider:
prometheus:
address: http://prometheus-operated.monitoring:9090
query: |
histogram_quantile(0.99,
sum(rate(http_request_duration_seconds_bucket{app="api-server-canary"}[1m])) by (le)
)
두 메트릭 중 하나라도 failureLimit을 넘기면 전체 분석이 실패로 처리되고 롤백이 트리거된다 - "에러율은 정상인데 레이턴시가 튀어서 막힌 배포"를 실제로 잡아내는 지점이다.
메트릭 노이즈가 잘못된 롤백을 만드는 문제. 5% 트래픽 구간은 절대 표본 수가 적기 때문에, 짧은 순간의 우연한 스파이크(느린 외부 API 호출 한 건, GC 일시정지 한 번)만으로도 successCondition을 순간적으로 어길 수 있다. 이걸 배포 자체의 결함으로 착각해 자동 롤백하면 "정상 버전인데 노이즈 때문에 롤백된" 거짓 양성(false positive)이 된다. 세 파라미터로 이 민감도를 조절한다.
interval을 늘린다 - 30초마다 재는 대신 1분마다 재면,rate()윈도우 안에 더 많은 요청이 섞여 순간 스파이크가 평균에 희석된다.count를 늘리고failureLimit도 같이 올린다 -count: 4, failureLimit: 1은 "4번 측정 중 1번만 실패해도 즉시 중단"이라 노이즈에 취약하다.count: 6, failureLimit: 2정도로 바꾸면 "6번 중 2번 이상 연속/누적으로 실패해야 진짜 문제로 판단"하게 되어 일회성 스파이크에는 버티고 지속적인 악화에는 반응한다.successCondition자체를 순간값이 아닌 집계값 기준으로 만든다 -result[0]처럼 마지막 측정값 하나만 보는 대신, Prometheus 쿼리 자체를avg_over_time(...[5m])으로 감싸서 5분 평균이 기준을 넘는지 보게 하면, 쿼리 레벨에서 이미 스무딩이 들어가 개별 측정의 흔들림에 덜 민감해진다.
이 세 값을 너무 느슨하게 풀면 진짜 결함도 못 잡고, 너무 빡빡하게 조이면 노이즈에도 롤백되는 "울보 늑대" 상태가 된다 - 실무에서는 배포 전 스테이징에서 정상 트래픽 패턴의 메트릭 변동폭을 먼저 관찰하고, 그 변동폭보다 확실히 벗어나는 지점을 기준으로 잡는 게 안전하다.
4. ArgoCD와의 연동
시리즈 2에서 이미 ArgoCD로 GitOps 배포를 하고 있다면, Rollout/AnalysisTemplate 매니페스트도 같은 Git 저장소·같은 Application에 그대로 커밋하면 된다 - ArgoCD 입장에서는 Deployment든 Rollout이든 그냥 관리하는 리소스 중 하나다. 다만 ArgoCD UI에서 카나리 진행 상태를 보려면 Argo Rollouts용 UI 확장(kubectl argo-rollouts dashboard)을 따로 띄워야 한다.
5. (선택) 블루그린으로 전략 교체
일부 서비스는 트래픽을 점진적으로 나누는 것보다 "완전히 새 버전으로 스위치 - 문제 시 즉시 원복"이 더 맞을 수 있다. strategy.canary 대신 strategy.blueGreen으로 바꾸면 된다.
strategy:
blueGreen:
activeService: api-server-active
previewService: api-server-preview
autoPromotionEnabled: false # 수동 승인 후에만 전환
prePromotionAnalysis:
templates:
- templateName: error-rate-check
prePromotionAnalysis로 전환 직전에도 같은 AnalysisTemplate을 재사용할 수 있다 - 카나리와 블루그린이 검증 로직 자체는 공유하고, 트래픽을 어떻게 나누느냐만 다르다는 걸 보여주는 지점이다.
카나리와 블루그린의 근본적인 차이는 "무엇을 줄이느냐"가 다르다는 데 있다.
- 카나리는 blast radius(장애 반경)를 줄이는 전략이다. 문제가 있는 버전이 배포돼도 5% 단계에서 잡히면 영향받는 사용자는 전체의 5%뿐이다. 하지만 그 대가로 신버전과 구버전이 트래픽 전환 기간 내내 동시에 살아있다 - 5%→20%→50% 단계를 거치는 동안 어떤 요청은 신버전이, 어떤 요청은 구버전이 처리한다. 이 기간 동안 둘 사이의 API 호환성(응답 스키마 변경, DB 마이그레이션과의 순서, 세션/캐시 포맷 변경 등)이 깨지면 카나리 매커니즘으로는 못 잡는다 - 에러율이나 레이턴시로는 안 보이는데 "신버전 응답을 구버전 클라이언트가 잘못 해석하는" 유형의 문제이기 때문이다. 즉 카나리는 버전 공존 자체가 원인인 문제에는 오히려 취약하다.
- 블루그린은 이 공존 문제를 원천적으로 없앤다. 전환은 스위치 한 번이라 특정 시점 이후로는 100% 신버전만 트래픽을 받는다 - 신구 버전이 동시에 실트래픽을 처리하는 구간이 없으므로 API 호환성 문제가 "전환 전엔 전혀 없었다가 전환 후 전부"라는 형태로만 나타난다. 대신 실사용자 트래픽으로 점진적 검증을 할 수 없다 -
previewService로 접근해 스모크 테스트는 가능하지만, 이건 결국 별도의 테스트 트래픽이지 "실제 사용자 5%가 신버전을 겪는" 것과 같은 신뢰도를 주지 못한다. 그래서 전환 직후 문제가 드러나면 즉시 원복은 가능해도, 원복 전까지는 100%가 노출된다는 점에서 blast radius 자체는 카나리보다 크다. - 실무적으로는 DB 스키마나 캐시 포맷처럼 신구 버전이 절대 공존하면 안 되는 변경은 블루그린으로, 런타임 동작(로직 변경, 성능 튜닝, 의존 라이브러리 업그레이드)처럼 점진적으로 실트래픽 검증이 유효한 변경은 카나리로 나누는 것이 각 전략의 장점을 살리는 선택이다.
(선택) 트래픽 미러링 - 카나리보다 안전한 검증
카나리도 결국 신버전에 실제 응답을 돌려주는 방식이라 5%든 1%든 실사용자가 영향을 받는다. 신버전의 동작을 아직 신뢰할 수 없어서 "사용자에게 절대 영향을 주지 않고" 검증하고 싶다면 카나리보다 한 단계 더 보수적인 방법이 **트래픽 미러링(traffic mirroring/shadowing)**이다. 미러링은 들어온 요청을 안정 버전이 정상 처리해서 사용자에게 응답을 돌려주는 동시에, 같은 요청의 복사본을 신버전에도 보내지만 그 응답은 그냥 버린다. 신버전이 500을 반환하든 타임아웃이 나든 사용자는 아무 영향도 받지 않는다.
strategy:
canary:
trafficRouting:
nginx:
stableIngress: api-server-ingress
steps:
- setCanaryScale: { weight: 0 } # 실트래픽 분배는 0%
- setMirrorRoute:
name: mirror-to-canary
match:
- method: { exact: GET }
requests:
service: api-server-canary
미러링이 카나리보다 안전한 경우는 명확하다.
- 부작용이 있는 API(결제, 재고 차감, 알림 발송)를 검증할 때 - 카나리는 실제로 트래픽의 일부가 결제를 "진짜로" 처리하게 만들지만, 미러링은 결제 요청을 복제해서 신버전에 흘려도 실제 결제는 안정 버전만 처리하므로 이중 결제 같은 사고가 나지 않는다(물론 신버전 쪽에서 미러링된 요청이 실제 부작용을 일으키지 않도록 별도 처리가 필요한 경우도 있다 - 예를 들어 결제 게이트웨이 호출까지 그대로 복제되면 안 된다).
- 신버전의 성능 특성(레이턴시, 리소스 사용량)을 실트래픽 패턴으로만 확인하고 싶을 때 - 사용자에게 응답을 주지 않아도 되므로 신버전이 얼마나 걸리는지, 얼마나 많은 CPU/메모리를 쓰는지는 그대로 측정 가능하다.
- 아직 프로덕션에 노출할 확신이 없는 초기 검증 단계 - 미러링으로 먼저 문제가 없다는 신호를 얻은 뒤에 카나리로 넘어가면, 카나리 5% 단계에서 마주칠 위험을 한 단계 줄일 수 있다. 즉 "미러링 → 카나리 → 블루그린 스위치"처럼 이어서 쓸 수 있는 검증 파이프라인이 된다.
단, 미러링은 신버전의 응답 자체를 사용자가 실제로 받아보는 검증은 하지 못한다 - 응답을 버리기 때문에 "신버전이 올바른 응답을 반환하는가"는 별도로 로그 비교나 오프라인 diff로 확인해야 한다. 그래서 미러링은 카나리를 대체하는 게 아니라, 카나리 전에 거치는 사전 검증 단계로 보는 게 정확하다.
검증 방법
- 의도적으로 에러율이 높은 이미지를 배포해, 5% 단계에서
AnalysisTemplate이 실패를 감지하고 자동 롤백하는지 확인 - 에러율은 정상이지만 레이턴시만 높은 이미지를 배포해, 다중 메트릭 AND 조건에서 레이턴시 메트릭만으로도 롤백이 트리거되는지 확인
- 정상 배포에서도 일시적인 메트릭 스파이크가 섞인 상황을 재현해,
interval/count/failureLimit조정이 거짓 양성 롤백을 막아주는지 확인 - 정상 이미지 배포 시 5%→20%→50%→100%까지 각 단계가 정의한 대기 시간대로 진행되는지
kubectl argo-rollouts get rollout --watch로 확인 - 롤백이 발생했을 때 실제 서비스 트래픽이 끊기지 않고 안정 버전으로 계속 처리되는지 확인
- (선택)
setMirrorRoute로 미러링을 구성해, 신버전이 실패해도 실사용자 응답에는 영향이 없는지 확인 - (선택) 블루그린 전략에서
previewService로 먼저 접근해 검증한 뒤 수동 승인으로 전환이 잘 되는지 확인
체크리스트
- Argo Rollouts 컨트롤러·kubectl 플러그인 설치
- 기존 Deployment를 Rollout으로 전환, canary/stable Service 분리
- Nginx Ingress 트래픽 분할 연동 확인
- Prometheus 쿼리 기반 AnalysisTemplate 작성, 카나리 단계에 편입
- 에러율·레이턴시 등 다중 메트릭 AND 조건으로 AnalysisTemplate 확장
- 서비스 트래픽 규모에 맞춰
interval/count/failureLimit과 카나리 weight 스텝·pause 시간 조정 - 의도적 실패 배포로 자동 롤백 동작 검증
- (선택) 부작용이 있는 API에 대해 트래픽 미러링으로 사전 검증 구성
- ArgoCD Application에 Rollout 매니페스트 편입
- (선택) 블루그린 전략으로 교체, prePromotionAnalysis 재사용 확인