Argo CD 업그레이드 v3.3 → v3.4

Argo CD 업그레이드 v3.3 → v3.4

이 페이지는 Argo CD v3.3에서 v3.4로 업그레이드할 때 알아야 할 변경 사항(breaking changes)을 정리합니다. 클러스터 버전 형식 변경, 누락된 리소스의 헬스 상태 처리 방식, gRPC DNS 조회 기본 비활성화 등이 핵심입니다.

출처: 문서

본문

v3.3 → 3.4

Breaking Changes

클러스터 버전 형식 변경

새 동작:

3.4에서는 클러스터 버전을 이전 형식 Major.Minor 대신 좀 더 상세한 vMajor.Minor.Patch 형식으로 저장합니다.

이 변경은 ArgoCD가 K8s 클러스터 버전을 해석하는 방식을 Helm 3.19.0 이상이 해석하는 방식과 맞추는 것입니다.

이 변경으로 버전 비교가 쉬워지고 향후 기능을 지원할 수 있게 됩니다. 또한 더 정확한 버전 비교가 가능해지고 향후 Kubernetes 릴리스와의 호환성이 향상됩니다.

이 변경은 Argo CD 3.3.3에도 백포트되었습니다.

영향:

클러스터 생성기(Cluster Generators)를 사용하면서 클러스터의 Kubernetes 버전을 기준으로 클러스터를 가져오고 클러스터 시크릿에 argocd.argoproj.io/auto-label-cluster-info를 사용하는 ApplicationSet은, 기존 Major.Minor 형식 대신 vMajor.Minor.Patch 형식의 argocd.argoproj.io/kubernetes-version을 사용하도록 업데이트해야 합니다. 자세한 내용은 여기에서 확인할 수 있습니다.

또한 클러스터 정보를 조회하는 API, UI, CLI 명령어는 이제 버전을 vMajor.Minor.Patch 형식으로 반환합니다.

Argo CD CMP 플러그인과 함께 사용되는 환경 변수 $KUBE_VERSION은 변경되지 않으며 Major.Minor.Patch 형식으로 버전을 반환하므로 CMP 플러그인은 영향을 받지 않습니다.

동작 개선 / 수정

헬스 상태가 누락된 Application

Application 헬스 상태의 동작이 더 일관되고 유용하게 변경되었습니다. 기존에는 누락된 리소스에 내장 또는 커스텀 헬스체크가 정의되어 있는지에 따라 Application의 헬스 상태가 Missing으로 일관되지 않게 표시되었습니다.

새 동작:

  • Application은 모든 리소스가 누락된 경우에만(예: 첫 동기화 전) Missing 헬스를 표시합니다.
  • 개별 누락 리소스는 더 이상 Application의 전체 헬스 상태에 영향을 주지 않습니다.
  • 헬스 상태는 이제 존재하는 리소스의 집계 헬스를 반영합니다.
  • OutOfSync 상태가 이미 리소스 누락을 나타내므로, 개별 누락 리소스에 대한 헬스 상태는 중복입니다.
  • 존재하는 리소스에 대해 정의된 리소스 헬스체크가 명시적으로 Missing을 반환한다면, 그 결과는 여전히 전체 Application 헬스에 반영됩니다.

영향:

  • 일부 리소스가 누락된 Application은 이제 Missing 대신 존재하는 리소스의 헬스(예: Healthy, Progressing, Degraded)를 표시합니다.
  • 리소스 누락 감지에 Application 헬스 상태를 사용하던 자동화는 이제 동기화 상태에서 OutOfSync를 확인하고, 필요하다면 개별 리소스 헬스를 선택적으로 검사해야 합니다.
  • 사용자는 이제 한 번도 동기화되지 않은 Application(모든 리소스 누락 = Missing 헬스)과 일부 리소스가 삭제된 Application(남은 리소스의 헬스 표시)을 구분할 수 있습니다.

gRPC 서비스 구성 DNS 조회가 기본적으로 비활성화됨

ArgoCD 컴포넌트는 이제 듀얼 스택(IPv4+IPv6) Kubernetes 환경에서 과도한 DNS 쿼리와 타임아웃을 방지하기 위해 기본적으로 DNS TXT 레코드를 통한 gRPC 서비스 구성 조회를 비활성화합니다.

배경:

gRPC 클라이언트는 기본적으로 _grpc_config.<hostname>에 대한 DNS TXT 레코드를 쿼리하여 서비스 구성을 발견하려고 시도합니다. 듀얼 스택 환경에서는 이러한 조회가 과도한 DNS 쿼리와 타임아웃을 유발하여 repo-server 충돌과 동기화 실패를 일으킬 수 있습니다.

