에이전트 토큰 만들기

에이전트 토큰 만들기 (Create an agent token)

이 주제에서는 에이전트를 카탈로그에 등록하는 데 사용할 수 있는 토큰을 만드는 방법을 설명해요.

출처: 문서

본문

이 주제에서는 에이전트를 카탈로그에 등록하는 데 사용할 수 있는 토큰을 만드는 방법을 설명합니다.

소개 (Introduction)

Consul 에이전트는 카탈로그에 등록하고 카탈로그의 서비스와 노드를 검색하려면 적절한 권한 집합을 부여하는 정책에 연결된 토큰을 제시해야 합니다.

agent 토큰을 Consul 에이전트에 지정하여 카탈로그에 등록할 때 토큰을 제시할 수 있게 합니다.

노드 아이덴티티 vs. 사용자 지정 정책 (Node identities versus custom policies)

사용자 지정 정책 또는 노드 아이덴티티에 연결된 토큰을 만들 수 있습니다. 노드 아이덴티티(Node identities)는 각 에이전트에 대해 유사한 정책을 만드는 대신 에이전트 그룹에 대한 권한을 빠르게 부여할 수 있게 해주는 Consul의 구성 요소입니다.

사용자 지정 정책을 만드는 대신 노드 아이덴티티를 사용하여 에이전트에 권한을 부여하는 것을 권장합니다. 이는 노드 아이덴티티가 노드 node:write 및 service:read 권한을 자동으로 부여하기 때문입니다.

조직의 요구 사항이나 프로세스로 인해 서비스 및 노드 아이덴티티와 일치하지 않는 방식으로 서비스를 배포해야 할 수 있습니다. 이 경우 사용자 지정 정책을 만들어 토큰에 연결할 수 있습니다.

요구 사항 (Requirements)

핵심 ACL 기능은 모든 Consul 버전에서 사용할 수 있습니다.

에이전트 토큰은 다음 권한을 부여하는 정책에 연결되어야 합니다:

node:write: 에이전트가 카탈로그를 업데이트할 수 있게 합니다.
service:read: 에이전트가 카탈로그의 다른 서비스를 검색할 수 있게 합니다.

인증 (Authentication)

CLI 또는 API를 사용하여 ACL 토큰과 정책을 만들고 수정하려면 acl:write 권한이 있는 정책에 연결된 ACL 토큰을 제공해야 합니다.

명령줄에서 -token 옵션으로 토큰을 수동으로 제공할 수 있지만, 워크플로우를 단순화하기 위해 CONSUL_HTTP_TOKEN 환경 변수를 설정하는 것을 권장합니다:

$ export CONSUL_HTTP_TOKEN=<acl-token-secret-id>

Consul CLI는 CONSUL_HTTP_TOKEN 환경 변수를 자동으로 읽으므로 모든 Consul CLI 명령에 토큰을 전달할 필요가 없습니다.

Consul HTTP API 호출을 인증하려면 각 호출의 X-Consul-Token 헤더에 토큰을 제공해야 합니다:

$ curl --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" ...

대체 인증 방법을 알아보려면 다음 문서를 참조하세요:

Consul CE의 노드 아이덴티티 (Node identity in Consul CE)

토큰에 연결할 수 있는 노드 아이덴티티에 대한 정보는 Node identities를 참조하세요.

Consul 명령줄 또는 API 엔드포인트를 사용하여 토큰을 수동으로 만들 수 있습니다. 또한 auth method를 사용하여 신뢰할 수 있는 외부 시스템에서 Consul이 토큰을 동적으로 만들도록 활성화할 수도 있습니다.

CLI:

consul acl token create 명령을 실행하고 연결할 정책 또는 노드 아이덴티티를 지정하여 토큰을 만듭니다. consul acl token create 명령에 대한 자세한 내용은 Consul ACL Token Create를 참조하세요.

다음 명령은 데이터센터 dc1에서 node1이라는 노드에 대한 노드 아이덴티티에 연결된 ACL 토큰을 만듭니다.

$ consul acl token create \
  -description "Agent token for node1" \
  -node-identity "node1:dc1"

API:

/acl/token 엔드포인트에 PUT 요청을 보내고 요청 본문에 노드 아이덴티티를 지정하여 노드 아이덴티티에 연결된 토큰을 만듭니다. API 엔드포인트를 사용할 권한이 있는 정책에 연결된 ACL 토큰이 필요합니다. API 엔드포인트 사용에 대한 자세한 내용은 ACL Token HTTP API를 참조하세요.

