ArgoCD 아키텍처 내부 분석: 소스코드 레벨 딥다이브

사용자 (Web UI / CLI / CI)
       |
       v
  API Server (gRPC/REST)
       |
       +-------> Repository Server (gRPC)
       |                |
       +-------> Application Controller
       |                |
       +-------> Redis (TCP)
       |
       +-------> Dex (OIDC)

// API Server의 gRPC 서비스 등록
func (s *ArgoCDServer) Run(ctx context.Context, listeners ...net.Listener) {
    grpcServer := grpc.NewServer(grpcOpts...)
    application.RegisterApplicationServiceServer(grpcServer, s.appService)
    repository.RegisterRepositoryServiceServer(grpcServer, s.repoService)
    project.RegisterProjectServiceServer(grpcServer, s.projectService)
    session.RegisterSessionServiceServer(grpcServer, s.sessionService)
}

1. 사용자가 로그인 요청
2. API Server가 Dex에 OIDC 인증 위임 (SSO의 경우)
3. Dex가 외부 IdP (GitHub, LDAP 등)에 인증 요청
4. 인증 성공 시 JWT 토큰 발급
5. 이후 요청에 JWT 토큰을 Bearer 헤더로 전송
6. API Server가 JWT를 검증하고 RBAC 정책으로 인가 수행

# 기본 정책 포맷
p, ROLE, RESOURCE, ACTION, OBJECT, EFFECT

