리포지토리 접근 구성

애플리케이션을 배포하기 전에 Argo CD가 Git 리포지토리와 Helm 차트 레지스트리에 접근하도록 구성하는 방법을 설명합니다.

출처: 문서

본문

Argo CD는 GitHub, GitLab, Bitbucket, AWS CodeCommit, AWS ECR에 대해 여러 인증 방법을 지원합니다.

참고

직접 AWS 서비스 통합(ECR Helm 차트, CodeCommit 리포지토리, CodeConnections)의 경우 Repository 구성을 만들지 않고 Application 리소스에서 직접 참조할 수 있습니다. 캐퍼빌리티 역할에 필요한 IAM 권한이 있어야 합니다. 자세한 내용은 Argo CD 권한 구성을 참고하세요.

사전 요구 사항

Argo CD 캐퍼빌리티가 생성된 EKS 클러스터
Kubernetes 매니페스트를 포함하는 Git 리포지토리
클러스터와 통신하도록 구성된 kubectl

참고

AWS CodeConnections는 AWS Cloud 또는 온프레미스에 있는 Git 서버에 연결할 수 있습니다. 자세한 내용은 AWS CodeConnections를 참고하세요.

인증 방법

방법	사용 사례	필요한 IAM 권한
CodeCommit (직접 AWS 서비스 통합)	AWS CodeCommit Git 리포지토리와의 직접 통합. Repository 구성 불필요.	`codecommit:GitPull`
CodeConnections	관리형 인증으로 GitHub, GitLab, Bitbucket에 연결. 연결 설정 필요.	`codeconnections:UseConnection`
ECR OCI Artifacts	OCI Helm 차트와 매니페스트 이미지용 AWS ECR과의 직접 통합. Repository 구성 불필요.	`arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPullOnly`
AWS Secrets Manager (사용자 이름/토큰) (자격 증명 포함 Repository 구성)	개인 액세스 토큰이나 비밀번호 저장. Kubernetes 접근 없이 자격 증명 교체 가능.	`arn:aws:iam::aws:policy/AWSSecretsManagerClientReadOnlyAccess`
AWS Secrets Manager (SSH Key) (자격 증명 포함 Repository 구성)	SSH 키 인증 사용. Kubernetes 접근 없이 자격 증명 교체 가능.	`arn:aws:iam::aws:policy/AWSSecretsManagerClientReadOnlyAccess`
AWS Secrets Manager (GitHub App) (자격 증명 포함 Repository 구성)	개인 키가 있는 GitHub App 인증. Kubernetes 접근 없이 자격 증명 교체 가능.	`arn:aws:iam::aws:policy/AWSSecretsManagerClientReadOnlyAccess`
Kubernetes Secret	클러스터 내 시크릿을 사용하는 표준 Argo CD 방법	없음(권한은 Kubernetes RBAC가 있는 EKS 접근 항목으로 처리)

AWS 서비스 직접 접근

AWS 서비스는 Repository 구성을 만들지 않고 Application 리소스에서 직접 참조할 수 있습니다. 캐퍼빌리티 역할에 필요한 IAM 권한이 있어야 합니다.

CodeCommit 리포지토리

Application에서 CodeCommit 리포지토리를 직접 참조합니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  source:
    repoURL: https://git-codecommit.region.amazonaws.com/v1/repos/repository-name
    targetRevision: main
    path: kubernetes/manifests

필요한 캐퍼빌리티 역할 권한:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "codecommit:GitPull",
      "Resource": "arn:aws:codecommit:region:account-id:repository-name"
    }
  ]
}

CodeConnections

CodeConnections를 통해 GitHub, GitLab, Bitbucket 리포지토리를 참조합니다. 리포지토리 URL 형식은 CodeConnections 연결 ARN에서 파생됩니다.

리포지토리 URL 형식:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  source:
    repoURL: https://codeconnections.region.amazonaws.com/git-http/account-id/region/connection-id/owner/repository.git
    targetRevision: main
    path: kubernetes/manifests

필요한 캐퍼빌리티 역할 권한:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "codeconnections:UseConnection",
      "Resource": "arn:aws:codeconnections:region:account-id:connection/connection-id"
    }
  ]
}

ECR Helm 차트

ECR은 Helm 차트를 OCI 아티팩트로 저장합니다. Argo CD는 이를 참조하는 두 가지 방법을 지원합니다.

