대상 클러스터 등록

대상 클러스터 등록

Argo CD가 애플리케이션을 배포할 수 있도록 클러스터를 등록하는 방법을 설명합니다.

출처: 문서

본문

클러스터를 등록하면 Argo CD가 해당 클러스터에 애플리케이션을 배포할 수 있습니다. Argo CD가 실행되는 클러스터(로컬 클러스터) 또는 다른 계정이나 리전의 원격 클러스터를 등록할 수 있습니다. 클러스터가 등록된 후, 해당 클러스터에서 애플리케이션을 만들 때까지 Unknown 연결 상태로 유지됩니다. 클러스터 등록 후 Argo CD 애플리케이션을 만들려면 Application 생성을 참고하세요.

사전 요구 사항

  • Argo CD 캐퍼빌리티가 생성된 EKS 클러스터
  • 클러스터와 통신하도록 구성된 kubectl
  • 원격 클러스터의 경우: 적절한 IAM 권한과 접근 항목(access entry)

로컬 클러스터 등록

Argo CD가 실행되는 것과 같은 클러스터에 애플리케이션을 배포하려면 이를 배포 대상으로 등록하세요.

중요

Argo CD 캐퍼빌리티는 로컬 클러스터를 자동으로 등록하지 않습니다. 같은 클러스터에 애플리케이션을 배포하려면 명시적으로 등록해야 합니다. 온라인의 대부분 Argo CD 예시와 호환되도록 클러스터 이름 in-cluster를 사용할 수 있습니다.

참고

Argo CD 캐퍼빌리티 역할과 함께 로컬 클러스터용 EKS 접근 항목이 자동 생성되지만, 기본적으로 Kubernetes RBAC 권한은 부여되지 않습니다. 이는 최소 권한 원칙을 따릅니다. 사용 사례에 따라 Argo CD에 필요한 권한을 직접 구성해야 합니다. 예를 들어 이 클러스터를 원격 클러스터를 관리하는 Argo CD 허브로만 사용한다면 로컬 배포 권한이 필요 없습니다. 구성 옵션은 아래의 접근 항목 RBAC 요구 사항 섹션을 참고하세요.

Argo CD CLI 사용:

argocd cluster add  \
  --aws-cluster-name arn:aws:eks:us-west-2:111122223333:cluster/my-cluster \
  --name local-cluster

Kubernetes 시크릿 사용:

apiVersion: v1
kind: Secret
metadata:
  name: local-cluster
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
stringData:
  name: local-cluster
  server: arn:aws:eks:us-west-2:111122223333:cluster/my-cluster
  project: default

구성을 적용합니다.

kubectl apply -f local-cluster.yaml

참고

server 필드에 Kubernetes API 서버 URL이 아니라 EKS 클러스터 ARN을 사용하세요. 관리형 캐퍼빌리티는 클러스터를 식별하기 위해 ARN을 요구합니다. 기본 kubernetes.default.svc는 지원되지 않습니다.

원격 클러스터 등록

원격 클러스터에 배포하려면:

1단계: 원격 클러스터에 접근 항목 생성

region-code를 원격 클러스터가 있는 AWS 리전으로, remote-cluster를 원격 클러스터 이름으로, ARN을 Argo CD 캐퍼빌리티 역할 ARN으로 바꾸세요.

aws eks create-access-entry \
  --region region-code \
  --cluster-name remote-cluster \
  --principal-arn arn:aws:iam::111122223333:role/ArgoCDCapabilityRole \
  --type STANDARD

2단계: Kubernetes RBAC 권한이 있는 접근 정책 연결

Argo CD가 애플리케이션을 배포하려면 접근 항목에 Kubernetes RBAC 권한이 필요합니다. 빠르게 시작하려면 AmazonEKSClusterAdminPolicy를 사용할 수 있습니다.

aws eks associate-access-policy \
  --region region-code \
  --cluster-name remote-cluster \
  --principal-arn arn:aws:iam::111122223333:role/ArgoCDCapabilityRole \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
  --access-scope type=cluster

중요

