consul 구성 블록

consul 구성 블록 (Consul Configuration Block)

이 페이지는 서비스 디스커버리와 키-값 통합을 위해 Nomad 에이전트 구성의 consul 블록에서 Nomad 서버·클라이언트와 Consul의 통합을 구성하는 방법에 대한 참조 정보를 제공해요. 클러스터 이름, Consul 네임스페이스, Nomad가 자체 서비스를 애드버타이즈할지 여부, 인증서, 토큰, 보안, 건강 검사, 자동 조인, 그리고 워크로드 서비스·태스크 아이덴티티를 구성해요.

출처: 문서

본문

구성되면 태스크가 Consul에 스스로 등록할 수 있고, Nomad 클러스터가 자동으로 부트스트랩할 수 있어요.

Consul의 서비스 디스커버리를 사용하는 방법은 Service Discovery on Nomad 튜토리얼을 참고해요.

consul {
  address = "127.0.0.1:8500"
  auth    = "admin:password"
  token   = "abcd1234"
}

기본 consul 블록은 모든 Nomad 에이전트 구성과 자동으로 병합돼요. 이러한 합리적인 기본값은 시스템에서 Consul이 감지되면 Consul 통합을 자동으로 활성화해요. 이는 제로 구성으로 클러스터를 원활하게 부트스트랩할 수 있게 해줘요. 다시 말해, 기본 구성의 Consul 에이전트가 Nomad 에이전트와 같은 호스트에서 실행 중이라면 Nomad는 나머지 Nomad 클러스터에 자동으로 연결할 수 있어요.

로컬 Consul 에이전트가 구성되고 Nomad 에이전트가 접근할 수 있다면, server_auto_join, client_auto_join, auto_advertise가 모두 활성화되어 있을 때(기본값) Nomad 클러스터는 자동으로 부트스트랩해요.

중요한 요구 사항은 각 Nomad 에이전트가 고유한 Consul 에이전트와 통신해야 한다는 점이에요. Nomad 에이전트는 Consul 서버가 아닌 Consul 에이전트와 통신하도록 구성해야 해요. 서비스가 플래핑(flapping)하는 것을 관찰한다면 여러 Nomad 에이전트가 같은 Consul 에이전트와 통신하고 있는 것일 수 있어요. 따라서 consul.service.consul 같은 DNS를 통해 Nomad가 Consul과 통신하도록 구성하지 마세요.

Nomad Enterprise에서는 여러 consul 블록을 지정해 여러 Consul 클러스터에 대한 접근을 구성할 수 있어요. 각 Consul 클러스터는 name 필드의 값이 달라야 해요.

consul 매개변수 (Parameters)

일부 매개변수는 클라이언트, 서버, 또는 모든 에이전트로 실행되는 Nomad 에이전트의 구성 파일에 지정하도록 예상돼요. 매개변수가 정의되지 않아야 하는 구성 파일에 배치되면 안전하게 무시돼요.

Nomad 클라이언트와 서버용 매개변수 (Parameters for Nomad Clients and Servers)

