ArgoCD 2편 — 설치와 초기 설정

Table of contents

• 설치 전 준비
• 네임스페이스 생성과 설치
• 주요 컴포넌트 이해
• admin 비밀번호 확인
• UI 접속
• CLI 설치
• CLI 로그인
• 여기까지의 상태

설치 전 준비

ArgoCD를 설치하려면 당연히 Kubernetes 클러스터가 필요하다. 프로덕션 환경이든 로컬 실습용이든 상관없다. 로컬에서 빠르게 해보고 싶다면 minikube, kind, Docker Desktop 중 하나를 쓰면 된다.

이 글에서는 kubectl이 이미 설치되어 있고, 클러스터에 연결된 상태라고 가정한다. 확인은 간단하다.

kubectl cluster-info

클러스터 정보가 출력되면 준비 완료. 연결이 안 되어 있다면 kubeconfig 설정부터 해야 하니 해당 클러스터의 문서를 참고하자.

네임스페이스 생성과 설치

ArgoCD는 전용 네임스페이스에 설치하는 것이 관례다. argocd라는 이름을 쓰는 게 일반적이고, 공식 문서도 이 이름을 기준으로 작성되어 있다.

네임스페이스를 만들고 ArgoCD를 설치한다.

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

첫 번째 명령이 네임스페이스를 만들고, 두 번째 명령이 ArgoCD의 모든 컴포넌트를 한 번에 설치한다. 공식 리포지토리의 stable 브랜치에서 매니페스트를 직접 가져오는 방식이라, 항상 최신 안정 버전이 설치된다.

설치가 끝나면 어떤 리소스가 만들어졌는지 확인해보자.

kubectl get all -n argocd

Deployment, Service, Pod 등이 쭉 나올 것이다. 모든 Pod이 Running 상태가 될 때까지 잠시 기다린다. 보통 1~2분이면 충분하다.

kubectl wait --for=condition=Ready pod --all -n argocd --timeout=120s

이 명령은 모든 Pod이 Ready 상태가 될 때까지 최대 120초 동안 기다려준다. 터미널에서 멍하니 기다리는 것보다 깔끔한 방법이다.

주요 컴포넌트 이해

설치된 Pod 목록을 보면 여러 개가 떠 있는데, 각각의 역할을 알아두면 트러블슈팅할 때 도움이 된다.

ArgoCD의 주요 컴포넌트가 서로 어떻게 연결되는지 먼저 전체 구조를 보자.

flowchart TB
    User["사용자 (UI / CLI)"]
    APIServer["argocd-server\n(API Server + Web UI)"]
    Dex["argocd-dex-server\n(SSO 인증)"]
    RepoServer["argocd-repo-server\n(Git Clone + 매니페스트 렌더링)"]
    Controller["argocd-application-controller\n(싱크 + 상태 비교)"]
    Redis["argocd-redis\n(캐시)"]
    Git["Git Repository"]
    K8s["Kubernetes Cluster"]

    User -->|"로그인 / 싱크 요청"| APIServer
    APIServer -->|"인증 위임"| Dex
    APIServer -->|"매니페스트 요청"| RepoServer
    APIServer -->|"캐시 읽기/쓰기"| Redis
    RepoServer -->|"clone & render\n(Helm, Kustomize 등)"| Git
    RepoServer -->|"캐시 저장"| Redis
    Controller -->|"렌더링된 매니페스트 조회"| RepoServer
    Controller -->|"실제 상태 비교 & 싱크"| K8s
    Controller -->|"캐시 읽기/쓰기"| Redis

kubectl get pods -n argocd

출력 예시는 이런 형태다.

argocd-application-controller-0       1/1     Running   0          2m
argocd-dex-server-xxx                 1/1     Running   0          2m
argocd-redis-xxx                      1/1     Running   0          2m
argocd-repo-server-xxx                1/1     Running   0          2m
argocd-server-xxx                     1/1     Running   0          2m

• argocd-server: API 서버이자 웹 UI를 제공하는 핵심 컴포넌트. 사용자가 직접 상호작용하는 건 이 녀석이다
• argocd-application-controller: 실제로 Git과 클러스터 상태를 비교하고 싱크를 수행하는 컨트롤러
• argocd-repo-server: Git 리포를 클론하고 매니페스트를 렌더링하는 역할. Helm 차트나 Kustomize 처리도 여기서 한다
• argocd-redis: 캐시 저장소. 컴포넌트 간 데이터 공유에 쓰인다
• argocd-dex-server: SSO(Single Sign-On) 인증을 담당. 외부 인증 연동이 필요 없으면 크게 신경 안 써도 괜찮다