새 동작:

  • 모든 ArgoCD 컴포넌트에서 환경 변수 GRPC_ENABLE_TXT_SERVICE_CONFIG가 기본적으로 false로 설정됩니다.
  • 이로써 gRPC가 서비스 구성에 대한 DNS TXT 레코드 조회를 시도하지 않게 됩니다.
  • 대부분의 사용자는 gRPC 서비스 구성에 DNS TXT 레코드를 사용하지 않습니다.

영향:

  • 긍정적: 듀얼 스택 환경에서 과도한 DNS 쿼리를 없애 타임아웃을 방지하고 안정성을 개선합니다.
  • 최소한: 대다수의 사용자는 gRPC 서비스 구성에 DNS TXT 레코드를 사용하지 않으므로 기능 변화를 느끼지 못합니다.
  • 재활성화: DNS TXT 레코드를 통한 gRPC 서비스 구성을 실제로 사용하는 사용자는 argocd-cmd-params-cm ConfigMap에서 controller.grpc.enable.txt.service.config: "true" 파라미터를 설정해 이 기능을 다시 활성화할 수 있습니다.

필요한 경우 재활성화 예시:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cmd-params-cm
  namespace: argocd
data:
  controller.grpc.enable.txt.service.config: "true"

관련 이슈

https://github.com/argoproj/argo-cd/issues/24991

더 상세한 클러스터 버전

3.4.0은 클러스터 버전을 이전 형식 Major.Minor 대신 더 상세한 Major.Minor.Patch 형식으로 저장합니다. 이 변경은 버전 비교를 쉽게 하고 향후 기능을 지원하기 위한 것입니다. 또한 더 정확한 버전 비교와 향후 Kubernetes 릴리스와의 더 나은 호환성을 제공합니다.

사용자는 UI와 클러스터 정보를 조회하는 CLI 명령어에서 이를 확인할 수 있습니다.

API 변경

API 표면의 변경 사항: 필드 제거나 변경된 API 기본값

보안 변경

보안 동작의 변경 사항: 민감한 필드 제거 또는 변경된 인증 기본값

폐기 항목

향후 릴리스에서 제거될 플래그/동작, 그리고 폐기된 구성 API 또는 CLI 플래그

Kustomize 업그레이드

번들 Kustomize 버전 상향: breaking 동작, 특정 업스트림 동작 변경(예: 네임스페이스 전파 수정)에 대한 참고사항

Helm 업그레이드

번들 Helm 버전 상향: breaking 동작, 차트가 특정 Helm 버전에 묶인 기능에 의존하는지 확인

Dex 업그레이드

Argo CD v3.4는 번들된 Dex 버전을 2.45.0으로 업그레이드합니다. 릴리스 노트에 따르면 몇 가지 유의할 점이 있습니다.

  • Gomplate가 내부적으로 사용되지만, 전처리에 Dex를 구성한 사용자는 영향을 받을 수 있습니다.
  • ContinueOnConnectorFailure 기능 플래그가 이제 기본적으로 활성화됩니다. 비활성화하려면 argocd-cmd-params-cm ConfigMap 파라미터 dexserver.connector.failure.continue를 false로 설정하세요.

go-oidc 업그레이드

go-oidc v3.17.0은 토큰 검증 단계의 순서를 변경합니다.

이전 순서:

parse claims → signature

업데이트된 순서:

signature → parse claims

가능한 사용자 영향과 완화 방안

만료되었고 회전(rotation)으로 인해 JWKS에서 제거된 키로 서명된 토큰의 경우, 서명 검증 실패 시 사용자를 SSO로 리다이렉트하지 않습니다. 대신 사용자는 로그인 페이지로 리다이렉트되고 SSO 로그인을 수동으로 시작해야 합니다.

이 시나리오는 이전에 사용된 키를 토큰 수명을 초과하는 유예 기간 동안 제공하는 프로바이더 모범 사례를 구현하면 피할 수 있습니다.

Open Telemetry 업그레이드

Argo CD v3.4는 go.opentelemetry.io/otel을 1.42.0으로 업그레이드하며, 시맨틱 컨벤션은 v1.40.0 릴리스입니다. 변경된 메트릭 이름과 제거된 속성 목록은 시맨틱 컨벤션 릴리스 노트를 참조하세요. OTEL 기반 Argo CD Grafana 대시보드/알림을 수정해야 할 수 있습니다.

추가된 커스텀 헬스체크

  • nmstate.io/NodeNetworkConfigurationPolicy

더 알아보기 (Learn more)