# 예시: proj-admin 역할에 my-project의 모든 application 권한 부여
p, role:proj-admin, applications, *, my-project/*, allow

# 그룹 매핑
g, my-github-team, role:proj-admin

1. Application Controller가 repo-server에 매니페스트 생성 요청
2. repo-server가 Git 저장소 클론 (shallow clone 기본)
3. 지정된 리비전(branch, tag, commit)으로 checkout
4. 경로 내 매니페스트를 감지하고 적절한 도구로 렌더링
5. 결과를 Application Controller에 반환하고 Redis에 캐시

// 매니페스트 생성 도구 감지 로직 (간소화)
func detectTool(path string) string {
    if fileExists(path, "Chart.yaml") {
        return "helm"
    }
    if fileExists(path, "kustomization.yaml") ||
       fileExists(path, "kustomization.yml") ||
       fileExists(path, "Kustomization") {
        return "kustomize"
    }
    return "directory" // plain YAML
}

1. Chart.yaml 파싱으로 차트 메타데이터 확인
2. dependencies가 있으면 helm dependency build 실행
3. values 파일 로드 (기본 values.yaml + 사용자 오버라이드)
4. helm template 명령으로 최종 매니페스트 생성
5. 생성된 YAML을 파싱하고 유효성 검사

1. kustomization.yaml 파싱
2. bases/resources 참조 해석
3. patches, overlays 적용
4. namePrefix, nameSuffix, labels, annotations 변환
5. 최종 YAML 출력

# CMP 설정 예시 - plugin.yaml
apiVersion: argoproj.io/v1alpha1
kind: ConfigManagementPlugin
metadata:
  name: custom-jsonnet
spec:
  version: v1.0
  generate:
    command: [jsonnet]
    args: [main.jsonnet]
  discover:
    fileName: main.jsonnet

캐시 키: HASH(git-url + revision + path + tool + params)
캐시 TTL: 기본 24시간 (ARGOCD_REPO_SERVER_CACHE_EXPIRATION)
캐시 무효화: Git revision 변경 시

// Informer 기반 리소스 감시 (간소화)
func (c *ApplicationController) watchResources() {
    factory := informers.NewSharedInformerFactory(clientset, resyncPeriod)

    factory.Apps().V1().Deployments().Informer().AddEventHandler(
        cache.ResourceEventHandlerFuncs{
            AddFunc:    c.onResourceAdd,
            UpdateFunc: c.onResourceUpdate,
            DeleteFunc: c.onResourceDelete,
        },
    )
}

반복:
  1. 모든 Application 리소스 조회
  2. 각 Application에 대해:
     a. Repository Server에 원하는 상태(매니페스트) 요청
     b. 대상 클러스터에서 실제 상태 조회
     c. 원하는 상태와 실제 상태 비교 (Diff)
     d. Sync Status 업데이트 (Synced / OutOfSync)
     e. Health Status 업데이트 (Healthy / Degraded / Progressing 등)
     f. Auto-Sync가 활성화되어 있으면 자동 동기화 실행
  3. 다음 주기까지 대기 (기본 180초)

비교 대상:
  - Last Applied Configuration (annotation에 저장)
  - Live State (클러스터 실제 상태)
  - Desired State (Git에서 생성된 매니페스트)

Diff 과정:
  1. Live State와 Desired State를 정규화 (normalization)
  2. 기본값 제거 (Kubernetes가 자동 추가하는 필드)
  3. 무시 필드 제외 (resourceVersion, generation 등)
  4. 남은 필드 간 구조적 비교 수행

// 정규화 예시
func normalizeResource(resource *unstructured.Unstructured) {
    // metadata에서 관리 필드 제거
    removeFields(resource, "metadata.managedFields")
    removeFields(resource, "metadata.resourceVersion")
    removeFields(resource, "metadata.uid")
    removeFields(resource, "metadata.generation")
    removeFields(resource, "metadata.creationTimestamp")

    // status 필드 제거 (선언적 상태가 아님)
    removeFields(resource, "status")
}

-- argocd-cm ConfigMap에 정의하는 커스텀 health check
hs = {}
if obj.status ~= nil then
    if obj.status.conditions ~= nil then
        for _, condition in ipairs(obj.status.conditions) do
            if condition.type == "Ready" and condition.status == "True" then
                hs.status = "Healthy"
                hs.message = condition.message
                return hs
            end
        end
    end
end
hs.status = "Progressing"
hs.message = "Waiting for resource to become ready"
return hs

1. 사용자 또는 Auto-Sync가 Sync 트리거
2. Application Controller가 Repository Server에 최신 매니페스트 요청
3. 매니페스트 생성 완료 후 Sync 작업 시작
4. PreSync Hook 실행 (있는 경우)
5. 메인 리소스 동기화 (kubectl apply 동등 작업)
6. PostSync Hook 실행 (있는 경우)
7. Health Check로 리소스 상태 확인
8. Sync Status 업데이트

# Sync Wave 예시
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: '-1' # 낮은 번호가 먼저 실행

Prune 대상 판별:
  1. 클러스터에 존재하는 리소스 목록 조회
  2. ArgoCD tracking label/annotation이 있는 리소스 필터
  3. 현재 Git 매니페스트에 존재하지 않는 리소스 식별
  4. cascade 또는 foreground 삭제 정책에 따라 삭제

app|resources|CLUSTER_URL|NAMESPACE: 리소스 트리 캐시
git|manifest|REPO_URL|REVISION|PATH: 매니페스트 캐시
repo|connection|REPO_URL: 연결 상태 캐시

1. 사용자가 ArgoCD UI에서 SSO 로그인 클릭
2. API Server가 Dex의 authorization endpoint로 리다이렉트
3. Dex가 설정된 커넥터(GitHub 등)로 인증 위임
4. 사용자가 외부 IdP에서 인증 수행
5. 외부 IdP가 Dex callback URL로 리다이렉트
6. Dex가 ID Token 생성 (사용자 정보, 그룹 포함)
7. API Server가 ID Token 검증 후 ArgoCD JWT 발급
8. JWT에 사용자 그룹 정보 포함 (RBAC에 활용)

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-alpha
  namespace: argocd
spec:
  description: 'Team Alpha의 프로젝트'
  # 허용 소스 저장소
  sourceRepos:
    - 'https://github.com/org/team-alpha-*'
  # 허용 대상 클러스터/네임스페이스
  destinations:
    - server: 'https://kubernetes.default.svc'
      namespace: 'team-alpha-*'
  # 생성 가능한 클러스터 리소스 (제한)
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
  # 네임스페이스 리소스 거부 목록
  namespaceResourceBlacklist:
    - group: ''
      kind: ResourceQuota
    - group: ''
      kind: LimitRange
  # 역할 정의
  roles:
    - name: developer
      description: '개발팀 역할'
      policies:
        - p, proj:team-alpha:developer, applications, get, team-alpha/*, allow
        - p, proj:team-alpha:developer, applications, sync, team-alpha/*, allow
      groups:
        - team-alpha-devs

Application Controller
  --gRPC--> Repository Server (매니페스트 생성 요청)
  --gRPC--> API Server (상태 업데이트)

API Server
  --gRPC--> Repository Server (저장소 검증)
  --HTTP--> Dex (인증)
  --TCP---> Redis (캐시/세션)

Repository Server
  --TCP---> Redis (매니페스트 캐시)
  --HTTPS--> Git Server (저장소 클론)

- API Server가 TLS 인증서를 생성하고 관리
- 각 컴포넌트는 argocd-server-tls Secret에서 인증서 로드
- mTLS(상호 TLS)는 선택적으로 활성화 가능