다음 예제는 node1이라는 이름의 노드 아이덴티티에 연결된 토큰을 만듭니다:

$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "NodeIdentities": [
    {
      "NodeName": "node1",
      "Datacenter": "dc1"
    }
  ]
}'

Consul Enterprise의 노드 아이덴티티 (Node identity in Consul Enterprise)

토큰에 연결할 수 있는 노드 아이덴티티에 대한 정보는 Node identities를 참조하세요.

CLI:

Consul Enterprise에서 토큰을 만들 때 admin 파티션을 지정할 수 있습니다. 토큰은 지정된 admin 파티션에서만 유효합니다. 다음 예제는 에이전트가 데이터센터 dc1의 ptn1 파티션에 등록하는 데 사용할 수 있는 ACL 토큰을 만듭니다:

$ consul acl token create -partition "ptn1" \
  -description "Agent token for node1" \
  -node-identity "node1:dc1"

API:

$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "NodeIdentities": [
    {
      "NodeName": "node1",
      "Datacenter": "dc1"
    }
  ],
  "Partition": "ptn1"
}'

Consul CE의 사용자 지정 정책 (Custom policy in Consul CE)

토큰을 노드 아이덴티티에 연결할 수 없을 때 정책을 정의하고, Consul에 등록하고, 노드가 Consul 카탈로그에 등록할 수 있게 하는 정책을 토큰에 연결할 수 있습니다.

정책 정의 (Define a policy)

명령줄 또는 API 인수로 정책 정의를 보내거나 외부 HCL 또는 JSON 파일로 정의할 수 있습니다. 정책에서 사용할 수 있는 모든 규칙에 대한 자세한 내용은 ACL Rules를 참조하세요.

다음 예제 정책은 파일로 정의되어 있습니다. 이 정책은 Consul 에이전트가 카탈로그에 등록할 수 있도록 노드 node1에 대해 write 권한을 부여합니다. 카탈로그의 서비스를 검색할 수 있는 read 권한을 부여합니다.

HCL:

node "node1" {
  policy = "write"
}
service_prefix "" {
  policy = "read"
}

JSON:

{
  "node": {
    "node1": [{
      "policy": "write"
    }]
  },
  "service_prefix": {
    "": [{
      "policy": "read"
    }]
  }
}

Consul에 정책 등록 (Register the policy with Consul)

정책을 정의한 후 명령줄 또는 API 엔드포인트를 사용하여 Consul에 정책을 등록할 수 있습니다.

CLI:

consul acl policy create 명령을 실행하고 정책 규칙을 지정하여 정책을 만듭니다. 다음 예제는 node1-register.hcl에 정의된 정책을 등록합니다:

$ consul acl policy create \
    -name "node1-register" -rules @node1-register.hcl \
    -description "Custom policy for node1" \

consul acl policy create 명령에 대한 자세한 내용은 Consul ACL Policy Create를 참조하세요.

API:

/acl/policy 엔드포인트에 PUT 요청을 보내고 요청 본문에 정책 규칙을 지정하여 정책을 만듭니다. 다음 예제는 node1-register.hcl에 정의된 정책을 등록합니다. 요청 본문의 Rules 필드에 정책 규칙을 포함해야 합니다.

$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "node1-register",
  "Description": "Allow node1 to register into the catalog",
  "Rules": "node \"node1\" {\n  policy = \"write\"\n}\nservice_prefix \"\" {\n  policy = \"read\"\n}\n"
}'

API 엔드포인트 사용에 대한 자세한 내용은 ACL Policy HTTP API를 참조하세요.

정책을 토큰에 연결 (Link the policy to a token)

정책을 Consul에 등록한 후 Consul 명령줄 또는 API 엔드포인트를 사용하여 토큰을 만들고 연결할 수 있습니다. 또한 auth method를 사용하여 신뢰할 수 있는 외부 시스템에서 Consul이 토큰을 동적으로 만들도록 활성화할 수도 있습니다.

CLI:

consul acl token create 명령을 실행하고 정책 이름 또는 ID를 지정하여 정책에 연결된 토큰을 만듭니다. consul acl token create 명령에 대한 자세한 내용은 Consul ACL Token Create를 참조하세요.

