Argo CD 고려 사항

EKS용 Argo CD 캐퍼빌리티를 사용할 때 고려해야 할 중요한 사항을 설명합니다. 계획, 권한, 인증, 멀티 클러스터 배포 패턴을 다룹니다.

출처: 문서

본문

계획

Argo CD를 배포하기 전에 다음을 고려하세요.

리포지토리 전략 - 애플리케이션 매니페스트를 저장할 위치(CodeCommit, GitHub, GitLab, Bitbucket)를 결정하세요. 서로 다른 환경을 위한 리포지토리 구조와 브랜칭 전략을 계획하세요.
RBAC 전략 - 어떤 팀이나 사용자에게 admin, editor, viewer 접근을 줄지 계획하세요. 이를 AWS Identity Center 그룹이나 Argo CD 역할에 매핑하세요.
멀티 클러스터 아키텍처 - 단일 Argo CD 인스턴스에서 여러 클러스터를 관리할지 결정하세요. Argo CD용 전용 관리 클러스터를 사용하는 것을 고려하세요.
애플리케이션 구성 - Application과 ApplicationSet을 어떻게 구성할지 계획하세요. 팀이나 환경별로 애플리케이션을 구성하려면 프로젝트를 사용하는 것을 고려하세요.
동기화 정책 - 애플리케이션을 자동으로 동기화할지 아니면 수동 승인을 요구할지 결정하세요. 개발에서는 자동 동기화가 일반적이고, 프로덕션에서는 수동입니다.

권한

IAM 캐퍼빌리티 역할, 신뢰 정책, 보안 모범 사례에 대한 자세한 정보는 Amazon EKS 캐퍼빌리티 IAM 역할과 EKS 캐퍼빌리티 보안 고려 사항을 참고하세요.

IAM 캐퍼빌리티 역할 개요

Argo CD 캐퍼빌리티 리소스를 만들 때 IAM 캐퍼빌리티 역할을 제공합니다. ACK와 달리 Argo CD는 주로 Kubernetes 리소스를 관리하며 AWS 리소스를 직접 관리하지는 않습니다. 그러나 IAM 캐퍼빌리티 역할은 다음에 필요합니다.

CodeCommit의 프라이빗 Git 리포지토리 접근
인증을 위한 AWS Identity Center 통합
AWS Secrets Manager의 시크릿 접근(구성된 경우)
다른 EKS 클러스터로의 교차 클러스터 배포

CodeCommit 통합

CodeCommit 리포지토리를 사용 중이라면 읽기 권한이 있는 정책을 연결하세요.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codecommit:GitPull"
      ],
      "Resource": "*"
    }
  ]
}

중요

프로덕션에서는 "*" 대신 Resource 필드를 특정 리포지토리 ARN으로 제한하세요.

예시:

"Resource": "arn:aws:codecommit:us-west-2:111122223333:my-app-repo"

이렇게 하면 Argo CD 캐퍼빌리티의 접근이 관리해야 하는 리포지토리로만 제한됩니다.

Secrets Manager 통합

리포지토리 자격 증명을 Secrets Manager에 저장한다면 읽기 접근용 관리형 정책을 연결하세요.

arn:aws:iam::aws:policy/AWSSecretsManagerClientReadOnlyAccess

이 정책에는 secretsmanager:GetSecretValue, secretsmanager:DescribeSecret, KMS 복호화 권한 등 필요한 권한이 포함됩니다.

기본 설정

공개 Git 리포지토리를 사용하는 기본 Argo CD 기능에는 신뢰 정책 외에 추가 IAM 정책이 필요하지 않습니다.

인증

AWS Identity Center 통합

Argo CD 관리형 캐퍼빌리티는 AWS Identity Center(이전 AWS SSO)와 직접 통합하므로, 기존 ID 프로바이더를 인증에 사용할 수 있습니다.

AWS Identity Center 통합을 구성하면:

사용자가 EKS 콘솔을 통해 Argo CD UI에 접근합니다.
AWS Identity Center로 인증합니다(기업 ID 프로바이더로 페더레이션 가능).
AWS Identity Center가 사용자 및 그룹 정보를 Argo CD에 제공합니다.
Argo CD가 구성에 따라 사용자와 그룹을 RBAC 역할에 매핑합니다.
사용자는 접근 권한이 있는 애플리케이션과 리소스만 볼 수 있습니다.

Identity Center 권한 집합으로 접근 간소화

AWS Identity Center는 Argo CD로 작업할 때 두 가지 별개의 인증 경로를 제공합니다.

Argo CD API 인증 - Identity Center가 Argo CD UI와 API에 SSO 인증을 제공합니다. 이는 Argo CD 캐퍼빌리티의 RBAC 역할 매핑을 통해 구성됩니다.
EKS 클러스터 접근 - Argo CD 캐퍼빌리티는 고객 제공 IAM 역할을 사용해 접근 항목(access entry)을 통해 EKS 클러스터에 인증합니다. 이 접근 항목은 수동으로 구성해 권한을 추가하거나 제거할 수 있습니다.