AmazonEKSClusterAdminPolicy는 전체 cluster-admin 접근(system:masters와 동일)을 제공합니다. 시작하기에 편리하지만 프로덕션에서 사용해서는 안 됩니다. 프로덕션 환경에서는 접근 항목을 커스텀 Kubernetes 그룹과 연결하고 적절한 Role 또는 ClusterRole 바인딩을 만들어 더 제한적인 권한을 사용하세요. 최소 권한 구성은 아래의 프로덕션 설정 섹션을 참고하세요.

3단계: Argo CD에서 클러스터 등록

Argo CD CLI 사용:

argocd cluster add  \
  --aws-cluster-name arn:aws:eks:us-west-2:111122223333:cluster/remote-cluster \
  --name remote-cluster

Kubernetes 시크릿 사용:

apiVersion: v1
kind: Secret
metadata:
  name: remote-cluster
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
stringData:
  name: remote-cluster
  server: arn:aws:eks:us-west-2:111122223333:cluster/remote-cluster
  project: default

구성을 적용합니다.

kubectl apply -f remote-cluster.yaml

교차 계정 클러스터

서로 다른 AWS 계정의 클러스터에 배포하려면:

  1. 대상 계정에서 소스 계정의 Argo CD IAM 캐퍼빌리티 역할 ARN을 프린시펄로 사용해 대상 EKS 클러스터에 접근 항목을 만듭니다.
  2. 적절한 Kubernetes RBAC 권한이 있는 접근 정책을 연결합니다.
  3. EKS 클러스터 ARN을 사용해 Argo CD에 클러스터를 등록합니다.

추가 IAM 역할 생성이나 신뢰 정책 구성은 필요하지 않습니다. EKS 접근 항목이 교차 계정 접근을 처리합니다. 클러스터 ARN 형식은 리전을 포함하므로, 교차 리전 배포는 같은 리전 배포와 동일한 과정을 사용합니다.

클러스터 등록 확인

등록된 클러스터를 확인합니다.

kubectl get secrets -n argocd -l argocd.argoproj.io/secret-type=cluster

또는 Argo CD UI의 Settings → Clusters에서 클러스터 상태를 확인합니다.

프라이빗 클러스터

Argo CD 캐퍼빌리티는 VPC 피어링이나 특수 네트워킹 구성 없이 완전 프라이빗 EKS 클러스터에 대한 투명한 접근을 제공합니다. AWS가 Argo CD 캐퍼빌리티와 프라이빗 원격 클러스터 간의 연결을 자동으로 관리합니다. ARN을 사용해 프라이빗 클러스터를 등록하기만 하면 됩니다. 추가 네트워킹 설정은 필요하지 않습니다.

접근 항목 RBAC 요구 사항

Argo CD 캐퍼빌리티를 만들면 캐퍼빌리티 역할용 EKS 접근 항목이 자동 생성되지만, 기본적으로 Kubernetes RBAC 권한은 부여되지 않습니다. 이는 의도적인 설계로, 최소 권한 원칙을 따릅니다. 사용 사례에 따라 서로 다른 권한이 필요합니다. 예를 들어:

  • 클러스터를 원격 클러스터를 관리하는 Argo CD 허브로만 사용한다면 로컬 배포 권한이 필요 없습니다.
  • 로컬로 애플리케이션을 배포한다면 클러스터 전체 읽기 접근과 특정 네임스페이스에 대한 쓰기 접근이 필요합니다.
  • CRD를 만들어야 한다면 추가 cluster-admin 권한이 필요합니다.

요구 사항에 따라 Argo CD에 필요한 권한을 직접 구성해야 합니다.

Argo CD의 최소 권한

Argo CD가 오류 없이 작동하려면 두 가지 유형의 권한이 필요합니다.

  • 읽기 권한(클러스터 전체) - Argo CD는 다음을 위해 클러스터 전체의 모든 리소스 유형과 커스텀 리소스 정의(CRD)를 읽을 수 있어야 합니다:
    • 리소스 발견과 상태(health) 검사
    • 원하는 상태와 실제 상태 간 드리프트 감지
    • 배포 전 리소스 검증
  • 쓰기 권한(네임스페이스별) - Argo CD는 Application에 정의된 리소스에 대한 생성, 업데이트, 삭제 권한이 필요합니다:
    • 애플리케이션 워크로드 배포(Deployments, Services, ConfigMaps 등)
    • 커스텀 리소스 적용(애플리케이션에 특화된 CRD)
    • 애플리케이션 수명 주기 관리

