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

이 페이지는 Argo CD v3.4에서 v3.5로 업그레이드할 때 알아야 할 변경 사항(breaking changes)을 정리합니다. Helm 4 업그레이드와 일반 HTTP OCI 레지스트리 처리, React 19 UI 확장, 가장(personation) 확장, GnuPG 서명 검증의 Source Integrity 대체 등이 핵심입니다.

출처: 문서

본문

v3.4 → 3.5

Breaking Changes

Helm이 4.2.0으로 업그레이드되었습니다

Helm v4에서 OCI 구현은 더 엄격합니다. 레지스트리가 TLS를 지원하지 않으면 helm push, helm registry login, helm dependency build 시 명시적으로 --plain-http를 사용해야 합니다.

이것은 일반 HTTP OCI 레지스트리를 사용하는 Argo CD 사용자에게 breaking change입니다. 두 가지 조치가 필요할 수 있습니다.

기존 OCI 저장소에 --insecure-oci-force-http 설정

일반 HTTP(HTTPS가 아닌)를 사용하는 기존 OCI 저장소에는 CLI(CLI 버전 3.5)로 플래그를 추가하세요: repo add ... --insecure-oci-force-http --upsert. 또는 Kubernetes 시크릿에서 직접 설정할 수 있습니다:

stringData:
   insecureOCIForceHttp: "true"

일반 HTTP 의존성 저장소를 명시적으로 등록

