EKS에 ArgoCD 설치하고 GitOps 배포 환경 구축하기
이번 포스팅에서는 AWS EKS 클러스터에 ArgoCD를 설치하고, GitHub 레포지토리와 연동해서 자동 배포까지 설정하는 과정을 정리했다.
ArgoCD란?
Kubernetes 환경에서 GitOps 방식의 배포를 도와주는 툴이다.
쉽게 말하면, GitHub에 코드를 올리면 ArgoCD가 자동으로 감지해서 클러스터에 배포해주는 자동화 배포 도구다.
1. kubeconfig 연결
먼저 로컬 환경에서 EKS 클러스터에 접근할 수 있도록 kubeconfig를 설정해야 한다.
kubectl 명령어가 어느 클러스터를 바라볼지 알려주는 작업이라고 생각하면 된다.
# kubeconfig 연결
aws eks update-kubeconfig --region ap-northeast-2 --name pposiraegi-cluster --profile goorm
# 클러스터 연결 확인
kubectl get nodes--region: 클러스터가 위치한 AWS 리전--name: EKS 클러스터 이름--profile: AWS CLI에 등록된 프로파일 이름
kubectl get nodes로 노드 목록이 출력되면 연결 성공이다.
2. ArgoCD 설치
ArgoCD를 위한 네임스페이스를 먼저 만들고, 공식 매니페스트를 적용해서 설치한다.
# ArgoCD 전용 네임스페이스 생성
kubectl create namespace argocd
# ArgoCD 공식 매니페스트 적용
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# 설치 완료 확인 (모든 Pod가 Running 상태여야 함)
kubectl get pods -n argocd네임스페이스(namespace)란?
쿠버네티스 안에서 리소스를 논리적으로 분리하는 공간이다.
ArgoCD 관련 리소스만 모아두기 위해 별도 네임스페이스를 만든다.
설치 후 kubectl get pods -n argocd를 실행했을 때, 모든 Pod의 STATUS가 Running으로 바뀌면 설치 완료다. (처음엔 ContainerCreating으로 뜨는 게 정상이니 잠깐 기다리자.)
3. ArgoCD UI 접속
ArgoCD는 웹 UI를 제공한다. 외부에 바로 노출하지 않고 포트 포워딩으로 로컬에서 접속할 수 있다.
# 로컬 8080 포트 → ArgoCD 서버 443 포트로 포워딩
kubectl port-forward svc/argocd-server -n argocd 8080:443포트 포워딩이란?
클러스터 내부 서비스를 외부로 노출하지 않고, 내 로컬 PC에서만 접근할 수 있도록 터널을 뚫어주는 것이다.
이 명령어를 실행한 상태로 브라우저에서 https://localhost:8080 에 접속하면 ArgoCD 로그인 화면이 나온다.
⚠️ 브라우저에서 "안전하지 않은 연결"이라고 경고가 뜰 수 있는데, 자체 서명 인증서라서 그렇다. 고급 → 계속 진행을 누르면 된다.
4. 초기 비밀번호 확인
초기 관리자 계정은 admin이고, 비밀번호는 쿠버네티스 시크릿에 저장되어 있다.
Linux / macOS:
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -dWindows (PowerShell):
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | ForEach-Object { [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($_)) }출력된 값이 초기 비밀번호다. 로그인 후에는 보안을 위해 비밀번호를 변경하는 걸 추천한다.
5. ArgoCD App 설정 (GitOps 연동)
이제 핵심이다. ArgoCD가 GitHub 레포지토리를 감시하고 자동으로 배포하도록 Application 리소스를 생성한다.
kubectl apply -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: pposiraegi
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/Goorm4I/pposiraegi-ecommerce-msa # 감시할 GitHub 레포
targetRevision: feat/eks-migration # 대상 브랜치
path: kubernetes # 매니페스트 파일 경로
destination:
server: https://kubernetes.default.svc
namespace: production # 배포할 네임스페이스
syncPolicy:
automated:
prune: true # 레포에서 삭제된 리소스는 클러스터에서도 삭제
selfHeal: true # 클러스터가 레포와 달라지면 자동으로 복구
syncOptions:
- CreateNamespace=true # production 네임스페이스 없으면 자동 생성
EOFyaml 파일로 따로 저장했다면 이렇게 적용할 수도 있다:
kubectl apply -f argocd-app.yaml각 설정의 의미:
| 옵션 | 설명 |
|---|---|
repoURL | ArgoCD가 감시할 GitHub 레포 주소 |
targetRevision | 배포 기준이 될 브랜치 또는 태그 |
path | 해당 브랜치 내에서 K8s 매니페스트가 있는 폴더 |
prune: true | 레포에서 파일 삭제 시 클러스터에서도 리소스 삭제 |
selfHeal: true | 누군가 클러스터를 직접 수정해도 레포 기준으로 자동 복구 |
6. 상태 확인
ArgoCD UI에서 App이 정상적으로 생성된 것을 확인할 수 있다.
Synced + Healthy 상태가 뜨면 GitHub 레포와 클러스터가 정상적으로 연동된 것이다. 이제 해당 브랜치에 커밋을 푸시하면 ArgoCD가 자동으로 감지해서 클러스터에 반영해준다.
마무리
| 단계 | 내용 |
|---|---|
| kubeconfig 연결 | 로컬에서 EKS 클러스터 접근 설정 |
| ArgoCD 설치 | argocd 네임스페이스에 공식 매니페스트 적용 |
| UI 접속 | 포트 포워딩으로 localhost:8080 접속 |
| App 생성 | GitHub 레포와 클러스터 자동 동기화 설정 |
GitOps를 도입하면 배포 이력이 GitHub 커밋 히스토리에 그대로 남고, 문제가 생겼을 때 revert만으로 롤백이 가능해서 운영이 훨씬 편해진다. 처음 설정이 좀 번거롭지만 한 번 해두면 그 이후엔 정말 편하다!