빠른 설정

빠르게 시작하거나 테스트, 개발 환경에서는 AmazonEKSClusterAdminPolicy를 사용하세요.

aws eks associate-access-policy \
  --region region-code \
  --cluster-name my-cluster \
  --principal-arn arn:aws:iam::111122223333:role/ArgoCDCapabilityRole \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
  --access-scope type=cluster

중요

AmazonEKSClusterAdminPolicy는 CRD 생성, 클러스터 전체 리소스 수정, 모든 네임스페이스에 배포하는 기능을 포함해 전체 cluster-admin 접근(system:masters와 동일)을 제공합니다. 개발과 POC에는 편리하지만 프로덕션에서 사용해서는 안 됩니다. 프로덕션에서는 아래의 최소 권한 설정을 사용하세요.

최소 권한 프로덕션 설정

프로덕션 환경에서는 다음을 부여하는 커스텀 Kubernetes RBAC를 만드세요.

  • 모든 리소스에 대한 클러스터 전체 읽기 접근(발견과 상태(health) 검사용)
  • 네임스페이스별 쓰기 접근(배포용)

1단계: 접근 항목을 커스텀 Kubernetes 그룹과 연결

aws eks associate-access-policy \
  --region region-code \
  --cluster-name my-cluster \
  --principal-arn arn:aws:iam::111122223333:role/ArgoCDCapabilityRole \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSEditPolicy \
  --access-scope type=namespace,namespaces=app-namespace

2단계: 읽기 접근용 ClusterRole 생성

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: argocd-read-all
rules:
# Read access to all resources for discovery and health checks
- apiGroups: ["*"]
  resources: ["*"]
  verbs: ["get", "list", "watch"]

3단계: 애플리케이션 네임스페이스 쓰기 접근용 Role 생성

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: argocd-deploy
  namespace: app-namespace
rules:
# Full access to deploy application resources
- apiGroups: ["*"]
  resources: ["*"]
  verbs: ["*"]

4단계: 역할을 Kubernetes 그룹에 바인딩

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: argocd-read-all
subjects:
- kind: Group
  name: eks-access-entry:arn:aws:iam::111122223333:role/ArgoCDCapabilityRole
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: argocd-read-all
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: argocd-deploy
  namespace: app-namespace
subjects:
- kind: Group
  name: eks-access-entry:arn:aws:iam::111122223333:role/ArgoCDCapabilityRole
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: argocd-deploy
  apiGroup: rbac.authorization.k8s.io

참고

접근 항목의 그룹 이름 형식은 eks-access-entry: 다음에 프린시펄 ARN입니다. Argo CD가 애플리케이션을 배포해야 하는 각 네임스페이스에 대해 RoleBinding을 반복하세요.

중요

Argo CD는 특정 네임스페이스에만 배포하더라도 상태(health) 검사와 발견을 위해 클러스터 전체의 모든 리소스 유형을 읽을 수 있어야 합니다. 클러스터 전체 읽기 접근이 없으면 Argo CD가 애플리케이션 상태(health)를 확인할 때 오류를 표시합니다.

Projects로 클러스터 접근 제한

spec.destinations에서 허용된 대상 클러스터와 네임스페이스를 구성해 Application이 배포할 수 있는 클러스터와 네임스페이스를 제어하려면 Projects를 사용하세요.

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: production
  namespace: argocd
spec:
  destinations:
  - server: arn:aws:eks:us-west-2:111122223333:cluster/prod-cluster
    namespace: '*'
  - server: arn:aws:eks:eu-west-1:111122223333:cluster/prod-eu-cluster
    namespace: '*'
  sourceRepos:
  - 'https://github.com/example/production-apps'

자세한 내용은 Argo CD Projects 작업을 참고하세요.

추가 리소스

  • Argo CD Projects 작업 - 애플리케이션 구성과 보안 경계 강제
  • Application 생성 - 첫 애플리케이션 배포
  • ApplicationSet 사용 - ApplicationSet으로 여러 클러스터에 배포
  • Argo CD 고려 사항 - 멀티 클러스터 패턴과 교차 계정 설정
  • Declarative Cluster Setup - 업스트림 클러스터 구성 레퍼런스

더 알아보기 (Learn more)