RBAC 구성

RBAC 구성 (RBAC Configuration)

RBAC 기능은 Argo CD 리소스에 대한 접근을 제한할 수 있게 해줘요. Argo CD는 자체 사용자 관리 시스템이 없고 기본 제공 사용자는 admin 하나뿐이에요. admin 사용자는 슈퍼유저로 시스템에 무제한 접근 권한을 가져요. RBAC를 사용하려면 SSO 구성 또는 로컬 사용자 하나 이상 설정이 필요해요. SSO나 로컬 사용자가 구성되면 추가 RBAC 역할을 정의하고, SSO 그룹이나 로컬 사용자를 역할에 매핑할 수 있어요.

출처: 문서

본문

RBAC 구성을 정의할 수 있는 주요 컴포넌트는 두 가지예요:

전역 RBAC 설정맵 (참고: argo-rbac-cm.yaml)
AppProject의 역할 (AppProject's roles)

기본 제공 역할 (Basic Built-in Roles)

Argo CD에는 사전 정의된 역할이 두 개 있지만, RBAC 구성을 사용하면 역할과 그룹을 정의할 수 있어요(아래 참고).

role:readonly: 모든 리소스에 대한 읽기 전용 접근
role:admin: 모든 리소스에 대한 무제한 접근

이 기본 제공 역할 정의는 builtin-policy.csv에서 볼 수 있어요.

인증된 사용자의 기본 정책 (Default Policy for Authenticated Users)

사용자가 Argo CD에서 인증되면 policy.default에 지정된 역할이 부여돼요.

[!WARNING] 기본 권한 제한 (Restricting Default Permissions)

모든 인증된 사용자는 기본 정책이 부여하는 최소한의 권한을 얻게 돼요. 이 접근은 deny 규칙으로도 막을 수 없어요. 가능한 최소 권한으로 새 role:authenticated 역할을 만들고, 필요에 따라 개별 역할에 권한을 부여하는 것을 권장해요.

익명 접근 (Anonymous Access)

Argo CD 인스턴스에 익명 접근을 활성화하면 사용자가 인증 없이 policy.default가 지정하는 기본 역할 권한을 사용할 수 있게 돼요.

Argo CD에 대한 익명 접근은 argocd-cm의 users.anonymous.enabled 필드로 활성화할 수 있어요 (참고: argocd-cm.yaml).

[!WARNING] 익명 접근을 활성화할 때는 새 기본 역할을 만들고 policy.default: role:unauthenticated로 기본 정책에 할당하는 것을 고려하세요.

RBAC 모델 구조 (RBAC Model Structure)

모델 문법은 Casbin(오픈소스 ACL)을 기반으로 해요. 정책을 할당하는 문법과 사용자를 내부 역할에 할당하는 문법, 두 가지 유형이 있어요.

Group (그룹): 인증된 사용자/그룹을 내부 역할에 할당할 수 있게 해줘요.

문법: g, <user/group>, <role>

<user/group>: 역할이 할당될 엔티티예요. 로컬 사용자 또는 SSO로 인증된 사용자일 수 있어요. SSO를 사용할 때 user는 토큰의 federated_claims.user_id 필드에서 파생되고, 그룹은 구성된 스코프(예: groups, roles) 아래에서 OIDC 제공자가 반환한 값으로 채워져요.
<role>: 엔티티가 할당될 내부 역할이에요.

Policy (정책): 엔티티에 권한을 할당할 수 있게 해줘요.

문법: p, <role/user/group>, <resource>, <action>, <object>, <effect>

<role/user/group>: 정책이 할당될 엔티티예요
<resource>: 작업이 수행되는 리소스 유형이에요
<action>: 리소스에 수행되는 작업이에요
<object>: 작업이 수행되는 리소스를 나타내는 객체 식별자예요. 리소스에 따라 객체 형식은 달라져요
<effect>: 이 정책이 대상 객체에 대한 작업을 허용할지 제한할지 여부예요. allow 또는 deny 중 하나예요

[!NOTE] 정책이 동작하려면 그룹에 역할이 할당되어야 해요

그룹에 정책을 할당하고 싶다면 먼저 g, <group>, <role>로 역할을 할당해야 해요. 그렇지 않으면 p, <group>, ...로 정의한 정책은 고려되지 않아요.

다음 표는 가능한 모든 리소스와 각각에 대해 유효한 동작을 요약한 것이에요.

Resource\Action	get	create	update	delete	sync	action	override	invoke
applications	✅	✅	✅	✅	✅	✅	✅	❌
applicationsets	✅	✅	✅	✅	❌	❌	❌	❌
clusters	✅	✅	✅	✅	❌	❌	❌	❌
projects	✅	✅	✅	✅	❌	❌	❌	❌
repositories	✅	✅	✅	✅	❌	❌	❌	❌
accounts	✅	❌	✅	❌	❌	❌	❌	❌
certificates	✅	✅	❌	✅	❌	❌	❌	❌
gpgkeys	✅	✅	❌	✅	❌	❌	❌	❌
logs	✅	❌	❌	❌	❌	❌	❌	❌
exec	❌	✅	❌	❌	❌	❌	❌	❌
extensions	❌	❌	❌	❌	❌	❌	❌	✅

애플리케이션 특화 정책 (Application-Specific Policy)

일부 정책은 애플리케이션 안에서만 의미가 있어요. 해당 리소스는 다음과 같아요:

applications
applicationsets
logs
exec

이 정책들은 전역 구성에서 설정할 수 있지만, AppProject의 역할에서도 구성할 수 있어요. 정책 구조에서 예상되는 <object> 값은 <app-project>/<app-name>으로 대체돼요.

예를 들어, 이 정책들은 example-user에게 모든 애플리케이션에 대한 get 접근을 부여하지만, example-project 프로젝트의 my-app 애플리케이션에서만 로그를 볼 수 있게 해줘요.

p, example-user, applications, get, *, allow
p, example-user, logs, get, example-project/my-app, allow

모든 네임스페이스의 애플리케이션 (Application in Any Namespaces)

모든 네임스페이스의 애플리케이션이 활성화되면 정책 구조에서 예상되는 <object> 값은 <app-project>/<app-ns>/<app-name>으로 대체돼요. 같은 프로젝트 안에서 여러 애플리케이션이 같은 이름을 가질 수 있으므로, 아래 정책은 app-namespace에만 접근을 제한하도록 해요.

p, example-user, applications, get, */app-namespace/*, allow
p, example-user, logs, get, example-project/app-namespace/my-app, allow

`applications` 리소스

applications 리소스는 애플리케이션 특화 정책이에요.

`update`/`delete` 동작의 세분화 권한 (Fine-grained Permissions)

애플리케이션에 부여된 update와 delete 동작은 사용자가 애플리케이션 자체에 대해서만 작업을 수행할 수 있게 해주고, 그 리소스에는 적용되지 않아요.

애플리케이션의 리소스에 작업을 허용하려면 동작을 <action>/<group>/<kind>/<ns>/<name>으로 지정하세요.

예를 들어 example-user에게 prod-app 애플리케이션에서 Pod만 삭제하도록 접근을 부여하려면 정책은 다음과 같이 할 수 있어요:

p, example-user, applications, delete/*/Pod/*/*, default/prod-app, allow

[!WARNING] glob 패턴 동작 이해하기 (Understand glob pattern behavior)

Argo CD RBAC는 glob 패턴을 평가할 때 /를 구분자로 사용하지 않아요. 그래서 delete/*/kind/* 패턴은 delete/<group>/kind/<namespace>/<name>과 매칭되지만, delete/<group>/<kind>/kind/<name>과도 매칭돼요.

둘 다 매칭되는 것은 일반적으로 문제가 되지 않아요. 리소스 종류(kind)는 일반적으로 대문자를 포함하고 네임스페이스는 대문자를 포함할 수 없기 때문이에요. 하지만 리소스 종류가 소문자가 될 수도 있어요. 그래서 패턴에 항상 리소스의 모든 부분을 포함하는 것이 좋아요(즉, 항상 슬래시 네 개를 사용하세요).

애플리케이션 자체는 제외하고 애플리케이션의 모든 리소스를 업데이트하도록 사용자에게 접근을 부여하고 싶다면:

p, example-user, applications, update/*, default/prod-app, allow

애플리케이션의 delete를 명시적으로 거부하되, 사용자가 Pod를 삭제하는 것은 허용하고 싶다면:

p, example-user, applications, delete, default/prod-app, deny
p, example-user, applications, delete/*/Pod/*/*, default/prod-app, allow

애플리케이션 자체는 업데이트를 허용하되 하위 리소스의 업데이트는 거부하고 싶다면:

p, example-user, applications, update, default/prod-app, allow
p, example-user, applications, update/*, default/prod-app, deny

[!NOTE] 애플리케이션 권한 상속 보존 (v3.0.0 이후, Preserve Application permission Inheritance)

v3 이전에는 /*가 없는 update와 delete 동작도 하위 리소스에 대해 평가되었어요.

이 동작을 보존하려면 Argo CD ConfigMap argocd-cm에서 server.rbac.disableApplicationFineGrainedRBACInheritance 값을 false로 설정할 수 있어요.

비활성화하면 애플리케이션에서 명시적으로 허용된 동작에 대해 하위 리소스의 세분화 권한을 거부할 수 없어요. 예를 들어 다음 정책은 사용자가 Pod와 애플리케이션의 다른 리소스를 삭제하는 것을 허용해요:

p, example-user, applications, delete, default/prod-app, allow
p, example-user, applications, delete/*/Pod/*, default/prod-app, deny

`action` 동작

action 동작은 Argo CD 리포지토리에 정의된 기본 제공 리소스 커스터마이즈나, 사용자가 정의한 커스텀 리소스 동작에 해당해요.

기본 제공 동작 목록은 리소스 동작 문서를 참고하세요.

<action>은 action/<group>/<kind>/<action-name> 형식이에요.

예를 들어, 리소스 커스터마이즈 경로 resource_customizations/extensions/DaemonSet/actions/restart/action.lua는 action/extensions/DaemonSet/restart라는 action 경로에 해당해요. 리소스가 그룹 아래에 없으면(예: Pod나 ConfigMap), 경로는 action//Pod/action-name이 돼요.

다음 정책은 사용자가 DaemonSet 리소스에서 어떤 동작이든 수행하고, Pod에서 maintenance-off 동작을 수행할 수 있게 해줘요:

p, example-user, applications, action//Pod/maintenance-off, default/*, allow
p, example-user, applications, action/extensions/DaemonSet/*, default/*, allow

사용자가 모든 동작을 수행하도록 허용하려면:

p, example-user, applications, action/*, default/*, allow

`override` 동작

override 동작 권한은 Application을 동기화할 때 임의의 매니페스트나 다른 리비전을 전달할 수 있게 해줘요. 예를 들어 개발 또는 테스트 목적으로 사용할 수 있어요.

주의: 이 권한은 사용자가 애플리케이션의 배포된 리소스를 완전히 변경/삭제할 수 있게 해줘요.

sync 동작 권한이 Application 객체에 정의된 대로 클러스터의 객체를 원하는 상태로 동기화할 권리를 주는 반면, override 동작 권한은 사용자가 임의의 로컬 매니페스트를 Application에 동기화할 수 있게 해줘요. 이 매니페스트는 다음 동기화가 수행될 때까지 구성된 소스 대신에 사용돼요. 이런 override 동기화를 수행한 후에는 Application 객체를 통해 정의된 상태와 애플리케이션이 OutOfSync가 될 가능성이 높아요. auto-sync가 활성화되면 override 동기화를 수행할 수 없어요.

v3.2부터 추가된 내용:

argcd-cm configmap에 application.sync.requireOverridePrivilegeForRevisionSync: 'true'를 설정하면, Application을 동기화할 때 리비전을 전달하는 것도 override로 간주돼요. Application 객체에 주어진 리비전 외의 임의의 리비전으로 동기화되는 것을 막기 위함이에요. 임의의 yaml 매니페스트로 동기화하는 것과 유사하게, 다른 리비전/브랜치/커밋으로 동기화하면 제어되는 객체가 상태를 달리하게 되어 Application에 정의된 상태와 다르게(OutOfSync) 될 수 있어요.

이 플래그의 기본 설정은 false로, 기존 설치에서 breaking change가 발생하는 것을 막기 위함이에요. 이 설정을 true로 하고 실제로 이 동작이 필요한 사용자에게만 AppProject별로 override 권한을 부여하는 것을 권장해요.

`applicationsets` 리소스

applicationsets 리소스는 애플리케이션 특화 정책이에요.

ApplicationSets는 Application을 자동으로 생성/업데이트/삭제할 수 있는 선언적 방법을 제공해요.

리소스에 create 동작을 허용하면 사실상 Application을 생성하는 능력을 부여해요. 사용자가 직접 Application을 만들 수는 없지만 ApplicationSet을 통해 Application을 만들 수 있는 것이에요.

[!NOTE] v2.5에서 템플릿화된 Project 필드(예: project: {{path.basename}})를 가진 ApplicationSet을 API(그리고 확장하면 CLI)를 통해 생성하는 것은 불가능해요. 템플릿화된 프로젝트를 금지하면 RBAC를 통한 프로젝트 제한이 안전해져요:

리소스가 애플리케이션 특화이므로 applicationsets 정책의 <object>는 <app-project>/<app-name> 형식을 가져요. 하지만 ApplicationSet은 특정 프로젝트에 속하지 않으므로, <app-project> 값은 ApplicationSet이 Application을 생성할 수 있는 프로젝트를 나타내요.

다음 정책으로 dev-group 사용자는 dev-project 프로젝트 밖에서 Application을 생성할 수 있는 ApplicationSet을 만들 수 없어요.

p, dev-group, applicationsets, *, dev-project/*, allow

`logs` 리소스

logs 리소스는 애플리케이션 특화 정책이에요.

get 동작으로 부여되면, 이 정책은 사용자가 Argo CD UI를 통해 애플리케이션의 Pod 로그를 볼 수 있게 해줘요. 기능은 kubectl logs와 유사해요.

`exec` 리소스

exec 리소스는 애플리케이션 특화 정책이에요.

create 동작으로 부여되면, 이 정책은 사용자가 Argo CD UI를 통해 애플리케이션의 Pod에 exec 할 수 있게 해줘요. 기능은 kubectl exec와 유사해요.

자세한 내용은 웹 기반 터미널을 참고하세요.

`extensions` 리소스

extensions 리소스로 프록시 확장 (proxy extensions)을 호출할 권한을 구성할 수 있어요. extensions RBAC 검증은 applications 리소스와 함께 동작해요. 사용자는 요청이 시작된 애플리케이션에 대한 읽기 권한이 있어야 해요.

아래 예시를 보면, example-user가 default 프로젝트 아래의 모든 애플리케이션에서 httpbin 확장을 호출할 수 있게 허용해요:

p, example-user, applications, get, default/*, allow
p, example-user, extensions, invoke, httpbin, allow

`deny` 효과

정책에서 효과로 deny를 사용하면, 그 정책이 매칭될 때 효과가 적용돼요. allow 효과의 더 구체적인 정책도 함께 매칭되더라도 deny가 우선순위를 가져요.

정책 파일 구성에서 정책이 나타나는 순서는 영향이 없으며 결과는 결정적(비결정적이지 않고)이에요.

정책 평가와 매칭 (Policies Evaluation and Matching)

접근 평가는 두 부분으로 수행돼요: 기본 정책 구성에 대해 검증한 다음, 현재 사용자에 대한 정책에 대해 검증하는 것이에요.

동작이 기본 정책에 의해 허용되거나 거부되면, 이 효과는 더 이상의 평가 없이 적용돼요. 효과가 정의되지 않으면 평가는 주체 특화(subject-specific) 정책으로 계속돼요.

접근은 먼저 사용자에 대해, 그 다음 사용자가 속한 각 구성된 그룹에 대해 평가돼요.

policy.matchMode에 구성된 매칭 엔진은 토큰 값을 비교하는 데 두 가지 매칭 모드를 사용할 수 있어요:

glob: glob 패키지 기반
regex: regexp 패키지 기반

평가 중에 모든 토큰이 매칭되면 효과가 반환돼요. 평가는 모든 매칭 정책이 평가될 때까지, 또는 deny 효과의 정책이 매칭될 때까지 계속돼요. 모든 정책이 평가된 후, allow 효과가 하나 이상 있었고 deny가 없었다면 접근이 허용돼요.

Glob 매칭 (Glob matching)

glob을 사용하면 정책 토큰은 구분자 없는 단일 용어로 취급돼요.

다음 정책을 고려하세요:

p, example-user, applications, action/extensions/*, default/*, allow

example-user가 extensions/DaemonSet/test 동작을 실행하면 다음 glob 매칭이 발생해요:

현재 사용자 example-user가 토큰 example-user와 매칭돼요.
값 applications가 토큰 applications와 매칭돼요.
값 action/extensions/DaemonSet/test가 action/extensions/*와 매칭돼요. /는 구분자로 취급되지 않으며 ** 사용은 필요하지 않다는 점을 참고하세요.
값 default/my-app이 default/*와 매칭돼요.

[!TIP] glob 패턴 매칭의 성능 튜닝은 고가용성 - argocd-server의 server.glob.cache.size 구성 키를 참고하세요.

SSO 사용자/그룹 사용 (Using SSO Users/Groups)

scopes 필드는 RBAC 강제 시(sub 스코프 외에) 어떤 OIDC 스코프를 검사할지 제어해요. 생략하면 기본값은 '[groups]'예요. 스코프 값은 문자열 또는 문자열 목록일 수 있어요.

scopes에 대한 자세한 내용은 사용자 관리 문서를 참고하세요.

다음 예시는 OIDC 제공자의 email과 groups를 모두 대상으로 하고, 명시적 역할 할당과 역할 간 상속을 보여줘요:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
  labels:
    app.kubernetes.io/name: argocd-rbac-cm
    app.kubernetes.io/part-of: argocd
data:
  policy.csv: |
    p, my-org:team-alpha, applications, sync, my-project/*, allow
    g, my-org:team-beta, role:admin
    g, [email protected], role:admin
    g, admin, role:admin
    g, role:admin, role:readonly
  policy.default: role:readonly
  scopes: '[groups, email]'

여기서:

g, admin, role:admin은 내장 admin 사용자를 admin 역할에 명시적으로 바인딩해요.
g, role:admin, role:readonly는 역할 상속을 보여줘요. 그래서 role:admin이 부여된 사람은 누구나 role:readonly의 모든 권한도 자동으로 가져요.

이 접근 방식은 AppProjects와 결합해 사용자의 이메일과 그룹을 프로젝트 수준에서 직접 연관시킬 수 있어요:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-beta-project
  namespace: argocd
spec:
  roles:
    - name: admin
      description: Admin privileges to team-beta
      policies:
        - p, proj:team-beta-project:admin, applications, *, team-beta-project/*, allow
      groups:
        - [email protected] # Value from the email scope
        - my-org:team-beta # Value from the groups scope

로컬 사용자/계정 (Local Users/Accounts)

로컬 사용자는 역할로 그룹핑하거나 직접 정책을 할당해서 접근 권한이 부여돼요.

아래 예시는 로컬 사용자에게 직접 정책을 할당하는 방법을 보여줘요:

p, my-local-user, applications, sync, my-project/*, allow

이 예시는 로컬 사용자에게 역할을 할당하는 방법을 보여줘요:

g, my-local-user, role:admin

[!WARNING] 모호한 그룹 할당 (Ambiguous Group Assignments)

SSO를 활성화했다면, 로컬 사용자와 이름이 일치하는 스코프를 가진 SSO 사용자는 로컬 사용자와 같은 역할에 추가돼요. 예를 들어 로컬 사용자 sally가 role:admin에 할당되었고, 어떤 SSO 사용자가 우연히 sally라는 이름의 스코프를 가진다면, 그 SSO 사용자도 role:admin에 할당돼요.

이것이 문제가 될 수 있는 예시로는 SSO 제공자가 SCM인 경우예요. 조직 구성원은 자동으로 조직 이름을 딴 스코프를 부여받아요. 사용자가 SCM에서 조직을 만들거나 자신을 조직에 추가할 수 있다면, 같은 이름을 가진 로컬 사용자의 권한을 얻을 수 있어요.

모호함을 피하려면 로컬 사용자와 SSO를 함께 사용할 때 로컬 사용자에게 직접 정책을 할당하고, 로컬 사용자에게 역할을 할당하지 않는 것이 좋아요. 즉, g, my-local-user, role:admin 대신 my-local-user에게 정책을 명시적으로 할당해야 해요:

p, my-local-user, *, *, *, allow

정책 CSV 구성 (Policy CSV Composition)

argocd-rbac-cm configmap에 추가 항목을 제공해 최종 정책 csv를 구성할 수 있어요. 이 경우 키는 policy.<any string>.csv 패턴을 따라야 해요. Argo CD는 이 패턴으로 찾은 모든 추가 정책을 기본 정책('policy.csv') 아래에 연결(concatenate)해요. 추가로 제공된 정책의 순서는 키 문자열에 의해 결정돼요.

예시: policy.A.csv와 policy.B.csv 키로 두 개의 추가 정책이 제공되면, 먼저 policy.A.csv를 연결하고 그 다음 policy.B.csv를 연결해요.

이것은 Kustomize, Helm 같은 설정 관리 도구에서 정책을 구성하는 데 유용해요.

아래 예시는 Kustomize 패치를 overlay에서 제공해 기존 RBAC ConfigMap에 추가 구성을 넣는 방법을 보여줘요:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.tester-overlay.csv: |
    p, role:tester, applications, *, */*, allow
    p, role:tester, projects, *, *, allow
    g, my-org:team-qa, role:tester

RBAC 정책 검증과 테스트 (Validating and testing your RBAC policies)

RBAC 정책이 예상대로 동작하는지 확인하려면 argocd admin settings rbac 명령으로 검증할 수 있어요. 이 도구는 특정 역할이나 주체가 아직 시스템에 적용되지 않은 정책(즉, 로컬 파일이나 config map의 정책)으로 요청된 동작을 수행할 수 있는지 테스트할 수 있게 해줘요. 또한 Argo CD가 실행 중인 클러스터의 실시간 RBAC 구성에 대해서도 사용할 수 있어요.

정책 검증 (Validating a policy)

새 정책 구성이 유효하고 Argo CD의 RBAC 구현에서 이해되는지 확인하려면 argocd admin settings rbac validate 명령을 사용할 수 있어요.

정책 테스트 (Testing a policy)

역할이나 주체(그룹 또는 로컬 사용자)가 특정 리소스에서 특정 동작을 실행할 충분한 권한이 있는지 테스트하려면 argocd admin settings rbac can 명령을 사용할 수 있어요.