Identity Center 권한 집합을 사용하면 단일 ID로 Argo CD와 EKS 클러스터 모두에 접근하도록 해 ID 관리를 간소화할 수 있습니다. 이는 Argo CD 접근용과 클러스터 접근용 별도 자격 증명을 유지하는 대신 두 시스템에서 하나의 ID만 관리하면 되므로 오버헤드를 줄입니다.

RBAC 역할 매핑

Argo CD에는 AWS Identity Center 사용자와 그룹에 매핑할 수 있는 기본 제공 역할이 있습니다.

ADMIN - 모든 애플리케이션과 설정에 대한 전체 접근. 애플리케이션 생성, 업데이트, 삭제 가능. Argo CD 구성 관리 가능.
EDITOR - 애플리케이션 생성 및 수정 가능. Argo CD 설정 변경이나 애플리케이션 삭제 불가.
VIEWER - 애플리케이션에 대한 읽기 전용 접근. 애플리케이션 상태와 이력 보기 가능. 변경 불가.

참고

역할 이름은 대소문자를 구분하며 대문자여야 합니다(ADMIN, EDITOR, VIEWER).

중요

EKS 캐퍼빌리티의 AWS Identity Center 통합은 Argo CD 캐퍼빌리티당 최대 1,000개의 ID를 지원합니다. ID는 사용자 또는 그룹일 수 있습니다.

멀티 클러스터 배포

Argo CD 관리형 캐퍼빌리티는 멀티 클러스터 배포를 지원하므로 단일 Argo CD 인스턴스에서 개발, 스테이징, 프로덕션 클러스터에 걸쳐 애플리케이션을 관리할 수 있습니다.

멀티 클러스터 작동 방식

Argo CD에 추가 클러스터를 등록하면:

대상 EKS 클러스터를 ARN으로 참조하는 클러스터 시크릿을 만듭니다.
다른 클러스터를 대상으로 하는 Application이나 ApplicationSet을 만듭니다.
Argo CD가 각 클러스터에 연결해 리소스를 배포하고 감시합니다.
단일 Argo CD UI에서 모든 클러스터를 보고 관리합니다.

멀티 클러스터 사전 요구 사항

추가 클러스터를 등록하기 전에:

Argo CD 캐퍼빌리티 역할에 대한 접근 항목을 대상 클러스터에 만듭니다.
Argo CD 캐퍼빌리티와 대상 클러스터 간의 네트워크 연결을 확인합니다.
대상 클러스터에 접근할 IAM 권한을 확인합니다.

클러스터 등록

argocd 네임스페이스의 Kubernetes 시크릿으로 클러스터를 등록합니다.

대상 클러스터 ARN을 가져옵니다. region-code를 대상 클러스터가 있는 AWS 리전으로, target-cluster를 대상 클러스터 이름으로 바꾸세요.

aws eks describe-cluster \
  --region region-code \
  --name target-cluster \
  --query 'cluster.arn' \
  --output text

클러스터 ARN을 사용해 클러스터 시크릿을 만듭니다.

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

중요

server 필드에 Kubernetes API 서버 URL이 아니라 EKS 클러스터 ARN을 사용하세요. 관리형 캐퍼빌리티는 대상 클러스터를 식별하기 위해 ARN을 요구합니다.

시크릿을 적용합니다.

kubectl apply -f cluster-secret.yaml

대상 클러스터에 접근 항목 구성

대상 클러스터에 Argo CD 캐퍼빌리티 역할에 애플리케이션 배포 권한을 부여하는 접근 항목이 있어야 합니다. region-code를 대상 클러스터가 있는 AWS 리전으로, target-cluster를 대상 클러스터 이름으로, ARN을 Argo CD 캐퍼빌리티 역할 ARN으로 바꾸세요.

aws eks create-access-entry \
  --region region-code \
  --cluster-name target-cluster \
  --principal-arn arn:aws:iam::111122223333:role/ArgoCDCapabilityRole \
  --type STANDARD \
  --kubernetes-groups system:masters

참고

프로덕션에서는 system:masters 대신 더 제한적인 Kubernetes 그룹을 사용하는 것을 고려하세요.

프라이빗 클러스터 접근

Argo CD 관리형 캐퍼빌리티는 VPC 피어링이나 특수 네트워킹 구성 없이 완전 프라이빗 EKS 클러스터에 배포할 수 있습니다. AWS가 Argo CD 캐퍼빌리티와 프라이빗 원격 클러스터 간의 연결을 자동으로 관리합니다. 리포지토리 접근 제어와 Argo CD RBAC 정책이 제대로 구성되었는지 확인하세요.

교차 계정 배포

교차 계정 배포를 위해 소스 계정의 Argo CD IAM 캐퍼빌리티 역할을 대상 클러스터의 EKS 접근 항목에 추가합니다.

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

추가 IAM 역할 생성이나 신뢰 정책 구성은 필요하지 않습니다. EKS 접근 항목이 교차 계정 접근을 처리합니다.

모범 사례

