ArgoCD 설치 가이드

1. 개요

본 문서는 gitops 저장소의 /argocd 디렉터리 구조 기반 ArgoCD 7.4.5 버전을 Kubernetes 클러스터에 설치하고, Keycloak OIDC 연동, RBAC 권한, 애플리케이션 등록까지 전체 설치 프로세스를 다룹니다.

2. 사전 요구사항

Kubernetes 클러스터: 1.30 이상
로컬 도구: kubectl, kustomize, helm 설치 완료
인증서: cert-manager를 통한 TLS 인증서 발급 및 네임스페이스 간 복제 구성 완료
DNS 등록: argocd.cnapcloud.com
Keycloak Client 설정: argocd client 생성

3. 디렉터리 구조 및 역할

Makefile: apply, delete, preview, pull 등 배포 자동화 스크립트.
apps/: ArgoCD Application YAML 파일 (메인 앱들 정의).
kustomize/base/: 모든 환경에 공통으로 적용될 리소스 및 원본 Helm Chart.
- secrets/.gpg/: SOPS 암호화/복호화에 사용되는 GPG 키 파일.
kustomize/overlays/dev/: dev 환경을 위한 설정.
- helm/values.yaml: dev 환경에 특화된 ArgoCD 설정 (도메인, OIDC, RBAC 등).

4. 설치 단계

4.1 사전 준비

4.1.1 GPG 키 생성 및 설정 (SOPS용)

ArgoCD repo-server에서 SOPS로 암호화된 secrets를 복호화하려면 GPG 키가 필요합니다.

Step 1: GPG 키 생성 및 내보내기

# GPG 키 생성 (batch 모드, 패스프레이즈 없음)
export KEY_NAME="master"
export KEY_COMMENT="master key for sops"

gpg --batch --full-generate-key <<EOF
%no-protection
Key-Type: 1
Key-Length: 4096
Subkey-Type: 1
Subkey-Length: 4096
Expire-Date: 0
Name-Comment: ${KEY_COMMENT}
Name-Real: ${KEY_NAME}
EOF

# GPG 디렉터리 생성 및 키 내보내기
mkdir -p kustomize/base/configmap/.gpg
gpg --export-secret-keys > kustomize/base/configmap/.gpg/private-master.asc
gpg --export > kustomize/base/secrets/configmap/public-master.asc
# GPG 키가 여러 개인 경우: gpg --export-secret-keys <KEY_ID> > ...

Step 2: Fingerprint 확인 및 .sops.yaml 설정

gpg --list-keys --keyid-format long
# 출력 예시:
# pub   rsa4096/6A08**********0E7D 2024-08-26 [SCEA]      <-- KEY_ID (16자리)
#       9A7968E2B********************30CE0E7D             <-- Fingerprint (40자리)
# uid           [ultimate] master (master key for sops)
# sub   rsa4096/1247*********A661 2024-08-26 [SEA]

# .sops.yaml (프로젝트 루트)
creation_rules:
  - path_regex: .*\.enc\.(yaml|yml|env)$
    pgp: <GPG_FINGERPRINT>  # 위에서 확인한 40자리 Fingerprint

Step 3: GPG 키 Import (다른 환경에서)

gpg --import kustomize/base/secrets/.gpg/public-master.asc
gpg --import kustomize/base/secrets/.gpg/private-master.asc

⚠️ .gpg/ 폴더는 .gitignore에 추가되어 Git에 커밋되지 않습니다. 키 파일은 안전한 별도 저장소에 보관하세요.

4.1.2 Keycloak 설정 (필수)

📖 Keycloak 상세 설치 및 구성 방법은 keycloak/README.md 참조

Step 1: Realm 선택

