DNS 토큰 생성

DNS 토큰 생성 (Create a DNS Token)

이 주제는 ACL이 활성화되었을 때 Consul DNS가 네트워크의 서비스를 쿼리할 수 있게 하는 토큰을 생성하는 방법을 설명해요.

출처: 문서

본문

이 주제는 ACL이 활성화되었을 때 Consul DNS가 네트워크의 서비스를 쿼리할 수 있게 하는 토큰을 생성하는 방법을 설명해요.

소개 (Introduction)

Consul 바이너리에는 네트워크에서 서비스 디스커버리에 사용할 수 있는 DNS 서버가 포함되어 있어요. DNS 조회를 수행하는 에이전트는 Consul에 등록된 서비스, 노드, 준비된 쿼리를 발견하기 위해 적절한 ACL 권한이 필요해요.

Consul 에이전트는 적절한 권한 집합을 부여하는 정책과 연결된 토큰으로 구성되어야 해요.

Consul 에이전트가 DNS 쿼리에 응답하도록 인가하려면 default 토큰을 지정해요. Consul DNS 구성 및 사용에 대한 세부 사항은 DNS 사용 개요를 참고해요.

요구 사항 (Requirements)

핵심 ACL 기능은 모든 Consul 버전에서 사용할 수 있어요.

DNS 토큰은 다음 권한을 부여하는 정책과 연결되어야 해요:

  • service:read: 에이전트가 DNS용 서비스 조회를 수행할 수 있게 해요.
  • node:read: DNS를 통한 노드 조회를 가능하게 해요.
  • query:read: 에이전트가 DNS용 준비된 쿼리 조회를 수행할 수 있게 해요.

인증 (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의 DNS 토큰 (DNS token in Consul CE)

DNS용 토큰을 생성하려면 정책을 정의하고, 정책을 Consul에 등록하고, 정책을 토큰에 연결해야 해요.

정책 정의 (Define a policy)

정책 정의를 명령줄 또는 API 인자로 보내거나 외부 HCL 또는 JSON 파일에 정의할 수 있어요. 정책에서 사용할 수 있는 모든 규칙에 대한 세부 사항은 ACL 규칙을 참고해요.

다음 예시 정책은 파일에 정의돼요. 이 정책은 Consul 에이전트가 DNS 쿼리에 응답할 수 있게 하는 적절한 권한을 부여해요.

HCL:

node_prefix "" {
  policy = "read"
}
service_prefix "" {
  policy = "read"
}
query_prefix "" {
  policy = "read"
}

JSON:

{
  "node_prefix": {
    "": [{
      "policy": "read"
    }]
  },
  "query_prefix": {
    "": [{
      "policy": "read"
    }]
  },
  "service_prefix": {
    "": [{
      "policy": "read"
    }]
  }
}

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

정책을 정의한 후 명령줄 또는 API 엔드포인트를 사용해 정책을 Consul에 등록할 수 있어요.

CLI: consul acl policy create 명령을 실행하고 정책 규칙을 지정해 정책을 생성해요. consul acl policy create 명령에 대한 세부 사항은 Consul ACL 정책 생성을 참고해요.

다음 예시는 dns-access.hcl에 정의된 정책을 등록해요.

$ consul acl policy create \
    -name "dns-access" -rules @dns-access.hcl \
    -description "DNS Policy"

API: /acl/policy 엔드포인트에 PUT 요청을 보내고 요청 본문에 정책 규칙을 지정해 정책을 생성해요. API 엔드포인트 사용에 대한 추가 정보는 ACL 정책 HTTP API를 참고해요.

다음 예시는 dns-access.hcl에 정의된 정책을 등록해요. 정책 규칙을 요청 본문의 Rules 필드에 포함해야 해요.

$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "dns-access",
  "Description": "DNS Policy",
  "Rules": "node_prefix \"\" {\n  policy = \"read\"\n}\nservice_prefix \"\" {\n  policy = \"read\"\n}\nquery_prefix \"\" {\n  policy = \"read\"\n}\n"
}'

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

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

CLI: consul acl token create 명령을 실행하고 정책 이름 또는 ID를 지정해 정책에 연결된 토큰을 생성해요. consul acl token create 명령에 대한 세부 사항은 Consul ACL 토큰 생성을 참고해요.

다음 명령은 정책 dns-access에 연결된 ACL 토큰을 생성해요.

$ consul acl token create \
    -description "DNS token" \
    -policy-name "dns-access"

API: /acl/token 엔드포인트에 PUT 요청을 보내고 요청에 정책 이름 또는 ID를 지정해 정책에 연결된 ACL 토큰을 생성해요. API 엔드포인트 사용에 대한 추가 정보는 ACL 토큰 HTTP API를 참고해요.