다음 명령은 정책 node1-register에 연결된 ACL 토큰을 만듭니다.

$ consul acl token create \
    -description "Agent token for node1" \
    -policy-name "node1-register"

API:

/acl/token 엔드포인트에 PUT 요청을 보내고 요청에 정책 이름 또는 ID를 지정하여 정책에 연결된 ACL 토큰을 만듭니다. API 엔드포인트 사용에 대한 자세한 내용은 ACL Token HTTP API를 참조하세요.

다음 예제는 에이전트가 카탈로그에서 node1 노드로 등록하는 데 사용할 수 있는 ACL 토큰을 만듭니다:

$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Policies": [
    {
      "Name": "node1-register"
    }
  ]
}'

Consul Enterprise의 사용자 지정 정책 (Custom policy in Consul Enterprise)

정책 정의 (Define a policy)

다음 예제 정책은 파일로 정의되어 있습니다. 이 정책은 Consul 에이전트가 카탈로그에 등록할 수 있도록 파티션 ptn1의 노드 node1에 대해 write 권한을 부여합니다. ptn1 파티션의 모든 namespace에서 서비스를 검색할 수 있는 read 권한을 부여합니다.

HCL:

partition "ptn1" {
  node "node1" {
    policy = "write"
  }
  namespace_prefix "" {
    service_prefix "" {
      policy = "read"
    }
  }
}

JSON:

{
  "partition": {
    "ptn1": [{
      "namespace_prefix": {
        "": [{
          "service_prefix": {
            "": [{
              "policy": "read"
            }]
          }
        }]
      },
      "node": {
        "node1": [{
          "policy": "write"
        }]
      }
    }]
  }
}

Consul에 정책 등록 (Register the policy with Consul)

정책을 정의한 후 명령줄 또는 API 엔드포인트를 사용하여 Consul에 정책을 등록할 수 있습니다.

CLI:

consul acl policy create 명령을 실행하고 정책 규칙을 지정하여 정책을 만듭니다. 다음 예제는 node1-register.hcl에 정의된 정책을 등록합니다:

$ consul acl policy create -partition "ptn1" \
  -name "node1-register" -rules @node1-register.hcl \
  -description "Custom policy for node1"

consul acl policy create 명령에 대한 자세한 내용은 Consul ACL Policy Create를 참조하세요.

API:

$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "node1-register",
  "Description": "Allow node1 to register into the catalog",
  "Partition": "ptn1",
  "Rules": "partition \"ptn1\" {\n  node \"node1\" {\n    policy = \"write\"\n  }\n  namespace_prefix \"\" {\n    service_prefix \"\" {\n      policy = \"read\"\n    }\n  }\n}\n"
}'

API 엔드포인트 사용에 대한 자세한 내용은 ACL Policy HTTP API를 참조하세요.

정책을 토큰에 연결 (Link the policy to a token)

CLI:

$ consul acl token create -partition "ptn1" \
    -description "Agent token for node1" \
    -policy-name "node1-register"

API:

Consul Enterprise에서 토큰을 만들 때 admin 파티션을 지정할 수 있습니다. 토큰은 지정된 admin 파티션에서만 유효합니다. 다음 예제는 에이전트가 ptn1 파티션에서 node1 노드로 등록하는 데 사용할 수 있는 ACL 토큰을 만듭니다:

$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Policies": [
    {
      "Name": "node1-register"
    }
  ],
  "Partition": "ptn1"
}'

토큰 적용 (Apply the token)

에이전트 구성 파일에 토큰을 지정하거나 consul set-agent-token 명령을 사용하여 Consul 에이전트가 토큰을 제시하도록 구성하세요.

파일에서 토큰 적용 (Apply the token in a file)

에이전트 구성 파일의 acl.token.agent 필드에 토큰을 지정하여 에이전트가 시작 시 토큰을 제시하고 카탈로그에 등록할 수 있게 합니다.

acl = {
  enabled = true
  tokens = {
    agent = "<token>"
    ...
  }
  ...
}

명령으로 토큰 적용 (Apply the token with a command)

consul set-agent-token 명령을 사용하여 agent 토큰을 설정합니다. 다음 명령은 실행 중인 Consul 에이전트 토큰을 지정된 토큰으로 구성합니다.

consul acl set-agent-token agent <acl-token-secret-id>

에이전트 토큰 만들기