Keycloak 콘솔 접속 (예: https://keycloak.cnapcloud.com)
Realm 선택: cnap (또는 원하는 realm)

Step 2: Client 생성

Clients > Create client
- Client ID: argocd
- Root URL: https://argocd.cnapcloud.com
- Home URL: https://argocd.cnapcloud.com
- Valid redirect URIs: https://argocd.cnapcloud.com/auth/callback
- Valid post logout redirect URIs: https://argocd.cnapcloud.com/
- Web origins: https://argocd.cnapcloud.com
- Client authentication: ON
- Standard flow: ON

Step 3: Client Secret 복사

Credentials 탭에서 Secret 확인 및 복사 (values.yaml에 필요)

Step 4: Groups Mapper 추가

Client > Mappers > Create
- Mapper type: Group Membership
- Name: groups
- Token Claim Name: groups
- Add to ID token: ON
- Add to access token: ON
- Add to userinfo: ON
- Full group path: OFF

Step 5: Groups 생성

Keycloak console > Groups에서 아래 그룹 생성:
- admin (역할: admin)
- viewer (역할: readonly)

Step 6: Users 생성 및 그룹 할당

Username: admin, Email: admin@cnapcloud.com
Email verified: ON
Set Password (Temporary: OFF)
Groups 탭 > Join Group > admin 할당

4.1.3 네트워크/DNS 설정

Pod 내에서 Ingress 서비스에 접근할 때 hairpin 이슈(Pod이 자신의 Ingress를 거쳐 자신에게 다시 접근하는 순환)를 방지하기 위해 hostAlias 설정 필요:

patches/add-host-alias.yaml: Pod 내 /etc/hosts에 도메인(keycloak.cnapcloud.com)을 Ingress Service의 ClusterIP로 직접 매핑

- op: add
  path: /spec/template/spec/hostAliases
  value:
    - ip: "10.96.224.39"  # Ingress controller 또는 service ClusterIP
      hostnames:
        - "keycloak.cnapcloud.com"

실제 IP는 환경의 Ingress Controller IP 또는 Service ClusterIP로 수정 필요
이를 통해 Pod이 Ingress를 거치지 않고 직접 internal IP로 Keycloak에 접근 가능 (성능 향상 및 순환 요청 방지)

hairpin 이슈가 없는 경우:

CNI 플러그인(예: Calico, Cilium)이 hairpin 모드를 지원하거나 설정된 경우
Pod이 Ingress를 거쳐도 자동으로 internal IP로 재라우팅되는 경우
이 경우 hostAlias 패치를 제거해도 정상 작동함

4.1.4 GitHub 연동 (선택)

Private GitHub repository 접근 시 토큰 준비:

# github-credentials.env 작성
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxx

# SOPS로 암호화
sops -e --output kustomize/base/secrets/sops/github-credentials.enc.env github-credentials.env

4.1.5 TLS 인증서 준비

Ingress TLS용 인증서는 cert-manager의 Certificate 리소스에서 자동 생성됩니다.

cert-manager/kustomize/overlays/dev/resources/cnapcloud-certificate.yaml에서 cnapcloud.com-tls Secret 생성
cert-manager가 설치되어 있고, ClusterIssuer(letsencrypt-cloudflare 등)가 준비되어야 함
인증서가 cicd 네임스페이스로 자동 복제됨 (reflector 설정)

확인 방법:

kubectl get certificate -n cert-manager
kubectl get secret cnapcloud.com-tls -n cicd

4.2 values.yaml 커스터마이징

kustomize/overlays/dev/helm/values.yaml을 환경에 맞게 수정:

4.2.1 기본 도메인

global:
  domain: argocd.cnapcloud.com

4.2.2 Ingress 설정

server:
  ingress:
    enabled: true
    ingressClassName: nginx  # 환경에 맞는 Ingress class
    path: /
    tls: true
    annotations:
      nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
      nginx.ingress.kubernetes.io/ssl-passthrough: "true"
      ingress.annotations.nginx.ingress.kubernetes.io/proxy-buffer-size: 128k
    hosts:
      - argocd.cnapcloud.com
    secretName: cnapcloud.com-tls

4.2.3 Keycloak OIDC 설정

configs:
  cm:
    oidc.config: |
      name: keycloak
      issuer: https://keycloak.cnapcloud.com/realms/cnap
      clientID: argocd
      clientSecret: <발급받은 secret>
      requestedScopes: ["openid", "profile", "email", "groups"]
      logoutURL: https://keycloak.cnapcloud.com/realms/cnap/protocol/openid-connect/logout?client_id=argocd&id_token_hint={{token}}&post_logout_redirect_uri=https://argocd.cnapcloud.com/

4.2.4 RBAC 권한 설정

  rbac:
    create: true
    policy.csv: |
      g, admin, role:admin
      g, viewer, role:readonly

4.2.5 초기 Admin 비밀번호 (선택)

  secret:
    argocdServerAdminPassword: "your-secure-password"

4.3 배포 프로세스

Step 1: Helm Chart 다운로드

cd argocd
make pull

kustomize/base/helm/argo-cd/ 디렉터리에 Helm chart 7.4.5가 다운로드됨

Step 2: 배포 미리보기 (검증)

make preview DEPLOY_ENV=dev

kustomize 빌드 결과 확인
YAML 문법 및 패치 적용 상태 검증

Step 3: Namespace 생성

kubectl create namespace cicd || true

Step 4: 배포 실행 (Apply)

make apply DEPLOY_ENV=dev

ArgoCD 모든 리소스 배포

Pod 상태 확인:

kubectl get pods -n cicd
kubectl get svc -n cicd
kubectl get ingress -n cicd

5. 설치 후 검증

5.1 Pod 상태 확인

kubectl get pods -n cicd
# argocd-server, argocd-repo-server, argocd-controller, argocd-redis 등 Running 상태

5.2 Service 확인

kubectl get svc -n cicd
# argocd-server, argocd-repo-server, argocd-redis 등

5.3 Ingress 확인

kubectl get ingress -n cicd
# argocd-server-ingress 상태 확인

5.4 웹 UI 접속

URL: https://argocd.cnapcloud.com
로그인:
- Keycloak OIDC: “LOGIN VIA KEYCLOAK” 버튼 클릭
- 또는 초기 admin 계정 (username: admin, password: values.yaml에서 설정)

5.5 Keycloak OIDC 연동 확인

ArgoCD UI에서 “LOGIN VIA KEYCLOAK” 클릭
Keycloak 로그인 페이지 리다이렉트 확인
사용자 로그인 후 ArgoCD로 리다이렉트 및 RBAC 권한 적용 확인

5.6 초기 Admin 비밀번호 확인 (OIDC 미사용 시)

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

6. 애플리케이션 등록 및 관리

6.1 AppProject 배포 (필수 사전 단계)

ArgoCD에서 Application을 배포하기 전에 먼저 AppProject를 생성해야 합니다.

kubectl apply -f apps/app-project.yaml -n cicd

app-project.yaml 내용 확인:

database, backend, frontend 등 여러 AppProject 정의
각 프로젝트별 클러스터/네임스페이스/저장소 접근 권한 정의
Application 배포 시 프로젝트 선택 필수

AppProject 상태 확인:

kubectl get appproject -n cicd
kubectl describe appproject database -n cicd

6.2 Sample Application 배포

AppProject 생성 후, 실제 애플리케이션 배포:

kubectl apply -f apps/msa-demo.yaml -n cicd

6.3 Application 상태 확인

kubectl get application -n cicd
argocd app list
argocd app info msa-demo

6.4 Sync 수행

ArgoCD에서 애플리케이션을 동기화하는 방법에는 수동 sync와 자동 sync가 있습니다.

6.4.1 수동 Sync

수동으로 애플리케이션을 즉시 동기화할 수 있습니다.

CLI를 통한 수동 Sync:

# 기본 수동 sync
argocd app sync msa-demo

# 강제 sync (기존 리소스 무시)
argocd app sync msa-demo --force

# Prune 옵션 (Git에 없는 리소스 삭제)
argocd app sync msa-demo --prune

# Dry-run (실제 적용 없이 미리보기)
argocd app sync msa-demo --dry-run

웹 UI를 통한 수동 Sync:

ArgoCD 웹 UI 접속 (https://argocd.cnapcloud.com)
대상 애플리케이션 선택
SYNC 버튼 클릭
옵션 선택:
- Force: 기존 리소스 무시
- Prune: 불필요한 리소스 삭제
SYNCHRONIZE 클릭

6.4.2 자동 Sync

ArgoCD는 Git 변경을 감지하여 자동으로 애플리케이션을 동기화할 수 있습니다.

기본 동작:

Git 리포지토리 폴링 주기: 3분 (180초)
변경 감지 → 상태 계산 → auto-sync 실행
Git 커밋 후 1~3분 내 자동 sync (정상 동작)

자동 Sync 지연 문제 해결:

현재 설정 확인:

kubectl -n cicd get configmap argocd-cm -o yaml

폴링 주기 줄이기 (예: 30초):
```
data:
  timeout.reconciliation: 30s
```

적용:

kubectl -n cicd rollout restart deployment argocd-application-controller

주의: 너무 짧게 설정하면 Git 서버 부하 증가 가능

7. 문제 해결

7.1 Keycloak OIDC 로그인 실패

# 1. oidc-config.yaml 확인
kubectl get cm argocd-cm -n cicd -o yaml | grep oidc.config

# 2. Pod 로그 확인
kubectl logs -n cicd <argocd-server-pod> | grep oidc

# 3. DNS/네트워크 확인
kubectl exec -it <argocd-server-pod> -n cicd -- nslookup keycloak.cnapcloud.com

7.2 Pod 실행 안됨

# Pod 상태 및 오류 메시지 확인
kubectl describe pod <pod-name> -n cicd
kubectl logs <pod-name> -n cicd

7.3 Ingress 접속 불가

# Ingress 상태 확인
kubectl get ingress -n cicd -o wide
kubectl describe ingress argocd-server-ingress -n cicd

# TLS 인증서 확인
kubectl get secret cnapcloud.com-tls -n cicd -o jsonpath="{.data}" | base64 -d

7.4 SOPS 시크릿 디크립션 오류

# SOPS 키 설정 및 재시도
export SOPS_PGP_FP=<PGP fingerprint>
sops -d kustomize/base/secrets/sops/github-credentials.enc.env

8. 배포 관리

8.1 업데이트/재배포

# values.yaml 수정 후
make apply DEPLOY_ENV=dev

8.2 삭제

make delete DEPLOY_ENV=dev

8.3 다른 환경 배포

# prod 환경 오버레이 생성 필요
make apply DEPLOY_ENV=prod

9. 참고 자료

최종 체크리스트
Keycloak Client, Groups, Users 생성 완료
values.yaml 도메인, OIDC, RBAC 설정 완료
cert-manager 설치 및 ClusterIssuer 준비 완료
cert-manager Certificate에서 cnapcloud.com-tls Secret 생성 확인
GitHub 토큰(필요시) SOPS 암호화 완료
make pull 완료
make preview 검증 완료
make apply 배포 완료
Pod 상태 확인 (Running)
Ingress 정상 (ADDRESS 할당)
웹 UI 접속 확인
Keycloak OIDC 로그인 확인