Vault를 사용한 ACL 토큰 관리
Vault를 사용한 ACL 토큰 관리 (Manage ACL Tokens with Vault)
이 문서는 Vault를 사용해 Consul의 ACL 토큰을 관리하는 과정을 설명해요. Vault에서 Consul 시크릿 엔진을 구성하고, 서버 토큰을 생성하며, 에이전트 토큰을 설정하는 과정을 다룰게요.
출처: 문서
본문
이 페이지는 Vault를 사용해 Consul의 ACL 토큰을 관리하는 과정을 설명합니다.
소개 (Introduction)
액세스 제어 목록(ACL)은 정책·아이덴티티와 연결된 토큰을 사용해 Consul 리소스에 대한 세분화된 접근을 제공하는 Consul 보안 계층입니다.
HashiCorp Vault에는 단기 Consul 토큰을 생성하는 전용 시크릿 엔진이 있습니다: Consul 시크릿 엔진. 이 엔진은 ACL 정책을 기반으로 Consul ACL 토큰을 동적으로 생성합니다.
토큰 임대 기간과 회전 (Token lease duration and rotation)
Vault의 Consul 시크릿 엔진으로 만든 토큰은 기본 Time To Live (TTL) 768시간(30일)을 가집니다.
TTL이 만료되면 토큰은 더 이상 유효하지 않으며 Consul에서 자동으로 제거됩니다.
Consul 중단을 피하려면 주기적으로 새 토큰을 생성하고 서버에 적용하는 프로세스를 구축해야 합니다.
선행 요구 사항 (Prerequisites)
- Consul: ACL이 활성화되고 부트스트랩된 Consul 서버 노드가 최소 하나 필요합니다. VM에 Consul 배포를 따라 Consul 에이전트를 배포하는 방법을 배우세요.
CONSUL_HTTP_ADDR와CONSUL_HTTP_TOKEN을 설정해 터미널이 Consul과 상호작용하도록 구성하세요. ACL 토큰을 만들어야 하므로global-management정책과 연결된 토큰을 사용하세요. - Vault: 네트워크에 실행 중인 Vault 클러스터가 필요합니다. 로컬 Vault dev 서버 또는 기존 Vault 배포를 사용할 수 있습니다.
VAULT_ADDR,VAULT_CACERT,VAULT_TOKEN을 설정해 터미널이 Vault 클러스터와 상호작용하도록 구성하세요.
아래 다이어그램은 기능을 시연하는 데 필요한 최소 아키텍처를 보여줍니다.
참고
브라우저의 호스팅 터미널 세션에서 따라 하려면 Nomad 샌드박스를 사용할 수 있습니다. 이 샌드박스에는 미리 구성된 Consul과 Vault 배포가 포함되어 있습니다.
워크플로 (Workflow)
Vault를 구성하고 Consul ACL 토큰 관리를 위해 사용하는 워크플로는 다음 단계로 구성됩니다:
또한 만드는 토큰의 TTL을 조정해 단기 Consul 토큰을 생성할 수 있습니다.
Vault에서 Consul 시크릿 엔진 구성 (Configure the Consul secrets engine in Vault)
Vault에서 Consul 시크릿 엔진을 활성화합니다.
$ vault secrets enable consul
Success! Enabled the consul secrets engine at: consul/
Vault가 Consul의 주소와 관리 토큰으로 접근하도록 구성합니다.
$ vault write consul/config/access address=${CONSUL_HTTP_ADDR} token=${CONSUL_HTTP_TOKEN}
Success! Data written to: consul/config/access
Vault를 사용해 Consul 서버 토큰 생성 (Generate Consul server tokens using Vault)
Consul 데이터센터를 보호하기 위해 서버 에이전트마다 개별 토큰을 만들 것을 권장합니다. 그렇게 하면 전역 관리 정책이 첨부된 고수준 관리 토큰을 할당받지 않고도 Consul 데이터센터의 나머지와 상호작용할 수 있습니다.
Consul 서버용 ACL 토큰을 생성하는 데 필요한 단계는 다음과 같습니다:
서버 노드용 Consul ACL 정책 생성 (Create a Consul ACL policy for server nodes)
다음 내용으로 server_policy.hcl이라는 파일을 만듭니다.
server_policy.hcl:
node_prefix "consul-server-" {
policy = "write"
}
node_prefix "" {
policy = "read"
}
service_prefix "" {
policy = "read"
}
팁
이 시나리오에서 서버 노드는 consul-server-<count_or_id> 스키마를 따라 이름이 지정됩니다. node_prefix 값을 여러분의 시나리오에 맞게 조정하세요.
consul acl 명령으로 정책을 생성합니다.
$ consul acl policy create \
-name consul-servers \
-rules @server_policy.hcl
예제 출력:
ID: 0d275732-ba15-9457-d9c0-65e914b7e404
Name: consul-servers
Description:
Datacenters:
Rules:
node_prefix "consul-server-" {
policy = "write"
}
node_prefix "" {
policy = "read"
}
service_prefix "" {
policy = "read"
}
이제 Consul 정책과 연결된 서로 다른 토큰을 만들 수 있습니다.
정책과 연결된 Vault 역할 생성 (Create a Vault role associated with the policy)
정책을 사용해 Consul 토큰을 만들 Vault 역할을 생성합니다.
$ vault write consul/roles/consul-server-role policies=consul-servers
Success! Data written to: consul/roles/consul-server-role
Vault 역할을 사용해 토큰을 만들면 토큰은 토큰 생성 시 역할에 연결된 정책에 따라 권한을 받습니다.
역할 구성을 변경해도(예: 새 정책 연결) 이전에 생성된 토큰에는 적용되지 않습니다. 이는 기존 토큰에 실수로 추가 권한을 부여하는 것을 방지합니다.
역할을 만들 때 Consul의 노드 아이덴티티와 서비스 아이덴티티를 사용할 수도 있습니다. 자세한 내용은 Vault 문서의 Consul 시크릿 엔진을 참조하세요.
Vault에서 Consul ACL 토큰 생성 (Generate Consul ACL tokens from Vault)
기존 Vault 역할을 사용해 Consul 토큰을 만듭니다.
$ vault read consul/creds/consul-server-role | tee consul-server.token
Key Value
--- -----
lease_id consul/creds/consul-server-role/tzsDqyEEQqA3iuTVjdvxlSOp
lease_duration 768h
lease_renewable true
accessor d5cf3fa4-18ac-eb1d-e5e8-eda5cde4cfc2
consul_namespace n/a
local false
partition n/a
token 7092c156-4ca2-55ab-57e4-ce59d0a8e67b
Vault와 Consul이 명령 출력에서 토큰을 참조하는 방식은 약간 다릅니다. 다음 표는 두 출력 사이의 관계를 나타냅니다.
| Consul | Vault | 의미 (Meaning) |
| AccessorID | accessor | Consul과 Vault 내부의 토큰 고유 식별자. |
| SecretID | token | 구성과 운영에 사용할 실제 토큰. |
Vault의 Consul 시크릿 엔진을 사용하면 토큰이 Consul에 복제될 때 이러한 값이 일관되게 유지됩니다.
파일에서 accessor 값을 가져옵니다.
$ export CONSUL_SERVER_ACCESSOR=$(cat consul-server.token | grep accessor | awk '{print $2}')
accessor로 검색해 Consul에서 토큰이 올바르게 생성되었는지 확인합니다.
$ consul acl token read -accessor-id ${CONSUL_SERVER_ACCESSOR}
AccessorID: d5cf3fa4-18ac-eb1d-e5e8-eda5cde4cfc2
SecretID: 7092c156-4ca2-55ab-57e4-ce59d0a8e67b
Description: Vault consul-server-role token 1764259659418057347
Local: false
Create Time: 2025-11-27 16:07:39.419416889 +0000 UTC
Policies:
0d275732-ba15-9457-d9c0-65e914b7e404 - consul-servers
Consul 서버 에이전트 토큰 설정 (Set Consul server agent token)
Consul 서버 에이전트에 ACL이 구성되지 않으면 데이터센터에 완전히 조인하지 못할 수 있습니다. 에이전트 로그에 경고가 출력됩니다:
[WARN] agent: Coordinate update blocked by ACLs: accessorID="anonymous token"
[WARN] agent: Coordinate update blocked by ACLs: accessorID="anonymous token"
이 경고는 다음을 나타냅니다:
- 에이전트가 Consul 데이터센터에서 정보를 업데이트하려고 하지만 올바른 권한이 없어 ACL 시스템에 의해 거부되었습니다.
- 에이전트에 요청을 수행할 할당된 토큰이 없고
anonymous token을 사용하고 있습니다.
이전 단계에서 생성한 토큰 파일에서 토큰 값을 가져옵니다.
$ export CONSUL_SERVER_TOKEN=$(cat consul-server.token | grep token | awk '{print $2}')
그런 다음 토큰 값으로 Consul 서버의 에이전트 토큰을 설정합니다.
$ consul acl set-agent-token agent ${CONSUL_SERVER_TOKEN}
ACL token "agent" set successfully
토큰이 적용되면 Consul 로그를 다시 확인해 경고 줄이 더 이상 기록되지 않는지 확인합니다.
## ...
[INFO] agent: Updated agent's ACL token: token=agent
[INFO] agent: Synced node info
## ...
단기 Consul 토큰 생성 (Generate short-lived Consul tokens)
Vault로 Consul ACL 토큰을 관리하는 한 가지 전략은 구성 가능한 TTL을 활용해 상승된 권한의 토큰을 생성하는 것입니다. 그렇게 하면 강력한 토큰을 오랫동안 유효하게 유지하지 않고 고수준 접근을 부여할 수 있습니다.
Consul에서 생성할 수 있는 가장 강력한 토큰은 global-management 정책과 연결된 토큰입니다. 이 토큰은 ACL 시스템을 구성할 때마다 필요하지만, Consul 데이터센터 리소스에 대한 무제한 접근도 가지고 있습니다. 이 토큰은 유출되면 데이터센터 보안에 매우 위험합니다.
Vault에서 global-management 정책을 사용해 Consul 토큰을 만들고 TTL 1h를 할당하는 역할을 생성합니다.
$ vault write consul/roles/global-management-role policies=global-management ttl=1h
Success! Data written to: consul/roles/global-management-role
Vault 역할을 사용해 Consul 토큰을 만듭니다.
$ vault read consul/creds/global-management-role | tee global-management.token
토큰에 lease_duration이 1h인지 확인할 수 있습니다.
Key Value
--- -----
lease_id consul/creds/global-management-role/Ql5Xz8s0Hh7FQsTNr3NhPJyw
lease_duration 1h
lease_renewable true
accessor 67f99086-12f5-d25c-7696-9cd043814102
consul_namespace n/a
local false
partition n/a
token f708a2c8-365f-e742-bff8-7317db8276e8
파일에서 accessor 값을 가져옵니다.
$ export CONSUL_TOKEN_ACCESSOR=$(cat global-management.token | grep accessor | awk '{print $2}')
accessor로 검색해 Consul에서 토큰이 올바르게 생성되었는지 확인합니다.
$ consul acl token read -accessor-id ${CONSUL_TOKEN_ACCESSOR}
AccessorID: 67f99086-12f5-d25c-7696-9cd043814102
SecretID: f708a2c8-365f-e742-bff8-7317db8276e8
Description: Vault global-management-role token 1764262053977248719
Local: false
Create Time: 2025-11-27 16:47:33.978778011 +0000 UTC
Policies:
00000000-0000-0000-0000-000000000001 - global-management
TTL이 만료되면 토큰은 Consul에서 자동으로 제거됩니다. 토큰을 다시 가져오려 시도해 제거를 확인할 수 있습니다.
$ consul acl token read -accessor-id ${CONSUL_TOKEN_ACCESSOR}
Error reading token "67f99086-12f5-d25c-7696-9cd043814102": Unexpected response code: 403 (token does not exist: ACL not found)
다음 단계 (Next steps)
이 페이지는 시크릿 관리를 위해 Vault를 사용해 Consul 토큰을 생성할 수 있도록 Vault의 Consul 시크릿 엔진을 구성하는 과정을 설명했습니다. Consul·Vault 통합 사용에 대해 더 알아보려면 다음 자료를 참조하세요:
Vault로 데이터센터를 계속 보호하려면 Vault와 Consul Template으로 Consul mTLS 인증서 생성을 참조하세요.
시크릿 저장·관리를 위해 Vault를 사용해 Consul 가십 암호화를 구성하는 방법을 배우려면 Vault와 Consul Template으로 Consul 가십 암호화 생성·관리를 참조하세요.
Vault를 Consul 서비스 메시 인증 기관으로 사용하려면 Consul 서비스 메시 인증 기관으로서의 Vault를 참조하세요.