본문으로 건너뛰기

ArgoCD

개요​

ArgoCD는 Lumie 플랫폼의 GitOps 연속 배포 도구입니다. Git 저장소에서 Kubernetes로 애플리케이션을 자동으로 동기화하며, App-of-Apps 패턴을 통해 다중 애플리케이션을 관리합니다.

아키텍처​

설치 및 구성​

ArgoCD Application 정의​

# applications/argocd/argocd.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: argocd
  namespace: argocd
  finalizers:
  - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  sources:
    # ArgoCD Helm Chart
    - repoURL: https://argoproj.github.io/argo-helm
      chart: argo-cd
      targetRevision: 7.7.10
      helm:
        valueFiles:
          - $values/applications/argocd/helm-values.yaml
    # Common chart values
    - repoURL: https://github.com/Lumie-Edu/lumie-infra.git
      targetRevision: main
      ref: values
      path: charts/common
      helm:
        valueFiles:
          - $values/applications/argocd/common-values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true
      - RespectIgnoreDifferences=true

핵심 설정​

글로벌 설정​

# helm-values.yaml
global:
  priorityClassName: high-priority  # 높은 우선순위 설정

ConfigMap 설정 (argocd-cm)​

configs:
  cm:
    # Authelia 인증 통합
    users.anonymous.enabled: "true"
    
    # 폴링 비활성화 (웹훅만 사용)
    timeout.reconciliation: "0"
    
    # 리소스 상태 필드 차이 무시
    resource.compareoptions: |
      ignoreResourceStatusField: all
    
    # Tekton 동적 리소스 제외
    resource.exclusions: |
      - apiGroups:
        - tekton.dev
        kinds:
        - PipelineRun
        - TaskRun
    
    # Kustomize Helm 지원 활성화
    kustomize.buildOptions: --enable-helm
    
    # Ingress 커스텀 헬스 체크
    resource.customizations.health.networking.k8s.io_Ingress: |
      hs = {}
      hs.status = "Healthy"
      return hs

서버 파라미터 (argocd-cmd-params-cm)​

configs:
  params:
    # TLS 비활성화 (Ingress에서 처리)
    server.insecure: "true"
    
    # 자가 치유 타임아웃
    controller.self.heal.timeout.seconds: "5"

RBAC 설정 (argocd-rbac-cm)​

configs:
  rbac:
    # 익명 사용자에게 admin 역할 부여 (Authelia가 인증 처리)
    policy.csv: |
      g, , role:admin
    policy.default: role:admin

컴포넌트별 설정​

1. Application Controller​

controller:
  # Prometheus 메트릭스
  metrics:
    enabled: true
    service:
      enabled: true
      servicePort: 8082
    serviceMonitor:
      enabled: true

  # 메모리 최적화
  env:
    - name: GOMEMLIMIT
      value: "800MiB"
    - name: GOGC
      value: "50"

  # 성능 최적화 인수
  extraArgs:
    - --app-resync=3600           # 앱 재동기화 간격
    - --app-hard-resync=0         # 하드 재동기화 비활성화
    - --status-processors=10      # 상태 프로세서 수
    - --operation-processors=5    # 작업 프로세서 수

  # 리소스 설정
  resources:
    requests:
      cpu: 130m
      memory: 1024Mi
    limits:
      memory: 1024Mi  # CPU 제한 없음 (안정성)

2. API Server​

server:
  # Prometheus 메트릭스
  metrics:
    enabled: true
    service:
      enabled: true
      servicePort: 8083
    serviceMonitor:
      enabled: true

  # Ingress 비활성화 (Teleport 접근)
  ingress:
    enabled: false

  # 리소스 설정
  resources:
    requests:
      cpu: 15m
      memory: 105Mi
    limits:
      memory: 105Mi

3. Repo Server​