Helm 형식(Helm 차트에 권장):

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-helm
  namespace: argocd
spec:
  source:
    repoURL: account-id.dkr.ecr.region.amazonaws.com/repository-name
    targetRevision: chart-version
    chart: chart-name
    helm:
      valueFiles:
        - values.yaml

참고: Helm 형식을 사용할 때는 oci:// 접두사를 포함하지 마세요. 차트 이름을 지정하려면 chart 필드를 사용하세요.

OCI 형식(Kubernetes 매니페스트가 있는 OCI 아티팩트):

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-oci
  namespace: argocd
spec:
  source:
    repoURL: oci://account-id.dkr.ecr.region.amazonaws.com/repository-name
    targetRevision: artifact-version
    path: path-to-manifests

참고: OCI 형식을 사용할 때는 oci:// 접두사를 포함하세요. chart 대신 path 필드를 사용하세요.

필요한 캐퍼빌리티 역할 권한 - 관리형 정책 연결:

arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPullOnly

이 정책에는 필요한 ECR 권한(ecr:GetAuthorizationToken, ecr:BatchGetImage, ecr:GetDownloadUrlForLayer)이 포함됩니다.

AWS Secrets Manager 사용

리포지토리 자격 증명을 Secrets Manager에 저장하고 Argo CD Repository 구성에서 참조합니다. Secrets Manager를 사용하면 Kubernetes RBAC 접근 없이도 자동 자격 증명 교체가 가능합니다. 자격 증명은 Secrets Manager에 대한 IAM 권한으로 교체할 수 있고, Argo CD는 업데이트된 값을 자동으로 읽습니다.

참고

여러 리포지토리에서 자격 증명을 재사용하려면(예: GitHub 조직의 모든 리포지토리) argocd.argoproj.io/secret-type: repo-creds와 함께 리포지토리 자격 증명 템플릿을 사용하세요. 이는 개별 리포지토리 시크릿을 만드는 것보다 더 나은 UX를 제공합니다. 자세한 내용은 Argo CD 문서의 Repository Credentials를 참고하세요.

사용자 이름과 토큰 인증

개인 액세스 토큰이나 비밀번호가 있는 HTTPS 리포지토리:

Secrets Manager에 시크릿 생성:

aws secretsmanager create-secret \
  --name argocd/my-repo \
  --description "GitHub credentials for Argo CD" \
  --secret-string '{"username":"your-username","token":"your-personal-access-token"}'

선택적 TLS 클라이언트 인증서 필드(프라이빗 Git 서버용):

aws secretsmanager create-secret \
  --name argocd/my-private-repo \
  --secret-string '{
    "username":"your-username",
    "token":"your-token",
    "tlsClientCertData":"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi4uLgotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t",
    "tlsClientCertKey":"LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi4uLgotLS0tLUVORCBQUklWQVRFIEtFWS0tLS0t"
  }'

참고

tlsClientCertData와 tlsClientCertKey 값은 base64로 인코딩되어야 합니다.

Secrets Manager를 참조하는 Repository 시크릿 생성:

apiVersion: v1
kind: Secret
metadata:
  name: my-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/your-org/your-repo
  secretArn: arn:aws:secretsmanager:us-west-2:111122223333:secret:argocd/my-repo-AbCdEf
  project: default

SSH 키 인증

SSH 기반 Git 접근의 경우 개인 키를 일반 텍스트로(JSON 아님) 저장합니다.

SSH 개인 키로 시크릿 생성:

aws secretsmanager create-secret \
  --name argocd/my-repo-ssh \
  --description "SSH key for Argo CD" \
  --secret-string "[REDACTED PRIVATE KEY]"

SSH용 Repository 시크릿 생성:

apiVersion: v1
kind: Secret
metadata:
  name: my-repo-ssh
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: [email protected]:your-org/your-repo.git
  secretArn: arn:aws:secretsmanager:us-west-2:111122223333:secret:argocd/my-repo-ssh-AbCdEf
  project: default

GitHub App 인증

개인 키가 있는 GitHub App 인증:

GitHub App 자격 증명으로 시크릿 생성:

aws secretsmanager create-secret \
  --name argocd/github-app \
  --description "GitHub App credentials for Argo CD" \
  --secret-string '{
    "githubAppPrivateKeySecret":"LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQouLi4KLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0=",
    "githubAppID":"123456",
    "githubAppInstallationID":"12345678"
  }'