이 매개변수들은 모든 Nomad 에이전트의 구성 파일에 정의해야 해요.

  • address (string: "127.0.0.1:8500") — 로컬 Consul 에이전트의 주소를 host:port 형식으로 지정해요. unix:///tmp/consul/consul.sock 형식의 Unix 소켓을 지원해요. 설정되면 CONSUL_HTTP_ADDR 환경 변수로 기본 설정돼요. 이 값은 go-sockaddr/template 형식을 지원해요.
  • auth (string: "") — Consul 에이전트에 접근하기 위해 사용할 HTTP Basic Authentication 정보를 username:password 형식으로 지정해요.
  • auto_advertise (bool: true) — Nomad가 자체 서비스를 Consul에 애드버타이즈할지 여부를 지정해요. 서비스는 server_service_name과 client_service_name에 따라 이름이 붙어요. Nomad 서버와 클라이언트는 각각 http 또는 rpc 태그로 적절히 태그된 각 서비스를 애드버타이즈해요. Nomad 서버는 또한 serf 태그된 서비스를 애드버타이즈해요.
  • ca_file (string: "") — Consul 통신에 사용되는 CA 인증서의 선택적 경로를 지정해요. 지정하지 않으면 시스템 번들로 기본 설정돼요. 설정되면 CONSUL_CACERT 환경 변수로 기본 설정돼요.
  • cert_file (string: "") — Consul 통신에 사용되는 인증서의 경로를 지정해요. 이 값을 설정하면 key_file도 함께 설정해야 해요.
  • checks_use_advertise (bool: false) — Consul 건강 검사가 애드버타이즈 주소에 바인드해야 하는지 여부를 지정해요. 기본적으로 이것은 첫 번째 HTTP 주소예요. HTTP 주소가 지정되지 않으면 bind_addr로 폴백해요.
  • key_file (string: "") — Consul 통신에 사용되는 개인 키의 경로를 지정해요. 이 값을 설정하면 cert_file도 함께 설정해야 해요.
  • name (string: "default") — Enterprise — 작업 제출자가 작업 스펙의 consul.cluster 또는 service.cluster 필드에서 참조할 수 있도록 클러스터의 이름을 지정해요. Nomad Community Edition에서는 "default" 클러스터만 사용되므로 이 필드는 생략해야 해요.
  • namespace (string: "") — Enterprise — Consul 통합이 사용하는 Consul 네임스페이스를 지정해요. 비어 있지 않으면 작업의 consul.namespace 필드가 덮어쓰지 않는 한 이 네임스페이스가 모든 Consul API 호출과 Consul 서비스 메시 구성에 사용돼요. Nomad Community Edition에서는 "default" 네임스페이스만 사용되므로 이 필드를 생략해야 해요.
  • ssl (bool: false) — 전송 체계가 Consul 에이전트와 통신할 때 HTTPS를 사용해야 하는지 여부를 지정해요. 설정되면 CONSUL_HTTP_SSL 환경 변수로 기본 설정돼요.
  • tags (array<string>: []) — Nomad 서버와 클라이언트 서비스와 함께 등록할 선택적 Consul 태그를 지정해요.
  • timeout (string: "5s") — Consul에 대한 요청 시간 제한을 지정해요. "10s" 같은 라벨 접미사로 지정돼요.
  • token (string: "") — 요청별 ACL 토큰을 제공하는 데 사용되는 토큰을 지정해요. 이 옵션은 Consul 에이전트의 기본 토큰을 덮어써요. 토큰이 여기나 Consul 에이전트에 설정되지 않으면 쓰기를 허용할 수도 있고 허용하지 않을 수도 있는 Consul의 익명 정책으로 기본 설정돼요. 설정되면 CONSUL_HTTP_TOKEN 환경 변수로 기본 설정돼요. Nomad는 이 토큰을 갱신할 수 없어요. 토큰이 삭제되면 Nomad는 Consul과 통신할 수 없어요. Nomad는 또한 CONSUL_HTTP_TOKEN_name 환경 변수를 찾는데, 여기서 name은 consul.name 매개변수예요. 이를 통해 Nomad Enterprise 사용자가 환경 변수로 여러 클러스터에 여러 토큰을 지정할 수 있어요. Nomad Enterprise에서 Nomad와 함께 실행되는 Consul 에이전트가 Consul Enterprise admin partition에 있다면, Nomad 클라이언트에 제공되는 Consul 토큰을 같은 파티션에서 만들어야 해요.
  • verify_ssl (bool: true) — HTTPS를 통해 Consul API 클라이언트와 통신할 때 SSL 피어 검증을 사용해야 하는지 여부를 지정해요. 설정되면 CONSUL_HTTP_SSL_VERIFY 환경 변수로 기본 설정돼요.

Nomad 클라이언트용 매개변수 (Parameters for Nomad Clients)

이 매개변수들은 client.enabled가 true로 설정된 Nomad 에이전트의 구성 파일에만 정의해야 해요.

  • client_auto_join (bool: true) — Nomad 클라이언트가 server_service_name 옵션에 정의된 Consul 서비스 이름을 검색해 같은 리전의 Nomad 서버를 자동으로 발견해야 하는지 여부를 지정해요. 검색은 클라이언트가 어떤 Nomad 서버에도 등록되지 않았거나 리전의 리더에 하트비트를 보낼 수 없을 때 발생하며, 이 경우 파티셔닝되었을 수 있으므로 다른 Nomad 서버를 검색해요.
  • client_service_name (string: "nomad-client") — Nomad 클라이언트에 대한 Consul의 서비스 이름을 지정해요.
  • client_http_check_name (string: "Nomad Client HTTP Check") — Nomad 클라이언트에 대한 Consul의 HTTP 건강 검사 이름을 지정해요.
  • client_failures_before_critical (int: 0) — Nomad 클라이언트 Consul 건강 검사가 critical이 되기 전의 연속 실패 횟수를 지정해요.
  • client_failures_before_warning (int: 0) — Nomad 클라이언트 Consul 건강 검사가 경고를 표시하기 전의 연속 실패 횟수를 지정해요.
  • grpc_address (string: "127.0.0.1:8502") — gRPC 요청을 위한 로컬 Consul 에이전트의 주소를 host:port 형식으로 지정해요. Consul은 기본적으로 grpc 또는 grpc_tls 리스너를 활성화하지 않는다는 점을 참고해 주세요.
  • grpc_ca_file (string: "") — Connect 사이드카 프록시와 Consul 에이전트 간 통신에 사용되는 GRPC CA 인증서의 선택적 경로를 지정해요. 설정되면 CONSUL_GRPC_CACERT 환경 변수로 기본 설정돼요.

    경고 — Consul은 Envoy 사이드카의 수신 TLS 검증을 지원하지 않아요. Connect를 사용할 때 Consul 구성에서 tls.grpc.verify_incoming = false를 설정해야 해요. 자세한 내용은 Consul/#13088을 참고해요.

  • share_ssl (bool: true) — Nomad 클라이언트가 자체 Consul SSL 구성을 Connect Native 애플리케이션과 공유할지 여부를 지정해요. ca_file, cert_file, key_file, ssl, verify_ssl 값을 포함해요. ACL 토큰이나 auth 값은 포함하지 않아요. 이 옵션은 Consul ACL이 활성화되지 않은 환경에서는 비활성화해야 해요.
  • service_auth_method (string: "nomad-workloads") — 서비스에 대해 Nomad JWT로 로그인하는 데 사용될 Consul 인증 방법의 이름을 지정해요.
  • task_auth_method (string: "nomad-workloads") — 태스크에 대해 Nomad JWT로 로그인하는 데 사용될 Consul 인증 방법의 이름을 지정해요.

