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

이 페이지는 Argo CD v3.2에서 v3.3으로 업그레이드할 때 알아야 할 변경 사항(breaking changes)을 정리합니다. ApplicationSet CRD의 서버 사이드 apply 필요성, 소스 하이드레이터의 git notes 사용 방식, Helm/Kustomize 버전 업그레이드 등이 핵심입니다.

출처: 문서

본문

v3.2 → 3.3

Breaking Changes

ApplicationSet CRD가 클라이언트 사이드 apply 크기 제한을 초과합니다

이 버전에서는 ApplicationSet CRD가 클라이언트 사이드 apply의 크기 제한을 초과합니다. 즉, 이전 업그레이드 방식은 The CustomResourceDefinition "applicationsets.argoproj.io" is invalid: metadata.annotations: Too long: may not be more than 262144 bytes 오류로 끝납니다.

이 문제를 피하려면 이제 resolve conflicts와 함께 서버 사이드 apply(SSA)를 사용해 Argo CD를 업그레이드해야 합니다. SSA는 ApplicationSet 필드를 last-applied 어노테이션에 저장하지 않으므로 어노테이션 크기 제한의 영향을 받지 않습니다. --force-conflicts 플래그는 이전에 다른 도구(Helm 또는 이전 kubectl apply 등)가 관리했을 수 있는 필드에 apply 작업이 소유권을 가져갈 수 있게 합니다. 업그레이드에는 이 플래그가 필요합니다. Argo CD 매니페스트에 정의된 필드(예: affinity, env, probes)에 직접 커스터마이즈한 내용은 덮어써진다는 점을 참고하세요. 다만 매니페스트에 지정되지 않은 필드(예: resources의 limits/requests 또는 tolerations)는 보존됩니다.

스스로를 관리하는 Argo CD 업그레이드하기

Argo CD Application으로 Argo CD를 업그레이드할 때는 Application 스펙에서 Server-Side Apply를 활성화해야 합니다:

  syncPolicy:
    syncOptions:
    - ServerSideApply=true

이 구성을 사용하면 Argo CD가 resolve conflicts 옵션을 자동으로 추가합니다.

Kustomize 또는 일반 매니페스트로 Argo CD 수동 업그레이드

일반 매니페스트 또는 Kustomize 오버레이로 Argo CD를 수동 업그레이드할 때는 --server-side --force-conflicts로 업그레이드해야 합니다. 예: kubectl apply -n argocd --server-side --force-conflicts -f manifests/install.yaml

Helm으로 Argo CD 수동 업그레이드

helm upgrade로 Argo CD를 수동 업그레이드하는 사용자는 이 변경의 영향을 받지 않습니다. Helm은 클라이언트 사이드 apply를 사용하지 않으며 last-applied 어노테이션을 생성하지 않기 때문입니다.

이전에 3.3.0 또는 3.3.1로 업그레이드한 사용자

어떤 경우에는 해당 버전 중 하나로 업그레이드하고 Server-Side Apply를 적용한 뒤 다음 오류가 발생했습니다: one or more synchronization tasks completed unsuccessfully, reason: Failed to perform client-side apply migration: failed to perform client-side apply migration on manager kubectl-client-side-apply: error when patching "/dev/shm/2047509016": CustomResourceDefinition.apiextensions.k8s.io "applicationsets.argoproj.io" is invalid: metadata.annotations: Too long: may not be more than 262144 bytes.

위 오류에 대한 임시 수정으로 ClientSideApplyMigration=false sync 옵션을 구성한 사용자는 3.3.2로 업그레이드한 뒤 이를 제거해야 합니다. ClientSideApplyMigration을 비활성화하면 향후 K8s 필드 매니저 간 충돌이 발생할 위험이 있습니다.

소스 하이드레이터가 이제 git notes로 하이드레이션 상태를 추적합니다

기존에는 Argo CD의 소스 하이드레이터(Source Hydrator)가 매니페스트 파일(manifest.yaml)이 실제로 변경되었는지와 무관하게 모든 DRY(소스) 커밋마다 새로운 하이드레이션 커밋을 푸시했습니다. 하이드레이터가 마지막으로 하이드레이션한 DRY 커밋을 추적하기 위해 필요했습니다. 즉, 각 하이드레이션 커밋의 hydrator.metadata 파일 drySha 필드에 이 정보를 임베딩했습니다.

v3.3부터 소스 하이드레이터는 모든 DRY 커밋에 하이드레이션 커밋을 생성하는 대신 git notes를 사용해 가장 최근에 하이드레이션한 DRY 커밋의 상태를 기록합니다. git note는 소스 하이드레이터 전용으로 예약된 네임스페이스에 저장되어, 상태가 신뢰할 수 있고 다른 저장소 작업과 격리됩니다.

이 설계 변경은 저장소의 청결성을 높이고 불필요한 커밋 노이즈를 줄이며, 빈번한 자동 커밋으로 인한 과도한 브랜치 분기 위험을 낮춥니다.

동작 방식

각 하이드레이션 실행 시:
하이드레이터는 먼저 네임스페이스의 기존 git note를 가져와 마지막으로 하이드레이션한 DRY 커밋 SHA를 확인합니다.
note SHA가 최신 DRY SHA와 일치하면 하이드레이터는 디버그 메시지를 기록하고 하이드레이션을 건너뜁니다.
manifest.yaml 같은 파일이 변경되지 않았다면(DRY SHA가 새로워도) 하이드레이터는 매니페스트 커밋을 건너뛰고 최신 하이드레이션 DRY SHA를 반영하도록 git note만 업데이트합니다.
매니페스트 파일이 변경되었다면 하이드레이터는 업데이트된 매니페스트를 커밋하고 git note도 업데이트합니다.