repoServer:
  # Prometheus 메트릭스
  metrics:
    enabled: true
    service:
      enabled: true
      servicePort: 8084
    serviceMonitor:
      enabled: true

  # 리소스 설정 (Helm 차트 처리를 위한 메모리 증가)
  resources:
    requests:
      cpu: 25m
      memory: 512Mi
    limits:
      memory: 512Mi

  # 프로브 타임아웃 증가
  livenessProbe:
    enabled: true
    timeoutSeconds: 5
  readinessProbe:
    enabled: true
    timeoutSeconds: 5

4. Redis​

redis:
  resources:
    requests:
      cpu: 15m
      memory: 100Mi
    limits:
      memory: 100Mi

5. ApplicationSet Controller​

applicationSet:
  enabled: true
  resources:
    requests:
      cpu: 10m
      memory: 64Mi
    limits:
      memory: 64Mi

네트워킹 설정​

폴링 모드 (Webhook 없음)​

ArgoCD는 외부 Webhook Ingress를 사용하지 않습니다. common-values.yaml에 ingress: enabled: false가 설정되어 있으며, timeout.reconciliation: "0" 설정으로 폴링 대신 Gitea 저장소 변경 시 수동 또는 ArgoCD 내부 RefreshInterval로 동기화합니다.

# argocd-cm (helm-values.yaml)
configs:
  cm:
    timeout.reconciliation: "0"   # 폴링 비활성화

UI 접근​

  • 내부 접근: Teleport를 통한 보안 터널 (argocd.lumie-infra.com)
  • 인증: Authelia 통합 인증
  • 권한: 익명 사용자에게 admin 권한 부여 (Authelia가 실제 인증 처리)

App-of-Apps 패턴​

현재 애플리케이션 구조​

applications/kustomization.yaml에 등록된 ArgoCD Application 목록입니다. 백엔드는 단일 모노리스 App(lumie-backend)으로 통합되었습니다:

# applications/kustomization.yaml
resources:
  - application.yaml               # App-of-Apps 루트

  # 클러스터 부트스트랩 (ClusterIssuers, StorageClass) — wave -2
  - cluster-bootstrap/argocd.yaml

  # 인프라 도구
  - argocd/argocd.yaml
  - lumie/document/argocd.yaml
  - umami/argocd.yaml
  - headlamp/argocd.yaml
  - openclaw/argocd.yaml
  - coder/argocd.yaml

  # Teleport 감사 이벤트 핸들러
  - teleport-event-handler/argocd.yaml

  # Tekton CI/CD (통합)
  - tekton/pipeline/argocd.yaml
  - tekton/triggers/argocd.yaml
  - tekton/dashboard/argocd.yaml
  - tekton/ci-cd/argocd.yaml

  # Lumie 플랫폼
  - lumie/argocd.yaml
  - lumie/develop/argocd.yaml

  # 백엔드 모노리스 (단일 App — 이전 10개 마이크로서비스 통합)
  - lumie/backend/argocd.yaml

  # 프론트엔드
  - lumie/frontend/argocd.yaml

  # Worker 서비스 (FastAPI — 독립 배포 유지)
  - lumie/worker/analysis-svc/argocd.yaml
  - lumie/worker/chatbot-svc/argocd.yaml
  - lumie/worker/grading-svc/argocd.yaml
  - lumie/worker/report-svc/argocd.yaml
  - lumie/worker/temp-omr-grading/argocd.yaml

이전 구조: 백엔드 마이크로서비스 10개(tenant, auth, academy, admin, exam, content, attendance, billing, file, ai)가 각각 개별 ArgoCD Application으로 등록되어 있었습니다. 현재는 lumie-backend 단일 Application으로 통합되었습니다.

lumie-backend Application 정의​

# applications/lumie/backend/argocd.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: lumie-backend
  namespace: argocd
  finalizers:
  - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/Lumie-Edu/lumie-infra.git
    targetRevision: main
    path: applications/lumie/backend
  destination:
    server: https://kubernetes.default.svc
    namespace: lumie-backend
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m
    syncOptions:
    - CreateNamespace=true
  revisionHistoryLimit: 10