Helm 차트에 일반 HTTP 레지스트리에서 호스팅되는 OCI 의존성(Chart.yaml dependencies with repository: oci://...)이 있다면, 그 의존성 저장소를 위에서 설명한 것과 같은 방식으로 --insecure-oci-force-http 플래그와 함께 Argo CD에 명시적으로 추가해야 합니다. Helm v3에서는 필요하지 않았습니다. 일반 HTTP OCI 의존성 레지스트리는 등록 없이 투명하게 접근되었습니다. Helm v4에서는 helm dependency build에 --plain-http를 전달하기 위해 Argo CD가 어떤 의존성 레지스트리가 일반 HTTP를 사용하는지 알아야 합니다.

알려진 제한 — 충돌하는 TLS 플래그 (Helm v4)

Argo CD OCI 저장소에서 --insecure-skip-server-verification(Helm에 --insecure-skip-tls-verify로 전달)과 --insecure-oci-force-http(Helm에 --plain-http로 전달)를 모두 설정하면, --insecure-skip-tls-verify가 내부적으로 우선하므로 Helm v4가 --plain-http를 조용히 버립니다. 그러면 일반 HTTP 레지스트리 작업이 http: server gave HTTP response to HTTPS client로 실패합니다. 이는 다음에 영향을 줍니다:

--enable-oci가 있는 type=helm Argo CD 저장소: 같은 저장소에 두 플래그가 모두 있으면 차트 풀(pull)이 실패합니다.
의존성이 있는 type=oci 및 type=helm Argo CD 저장소: 메인 저장소의 --insecure-skip-server-verification과 의존성 저장소의 --insecure-oci-force-http가 결합되면 의존성 빌드가 실패합니다.

같은 체인에서 두 구성이 모두 정당하게 요구되는 경우 우회 방법이 없습니다.

spec.source.helm.version 설정이 있는 Application

Helm 애플리케이션에 다음과 같은 설정이 과거에 있었다면 해당 설정은 무시되고 Argo CD는 차트 렌더링에 Helm v4만 사용합니다:

spec:
  source:
    helm:
      version: v3

이 필드를 업데이트하거나 제거할 필요는 없으며, 그대로 두어도 됩니다.

UI 확장은 react/jsx-runtime을 외부화해야 합니다

Argo CD UI가 3.5에서 React 16에서 React 19로 업그레이드되었습니다. 이전 Argo CD UI를 대상으로 빌드된 UI 확장은 react/jsx-runtime을 외부화하도록 다시 빌드할 때까지 TypeError로 로드에 실패할 수 있습니다.

호스트 UI는 실패를 다음과 같이 표시합니다:

Extension <name>.js failed to load: TypeError: Cannot read properties of undefined (reading '<prop>')

전체 수정 가이드는 UI 확장: React 19 업그레이드를 참조하세요.

UI 확장을 설치하지 않는 사용자는 조치가 필요 없습니다.

이벤트 목록 gRPC 메서드가 이제 Argo CD EventList 타입을 반환합니다

Argo CD 3.5는 이벤트 목록 API의 gRPC 응답 타입을 k8s.io.api.core.v1.EventList에서 Argo CD가 정의한 EventList 타입으로 변경합니다. 이는 Kubernetes 프로토타입 타입을 Argo CD의 공개 gRPC 표면에 직접 노출하지 않으면서 최신 Kubernetes 프로토버프 정의와 호환성을 유지하기 위한 것입니다.

영향을 받는 gRPC 메서드는:

application.ApplicationService/ListResourceEvents
applicationset.ApplicationSetService/ListResourceEvents
project.ProjectService/ListEvents

gRPC 클라이언트에 대한 영향

이 메서드를 호출하는 생성되거나 커스텀된 모든 gRPC 클라이언트는 Argo CD 3.5 서버와 함께 재생성하거나 업그레이드해야 합니다.

여기에는 영향을 받는 이벤트 목록 RPC를 직접 호출하는 모든 프로그램이나 스크립트가 포함됩니다. grpc-web 프로토콜을 사용하는 것은 이 변경에 대한 호환성 우회 방법이 아닙니다.

Argo CD CLI는 이러한 API를 사용하지 않으므로 영향을 받지 않습니다.

REST 클라이언트와 UI에 대한 영향

REST 엔드포인트와 경로는 변경되지 않습니다:

GET /api/v1/applications/{name}/events
GET /api/v1/applicationsets/{name}/events
GET /api/v1/projects/{name}/events

JSON 응답 본문은 계속 동일한 EventList 형태의 페이로드를 사용하므로, Argo CD UI와 이 엔드포인트를 JSON으로 소비하는 모든 REST 통합은 영향을 받지 않습니다.

OpenAPI / 스키마 참고

REST 경로와 JSON 페이로드는 동일하지만, 이 엔드포인트에 대해 생성되는 OpenAPI 스키마는 이제 io.k8s.api.core.v1.EventList 대신 Argo CD의 eventsEventList 정의를 사용합니다.

Argo CD의 OpenAPI 정의에서 REST 클라이언트를 생성한다면 이를 스키마 수준의 breaking change로 취급하고 업그레이드 중에 해당 클라이언트를 재생성하거나 업데이트하세요.

동작 개선 / 수정

가장(Impersonation)이 서버 작업으로 확장됨

가장이 활성화되면 이제 동기화 작업뿐 아니라 모든 API 서버 작업에 적용됩니다. 즉, UI나 API를 통해 트리거된 작업(로그 보기, 이벤트 나열, 리소스 삭제, 리소스 액션 실행 등)은 AppProject의 destinationServiceAccounts 구성에서 파생된 가장된 서비스 계정을 사용합니다.

기존에는 가장이 동기화 작업에만 적용되었습니다.

영향을 받는 작업과 필요한 권한:

작업	Kubernetes API 호출	필요한 RBAC 동사
리소스 가져오기	대상 리소스에 GET	get
리소스 패치	대상 리소스에 PATCH	get , patch
리소스 삭제	대상 리소스에 DELETE	delete
리소스 이벤트 목록	events에 LIST (core/v1)	list
pod 로그 보기	pods 및 pods/log에 GET	get
리소스 액션 실행	대상 리소스에 GET , CREATE , PATCH	get , create , patch

이 목록은 기본 제공 작업을 다룹니다. 커스텀 리소스 액션은 수행하는 Kubernetes API 호출에 따라 추가 권한이 필요할 수 있습니다.

가장이 활성화된 사용자는 destinationServiceAccounts에 구성된 서비스 계정이 이러한 작업에 대한 권한을 가지고 있는지 확인해야 합니다.

가장이 활성화되지 않은 사용자는 조치가 필요 없습니다.

자격 증명이 구성되지 않은 저장소에 SSH known_hosts가 이제 사용됩니다

Argo CD는 go-git을 v5.19.x로 업그레이드하여 SSH 호스트 키 검증을 더 엄격하게 했습니다. Argo CD가 관리하는 argocd-ssh-known-hosts-cm ConfigMap에 대한 호스트 키 검증이 계속 작동하도록(그리고 새 go-git에서 knownhosts: key mismatch 핸드셰이크 실패를 피하기 위해), Argo CD는 이제 명시적 자격 증명이 구성되지 않은 저장소에 대해 SSH 인증을 자체적으로 구성합니다.

기존에는 SSH 저장소 URL에 자격 증명이 없으면 repo 서버가 go-git이 기본 인증 빌더로 대체하도록 두었습니다. 이 빌더는 ssh-agent 기반 인증을 구성하고 repo-server 컨테이너 안의 ~/.ssh/known_hosts(또는 $SSH_KNOWN_HOSTS)에서 known_hosts를 읽습니다. 이제 Argo CD는 동일한 ssh-agent 기반 인증을 직접 구성하되, 호스트 키 콜백을 argocd-ssh-known-hosts-cm ConfigMap에 연결하여 자격 증명이 구성된 저장소와 동일한 동작을 유지합니다.

이전에 repo server 이미지/파드가 자격 증명이 없는 SSH 저장소에 대해 커스텀 ~/.ssh/known_hosts(예: 커스텀 이미지에 내장하거나 볼륨으로 마운트)에 의존했다면, 그 호스트 키를 대신 argocd-ssh-known-hosts-cm에 추가하세요.

자격 증명이 구성된 SSH 저장소만 접근하거나 HTTPS 저장소만 접근하는 사용자는 조치가 필요 없습니다.

GnuPG 서명 검증이 Source Integrity로 대체됨

GnuPG 키 검증 기능이 애플리케이션 소스의 무결성을 검증하는 더 다재다능한 하위 시스템인 Source Integrity로 대체되었습니다.

마이그레이션 세부 사항은 Upgrade to Source Integrity Verification 섹션을 참조하세요.

레거시 구성은 마이그레이션을 용이하게 하기 위해 잠시 동안 계속 작동합니다(경고를 표시).

GnuPG 서명 검증을 사용하지 않는 사용자는 조치가 필요 없습니다.

API 변경

보안 변경

폐기 항목

GnuPG 서명 구성

argocd proj add-signature-key 및 argocd proj remove-signature-key를 사용한 프로젝트 서명 키 수정은 폐기되었습니다.
AppProject에서 .spec.signatureKeys를 선언하는 것은 폐기되었습니다.
대신 AppProject YAML에서 sourceIntegrity를 구성하세요.

GnuPG 서명 검증 결과

REST API의 verifyResult에서 GnuPG 검증 결과를 읽는 것은 폐기되었습니다.
대신 sourceIntegrityResult 필드에서 구조화된 결과를 사용하세요.

Kustomize 업그레이드

Helm 업그레이드

Helm이 4.2.1로 업그레이드되어, 이 문서의 Breaking changes 섹션에 설명된 몇 가지 breaking change가 발생했습니다.

추가된 커스텀 헬스체크

기타 변경 사항

릴리스 sbom.tar.gz 내용

일반 GitHub 릴리스에서 sbom.tar.gz에는 여전히 bom-go-mod.spdx(Go 의존성, spdx-sbom-generator의 tag-value SPDX)와 bom-docker-image.spdx(게시된 릴리스 이미지, sigs.k8s.io/bom의 tag-value SPDX)가 포함됩니다. UI 의존성 목록은 이제 bom-ui-pnpm.spdx.json입니다. pnpm sbom의 SPDX 2.3 JSON으로, spdx-sbom-generator의 이전 tag-value ./ui 출력을 대체합니다.

*.spdx 파일만 보던 도구로 이 아카이브를 사용한다면 bom-ui-pnpm.spdx.json도 처리하도록 확장하거나, 고정된 내부 파일 목록에 의존하지 않고 argocd-sbom.intoto.jsonl을 사용해 sbom.tar.gz를 검증하세요.

repo-server의 mTLS 지원

mTLS는 선택 사항(opt-in)이며 기본적으로 비활성화되어 있습니다. 구성하지 않는 운영자는 조치가 필요 없습니다.

mTLS를 활성화하려면 다음 키로 argocd-repo-server-mtls 시크릿을 생성하세요:

apiVersion: v1
kind: Secret
metadata:
  name: argocd-repo-server-mtls
  namespace: argocd
type: Opaque
stringData:
  client-ca.crt: |
    <PEM-encoded CA certificate that signed the client certs>
  client.crt: |
    <PEM-encoded shared client certificate>
  client.key: |
    <PEM-encoded private key for the shared client certificate>

시크릿은 관련 모든 파드의 /app/config/reposerver/mtls에 자동으로 마운트됩니다. 모든 컴포넌트는 기본적으로 그 마운트 경로에서 인증서/키/CA 파일을 읽으므로, 시크릿이 존재하는 순간 mTLS가 자동으로 활성화됩니다. ConfigMap 변경, 플래그 재정의 또는 추가 구성이 필요하지 않습니다.

핵심 사항:

repo 서버(서버 측):
--client-ca-path 기본값은 /app/config/reposerver/mtls/client-ca.crt(자동 마운트된 시크릿 경로)입니다. 파일이 존재하면 mTLS가 활성화되고, 없으면 조용히 건너뜁니다.
--disable-tls와는 함께 사용할 수 없습니다.
서버 TLS 인증서/키는 /app/config/reposerver/tls/tls.crt 및 /app/config/reposerver/tls/tls.key에서 로드됩니다.
클라이언트(argocd-server, application-controller, applicationset-controller, notifications-controller):
--repo-server-client-cert-path 기본값은 /app/config/reposerver/mtls/client.crt입니다. 파일이 없으면 mTLS 클라이언트 인증서는 건너뜁니다.
--repo-server-client-cert-key-path 기본값은 /app/config/reposerver/mtls/client.key입니다. 파일이 없으면 mTLS 클라이언트 인증서는 건너뜁니다.
--repo-server-ca-cert-path는 선택 사항이며, repo-server의 서버 인증서가 커스텀 CA로 서명된 경우 사용됩니다.

운영 참고:

repo-server에서 mTLS가 활성화되면 자체 liveness 자체 점검을 위한 임시 클라이언트 인증서를 자동으로 생성합니다. 프로브를 수정할 필요가 없습니다.
위 모든 설정에 대해 동등한 환경 변수와 argocd-cmd-params-cm ConfigMap 키가 존재합니다. 이름과 예시는 링크된 문서를 참조하세요.

전체 설정 방법, 컴포넌트별 인증서 옵션, 검증 단계, 문제 해결은 전용 mTLS 문서를 참조하세요.

--repo-server-strict-tls 플래그 (--repo-server-ca-cert-path로 대체되어 폐기됨)

--repo-server-strict-tls 불리언 플래그가 모든 컴포넌트에서 폐기되었습니다:

argocd-server
argocd-application-controller
argocd-applicationset-controller
argocd-notification

폐기 이유: 기존 플래그는 암시적 동작(/app/config/server/tls/에서 임베디드 인증서 자동 로드)을 사용하여 컴포넌트 간 일관성 유지가 어려웠습니다. 새 방식은 더 명시적이며 Kubernetes 시크릿 마운트 패턴과 일치합니다.

중요: 이 폐기는 TLS 기능에 영향을 주지 않습니다. 운영자는 새 플래그를 사용해 여전히 TLS 전용 연결(mTLS 없이)을 구성할 수 있습니다.

마이그레이션 가이드

폐기된 플래그는 3.5에서 계속 작동하지만(경고 표시), 새 방식으로 마이그레이션해야 합니다:

옵션 1: --repo-server-ca-cert-path로 마이그레이션 (권장)

폐기된 플래그를 명시적 CA 인증서 경로로 대체하세요:

# Before (3.4 and earlier):
argocd-server \
  --repo-server-strict-tls

# After (3.5):
argocd-server \
  --repo-server-ca-cert-path=/app/config/server/tls/ca.crt

Kubernetes 매니페스트:

# Before:
spec:
  containers:
  - name: argocd-server
    args:
    - argocd-server
    - --repo-server-strict-tls
    volumeMounts:
    - name: server-tls
      mountPath: /app/config/server/tls

# After:
spec:
  containers:
  - name: argocd-server
    args:
    - argocd-server
    - --repo-server-ca-cert-path=/app/config/server/tls/ca.crt
    volumeMounts:
    - name: server-tls
      mountPath: /app/config/server/tls

옵션 2: 환경 변수 사용 (대안)

플래그 대신 해당 환경 변수를 사용하세요:

# Before:
argocd-server --repo-server-strict-tls

# After:
export ARGOCD_SERVER_REPO_SERVER_CA_CERT_PATH=/app/config/server/tls/ca.crt
argocd-server

옵션 3: 폐기된 플래그 계속 사용 (권장하지 않음, 임시 전용)

플래그는 3.5에서 계속 작동하지만 폐기 경고를 표시합니다. 두 플래그를 함께 사용하는 것도 지원됩니다:

# This continues to work in 3.5 (but will show deprecation warning):
argocd-server \
  --repo-server-strict-tls \
  --repo-server-ca-cert-path=/app/config/server/tls/ca.crt

하위 호환성

두 플래그는 OR 의미로 함께 작동합니다. 둘 중 하나라도 true로 설정되면 엄격 검증이 활성화됩니다.
손실되는 기능이 없으며, TLS 검증 기능은 변경되지 않습니다.
새 플래그는 더 명시적이고 유지보수가 쉽습니다.

일정

v3.5: 폐기된 플래그가 여전히 작동합니다(경고 포함).
v3.6+: 플래그가 제거될 수 있습니다. 이에 맞춰 마이그레이션을 계획하세요.

영향을 받는 모든 컴포넌트(server, application-controller, applicationset-controller, notification-controller)는 동일한 마이그레이션 패턴을 따릅니다.

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