admin 비밀번호 확인

ArgoCD를 처음 설치하면 admin 계정의 초기 비밀번호가 자동 생성된다. 이 비밀번호는 Kubernetes Secret에 저장되어 있다.

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

출력되는 문자열이 초기 비밀번호다. 복사해두자.

이 Secret은 초기 설정용이라 로그인 후 비밀번호를 변경하면 삭제해도 무방하다. 공식 문서에서도 보안을 위해 변경 후 삭제를 권장한다.

# 비밀번호 변경 후 실행
kubectl -n argocd delete secret argocd-initial-admin-secret

UI 접속

ArgoCD 서버는 기본적으로 ClusterIP 타입 Service로 생성된다. 클러스터 외부에서 접속하려면 방법이 필요한데, 로컬 환경에서 가장 빠른 건 port-forward다.

kubectl port-forward svc/argocd-server -n argocd 8080:443

이제 브라우저에서 https://localhost:8080으로 접속할 수 있다. 자체 서명 인증서를 쓰기 때문에 브라우저가 보안 경고를 띄우는데, 로컬 환경이니 무시하고 진행하면 된다.

로그인 화면이 나오면 위에서 확인한 정보로 접속한다.

• Username: admin
• Password: 위에서 복사한 초기 비밀번호

프로덕션 환경에서는 port-forward 대신 Ingress를 설정하는 게 일반적이다. Nginx Ingress Controller나 Traefik을 쓰고 있다면 Ingress 리소스를 만들어 연결하면 된다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server-ingress
  namespace: argocd
  annotations:
    nginx.ingress.kubernetes.io/ssl-passthrough: "true"
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: nginx
  rules:
    - host: argocd.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: argocd-server
                port:
                  number: 443

ssl-passthrough를 쓰는 이유는 ArgoCD 서버가 자체적으로 TLS를 처리하기 때문이다. Ingress에서 TLS를 종료하고 싶다면 ArgoCD 서버에 --insecure 플래그를 추가해야 하는데, 이 부분은 공식 문서를 참고하는 게 좋다.

CLI 설치

웹 UI만으로도 대부분의 작업이 가능하지만, CLI가 있으면 스크립트 자동화나 빠른 조작에 유리하다.

macOS에서는 Homebrew로 간단히 설치할 수 있다.

brew install argocd

Linux에서는 바이너리를 직접 받는다.

curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
rm argocd-linux-amd64

설치 확인은 버전 출력으로 한다.

argocd version --client

CLI 로그인

CLI를 설치했으면 ArgoCD 서버에 로그인한다. port-forward가 실행 중인 상태에서 진행해야 한다.

argocd login localhost:8080

자체 서명 인증서 경고가 나오면 y를 눌러 수락하고, admin 계정과 초기 비밀번호를 입력한다.

로그인에 성공하면 바로 비밀번호를 변경하자.

argocd account update-password

현재 비밀번호와 새 비밀번호를 입력하라는 프롬프트가 뜬다. 변경이 완료되면 앞서 말한 것처럼 초기 비밀번호 Secret을 삭제해도 좋다.

CLI가 제대로 동작하는지 확인하려면 클러스터 목록을 조회해본다.

argocd cluster list

ArgoCD가 설치된 클러스터가 기본으로 등록되어 있을 것이다. https://kubernetes.default.svc 주소로 잡혀 있는데, 이건 ArgoCD가 자기 자신이 돌아가고 있는 클러스터를 in-cluster로 인식하는 것이다.

여기까지의 상태

설치와 초기 설정이 끝났다. 정리하면 이런 상태다.

• ArgoCD가 argocd 네임스페이스에 설치됨
• 웹 UI에 https://localhost:8080으로 접속 가능
• CLI로 로그인 완료, 비밀번호 변경 완료
• 아직 등록된 Application은 없음 — 빈 대시보드가 보이는 게 정상

다음 편에서는 이 빈 대시보드에 첫 번째 Application을 등록해본다. Git 리포를 연결하고, Application CRD의 구조를 뜯어보고, 수동 싱크와 자동 싱크의 차이를 실습한다.

→ 3편: Application 등록