ArgoCD ApplicationSet

📚 GitOps / ArgoCD 시리즈

• 1편 — ArgoCD Helm 설치 시 생성되는 컴포넌트 역할 정리
• 2편 — ArgoCD Application, AppProject 개념 정리
• 3편 — ApplicationSet으로 멀티 클러스터 배포 자동화 (현재 글)
• 4편 — ArgoCD Notifications Slack 연동 가이드

Application을 하나씩 수동으로 만들다 보면 클러스터나 환경이 늘어날수록 관리가 힘들어집니다. ApplicationSet은 이 문제를 해결하는 ArgoCD의 자동화 리소스입니다. Generator가 만들어내는 파라미터 목록을 템플릿에 주입해서 Application을 자동으로 생성·삭제합니다.

ApplicationSet의 핵심 구조: Generator (파라미터 목록 생성) + Template (Application 템플릿) → Application 자동 생성

기본 구조

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-appset
  namespace: argocd
spec:
  generators:
    - list:                    # Generator: 파라미터 목록
        elements:
          - cluster: prod
            url: https://prod.example.com
          - cluster: staging
            url: https://staging.example.com

  template:                    # Template: Application 청사진
    metadata:
      name: "my-app-{{cluster}}"   # Generator 파라미터 사용
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/my-repo
        targetRevision: main
        path: "k8s/overlays/{{cluster}}"
      destination:
        server: "{{url}}"
        namespace: my-app

위 ApplicationSet은 my-app-prod와 my-app-staging 두 Application을 자동으로 생성합니다. 환경이 추가되면 elements에 항목만 추가하면 됩니다.

Generator 종류

List Generator

가장 단순

직접 작성한 값 목록으로 Application을 생성합니다. 환경 수가 적고 정적일 때 사용합니다.

Cluster Generator

멀티 클러스터 핵심

ArgoCD에 등록된 클러스터 목록을 자동으로 읽어서 파라미터를 생성합니다. 클러스터가 추가되면 Application도 자동으로 생성됩니다.

Git Generator

디렉토리 / 파일 기반

Git 레포의 디렉토리 구조나 JSON/YAML 파일을 읽어서 파라미터를 생성합니다. 디렉토리 하나 = Application 하나 패턴에 유용합니다.

Matrix / Merge Generator

조합 / 병합

두 Generator의 결과를 곱집합(Matrix)하거나 병합(Merge)해서 복잡한 파라미터 조합을 만듭니다. "모든 앱 × 모든 환경" 패턴에 사용합니다.

Cluster Generator — 멀티 클러스터 자동 배포

가장 많이 쓰는 패턴입니다. ArgoCD에 클러스터를 등록하면 자동으로 해당 클러스터에 Application이 생성됩니다.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-addons
  namespace: argocd
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            env: production    # 레이블로 대상 클러스터 필터링

  template:
    metadata:
      name: "cluster-addons-{{name}}"
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/cluster-addons
        targetRevision: main
        path: addons
      destination:
        server: "{{server}}"   # 클러스터 URL 자동 주입
        namespace: kube-system
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

클러스터를 ArgoCD에 등록하는 명령:

# ArgoCD CLI로 클러스터 등록
argocd cluster add my-prod-context --name prod-ap-northeast-2

# 레이블 추가 (Cluster Generator 필터링용)
kubectl label secret -n argocd \
  $(argocd cluster list -o json | jq -r '.[] | select(.name=="prod-ap-northeast-2") | .connectionState.attemptedAt' ) \
  env=production

Git Generator — 디렉토리 기반 자동 생성

Git 레포의 디렉토리 구조를 그대로 Application으로 매핑합니다. 새 서비스를 추가할 때 디렉토리만 만들면 Application이 자동 생성됩니다.

# 레포 구조 예시
apps/
├── frontend/
│   └── kustomization.yaml
├── backend-api/
│   └── kustomization.yaml
└── batch-worker/
    └── kustomization.yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: apps-from-dirs
  namespace: argocd
