1. 설치 절차

ArgoCD는 GitOps 방식의 쿠버네티스 애플리케이션 배포 도구로, 아래와 같은 단계를 통해 클러스터에 설치할 수 있습니다.

# 공식 GitHub 저장소에서 설치 매니페스트 다운로드
curl -sSL -o argocd-install.yaml https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# 이미지 레지스트리 주소를 내부 레지스트리로 수정 (예: private-registry.example.com)
vim argocd-install.yaml

# YAML을 기반으로 ArgoCD 구성 요소 배포
kubectl create namespace argocd --dry-run=client || true
kubectl apply -n argocd -f argocd-install.yaml

# CLI 도구 설치
curl -LO https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
chmod +x argocd-linux-amd64
sudo mv argocd-linux-amd64 /usr/local/bin/argocd

# 초기 관리자 비밀번호 확인
argocd admin initial-password -n argocd

# 서비스 노출 (NodePort 예시)
kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "NodePort"}}'

설치 후 웹 UI 또는 CLI를 통해 접속하고, 기본 비밀번호를 변경하는 것을 권장합니다.

2. 애플리케이션 등록

Git 저장소에 정의된 쿠버네티스 리소스를 ArgoCD를 통해 동기화하려면 애플리케이션을 생성해야 합니다.

argocd login <ARGOCD_SERVER_IP> --username admin --password <INITIAL_PASSWORD>

# Git 저장소 연결 후 앱 생성
argocd app create my-nginx-app \
  --repo https://github.com/example/my-k8s-manifests.git \
  --path ./nginx/deployment \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

3. 주요 명령어

3.1 애플리케이션 관리

# 앱 상태 조회
argocd app get my-nginx-app

# 동기화 실행
argocd app sync my-nginx-app

# 앱 목록 출력
argocd app list

3.2 계정 및 인증 관리

# 사용자 목록 확인
argocd account list

# 특정 계정 정보 조회
argocd account get --account dev-user

# 비밀번호 갱신
argocd account update-password \
  --account dev-user \
  --current-password old-secret \
  --new-password new-strong-secret

# API 토큰 생성
argocd account generate-token --account ci-bot

# TLS 인증서 기반 서버 보안 설정
kubectl create secret tls argocd-tls-cert \
  -n argocd \
  --cert=./tls.crt \
  --key=./tls.key

4. 핵심 아키텍처 구성 요소

• API Server: HTTP 엔드포인트 제공, 인증/권한 부여, Webhook 처리, 외부 ID 제공자 연동
• Repository Server: Git 저장소 접근, Helm 차트 해석, Kustomize 빌드 수행
• Application Controller: 클러스터 상태 모니터링, 드리프트 감지, 선언형 상태 유지

5. 설정 구성

5.1 주요 ConfigMap 및 Secret

리소스 이름	용도
argocd-cm	전역 설정, 사용자 정의 파라미터, OIDC 설정 포함
argocd-rbac-cm	RBAC 정책 정의 (policy.csv)
argocd-secret	비밀번호, JWT 서명 키, 웹훅 시크릿 보관
argocd-tls-certs-cm	사용자 정의 CA 인증서 저장
argocd-ssh-known-hosts-cm	SSH 호스트 지문 등록

5.2 Application 리소스 예제

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: frontend-service
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: 'https://github.com/company/deploy-configs.git'
    targetRevision: main
    path: apps/frontend
  destination:
    server: 'https://kubernetes.default.svc'
    namespace: frontend
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

5.3 AppProject 리소스 활용

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: production-team
  namespace: argocd
spec:
  description: Production 환경 전용 프로젝트
  sourceRepos:
    - https://github.com/company/production-manifests.git
  destinations:
    - namespace: '*'
      server: https://prod-cluster-api.example.com
  namespaceResourceWhitelist:
    - group: apps
      kind: Deployment
    - group: ""
      kind: Service
  clusterResourceBlacklist:
    - group: rbac.authorization.k8s.io
      kind: ClusterRoleBinding
  roles:
    - name: developer-access
      policies:
        - p, proj:production-team:developer-access, applications, get, production-team/*, allow
        - p, proj:production-team:developer-access, applications, sync, production-team/frontend-app, allow
      groups:
        - oidc:engineering-team

5.4 저장소 인증 설정

HTTPS 기반 Git 저장소

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-repo-creds
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://gitlab.com/company/internal-configs.git
  username: deploy-bot
  password: xxyyzz12345

SSH 기반 저장소

apiVersion: v1
kind: Secret
metadata:
  name: ssh-private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: git@gitlab.com:company/private-charts.git
  sshPrivateKey: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAA...
    -----END OPENSSH PRIVATE KEY-----

Helm 저장소 등록

apiVersion: v1
kind: Secret
metadata:
  name: nexus-helm-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: helm
  name: internal-charts
  url: https://nexus.company.com/helm-charts/
  username: helm-user
  password: secure-password
  tlsClientCertData: base64encodedcert
  tlsClientCertKey: base64encodedkey

6. 보안 및 접근 제어

6.1 사용자 계정 관리

# argocd-cm에 로컬 사용자 추가
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  accounts.ci-runner: login, apiKey
  accounts.ci-runner.enabled: "true"

6.2 관리자 계정 비활성화

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  admin.enabled: "false"

6.3 로그인 실패 제한

다음 환경 변수를 argocd-server 컨테이너에 설정:

• ARGOCD_SESSION_FAILURE_MAX_FAIL_COUNT=5
• ARGOCD_SESSION_FAILURE_WINDOW_SECONDS=300
• ARGOCD_MAX_CONCURRENT_LOGIN_REQUESTS_COUNT=10

6.4 RBAC 정책 설정

# argocd-rbac-cm 예제
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.default: role:readonly
  policy.csv: |
    p, role:admin, *, *, *, allow
    p, role:devops, applications, sync, *, allow
    p, role:viewer, applications, get, *, allow
    g, oidc:dev-group, role:devops
  scopes: '[groups, email]'

7. Tekton과 결합한 CI/CD 파이프라인

7.1 Helm 차트 준비

helm create my-nginx-chart
cd my-nginx-chart
# values.yaml 및 templates 수정
git add .
git commit -m "init helm chart"
git push origin main

7.2 GitOps 기반 배포 흐름

1. Tekton Pipeline에서 코드 빌드 및 이미지 푸시
2. Chart 버전 증가 및 Git 저장소에 커밋
3. ArgoCD가 변경 감지 후 자동 동기화
4. 클러스터 상태가 선언된 대로 갱신됨