ArgoCD 연재 2편: GitLab Repository 및 대상 EKS 클러스터 연동

1편에서 설치한 ArgoCD 서버가 우리의 소스 코드를 읽어올 수 있도록 GitLab 저장소를 연결하고, 애플리케이션이 실제로 배포될 타겟 EKS 클러스터를 등록하는 과정을 다룹니다.

1. GitLab Repository 연결 (HTTPS Token 방식)

프라이빗 GitLab 저장소에 접근하기 위해 SSH Key 방식 대신, 관리 및 권한 제어가 용이한 Access Token (glpat) 방식으로 진행 합니다.

1) GitLab Service Account 생성 및 Token 발급

일반 사용자 계정에 종속되지 않도록 GitLab에서 제공하는 Service Account 기능을 활용하는 것이 보다 이상적입니다. (GitLab Premium 이상에서 Group/Project 레벨 Service Account 지원)

Service Account 유저 생성:
- Group Settings > Service Accounts 메뉴로 이동합니다.
- Add service account를 클릭하여 새 계정(예: argocd-service-account)을 생성합니다.
- 생성 후 대상 Project(또는 Group)의 Members 설정에서 해당 Service Account 유저를 초대하고 Reporter 이상의 권한을 할당합니다.
Access Token (glpat) 발급:
- 생성된 Service Account의 설정 메뉴(또는 API)를 통해 Personal Access Token을 생성합니다.
- Scopes:
  - read_repository: (필수) Git 저장소 소스코드를 가져오기 위해 필요합니다.
  - read_api: GitLab API를 호출하여 저장소 메타데이터나 커밋 정보 등을 동기화할 때 종종 필요합니다. (특히 고급 연동 시)
  - read_registry: (선택) GitLab Container Registry에 저장된 프라이빗 이미지를 배포하거나 나중에 이미지 업데이터를 연동할 경우 필요합니다.

[TIP] 만약 Free Tier를 사용 중이어서 Service Account 기능이 없다면, 봇 용도의 공용 일반 계정을 별도로 생성하고 해당 계정의 Personal Access Tokens을 발급받아 사용하는 것을 권장합니다.

생성된 토큰(glpat-xxxx...)은 다시 볼 수 없으므로 안전한 곳에 기록해 둡니다.

2) ArgoCD에 저장소 등록

ArgoCD UI를 통하거나 선언적으로 Secret을 생성하여 저장소를 등록할 수 있습니다.

argocd repo add https://gitlab.com/your-group/your-repo.git \
  --username argocd-service-account \
  --password <GITLAB_ACCESS_TOKEN>

성공적으로 연결되면 상태가 Successful로 표시됩니다.

2. 대상 EKS 클러스터 연동

ArgoCD가 설치된 클러스터가 아닌 다른 EKS 클러스터(예: Dev/Prod 환경)에 애플리케이션을 배포하려면, 타겟 클러스터에 권한을 생성하고 ArgoCD 쪽에 클러스터 정보를 등록해야 합니다.

1) 대상 클러스터에 ServiceAccount 및 RBAC 구성

배포 대상이 되는 EKS 클러스터(Target Cluster)에 접근하여 다음 리소스들을 생성합니다.

# 타겟 클러스터에 적용
apiVersion: v1
kind: ServiceAccount
metadata:
  name: argocd-manager
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: argocd-manager-role-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin # 실무에서는 필요한 권한만 부여하는 것을 권장합니다
subjects:
  - kind: ServiceAccount
    name: argocd-manager
    namespace: kube-system

2) Token 및 인증 정보 추출

Kubernetes 1.24 버전부터는 ServiceAccount 생성 시 토큰 정보(Secret)가 자동으로 만들어지지 않습니다. ArgoCD 클러스터 등록을 위해서는 장기(Long-lived) 토큰이 필요하므로 수동으로 Secret 자원을 하나 추가 생성하고 연결해주어야 합니다.

ServiceAccount Token Secret 생성 (타겟 클러스터에 적용)

apiVersion: v1
kind: Secret
metadata:
  name: argocd-manager-token
  namespace: kube-system
  annotations:
    kubernetes.io/service-account.name: argocd-manager
type: kubernetes.io/service-account-token

Secret 생성이 완료되었으면, 아래 명령어를 실행하여 ArgoCD 등록에 필요한 Bearer Token값과 CA(Certificate Authority) Data값을 각각 추출합니다.

Bearer Token 추출 명령어 (출력된 값을 복사해둡니다)

kubectl get secret argocd-manager-token -n kube-system -o jsonpath="{.data.token}" | base64 -d

CA Data 추출 명령어 (Secret 내부의 ca.crt 값은 이미 Base64로 인코딩되어 있으므로 그대로 출력합니다)

kubectl get secret argocd-manager-token -n kube-system -o jsonpath="{.data.ca\.crt}"

3) ArgoCD 클러스터에 대상 클러스터 등록 (선언적 방식)

ArgoCD는 클러스터 정보를 Secret 리소스로 관리합니다. ArgoCD가 설치된 클러스터에서 cluster-resources/dev.yaml과 같이 파일을 생성하여 타겟 클러스터 정보를 등록할 수 있습니다.

cluster-resources/target.yaml

apiVersion: v1
kind: Secret
metadata:
  name: target-cluster-secret
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster # [필수] ArgoCD가 클러스터 인증 정보로 인식하게 함
type: Opaque
stringData:
  name: "target" # ArgoCD UI에 표시될 클러스터 이름
  server: "https://<TARGET_EKS_API_SERVER_ENDPOINT>"
  config: |
    {
      "bearerToken": "<추출한_SERVICEACCOUNT_TOKEN>",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<추출한_CA_DATA>"
      }
    }

파일 작성이 완료되면 kubectl apply를 통해 적용해 줍니다.

kubectl apply -f cluster-resources/target.yaml

정상적으로 적용되었다면 ArgoCD UI의 Settings > Clusters 메뉴에서 target 클러스터가 추가된 것을 확인할 수 있습니다.

다음 편에서는 다수의 애플리케이션을 효율적으로 배포하고 관리하기 위한 App of Apps 패턴과 ApplicationSet에 대해 알아봅니다.

1. GitLab Repository 연결 (HTTPS Token 방식)#

1) GitLab Service Account 생성 및 Token 발급#

2) ArgoCD에 저장소 등록#

2. 대상 EKS 클러스터 연동#

1) 대상 클러스터에 ServiceAccount 및 RBAC 구성#

2) Token 및 인증 정보 추출#

3) ArgoCD 클러스터에 대상 클러스터 등록 (선언적 방식)#