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

이 페이지는 Argo CD v3.1에서 v3.2로 업그레이드할 때 알아야 할 변경 사항(breaking changes)을 정리합니다. 소스 하이드레이션 경로 규칙, Kustomize 버전 지정 방식, CronJob 헬스체크 동작 변화 등이 포함되어 있습니다.

출처: 문서

본문

v3.1 → 3.2

대규모 모노레포를 운영하는 사용자는 pod 재시작이 필요한 repo-server 잠금 경합(lock contention)이 발생할 수 있습니다. 수정 사항이 검토 중이며 다음 패치 릴리스에 포함될 예정입니다.

Breaking Changes

하이드레이션 경로는 이제 루트가 아닌 경로여야 합니다

소스 하이드레이션(Source Hydrator)은 이제 모든 애플리케이션이 루트가 아닌 경로(non-root path)를 지정하도록 요구합니다. 저장소 루트(예: "" 또는 ".")를 사용하는 것은 더 이상 지원되지 않습니다. 이 변경은 하이드레이션 출력이 전용 하위 디렉터리에 격리되도록 보장하며, 루트에 저장된 CI 파이프라인, 문서, 설정 파일 같은 중요한 파일이 실수로 덮어써지거나 삭제되는 것을 방지합니다.

기존에는 하이드레이션 결과가 매니페스트를 저장소 루트에 직접 쓸 수 있었습니다. 편리하지만 두 가지 큰 단점이 있었습니다:

하이드레이션이 실행될 때마다 루트의 파일을 지우고 교체해서, CI/CD 워크플로우나 프로젝트 README, 기타 설정 같은 중요한 파일이 삭제될 위험이 있었습니다.
하이드레이션된 애플리케이션 출력을 저장소와 무관한 콘텐츠와 명확히 분리하기 어려웠습니다.

영향을 받는 애플리케이션을 찾으려면 Application 매니페스트에서 .spec.sourceHydrator.syncSource.path 값이 비어 있거나, 없거나, "."이거나 저장소 루트를 가리키는지 확인하세요. 이런 애플리케이션은 apps/guestbook 같은 하위 디렉터리 경로를 사용하도록 수정해야 합니다.

마이그레이션 후에는 저장소 루트에 이전 버전에서 남은 하이드레이션 출력이 있는지 확인하세요. 흔한 잔여물로는 manifest.yaml이나 README.md 같은 파일이 있습니다. 이것들은 자동으로 정리되지 않으므로, 더 이상 필요 없다면 직접 삭제해야 합니다.

Argo CD가 이제 .argocd-source.yaml에서 Kustomize 버전을 존중합니다

Argo CD는 .argocd-source.yaml 파일을 사용해 Application spec.source 값을 재정의하는 방법을 제공합니다.

Argo CD v3.2 이전에는 Application의 .spec.source.kustomize.version 필드에는 Kustomize 버전을 설정할 수 있었지만, .argocd-source.yaml 파일에는 설정할 수 없었습니다.

Argo CD v3.2부터는 다음과 같이 .argocd-source.yaml 파일에서 Kustomize 버전을 설정할 수 있습니다:

kustomize:
  version: v4.5.7

repo-server GRPC 서비스의 폐기(deprecated) 필드

repo-server의 GRPC 서비스는 일반적으로 내부 API로 간주되며 외부 클라이언트가 사용하는 것을 권장하지 않습니다. 사용자에게 보이는 서비스나 기능은 변경되지 않았습니다. 다만 repo-server의 GRPC 서비스를 직접 사용한다면 다음 메시지의 필드 폐기(deprecation) 사항을 참고하세요.

ManifestRequest와 RepoServerAppDetailsQuery 메시지의 kustomizeOptions.binaryPath 필드가 폐기되었습니다. 클라이언트가 올바른 바이너리 경로를 클라이언트 사이드에서 계산하는 대신, kustomizeOptions.versions 필드에 구성된 Kustomize 바이너리 경로를 채워 넣어야 합니다. 이를 통해 repo-server가 Application의 소스 필드에 구성된 Kustomize 버전과 git을 통해 구성된 재정의를 바탕으로 올바른 바이너리 경로를 선택할 수 있습니다.

