Flagger MetricTemplate CRD로 Datadog·New Relic을 카나리 배포 자동화에 활용
Kubernetes 환경에서 새 버전을 배포할 때 가장 두려운 순간은 "이 버전, 실제로 안전한가?"를 판단해야 할 때다. 새벽 2시에 카나리 배포를 시작하고, 밤새 Datadog 대시보드를 새로고침하다가 에러율이 치솟는 것을 30분 뒤에 발견하는 상황 — 이미 수천 명의 사용자가 영향을 받은 뒤다. 조직이 이미 Datadog이나 New Relic 같은 APM을 사용하고 있다면, 그 판단을 사람 대신 시스템이 내리게 할 수 있다. Flagger의 MetricTemplate CRD를 사용하면 외부 APM에 저장된 실제 서비스 메트릭을 카나리 분석의 자동 판단 기준으로 연결할 수 있다.
Flagger는 Flux CD 프로젝트의 공식 프로그레시브 딜리버리 오퍼레이터다. 비슷한 도구로 Argo Rollouts가 있는데, Argo Rollouts는 세밀한 수동 제어와 단계적 승인에 강점이 있는 반면, Flagger는 메트릭 기반 완전 자동화와 GitOps 워크플로 통합에 초점을 맞춘다. 이 글에서는 Flagger의 MetricTemplate을 이용해 Datadog·New Relic과 연동하는 실전 예시, templateVariables를 활용한 재사용 패턴, 그리고 운영 현장에서 자주 발생하는 실수를 다룬다.
새로운 메트릭 스택을 별도로 구축할 필요 없이, 오늘 이미 사용 중인 APM 쿼리를 카나리 판단 기준으로 바로 연결할 수 있다.
이 글은 누구를 위한 가이드인가: Kubernetes 클러스터를 운영 중이고, Istio 또는 NGINX Ingress 같은 L7 트래픽 관리 레이어를 갖추고 있으며, Datadog 또는 New Relic 계약이 있는 팀의 플랫폼·DevOps 엔지니어를 대상으로 한다. Flagger 설치는 공식 설치 가이드를 참고한다.
핵심 개념
MetricTemplate CRD란 무엇인가
MetricTemplate은 Flagger가 카나리 분석 중 외부 메트릭 제공자에게 던질 질문을 정의한 Kubernetes CRD다. "Datadog에 연결해서 이 쿼리를 실행하고, 결과가 이 기준을 벗어나면 배포를 멈춰라"는 선언적 명세서로, Canary 오브젝트가 이를 참조함으로써 분석 기준이 완성된다.
트래픽 일부 → 카나리 Pod
→ Flagger가 interval마다 MetricTemplate 쿼리 실행
→ 반환값이 thresholdRange 내 → weight 증가
→ 최대 weight 도달 → 자동 프로모션
→ threshold 위반 횟수 초과 → 자동 롤백MetricTemplate의 핵심 동작 원리는 세 가지다.
| 원리 | 설명 |
|---|---|
| 단일 float64 반환 | 쿼리는 반드시 숫자 하나를 반환해야 하며, 이 값이 thresholdRange와 비교됨 |
| 템플릿 변수 자동 주입 | {{ namespace }}, {{ target }}, {{ interval }} 등이 카나리 컨텍스트에서 자동 치환됨 |
| 네임스페이스 공유 | 하나의 MetricTemplate을 여러 팀·서비스가 참조 가능 — 분석 기준을 조직 표준으로 통일 |
프로그레시브 딜리버리(Progressive Delivery): 새 버전을 전체가 아닌 일부 트래픽에 먼저 노출한 뒤, 메트릭 기반으로 안전성을 검증하며 점진적으로 확대하는 배포 전략. 카나리 배포는 그 대표적인 구현 방식이다.
전체 아키텍처 구조
MetricTemplate이 실제로 작동하려면 트래픽을 분할하는 레이어가 필요하다. Flagger 자체는 판단 로직만 담당하고, 실제 트래픽 라우팅은 Istio·Linkerd·NGINX 같은 도구가 수행한다.
[개발자] → Git 커밋 → [Flux CD] → Kubernetes 적용
↓
[Flagger 오퍼레이터]
↙ ↘
[Istio/NGINX] [MetricTemplate]
트래픽 분할 APM 쿼리 실행
↓ ↓
카나리 Pod Datadog / New Relic
↘ ↙
판단: 프로모션 or 롤백서비스 메시(Service Mesh): Istio, Linkerd 같은 도구로, Pod 간 트래픽을 가로채 라우팅·관찰·보안을 제어하는 인프라 레이어. Flagger의 카나리 분석은 이 레이어의 트래픽 분할 능력에 의존한다.
실전 적용
세 가지 예시를 다룬다. 예시 1은 Istio 서비스 메시를 사용하는 환경에서 Datadog으로 메시 레이어 메트릭을 분석하는 방법이고, 예시 2는 NGINX Ingress를 사용하는 환경에서 New Relic으로 인그레스 레이어 메트릭을 분석하는 방법이다. 두 APM이 서로 다른 레이어에 특화된 이유를 예시 사이에서 설명한다. 예시 3은 하나의 MetricTemplate을 여러 서비스에서 재사용하는 패턴이다. 자신의 환경에 맞는 예시부터 시작해도 좋다.
예시 1: Datadog 연동 — Istio 메시 레이어 404 에러율 기반 자동 롤백
전제: 이 예시는 Istio 서비스 메시를 사용하는 환경 기준이다.
istio.mesh.request.count메트릭은 Istio가 수집하는 메시 레이어 지표로, NGINX Ingress 환경에서는 동작하지 않는다. NGINX를 사용한다면 예시 2를 참고한다.
Datadog은 Istio 사이드카 프록시가 생성하는 메시 레이어 메트릭을 자동으로 수집한다. 이 레이어에서 측정된 에러율은 특정 서비스의 카나리 Pod에 정확히 귀속되기 때문에 배포 판단에 신뢰도가 높다.
Step 1 — API 키를 Kubernetes Secret으로 등록
# kubectl create secret 명령어 사용 (평문 노출 위험 없음)
kubectl create secret generic datadog \
--namespace istio-system \
--from-literal=datadog_api_key=여기에_실제_API_키 \
--from-literal=datadog_application_key=여기에_실제_APP_키또는 YAML로 직접 관리할 경우, echo -n "실제키값" | base64 명령으로 인코딩한 값을 사용한다.
apiVersion: v1
kind: Secret
metadata:
name: datadog
namespace: istio-system
type: Opaque
data:
datadog_api_key: <base64-encoded-api-key> # echo -n "키값" | base64
datadog_application_key: <base64-encoded-app-key>Step 2 — MetricTemplate 정의
apiVersion: flagger.app/v1beta1
kind: MetricTemplate
metadata:
name: not-found-percentage
namespace: istio-system
spec:
provider:
type: datadog
address: https://api.datadoghq.com
secretRef:
name: datadog
query: |
100 - (
sum:istio.mesh.request.count{
reporter:destination,
destination_workload_namespace:{{ namespace }},
destination_workload:{{ target }},
!response_code:404
}.as_count()
/
sum:istio.mesh.request.count{
reporter:destination,
destination_workload_namespace:{{ namespace }},
destination_workload:{{ target }}
}.as_count()
) * 100| 쿼리 요소 | 역할 |
|---|---|
{{ namespace }} |
Canary가 속한 네임스페이스로 자동 치환 |
{{ target }} |
카나리 대상 워크로드 이름으로 자동 치환 |
!response_code:404 |
404가 아닌 요청만 카운트 (정상 요청) |
100 - (정상/전체 * 100) |
결과적으로 404 에러율(%) 반환 |
Step 3 — Canary에서 MetricTemplate 참조
apiVersion: flagger.app/v1beta1
kind: Canary
metadata:
name: my-app
namespace: production
spec:
# targetRef, service 섹션 등 필수 필드는 생략됨 — 전체 스펙은 공식 문서 참고
analysis:
interval: 1m # 1분마다 MetricTemplate 쿼리 실행
threshold: 5 # 5번 연속 분석 실패 시 롤백 트리거
maxWeight: 50 # 카나리 트래픽 최대 50%까지 증가
stepWeight: 10 # 분석 성공 1회당 트래픽 10%씩 증가
metrics:
- name: "not-found-percentage"
templateRef:
name: not-found-percentage
namespace: istio-system # 다른 네임스페이스의 MetricTemplate 참조
thresholdRange:
max: 5 # 404 에러율 5% 초과 시 해당 분석 실패 판정
interval: 1mYAML 값 선택 기준:
threshold: 5는 "일시적 스파이크를 롤백으로 오해하지 않도록 5번 연속 실패 시에만 롤백"을 의미한다. 안정성이 중요한 결제 서비스라면threshold: 3으로 낮추고, 실험적 기능이라면threshold: 7로 높일 수 있다.stepWeight: 10은 5분마다 10%씩 증가하여 50%까지 총 5단계 검증을 의미한다. 배포 속도가 중요하다면stepWeight: 20으로 조정하되, 검증 단계가 줄어드는 트레이드오프를 인식해야 한다.
thresholdRange:
max만 지정하면 "이 값 이하여야 정상",min만 지정하면 "이 값 이상이어야 정상", 둘 다 지정하면 범위 내에 있어야 정상으로 판단한다. 성공률에는min, 에러율에는max를 사용하는 것이 일반적이다.
크로스 네임스페이스 참조와 RBAC:
templateRef에서 다른 네임스페이스의 MetricTemplate을 참조할 경우, Flagger 오퍼레이터의 ServiceAccount에 해당 네임스페이스의 MetricTemplate과 Secret을 읽을 수 있는 ClusterRole이 필요할 수 있다. 크로스 네임스페이스 접근이 안 된다면 Flagger 파드 로그에서 RBAC 관련 에러를 먼저 확인한다.
동작 확인 방법
# Canary 오브젝트 상태 확인
kubectl describe canary my-app -n production
# 분석 관련 이벤트 스트림 확인
kubectl get events -n production --field-selector reason=Synced
# Flagger 오퍼레이터 로그에서 MetricTemplate 쿼리 결과 확인
kubectl logs -n flagger-system deploy/flagger -f | grep "not-found-percentage"예시 2: New Relic 연동 — NGINX 인그레스 레이어 HTTP 5xx 에러율 분석
Datadog이 메시 레이어(서비스 간 트래픽)에 강점이 있다면, New Relic은 NRQL이라는 유연한 쿼리 언어 덕분에 인그레스 레이어(클라이언트 → 클러스터 진입점)를 측정하는 시나리오에 잘 맞는다. NGINX Ingress를 사용하는 팀에게 더 자연스러운 선택이다.
NRQL 쿼리 검증 권고: 아래 쿼리는
FROM Metric WHERE metricName = 'nginx_ingress_controller_requests'형태를 사용한다. 환경에 따라FROM nginx_ingress_controller_requests형태의 이벤트 타입 직접 지정이 더 일반적일 수 있다. 반드시 New Relic Query Builder에서 직접 실행하여 예상 범위의 값이 반환되는지 확인한 뒤 MetricTemplate에 적용할 것을 강력히 권장한다.
Step 1 — New Relic 자격 증명 Secret 등록
kubectl create secret generic newrelic \
--namespace ingress-nginx \
--from-literal=newrelic_account_id=여기에_계정_ID \
--from-literal=newrelic_query_key=여기에_쿼리_키Step 2 — NRQL MetricTemplate 정의
apiVersion: flagger.app/v1beta1
kind: MetricTemplate
metadata:
name: newrelic-error-rate
namespace: ingress-nginx
spec:
provider:
type: newrelic
secretRef:
name: newrelic
query: |
SELECT
filter(sum(nginx_ingress_controller_requests), WHERE status >= '500')
/ sum(nginx_ingress_controller_requests) * 100
FROM Metric
WHERE metricName = 'nginx_ingress_controller_requests'
AND ingress = '{{ ingress }}'
AND namespace = '{{ namespace }}'여기서 {{ ingress }}는 표준 Flagger 내장 변수가 아니라 사용자 정의 변수다. 이 값은 다음 단계의 templateVariables를 통해 각 서비스가 주입한다.
예시 3: templateVariables로 하나의 템플릿을 여러 서비스에 재사용
templateVariables는 Flagger v1.12.0 이상에서 지원하는 기능으로, 동일한 MetricTemplate을 서비스별로 파라미터화해서 공유할 수 있게 한다. 위의 newrelic-error-rate 템플릿을 서로 다른 두 서비스에서 각각 다른 ingress 이름으로 사용하는 예시다.
# 서비스 A의 Canary
apiVersion: flagger.app/v1beta1
kind: Canary
metadata:
name: service-a
namespace: production
spec:
analysis:
metrics:
- name: "newrelic-error-rate"
templateRef:
name: newrelic-error-rate
namespace: ingress-nginx
templateVariables:
ingress: service-a-ingress # 서비스 A의 ingress 이름 주입
thresholdRange:
max: 1 # 5xx 에러율 1% 초과 시 실패 판정
interval: 2m# 서비스 B의 Canary — 동일 템플릿, 다른 변수와 임계값
apiVersion: flagger.app/v1beta1
kind: Canary
metadata:
name: service-b
namespace: production
spec:
analysis:
metrics:
- name: "newrelic-error-rate"
templateRef:
name: newrelic-error-rate
namespace: ingress-nginx
templateVariables:
ingress: service-b-ingress # 서비스 B의 ingress 이름 주입
thresholdRange:
max: 2 # 서비스 B는 임계값을 다르게 설정
interval: 2m이 패턴의 실무 가치는 크다. 플랫폼 팀이 MetricTemplate을 중앙 네임스페이스에 한 번 정의하면, 각 서비스 팀은 templateVariables와 thresholdRange만 조정해서 조직 표준 분석 기준을 그대로 따를 수 있다. 쿼리 로직의 변경이 필요할 때도 MetricTemplate 하나만 수정하면 모든 서비스에 즉시 반영된다.
장단점 분석
장점
| 항목 | 내용 |
|---|---|
| 기존 APM 즉시 활용 | 이미 계약·운영 중인 Datadog·New Relic을 배포 판단 기준으로 바로 연결 — 별도 메트릭 스택 구축 불필요 |
| 조직 표준화 | MetricTemplate을 공유 네임스페이스에 두면 팀·서비스 간 분석 기준 통일 — 배포 기준이 구두 규약이 아닌 코드가 됨 |
| 완전 자동화 | 사람이 대시보드를 지켜보지 않아도 메트릭 기반으로 프로모션·롤백 자동 결정 — 야간 배포 부담 감소 |
| GitOps 친화적 | MetricTemplate·Canary 스펙 모두 YAML로 관리되어 PR 리뷰·변경 이력·롤백이 Git 워크플로 안에서 처리됨 |
| 다중 메트릭 AND 조건 | 에러율 + P99 레이턴시 + 비즈니스 전환율 등 복수 기준을 동시에 만족해야만 프로모션 진행 |
| Flux CD 생태계 통합 | Flux가 Git 변경을 감지해 Kubernetes에 적용하면, Flagger가 자동으로 카나리 분석을 시작하는 완전 자동화 파이프라인 구성 가능 |
단점 및 주의사항
| 항목 | 내용 | 대응 방안 |
|---|---|---|
| 단순 임계값 비교 | 트래픽이 적을 때 통계적 신뢰도 없이 threshold만 비교하므로 오판 가능 | 충분한 트래픽을 카나리에 유도하고, interval을 길게 설정해 데이터를 충분히 축적 |
| L7 트래픽 분할 필수 | Istio, Linkerd, NGINX 등 서비스 메시나 인그레스 없이는 카나리 자체가 불가 | 트래픽 관리 레이어 먼저 구축 후 Flagger 도입 |
| APM API 호출 비용 | interval마다 Datadog·New Relic API 쿼리 실행 — 짧은 간격에서 비용 누적 가능 |
interval을 너무 짧게 설정하지 말 것 (최소 1m 권장) |
| 쿼리 오류 늦은 발견 | MetricTemplate 쿼리 오류는 카나리 분석 시점에 드러남 | APM 콘솔에서 쿼리를 먼저 검증한 뒤 적용 |
| 크로스 네임스페이스 Secret 제한 | secretRef는 기본적으로 동일 네임스페이스만 참조 가능 |
MetricTemplate과 Secret을 같은 네임스페이스에 배치 |
| 콜드 스타트 오분석 | 카나리 초기에는 메트릭 데이터 부족으로 분석 신뢰도 저하 | spec.analysis.iterations으로 초기 워밍업 구간 설정, progressDeadlineSeconds·canaryReadyThreshold를 조정해 Pod 안정화 후 분석 시작 |
콜드 스타트(Cold Start): 카나리 Pod가 막 뜬 시점에는 APM에 메트릭 데이터가 거의 없다. 이 상태에서 분석을 시작하면 정상 서비스가 비정상으로 오판될 수 있다.
spec.analysis.iterations으로 초기 분석 횟수를 건너뛰거나,canaryReadyThreshold를 설정해 Pod 준비 상태를 확인한 뒤 분석이 시작되도록 구성하는 것이 실무에서 권장된다.
실무에서 가장 흔한 실수
- 쿼리 사전 검증 생략: MetricTemplate을 배포하고 실제 카나리 분석이 돌 때서야 쿼리 문법 오류나 빈 결과값을 발견하는 경우. Datadog Metrics Explorer 또는 New Relic Query Builder에서 동일 쿼리를 직접 실행해 예상 범위의 값이 반환되는지 먼저 확인해야 한다. 쿼리 오류는 Flagger가 "메트릭 값을 읽을 수 없음"으로 처리하며, 이것이 즉시 롤백으로 이어질 수 있다.
- 단일 메트릭에만 의존: 에러율 하나만으로 판단하면 에러는 없지만 P99 레이턴시가 치솟는 케이스를 놓친다.
analysis.metrics배열에 에러율 + P99 레이턴시를 함께 등록하면 두 기준 모두 만족해야만 프로모션이 진행된다. 가능하면 비즈니스 전환율 메트릭도 추가하는 것이 가장 안전하다. - 너무 관대한 초기 임계값: "일단 빠르게 배포하자"는 생각으로
max: 20처럼 임계값을 느슨하게 설정하고, 실제 장애 상황에서 롤백이 발동하지 않는 경우. 처음에는max: 1처럼 보수적으로 시작해 운영 데이터를 쌓으면서 점진적으로 완화하는 것이 올바른 순서다.
마치며
Flagger MetricTemplate CRD는 이미 조직에 있는 APM 투자를 배포 안전망으로 바꿔주는 가장 직접적인 방법이다. 이 패턴을 팀에 도입하면 야간 배포 알람이 줄고, "배포가 안전한지 30분 지켜보는" 시간이 자동화된 분석으로 대체된다. 배포 승인 사이클이 짧아지고, 플랫폼 팀이 중앙 MetricTemplate을 관리함으로써 각 서비스 팀은 임계값 조정에만 집중할 수 있게 된다.
지금 바로 시작할 수 있는 3단계:
- APM 콘솔에서 쿼리 먼저 검증: Datadog이라면 Metrics Explorer, New Relic이라면 Query Builder에서 카나리 Pod의 에러율을 반환하는 쿼리를 직접 작성하고 예상 범위 확인 — MetricTemplate 적용 전 이 단계는 필수다.
- MetricTemplate 단독 배포 후 파이프라인 연결:
kubectl apply -f metric-template.yaml로 템플릿을 먼저 배포하고, 기존 Canary 오브젝트에templateRef만 추가해 점진적으로 전환 —kubectl describe canary <이름>으로 분석 결과를 실시간 확인. - 복수 메트릭 조합으로 안전망 강화: 에러율 MetricTemplate이 정상 동작하면, P99 레이턴시 MetricTemplate을 추가해
analysis.metrics배열에 병렬 등록 — 두 기준 모두 만족해야 프로모션이 진행되는 다중 안전망 완성.
다음 글: Flagger + Istio 환경에서 HTTP 헤더 기반 A/B 라우팅 YAML을 설정하고, New Relic NRQL로 전환율·세션 길이 같은 비즈니스 메트릭을 분석 기준으로 연동
참고 자료
- Flagger 공식 문서 - Metrics Analysis | flagger.app
- Flux CD - Flagger Metrics Analysis | fluxcd.io
- fluxcd/flagger GitHub - metrics.md 소스
- fluxcd/flagger GitHub - CRD 정의
- How to Configure Flagger Metrics Analysis with Datadog | OneUptime
- Canary analysis metrics templating - Issue #418 | GitHub
- MetricTemplate secretRef cross-namespace - Issue #716 | GitHub
- Canary deployments with Amazon Managed Prometheus and Flagger | AWS Open Source Blog
- Mastering Progressive Delivery with Istio and Flagger | Medium
- Progressive Delivery: Argo Rollouts vs Flagger | Medium