터미네이팅 게이트웨이 토큰 생성

터미네이팅 게이트웨이 토큰 생성 (Create a Terminating Gateway Token)

이 주제는 터미네이팅 게이트웨이가 Consul에 등록할 수 있게 하는 ACL 토큰을 생성하는 방법을 설명해요.

출처: 문서

본문

이 주제는 터미네이팅 게이트웨이가 Consul에 등록할 수 있게 하는 ACL 토큰을 생성하는 방법을 설명해요.

소개 (Introduction)

터미네이팅 게이트웨이는 조직 내 네트워크에서 Consul 서비스 메시의 서비스가 메시 밖의 서비스 및 대상에 연결할 수 있게 해요.

터미네이팅 게이트웨이를 구성하는 방법은 터미네이팅 게이트웨이 문서와 터미네이팅 게이트웨이 이해하기 튜토리얼을 참고해요.

요구 사항 (Requirements)

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

터미네이팅 게이트웨이 토큰은 발견 가능하고 메시 밖으로 트래픽을 전달하기 위해 적절한 권한 집합을 부여하는 정책과 연결되어야 해요. 다음 권한이 필요해요:

  • 터미네이팅 게이트웨이가 카탈로그에 등록할 수 있도록 하는 service:write
  • 트래픽을 전달하는 각 서비스에 대한 service:write
  • 트래픽을 전달하는 각 서비스의 노드에 대한 node:read
  • 모든 서비스에 대한 service:read 및 모든 노드에 대한 node:read — 서비스를 발견하고 라우팅하기 위함
  • agent:read — consul connect envoy CLI 명령이 Consul 에이전트에서 gRPC 설정을 자동으로 발견할 수 있게 함. 이 명령으로 게이트웨이를 시작하지 않거나 Consul 에이전트가 기본 gRPC 설정을 사용한다면 agent: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

터미네이팅 게이트웨이용 토큰을 생성하려면 정책을 정의하고, 정책을 Consul에 등록하고, 정책을 토큰에 연결해야 해요.

정책 정의 (Define a policy)

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

다음 예시 정책은 파일에 정의돼요. 이 정책은 terminating-gateway라는 서비스로 등록하고 터미네이팅 게이트웨이로 운영하기 위한 적절한 권한을 부여해요. 이 예시에서 터미네이팅 게이트웨이는 external-service-1과 external-service-2라는 두 서비스에 대한 트래픽을 전달해요. 정책 예시에는 이러한 서비스에 대한 service:write 권한이 포함돼요. 추가 서비스가 있다면 정책 규칙에 포함되도록 추가 서비스에 대한 service:write 권한을 정책에 포함해야 해요.

HCL:

service "terminating-gateway" {
   policy = "write"
}
service "external-service-1" {
  policy = "write"
}
service "external-service-2" {
  policy = "write"
}
node_prefix "" {
  policy = "read"
}
agent_prefix "" {
  policy = "read"
}

JSON:

{
  "service": {
    "terminating-gateway": [{
      "policy": "write"
    }],
    "external-service-1": [{
      "policy": "write"
    }],
    "external-service-2": [{
      "policy": "write"
    }]
  },
  "node_prefix": {
    "": [{
      "policy": "read"
    }]
  },
  "agent_prefix": {
    "": [{
      "policy": "read"
    }]
  }
}

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

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

다음 명령은 ACL 정책과 토큰을 생성해요.

CLI: consul acl policy create 명령을 실행하고 정책 규칙을 지정해 정책을 생성해요. 다음 예시는 tgw-register.hcl에 정의된 정책을 등록해요:

$ consul acl policy create \
    -name "tgw-register" -rules @tgw-register.hcl \
    -description "Terminating gateway policy"

consul acl policy create 명령에 대한 세부 사항은 Consul ACL 정책 생성을 참고해요.

API: /acl/policy 엔드포인트에 PUT 요청을 보내고 요청 본문에 정책 규칙을 지정해 정책을 생성해요. 다음 예시는 tgw-register.hcl에 정의된 정책을 등록해요. 정책 규칙을 요청 본문의 Rules 필드에 포함해야 해요.

$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "tgw-register",
  "Description": "Terminating gateway policy",
  "Rules": "service \"terminating-gateway\" {\n   policy = \"write\"\n}\nservice \"external-service-1\" {\n  policy = \"write\"\n}\nservice \"external-service-2\" {\n  policy = \"write\"\n}\nnode_prefix \"\" {\n  policy = \"read\"\n}\nagent_prefix \"\" {\n  policy = \"read\"\n}\n"
}'

API 엔드포인트 사용에 대한 추가 정보는 ACL 정책 HTTP API를 참고해요.

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

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

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

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

$ consul acl token create \
    -description "Terminating gateway token" \
    -policy-name "tgw-register"

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

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

Consul Enterprise

터미네이팅 게이트웨이용 토큰을 생성하려면 정책을 정의하고, 정책을 Consul에 등록하고, 정책을 토큰에 연결해야 해요.

정책 정의 (Define a policy)

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

