🛠 ArgoCD ApplicationSet Generator 완벽 가이드: 자동화의 끝판왕

안녕하세요! 오늘은 Kubernetes 환경에서 멀티 클러스터와 멀티 앱 관리를 혁신적으로 줄여주는 ArgoCD ApplicationSet과 그 심장부인 Generator에 대해 상세히 알아보겠습니다.

단순히 애플리케이션 하나를 배포하는 것을 넘어, "클러스터가 100개라면?", "스테이징과 프로덕션 환경이 다르다면?"이라는 고민을 한 방에 해결해 줄 도구입니다.

---

1. ApplicationSet이란 무엇인가요? 🤔

ArgoCD의 기본 단위인 Application 리소스는 하나의 소스(Git)와 하나의 목적지(Cluster)를 연결합니다. 하지만 관리해야 할 서비스가 늘어나면 Application YAML 파일도 기하급수적으로 늘어나죠.

ApplicationSet은 일종의 '붕어빵 틀'입니다. Generator라는 엔진을 통해 동적으로 여러 개의 Application을 생성해 줍니다.

---

2. Generator 종류별 상세 분석 🔍

Generator는 "어떤 데이터를 바탕으로 Application을 만들 것인가?"를 결정합니다. 가장 많이 쓰이는 4가지를 중점적으로 살펴보겠습니다.

① List Generator: 가장 직관적인 시작 📋

가장 간단한 형태로, YAML 안에 생성할 리스트를 직접 명시합니다.

• 용도: 관리 대상이 적고 명확할 때.
• 장점: 직관적이고 설정이 쉽습니다.

📝 코드 예시 및 설명

YAML

 

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-apps
  namespace: argocd
spec:
  generators:
    - list:
        # 생성할 요소들을 리스트로 정의합니다.
        elements:
          - cluster: engineering-dev
            url: https://kubernetes.default.svc # 로컬 클러스터
          - cluster: engineering-prod
            url: https://1.2.3.4 # 원격 클러스터
  template:
    metadata:
      # 위 elements에서 정의한 {{cluster}} 변수를 동적으로 사용합니다.
      name: '{{cluster}}-guestbook'
    spec:
      project: default
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps.git
        targetRevision: HEAD
        path: guestbook
      destination:
        server: '{{url}}' # {{url}} 변수가 여기에 치환됩니다.
        namespace: guestbook

---

② Cluster Generator: 멀티 클러스터 관리의 핵심 ☸️

ArgoCD에 등록된 클러스터 정보를 자동으로 읽어와서 앱을 배포합니다.

• 용도: 클러스터가 추가될 때마다 자동으로 앱을 배포하고 싶을 때.
• 특징: 레이블 셀렉터(labelSelector)를 통해 특정 클러스터만 골라낼 수 있습니다.

📝 코드 예시 및 설명

YAML

 

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-scoped-app
spec:
  generators:
    - clusters:
        # ArgoCD에 'env: staging' 레이블이 붙은 클러스터만 대상으로 합니다.
        selector:
          matchLabels:
            env: staging
  template:
    metadata:
      # {{name}}은 ArgoCD에 등록된 클러스터 이름으로 자동 매핑됩니다.
      name: '{{name}}-monitoring'
    spec:
      project: default
      source:
        repoURL: https://github.com/my-repo/monitoring.git
        targetRevision: main
        path: charts/prometheus
      destination:
        # {{server}}는 클러스터의 API 서버 주소로 치환됩니다.
        server: '{{server}}'
        namespace: monitoring

---

③ Git Generator: Git 저장소 구조가 곧 설정 📂

Git 저장소 내의 파일 내용이나 디렉토리 구조를 감지하여 앱을 생성합니다.

• 용도: apps/app-a, apps/app-b 처럼 폴더 구조로 앱을 관리할 때.
• 종류:
  1. Directory: 특정 경로의 하위 디렉토리를 탐색.
  2. File: JSON/YAML 파일 내용을 읽어서 변수로 사용.

📝 코드 예시 (Directory 기반)

YAML

 