kustomizeOptions.binaryPath는 kustomizeOptions.versions가 설정되지 않았을 때 계속 존중되지만, 권장되지는 않습니다. git을 통해 구성된 재정의가 무시되기 때문입니다. kustomizeOptions.binaryPath 필드는 향후 릴리스에서 제거될 예정입니다.

repo-server가 kustomizeOptions.binaryPath 필드가 설정된 요청을 받으면 다음과 같은 경고 메시지를 기록합니다:

kustomizeOptions.binaryPath는 폐기되었습니다. 대신 KustomizeOptions.versions를 사용하세요

ManifestRequest와 RepoServerAppDetailsQuery 메시지는 다음 GRPC 서비스에서 사용됩니다: GenerateManifest, GenerateManifestWithFiles, GetAppDetails.

CronJob 헬스(Health)

업그레이드 후, CronJob 헬스에 따라 Application의 상태가 Degraded로 전환될 수 있습니다.

참고: 실행 중인 Job이 있는 CronJob — CronJob이 Degraded 상태이고 새 Job이 예약되면, 활성 Job이 완료될 때까지 헬스가 Healthy로 변경됩니다. 이로 인해 애플리케이션이 Degraded → Healthy → Degraded로 다시 전환될 수 있습니다. 활성 Job이 있으면 CronJob 상태에 마지막으로 완료된 Job의 헬스를 추론할 충분한 정보가 없습니다. CronJob에 활성 Job이 계속 있으면, 마지막 Job이 실패했어도 헬스가 계속 Healthy로 유지됩니다.

참고: 일시 중단(suspended)된 CronJob — CronJob이 일시 중단 상태면 CronJob 상태는 Healthy로 유지됩니다. argocd-cm ConfigMap의 resource.customizations.health.batch_CronJob 키로 헬스체크를 구성해 이 동작을 재정의할 수 있습니다. 이렇게 구성하면 CronJob이 Suspended일 때 Application의 집계 헬스가 Healthy 대신 Suspended가 됩니다.

CronJob이 Application의 집계 헬스에 영향을 주지 않도록 하려면 CronJob 리소스에 argocd.argoproj.io/ignore-healthcheck: "true" 어노테이션을 구성할 수 있습니다.

정리된(sanitized) 프로젝트 API 응답

보안상의 이유(GHSA-786q-9hcg-v9ff)로 프로젝트 API 응답에서 민감한 정보가 정리(sanitize)되었습니다. 여기에는 프로젝트 범위 저장소와 클러스터의 자격 증명도 포함됩니다.

ApplicationSet status 리소스의 resources 필드는 기본적으로 5000개로 제한됩니다

ApplicationSet의 status 리소스에 있는 resources 필드는 이제 기본적으로 5000개 요소로 제한됩니다. 이는 상태 비대화(status bloat)와 etcd 한도 초과를 방지하기 위한 것입니다. 한도는 argocd-cmd-params-cm ConfigMap에서 applicationsetcontroller.status.max.resources.count 필드를 설정해 구성할 수 있습니다.

추가된 헬스체크

datadoghq.com/DatadogMetric
CronJob
promoter.argoproj.io/ArgoCDCommitStatus
promoter.argoproj.io/ChangeTransferPolicy
promoter.argoproj.io/CommitStatus
promoter.argoproj.io/PromotionStrategy
promoter.argoproj.io/PullRequest
coralogix.com/Alert
coralogix.com/RecordingRuleGroupSet
projectcontour.io/ExtensionService
clickhouse-keeper.altinity.com/ClickHouseKeeperInstallation
clickhouse.altinity.com/ClickHouseInstallation
apps.3scale.net/APIManager
capabilities.3scale.net/ActiveDoc
capabilities.3scale.net/ApplicationAuth
capabilities.3scale.net/Application
capabilities.3scale.net/Backend
capabilities.3scale.net/CustomPolicyDefinition
capabilities.3scale.net/DeveloperAccount
capabilities.3scale.net/DeveloperUser
capabilities.3scale.net/OpenAPI
capabilities.3scale.net/Product
capabilities.3scale.net/ProxyConfigPromote
capabilities.3scale.net/Tenant

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