다음 예시는 정책 dns-access에 연결된 ACL 토큰을 생성해요.

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

Consul Enterprise의 DNS 토큰 (DNS token in Consul Enterprise)

DNS용 토큰을 생성하려면 정책을 정의하고, 정책을 Consul에 등록하고, 정책을 토큰에 연결해야 해요.

정책 정의 (Define a policy)

정책 정의를 명령줄 또는 API 인자로 보내거나 외부 HCL 또는 JSON 파일에 정의할 수 있어요. 정책에서 사용할 수 있는 모든 규칙에 대한 세부 사항은 ACL 규칙을 참고해요.

다음 예시 정책은 파일에 정의돼요. 이 정책은 모든 파티션의 모든 네임스페이스에 있는 리소스에 대한 DNS 쿼리에 응답할 수 있게 하는 적절한 권한을 부여해요.

HCL:

partition "default" {
    namespace "default" {
        query_prefix "" {
            policy = "read"
        }
    }
}
partition_prefix "" {
  namespace_prefix "" {
    node_prefix "" {
      policy = "read"
    }
    service_prefix "" {
      policy = "read"
    }
  }
}

JSON:

{
  "partition": {
    "default": [{
      "namespace": {
        "default": [{
          "query_prefix": {
            "": [{
              "policy": "read"
            }]
          }
        }]
      }
    }]
  },
  "partition_prefix": {
    "": [{
      "namespace_prefix": {
        "": [{
          "node_prefix": {
            "": [{
              "policy": "read"
            }]
          },
          "service_prefix": {
            "": [{
              "policy": "read"
            }]
          }
        }]
      }
    }]
  }
}

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

정책을 정의한 후 명령줄 또는 API 엔드포인트를 사용해 정책을 Consul에 등록할 수 있어요.

Consul Enterprise에서 정책을 생성할 때 관리 파티션을 지정할 수 있어요. 정책은 지정된 관리 파티션에서만 유효해요. 예시 정책은 여러 파티션의 여러 네임스페이스에 대한 권한을 포함해요. 여러 파티션의 여러 네임스페이스에 권한을 부여하는 ACL 정책은 default 네임스페이스와 default 파티션에서 생성해야 해요.

CLI: consul acl policy create 명령을 실행하고 정책 규칙을 지정해 정책을 생성해요. consul acl policy create 명령에 대한 세부 사항은 Consul ACL 정책 생성을 참고해요.

consul acl policy create -partition "default" -namespace "default" \
  -name dns-access -rules @dns-access.hcl \
  -description "DNS Policy"

API: /acl/policy 엔드포인트에 PUT 요청을 보내고 요청 본문에 정책 규칙을 지정해 정책을 생성해요. API 엔드포인트 사용에 대한 추가 정보는 ACL 정책 HTTP API를 참고해요.

다음 예시는 dns-access.hcl에 정의된 정책을 등록해요. 정책 규칙을 요청 본문의 Rules 필드에 포함해야 해요.

$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "dns-access",
  "Description": "DNS Policy",
  "Partition": "default",
  "Namespace": "default",
  "Rules": "partition_prefix \"\" {\n  namespace_prefix \"\" {\n    node_prefix \"\" {\n      policy = \"read\"\n    }\n    service_prefix \"\" {\n      policy = \"read\"\n    }\n    query_prefix \"\" {\n      policy = \"read\"\n    }\n  }\n}\n"
}'

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

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

CLI: consul acl token create 명령을 실행하고 정책 이름 또는 ID를 지정해 정책에 연결된 토큰을 생성해요. consul acl token create 명령에 대한 세부 사항은 Consul ACL 토큰 생성을 참고해요.

다음 명령은 정책 dns-access에 연결된 ACL 토큰을 생성해요.

$ consul acl token create -partition "default" -namespace "default" \
    -description "DNS token" \
    -policy-name "dns-access"

API: /acl/token 엔드포인트에 PUT 요청을 보내고 요청에 정책 이름 또는 ID를 지정해 정책에 연결된 ACL 토큰을 생성해요. API 엔드포인트 사용에 대한 추가 정보는 ACL 토큰 HTTP API를 참고해요.

다음 예시는 정책 dns-access에 연결된 ACL 토큰을 생성해요.

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

토큰 적용 (Apply the token)

에이전트 구성 파일에 토큰을 지정하거나 consul set-agent-token 명령을 사용해 Consul 에이전트를 토큰으로 구성해요.

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

에이전트가 시작 시 이를 제시하고 카탈로그에 등록할 수 있도록 에이전트 구성 파일의 default 필드에 토큰을 지정해요.

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

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

acl.token.default 명령을 사용해 default 토큰을 설정해요. 다음 명령은 실행 중인 Consul 에이전트 토큰을 지정된 토큰으로 구성해요.

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

더 알아보기 (Learn more)