ACL 정책
ACL 정책 (ACL Policies)
이 문서는 Consul의 접근 제어 목록(ACL) 시스템의 컴포넌트인 정책(policy)을 설명해요. 정책은 네트워크의 리소스와 상호작용할 권한이 있는 서비스와 에이전트를 정의해요. 정책 형식, 규칙, 정책 disposition, 예제 정책을 다룰게요.
출처: 문서
본문
이 항목은 Consul의 접근 제어 목록(ACL) 시스템의 컴포넌트인 정책을 설명합니다. 정책은 네트워크의 리소스와 상호작용할 권한이 있는 서비스와 에이전트를 정의합니다.
소개 (Introduction)
정책은 ACL 토큰에 연결된 하나 이상의 ACL 규칙 그룹입니다. 다음 다이어그램은 규칙, 정책, 토큰 간의 관계를 설명합니다:
"정책(policy)"이라는 용어는 policy 키워드와 혼동해서는 안 됩니다. 키워드는 리소스에 대한 접근을 결정하는 규칙 수준 요소입니다 (Policy Dispositions 참조).
규칙 (Rules)
규칙은 정책을 형성하는 여러 속성 중 하나입니다. 리소스에 대한 접근을 정의하는 구성 요소입니다.
이 섹션은 규칙을 정책으로 조합하는 방법을 설명합니다. 규칙을 구성하는 방법과 리소스 접근에 미치는 영향에 대한 추가 세부 정보는 ACL 규칙 참조를 참조하세요.
규칙 사양 (Rule Specification)
규칙은 리소스 선언과 policy 키워드 및 policy disposition으로 정의된 접근 수준으로 구성됩니다. 다음 구문은 규칙의 기본 구조를 설명합니다:
ACL 규칙 구성의 기본 구문 (Basic syntax for configuring an ACL rule)
HCL
<resource> {
policy = "<policy disposition>"
}
JSON
{
"<resource>": {
"policy": "<policy disposition>"
}
}
지정된 리소스에 대한 접근은 policy disposition에 따라 허용되거나 거부됩니다.
리소스 라벨 (Resource Labels)
많은 리소스는 규칙의 범위를 같은 라벨을 가진 리소스로 제한하는 추가 값을 받습니다. 리소스 라벨은 같은 name 값으로 구성된 노드 같은 특정 리소스 집합의 이름일 수 있습니다.
다음 구문은 규칙에 리소스 라벨을 포함하는 방법을 설명합니다:
명명된 리소스에 ACL 규칙을 적용하는 구문 (Syntax for applying an ACL rule to named resources)
HCL
<resource> "<label>" {
policy = "<policy disposition>"
}
JSON
{
"<resource>": {
"<label>": {
"policy": "<policy disposition>"
}
}
}
라벨은 운영자에게 리소스 접근에 대한 더 세밀한 제어를 제공하지만, 다음 리소스 유형은 라벨을 받지 않습니다:
이러한 리소스에 대한 규칙을 만들려면 다음 구문을 사용합니다:
ACL 규칙 구성을 직접 받는 리소스의 구문 (Syntax for resources that take ACL rule configurations directly)
HCL
<resource> = "<policy disposition>"
JSON
{
"<resource>": "<policy disposition>"
}
Policy Dispositions
policy 키워드와 다음 접근 수준 중 하나를 사용해 policy disposition을 설정합니다:
특수 list 접근 수준은 Consul KV에서 지정된 리소스 라벨이 있는 모든 키에 대한 접근을 제공합니다. list 접근 수준은 key_prefix 리소스에서만 사용할 수 있습니다. acl.enable_key_list_policy 설정이 true로 설정되어야 합니다.
일치 및 접두사 값 (Matching and Prefix Values)
정확한 일치 또는 같은 값으로 시작하는 여러 리소스 라벨을 일치시키는 리소스 접두사를 사용해 라벨이 있는 리소스에 대한 규칙을 정의할 수 있습니다. 정확한 값으로 리소스 라벨을 일치시키는 것은 리소스 라벨 섹션에 설명되어 있습니다.
다음 예제 규칙은 web-prod로 라벨된 서비스에 대한 접근을 거부하는 정확한 일치입니다:
'web-prod'라는 이름의 서비스 접근을 거부하는 예제 규칙 (Example rule that denies access to services named 'web-prod')
HCL
service "web-prod" {
policy = "deny"
}
JSON
{
"service": {
"web-prod": {
"policy": "deny"
}
}
}
리소스에 _prefix를 붙여 같은 값으로 시작하는 모든 리소스 라벨을 일치시킬 수 있습니다. 다음 예제 규칙은 "web"으로 시작하는 라벨이 있는 모든 서비스에 write 접근을 허용합니다:
"web"으로 시작하는 이름을 가진 서비스에 읽기·쓰기 접근을 허용하는 예제 규칙 (Example rule that grants read and write access to services with names beginning with 'web')
HCL
service_prefix "web" {
policy = "write"
}
JSON
{
"service_prefix": {
"web": {
"policy": "write"
}
}
}
접두사 기반 리소스 라벨은 빈 문자열을 포함할 수도 있으며, 이는 규칙이 선언된 유형의 모든 리소스에 적용되도록 구성합니다. 다음 예제 규칙은 모든 service 리소스에 read 접근을 허용합니다:
모든 서비스에 읽기 접근을 허용하는 예제 규칙 (Example rule that grants read access to all services)
HCL
service_prefix "" {
policy = "read"
}
JSON
{
"service_prefix": {
"": {
"policy":"read"
}
}
}
접두사 기반 규칙을 사용할 때 가장 구체적인 접두사 일치가 작업을 결정합니다. 실제 시나리오에서는 규칙의 조합이 결합되어 유연한 정책을 만듭니다. 각 팀 또는 사업 단위는 여러 규칙을 시행하는 정책에 기반한 토큰을 사용합니다, 예를 들어:
- 특정 리소스 라벨에 대한 접근을 거부하는 규칙
- 리소스 클래스에 쓰기 접근을 허용하는 접두사 기반 규칙
- 선언된 클래스 내 모든 리소스에 대한 읽기 전용 접근을 부여하는 빈 접두사
일치 우선순위 (Matching Precedence)
정확한 일치 규칙은 지정된 정확한 리소스에만 적용됩니다. 일치 규칙의 우선순위 순서는 다음과 같습니다:
정책 형식 (Policy Format)
HashiCorp 구성 언어 (HCL)를 사용해 정책을 정의합니다. HCL은 사람이 읽을 수 있고 JSON과 상호 운용 가능하여 정책 생성을 자동화하기 쉽습니다. 다음 예제는 HCL과 JSON으로 포맷된 동일한 정책을 보여줍니다:
예제 규칙 (Example rules)
HCL
# These control access to the key/value store.
key_prefix "" {
policy = "read"
}
key_prefix "foo/" {
policy = "write"
}
key_prefix "foo/private/" {
policy = "deny"
}
# Or for exact key matches
key "foo/bar/secret" {
policy = "deny"
}
# This controls access to cluster-wide Consul operator information.
operator = "read"
JSON
{
"key_prefix": {
"": {
"policy": "read"
},
"foo/": {
"policy": "write"
},
"foo/private/": {
"policy": "deny"
}
},
"key": {
"foo/bar/secret": {
"policy": "deny"
}
},
"operator": "read"
}
규칙 범위 (Rule Scope)
역할과 서비스 아이덴티티를 포함한 모든 정책의 규칙은 토큰과 연결된 규칙이 결합되어 해당 토큰의 유효 규칙 집합을 형성합니다. 정책 규칙은 acl_default_policy 구성에 따라 allowlist 또는 denylist 모드로 정의될 수 있습니다. 기본 정책이 모든 리소스에 대한 접근을 거부하도록 구성된 경우 정책 규칙에 allowlist를 지정해 리소스에 대한 접근을 명시적으로 허용할 수 있습니다. 반대로 기본 정책이 모든 리소스에 대한 접근을 허용하도록 구성된 경우 정책 규칙에 denylist를 지정해 리소스에 대한 접근을 명시적으로 거부할 수 있습니다.
정책 구현 (Implementing Policies)
정책을 정의한 후 조직에서 ACL을 관리하는 담당자는 명령줄을 통해 또는 페이로드에 규칙을 포함해 ACL HTTP API 엔드포인트를 호출해 구현할 수 있습니다.
명령줄 (Command Line)
정책을 관리하려면 consul acl policy 명령을 사용합니다. 자세한 내용은 ACL 명령줄 문서를 참조하세요.
다음 예제는 my-app-policy라는 정책을 만들고 rules.hcl에 정의된 규칙을 적용합니다:
$ consul acl policy create -name "my-app-policy" -description "Human-readable description of my policy" -rules @rules.hcl -token "<token with ACL 'write' access>"
명령은 ACL 시스템을 사용할 권한이 있는 토큰을 제시해야 합니다. 명령이 성공적으로 실행되면 콘솔이 정책에 대한 정보를 출력합니다:
ID: <auto-generated ID>
Name: my-app-policy
Description: Human-readable description of my policy
Datacenters: <specified with the -valid-datacenter option>
Rules:
<rules defined in the rules.hcl file>
추가 메타데이터를 첨부하고 정책의 범위를 지정하는 여러 속성을 정의할 수 있습니다. 자세한 내용은 정책 속성을 참조하세요.
HTTP API 엔드포인트 (HTTP API Endpoint)
엔드포인트는 HCL 또는 JSON으로 포맷된 데이터를 받습니다. API에 대한 자세한 내용은 ACL HTTP API 엔드포인트 문서를 참조하세요.
다음 예제는 my-app-policy라는 정책에 규칙 집합을 추가합니다. 정책은 key 리소스(Consul K/V)에 대한 접근을 정의합니다. 규칙은 HCL로 포맷되지만 cURL로 보낼 수 있도록 JSON으로 감싸집니다:
$ curl \
--request PUT \
--header "X-Consul-Token: <token with ACL 'write' access>" \
--data \
'{
"Name": "my-app-policy",
"Rules": "key \"\" { policy = \"read\" } key \"foo/\" { policy = \"write\" } key \"foo/private/\" { policy = \"deny\" } operator = \"read\""
}' http://127.0.0.1:8500/v1/acl/policy
다음 호출은 JSON을 사용해 이전 예제와 동일한 작업을 수행합니다:
$ curl \
--request PUT \
--header "X-Consul-Token: <management token>" \
--data \
'{
"Name": "my-app-policy",
"Rules": "{\"key\":{\"\":{\"policy\":\"read\"},\"foo/\":{\"policy\":\"write\"},\"foo/private\":{\"policy\":\"deny\"}},\"operator\":\"read\"}"
}' http://127.0.0.1:8500/v1/acl/policy
호출이 성공적으로 수행되면 정책 구성이 반환됩니다:
{
"CreateIndex": 7,
"Hash": "UMG6QEbV40Gs7Cgi6l/ZjYWUwRS0pIxxusFKyKOt8qI=",
"ID": "5f423562-aca1-53c3-e121-cb0eb2ea1cd3",
"ModifyIndex": 7,
"Name": "my-app-policy",
"Rules": "key \"\" { policy = \"read\" } key \"foo/\" { policy = \"write\" } key \"foo/private/\" { policy = \"deny\" } operator = \"read\""
}
정책을 토큰에 연결 (Linking Policies to Tokens)
구현된 정책은 정책이 효과를 가지기 전에 여전히 토큰에 연결되어야 합니다. 서비스 또는 에이전트는 네트워크의 리소스와 상호작용할 때 토큰을 제시합니다. ACL 시스템 프로세스는 토큰에 연결된 정책을 평가해 요청자가 요청한 리소스에 대한 접근 권한이 있는지 결정합니다.
ACL을 관리하는 담당자는 명령줄을 사용하거나 API 엔드포인트를 호출해 정책을 토큰에 연결할 수 있습니다. 토큰은 Consul의 인증 메서드 기능을 사용해 외부 시스템에서 동적으로 생성될 수도 있습니다.
정책을 만들고 토큰에 연결하는 방법에 대한 자세한 내용은 토큰 문서 및 ACL 튜토리얼을 참조하세요.
정책 속성 (Policy Attributes)
정책은 특정 기능을 수행할 수 있게 하는 여러 속성을 가질 수 있습니다. 예를 들어, 정책과 상호작용하거나 만들 때 데이터센터, 네임스페이스(Consul Enterprise) 또는 어드민 파티션(Consul Enterprise)의 이름을 지정해 정책의 범위를 구성할 수 있습니다.
ID 및 name 필드의 값 같은 추가 메타데이터는 정책을 업데이트·관리하기 위한 핸들을 제공합니다.
추가 정보는 다음 항목을 참조하세요:
ACL 정책은 다음 속성을 가질 수 있습니다:
| 속성 (Attribute) | 설명 (Description) | 필수 (Required) | 기본값 (Default) |
| ID | 정책의 공개 식별자. 정책과 상호작용할 때 ID(또는 name) 값을 제시. 정책을 만들 때 값을 지정하거나 Consul이 자동 생성한 값을 사용. | N/A | N/A |
| name | 정책의 고유 이름. | Required | none |
| description | 정책의 사람이 읽을 수 있는 설명. | Optional | none |
| rules | 권한을 부여하거나 거부하는 규칙 집합. 자세한 내용은 규칙 사양 문서 참조. | Optional | none |
| datacenter | 정책이 유효한 데이터센터. 둘 이상의 데이터센터를 지정할 수 있음. | Optional | none |
| namespace | Enterprise 정책이 유효한 네임스페이스. Consul Enterprise 1.7.0에서 추가. | Optional | default |
| partition | Enterprise 정책이 유효한 어드민 파티션. Consul Enterprise 1.11.0에서 추가. | Optional | default |
기본이 아닌 네임스페이스와 파티션 - default가 아닌 네임스페이스 또는 어드민 파티션에 연결된 정책에 정의된 규칙은 해당 네임스페이스 또는 파티션에 영향을 미치는 권한의 부분집합만 부여할 수 있습니다. 추가 정보는 네임스페이스 규칙 및 어드민 파티션 규칙을 참조하세요.
명령줄이나 API를 통해 현재 ACL 정책을 볼 수 있습니다. 다음 예제는 명령줄 사용을 보여줍니다:
$ consul acl policy list -format json -token <token_id>
[
{
"ID": "56595ec1-52e4-d6de-e566-3b78696d5459",
"Name": "b-policy",
"Description": "",
"Datacenters": null,
"Hash": "ULwaXlI6Ecqb9YSPegXWgVL1LlwctY9TeeAOhp5HGBA=",
"CreateIndex": 126,
"ModifyIndex": 126,
"Namespace": "default",
"Partition": "default"
},
{
"ID": "00000000-0000-0000-0000-000000000001",
"Name": "global-management",
"Description": "Builtin Policy that grants unlimited access",
"Datacenters": null,
"Hash": "W1bQuDAlAlxEb4ZWwnVHplnt3I5oPKOZJQITh79Xlog=",
"CreateIndex": 70,
"ModifyIndex": 70,
"Namespace": "default",
"Partition": "default"
}
]
Hash, CreateIndex, ModifyIndex 속성도 출력됩니다. 이 속성은 모든 응답에 대해 출력되며 ACL 정책에 특정한 것이 아닙니다.
내장 정책 (Built-in Policies)
새 Consul 설치에는 다음과 같은 내장 정책이 포함되어 있습니다.
Global Management
global-management 정책은 연결된 모든 토큰에 무제한 권한을 부여합니다. 이 정책에는 예약된 ID 00000000-0000-0000-0000-000000000001이 할당됩니다. global management 정책의 이름을 바꿀 수 있지만 Consul은 규칙 집합과 데이터센터 범위를 포함한 다른 속성의 수정을 방지합니다.
Global Read-Only
builtin/global-read-only 정책은 연결된 모든 토큰에 무제한 읽기 전용 권한을 부여합니다. 이 정책에는 예약된 ID 00000000-0000-0000-0000-000000000002이 할당됩니다. global read-only 정책의 이름을 바꿀 수 있지만 Consul은 규칙 집합과 데이터센터 범위를 포함한 다른 속성의 수정을 방지합니다.
Namespace Management Enterprise
namespace-management 정책은 여러분이 만드는 모든 네임스페이스에 주입됩니다. 이 정책에는 무작위화된 UUID가 할당되며 네임스페이스 내에서 일반 사용자 정의 정책으로 관리할 수 있습니다. 이 기능은 Consul Enterprise 1.7.0에서 추가되었습니다.
예제 정책 (Example Policies)
이 섹션은 특정 사용 사례를 달성하기 위한 예제 정책 구성을 포함합니다.
특정 노드에서 스냅샷 에이전트를 실행할 수 있게 (Enable the Snapshot Agent to Run on a Specific Node)
consul snapshot agent 명령은 Consul 서버 상태의 스냅샷을 만들고 로컬에 저장하거나 원격 스토리지 서비스로 푸시하는 프로세스를 시작합니다. 추가 정보는 Consul 스냅샷 에이전트를 참조하세요.
다음 예제에서 ACL 정책은 server-1234라는 노드에서 스냅샷 에이전트가 실행될 수 있게 합니다.
HCL
# Required to read and snapshot ACL data
acl = "write"
# Allow the snapshot agent to create the key consul-snapshot/lock which will
# serve as a leader election lock when multiple snapshot agents are running in
# an environment
key "consul-snapshot/lock" {
policy = "write"
}
# Allow the snapshot agent to create sessions on the specified node
session "server-1234" {
policy = "write"
}
# Allow the snapshot agent to register itself into the catalog
service "consul-snapshot" {
policy = "write"
}
JSON
{
"acl": "write",
"key": {
"consul-snapshot/lock": {
"policy": "write"
}
},
"session": {
"server-1234": {
"policy": "write"
}
},
"service": {
"consul-snapshot": {
"policy": "write"
}
}
}
Vault가 Consul 스토리지 백엔드에 접근할 수 있게 (Enable Vault to Access the Consul Storage Backend)
인프라에서 시크릿을 관리하기 위해 Vault를 사용하는 경우, Vault의 데이터를 영구 저장하기 위해 Vault가 Consul의 키/값(KV) 저장소를 백엔드 스토리지로 사용하도록 구성할 수 있습니다. 추가 정보는 Consul KV 문서와 Vault 스토리지 문서를 참조하세요.
다음 예제에서 ACL 정책은 Vault가 서비스로 등록할 수 있게 하고 Consul의 KV 저장소에서 vault/ 경로에 대한 접근을 제공합니다.
HCL
# Provide KV visibility to all agents.
agent_prefix "" {
policy = "read"
}
# Enable resources prefixed with 'vault/' to write to the KV
key_prefix "vault/" {
policy = "write"
}
# Enable the vault service to write to the KV
service "vault" {
policy = "write"
}
# Enable the agent to initialize a new session.
session_prefix "" {
policy = "write"
}
JSON
{
"agent_prefix": {
"": {
"policy": "read"
}
},
"key_prefix": {
"vault/": {
"policy": "write"
}
},
"service": {
"vault": {
"policy": "write"
}
},
"session_prefix": {
"": {
"policy": "write"
}
}
}