spec:
  generators:
    - git:
        repoURL: https://github.com/my-org/infra.git
        revision: HEAD
        # 'services/*' 경로에 있는 모든 디렉토리를 찾습니다.
        directories:
          - path: services/*
  template:
    metadata:
      # 디렉토리 이름(예: auth-service)이 앱 이름이 됩니다.
      name: '{{path.basename}}'
    spec:
      source:
        repoURL: https://github.com/my-org/infra.git
        targetRevision: HEAD
        path: '{{path}}' # 실제 Git 내의 경로 사용
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{path.basename}}'

---

④ Matrix Generator: 끝판왕 조합 🧬

두 개 이상의 Generator를 조합(곱하기)합니다. 예를 들어 **"모든 클러스터(Cluster Gen)"**에 **"모든 앱(Git Gen)"**을 배포하고 싶을 때 사용합니다.

• 작동 방식: A 리스트 [1, 2]와 B 리스트 [a, b]가 있다면, 결과는 [1-a, 1-b, 2-a, 2-b]가 됩니다.

📝 코드 예시 (Cluster x Git 조합)

YAML

 

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: matrix-deploy
spec:
  generators:
    - matrix:
        generators:
          # 1. 대상 클러스터 선정 (개발, 운영)
          - clusters:
              selector:
                matchLabels:
                  tier: backend
          # 2. 배포할 앱 목록 (Git 파일 기반)
          - git:
                repoURL: https://github.com/my-repo/configs.git
                revision: HEAD
                files:
                  - path: "config/**/config.json"
  template:
    metadata:
      # 결과: 'dev-cluster-api-server', 'prod-cluster-api-server' 등 생성
      name: '{{name}}-{{customer}}' 
    spec:
      project: default
      source:
        repoURL: https://github.com/my-repo/apps.git
        targetRevision: HEAD
        path: app-chart
        helm:
          # JSON 파일 안에 정의된 파라미터를 Helm value로 전달 가능!
          parameters:
            - name: "customerName"
              value: "{{customer}}"
      destination:
        server: '{{server}}'
        namespace: '{{customer}}'

---

⑤ Merge Generator: 조건부 덮어쓰기 🔗

Matrix와 비슷하지만, 동일한 키를 기준으로 데이터를 병합합니다. 특정 환경에서만 설정을 살짝 바꾸고 싶을 때 유용합니다.

---

3. 실무 꿀팁: 어떤 상황에 무엇을 써야 할까?💡

상황	추천 Generator
이제 막 ArgoCD를 시작했고 수동 관리가 싫다	List
클러스터가 계속 늘어나는 멀티 클러스터 환경이다	Clusters
하나의 Git Repo에 여러 마이크로서비스 코드가 있다	Git (Directory)
고객사별(SaaS)로 서로 다른 클러스터에 배포해야 한다	Matrix

---

4. 주의사항 및 모범 사례 (Best Practices) ⚠️

1. Dry-run 활용: ApplicationSet을 배포하기 전에 argocd-appset-controller 로그를 확인하거나, 작은 단위로 먼저 테스트하세요. 자칫하면 수백 개의 잘못된 앱이 동시에 생성될 수 있습니다.
2. Namespace 관리: ApplicationSet 자체는 argocd 네임스페이스에 있어야 하지만, 생성되는 Application들의 목적지는 적절히 분리하세요.
3. Preserve Resources: ApplicationSet을 삭제할 때 실제 배포된 리소스(Pod, Service 등)도 삭제할지 여부를 policy 설정을 통해 결정할 수 있습니다. 운영 환경에서는 신중해야 합니다.

---

5. 마치며 🏁

ApplicationSet은 단순한 반복 작업을 줄여주는 것을 넘어, **인프라를 코드로 완벽하게 제어(Infrastructure as Code)**할 수 있게 해주는 핵심 도구입니다. 처음에는 Matrix Generator의 복잡함이 낯설 수 있지만, 한 번 구축해두면 운영 효율이 수십 배는 올라갈 것입니다.

여러분의 환경에 맞는 Generator는 무엇인가요? 지금 바로 시도해 보세요! 🛠️