Impersonation을 이용한 Application 동기화

Impersonation을 이용한 Application 동기화 (Application Sync using impersonation)

Argo CD는 애플리케이션 동기화(sync) 작업을 컨트롤 플레인과 분리된 별도의 서비스 어카운트로 수행할 수 있게 해줘요. 이 기능을 이용하면 멀티테넌트 환경에서 각 테넌트에 필요한 최소 권한만 부여하면서도 동기화를 안전하게 수행할 수 있답니다.

출처: 문서

본문

주의 (Beta 기능, v3.5.0부터)

이 기능은 베타 품질의 기능으로, 동기화 작업에 사용되는 서비스 어카운트를 제어할 수 있게 해줘요. 설정한 서비스 어카운트는 리소스를 생성하는 데 필요한 권한이 컨트롤 플레인 작업에 필요한 높은 권한보다 더 적을 수 있어요.

주의

이 기능을 활성화하기 전에 이 문서를 주의 깊게 읽어주세요. 잘못 구성하면 잠재적인 보안 문제가 발생할 수 있어요.

소개 (Introduction)

Argo CD는 컨트롤 플레인 작업에 사용하는 것과 동일한 서비스 어카운트를 사용해 Application 리소스를 동기화하는 것을 지원해요. 이 기능은 애플리케이션 동기화에 사용되는 서비스 어카운트를 컨트롤 플레인 작업에 사용되는 서비스 어카운트와 분리할 수 있게 해줘요.

기본적으로 Argo CD의 애플리케이션 동기화는 Argo CD 컨트롤 플레인과 동일한 권한을 가져요. 그 결과, 멀티테넌트 구성에서는 Argo CD 컨트롤 플레인 권한이 가장 높은 권한이 필요한 테넌트와 일치해야 해요. 예를 들어 Argo CD 인스턴스에 10개의 Application이 있고 그중 하나만 admin 권한이 필요하다면, 그 하나의 Application을 동기화하기 위해 Argo CD 컨트롤 플레인은 admin 권한을 가져야 해요. 이는 악의적인 테넌트가 admin 수준 접근 권한을 얻을 수 있는 기회를 제공해요. Argo CD는 AppProjects를 사용해 각 Application이 수행할 수 있는 작업을 제한하는 멀티테넌시 모델을 제공하지만, 이는 충분히 안전하지 않으며 Argo CD가 손상되면 공격자가 쉽게 클러스터에 대한 cluster-admin 접근 권한을 얻을 수 있어요.

이 기능은 기본적으로 비활성화되어 있기 때문에, 활성화하려면 Argo CD 관리자가 몇 가지 수동 단계를 수행해야 해요.

참고

이 기능은 베타로 간주돼요. API는 안정적이지만, 안정 상태로 승격하기 전에 사용자 피드백을 수집하면서 일부 구현 세부 사항이 변경될 수 있어요.

Impersonation이란 무엇인가 (What is Impersonation)

Impersonation은 Kubernetes의 기능으로 kubectl CLI 클라이언트에서 활성화되며, impersonation 헤더를 통해 사용자가 다른 사용자로 행동할 수 있게 해줘요. 예를 들어 관리자는 이 기능을 사용해 다른 사용자를 일시적으로 가장(impersonate)하고 요청이 거부되었는지 확인함으로써 권한 부여 정책을 디버깅할 수 있어요.

Impersonation 요청은 먼저 요청하는 사용자로 인증한 다음, 가장된 사용자의 정보로 전환돼요.

기능 범위 (Feature scope)

Impersonation은 Application이 직접 관리하는 객체의 수명 주기(lifecycle)에 대해 지원돼요. 여기에는 동기화 작업(리소스 생성, 업데이트, 프루닝)과 Application finalizer 로직의 일부로 수행되는 삭제가 포함돼요. 또한 사용자가 트리거한 UI 작업에도 지원돼요.

전제 조건 (Prerequisites)