Nomad 서버용 매개변수 (Parameters for Nomad Servers)

이 매개변수들은 server.enabled가 true로 설정된 Nomad 에이전트의 구성 파일에만 정의해야 해요.

  • server_service_name (string: "nomad") — Nomad 서버에 대한 Consul의 서비스 이름을 지정해요.
  • server_http_check_name (string: "Nomad Server HTTP Check") — Nomad 서버에 대한 Consul의 HTTP 건강 검사 이름을 지정해요.
  • server_serf_check_name (string: "Nomad Server Serf Check") — Nomad 서버에 대한 Consul의 Serf 건강 검사 이름을 지정해요.
  • server_rpc_check_name (string: "Nomad Server RPC Check") — Nomad 서버에 대한 Consul의 RPC 건강 검사 이름을 지정해요.
  • server_auto_join (bool: true) — Nomad 서버가 server_service_name 옵션에 정의된 Consul 서비스 이름을 검색해 다른 Nomad 서버를 자동으로 발견하고 조인해야 하는지 여부를 지정해요. 이 검색은 서버에 리더가 없을 때만 발생해요.
  • server_failures_before_critical (int: 0) — Nomad 서버 Consul 건강 검사가 critical이 되기 전의 연속 실패 횟수를 지정해요.
  • server_failures_before_warning (int: 0) — Nomad 서버 Consul 건강 검사가 경고를 표시하기 전의 연속 실패 횟수를 지정해요.
  • service_identity (Identity: nil) — 서비스를 등록하기 위해 Consul에서 Service Identity 토큰을 얻을 때 사용할 기본 워크로드 아이덴티티를 지정해요. 권장 구성은 워크로드 아이덴티티를 참고해요.
  • task_identity (Identity: nil) — template 블록을 지원하기 위해 Consul에서 Consul 토큰을 얻을 때 사용할 기본 워크로드 아이덴티티를 지정해요. 권장 구성은 워크로드 아이덴티티를 참고해요.

워크로드 아이덴티티 (Workload Identity)

service_identity와 task_identity 블록은 작업 스펙의 identity와 같은 모든 값을 허용해요(service_identity가 env와 file 필드를 무시한다는 점 제외). 이 블록들이 Nomad 서버에 설정되도록 보장함으로써, 다음 버전이 클러스터에 제출될 때 워크로드를 자동으로 워크로드 아이덴티티를 사용하도록 마이그레이션해요.

service_identity와 task_identity의 권장 구성은 다음과 같아요. Consul이 이러한 아이덴티티를 수락하도록 구성하는 방법은 Migrating to Using Workload Identity with Consul을 참고해요. 여기서 ttl 필드는 Consul 토큰이 아닌 Nomad 아이덴티티의 TTL을 가리킨다는 점을 참고해 주세요.

consul {
  service_identity {
    aud = ["consul.io"]
    ttl = "1h"
  }

  task_identity {
    aud = ["consul.io"]
    ttl = "1h"
  }
}

service_identity 매개변수 (Parameters)

  • aud (array<string>: []) — 이 워크로드 아이덴티티의 유효 수신자 목록이에요. 이 값은 Consul JWT 인증 방법의 BoundAudiences 구성과 일치해야 해요. 아이덴티티가 사용될 수 있는 위치를 최소화하기 위해 정확히 하나의 오디언스만 제공하는 것을 권장해요.
  • ttl (string: "") — 워크로드 아이덴티티가 만료되기 전에 유효한 것으로 간주되는 기간을 지정해요.

