스터디(Study)/CI·CD Study

예제로 배우는 Argo CD 2장: Argo CD 시작하기

Chann._.y 2025. 11. 8.

728x90

GitOps의 실질적 구현

1장에서 GitOps의 개념을 이해했다면, 이제 그 철학을 실제로 구현할 수 있는 대표적인 도구인 Argo CD를 살펴볼 차례다.
Argo CD는 깃 리포지터리에 정의된 애플리케이션 상태를 쿠버네티스 클러스터와 자동으로 동기화하는 GitOps 기반 CD(Continuous Delivery) 도구다.

이번 장에서는 Argo CD의 구성 요소, 설치 및 초기 설정, 깃 리포지터리와 클러스터 연결 방법을 정리한다.

1. Argo CD란 무엇인가

1.1 개념 정리

Argo CD는 쿠버네티스 환경에서 GitOps 원칙을 실제로 구현한 도구다.
즉, 깃 리포지터리의 선언적 매니페스트를 읽어, 해당 리소스들이 클러스터에서 동일한 상태로 유지되도록 지속적으로 동기화한다.

Argo CD는 명시적 배포 명령이 필요 없다.
대신 깃에 커밋이 발생하면 Argo CD가 이를 감지하고 쿠버네티스 리소스를 자동으로 조정한다.

“깃 리포지터리의 상태가 곧 쿠버네티스의 상태다.”
이 철학이 Argo CD의 모든 설계의 중심이다.

2. Argo CD의 구조

Argo CD는 내부적으로 API 서버, Repository 서버, Application Controller라는 세 가지 주요 컴포넌트로 구성된다.

구성요소 설명

API Server	CLI, UI, 외부 API와 통신하며 사용자 요청을 처리한다. RBAC, 인증, 접근 제어를 담당한다.
Repository Server	깃 리포지터리를 주기적으로 캐싱하고, 매니페스트를 렌더링한다. Helm, Kustomize, plain YAML 등 다양한 포맷을 지원한다.
Application Controller	실제 쿠버네티스 리소스 상태를 모니터링하고, 깃의 선언 상태와 지속적으로 비교·조정한다.

이 3요소는 GitOps의 4가지 원칙 중

선언적 구성
자동 동기화
지속적 조정
을 완벽히 구현한다.

3. Argo CD의 주요 개념

개념 설명

Application	하나의 애플리케이션 단위를 정의하는 CRD(Custom Resource Definition).
AppProject	여러 Application을 논리적으로 묶은 그룹 단위.
Repository Credentials	프라이빗 깃 리포지터리에 접근하기 위한 자격 증명.
Cluster Credentials	여러 쿠버네티스 클러스터를 관리하기 위한 인증 정보.
Sync Policy	동기화 모드 설정 (자동, 수동, SelfHeal 등).

이 개념들은 모두 쿠버네티스 리소스(YAML) 로 선언적으로 관리할 수 있다.
즉, Argo CD의 설정 자체도 GitOps로 관리가 가능하다.

4. 깃 리포지터리 연결 (Repository Credentials)

Argo CD가 깃 리포지터리의 내용을 읽기 위해서는 접근 권한이 필요하다.
이를 설정하는 방법은 Secret 리소스를 이용하는 것이다.

apiVersion: v1
kind: Secret
metadata:
  name: repo-credentials
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  url: https://github.com/your-org/private-repo.git
  username: your-github-username
  password: ghp_xxxxxxxxxxxxxxxxxxxxxxx

이 Secret을 생성하면, Argo CD가 해당 리포지터리를 자동으로 감지해 매니페스트를 캐싱한다.

5. 클러스터 등록 (Cluster Credentials)

Argo CD는 기본적으로 설치된 쿠버네티스 클러스터를 관리하지만,
필요하다면 여러 외부 클러스터를 동시에 관리할 수도 있다.

방법 1. 매니페스트 방식

apiVersion: v1
kind: Secret
metadata:
  name: cluster-credentials-dev
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
stringData:
  name: dev-cluster
  server: https://123.45.67.89:6443
  config: |
    {
      "bearerToken": "eyJhbGciOi...",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "LS0tLS1..."
      }
    }

방법 2. CLI 방식

argocd cluster add CONTEXT_NAME

이 명령은 현재 kubeconfig 에 설정된 컨텍스트를 Argo CD에 등록한다.

6. Argo CD 설치 (Helm 이용)

6.1 네임스페이스 생성

kubectl create ns argocd

6.2 Helm 값 파일 작성

cat <<EOF > argocd-values.yaml
server:
  service:
    type: NodePort
    nodePortHttps: 30002
  extraArgs:
    - --insecure
EOF

6.3 설치 실행

helm repo add argo https://argoproj.github.io/argo-helm
helm install argocd argo/argo-cd --version 9.0.5 -f argocd-values.yaml -n argocd

6.4 설치 확인

kubectl get pods -n argocd
kubectl get crd | grep argo

6.5 초기 관리자 비밀번호 확인

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

6.6 접속 주소

http://127.0.0.1:30002

브라우저에서 Argo CD UI에 접속하면 기본 계정 admin 으로 로그인할 수 있다.

7. Argo CD CLI 사용

CLI는 API 서버와 직접 통신하며 Application 관리, 동기화 명령 등을 수행한다.

argocd login 127.0.0.1:30002 --plaintext
argocd app list
argocd app create guestbook --repo https://github.com/argoproj/argocd-example-apps --path guestbook --dest-server https://kubernetes.default.svc --dest-namespace default
argocd app sync guestbook

CLI는 강력하지만, GitOps 철학에 맞추려면 UI나 CLI보다는 Git 변경으로 배포를 유도하는 것이 권장된다.

8. 동작 원리

Argo CD의 내부 동작은 다음 세 단계로 요약된다.

깃 리포지터리에서 매니페스트를 가져온다.
쿠버네티스 클러스터의 실제 상태를 비교한다.
차이가 있다면 자동 혹은 수동으로 동기화를 수행한다.

이 루프를 통해 시스템은 항상 깃에 선언된 상태로 유지된다.
즉, “의도한 상태를 보증하는 운영 자동화” 가 완성되는 것이다.

9. 정리

항목 내용

도구	Argo CD
역할	Git 리포지터리 선언 상태를 클러스터와 자동 동기화
핵심 구성 요소	API Server, Repository Server, Application Controller
핵심 개념	Application, Project, Repository Credentials, Cluster Credentials
설치 방법	Helm 설치, 초기 비밀번호 확인 후 UI 접속
운영 방식	깃 커밋 → Argo CD 감지 → 클러스터 동기화

개인적인 인사이트

Argo CD는 단순 배포 자동화 도구가 아니라, 운영의 일관성을 보장하는 제어 루프다.
깃 커밋을 통해 모든 변경이 이루어지므로, 배포 히스토리를 관리하기 쉬워진다.
CI/CD에서 CI는 “코드 빌드”, CD는 “의도된 상태 보정”으로 분리된다는 점이 특히 명확하다.