멀티팀/멀티테넌트 환경에서는 일반적으로 팀/테넌트가 대상 네임스페이스에 대한 접근 권한을 부여받아 선언적인 방식으로 자신의 kubernetes 리소스를 자체 관리해요. 일반적인 테넌트 온보딩 프로세스는 아래와 같아요:

  1. 플랫폼 관리자가 테넌트 네임스페이스를 만들고, 리소스 생성에 사용할 서비스 어카운트도 같은 테넌트 네임스페이스에 생성해요.
  2. 플랫폼 관리자가 테넌트 네임스페이스의 kubernetes 리소스를 관리하기 위한 하나 이상의 Role을 만들어요.
  3. 플랫폼 관리자가 서비스 어카운트를 앞서 만든 역할에 매핑하는 하나 이상의 RoleBinding을 만들어요.
  4. 플랫폼 관리자는 apps-in-any-namespace 기능을 사용하거나, 테넌트가 ArgoCD 컨트롤 플레인 네임스페이스에서 애플리케이션을 만들 수 있도록 접근 권한을 제공할 수 있어요.
  5. 플랫폼 관리자가 apps-in-any-namespace 기능을 선택하면, 테넌트는 각자의 테넌트 네임스페이스에서 Argo 애플리케이션을 셀프 서비스할 수 있고, 컨트롤 플레인 네임스페이스에 대한 추가 접근 권한을 제공할 필요가 없어요.

구현 세부 사항 (Implementation details)

개요 (Overview)

애플리케이션이 동기화 작업에 다른 서비스 어카운트를 사용하려면 다음 단계를 수행해야 해요:

  1. impersonation 기능 플래그를 활성화해야 해요. Enable application sync with impersonation feature에 제공된 단계를 참고하세요.
  2. Application의 .spec.project 필드가 참조하는 AppProject에 DestinationServiceAccounts가 있어야 해요. 이는 대상 서버와 네임스페이스를 동기화 작업에 사용할 서비스 어카운트에 매핑해요. Configuring destination service accounts에 제공된 단계를 참고하세요.

impersonation 기능으로 애플리케이션 동기화 활성화 (Enable application sync with impersonation feature)

이 기능을 활성화하려면 Argo CD 관리자가 argocd-cm ConfigMap의 application.sync.impersonation.enabled 설정을 아래와 같이 재구성해야 해요:

data:
  application.sync.impersonation.enabled: 'true'

impersonation 기능으로 애플리케이션 동기화 비활성화 (Disable application sync with impersonation feature)

이 기능을 비활성화하려면 Argo CD 관리자가 argocd-cm ConfigMap의 application.sync.impersonation.enabled 설정을 아래와 같이 재구성해야 해요:

data:
  application.sync.impersonation.enabled: 'false'

참고

이 기능은 기본적으로 비활성화되어 있어요.

참고

이 기능은 시스템 수준에서만 활성화/비활성화할 수 있으며, 일단 활성화/비활성화되면 ArgoCD가 관리하는 모든 Application에 적용돼요.

강제 동작 구성 (Configure enforcement behavior)

기본적으로 impersonation이 활성화되면 Argo CD는 모든 프로젝트가 일치하는 서비스 어카운트를 구성해야 한다고 엄격하게 강제해요. 일치하는 항목을 찾지 못하면 동기화 작업이 실패해요.

argocd-cm ConfigMap에서 application.sync.impersonation.enforced를 false로 설정하면 이 강제를 비활성화할 수 있어요:

data:
  application.sync.impersonation.enabled: 'true'
  application.sync.impersonation.enforced: 'false'

강제가 비활성화되면 일치하는 서비스 어카운트를 찾지 못하는 경우 Argo CD는 컨트롤러의 서비스 어카운트를 사용하는 것으로 대체(fallback)해요.

이는 impersonation으로 점진적으로 마이그레이션할 때 유용해요. Argo CD 관리자는 다음을 수행할 수 있어요:

  1. 강제(enforcement)를 비활성화한 상태로 impersonation 활성화
  2. 시간이 지남에 따라 각 프로젝트에 서비스 어카운트 구성
  3. 모든 프로젝트가 올바르게 구성되면 강제 활성화

주의