정보 원천으로 선언적 소스 사용 - 모든 애플리케이션 매니페스트를 선언적 소스(Git 리포지토리, Helm 레지스트리 또는 OCI 이미지)에 저장해 버전 관리, 감사 추적, 협업을 가능하게 하세요.
적절한 RBAC 구현 - Argo CD에서 누가 애플리케이션에 접근하고 관리할 수 있는지 제어하려면 AWS Identity Center 통합을 사용하세요. Argo CD는 Application 내 리소스(Deployments, Pods, ConfigMaps, Secrets)에 대한 세분화된 접근 제어를 지원합니다.
멀티 환경 배포에 ApplicationSet 사용 - 서로 다른 구성으로 여러 클러스터 또는 네임스페이스에 애플리케이션을 배포하려면 ApplicationSet을 사용하세요.

수명 주기 관리

애플리케이션 동기화 정책

Argo CD가 애플리케이션을 동기화하는 방식을 제어합니다.

수동 동기화 - 애플리케이션이 변경을 동기화하려면 수동 승인이 필요합니다. 프로덕션 환경에 권장됩니다.
자동 동기화 - Git 변경이 감지되면 애플리케이션이 자동으로 동기화합니다. 개발 및 스테이징 환경에서 일반적입니다.
자가 치유 - 클러스터에 가해진 수동 변경을 자동으로 되돌립니다. 클러스터 상태가 Git과 일치하도록 보장합니다.
Pruning - Git에서 제거된 리소스를 자동으로 삭제합니다. 리소스를 삭제할 수 있으므로 주의해서 사용하세요.

애플리케이션 상태(health)

Argo CD는 애플리케이션 상태(health)를 지속적으로 모니터링합니다.

Healthy - 모든 리소스가 예상대로 실행 중
Progressing - 리소스가 생성 또는 업데이트 중
Degraded - 일부 리소스가 정상이 아님
Suspended - 애플리케이션이 일시 중지됨
Missing - 리소스가 클러스터에 없음

동기화 창(sync windows)

애플리케이션을 동기화할 수 있는 시기를 제어하도록 동기화 창을 구성합니다.

유지 관리 창 동안에만 동기화 허용
업무 시간 동안 동기화 차단
특정 시간에 자동 동기화 예약
변경하고 동기화를 중지해야 하는 상황(break-glass 시나리오)에서 동기화 창 사용

더 빠른 동기화를 위한 웹훅 구성

기본적으로 Argo CD는 변경을 감지하기 위해 6분마다 Git 리포지토리를 폴링합니다. 더 빠른 대응 배포를 위해 Git 웹훅을 구성해 변경이 푸시될 때 즉시 동기화를 트리거할 수 있습니다.

웹훅은 여러 이점을 제공합니다.

코드가 푸시될 때 즉시 동기화 응답(분 단위가 아닌 초 단위)
폴링 오버헤드 감소와 시스템 성능 개선
API 속도 제한의 더 효율적인 사용
더 빠른 피드백으로 더 나은 사용자 경험

웹훅 엔드포인트

웹훅 URL은 ${serverUrl}/api/webhook 패턴을 따르며, 여기서 serverUrl은 Argo CD 서버 URL입니다. 서버 URL을 찾으려면 Argo CD 엔드포인트 URL을 참고하세요.

예를 들어 Argo CD 서버 URL이 https://my-argocd-dc855fdf-111122223333.eks-capabilities.us-west-2.amazonaws.com이라면 웹훅 URL은 다음과 같습니다.

https://my-argocd-dc855fdf-111122223333.eks-capabilities.us-west-2.amazonaws.com/api/webhook

Git 프로바이더별 웹훅 구성

GitHub - 리포지토리 설정에서 Argo CD 웹훅 URL로 웹훅을 추가합니다. 콘텐츠 유형을 application/json으로 설정하고 "Just the push event"를 선택합니다.
GitLab - 프로젝트 설정에서 Argo CD 웹훅 URL로 웹훅을 추가합니다. "Push events"와 선택적으로 "Tag push events"를 활성화합니다.
Bitbucket - 리포지토리 설정에서 Argo CD 웹훅 URL로 웹훅을 추가합니다. 트리거로 "Repository push"를 선택합니다.
CodeCommit - CodeCommit 리포지토리 상태 변경에서 트리거되고 Argo CD 웹훅 엔드포인트로 알림을 보내는 Amazon EventBridge 규칙을 만듭니다.

자세한 웹훅 구성 지침은 Argo CD Webhook Configuration을 참고하세요.

참고

웹훅은 폴링을 보완하지 대체하지는 않습니다. Argo CD는 웹훅 알림을 놓치는 경우를 위한 대체 메커니즘으로 리포지토리를 계속 폴링합니다.

다음 단계

Argo CD 사용하기 - Argo CD Application 생성 및 관리 방법 알아보기
Argo CD 캐퍼빌리티 문제 해결 - Argo CD 문제 해결
캐퍼빌리티 리소스 다루기 - Argo CD 캐퍼빌리티 리소스 관리

더 알아보기 (Learn more)

공식 문서