선언적 설정

선언적 설정 (Declarative Setup)

Argo CD 애플리케이션, 프로젝트, 그리고 설정 값들은 Kubernetes 매니페스트를 이용해 선언적으로 정의할 수 있어요. 이 값들은 argocd 커맨드라인 도구를 건드리지 않고 kubectl apply만으로도 업데이트할 수 있답니다.

출처: 문서

본문

빠른 참조 (Quick Reference)

Application 및 AppProject 스펙을 포함한 모든 리소스는 Argo CD 네임스페이스(기본값은 argocd)에 설치되어 있어야 해요.

원자적 구성 (Atomic configuration)

| 샘플 파일 | 리소스 이름 | 종류 | 설명 | | argocd-cm.yaml | argocd-cm | ConfigMap | 일반 Argo CD 설정 | | argocd-repositories.yaml | my-private-repo / istio-helm-repo / private-helm-repo / private-repo | Secrets | 샘플 저장소 연결 정보 | | argocd-repo-creds.yaml | argoproj-https-creds / argoproj-ssh-creds / github-creds / github-enterprise-creds | Secrets | 샘플 저장소 자격 증명 템플릿 | | argocd-cmd-params-cm.yaml | argocd-cmd-params-cm | ConfigMap | Argo CD 환경 변수 설정 | | argocd-secret.yaml | argocd-secret | Secret | 사용자 비밀번호, 인증서(더 이상 사용되지 않음), 서명 키, Dex 시크릿, 웹훅 시크릿 | | argocd-rbac-cm.yaml | argocd-rbac-cm | ConfigMap | RBAC 설정 | | argocd-tls-certs-cm.yaml | argocd-tls-certs-cm | ConfigMap | HTTPS로 Git 저장소에 연결하기 위한 사용자 지정 TLS 인증서 (v1.2 이상) | | argocd-ssh-known-hosts-cm.yaml | argocd-ssh-known-hosts-cm | ConfigMap | SSH로 Git 저장소에 연결하기 위한 SSH known hosts 데이터 (v1.2 이상) |

각 종류의 ConfigMap과 Secret 리소스에 대해 지원되는 리소스 이름은 위 표에 나열된 단 하나뿐이에요. 만약 값을 합쳐야 한다면 리소스를 생성하기 전에 미리 합쳐두어야 해요.

⚠️ 경고: ConfigMap 리소스에 대해

반드시 ConfigMap 리소스에 app.kubernetes.io/part-of: argocd 라벨을 달아주어야 해요. 그렇지 않으면 Argo CD가 이를 사용할 수 없답니다.

여러 구성 객체 (Multiple configuration objects)

| 샘플 파일 | 종류 | 설명 | | application.yaml | Application | 예제 애플리케이션 스펙 | | project.yaml | AppProject | 예제 프로젝트 스펙 | | argocd-repositories.yaml | Secret | 저장소 자격 증명 |

Application과 AppProject 리소스의 경우, 리소스의 이름이 Argo CD 내부의 애플리케이션 또는 프로젝트 이름과 동일해요. 이는 곧 애플리케이션 이름과 프로젝트 이름이 주어진 Argo CD 설치 환경 내에서 유일(unique)하다는 뜻이에요. 즉, 두 개의 서로 다른 애플리케이션이 같은 이름을 가질 수 없답니다.

애플리케이션 (Applications)

Application CRD는 환경에 배포된 애플리케이션 인스턴스를 나타내는 Kubernetes 리소스 객체예요. 이는 두 가지 핵심 정보로 정의됩니다:

• Git에서의 원하는 상태에 대한 source 참조 (repository, revision, path, environment)
• 대상 클러스터와 네임스페이스에 대한 destination 참조. 클러스터의 경우 server 또는 name 중 하나를 사용할 수 있으며, 둘 다 사용할 수는 없어요(둘 다 쓰면 오류가 발생합니다). 내부적으로 server가 없을 때는 name을 기준으로 계산되어 모든 작업에 사용됩니다.

최소한의 Application 스펙은 다음과 같아요:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook

추가 필드는 application.yaml을 참고해 주세요. Getting Started의 첫 단계를 완료했다면, kubectl apply -n argocd -f application.yaml을 실행해 이 스펙을 적용할 수 있고, Argo CD가 guestbook 애플리케이션의 배포를 시작할 거예요.

참고: 네임스페이스는 Argo CD 인스턴스의 네임스페이스와 일치해야 해요. 일반적으로 이는 argocd입니다.

참고: Helm 저장소에서 애플리케이션을 생성할 때는 spec.source 안의 path 속성 대신 chart 속성을 지정해야 해요.

spec:
  project: default
  source:
    repoURL: https://argoproj.github.io/argo-helm
    chart: argo

⚠️ 경고: resources-finalizer.argocd.argoproj.io finalizer가 없다면, 애플리케이션을 삭제해도 이 애플리케이션이 관리하는 리소스는 삭제되지 않아요. 연쇄 삭제(cascading delete)를 수행하려면 이 finalizer를 추가해야 해요. App Deletion을 참고하세요.

metadata:
  finalizers:
    - resources-finalizer.argocd.argoproj.io

앱 오브 앱스 (App of Apps)

다른 앱을 생성하는 앱을 만들 수 있고, 그 앱들은 또 다른 앱들을 생성할 수 있어요. 이렇게 하면 함께 배포되고 함께 구성될 수 있는 앱 그룹을 선언적으로 관리할 수 있답니다.

클러스터 부트스트래핑(cluster bootstrapping)을 참고하세요.

프로젝트 (Projects)

AppProject CRD는 애플리케이션의 논리적 그룹을 나타내는 Kubernetes 리소스 객체예요. 이는 다음과 같은 핵심 정보로 정의됩니다:

• sourceRepos: 프로젝트 내 애플리케이션이 매니페스트를 가져올 수 있는 저장소에 대한 참조
• destinations: 프로젝트 내 애플리케이션이 배포할 수 있는 클러스터와 네임스페이스에 대한 참조
• roles: 프로젝트 내 리소스에 대한 접근 권한이 정의된 엔티티 목록

⚠️ 경고: Argo CD 네임스페이스에 배포할 수 있는 프로젝트는 관리자 접근 권한을 부여합니다

프로젝트의 destinations 설정이 Argo CD가 설치된 네임스페이스에 배포하는 것을 허용한다면, 해당 프로젝트의 애플리케이션은 관리자 수준의 접근 권한을 갖게 돼요. 관리자 수준 프로젝트에 대한 RBAC 접근은 신중하게 제한해야 하고, 허용된 sourceRepos에 대한 push 접근도 관리자에게만 제한해야 합니다.

