ArgoCD Helm 설치 시 생성되는 컴포넌트 역할 정리

📚 GitOps / ArgoCD 시리즈

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

Helm으로 ArgoCD를 설치하면 한 namespace 안에 여러 Deployment와 StatefulSet이 생깁니다. 처음 보면 뭐가 뭔지 헷갈리는데, 각 컴포넌트가 담당하는 역할이 명확히 나뉩니다. 이 글에서는 kubectl get pod -n argocd 했을 때 보이는 각 파드가 무슨 일을 하는지 정리합니다.

테스트 환경: ArgoCD v2.x, argo-cd Helm chart (argoproj/argo-cd)

설치 후 생성되는 파드 목록

$ kubectl get pod -n argocd

NAME                                                READY   STATUS
argocd-server-xxxxxxxxx-xxxxx                       1/1     Running   ← Deployment
argocd-repo-server-xxxxxxxxx-xxxxx                  1/1     Running   ← Deployment
argocd-application-controller-0                     1/1     Running   ← StatefulSet
argocd-applicationset-controller-xxxxxxxxx-xxxxx    1/1     Running   ← Deployment
argocd-notifications-controller-xxxxxxxxx-xxxxx     1/1     Running   ← Deployment
argocd-redis-xxxxxxxxx-xxxxx                        1/1     Running   ← Deployment
argocd-dex-server-xxxxxxxxx-xxxxx                   1/1     Running   ← Deployment (SSO 사용 시)

application-controller만 StatefulSet이고 나머지는 전부 Deployment입니다. StatefulSet인 이유는 클러스터 상태 캐시를 안정적으로 유지하고, HA 구성 시 샤딩을 위해 고정된 파드 식별자가 필요하기 때문입니다.

컴포넌트별 역할 상세

argocd-server

Deployment

ArgoCD의 API 게이트웨이이자 Web UI 서버입니다. 외부에서 들어오는 모든 요청이 여기를 통합니다.

• gRPC / REST API 제공 — CLI(argocd)와 Web UI가 이 서버와 통신
• RBAC 인증 처리 — 어떤 사용자가 어떤 Application에 접근할 수 있는지 판단
• Dex와 연동해서 SSO 토큰 검증
• Webhook 수신 — GitHub/GitLab Push 이벤트를 받아서 즉시 Sync 트리거

argocd-repo-server

Deployment

Git 레포지토리에서 매니페스트를 가져와 최종 YAML로 변환하는 컴포넌트입니다. ArgoCD에서 CPU를 가장 많이 쓰는 컴포넌트입니다.

• Git clone / fetch 수행
• Helm, Kustomize, Jsonnet, Plain YAML 렌더링 — helm template 실행이 여기서 일어남
• 렌더링 결과를 Redis에 캐시해서 동일 커밋 반복 렌더링 방지
• 커스텀 플러그인(CMP, Config Management Plugin) 실행도 여기서 처리

argocd-application-controller

StatefulSet

ArgoCD의 핵심 컴포넌트입니다. Git의 desired state와 실제 클러스터 상태를 지속적으로 비교하고, 차이가 있으면 Sync(배포)를 실행합니다.

• 주기적으로 클러스터 상태를 조회해서 Redis에 캐시
• Repo Server에서 받은 매니페스트와 실제 상태 비교 → OutOfSync / Synced 판단
• Auto-sync 설정 시 자동으로 kubectl apply 수행
• Health 상태 평가 — Deployment rollout, PVC 바인딩 등 리소스별 상태 판단
• HA 구성 시 샤딩으로 여러 클러스터를 분산 처리 (인스턴스 인덱스 기반)

argocd-applicationset-controller

Deployment

ApplicationSet 커스텀 리소스를 감시해서 Application을 자동으로 생성·업데이트·삭제합니다.

• List, Cluster, Git, Matrix 등 다양한 generator로 Application 목록 생성
• 멀티 클러스터 배포 자동화 — 클러스터가 추가되면 Application 자동 생성
• PR 환경 자동화 — PR 오픈 시 임시 환경 생성, 머지 시 삭제

argocd-notifications-controller

Deployment

Application 상태 변화를 감지해서 외부로 알림을 보내는 컴포넌트입니다.

• Sync 성공 / 실패, Health 상태 변화 감지
• Slack, 이메일, PagerDuty, Teams, Webhook 등 다양한 채널 지원
• trigger + template 조합으로 유연한 알림 조건 정의 가능

argocd-redis

Deployment

API Server와 Application Controller가 클러스터 상태 캐시를 공유하는 저장소입니다.

• 클러스터 리소스 상태 캐시 — 매번 kube-apiserver를 호출하지 않도록
• Repo Server 렌더링 결과 캐시
• 재시작하면 데이터가 초기화됨 (캐시 전용, 영구 저장 아님)
• HA 구성 시 Redis Sentinel 또는 Redis Cluster로 대체 가능

