ACL 역할
ACL 역할 (ACL Role)
역할(role)은 ACL 관리자가 토큰에 연결할 수 있는 정책 모음이에요. 여러 정책을 역할 하나로 묶어 팀원에게 배포되는 토큰과 분리하면 정책을 재사용하고 유연하게 갱신할 수 있어요. 이 문서에서는 역할 생성, 역할 속성, 템플릿 정책, 서비스·노드 아이덴티티를 설명할게요.
출처: 문서
본문
역할(role)은 ACL 관리자가 토큰에 연결할 수 있는 정책 모음입니다. 역할을 사용하면 팀원에게 배포되는 토큰에서 정책을 분리하여 정책을 재사용할 수 있습니다. 대신 토큰은 역할에 연결되며, 역할은 사용자에게 새 토큰을 배포하지 않고도 비동기적으로 갱신할 수 있는 여러 정책을 보유할 수 있습니다. 결과적으로 역할은 요청자마다 고유한 정책과 토큰을 만드는 것보다 더 편리한 인증 인프라를 제공할 수 있습니다.
워크플로 개요 (Workflow overview)
역할은 여러 정책을 토큰에 연결하는 구성입니다. 다음 절차는 역할을 구현하기 위한 워크플로를 설명합니다.
- 규칙을 정책으로 조합하고 Consul에 등록합니다.
- 역할을 정의하고 정책 ID 또는 이름을 포함합니다.
- Consul에 역할을 등록하고 토큰에 연결합니다.
- 구현을 위해 토큰을 사용자에게 배포합니다.
역할 생성 (Create roles)
역할 생성은 일반적으로 Consul ACL 관리자의 책임입니다. 역할에는 서비스 아이덴티티와 노드 아이덴티티를 포함한 여러 속성이 있습니다. 자세한 내용은 다음 문서를 참조하세요:
Consul CLI 또는 API 엔드포인트를 사용해 역할을 만듭니다.
CLI
역할을 만들려면 consul acl role create 명령을 실행합니다. 다음 예제에서는 crawler-kv 정책과 crawler-key 정책을 포함하는 crawler라는 역할이 생성됩니다.
$ consul acl role create -name "crawler" -description "web crawler role" -policy-name "crawler-kv" -policy-name "crawler-key"
자세한 내용은 CLI 문서를 참조하세요.
API
역할을 만들려면 acl/role 엔드포인트에 PUT 호출을 하고 페이로드에 역할 구성을 지정합니다. 역할 정의를 JSON 파일에 저장하거나 호출에서 이스케이프된 JSON을 사용할 수 있습니다. 다음 예제 호출에서는 페이로드가 외부에 정의됩니다.
$ curl --request PUT --data @payload.json http://127.0.0.1:8500/v1/acl/role
자세한 내용은 API 문서를 참조하세요.
역할 속성 (Role attributes)
역할은 다음 속성을 포함할 수 있습니다:
ID:ID는 자동 생성된 공개 식별자입니다. 토큰에 연결할 때 역할ID를 지정할 수 있습니다.Name: 역할의 고유한 의미 있는 이름입니다. 토큰에 연결할 때 역할Name을 지정할 수 있습니다.Description: (선택) 역할에 대한 사람이 읽을 수 있는 설명.Policies: 역할에 적용되는 정책 목록을 지정합니다. 객체는 정책ID또는Name속성을 참조할 수 있습니다.TemplatedPolicies: 역할에 적용되는 템플릿 정책 목록을 지정합니다. 자세한 내용은 템플릿 정책을 참조하세요.ServiceIdentities: 역할에 적용되는 서비스 목록을 지정합니다. 자세한 내용은 서비스 아이덴티티를 참조하세요.NodeIdentities: 역할에 적용되는 노드 목록을 지정합니다. 자세한 내용은 노드 아이덴티티를 참조하세요.Namespace: Enterprise 정책이 있는 네임스페이스. 역할은 같은 네임스페이스에 정의된 정책에만 연결할 수 있습니다. 추가 정보는 네임스페이스를 참조하세요. Consul Enterprise 1.7.0+ 필요.Partition: Enterprise 정책이 있는 어드민 파티션. 역할은 같은 어드민 파티션에 정의된 정책에만 연결할 수 있습니다. 추가 정보는 어드민 파티션을 참조하세요. Consul Enterprise 1.10.0+ 필요.
템플릿 정책 (Templated policies)
역할을 구성하거나 토큰을 정책에 연결할 때 템플릿 정책을 지정할 수 있습니다. 템플릿 정책은 각 사용 사례에 대해 동일한 정책을 만드는 대신 일반적인 Consul 사용 사례에 대한 정책을 빠르게 구성할 수 있게 합니다.
Consul은 권한 부여 과정에서 지정된 사용 사례에 대한 정책을 자동 생성하기 위해 템플릿 정책을 사용합니다. Consul은 생성된 정책을 역할 또는 토큰에 연결하여 특정 사용 사례에 대한 권한을 가지게 합니다.
템플릿 정책 사양 (Templated policy specification)
다음 템플릿 정책 예제 구성은 builtin/service 템플릿 정책을 사용해 api라는 서비스와 그 사이드카 프록시에 카탈로그에 등록하는 데 필요한 권한을 부여합니다.
{
"TemplatedPolicies": [
{
"TemplateName": "builtin/service",
"TemplateVariables": {
"Name": "api"
}
}
]
}
TemplatedPolicies: 템플릿 정책 블록을 선언합니다.TemplatedPolicies.TemplateName: 사용하려는 템플릿 정책의 이름을 지정하는 문자열 값.TemplatedPolicies.TemplateVariables: 템플릿 정책에 필요한 변수를 지정하는 맵. 모든 템플릿 정책이 변수를 요구하는 것은 아니므로 이 필드는 선택 사항입니다.
추가 정보와 예제는 역할 API 문서를 참조하세요.
Consul Enterprise
Consul Enterprise에서 템플릿 정책은 해당 ACL 토큰 또는 역할의 네임스페이스 또는 어드민 파티션 범위를 상속합니다.
builtin/service 샘플 템플릿 정책은 api라는 서비스에 대해 다음 정책을 생성합니다:
# Allow the service and its sidecar proxy to register into the catalog.
service "api" {
policy = "write"
}
service "api-sidecar-proxy" {
policy = "write"
}
# Allow for any potential upstreams to be resolved.
service_prefix "" {
policy = "read"
}
node_prefix "" {
policy = "read"
}
정책의 규칙에 대한 정보는 규칙 참조를 참조하세요.
템플릿 정책이 있는 예제 역할 구성 (Example role configuration with templated policies)
다음 역할 구성은 web라는 서비스가 자신과 사이드카를 카탈로그에 등록하는 데 필요한 권한을 역할에 부여하는 템플릿 정책을 포함합니다.
example-role.json
{
"Name": "example-role",
"Description": "Showcases all input parameters",
"TemplatedPolicies": [
{
"TemplateName": "builtin/service",
"TemplateVariables": {
"Name": "web"
}
}
]
}
권한 부여 과정에서 Consul은 web 서비스에 대해 다음 정책을 생성하고 토큰에 연결합니다:
web-policy.hcl
# Allow the service and its sidecar proxy to register into the catalog.
service "web" {
policy = "write"
}
service "web-sidecar-proxy" {
policy = "write"
}
# Allow for any potential upstreams to be resolved.
service_prefix "" {
policy = "read"
}
node_prefix "" {
policy = "read"
}
서비스 아이덴티티 (Service identities)
역할을 구성하거나 토큰을 정책에 연결할 때 서비스 아이덴티티를 지정할 수 있습니다. 서비스 아이덴티티는 각 서비스에 대해 동일한 정책을 만드는 대신 서비스에 대한 정책을 빠르게 구성할 수 있게 합니다.
Consul은 권한 부여 과정에서 지정된 서비스에 대한 정책을 자동 생성하기 위해 서비스 아이덴티티를 사용합니다. 정책은 역할 또는 토큰에 연결되어 서비스가 서비스 메시에서 발견되고 다른 정상 서비스 인스턴스를 발견할 수 있게 합니다. Consul 서비스 메시에 대한 추가 정보는 서비스 메시 항목을 참조하세요.
서비스 아이덴티티 사양 (Service identity specification)
서비스 아이덴티티를 정의하려면 다음 구문을 사용합니다:
{
"ServiceIdentities": [
{
"ServiceName": "<service name>",
"Datacenters": ["<datacenter name>"]
}
]
}
ServiceIdentities: 서비스 아이덴티티 블록을 선언합니다.ServiceIdentities.ServiceName: 정책과 연관시킬 서비스의 이름을 지정하는 문자열 값.ServiceIdentities.Datacenters: 서비스 아이덴티티가 적용되는 데이터센터의 이름을 지정하는 배열. 이 필드는 선택 사항입니다.
추가 정보와 예제는 역할 API 문서를 참조하세요.
네임스페이스 및 어드민 파티션 범위 (Scope for namespace and admin partition)
Consul Enterprise에서 서비스 아이덴티티는 해당 ACL 토큰 또는 역할의 네임스페이스 또는 어드민 파티션 범위를 상속합니다.
서비스 아이덴티티를 선언하면 Consul은 각 서비스에 대해 다음 정책을 생성합니다:
# Allow the service and its sidecar proxy to register into the catalog.
service "<service name>" {
policy = "write"
}
service "<service name>-sidecar-proxy" {
policy = "write"
}
# Allow for any potential upstreams to be resolved.
service_prefix "" {
policy = "read"
}
node_prefix "" {
policy = "read"
}
정책의 규칙에 대한 정보는 규칙 참조를 참조하세요.
서비스 아이덴티티가 있는 예제 역할 구성 (Example role configuration with service identities)
다음 역할 구성은 web 및 db 서비스에 대한 서비스 아이덴티티를 포함합니다. db 서비스는 dc1 데이터센터로 범위가 지정되어 정책이 dc1의 db 인스턴스에만 적용됩니다.
example-role.json
{
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765"
},
{
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "web"
},
{
"ServiceName": "db",
"Datacenters": ["dc1"]
}
],
"NodeIdentities": [
{
"NodeName": "node-1",
"Datacenter": "dc2"
}
]
}
권한 부여 과정에서 Consul은 web 및 db 서비스에 대해 다음 정책을 생성하고 토큰에 연결합니다:
web-policy.hcl
# Allow the service and its sidecar proxy to register into the catalog.
service "web" {
policy = "write"
}
service "web-sidecar-proxy" {
policy = "write"
}
# Allow for any potential upstreams to be resolved.
service_prefix "" {
policy = "read"
}
node_prefix "" {
policy = "read"
}
ServiceIdentities.Datacenters 구성에 따라 db 정책은 dc1 데이터센터의 리소스로 범위가 지정됩니다.
db-policy.hcl
# Allow the service and its sidecar proxy to register into the catalog.
service "db" {
policy = "write"
}
service "db-sidecar-proxy" {
policy = "write"
}
# Allow for any potential upstreams to be resolved.
service_prefix "" {
policy = "read"
}
node_prefix "" {
policy = "read"
}
노드 아이덴티티 (Node identities)
역할을 구성하거나 토큰을 정책에 연결할 때 노드 아이덴티티를 지정할 수 있습니다. _노드_는 일반적으로 Consul 에이전트를 가리키지만 물리 서버, 클라우드 인스턴스, 가상 머신, 컨테이너일 수도 있습니다.
노드 아이덴티티는 각 노드에 대해 동일한 정책을 수동으로 만드는 대신 노드에 대한 정책을 빠르게 구성할 수 있게 합니다. 권한 부여 과정에서 지정된 노드에 대한 정책을 자동 생성하는 데 사용됩니다. 에이전트를 구성할 때 acl_tokens_agent 필드에 정책에 연결된 토큰을 지정할 수 있습니다.
노드 아이덴티티 사양 (Node identity specification)
노드 아이덴티티를 정의하려면 다음 구문을 사용합니다:
{
"NodeIdentities": [
{
"NodeName": "<node name>",
"Datacenter": "<datacenter name>"
}
]
}
NodeIdentities: 노드 아이덴티티 블록을 선언합니다.NodeIdentities.NodeName: 정책과 연관시킬 노드의 이름을 지정하는 문자열 값.NodeIdentities.Datacenter: 노드 아이덴티티가 적용되는 데이터센터의 이름을 지정하는 문자열 값.
추가 정보와 예제는 역할 API 문서를 참조하세요.
Consul Enterprise 네임스페이싱 (Consul Enterprise Namespacing)
노드 아이덴티티는 default 네임스페이스의 토큰과 역할에만 적용할 수 있습니다. 생성된 정책 규칙은 모든 네임스페이스의 모든 서비스에 대해 service:read 권한을 허용합니다.
노드 아이덴티티를 선언하면 Consul은 각 노드에 대해 다음 정책을 생성합니다:
# Allow the agent to register its own node in the Catalog and update its network coordinates
node "<node name>" {
policy = "write"
}
# Allows the agent to detect and diff services registered to itself. This is used during
# anti-entropy to reconcile difference between the agents knowledge of registered
# services and checks in comparison with what is known in the Catalog.
service_prefix "" {
policy = "read"
}
정책의 규칙에 대한 정보는 규칙 참조를 참조하세요.
노드 아이덴티티가 있는 예제 역할 구성 (Example role configuration with node identities)
다음 역할 구성은 node-1에 대한 노드 아이덴티티를 포함합니다. 노드 아이덴티티는 dc2 데이터센터로 범위가 지정되어 정책이 dc2의 node-1이라는 노드에만 적용됩니다.
example-role.json
{
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765"
},
{
"Name": "node-read"
}
],
"NodeIdentities": [
{
"NodeName": "node-1",
"Datacenter": "dc2"
}
]
}
권한 부여 과정에서 Consul은 다음 정책을 생성하고 토큰에 연결합니다:
node-1-policy.hcl
# Allow the agent to register its own node in the Catalog and update its network coordinates
node "node-1" {
policy = "write"
}
# Allows the agent to detect and diff services registered to itself. This is used during
# anti-entropy to reconcile differences between the agent's knowledge of registered
# services and checks in comparison with what is known in the Catalog.
service_prefix "" {
policy = "read"
}