Consul Enterprise에서 정책을 생성할 때 관리 파티션과 네임스페이스를 지정할 수 있어요. 정책은 지정된 범위에서만 유효해요.

다음 예시 정책은 파일에 정의돼요. 이 정책은 터미네이팅 게이트웨이가 파티션 ptn1의 네임스페이스 ns1에서 terminating-gateway라는 서비스로 등록할 수 있게 하는 적절한 권한을 부여해요.

이 예시에서 터미네이팅 게이트웨이는 다음 두 서비스에 대한 트래픽을 전달해요:

정책 예시에는 이러한 서비스에 대한 service:write 권한이 포함돼요. 추가 서비스가 있다면 정책 규칙에 포함되도록 추가 서비스에 대한 service:write 권한을 정책에 포함해야 해요.

정책은 여러 네임스페이스의 리소스에 대한 권한을 포함해요. 여러 네임스페이스에 권한을 부여하는 ACL 정책은 default 네임스페이스에서 생성해야 해요.

HCL:

partition "ptn1" {
  namespace "ns1" {
    service "terminating-gateway" {
       policy = "write"
    }
    node_prefix "" {
      policy = "read"
    }
    service "external-service-2" {
      policy = "write"
    }
  }
  namespace "default" {
    service "external-service-1" {
      policy = "write"
    }
    node_prefix "" {
      policy = "read"
    }
    agent_prefix "" {
      policy = "read"
    }
  }
}

JSON:

{
  "partition": {
    "ptn1": [{
      "namespace": {
        "default": [{
          "agent_prefix": {
            "": [{
              "policy": "read"
            }]
          },
          "node_prefix": {
            "": [{
              "policy": "read"
            }]
          },
          "service": {
            "external-service-1": [{
              "policy": "write"
            }]
          }
        }],
        "ns1": [{
          "node_prefix": {
            "": [{
              "policy": "read"
            }]
          },
          "service": {
            "external-service-2": [{
              "policy": "write"
            }],
            "terminating-gateway": [{
              "policy": "write"
            }]
          }
        }]
      }
    }]
  }
}

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

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

Consul Enterprise에서 정책을 생성할 때 관리 파티션과 네임스페이스를 지정할 수 있어요. 정책은 지정된 관리 파티션과 네임스페이스에서만 유효해요. 터미네이팅 게이트웨이가 등록된 동일한 파티션에 정책을 생성해야 해요. 터미네이팅 게이트웨이가 여러 네임스페이스에 대한 권한이 필요하다면 정책을 default 네임스페이스에서 생성해야 해요. 다음 예시는 예시 정책이 여러 네임스페이스에 대한 권한을 포함하므로 파티션 ptn1과 default 네임스페이스에 정책을 생성해요.

CLI: consul acl policy create 명령을 실행하고 정책 규칙을 지정해 정책을 생성해요. 다음 예시는 tgw-register.hcl에 정의된 정책을 등록해요:

$ consul acl policy create -partition "ptn1" -namespace "default" \
    -name "tgw-register" -rules @tgw-register.hcl \
    -description "Terminating gateway policy"

consul acl policy create 명령에 대한 세부 사항은 Consul ACL 정책 생성을 참고해요.

API: /acl/policy 엔드포인트에 PUT 요청을 보내고 요청 본문에 정책 규칙을 지정해 정책을 생성해요. 다음 예시는 tgw-register.hcl에 정의된 정책을 등록해요. 정책 규칙을 요청 본문의 Rules 필드에 포함해야 해요.

$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "tgw-register",
  "Description": "Terminating gateway policy",
  "Partition": "ptn1",
  "Namespace": "default",
  "Rules": "partition \"ptn1\" {\n  namespace \"ns1\" {\n    service \"terminating-gateway\" {\n       policy = \"write\"\n    }\n    node_prefix \"\" {\n      policy = \"read\"\n    }\n    service \"external-service-2\" {\n      policy = \"write\"\n    }\n  }\n  namespace \"default\" {\n    service \"external-service-1\" {\n      policy = \"write\"\n    }\n    node_prefix \"\" {\n      policy = \"read\"\n    }\n    agent_prefix \"\" {\n      policy = \"read\"\n    }\n  }\n}\n"
}'

API 엔드포인트 사용에 대한 추가 정보는 ACL 정책 HTTP API를 참고해요.

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

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

Consul Enterprise에서 토큰을 생성할 때 관리 파티션을 지정할 수 있어요. 토큰은 지정된 관리 파티션에서만 유효해요. 터미네이팅 게이트웨이가 등록된 파티션에 토큰을 생성해야 해요. 터미네이팅 게이트웨이가 여러 네임스페이스에 대한 권한이 필요하다면 토큰을 default 네임스페이스에서 생성해야 해요. 다음 예시는 예시 정책이 여러 네임스페이스에 대한 권한을 포함하므로 ptn1 파티션의 default 네임스페이스에 토큰을 생성해요.

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

$ consul acl token create -partition "ptn1" -namespace "default" \
    -description "Terminating gateway token" \
    -policy-name "tgw-register"

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

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

더 알아보기 (Learn more)