task_identity 매개변수 (Parameters)

  • aud (array<string>: []) — 이 워크로드 아이덴티티의 유효 수신자 목록이에요. 이 값은 Consul JWT 인증 방법의 BoundAudiences 구성과 일치해야 해요. 정확히 하나의 오디언스만 제공하는 것을 권장해요.
  • env (bool: false) — true이면 워크로드 아이덴티티를 태스크의 NOMAD_TOKEN_consul_default(또는 name 필드에 따라 NOMAD_TOKEN_consul_) 환경 변수에서 사용할 수 있어요.
  • file (bool: false) — true이면 워크로드 아이덴티티를 태스크 파일시스템의 secrets/nomad_consul_default.jwt(또는 name 필드에 따라 secrets/nomad_consul_<name>.jwt) 경로에서 사용할 수 있어요. task.user 매개변수가 설정되면 토큰 파일은 해당 사용자만 읽을 수 있어요. 그렇지 않으면 파일은 모든 사람이 읽을 수 있지만 부모 디렉터리 권한으로 보호돼요.
  • ttl (string: "") — 워크로드 아이덴티티가 만료되기 전에 유효한 것으로 간주되는 기간을 지정해요.

consul 예시 (Examples)

기본 (Default)

이 예시는 기본 Consul 통합을 보여줘요.

consul {
  address             = "127.0.0.1:8500"
  server_service_name = "nomad"
  client_service_name = "nomad-client"
  auto_advertise      = true
  server_auto_join    = true
  client_auto_join    = true
}

커스텀 주소와 포트 (Custom Address and Port)

이 예시는 Nomad 에이전트를 다른 Consul 주소로 지정하는 방법을 보여줘요. Consul 서버를 직접 가리키지 말고 항상 로컬 클라이언트를 가리켜야 한다는 점을 참고해 주세요. 이 예시에서 Consul 서버는 localhost 대신 노드의 개인 IP 주소에 바인드되어 수신 중이므로 그 주소를 사용해요.

consul {
  address = "10.0.2.4:8500"
}

커스텀 SSL (Custom SSL)

이 예시는 Consul 에이전트와 통신하기 위한 커스텀 SSL 인증서를 구성하는 방법을 보여줘요. Consul 에이전트는 인증서를 유사하게 수락하도록 구성해야 하지만, 여기서는 다루지 않아요.

consul {
  ssl       = true
  ca_file   = "/var/ssl/bundle/ca.bundle"
  cert_file = "/etc/ssl/consul.crt"
  key_file  = "/etc/ssl/consul.key"
}

Nomad용 Consul ACL 정책 (Consul ACL policy for Nomad)

Nomad 에이전트는 서비스 카탈로그에 자신을 등록하고 서비스 디스커버리를 통해 다른 Nomad 에이전트를 발견해 자동 클러스터링을 수행하려면 Consul에 접근해야 해요. Nomad 클라이언트는 워크로드 아이덴티티의 Consul 토큰을 사용해 서비스와 검사를 등록하지만, 등록 해제하려면 자체 토큰에 대한 권한이 필요해요. Nomad 서버는 또한 Consul Service Mesh에 대한 구성 항목을 만들므로, 특정 권한은 Nomad 서버와 클라이언트 간에 약간 다를 수 있어요. 다음 Consul ACL 정책은 Nomad 서버와 클라이언트가 필요로 하는 최소 권한을 나타내요.

agent_prefix "" {
  policy = "read"
}

node_prefix "" {
  policy = "write"
}

service_prefix "" {
  policy = "write"
}

acl  = "write"
mesh = "write"

agent_prefix "" {
  policy = "read"
}

node_prefix "" {
  policy = "write"
}

service_prefix "" {
  policy = "write"
}

Consul 네임스페이스 — Enterprise

Consul은 네임스페이스와 연관된 ACL 정책이 agent 권한을 사용하는 것을 허용하지 않아요. Nomad는 agent:read 권한이 필요해요. consul_namespace 기능을 사용하려면 Nomad가 Consul의 default 네임스페이스에서 생성된 토큰이 필요해요. 그 토큰은 agent:read와 함께, 의도한 네임스페이스에서 Nomad를 실행하기 위한 다른 관련 권한이 있는 네임스페이스 블록으로 생성되어야 해요.

이 Consul 정책은 Nomad 서버에 대한 예시 정책 구성을 보여줘요.

agent_prefix "" {
  policy = "read"
}

namespace "nomad-ns" {
  acl = "write"

  key_prefix "" {
    policy = "read"
  }

  node_prefix "" {
    policy = "read"
  }

  service_prefix "" {
    policy = "write"
  }
}

Consul Admin Partition — Enterprise

Nomad Enterprise에서 Nomad와 함께 실행되는 Consul 에이전트가 Consul Enterprise admin partition에 있다면, Nomad 클라이언트를 위한 Consul ACL 토큰과 ACL 정책을 같은 파티션에서 만들어야 해요.

더 알아보기 (Learn more)