ArgoCD 설치 및 + 트러블슈팅

ArgoCD 설치 가이드(헬름 기반)

1️⃣ 사전 준비

• 헬름 3.x 이상 설치
• 쿠버네티스 클러스터 접근 권한(kubectl)
• 선택적으로 argocd CLI 설치

---

2️⃣ 반드시 버전을 고정하세요

최신 버전 사용은 권장하지 않음.

이유	설명
예측 불가	시간에 따라 내용이 바뀌며, 재현 불가능한 상태 발생
API 변경 위험	values.yaml 구조 변경 → 배포 실패 가능성
안정성 확보	명시 버전 사용 시 동일한 결과 보장

안정 버전 예시:

helm install argocd argo/argo-cd -n argocd --version 5.46.7

👉 버전 목록 보러 가기

---

3️⃣ 설치 절차

1. 네임스페이스 생성

kubectl create namespace argocd

---

2. 헬름 차트 설치

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update
# 안정된 버전 명시
helm install argocd argo/argo-cd -n argocd --version 5.46.7

---

3. 서비스 상태 확인

kubectl get pods -n argocd

---

4. 웹 UI 접속 (로컬 테스트용)

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

👉 브라우저 접속: https: //localhost:8080

---

5. 초기 관리자 로그인

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

• 아이디: admin
• 비밀번호: 위 명령어로 출력된 값

---

6. ArgoCD CLI 설치 (선택)

# macOS
brew install argocd

# Linux
sudo curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
sudo chmod +x /usr/local/bin/argocd

---

🛠️ 설치 중 트러블슈팅 모음

---

🔐 1. 권한 거부 오류

rpc error: code = PermissionDenied desc = permission denied

✅ 해결 방법

1. 로그인 안 한 경우

argocd login $ARGOCD_SERVER --auth-token=$ARGOCD_TOKEN --grpc-web --insecure

1. RBAC 권한 부족

# argocd-rbac-cm
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.csv: |
    p, role:admin, applications, *, */*, allow
    g, gitlab, role:admin
  policy.default: role:readonly

---

2. EOF 오류 (gRPC 실패)

✅ 해결 방법

• 인증서 문제, 프록시, Istio 설정 확인 필요
• 포트포워딩으로 직접 테스트 가능:

kubectl port-forward svc/argocd-server -n argocd 8080:443
curl https://localhost:8080/api/version -k

---

3. values-dev.yaml: 해당 파일 또는 디렉토리 없음

Error: open <path>/values-dev.yaml: no such file or directory

✅ 해결 방법

• CI/CD 파이프라인에서 values.yaml.template 사용 후 envsubst로생성

envsubst < helm/values.yaml.template > helm/values-dev.yaml

• 해당 파일은 Git에 커밋하거나, 파이프라인 내에서 생성 필요

---

4. 자동 커밋 후 파이프라인 재실행 (불필요한 트리거)

Auto-update values-dev.yaml ## 파이프라인에 들어간 커밋 메세지

✅ 해결 방법

• Git 커밋 시 [CI SKIP] 사용:

git commit -m "auto-update values-dev.yaml [ci skip]"

• 또는 GitLab .gitlab-ci.yml에서다음과 같이 처리:

rules:
  - if: '$CI_COMMIT_MESSAGE =~ /.*\[ci skip\].*/'
    when: never

---

5. Istio 사용 시 웹 UI 접속 오류

• gRPC 및 gRPC-Web 트래픽을 명확히 설정해야 함

apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: argocd
  namespace: istio-system
spec:
  hosts:
    - "argocd.example.com"
  gateways:
    - argocd-gateway
  http:
    - match:
        - uri:
            prefix: /
      route:
        - destination:
            host: argocd-server.argocd.svc.cluster.local
            port:
              number: 80

---

✅ 체크리스트

• ArgoCD 설치를 위한 네임스페이스 생성
• 안정된 헬름 차트 버전으로 ArgoCD 설치
• 서비스 상태 확인
• 웹 UI 접속을 위한 포트포워딩 설정
• 초기 관리자 비밀번호 확인 및 로그인
• (선택 사항) ArgoCD CLI 설치
• Istio 사용 시 웹 UI 접속 오류 해결을 위한 설정 적용