path: applications/lumie/backend는 kustomization.yaml을 포함하는 디렉토리입니다. Kustomize가 charts/common Helm 차트와 manifests/strip-prefix.yaml 미들웨어를 함께 렌더링합니다.

부트스트랩 애플리케이션 구조​

# bootstrap/kustomization.yaml
resources:
  - minio/argocd.yaml   # sync wave 0 — 오브젝트 스토리지
  - zot/argocd.yaml     # sync wave 1 — 컨테이너 레지스트리
  - vault/argocd.yaml   # sync wave 2 — 시크릿 저장소
  - gitea/argocd.yaml   # sync wave 3 — Git 서비스 (Vault VSO 의존)

Kong은 부트스트랩에서 제거되어 Traefik으로 대체되었습니다. bootstrap/kong/ 디렉토리는 참조용으로 보존되어 있으나 ArgoCD에 등록되지 않습니다.

일반 애플리케이션 구조 예시​

각 서비스는 개별 ArgoCD Application으로 정의:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: example-service
  namespace: argocd
  finalizers:
  - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/Lumie-Edu/lumie-infra.git
    targetRevision: main
    path: applications/example-service
  destination:
    server: https://kubernetes.default.svc
    namespace: example-service
  syncPolicy:
    automated:
      prune: true      # 삭제된 리소스 자동 제거
      selfHeal: true   # 수동 변경사항 자동 복구
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true
      - RespectIgnoreDifferences=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

동기화 정책​

자동 동기화​

  • prune: Git에서 삭제된 리소스를 클러스터에서도 제거
  • selfHeal: 클러스터에서 수동으로 변경된 사항을 Git 상태로 되돌림

동기화 옵션​

  • CreateNamespace: 네임스페이스 자동 생성
  • ServerSideApply: 서버 사이드 적용으로 충돌 방지
  • RespectIgnoreDifferences: ignoreDifferences 설정 준수

재시도 정책​

  • limit: 최대 5회 재시도
  • backoff: 지수 백오프 (5초 → 10초 → 20초 → 40초 → 3분)

배포 워크플로우​

1. 코드 변경 → 이미지 빌드​

2. 인프라 변경 → 배포​

운영 가이드​

새 서비스 추가​

  1. 서비스 디렉토리 생성

    mkdir -p applications/my-service
    cd applications/my-service

  2. Kubernetes 매니페스트 작성

    # deployment.yaml, service.yaml, ingress.yaml 등

  3. Kustomization 파일 생성

    # kustomization.yaml
    apiVersion: kustomize.config.k8s.io/v1beta1
    kind: Kustomization
    resources:
      - deployment.yaml
      - service.yaml
      - ingress.yaml

  4. ArgoCD Application 정의

    # argocd.yaml
    apiVersion: argoproj.io/v1alpha1
    kind: Application
    metadata:
      name: my-service
      namespace: argocd
    spec:
      # ... 설정

  5. Git 푸시

    git add .
    git commit -m "add my-service"
    git push

서비스 업데이트​

  1. 배포 파일 수정

    vim applications/my-service/deployment.yaml

  2. 변경사항 커밋

    git add .
    git commit -m "update my-service deployment"
    git push

  3. ArgoCD 자동 동기화 대기

    # 동기화 상태 확인
    kubectl get application -n argocd my-service

롤백 수행​

Git 기반 롤백​

# 특정 커밋으로 되돌리기
git revert <commit-hash>
git push

# 또는 특정 커밋으로 리셋
git reset --hard <commit-hash>
git push --force

ArgoCD 기반 롤백​

# CLI를 통한 롤백
argocd app rollback <app-name> <revision>

# 또는 특정 커밋으로 동기화
argocd app sync <app-name> --revision <commit-hash>

모니터링 및 관찰성​

메트릭스 수집​

각 컴포넌트는 Prometheus 메트릭스를 제공:

# ServiceMonitor 자동 생성
metrics:
  enabled: true
  serviceMonitor:
    enabled: true

주요 메트릭스​

  • argocd_app_info: 애플리케이션 정보
  • argocd_app_sync_total: 동기화 횟수
  • argocd_app_health_status: 애플리케이션 상태
  • argocd_cluster_connection_status: 클러스터 연결 상태

상태 확인 명령어​

# 모든 애플리케이션 상태
kubectl get applications -n argocd

# 특정 애플리케이션 상세 정보
kubectl get application -n argocd <app-name> -o yaml

# 동기화 차이점 확인
argocd app diff <app-name>

# 애플리케이션 로그 확인
kubectl logs -n argocd deployment/argocd-application-controller

문제 해결​

동기화 실패​

강제 새로고침​

kubectl patch application -n argocd <app-name> \
  -p '{"metadata": {"annotations": {"argocd.argoproj.io/refresh": "hard"}}}' \
  --type merge

수동 동기화​

argocd app sync <app-name> --force

Out of Sync 상태​

차이점 분석​

# CLI를 통한 차이점 확인
argocd app diff <app-name>

# 상세 상태 확인
kubectl describe application -n argocd <app-name>

일반적인 원인​

  1. 리소스 상태 차이: resource.compareoptions로 해결
  2. 동적 리소스: resource.exclusions로 제외
  3. 권한 문제: ServiceAccount 권한 확인
  4. 네트워크 문제: Git 저장소 접근성 확인

성능 문제​

메모리 사용량 최적화​

# Controller 메모리 사용량 확인
kubectl top pod -n argocd -l app.kubernetes.io/name=argocd-application-controller

# 메모리 제한 조정
kubectl patch deployment -n argocd argocd-application-controller \
  -p '{"spec":{"template":{"spec":{"containers":[{"name":"argocd-application-controller","resources":{"limits":{"memory":"2Gi"}}}]}}}}'

동기화 성능 개선​

# 프로세서 수 조정
kubectl patch deployment -n argocd argocd-application-controller \
  -p '{"spec":{"template":{"spec":{"containers":[{"name":"argocd-application-controller","args":["--status-processors=20","--operation-processors=10"]}]}}}}'

보안 고려사항​

1. 인증 및 권한​

  • Authelia 통합: 중앙화된 인증 시스템
  • 익명 접근: 내부 네트워크에서만 허용
  • RBAC: Kubernetes 네이티브 권한 관리

2. 네트워크 보안​

  • UI 접근: Teleport를 통한 보안 터널만 허용
  • 웹훅 엔드포인트: 제한된 경로만 외부 노출
  • TLS 암호화: Let's Encrypt 인증서 사용

3. 시크릿 관리​

  • Git 저장소: 시크릿 정보 제외
  • Vault 통합: 민감한 정보는 Vault에서 관리
  • 이미지 풀 시크릿: 자동 주입

4. 감사 및 로깅​

  • 변경 추적: Git 커밋 히스토리
  • 접근 로그: ArgoCD 서버 로그
  • 동기화 이벤트: Kubernetes 이벤트 로그

성능 최적화​

1. 리소스 튜닝​

# 메모리 최적화
env:
  - name: GOMEMLIMIT
    value: "800MiB"
  - name: GOGC
    value: "50"

# CPU 제한 제거 (안정성 우선)
resources:
  requests:
    cpu: 130m
    memory: 1024Mi
  limits:
    memory: 1024Mi  # CPU 제한 없음

2. 동기화 최적화​

# 폴링 비활성화
timeout.reconciliation: "0"

# 프로세서 수 조정
extraArgs:
  - --status-processors=10
  - --operation-processors=5

3. 캐싱 최적화​

  • Redis: 메타데이터 캐싱
  • Repo Server: Git 저장소 캐싱
  • 이미지 캐싱: 컨테이너 이미지 로컬 캐시

관련 문서​