argocd-dex-server

Deployment (선택)

OIDC 브로커 역할을 하는 SSO 컴포넌트입니다. GitHub, Google, LDAP, SAML 등 외부 IdP와 ArgoCD 사이에서 인증을 중계합니다.

• 외부 IdP로부터 받은 토큰을 ArgoCD가 이해할 수 있는 형태로 변환
• SSO가 필요 없으면 dex.enabled: false로 비활성화 가능
• 비활성화 시 ArgoCD 로컬 사용자 또는 직접 OIDC 연동으로 대체

한눈에 정리

컴포넌트	종류	핵심 역할	리소스 특성
argocd-server	Deployment	API / Web UI / Webhook 수신	외부 트래픽 집중
argocd-repo-server	Deployment	Git clone + 매니페스트 렌더링	CPU 집중
argocd-application-controller	StatefulSet	상태 비교 + Sync 실행	메모리 집중, 핵심
argocd-applicationset-controller	Deployment	ApplicationSet → Application 생성	경량
argocd-notifications-controller	Deployment	상태 변화 감지 + 알림 발송	경량
argocd-redis	Deployment	상태 캐시 공유	메모리, 재시작 시 초기화
argocd-dex-server	Deployment	OIDC / SSO 인증 브로커	선택, SSO 불필요 시 비활성화

Git Push부터 배포까지 전체 흐름

[Git repo] ─ push ──────────────────────────────────────────▶ [argocd-server] (Webhook 수신) │ ▼ [argocd-repo-server] ◀── 매니페스트 렌더링 요청 ────────── [argocd-application-controller] │ │ │ Helm/Kustomize 실행 │ 상태 비교 ▼ │ (desired vs actual) [argocd-redis] ◀── 캐시 저장 ──────────────────────────────────────▶ [argocd-application-controller] │ │ kubectl apply ▼ [Kubernetes cluster] │ │ Sync 결과 ▼ [argocd-notifications-controller] ──▶ Slack

리소스 설정 예시

처음 설치할 때 최소한으로 잡아야 할 리소스 설정입니다. repo-server는 Helm 렌더링이 많을수록 CPU를 많이 쓰고, application-controller는 관리하는 Application/클러스터 수에 비례해서 메모리가 늘어납니다.

# values.yaml

server:
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "500m"
      memory: "256Mi"

repoServer:
  resources:
    requests:
      cpu: "200m"
      memory: "256Mi"
    limits:
      cpu: "1000m"      # Helm 렌더링 시 CPU 급증
      memory: "512Mi"

controller:
  resources:
    requests:
      cpu: "250m"
      memory: "512Mi"
    limits:
      cpu: "1000m"
      memory: "2Gi"     # Application 수에 비례해서 증가

redis:
  resources:
    requests:
      cpu: "100m"
      memory: "64Mi"
    limits:
      cpu: "200m"
      memory: "128Mi"

applicationSet:
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "200m"
      memory: "256Mi"

notifications:
  resources:
    requests:
      cpu: "100m"
      memory: "64Mi"
    limits:
      cpu: "200m"
      memory: "128Mi"

# SSO 불필요 시 Dex 비활성화
dex:
  enabled: false

자주 하는 실수

repo-server CPU limit을 너무 낮게 잡는 경우

Helm 차트가 크거나 Application이 많으면 repo-server에서 동시에 여러 렌더링이 일어납니다. CPU limit이 너무 낮으면 Sync가 느려지거나 타임아웃이 발생합니다. 처음에는 넉넉하게 잡고 실제 사용량을 보면서 줄이세요.

application-controller 메모리 부족

관리하는 클러스터와 Application이 늘어날수록 application-controller의 메모리 사용량이 선형으로 증가합니다. OOMKilled가 반복되면 limit을 올리거나 HA 샤딩 구성을 검토하세요.

Webhook 설정으로 Sync 속도 개선

기본 설정에서 ArgoCD는 3분마다 Git을 polling합니다. GitHub/GitLab Webhook을 argocd-server에 연결하면 Push 즉시 Sync가 트리거되어 배포 지연이 없어집니다.

마치며

ArgoCD는 컴포넌트가 많아 보이지만, 역할을 나눠 보면 구조가 명확합니다. 문제가 생겼을 때 어느 파드 로그를 봐야 할지 파악하는 것만으로도 트러블슈팅 시간이 크게 줄어듭니다. Sync가 안 되면 application-controller, 렌더링 에러면 repo-server, 로그인 문제면 dex나 argocd-server를 먼저 확인하세요.

📚 다음 편

• 2편 — ArgoCD Application, AppProject 개념 정리