마이그레이션 영향

동작(Behavioral):
사용자는 더 이상 모든 DRY 커밋에 대한 하이드레이션 커밋을 보지 못합니다. 실제 매니페스트 변경이 있을 때만 새 커밋이 생성되고, 그 외에는 하이드레이션 상태가 git note 네임스페이스에 추적됩니다.
운영(Operational):
모든 DRY 커밋마다 하이드레이션 커밋에 의존했던 애플리케이션과 도구는 이제 소스 하이드레이터 네임스페이스의 git note를 사용해 하이드레이션 상태를 판단해야 합니다.
대부분의 사용자에게는 조치가 필요 없지만, 하이드레이션 커밋을 신호로 사용하는 자동화가 있다면 새 git note를 참고하도록 업데이트하세요.

근거와 이점

저장소 클러터를 줄입니다: 불필요한 커밋이 줄어듭니다.
DRY 변경이 빈번하고 매니페스트 변경이 드문 팀의 성능을 개선합니다.
자동화 시나리오에서 병합 충돌과 브랜치 비대화 위험을 낮춥니다.

하이드레이션 중 Application 경로 정리 제거

동작 변경: v3.3 이전 Argo CD 버전에서는 소스 하이드레이터가 각 하이드레이션 실행 시 새 매니페스트 파일을 쓰기 전에 Application의 구성된 경로를 자동으로 정리(그 경로의 모든 파일 삭제)했습니다. v3.3부터 이 정리 로직이 제거되었습니다. 이제 하이드레이터는 현재 매니페스트 출력에 해당하는 파일만 덮어쓰거나 생성하며, 애플리케이션 경로의 추가 파일이나 오래된 데이터는 명시적으로 덮어쓰지 않는 한 그대로 남습니다.
운영 영향: 저장소나 자동화가 애플리케이션 경로의 오래되거나 사용하지 않는 파일의 자동 정리에 의존했다면, 이제 이 정리를 직접 처리해야 합니다. 이 변경은 관련 없는 파일(예: 애플리케이션 경로가 다른 자산이 있는 디렉터리와 겹치거나, 애플리케이션이 재구성된 경우)이 실수로 삭제될 위험을 방지합니다.
권장 조치: 애플리케이션 경로의 오래되거나 불필요한 파일이 필요에 따라 정리되도록 자동화 워크플로우와 저장소 유지보수 스크립트를 검토하세요. 사용 사례에 따라 주기적인 수동 또는 자동 정리 절차를 도입하는 것을 고려하세요.
현재 동작에 대한 자세한 내용은 소스 하이드레이터 사용자 가이드를 참고하세요.

Settings API 익명 호출이 더 적은 필드를 반환합니다

Settings API는 이제 익명으로 접근할 때 더 적은 정보를 반환합니다. 민감한 정보로 간주되는 resourceOverrides 필드를 더 이상 반환하지 않습니다.

K8s API 요청의 서버 사이드 타임아웃을 제어하는 새 환경 변수

새 환경 변수 ARGOCD_K8S_SERVER_SIDE_TIMEOUT를 사용해 API 요청의 K8s 서버 사이드 타임아웃을 제어할 수 있습니다. 이 변경 이전(3.2 및 이전)에는 K8s 서버 사이드 타임아웃이 ARGOCD_K8S_TCP_TIMEOUT로 제어되었는데, 이 변수는 K8s API 서버와 통신할 때 TCP 타임아웃도 함께 제어했습니다. 이제부터 Kubernetes 서버 사이드 타임아웃은 별도의 환경 변수로 제어됩니다.

--self-heal-backoff-cooldown-seconds 플래그 폐기

argocd-application-controller의 --self-heal-backoff-cooldown-seconds 플래그가 폐기되었으며 향후 릴리스에서 제거될 예정입니다.

Helm이 3.19.2로 업그레이드됨

Argo CD v3.3은 번들된 Helm 버전을 3.19.2로 업그레이드합니다. 릴리스 노트에 따르면 Helm 3.19.2에는 breaking change가 없습니다.

helm version 호출에서 --client 플래그를 제거함에 따라 Helm 2.x는 더 이상 지원되지 않습니다.

Kustomize가 5.8.0으로 업그레이드됨

Argo CD v3.3은 번들된 Kustomize 버전을 v5.7.0에서 v5.8.0으로 업그레이드합니다. 5.7.1 및 5.8.0 릴리스 노트에 따르면 breaking change는 없습니다.

다만 Kustomize 5.7.1은 exec 플러그인의 인자 파싱에 사용되던 shlex 라이브러리를 대체하는 코드를 도입합니다. 기존 매니페스트가 손상되면 5.7.1 릴리스 노트의 지침을 따르세요.

Kustomize 5.8.0은 또한 네임스페이스가 Helm 차트에 제대로 전파되지 않던 문제를 해결합니다. kustomization 파일 내에서 Helm 차트를 사용한다면 관련 수정 사항(kubernetes-sigs/kustomize#5940)의 세부 내용을 검토하세요.

추가된 헬스체크

ceph.rook.io/CephCluster
ceph.rook.io/CephObjectStore
objectbucket.io/ObjectBucketClaim
keda.sh/ScaledJob
services.cloud.sap.com/ServiceBinding
services.cloud.sap.com/ServiceInstance
.cnrm.cloud.google.com/
grafana-org-operator.kubitus-project.gitlab.io/_

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