Application 정의

Application 정의 (Application Specification) — CRD 필드를 한눈에

Argo CD에서 '배포할 것'은 전부 Application이라는 커스텀 리소스로 표현돼요. 이 글은 그 CRD에 넣을 수 있는 필드들을 살펴봅니다. 전체 YAML을 통째로 외울 필요는 없고, source·destination·syncPolicy 세 덩어리가 어떻게 생겼는지 감을 잡는 게 핵심이에요.

출처: Argo CD 공식 문서 — Application Specification Reference

본문

Application은 argoproj.io/v1alpha1 API 그룹의 Application kind로 정의하고, 보통 Argo CD가 설치된 argocd 네임스페이스에 둡니다. 아래는 골격을 잡는 예시예요.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
  # 캐스케이드 삭제를 원하면 finalizer를 추가해요.
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  # 이 애플리케이션이 속할 프로젝트
  project: default
  # 매니페스트를 가져올 소스
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  # 배포할 대상 클러스터와 네임스페이스
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook

source — 매니페스트를 어디서 만들까

source는 매니페스트를 만들어내는 출처를 가리켜요. Git 저장소든 Helm 차트 저장소든 상관없고, 매니페스트를 렌더링할 도구가 뭔지에 따라 helm, kustomize, directory, plugin 하위 설정이 갈립니다.

Helm을 쓸 때는 chart, releaseName, valueFiles, valuesObject, parameters, fileParameters 같은 필드를 써요. valuesObject는 값 파일을 블록으로 직접 넣는 방식이고, values보다 우선합니다.

source:
  repoURL: https://github.com/argoproj/argocd-example-apps.git
  targetRevision: HEAD
  path: guestbook
  helm:
    releaseName: guestbook
    valueFiles:
      - values-prod.yaml
    valuesObject:
      ingress:
        enabled: true
        hosts:
          - mydomain.example.com

Kustomize를 쓸 때는 namePrefix, nameSuffix, commonLabels, patches, images, replicas 같은 필드가 익숙할 거예요.

source:
  repoURL: https://github.com/argoproj/argocd-example-apps.git
  path: guestbook
  kustomize:
    namePrefix: prod-
    commonLabels:
      foo: bar
    images:
      - my-app=gcr.io/my-repo/my-app:0.1

여러 소스를 한 번에 쓰고 싶다면 source 대신 sources 목록을 사용할 수 있어요. 각 소스는 ref로 이름을 붙여 다른 소스의 값 파일을 참조하는 데 쓸 수도 있습니다.

destination — 어디로 배포할까

대상 클러스터의 API URL(server) 또는 클러스터 이름(name)과 namespace를 지정해요. namespace는 아직 정해지지 않은 네임스페이스 스코프 리소스에만 적용됩니다.

destination:
  server: https://kubernetes.default.svc
  # 또는 name: in-cluster
  namespace: guestbook

syncPolicy — 어떻게 동기화할까

자동 싱크, 프루닝, 자기 치유, 재시도 정책을 여기서 정해요.

syncPolicy:
  automated:
    enabled: true   # 자동 싱크 (기본 true)
    prune: true     # Git에서 사라진 리소스도 지울지 (기본 false)
    selfHeal: true  # 클러스터에서만 바뀐 부분도 되돌릴지 (기본 false)
    allowEmpty: false
  retry:
    limit: 5        # 실패 재시도 횟수 (음수면 무제한)
    backoff:
      duration: 5s  # 첫 재시도 전 대기
      factor: 2     # 지수 백오프 배수
      maxDuration: 3m

retry는 v1.7부터 지원되며, 실패한 싱크를 지수 백오프로 자동 재시도하게 합니다.

싱크·검증을 다듬는 부가 필드

syncOptions: Validate=false, CreateNamespace=true, PrunePropagationPolicy=foreground, PruneLast=true, Replace=true, ApplyOutOfSyncOnly=true 같은 싱크 동작 변경 옵션의 목록이에요. 각 옵션의 의미는 Sync Options 페이지에서 자세히 다뤄요.
ignoreDifferences: 라이브와 원하는 상태의 diff에서 특정 필드(jsonPointer나 jq 경로)를 무시하도록 해요. 실제 싱크 과정에 반영하려면 RespectIgnoreDifferences=true 싱크 옵션을 함께 켜야 해요.
revisionHistoryLimit: 롤백 등에 쓰는 리비전 히스토리를 몇 개 보관할지 정해요. 기본은 10이고, 0으로 두면 히스토리를 저장하지 않아 저장 공간을 아낍니다.
info: Argo CD UI의 Application 상세 탭에 보여줄 추가 정보 항목을 넣을 수 있어요.

이 YAML 어디에 무엇이 있는지만 잡아두면, 이후에 싱크 옵션·자동 싱크·프로젝트를 배울 때 '아, 이 필드가 그거구나' 하고 자연스럽게 연결됩니다.

Application 정의