spec:
  generators:
    - git:
        repoURL: https://github.com/my-org/my-repo
        revision: main
        directories:
          - path: apps/*        # apps/ 하위 모든 디렉토리

  template:
    metadata:
      name: "{{path.basename}}"    # 디렉토리 이름이 Application 이름
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/my-repo
        targetRevision: main
        path: "{{path}}"           # 해당 디렉토리 경로
      destination:
        server: https://kubernetes.default.svc
        namespace: "{{path.basename}}"
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

Matrix Generator — 앱 × 환경 조합

"모든 앱을 모든 환경에 배포"하는 패턴입니다. 앱 목록과 환경 목록의 곱집합으로 Application을 생성합니다.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: all-apps-all-envs
  namespace: argocd
spec:
  generators:
    - matrix:
        generators:
          # Generator 1: 앱 목록 (Git 디렉토리)
          - git:
              repoURL: https://github.com/my-org/my-repo
              revision: main
              directories:
                - path: apps/*

          # Generator 2: 환경 목록
          - list:
              elements:
                - env: staging
                  server: https://staging.example.com
                - env: production
                  server: https://prod.example.com

  template:
    metadata:
      name: "{{path.basename}}-{{env}}"
    spec:
      project: "{{env}}"
      source:
        repoURL: https://github.com/my-org/my-repo
        targetRevision: main
        path: "{{path}}/overlays/{{env}}"
      destination:
        server: "{{server}}"
        namespace: "{{path.basename}}"

PR 환경 자동화 — Pull Request Generator

PR이 열릴 때 임시 환경을 자동으로 만들고, PR이 닫히면 삭제하는 패턴입니다.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: pr-preview
  namespace: argocd
spec:
  generators:
    - pullRequest:
        github:
          owner: my-org
          repo: my-repo
          tokenRef:
            secretName: github-token
            key: token
          labels:
            - preview              # 'preview' 레이블이 달린 PR만 대상

  template:
    metadata:
      name: "pr-{{number}}-preview"
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/my-repo
        targetRevision: "{{head_sha}}"    # PR의 최신 커밋
        path: k8s/overlays/preview
      destination:
        server: https://kubernetes.default.svc
        namespace: "pr-{{number}}"        # PR 번호별 namespace
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

syncPolicy.preserveResourcesOnDeletion

ApplicationSet이 삭제되거나 Generator에서 항목이 제거될 때, 생성된 Application과 그 리소스를 어떻게 처리할지 설정합니다.

spec:
  syncPolicy:
    preserveResourcesOnDeletion: true   # true: Application 삭제 시 클러스터 리소스 유지
                                        # false (기본): Application 삭제 시 리소스도 삭제

PR Generator 사용 시 주의

PR이 닫히면 namespace와 그 안의 모든 리소스가 삭제됩니다. preserveResourcesOnDeletion: true를 사용하면 리소스는 남기고 Application만 삭제합니다. 데이터가 중요한 서비스라면 반드시 확인하세요.

실무 팁

tempate.metadata.annotations으로 알림 연동

ApplicationSet으로 생성된 Application에도 Notifications 어노테이션을 템플릿에 추가하면 자동으로 알림이 붙습니다.

notifications.argoproj.io/subscribe.on-sync-failed.slack: devops-alerts

ignoreApplicationDifferences로 일부 필드 무시

ApplicationSet이 관리하지 않는 필드(예: 수동으로 추가한 어노테이션)가 있을 때 ApplicationSet이 계속 덮어쓰는 문제를 방지합니다.

spec:
  ignoreApplicationDifferences:
    - jsonPointers:
        - /spec/source/targetRevision   # 이미지 태그 등 별도 관리하는 필드 무시

마치며

ApplicationSet은 "Application을 어떻게 자동화할 것인가"의 답입니다. List Generator로 시작해서 Git Generator, Cluster Generator 순서로 익혀가면 자연스럽게 멀티 클러스터 GitOps 체계를 갖출 수 있습니다.

다음 편에서는 argocd-notifications-controller를 이용해 Slack 알림을 설정하는 방법을 다룹니다.

📚 다음 편

• 4편 — ArgoCD Notifications Slack 연동 가이드