강제를 비활성화하면 애플리케이션 간 보안 격리가 줄어들어요. 보안 영향을 이해하고 Argo CD 인스턴스가 관리하는 모든 애플리케이션을 신뢰하는 경우에만 강제를 비활성화하세요.

대상 서비스 어카운트 구성 (Configuring destination service accounts)

대상 서비스 어카운트는 AppProject의 .spec.destinationServiceAccounts 아래에 추가할 수 있어요. 대상 server와 namespace를 지정하고 defaultServiceAccount 필드를 사용해 동기화 작업에 사용할 서비스 어카운트를 제공해요. 이 AppProject를 참조하는 애플리케이션은 해당 대상에 구성된 서비스 어카운트를 사용해요.

동기화 작업 중에 컨트롤러는 매핑된 AppProject의 사용 가능한 destinationServiceAccounts를 순회하며 일치하는 후보를 찾으려 해요. 대상 서버와 네임스페이스 조합에 대해 일치하는 항목이 여러 개 있으면 첫 번째 유효한 일치 항목이 고려돼요. 일치 항목이 없으면 동기화 작업 중에 오류가 보고돼요. 이러한 동기화 오류를 피하기 위해 모든 대상 대상(destination)에 대해 유효한 서비스 어카운트를 catch-all 구성으로 설정하고 우선순위가 가장 낮은 순서로 유지하는 것이 좋아요.

서비스 어카운트를 네임스페이스와 함께 지정할 수 있어요. 예: tenant1-ns:guestbook-deployer. 서비스 어카운트에 네임스페이스를 제공하지 않으면 Application의 spec.destination.namespace가 사용돼요. 서비스 어카운트에 네임스페이스가 제공되지 않고 Application에 선택적인 spec.destination.namespace 필드도 제공되지 않으면 Application의 네임스페이스가 사용돼요.

AppProject와 연결된 DestinationServiceAccounts는 선언적으로 또는 Argo CD API(예: CLI, 웹 UI, REST API 등)를 통해 생성하고 관리할 수 있어요.

선언적 yaml 사용 (Using declarative yaml)

대상 서비스 어카운트를 선언적으로 구성하려면 아래와 같이 AppProject에 대한 yaml 파일을 만들고 kubectl apply 명령을 사용해 변경 사항을 적용해요.

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: my-project
  namespace: argocd
spec:
  description: Example Project
  # Allow manifests to deploy from any Git repos
  sourceRepos:
    - '*'
  destinations:
    - '*'
  destinationServiceAccounts:
    - server: https://kubernetes.default.svc
      namespace: guestbook
      defaultServiceAccount: guestbook-deployer
    - server: https://kubernetes.default.svc
      namespace: guestbook-dev
      defaultServiceAccount: guestbook-dev-deployer
    - server: https://kubernetes.default.svc
      namespace: guestbook-stage
      defaultServiceAccount: guestbook-stage-deployer
    - server: https://kubernetes.default.svc # catch-all configuration
      namespace: '*'
      defaultServiceAccount: default

CLI 사용 (Using the CLI)

대상 서비스 어카운트는 ArgoCD CLI를 사용해 AppProject에 추가할 수 있어요.

예를 들어 in-cluster와 guestbook 네임스페이스에 대한 대상 서비스 어카운트를 추가하려면 다음 CLI 명령을 사용할 수 있어요:

argocd proj add-destination-service-account my-project https://kubernetes.default.svc guestbook guestbook-sa

마찬가지로 AppProject에서 대상 서비스 어카운트를 제거하려면 다음 CLI 명령을 사용할 수 있어요:

argocd proj remove-destination-service-account my-project https://kubernetes.default.svc guestbook

UI 사용 (Using the UI)

CLI와 유사하게, UI에서 AppProject를 생성하거나 업데이트할 때 대상 서비스 어카운트를 추가할 수 있어요.

더 알아보기 (Learn more)

  • Impersonation의 개념과 Kubernetes에서의 동작 방식에 대해 더 알아보고 싶다면 apps-in-any-namespace와 AppProject·RBAC 관련 문서를 함께 살펴보세요.
  • Argo CD의 핵심 컴포넌트 구조가 궁금하다면 Arquitectura 패턴 문서를 참고하세요.