예제 스펙은 다음과 같아요:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: my-project
  namespace: argocd
  # Finalizer that ensures that project is not deleted until it is not referenced by any application
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  description: Example Project
  # Allow manifests to deploy from any Git repos
  sourceRepos:
  - '*'
  # Only permit applications to deploy to the guestbook namespace in the same cluster
  destinations:
  - namespace: guestbook
    server: https://kubernetes.default.svc
  # Deny all cluster-scoped resources from being created, except for Namespace
  clusterResourceWhitelist:
  - group: ''
    kind: Namespace
  # Allow all namespaced-scoped resources to be created, except for ResourceQuota, LimitRange, NetworkPolicy
  namespaceResourceBlacklist:
  - group: ''
    kind: ResourceQuota
  - group: ''
    kind: LimitRange
  - group: ''
    kind: NetworkPolicy
  # Deny all namespaced-scoped resources from being created, except for Deployment and StatefulSet
  namespaceResourceWhitelist:
  - group: 'apps'
    kind: Deployment
  - group: 'apps'
    kind: StatefulSet
  roles:
  # A role which provides read-only access to all applications in the project
  - name: read-only
    description: Read-only privileges to my-project
    policies:
    - p, proj:my-project:read-only, applications, get, my-project/*, allow
    groups:
    - my-oidc-group
  # A role which provides sync privileges to only the guestbook-dev application, e.g. to provide
  # sync privileges to a CI system
  - name: ci-role
    description: Sync privileges for guestbook-dev
    policies:
    - p, proj:my-project:ci-role, applications, sync, my-project/guestbook-dev, allow
    # NOTE: JWT tokens can only be generated by the API server and the token is not persisted
    # anywhere by Argo CD. It can be prematurely revoked by removing the entry from this list.
    jwtTokens:
    - iat: 1535390316

저장소 (Repositories)

참고: 일부 Git 호스팅 서비스(특히 GitLab, 그리고 온프레미스 GitLab 인스턴스도 마찬가지)는 저장소 URL에 .git 접미사를 지정하도록 요구해요. 그렇지 않으면 .git이 붙은 저장소 URL로 HTTP 301 리다이렉트를 보내거든요. Argo CD는 이러한 리다이렉트를 따라가지 않으므로, 저장소 URL이 .git 접미사로 끝나게 조정해야 합니다.

저장소 상세 정보는 시크릿(secrets)에 저장돼요. 저장소를 구성하려면 저장소 상세 정보를 담은 시크릿을 생성하면 됩니다. 암호화된 시크릿 정의를 Kubernetes 매니페스트로 저장하려면 bitnami-labs/sealed-secrets 사용을 고려해 보세요. 각 저장소는 url 필드를 가져야 하며, HTTPS, SSH, GitHub App 또는 Azure Service Principal 중 어떻게 연결하느냐에 따라 username과 password(HTTPS의 경우), sshPrivateKey(SSH의 경우), githubAppPrivateKey(GitHub App의 경우) 또는 azureServicePrincipalClientSecret(Azure Service Principal의 경우)을 가져야 해요. 자격 증명은 선택적인 project 필드를 사용해 특정 프로젝트로 범위를 제한할 수 있어요. 이 필드를 생략하면 해당 자격 증명은 범위가 지정된 자격 증명이 없는 모든 프로젝트의 기본값으로 사용됩니다.

⚠️ 경고: bitnami-labs/sealed-secrets를 사용할 때는 라벨이 제거되므로, 여기에 설명된 대로 다시 추가해야 해요: https://github.com/bitnami-labs/sealed-secrets#sealedsecrets-as-templates-for-secrets

HTTPS 예제:

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

SSH 예제:

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

GitHub App 예제:

apiVersion: v1
kind: Secret
metadata:
  name: github-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/argoproj/my-private-repository
  githubAppID: 1
  githubAppInstallationID: 2
  githubAppPrivateKey: |
    [REDACTED PRIVATE KEY]
---
apiVersion: v1
kind: Secret
metadata:
  name: github-enterprise-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://ghe.example.com/argoproj/my-private-repository
  githubAppID: 1
  githubAppInstallationID: 2
  githubAppEnterpriseBaseUrl: https://ghe.example.com/api/v3
  githubAppPrivateKey: |
    [REDACTED PRIVATE KEY]

Google Cloud Source 저장소 예제:

kind: Secret
metadata:
  name: github-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://source.developers.google.com/p/my-google-project/r/my-repo
  gcpServiceAccountKey: |
    {
      "type": "service_account",
      "project_id": "my-google-project",
      "private_key_id": "REDACTED",
      "private_key": "[REDACTED PRIVATE KEY]\n",
      "client_email": "[email protected]",
      "client_id": "REDACTED",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "token_uri": "https://oauth2.googleapis.com/token",
      "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
      "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/argocd-service-account%40my-google-project.iam.gserviceaccount.com"
    }

💡 팁: Kubernetes 문서에 개인 키를 포함하는 시크릿을 생성하는 방법에 대한 안내가 있습니다.

Azure Workload Identity를 사용하는 Azure Container Registry / Azure DevOps 저장소 예제:

Azure Workload Identity를 사용한 Azure Container Registry/Azure Repos를 참고하세요.

Azure Service Principal 예제:

apiVersion: v1
kind: Secret
metadata:
  name: service-principal-for-azure-public-cloud
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://dev.azure.com/my-devops-organization/my-devops-project/_git/my-devops-repo
  azureServicePrincipalClientId: 12345678-1234-1234-1234-123456789012
  azureServicePrincipalTenantId: 12345678-1234-1234-1234-123456789012
  azureServicePrincipalClientSecret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
---
apiVersion: v1
kind: Secret
metadata:
  name: service-principal-for-azure-other-cloud
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://dev.azure.com/my-devops-organization/my-devops-project/_git/my-devops-repo
  azureActiveDirectoryEndpoint: https://login.microsoftonline.de
  azureServicePrincipalClientId: 12345678-1234-1234-1234-123456789012
  azureServicePrincipalTenantId: 12345678-1234-1234-1234-123456789012
  azureServicePrincipalClientSecret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

저장소 자격 증명 (Repository Credentials)

여러 저장소에 동일한 자격 증명을 사용하려면 자격 증명 템플릿을 구성할 수 있어요. 자격 증명 템플릿은 저장소와 동일한 자격 증명 정보를 담을 수 있습니다.

apiVersion: v1
kind: Secret
metadata:
  name: first-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/argoproj/private-repo
---
apiVersion: v1
kind: Secret
metadata:
  name: second-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/argoproj/other-private-repo
---
apiVersion: v1
kind: Secret
metadata:
  name: private-repo-creds
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repo-creds
stringData:
  type: git
  url: https://github.com/argoproj
  password: my-password
  username: my-username

위 예제에서, URL이 https://github.com/argoproj로 시작하는 HTTPS 방식의 모든 저장소는 Git 연결 시 private-repo-creds 시크릿의 username 키에 저장된 사용자 이름과 password 키에 저장된 비밀번호를 사용하게 됩니다.

Argo CD가 특정 저장소에 자격 증명 템플릿을 사용하려면 다음 조건이 충족되어야 해요:

• 해당 저장소가 전혀 구성되지 않았거나, 구성되어 있다 하더라도 어떤 자격 증명 정보도 담고 있지 않아야 함 (즉, sshPrivateKey, username, password 중 어느 것도 없어야 함)
• 자격 증명 템플릿에 구성된 URL (예: https://github.com/argoproj)이 저장소 URL (예: https://github.com/argoproj/argocd-example-apps)의 prefix로 일치해야 함

참고: 자격 증명 템플릿 URL prefix는 최상의 일치(best match) 방식으로 비교돼요. 따라서 가장 길고(가장 좋은) 일치가 우선합니다. 정의 순서는 중요하지 않아요. 이는 v1.4 이전 구성과는 대조적입니다.

자격 증명 시크릿을 참조하는 데 유효한 키는 다음과 같아요:

SSH 저장소

• sshPrivateKey: 저장소에 접근하기 위한 SSH 개인 키를 나타냄

HTTPS 저장소

• username과 password: 저장소에 접근하기 위한 사용자 이름 및/또는 비밀번호를 나타냄
• tlsClientCertData와 tlsClientCertKey: 저장소에 접근하기 위해 TLS 클라이언트 인증서(tlsClientCertData)와 해당 개인 키(tlsClientCertKey)가 저장된 시크릿을 나타냄

GitHub App 저장소

• githubAppPrivateKey: 저장소에 접근하기 위한 GitHub App 개인 키를 나타냄
• githubAppID: 생성한 애플리케이션의 GitHub Application ID를 나타냄
• githubAppInstallationID: 생성하고 설치한 GitHub 앱의 Installation ID를 나타냄
• githubAppEnterpriseBaseUrl: GitHub Enterprise의 기본 API URL을 나타냄 (예: https://ghe.example.com/api/v3)
• tlsClientCertData와 tlsClientCertKey: 사용자 지정 인증서를 사용할 때 GitHub Enterprise에 접근하기 위해 TLS 클라이언트 인증서(tlsClientCertData)와 해당 개인 키(tlsClientCertKey)가 저장된 시크릿을 나타냄

Helm 차트 저장소

Helm 저장소와 OCI 레지스트리에서 가져온 차트에 적용되는 속성은 Helm 섹션을 참고하세요.

자체 서명 TLS 인증서(또는 사용자 지정 CA로 서명)를 사용하는 저장소

저장소 서버의 신뢰성을 검증하는 데 사용되는 TLS 인증서는 argocd-tls-certs-cm이라는 ConfigMap 객체에서 관리할 수 있어요. data 섹션에는 저장소 서버의 호스트네임 부분(전체 URL이 아니라)을 키로 하고, PEM 형식의 인증서를 데이터로 하는 맵이 들어 있어야 합니다. 예를 들어 https://server.example.com/repos/my-repo라는 URL의 저장소에 연결한다면 server.example.com을 키로 사용해야 하는 거예요. 인증서 데이터는 서버의 인증서(자체 서명 인증서인 경우) 또는 서버 인증서를 서명할 때 사용된 CA의 인증서여야 해요. 예를 들어 인증서 롤오버(roll-over)를 계획하고 있다면, 각 서버에 대해 여러 인증서를 구성할 수도 있습니다.

저장소 서버에 대해 전용 인증서가 구성되어 있지 않으면, 서버의 저장소를 검증하는 데 시스템의 기본 신뢰 저장소(default trust store)가 사용됩니다. 이는 GitLab, GitHub, Bitbucket과 같은 대부분의(아니면 모든) 공개 Git 저장소 서비스와, Let's Encrypt 인증서를 포함해 잘 알려진 CA의 인증서를 사용하는 대부분의 사설 호스팅 사이트에 충분히 적합해요.

예제 ConfigMap 객체:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-tls-certs-cm
  namespace: argocd
  labels:
    app.kubernetes.io/name: argocd-cm
    app.kubernetes.io/part-of: argocd
data:
  server.example.com: |
    -----BEGIN CERTIFICATE-----
    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
    XWyb96wrUlv+E8I=
    -----END CERTIFICATE-----

참고: argocd-tls-certs-cm ConfigMap은 argocd-server와 argocd-repo-server 파드의 /app/config/tls 마운트 경로에 볼륨으로 마운트됩니다. data의 각 키에 대해 마운트 경로 디렉터리에 파일을 생성하며, 위 예제는 인증서 데이터를 담은 /app/config/tls/server.example.com 파일을 남기게 돼요. Kubernetes 구성에 따라 ConfigMap의 변경 사항이 파드에 반영되는 데 시간이 걸릴 수 있습니다.

SSH known hosts 공개 키

저장소를 SSH로 구성한다면 Argo CD가 해당 저장소의 SSH 공개 키를 알고 있어야 해요. Argo CD가 SSH로 연결하려면 각 저장소 서버의 공개 키를 Argo CD에 미리 구성해야 합니다(TLS 구성과는 달리요). 그렇지 않으면 저장소 연결이 실패하게 됩니다.

SSH known hosts 데이터는 argocd-ssh-known-hosts-cm ConfigMap에서 관리할 수 있어요. 이 ConfigMap에는 ssh_known_hosts라는 단일 항목이 있으며, 그 값으로 SSH 서버의 공개 키가 들어갑니다. 값은 기존 ssh_known_hosts 파일에서 채우거나, ssh-keyscan 유틸리티(OpenSSH 클라이언트 패키지의 일부)의 출력에서 채울 수 있어요. 기본 형식은 <server_name> <keytype> <base64-encoded_key>이며, 한 줄에 하나씩입니다.

ssh-keyscan 실행 예제:

$ for host in bitbucket.org github.com gitlab.com ssh.dev.azure.com vs-ssh.visualstudio.com ; do ssh-keyscan $host 2> /dev/null ; done
bitbucket.org ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDQeJzhupRu0u0cdegZIa8e86EG2qOCsIsD1Xw0xSeiPDlCr7kq97NLmMbpKTX6Esc30NuoqEEHCuc7yWtwp8dI76EEEB1VqY9QJq6vk+aySyboD5QF61I/1WeTwu+deCbgKMGbUijeXhtfbxSxm6JwGrXrhBdofTsbKRUsrN1WoNgUa8uqN1Vx6WAJw1JHPhglEGGHea6QICwJOAr/6mrui/oB7pkaWKHj3z7d1IC4KWLtY47elvjbaTlkN04Kc/5LFEirorGYVbt15kAUlqGM65pk6ZBxtaO3+30LVlORZkxOh+LKL/BvbZ/iRNhItLqNyieoQj/uh/7Iv4uyH/cV/0b4WDSd3DptigWq84lJubb9t/DnZlrJazxyDCulTmKdOR7vs9gMTo+uoIrPSb8ScTtvw65+odKAlBj59dhnVp9zd7QUojOpXlL62Aw56U4oO+FALuevvMjiWeavKhJqlR7i5n9srYcrNV7ttmDw7kf/97P5zauIhxcjX+xHv4M=
github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=
github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFSMqzJeV9rUzU4kWitGjeR4PWSa29SPqJ1fVkhtj3Hw9xjLVXVYrU9QlYWrOLXBpQ6KWjbjTDTdDkoohFzgbEY=
gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
gitlab.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onrSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9
ssh.dev.azure.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7Hr1oTWqNqOlzGJOfGJ4NakVyIzf1rXYd4d7wo6jBlkLvCA4odBlL0mDUyZ0/QUfTTqeu+tm22gOsv+VrVTMk6vwRU75gY/y9ut5Mb3bR5BV58dKXyq9A9UeB5Cakehn5Zgm6x1mKoVyf+FFn26iYqXJRgzIZZcZ5V6hrE0Qg39kZm4az48o0AUbf6Sp4SLdvnuMa2sVNwHBboS7EJkm57XQPVU3/QpyNLHbWDdzwtrlS+ez30S3AdYhLKEOxAG8weOnyrtLJAUen9mTkol8oII1edf7mWWbWVf0nBmly21+nZcmCTISQBtdcyPaEno7fFQMDD26/s0lfKob4Kw8H
vs-ssh.visualstudio.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7Hr1oTWqNqOlzGJOfGJ4NakVyIzf1rXYd4d7wo6jBlkLvCA4odBlL0mDUyZ0/QUfTTqeu+tm22gOsv+VrVTMk6vwRU75gY/y9ut5Mb3bR5BV58dKXyq9A9UeB5Cakehn5Zgm6x1mKoVyf+FFn26iYqXJRgzIZZcZ5V6hrE0Qg39kZm4az48o0AUbf6Sp4SLdvnuMa2sVNwHBboS7EJkm57XQPVU3/QpyNLHbWDdzwtrlS+ez30S3AdYhLKEOxAG8weOnyrtLJAUen9mTkol8oII1edf7mWWbWVf0nBmly21+nZcmCTISQBtdcyPaEno7fFQMDD26/s0lfKob4Kw8H

위 ssh-keyscan 출력을 사용한 예제 ConfigMap 객체:

apiVersion: v1
kind: ConfigMap
metadata:
  labels:
    app.kubernetes.io/name: argocd-ssh-known-hosts-cm
    app.kubernetes.io/part-of: argocd
  name: argocd-ssh-known-hosts-cm
data:
  ssh_known_hosts: |
    # This file was automatically generated by hack/update-ssh-known-hosts.sh. DO NOT EDIT
    [ssh.github.com]:443 ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
    [ssh.github.com]:443 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
    [ssh.github.com]:443 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=
    bitbucket.org ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBPIQmuzMBuKdWeF4+a2sjSSpBK0iqitSQ+5BM9KhpexuGt20JpTVM7u5BDZngncgrqDMbWdxMWWOGtZ9UgbqgZE=
    bitbucket.org ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIazEu89wgQZ4bqs3d63QSMzYVa0MuJ2e2gKTKqu+UUO
    bitbucket.org ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDQeJzhupRu0u0cdegZIa8e86EG2qOCsIsD1Xw0xSeiPDlCr7kq97NLmMbpKTX6Esc30NuoqEEHCuc7yWtwp8dI76EEEB1VqY9QJq6vk+aySyboD5QF61I/1WeTwu+deCbgKMGbUijeXhtfbxSxm6JwGrXrhBdofTsbKRUsrN1WoNgUa8uqN1Vx6WAJw1JHPhglEGGHea6QICwJOAr/6mrui/oB7pkaWKHj3z7d1IC4KWLtY47elvjbaTlkN04Kc/5LFEirorGYVbt15kAUlqGM65pk6ZBxtaO3+30LVlORZkxOh+LKL/BvbZ/iRNhItLqNyieoQj/uh/7Iv4uyH/cV/0b4WDSd3DptigWq84lJubb9t/DnZlrJazxyDCulTmKdOR7vs9gMTo+uoIrPSb8ScTtvw65+odKAlBj59dhnVp9zd7QUojOpXlL62Aw56U4oO+FALuevvMjiWeavKhJqlR7i5n9srYcrNV7ttmDw7kf/97P5zauIhxcjX+xHv4M=
    github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
    github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
    github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=
    gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFSMqzJeV9rUzU4kWitGjeR4PWSa29SPqJ1fVkhtj3Hw9xjLVXVYrU9QlYWrOLXBpQ6KWjbjTDTdDkoohFzgbEY=
    gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
    gitlab.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onrSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9
    ssh.dev.azure.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7Hr1oTWqNqOlzGJOfGJ4NakVyIzf1rXYd4d7wo6jBlkLvCA4odBlL0mDUyZ0/QUfTTqeu+tm22gOsv+VrVTMk6vwRU75gY/y9ut5Mb3bR5BV58dKXyq9A9UeB5Cakehn5Zgm6x1mKoVyf+FFn26iYqXJRgzIZZcZ5V6hrE0Qg39kZm4az48o0AUbf6Sp4SLdvnuMa2sVNwHBboS7EJkm57XQPVU3/QpyNLHbWDdzwtrlS+ez30S3AdYhLKEOxAG8weOnyrtLJAUen9mTkol8oII1edf7mWWbWVf0nBmly21+nZcmCTISQBtdcyPaEno7fFQMDD26/s0lfKob4Kw8H
    vs-ssh.visualstudio.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7Hr1oTWqNqOlzGJOfGJ4NakVyIzf1rXYd4d7wo6jBlkLvCA4odBlL0mDUyZ0/QUfTTqeu+tm22gOsv+VrVTMk6vwRU75gY/y9ut5Mb3bR5BV58dKXyq9A9UeB5Cakehn5Zgm6x1mKoVyf+FFn26iYqXJRgzIZZcZ5V6hrE0Qg39kZm4az48o0AUbf6Sp4SLdvnuMa2sVNwHBboS7EJkm57XQPVU3/QpyNLHbWDdzwtrlS+ez30S3AdYhLKEOxAG8weOnyrtLJAUen9mTkol8oII1edf7mWWbWVf0nBmly21+nZcmCTISQBtdcyPaEno7fFQMDD26/s0lfKob4Kw8H

참고: argocd-ssh-known-hosts-cm ConfigMap은 argocd-server와 argocd-repo-server 파드의 /app/config/ssh 마운트 경로에 볼륨으로 마운트됩니다. 이 디렉터리에 Argo CD가 SSH로 Git 저장소에 연결할 때 사용하는 SSH known hosts 데이터를 담은 ssh_known_hosts 파일이 생성됩니다. Kubernetes 구성에 따라 ConfigMap의 변경 사항이 파드에 반영되는 데 시간이 걸릴 수 있습니다.

프록시로 저장소 구성하기 (Configure repositories with proxy)

저장소의 프록시는 저장소 시크릿의 proxy 필드와 함께, 해당하는 noProxy 설정으로 지정할 수 있어요. Argo CD는 이 proxy/noProxy 설정을 이용해 저장소에 접근하고 관련 Helm/kustomize 작업을 수행합니다. 사용자 지정 프록시 설정이 없으면 Argo CD는 저장소 서버의 표준 프록시 환경 변수를 찾아봅니다.

proxy와 noProxy가 있는 저장소 예제:

apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/argoproj/private-repo
  proxy: https://proxy-server-url:8888
  noProxy: ".internal.example.com,company.org,10.123.0.0/16"
  password: my-password
  username: my-username

noProxy에 대한 참고: Argo CD는 helm과 kustomize 같은 다양한 도구와 상호작용하기 위해 exec를 사용해요. 이 도구들 모두가 httpproxy go 패키지와 동일한 noProxy 문법을 지원하는 것은 아닙니다. noProxy가 적용되지 않는 문제가 발생한다면, 와일드카드 패턴이나 IP 범위 대신 전체 도메인을 사용해서 모든 도구가 지원하는 공통 문법을 찾아보는 게 좋아요.

클러스터 (Clusters)

클러스터 자격 증명은 저장소나 저장소 자격 증명과 마찬가지로 시크릿에 저장됩니다. 각 시크릿에는 argocd.argoproj.io/secret-type: cluster 라벨이 있어야 해요.

시크릿 데이터에는 다음 필드가 포함되어야 합니다:

• name: 클러스터 이름
• server: 클러스터 API 서버 URL
• namespaces: 선택 사항. 해당 클러스터에서 접근할 수 있는 네임스페이스의 쉼표로 구분된 목록. 네임스페이스 값을 설정하면 클러스터 수준 리소스는 무시됩니다. 단, clusterResources가 true로 설정된 경우는 예외예요.
• clusterResources: 선택 사항. Argo CD가 이 클러스터의 클러스터 수준 리소스를 관리할 수 있는지 여부를 결정하는 불리언 문자열("true" 또는 "false"). 이 설정은 namespaces 리스트로 네임스페이스가 제한된 경우에만 사용됩니다.
• project: 선택 사항. 이를 프로젝트 범위의 클러스터로 지정하는 문자열
• config: 다음 데이터 구조의 JSON 표현:

# Basic authentication settings
username: string
password: string
# Bearer authentication settings
bearerToken: string
# IAM authentication configuration
awsAuthConfig:
    clusterName: string
    roleARN: string
    profile: string
# Configure external command to supply client credentials
# See https://godoc.org/k8s.io/client-go/tools/clientcmd/api#ExecConfig
execProviderConfig:
    command: string
    args: [
      string
    ]
    env: {
      key: value
    }
    apiVersion: string
    installHint: string
# Proxy URL for the kubernetes client to use when connecting to the cluster api server
proxyUrl: string
# Transport layer security configuration settings
tlsClientConfig:
    # Base64 encoded PEM-encoded bytes (typically read from a client certificate file).
    caData: string
    # Base64 encoded PEM-encoded bytes (typically read from a client certificate file).
    certData: string
    # Server should be accessed without verifying the TLS certificate
    insecure: boolean
    # Base64 encoded PEM-encoded bytes (typically read from a client certificate key file).
    keyData: string
    # ServerName is passed to the server for SNI and is used in the client to check server
    # certificates against. If ServerName is empty, the hostname used to contact the
    # server is used.
    serverName: string
# Disable automatic compression for requests to the cluster 
disableCompression: boolean

⚠️ 중요: namespaces가 설정되면 Argo CD는 각 네임스페이스에 대해 별도의 list/watch 작업을 수행해요. 이로 인해 Application 컨트롤러가 Kubernetes API 서버에 허용된 최대 유휴 연결(idle connections) 수를 초과할 수 있습니다. 이 문제를 해결하려면 Application 컨트롤러의 ARGOCD_K8S_CLIENT_MAX_IDLE_CONNECTIONS 환경 변수를 늘리면 됩니다.

⚠️ 중요: execProviderConfig 아래 실행할 명령을 지정한다면, 그 명령은 Argo CD 이미지에 존재해야 해요. BYOI (Build Your Own Image)를 참고하세요.

클러스터 시크릿 예제:

apiVersion: v1
kind: Secret
metadata:
  name: mycluster-secret
  labels:
    argocd.argoproj.io/secret-type: cluster
type: Opaque
stringData:
  name: mycluster.example.com
  server: https://mycluster.example.com
  config: |
    {
      "bearerToken": "<authentication token>",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<base64 encoded certificate>"
      }
    }

클러스터 재조정 건너뛰기 (Skipping Cluster Reconciliation)

클러스터를 대상으로 하는 모든 앱의 재조정(reconciliation)을 방지하려면 해당 클러스터의 시크릿에 argocd.argoproj.io/skip-reconcile: "true" 어노테이션을 달아주면 돼요. 이는 Skip Application Reconcile과 같은 어노테이션이지만 클러스터 수준에서 적용되는 거예요.

클러스터는 API 응답(argocd cluster list)에는 계속 표시되지만, 컨트롤러는 이를 관리되지 않는(unmanaged) 것으로 취급합니다.

apiVersion: v1
kind: Secret
metadata:
  name: mycluster-secret
  labels:
    argocd.argoproj.io/secret-type: cluster
  annotations:
    argocd.argoproj.io/skip-reconcile: "true"
type: Opaque
stringData:
  name: mycluster.example.com
  server: https://mycluster.example.com
  config: |
    {
      "bearerToken": "<authentication token>",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<base64 encoded certificate>"
      }
    }

기존 클러스터를 건너뛰려면:

kubectl -n argocd annotate secret mycluster-secret argocd.argoproj.io/skip-reconcile=true

재조정을 재개하려면:

kubectl -n argocd annotate secret mycluster-secret argocd.argoproj.io/skip-reconcile-

EKS

argocd-k8s-auth, IRSA, Pod Identity를 사용하는 EKS 클러스터 시크릿 예제:

apiVersion: v1
kind: Secret
metadata:
  name: mycluster-secret
  labels:
    argocd.argoproj.io/secret-type: cluster
type: Opaque
stringData:
  name: "eks-cluster-name-for-argo"
  server: "https://xxxyyyzzz.xyz.some-region.eks.amazonaws.com"
  config: |
    {
      "awsAuthConfig": {
        "clusterName": "my-eks-cluster-name",
        "roleARN": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_ROLE_NAME>"
      },
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<base64 encoded certificate>"
      }        
    }

이 설정에는 다음이 필요합니다:

1. Argo CD EKS 클러스터에 IRSA를 활성화하거나 Pod Identity 에이전트를 활성화할 것
2. 적절한 신뢰 정책(trust policy)과 권한 정책(permission policies)을 가진 Argo CD EKS 클러스터용 IAM 역할("관리 역할") (아래 참고)
3. Argo CD 관리 역할이 맡을 수 있는(assumable), Argo CD에 추가되는 각 클러스터용 역할 생성
4. Argo CD에 추가되는 각 EKS 클러스터에 클러스터의 역할(3번 항목)에게 클러스터 내에서 작업을 수행할 RBAC 권한을 부여하는 Access Entry. 또는 Argo CD에 추가되는 클러스터 내 aws-auth ConfigMap에 항목을 추가하는 방법(이 방법은 EKS에서 더 이상 사용하지 않음)

Argo CD 관리 역할 (Argo CD Management Role)

Argo CD용으로 생성된 역할("관리 역할")은 특정 Argo CD 서비스 계정과 자기 자신이 맡을 수 있도록 적절한 신뢰 정책을 가져야 합니다.

이 역할을 맡아야 하는 서비스 계정은 다음과 같습니다:

• argocd-application-controller
• argocd-applicationset-controller
• argocd-server

이 목적을 위해 arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ARGO_CD_MANAGEMENT_IAM_ROLE_NAME> 역할을 생성한다면, 다음은 이 요구에 적합한 예제 신뢰 정책이에요. Argo CD 클러스터에 IAM OIDC 공급자가 구성되어 있거나 Pod Identity 에이전트가 실행 중인지 확인하세요.

IRSA용:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ExplicitSelfRoleAssumption",
            "Effect": "Allow",
            "Principal": {
                "AWS": "*"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "ArnLike": {
                  "aws:PrincipalArn": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ARGO_CD_MANAGEMENT_IAM_ROLE_NAME>"
                }
            }
        },
        {
            "Sid": "ServiceAccountRoleAssumption",
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::<AWS_ACCOUNT_ID>:oidc-provider/oidc.eks.<AWS_REGION>.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "oidc.eks.<AWS_REGION>.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": [
                        "system:serviceaccount:argocd:argocd-application-controller",
                        "system:serviceaccount:argocd:argocd-applicationset-controller",
                        "system:serviceaccount:argocd:argocd-server"
                    ],
                    "oidc.eks.<AWS_REGION>.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

Pod Identity용:

{
    "Version":"2012-10-17",              
    "Statement": [
        {
            "Sid": "AllowEksAuthToAssumeRoleForPodIdentity",
            "Effect": "Allow",
            "Principal": {
                "Service": "pods.eks.amazonaws.com"
            },
            "Action": [
                "sts:AssumeRole",
                "sts:TagSession"
            ],
            "Condition": {
                "StringEquals": {
                    "aws:RequestTag/kubernetes-namespace": [
                        "argocd"
                    ],
                    "aws:RequestTag/kubernetes-service-account": [
                        "argocd-server",
                        "argocd-application-controller",
                        "argocd-applicationset-controller"
                    ]
                }
            }
        }
    ]
}

Argo CD 서비스 계정 (Argo CD Service Accounts)

3개의 서비스 계정은 Argo CD 관리 역할 ARN을 담은 어노테이션이 포함되도록 수정되어야 해요.

다음은 argocd-application-controller, argocd-applicationset-controller, argocd-server의 예제 서비스 계정 구성입니다.

⚠️ 경고: 서비스 계정에 어노테이션이 설정되면 application controller와 server 파드를 재시작해야 합니다.

IRSA용:

apiVersion: v1
kind: ServiceAccount
metadata:
  annotations:
    eks.amazonaws.com/role-arn: "<arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ARGO_CD_MANAGEMENT_IAM_ROLE_NAME>"
  name: argocd-application-controller
---
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations:
    eks.amazonaws.com/role-arn: "<arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ARGO_CD_MANAGEMENT_IAM_ROLE_NAME>"
  name: argocd-applicationset-controller
---
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations:
    eks.amazonaws.com/role-arn: "<arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ARGO_CD_MANAGEMENT_IAM_ROLE_NAME>"
  name: argocd-server

Pod Identity용:

aws eks associate-pod-identity -- cluster-name <EKS_CLUSTER_NAME> --namespace argocd --service-account argocd-applicationset-controller --role-arn arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ARGO_CD_MANAGEMENT_IAM_ROLE_NAME>
aws eks associate-pod-identity -- cluster-name <EKS_CLUSTER_NAME> --namespace argocd --service-account argocd-application-controller --role-arn arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ARGO_CD_MANAGEMENT_IAM_ROLE_NAME>
aws eks associate-pod-identity -- cluster-name <EKS_CLUSTER_NAME> --namespace argocd --service-account argocd-server --role-arn arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ARGO_CD_MANAGEMENT_IAM_ROLE_NAME>

IAM 권한 정책 (IAM Permission Policy)

Argo CD 관리 역할(예제에서는 arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ARGO_CD_MANAGEMENT_IAM_ROLE_NAME>)은 Argo CD에 추가되는 각 클러스터에 대한 역할을 맡을 수 있도록 추가로 허용되어야 해요.

Argo CD에 추가하는 EKS 클러스터에 대해 <IAM_CLUSTER_ROLE>이라는 이름의 역할을 생성한다면, Argo CD 관리 역할의 권한 정책에 다음을 포함하도록 업데이트하게 됩니다:

IRSA용:

{
    "Version" : "2012-10-17",
    "Statement" : {
      "Effect" : "Allow",
      "Action" : "sts:AssumeRole",
      "Resource" : [
        "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_CLUSTER_ROLE>"
      ]
    }
  }

Pod Identity용:

{
    "Version" : "2012-10-17",
    "Statement" : {
      "Effect" : "Allow",
      "Action" : [
        "sts:AssumeRole",
        "sts:TagSession"
      ],
      "Resource" : [
        "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_CLUSTER_ROLE>"
      ]
    }
  }

이렇게 하면 Argo CD 관리 역할이 클러스터 역할을 맡을 수 있게 됩니다.

Argo CD가 관리하는 각 클러스터에 대해 위와 같은 권한을 Argo CD 관리 역할에 추가할 수 있어요(클러스터마다 새 역할을 만든다고 가정).

클러스터 역할 신뢰 정책 (Cluster Role Trust Policies)

앞서 설명했듯이, Argo CD에 추가되는 각 EKS 클러스터는 각자의 역할을 가져야 해요. 이 역할은 권한 정책을 가지면 안 됩니다. 대신 이 역할은 EKS 클러스터의 API에 대해 인증하는 데 사용됩니다. Argo CD 관리 역할이 이 역할을 맡고, argocd-k8s-auth를 통해 AWS API를 호출해 인증 토큰을 얻습니다. 그 토큰은 추가된 클러스터의 API 엔드포인트에 연결할 때 사용돼요.

Argo CD에 추가되는 클러스터에 대해 arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_CLUSTER_ROLE> 역할을 생성한다면, 그 신뢰 정책을 Argo CD 관리 역할이 이를 맡을 수 있도록 설정해야 합니다. 위에서 Argo CD 관리 역할에게 이 역할을 맡을 권한을 부여했지만, 클러스터 역할의 신뢰 정책을 통해서도 해당 동작을 허용해 주어야 합니다.

IAM_CLUSTER_ROLE이 ARGO_CD_MANAGEMENT_IAM_ROLE_NAME 역할에 의해 맡아질 수 있도록 허용하는 적합한 신뢰 정책은 다음과 같습니다:

IRSA용:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ARGO_CD_MANAGEMENT_IAM_ROLE_NAME>"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Pod Identity용:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ARGO_CD_MANAGEMENT_IAM_ROLE_NAME>"
            },
            "Action": [
                "sts:TagSession",
                "sts:AssumeRole"
            ]
        }
    ]
}

액세스 항목 (Access Entries)

각 클러스터의 역할(예: arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_CLUSTER_ROLE>)은 권한 정책이 없어요. 대신 이 역할을 EKS 권한 정책과 연결해, 그 역할이 클러스터 API에 대한 인증 토큰을 생성할 수 있는 능력을 부여합니다. 이 EKS 권한 정책이 해당 과정에서 어떤 RBAC 권한이 부여되는지 결정합니다.

액세스 항목(그리고 역할에 연결된 정책)은 다음 명령으로 만들 수 있습니다:

# For each cluster being added to Argo CD
aws eks create-access-entry \
    --cluster-name my-eks-cluster-name \
    --principal-arn arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_CLUSTER_ROLE> \
    --type STANDARD \
    --kubernetes-groups [] # No groups needed

aws eks associate-access-policy \
    --cluster-name my-eks-cluster-name \
    --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
    --access-scope type=cluster \
    --principal-arn arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_CLUSTER_ROLE>

위 역할은 AmazonEKSClusterAdminPolicy를 통해 클러스터 관리자 권한을 부여받습니다. 이 역할을 맡는 Argo CD 관리 역할은, 관련 EKS 클러스터를 추가할 때 API 토큰을 생성하면 동일한 클러스터 관리자 권한을 얻게 됩니다.

AWS Auth (더 이상 사용되지 않음)

액세스 항목(Access Entries) 대신, 더 이상 사용되지 않는 aws-auth를 사용해야 할 수도 있어요.

그렇다면 각 관리 클러스터의 roleARN을 각 클러스터의 aws-auth config map에 추가해야 합니다(클러스터에 IAM 프린시펄 접근 활성화를 참고). 또한 Argo CD 파드 역할이 이를 맡을 수 있도록 허용하는 assume role 정책도 필요해요.

Argo CD가 관리하는 클러스터의 예제 assume role 정책:

{
    "Version" : "2012-10-17",
    "Statement" : {
      "Effect" : "Allow",
      "Action" : "sts:AssumeRole",
      "Principal" : {
        "AWS" : "<arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ARGO_CD_MANAGEMENT_IAM_ROLE_NAME>"
      }
    }
  }

Argo CD가 관리하는 클러스터의 예제 kube-system/aws-auth configmap:

apiVersion: v1
data:
  # Other groups and accounts omitted for brevity. Ensure that no other rolearns and/or groups are inadvertently removed, 
  # or you risk borking access to your cluster.
  #
  # The group name is a RoleBinding which you use to map to a [Cluster]Role. See https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-binding-examples  
  mapRoles: |
    - "groups":
      - "<GROUP-NAME-IN-K8S-RBAC>"
      "rolearn": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_CLUSTER_ROLE>"
      "username": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_CLUSTER_ROLE>"

rolearn과 username 모두에 역할 ARN을 사용하세요.

대체 EKS 인증 방법 (Alternative EKS Authentication Methods)

일부 시나리오에서는 Argo CD 클러스터가 다른 클라우드 제공자의 플랫폼에서 실행되는 경우처럼 IRSA를 사용할 수 없을 수도 있어요. 이 경우 두 가지 옵션이 있습니다:

1. 자격 증명을 공급할 환경 변수 주입을 가능하게 하는 AWS 인증 메커니즘을 호출하기 위해 execProviderConfig를 사용
2. Argo CD 릴리스 2.10에서 제공되는 새로운 AWS 프로필 옵션 활용

두 옵션 모두 프린시펄에 클러스터 접근 권한을 부여하기 위해 IAM과 aws-auth config map(위에서 정의됨)을 포함한 단계가 필요합니다.

환경 변수와 함께 execProviderConfig 사용:

---
apiVersion: v1
kind: Secret
metadata:
  name: mycluster-secret
  labels:
    argocd.argoproj.io/secret-type: cluster
type: Opaque
stringData:
  name: mycluster
  server: https://mycluster.example.com
  namespaces: "my,managed,namespaces"
  clusterResources: "true"
  config: |
    {
      "execProviderConfig": {
        "command": "argocd-k8s-auth",
        "args": ["aws", "--cluster-name", "my-eks-cluster"],
        "apiVersion": "client.authentication.k8s.io/v1beta1",
        "env": {
          "AWS_REGION": "xx-east-1",
          "AWS_ACCESS_KEY_ID": "{{ .aws_key_id }}",
          "AWS_SECRET_ACCESS_KEY": "{{ .aws_key_secret }}",
          "AWS_SESSION_TOKEN": "{{ .aws_token }}"
        }
      },
      "tlsClientConfig": {
        "insecure": false,
        "caData": "{{ .cluster_cert }}"
      }
    }

이 예제는 공급된 자격 증명에 연결된 역할이 존재한다고 가정해요. 그렇지 않다면 역할을 args 섹션에 다음과 같이 추가할 수 있습니다:

...
    "args": ["aws", "--cluster-name", "my-eks-cluster", "--role-arn", "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_ROLE_NAME>"],
...

이 구성을 External Secrets Operator 같은 도구와 함께 사용하면 키를 일반 텍스트로 저장하지 않을 수 있고, 키 회전(rotation)을 위한 기반을 마련하는 데도 도움이 됩니다.

AWS 프로필을 사용한 인증:

2.10 릴리스에 추가된 프로필 사용 옵션은, AWS 자격 증명 파일을 가리키는 추가 명령 플래그와 함께 표준 Argo CD EKS 클러스터 선언을 사용하면서도 자격 증명을 공급하는 방법을 제공합니다:

apiVersion: v1
kind: Secret
metadata:
  name: mycluster-secret
  labels:
    argocd.argoproj.io/secret-type: cluster
type: Opaque
stringData:
  name: "mycluster.com"
  server: "https://mycluster.com"
  config: |
    {
      "awsAuthConfig": {
        "clusterName": "my-eks-cluster-name",
        "roleARN": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_ROLE_NAME>",
        "profile": "/mount/path/to/my-profile-file"
      },
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<base64 encoded certificate>"
      }        
    }

이렇게 하면 Argo CD가 제공된 경로의 파일을 읽고 그 안에 정의된 자격 증명을 사용해 AWS에 인증하도록 지시하게 됩니다. 이 프로필은 이 기능이 작동하려면 argocd-server와 argocd-application-controller 컴포넌트 양쪽에 마운트되어야 해요. 예를 들어, Helm 기반 Argo CD 배포에서 다음 값을 정의할 수 있습니다:

controller:
  extraVolumes:
    - name: my-profile-volume
      secret:
        secretName: my-aws-profile
        items:
          - key: my-profile-file
            path: my-profile-file
  extraVolumeMounts:
    - name: my-profile-mount
      mountPath: /mount/path/to
      readOnly: true

server:
  extraVolumes:
    - name: my-profile-volume
      secret:
        secretName: my-aws-profile
        items:
          - key: my-profile-file
            path: my-profile-file
  extraVolumeMounts:
    - name: my-profile-mount
      mountPath: /mount/path/to
      readOnly: true

시크릿은 다음과 같이 정의됩니다:

apiVersion: v1
kind: Secret
metadata:
  name: my-aws-profile
type: Opaque
stringData:
  my-profile-file: |
    [default]
    region = <aws_region>
    aws_access_key_id = <aws_access_key_id>
    aws_secret_access_key = <aws_secret_access_key>
    aws_session_token = <aws_session_token>

⚠️ 시크릿 마운트는 실시간이 아니라 일정 간격으로 업데이트돼요. 회전(rotation)이 요구 사항이라면, 토큰 수명이 마운트 업데이트 간격보다 길고 회전 프로세스가 기존 토큰을 즉시 무효화하지 않도록 하세요.

GKE

argocd-k8s-auth와 Workload Identity를 사용하는 GKE 클러스터 시크릿 예제:

apiVersion: v1
kind: Secret
metadata:
  name: mycluster-secret
  labels:
    argocd.argoproj.io/secret-type: cluster
type: Opaque
stringData:
  name: mycluster.example.com
  server: https://mycluster.example.com
  config: |
    {
      "execProviderConfig": {
        "command": "argocd-k8s-auth",
        "args": ["gcp"],
        "apiVersion": "client.authentication.k8s.io/v1beta1"
      },
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<base64 encoded certificate>"
      }
    }

GKE 클러스터에서 Workload Identity를 활성화하고, 적절한 IAM 역할을 가진 GCP 서비스 계정을 만들고, 이를 argocd-application-controller와 argocd-server(UI에서 파드 로그를 보여주는 역할)의 Kubernetes 서비스 계정에 바인딩해야 해요. Use Workload Identity 및 Authenticating to the Kubernetes API server를 참고하세요.

AKS

argocd-k8s-auth와 kubelogin을 사용하는 Azure 클러스터 시크릿 예제. argocd-k8s-auth execProviderConfig의 azure 옵션은 kubelogin의 get-token 명령을 캡슐화합니다. 원하는 인증 흐름(devicecode, spn, ropc, msi, azurecli, workloadidentity)에 따라 환경 변수 AAD_LOGIN_METHOD를 그 값으로 설정하세요. 원하는 인증 흐름에 따라 다른 적절한 환경 변수도 설정합니다.

| 변수 이름 | 설명 | | AAD_LOGIN_METHOD | devicecode, spn, ropc, msi, azurecli, workloadidentity 중 하나 | | AZURE_CLIENT_CERTIFICATE_PATH | pfx 형태의 AAD 클라이언트 인증서 경로. spn 로그인과 WorkloadIdentityLogin 흐름에서 사용 | | AZURE_CLIENT_CERTIFICATE_PASSWORD | pfx 형태의 클라이언트 인증서 비밀번호. spn 로그인에서 사용 | | AZURE_CLIENT_ID | AAD 클라이언트 애플리케이션 ID | | AZURE_CLIENT_SECRET | AAD 클라이언트 애플리케이션 시크릿 | | AAD_USER_PRINCIPAL_NAME | ropc 흐름에서 사용 | | AAD_USER_PRINCIPAL_PASSWORD | ropc 흐름에서 사용 | | AZURE_TENANT_ID | AAD 테넌트 ID | | AZURE_AUTHORITY_HOST | WorkloadIdentityLogin 흐름에서 사용 | | AZURE_FEDERATED_TOKEN_FILE | WorkloadIdentityLogin 흐름에서 사용 |

위 환경 변수 외에도 argocd-k8s-auth는 AAD 환경을 설정하고 AAD 서버 애플리케이션 ID를 설정하기 위한 두 개의 추가 환경 변수를 받아들입니다. AAD 서버 애플리케이션 ID는 지정하지 않으면 기본값 6dae42f8-4368-4678-94ff-3960e28e3630을 사용해요. 자세한 내용은 Exec Plugin을 참고하세요.

| 변수 이름 | 설명 | | AAD_ENVIRONMENT_NAME | 사용할 azure 환경. 기본값은 AzurePublicCloud | | AAD_SERVER_APPLICATION_ID | 선택적인 AAD 서버 애플리케이션 ID. 기본값은 6dae42f8-4368-4678-94ff-3960e28e3630 |

이는 federated workload login 흐름을 사용하는 예제입니다. federated token 파일은 흐름에서 사용할 수 있도록 시크릿으로 Argo CD에 마운트되어야 해요. 토큰 파일의 위치는 환경 변수 AZURE_FEDERATED_TOKEN_FILE에 설정해야 합니다.

AKS 클러스터가 Azure Workload Identity 프로젝트의 Mutating Admission Webhook을 사용한다면, 다음 단계를 따라 argocd-application-controller와 argocd-server 파드가 federated identity를 사용할 수 있게 하세요:

1. 파드에 라벨 지정: argocd-application-controller와 argocd-server 파드에 azure.workload.identity/use: "true" 라벨 추가
2. Federated Identity Credential 생성: argocd-application-controller와 argocd-server 서비스 계정에 대한 Azure federated identity credential 생성. 자세한 지침은 Federated Identity Credential 문서를 참고
3. 서비스 계정에 어노테이션 추가: federated credential의 세부 정보를 사용해 argocd-application-controller와 argocd-server 서비스 계정에 azure.workload.identity/client-id: "$CLIENT_ID" 및 azure.workload.identity/tenant-id: "$TENANT_ID" 어노테이션 추가
4. AZURE_CLIENT_ID 설정: 클러스터 시크릿의 AZURE_CLIENT_ID를 새로 만든 federated identity credential의 클라이언트 ID와 일치하도록 업데이트

apiVersion: v1
kind: Secret
metadata:
  name: mycluster-secret
  labels:
    argocd.argoproj.io/secret-type: cluster
type: Opaque
stringData:
  name: mycluster.example.com
  server: https://mycluster.example.com
  config: |
    {
      "execProviderConfig": {
        "command": "argocd-k8s-auth",
        "env": {
          "AAD_ENVIRONMENT_NAME": "AzurePublicCloud",
          "AZURE_CLIENT_ID": "fill in client id",
          "AZURE_TENANT_ID": "fill in tenant id", # optional, injected by workload identity mutating admission webhook if enabled
          "AZURE_FEDERATED_TOKEN_FILE": "/opt/path/to/federated_file.json", # optional, injected by workload identity mutating admission webhook if enabled
          "AZURE_AUTHORITY_HOST": "https://login.microsoftonline.com/", # optional, injected by workload identity mutating admission webhook if enabled
          "AAD_LOGIN_METHOD": "workloadidentity"
        },
        "args": ["azure"],
        "apiVersion": "client.authentication.k8s.io/v1beta1"
      },
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<base64 encoded certificate>"
      }
    }

이는 spn(서비스 프린시펄 이름) 흐름을 사용하는 예제입니다.

apiVersion: v1
kind: Secret
metadata:
  name: mycluster-secret
  labels:
    argocd.argoproj.io/secret-type: cluster
type: Opaque
stringData:
  name: mycluster.example.com
  server: https://mycluster.example.com
  config: |
    {
      "execProviderConfig": {
        "command": "argocd-k8s-auth",
        "env": {
          "AAD_ENVIRONMENT_NAME": "AzurePublicCloud",
          "AZURE_CLIENT_SECRET": "fill in your service principal client secret",
          "AZURE_TENANT_ID": "fill in tenant id",
          "AZURE_CLIENT_ID": "fill in your service principal client id",
          "AAD_LOGIN_METHOD": "spn"
        },
        "args": ["azure"],
        "apiVersion": "client.authentication.k8s.io/v1beta1"
      },
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<base64 encoded certificate>"
      }
    }

Helm

Helm 차트는 Helm 저장소 또는 OCI 레지스트리에서 가져올 수 있어요.

다음은 Helm 차트를 Helm 저장소에서 가져오는 예제입니다. releaseName 속성은 Helm 릴리스의 이름을 사용자 지정하는 데 사용됩니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: sealed-secrets
  namespace: argocd
spec:
  project: default
  source:
    chart: sealed-secrets
    repoURL: https://bitnami-labs.github.io/sealed-secrets
    targetRevision: 1.16.1
    helm:
      releaseName: sealed-secrets
  destination:
    server: "https://kubernetes.default.svc"
    namespace: kubeseal

공개 OCI Helm 차트를 사용하는 또 다른 예제:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx
spec:
  project: default
  source:
    chart: nginx
    repoURL: registry-1.docker.io/bitnamicharts  # note: the oci:// syntax is not included.
    targetRevision: 15.9.0
  destination:
    name: "in-cluster"
    namespace: nginx

인증이나 TLS 연결 세부 정보처럼 추가 구성이 필요한 소스에 위치한 Helm 차트는 저장소 시크릿 내에 정의됩니다. 각 시크릿은 url, type, name 필드를 지정해야 해요. username, password, tlsClientCertData, tlsClientCertKey 같은 추가 필드는 원하는 대로 지정할 수 있습니다.

Helm 차트 저장소:

apiVersion: v1
kind: Secret
metadata:
  name: argo-helm
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  name: argo
  url: https://argoproj.github.io/argo-helm
  type: helm
  username: my-username
  password: my-password
  tlsClientCertData: ...
  tlsClientCertKey: ...

OCI 레지스트리에서 가져온 Helm 차트는 앞서 설명한 필드를 사용하면서도 enableOCI 필드를 true로 설정해야 합니다.

apiVersion: v1
kind: Secret
metadata:
  name: oci-helm-chart
  namespace: oci-helm-chart
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  name: oci-helm-chart
  url: myregistry.example.com
  type: helm
  enableOCI: "true"

리소스 제외/포함 (Resource Exclusion/Inclusion)

리소스는 Argo CD가 이를 인식하지 못하도록 발견(discovery)과 동기화(sync)에서 제외할 수 있어요. 예를 들어 apiGroup/kind events.k8s.io/*, metrics.k8s.io/*, coordination.k8s.io/Lease는 항상 제외됩니다. 사용 사례:

• 일시적인 문제가 있어 문제가 되는 리소스를 제외하고 싶을 때
• Argo CD의 성능에 영향을 주는 종류의 리소스가 너무 많을 때
• 시크릿과 같은 특정 종류의 리소스에 대한 Argo CD의 접근을 제한하고 싶을 때. security.md#cluster-rbac를 참고하세요.

이를 구성하려면 argocd-cm config map을 편집하세요:

kubectl edit configmap argocd-cm -n argocd

resource.exclusions를 추가하세요. 예:

apiVersion: v1
data:
  resource.exclusions: |
    - apiGroups:
      - "*"
      kinds:
      - "*"
      clusters:
      - https://192.168.0.20
kind: ConfigMap

resource.exclusions 노드는 객체들의 목록이에요. 각 객체는 다음을 가질 수 있습니다:

• apiGroups: API 그룹과 일치시키기 위한 glob 목록
• kinds: 일치시킬 kinds 목록. 전부 일치시키려면 "*"를 사용
• clusters: 클러스터 URL과 일치시키기 위한 glob 목록

세 가지 모두 일치하면 해당 리소스는 무시됩니다.

제외 외에도 resource.inclusions 설정을 사용해 포함할 리소스 목록을 구성할 수 있어요. 기본적으로 모든 리소스 group/kind가 포함됩니다. resource.inclusions 설정은 포함할 group/kind 목록을 사용자 지정할 수 있습니다:

apiVersion: v1
data:
  resource.inclusions: |
    - apiGroups:
      - "*"
      kinds:
      - Deployment
      clusters:
      - https://192.168.0.20
kind: ConfigMap

resource.inclusions와 resource.exclusions는 함께 사용할 수 있습니다. 최종 리소스 목록은 resource.inclusions에 지정된 group/kind에서 resource.exclusions 설정에 지정된 group/kind를 뺀 것입니다.

참고:

• YAML에서 glob을 따옴표로 감싸 파싱 오류를 피하세요
• 잘못된 glob은 전체 규칙이 무시되게 합니다
• 기존 리소스와 일치하는 규칙을 추가하면, 그 리소스는 인터페이스에 OutOfSync로 표시됩니다
• 일부 제외된 객체는 이미 컨트롤러 캐시에 있을 수 있어요. Application View에서 이를 제거하려면 컨트롤러를 재시작해야 합니다

시크릿의 민감한 어노테이션 마스킹 (Mask sensitive Annotations on Secrets)

선택적인 쉼표로 구분된 metadata.annotations 키 목록을 resource.sensitive.mask.annotations로 구성해, 시크릿의 UI/CLI에서 해당 값을 마스킹할 수 있습니다.

  resource.sensitive.mask.annotations: openshift.io/token-secret.value, api-key

컨트롤러의 RBAC 자동 존중 (Auto respect RBAC for controller)

Argo CD 컨트롤러는 리소스 제외를 수동으로 구성하지 않아도, 컨트롤러 RBAC만으로 특정 리소스의 발견/동기화를 제한할 수 있어요. 이 기능은 argocd cm에 resource.respectRBAC 키를 설정해 활성화할 수 있는데, 설정되면 컨트롤러는 list/access 권한이 없는 리소스에 대한 모니터링을 자동으로 중단합니다. resource.respectRBAC의 가능한 값은 다음과 같아요:

• strict: 컨트롤러가 수행한 list 호출이 forbidden/unauthorized인지 확인하고, 그렇다면 해당 리소스에 대해 SelfSubjectAccessReview 호출을 수행해 권한을 교차 확인합니다
• normal: list 호출 응답이 forbidden/unauthorized인지만 확인하고 추가 API 서버 호출을 최소화하기 위해 SelfSubjectAccessReview 호출은 건너뜁니다
• 미설정/빈 값 (기본값): 이 기능을 비활성화하며 컨트롤러는 모든 리소스를 계속 모니터링합니다

kube api-server 호출 증가를 감수할 수 있는 사용자는 strict 옵션을 선택하면 되고, API 호출이 많은 것이 우려되어 정확도 일부를 타협할 의향이 있는 사용자는 normal 옵션을 선택하면 됩니다.

참고:

• strict 모드를 사용하도록 설정하면 컨트롤러가 SelfSubjectAccessReview 리소스를 생성할 RBAC 권한이 있어야 합니다
• SelfSubjectAccessReview 요청은 list 동사에 대해서만 수행됩니다. 리소스에 대한 list가 허용되면 다른 모든 권한도 컨트롤러에 있다고 가정합니다

resource.respectRBAC가 strict로 설정된 argocd cm 예제:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
data:
  resource.respectRBAC: "strict"

리소스 사용자 지정 라벨 (Resource Custom Labels)

resource.customLabels(쉼표로 구분된 문자열)로 구성된 사용자 지정 라벨은 UI에 표시돼요(라벨을 정의한 리소스에 대해서요). 이 기능은 적용되려면 Argo CD Application Controller를 재시작해야 합니다.

애플리케이션 이벤트의 라벨 (Labels on Application Events)

선택적인 쉼표로 구분된 metadata.labels 키 목록을 resource.includeEventLabelKeys로 구성해 Argo CD 애플리케이션에 대해 생성되는 Kubernetes 이벤트에 추가할 수 있어요. 지정된 라벨을 포함한 애플리케이션에 대해 이벤트가 생성되면, 컨트롤러는 일치하는 라벨을 이벤트에 추가합니다. 이는 이벤트와 애플리케이션 사이의 쉬운 연결을 만들어 라벨로 필터링할 수 있게 해줘요. 애플리케이션과 AppProject의 라벨이 충돌하는 경우, 애플리케이션 라벨 값이 우선하여 이벤트에 추가됩니다.

  resource.includeEventLabelKeys: team,env*

특정 라벨을 이벤트에서 제외하려면 resource.excludeEventLabelKeys 키를 사용하세요. 이 키는 쉼표로 구분된 metadata.labels 키 목록을 받습니다.

  resource.excludeEventLabelKeys: environment,bu

resource.includeEventLabelKeys와 resource.excludeEventLabelKeys 모두 와일드카드를 지원합니다.

SSO & RBAC

• SSO 구성 세부 정보: SSO
• RBAC 구성 세부 정보: RBAC

Argo CD로 Argo CD 관리하기 (Manage Argo CD Using Argo CD)

Argo CD는 모든 설정이 Kubernetes 매니페스트로 표현되므로 자기 자신을 관리할 수 있어요. 권장하는 방법은 https://github.com/argoproj/argo-cd 의 기본 Argo CD 매니페스트를 사용하는 Kustomize 기반 애플리케이션을 만들고, 그 위에 필요한 변경 사항을 적용하는 것입니다.

kustomization.yaml 예제:

# additional resources like ingress rules, cluster and repository secrets.
resources:
- github.com/argoproj/argo-cd//manifests/cluster-install?ref=stable
- clusters-secrets.yaml
- repos-secrets.yaml

# changes to config maps
patches:
- path: overlays/argo-cd-cm.yaml

자체 관리되는 Argo CD 구성의 실제 예제는 https://cd.apps.argoproj.io 에서 볼 수 있고, 구성은 argoproj/argoproj-deployments에 저장되어 있습니다.

참고: https://cd.apps.argoproj.io 에 접근하려면 GitHub 계정으로 로그인해야 합니다.

서버 측 적용 요구 사항 (Server-Side Apply Requirement)

Argo CD로 Argo CD를 관리할 때는 ServerSideApply=true 동기화 옵션을 활성화해야 해요. 서버 측 적용이 왜 필요한지에 대한 자세한 내용은 Getting Started 가이드를 참고하세요.

자체 관리되는 Argo CD의 예제 애플리케이션:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: argocd
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argo-cd
    path: manifests/cluster-install
    targetRevision: stable
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - ServerSideApply=true

참고: Argo CD 배포를 사용자 지정하려면 라이브 리소스를 수동으로 수정하는 대신 구성 저장소에서 Kustomize 패치를 사용하세요. 필드 소유권 동작에 대한 자세한 내용은 sync options 문서를 참고하세요.

더 알아보기 (Learn more)

• Argo CD 공식 문서 - Declarative Setup
• Argo CD Getting Started
• Argo CD Kustomize