업그레이드 가이드

원문 보기 위키 갱신 2026.10.03

업그레이드 가이드 (Upgrade Guide)

이 문서는 Flagger를 업그레이드하는 방법을 설명합니다. 특히 canaries v1alpha3에서 v1beta1로의 마이그레이션과 Istio 텔레메트리 v2 관련 변경 사항을 안내해 드릴게요.

출처: 문서

본문

이 문서는 Flagger를 업그레이드하는 방법을 설명합니다.

canaries v1alpha3에서 v1beta1로 업그레이드

canaries.flagger.app/v1beta1에서의 Canary CRD 변경 사항:

spec.canaryAnalysis 필드는 더 이상 사용되지 않으며 spec.analysis로 대체되었습니다
spec.analysis.interval 및 spec.analysis.threshold 필드는 필수입니다
status.lastAppliedSpec과 status.lastPromotedSpec 해싱 알고리즘이 hash/fnv로 변경되었습니다
spec.analysis.alerts 배열은 alertproviders.flagger.app/v1beta1 리소스를 참조할 수 있습니다
spec.analysis.metrics[].templateRef는 metrictemplate.flagger.app/v1beta1 리소스를 참조할 수 있습니다
metric.threshold 필드는 더 이상 사용되지 않으며 metric.thresholdRange로 대체되었습니다
metric.query 필드는 더 이상 사용되지 않으며 metric.templateRef로 대체되었습니다
spec.ingressRef.apiVersion은 networking.k8s.io/v1beta1을 허용합니다
spec.targetRef는 DaemonSet kind를 참조할 수 있습니다
spec.service.meshName 필드는 더 이상 사용되지 않으며 provider: appmesh:v1beta2에서 더 이상 사용되지 않습니다

업그레이드 절차:

v1beta1 CRD를 설치합니다
Flagger 배포를 업데이트합니다
모든 canary 매니페스트에서 apiVersion: flagger.app/v1alpha3을 apiVersion: flagger.app/v1beta1로 바꿉니다
모든 canary 매니페스트에서 spec.canaryAnalysis를 spec.analysis로 바꿉니다
클러스터의 canary 매니페스트를 업데이트합니다

참고 Flagger를 업그레이드한 후에는 변경 추적에 사용되는 해시 값이 다르게 계산되므로 모든 canary가 트리거됩니다. Flagger를 업그레이드하기 전에 모든 canary 매니페스트에서 spec.skipAnalysis: true를 설정하고, 업그레이드를 수행한 뒤 Flagger가 no-op 승격을 끝낼 때까지 기다린 다음 skipAnalysis를 false로 설정할 수 있습니다.

내장 메트릭을 업데이트합니다:

request-success-rate에 대해 threshold를 thresholdRange.min으로 바꿉니다
request-duration에 대해 threshold를 thresholdRange.max로 바꿉니다

metrics:
- name: request-success-rate
  thresholdRange:
    min: 99
  interval: 1m
- name: request-duration
  thresholdRange:
    max: 500
  interval: 1m

Istio 텔레메트리 v2

Istio 1.5는 Flagger 사용에 호환성이 깨지는 변경(breaking change)을 가져옵니다. Istio 텔레메트리 v2에서 메트릭 istio_request_duration_seconds_bucket은 제거되고 istio_request_duration_milliseconds_bucket으로 대체되어, request-duration 메트릭 검사가 깨집니다.

Istio 1.4를 사용한다면 다음과 같이 이전 duration 메트릭을 사용하는 메트릭 템플릿을 만들 수 있습니다:

apiVersion: flagger.app/v1beta1
kind: MetricTemplate
metadata:
  name: latency
  namespace: istio-system
spec:
  provider:
    type: prometheus
    address: http://prometheus.istio-system:9090
  query: |
    histogram_quantile(
        0.99,
        sum(
            rate(
                istio_request_duration_seconds_bucket{
                    reporter="destination",
                    destination_workload_namespace="{{ namespace }}",
                    destination_workload=~"{{ target }}"
                }[{{ interval }}]
            )
        ) by (le)
    )

canary 매니페스트에서 request-duration 메트릭을 latency로 바꿉니다:

metrics:
- name: latency
  templateRef:
    name: latency
    namespace: istio-system
  thresholdRange:
    max: 0.500
  interval: 1m

업그레이드 가이드