Projects

Projects (AppProject) — 팀별로 애플리케이션을 묶고 권한을 나누는 단위

Argo CD를 여러 팀이 함께 쓰다 보면, 'A 팀은 어느 저장소에서 뭘 배포할 수 있는지'부터 '어느 클러스터·네임스페이스에 올릴 수 있는지'까지 제한하고 싶어져요. **프로젝트(Project, AppProject)**가 바로 그 경계를 만들어 주는 논리적 묶음입니다.

출처: Argo CD 공식 문서 — Projects

본문

프로젝트는 애플리케이션을 논리적으로 그룹핑하며, Argo CD를 여러 팀이 쓸 때 특히 유용해요. 프로젝트가 제공하는 것들을 보면:

무엇을 배포할 수 있는지 제한 (신뢰하는 Git 소스 저장소)
어디에 배포할 수 있는지 제한 (대상 클러스터와 네임스페이스)
어떤 종류의 객체를 배포할 수 있는지 제한 (예: RBAC, CRD, DaemonSet, NetworkPolicy 등)
프로젝트 롤 정의로 애플리케이션 RBAC 제공 (OIDC 그룹이나 JWT 토큰에 바인딩)

기본 프로젝트 (default)

모든 애플리케이션은 반드시 어떤 프로젝트 하나에 속해요. 지정하지 않으면 자동 생성된 default 프로젝트에 들어가는데, 처음에는 가장 관대하게 만들어져 있습니다.

spec:
  sourceRepos:
    - '*'
  destinations:
    - namespace: '*'
      server: '*'
  clusterResourceWhitelist:
    - group: '*'
      kind: '*'

default 프로젝트는 수정할 수 있지만 삭제는 불가능해요. 초기 테스트에는 편하지만, 명시적인 권한을 가진 전용 프로젝트를 따로 만들어 쓰는 걸 권장합니다. default 프로젝트의 모든 권한을 없애려면 Argo CD가 설치된 네임스페이스에 빈 목록으로 된 AppProject 매니페스트를 적용하면 돼요.

프로젝트 만들기

argocd proj create 명령으로 만들 수 있어요. 아래는 myproject를 만들면서 배포 허용 대상을 클러스터의 mynamespace로, 허용 Git 소스를 특정 저장소로 정한 예시예요.

argocd proj create myproject -d https://kubernetes.default.svc,mynamespace -s https://github.com/argoproj/argocd-example-apps.git

소스·대상 접근 관리

허용 Git 소스 저장소는 다음 명령으로 관리해요.

argocd proj add-source <PROJECT> <REPO>
argocd proj remove-source <PROJECT> <REPO>

부정(deny)도 가능해요. ! 접두사를 붙이면 '이 저장소는 쓰지 마라'가 됩니다.

argocd proj add-source <PROJECT> !<REPO>

선언적으로도 표현할 수 있는데, 소스가 유효하려면 ① !로 시작하지 않는 allow 규칙 중 하나가 허용하고 ② !로 시작하는 deny 규칙이 거부하지 않아야 해요. 참고로 아무것도 금지한다는 뜻의 !*는 무의미해서 유효하지 않은 규칙입니다.

배포 대상 클러스터·네임스페이스도 비슷한 명령으로 관리해요. 클러스터는 항상 서버(server)를 주고, 이름은 매칭에 쓰이지 않는다는 점을 기억하세요.

argocd proj add-destination <PROJECT> <CLUSTER>,<NAMESPACE>
argocd proj remove-destination <PROJECT> <CLUSTER>,<NAMESPACE>

대상 리소스 kind도 제한할 수 있는데, 네임스페이스 스코프 리소스는 deny 목록으로, 클러스터 스코프 리소스는 allow 목록으로 제한해요.

argocd proj allow-cluster-resource <PROJECT> <GROUP> <KIND>
argocd proj deny-namespace-resource <PROJECT> <GROUP> <KIND> [<NAME>]

이름으로 클러스터 스코프 리소스를 제한할 수도 있어요. 예를 들어 team1-로 시작하는 Namespace만 허용하려면 clusterResourceWhitelist에 name: team1-*를 줍니다.

애플리케이션을 프로젝트에 배정

app set 명령으로 애플리케이션의 프로젝트를 바꿀 수 있어요. 이때 사용자는 새 프로젝트에 접근 권한이 있어야 합니다.

argocd app set guestbook-default --project myproject

프로젝트 롤과 JWT 토큰

프로젝트에는 롤(role) 이라는 기능이 있어서, 프로젝트에 속한 애플리케이션에 대해 누가 무슨 일을 할 수 있는지 정할 수 있어요. 예를 들어 CI 파이프라인에 특정 앱의 싱크만 허용하는 제한된 권한을 주는 식이에요. 롤의 권한은 Argo CD 구성의 RBAC 패턴을 따르는 정책(policy) 문자열 목록으로 저장됩니다.

롤 이름은 인가 과정에서 그룹으로 동적으로 생성돼요. 정책이 효과를 내려면 proj:<프로젝트명>:<롤명> 패턴을 반드시 지켜야 합니다. 정책의 리소스로는 applications 외에도 applicationsets, repositories, clusters, logs, exec가 올 수 있어요.

롤 관리는 다음 명령으로 해요.

argocd proj role list
argocd proj role create <PROJECT> <ROLE>
argocd proj role add-policy <PROJECT> <ROLE> --action get --permission allow --object <APP>
argocd proj role remove-policy <PROJECT> <ROLE> -a get -o <APP>

롤에 붙는 JWT 토큰으로 해당 롤에 인증할 수 있어요. 토큰은 Argo CD에 저장되지 않으니 생성할 때만 얻을 수 있고, CLI의 --auth-token 플래그나 ARGOCD_AUTH_TOKEN 환경변수로 씁니다. 만료를 지정할 수도(-e 10m) 있고, 기본은 만료일이 없어요.

argocd proj role create-token <PROJECT> <ROLE>
argocd proj role delete-token <PROJECT> <ROLE> <ISSUED-AT>

프로젝트 스코프 저장소·클러스터 (셀프서비스)

관리자가 RBAC를 열어두면, 개발자가 프로젝트에 저장소나 클러스터를 직접 추가하는 셀프서비스도 가능해요. 저장소·클러스터는 기본적으로 쿠버네티스 Secret으로 저장되는데, Secret에 project 필드를 넣으면 해당 프로젝트 스코프가 됩니다.

apiVersion: v1
kind: Secret
metadata:
  name: argocd-example-apps
  labels:
    argocd.argoproj.io/secret-type: repository
type: Opaque
stringData:
  project: my-project1            # 프로젝트 스코프
  name: argocd-example-apps
  url: https://github.com/argoproj/argocd-example-apps.git

주의할 점이 있어요. 프로젝트 스코프 저장소는 프로젝트 이름이 정확히 일치하는 애플리케이션·애플리케이션셋만 사용할 수 있어요. Git 생성기로 템플릿화된 project({{ ... }})를 쓰는 애플리케이션셋이라면 스코프가 없는(project를 안 정한) 저장소만 사용할 수 있습니다.

클러스터도 같은 원리로 스코프를 줄 수 있어요. 프로젝트에 permitOnlyProjectScopedClusters: true를 두면, 앱이 같은 프로젝트에 속한 클러스터로만 싱크되도록 제한할 수 있습니다. 기본은 같은 프로젝트가 아닌 클러스터에도 배포가 허용되니까요.