참고

githubAppPrivateKeySecret 값은 base64로 인코딩되어야 합니다.

GitHub Enterprise용 선택적 필드:

aws secretsmanager create-secret \
  --name argocd/github-enterprise-app \
  --secret-string '{
    "githubAppPrivateKeySecret":"LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQouLi4KLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0=",
    "githubAppID":"123456",
    "githubAppInstallationID":"12345678",
    "githubAppEnterpriseBaseUrl":"https://github.example.com/api/v3"
  }'

GitHub App용 Repository 시크릿 생성:

apiVersion: v1
kind: Secret
metadata:
  name: my-repo-github-app
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/your-org/your-repo
  secretArn: arn:aws:secretsmanager:us-west-2:111122223333:secret:argocd/github-app-AbCdEf
  project: default

리포지토리 자격 증명 템플릿

여러 리포지토리에서 자격 증명을 재사용하려면(예: GitHub 조직이나 사용자의 모든 리포지토리) argocd.argoproj.io/secret-type: repo-creds와 함께 리포지토리 자격 증명 템플릿을 사용하세요. 이는 각 리포지토리에 개별 시크릿을 만드는 것보다 더 나은 UX를 제공합니다.

리포지토리 자격 증명 템플릿 생성:

apiVersion: v1
kind: Secret
metadata:
  name: github-org-creds
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repo-creds
stringData:
  type: git
  url: https://github.com/your-org
  secretArn: arn:aws:secretsmanager:us-west-2:111122223333:secret:argocd/github-org-AbCdEf

이 자격 증명 템플릿은 URL 접두사 https://github.com/your-org와 일치하는 모든 리포지토리에 적용됩니다. 그러면 추가 시크릿을 만들지 않고도 Application에서 이 조직 아래의 모든 리포지토리를 참조할 수 있습니다. 자세한 내용은 Argo CD 문서의 Repository Credentials를 참고하세요.

중요

IAM 캐퍼빌리티 역할에 관리형 정책 arn:aws:iam::aws:policy/AWSSecretsManagerClientReadOnlyAccess를 연결했는지, 또는 secretsmanager:GetSecretValue와 KMS 복호화 권한을 포함한 동등한 권한이 있는지 확인하세요. IAM 정책 구성은 Argo CD 고려 사항을 참고하세요.

AWS CodeConnections 사용

CodeConnections 통합에 대해서는 AWS CodeConnections로 Git 리포지토리 연결을 참고하세요. CodeConnections는 자격 증명을 저장하지 않고 GitHub, GitLab, Bitbucket에 대한 관리형 인증을 제공합니다.

Kubernetes 시크릿 사용

표준 Argo CD 방법으로 자격 증명을 Kubernetes에 직접 저장합니다.

개인 액세스 토큰이 있는 HTTPS:

apiVersion: v1
kind: Secret
metadata:
  name: my-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/your-org/your-repo
  username: your-username
  password: your-personal-access-token

SSH:

apiVersion: v1
kind: Secret
metadata:
  name: my-repo-ssh
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: [email protected]:your-org/your-repo.git
  sshPrivateKey: |
    [REDACTED PRIVATE KEY]

CodeCommit 리포지토리

AWS CodeCommit의 경우 IAM 캐퍼빌리티 역할에 CodeCommit 권한(codecommit:GitPull)을 부여합니다.

리포지토리 구성:

apiVersion: v1
kind: Secret
metadata:
  name: codecommit-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://git-codecommit.us-west-2.amazonaws.com/v1/repos/my-repo
  project: default

자세한 IAM 정책 구성은 Argo CD 고려 사항을 참고하세요.

리포지토리 연결 확인

Argo CD UI의 Settings → Repositories에서 연결 상태를 확인합니다. UI는 연결 상태와 모든 인증 오류를 보여줍니다. Repository 시크릿에는 상태 정보가 포함되지 않습니다.

추가 리소스

대상 클러스터 등록 - 배포용 대상 클러스터 등록
Application 생성 - 첫 Application 만들기
Argo CD 고려 사항 - IAM 권한과 보안 구성
Private Repositories - 업스트림 리포지토리 구성 레퍼런스

더 알아보기 (Learn more)

공식 문서