구성

구성 (Configuration)

이 페이지는 Nomad 에이전트 구성에 대한 참조 정보의 개요를 제공해요. Nomad가 여러 구성 파일을 로드하고 병합하는 방법을 알아봐요. 네트워킹과 애드버타이즈 주소, Nomad 리전과 데이터 센터, 데이터 디렉터리, Consul 통합, 핸드셰이크 제한, 클라이언트당 연결, 로깅, 플러그인, Sentinel 정책, 보안, 업데이트 확인 동작, 그리고 Vault 통합을 구성해요. 디버깅 활성화, syslog 기록, 인터럽트·종료 시 떠나기(leave), cross-origin resource sharing (CORS)을 활성화해요.

출처: 문서

본문

구성 파일을 HCL로 작성하거나 매개변수를 커맨드라인 플래그로 지정해요. Nomad는 여러 구성 파일이나 디렉터리에서 매개변수를 읽고 결합해 Nomad 에이전트를 구성할 수 있어요.

구성 파일 로드 순서와 병합 (Configuration file load order and merging)

Nomad 에이전트는 -config CLI 플래그로 제공할 수 있는 여러 구성 파일을 지원해요. 이 플래그는 파일이나 폴더를 받을 수 있어요. 폴더의 경우 해당 폴더의 모든 .hcl과 .json 파일이 사전순(lexicographical order)으로 로드되고 병합돼요. 디렉터리는 재귀적으로 로드되지 않아요.

예를 들어:

$ nomad agent -config=server.conf -config=/etc/nomad -config=extra.json

이렇게 하면 server.conf에서, /etc/nomad 아래의 .hcl과 .json 파일들에서, 마지막으로 extra.json에서 구성을 로드해요.

각 파일이 처리됨에 따라 그 내용이 기존 구성에 병합돼요. 병합 시 최신 구성 파일의 비어 있지 않은 값은 현재 구성의 매개변수에 추가되거나 대체해요. 빈 값은 문자열의 경우 "", 정수나 부동소수 값의 경우 0, 부울의 경우 false를 의미해요. 빈 값은 무시되므로 서버 모드 같은 매개변수를 활성화한 후에는 비활성화할 수 없어요.

주어진 플러그인에 대한 plugin 블록은 병합되는 것이 아니라 항상 서로를 대체하고 덮어쓴다는 점을 참고해 주세요.

다음은 클라이언트와 서버 모드로 모두 실행되는 Nomad 에이전트 구성 예시예요.

data_dir  = "/var/lib/nomad"

bind_addr = "0.0.0.0" # the default

advertise {
  # Defaults to the first private IP address.
  http = "1.2.3.4"
  rpc  = "1.2.3.4"
  serf = "1.2.3.4:5648" # non-default ports may be specified
}

server {
  enabled          = true
  bootstrap_expect = 3
}

client {
  enabled       = true
}

plugin "raw_exec" {
  config {
    enabled = true
  }
}

consul {
  address = "1.2.3.4:8500"
}

개발과 테스트를 간소화하기 위해 지원되기는 하지만, 노드를 클라이언트와 서버로 동시에 운영하는 것은 강력히 권장되지 않는다는 점을 참고해 주세요.

플러그인 디렉터리 구성 (Configure plugin directories)

플러그인 실행 바이너리를 배치하는 디렉터리를 구성할 수 있어요. 다음 표는 각 플러그인 유형에 대한 에이전트 구성 필드와 기본 디렉터리를 나열해요. 기본 디렉터리는 로컬 디렉터리를 지정하는 구성된 data_dir 매개변수의 값을 사용한다는 점을 참고해 주세요.

일반 매개변수 (General parameters)

• acl (ACL: nil) — ACL에 특정한 구성을 지정해요.
• addresses (Addresses: 설명 참고) — 개별 네트워크 서비스의 바인드 주소를 지정해요. 이 블록에서 구성된 값은 기본 bind_addr보다 우선해요. 이 값들은 포트 없이 IP 형식(예: "0.0.0.0")으로 지정해야 해요. 포트를 설정하려면 ports 필드를 참고해요. 이 값들은 go-sockaddr/template 형식을 지원해요.
  • http — HTTP 서버가 바인드되는 주소예요. 가장 흔하게 변경하는 바인드 주소예요. http 필드는 여러 주소를 바인드하기 위해 공백으로 구분된 여러 값을 허용해요.
  • rpc — 내부 RPC 인터페이스를 바인드할 주소예요. 가능하면 다른 클러스터 멤버에게만 노출해야 해요.
  • serf — 가십 레이어를 바인드하는 데 사용되는 주소예요. 이 주소에 TCP와 UDP 리스너가 모두 노출돼요. 가능하면 다른 클러스터 멤버에게만 노출해야 해요.
• advertise (Advertise: 설명 참고) — 개별 네트워크 서비스의 애드버타이즈 주소를 지정해요. 이는 NAT 같은 더 복잡한 네트워크 구성을 지원하기 위해 서버나 클라이언트 노드의 피어에게 다른 주소를 애드버타이즈하는 데 사용할 수 있어요. 이 구성은 선택적이며, 제공하지 않으면 특정 네트워크 서비스의 바인드 주소로 기본 설정돼요. 이 블록에서 구성된 값은 기본 bind_addr보다 우선해요. 바인드 주소가 0.0.0.0이면 기본 개인 네트워크 인터페이스의 IP 주소가 애드버타이즈돼요. advertise 값은 대체 포트를 포함할 수 있지만, 그 외에는 바인드 주소가 사용하는 포트로 기본 설정돼요. 이 값들은 go-sockaddr/template 형식을 지원해요.
  • http — HTTP 인터페이스에 대해 애드버타이즈할 주소예요. 최종 사용자가 Nomad CLI 도구를 사용할 모든 노드에서 도달 가능해야 해요.
  • rpc — Nomad 클라이언트가 RPC를 위해 Nomad 서버에 연결하도록 애드버타이즈하는 데 사용되는 주소예요. 이는 NAT 게이트웨이 뒤에서도 Nomad 클라이언트가 Nomad 서버에 연결할 수 있게 해줘요. 이 주소는 모든 Nomad 클라이언트 노드에서 도달 가능해야 해요. 설정되면 Nomad 서버는 서로 간의 RPC 연결에 advertise.serf 주소를 사용해요. Nomad 클라이언트에서 이 값을 설정해도 효과가 없어요.
  • serf — 가십 레이어에 대해 애드버타이즈되는 주소예요. 이 주소는 모든 서버 노드에서 도달 가능해야 해요. 클라이언트가 이 주소에 도달할 수 있어야 하는 것은 아니에요. Nomad 서버는 애드버타이즈된 Serf IP와 애드버타이즈된 RPC 포트를 사용해 서로 RPC로 통신해요.
• audit (Audit: nil) — 엔터프라이즈 전용. 감사 로깅 구성을 지정해요.
• bind_addr (string: "0.0.0.0") — HTTP 인터페이스뿐 아니라 내부 가십 프로토콜과 RPC 메커니즘을 포함한 네트워크 서비스를 위해 Nomad 에이전트가 바인드할 주소를 지정해요. IP 형식으로 지정해야 하며, 모든 네트워크 서비스를 같은 주소에 쉽게 바인드하는 데 사용할 수 있어요. 개별 서비스를 서로 다른 주소에 바인드하려면 addresses 구성 옵션을 사용할 수도 있어요. Dev 모드( -dev )는 로컬호스트로 기본 설정돼요. 이 값은 go-sockaddr/template 형식을 지원해요.
• client (Client: nil) — Nomad 클라이언트에 특정한 구성을 지정해요.
• consul (Consul: nil) — Consul에 연결하기 위한 구성을 지정해요.
• datacenter (string: "dc1") — 로컬 에이전트의 데이터 센터를 지정해요. 데이터 센터는 리전 내 클라이언트의 추상적 그룹화예요. 클라이언트는 조인된 서버와 같은 데이터 센터에 있을 필요는 없지만, 같은 리전에는 있어야 해요.
• data_dir (string: required) — 에이전트 상태를 저장하는 데 사용되는 로컬 디렉터리를 지정해요. 클라이언트 노드는 이 디렉터리를 기본적으로 임시 할당 데이터와 클러스터 정보를 저장하는 데 사용해요. 서버 노드는 복제된 로그와 스냅샷 데이터를 포함한 클러스터 상태를 저장하는 데 이 디렉터리를 사용해요. 절대 경로로 지정해야 해요. 에이전트 프로세스가 시작될 때 디렉터리가 존재하지 않으면 Nomad는 호스트에 디렉터리를 만들어요.
• disable_anonymous_signature (bool: false) — Nomad가 업데이트 확인과의 중복 제거를 위해 익명 서명을 제공할지 여부를 지정해요.
• disable_update_check (bool: false) — Nomad가 업데이트와 보안 게시판을 확인하지 않도록 할지 여부를 지정해요. 이것은 Nomad Enterprise에서 기본적으로 true예요.
• enable_debug (bool: false) — 디버깅 HTTP 엔드포인트를 활성화할지 여부를 지정해요. 이 엔드포인트는 프로파일링 도구와 함께 사용해 Nomad 내부에 대한 진단 정보를 덤프할 수 있어요.
• enable_syslog (bool: false) — 에이전트가 syslog에 기록할지 여부를 지정해요. 이 옵션은 Unix 기반 시스템에서만 작동해요. 로그 수준은 log_level에 설정된 Nomad 에이전트 로그에서 상속돼요.
• eventlog — Windows 이벤트 로그의 동작을 구성하는 중첩 객체예요. 다음 매개변수를 사용할 수 있어요.
  • enabled — Nomad 에이전트 로그를 Windows 이벤트 로그로 보내기를 활성화해요.
  • level (string: "ERROR") — Nomad 에이전트가 출력하는 로그의 구체성을 지정해요. 유효한 로그 수준은 구체성이 높아지는 순서로 ERROR, WARN, INFO예요. 수준은 log_level 매개변수에 정의된 것과 같거나 낮은 구체성이어야 해요.
• http_api_response_headers (map<string|string>: nil) — HTTP API 응답에 추가할 사용자 정의 헤더를 지정해요.
• http_disable_http2 (bool: false) — HTTP 서버에서 HTTP/2 프로토콜 지원을 비활성화해요.
• http_disable_websocket_origin_check (bool: false) — HTTP 요청을 WebSocket으로 업그레이드할 때 origin 확인을 비활성화해요. 개발 클러스터에 요청을 프록시할 때 UI 개발에 유용해요. 프로덕션에서는 사용하면 안 돼요.
• leave_on_interrupt (bool: false) — 에이전트가 인터럽트 신호를 받을 때 떠날(leave)지 여부를 지정해요. 기본적으로 에이전트에 대한 모든 정지 신호(interrupt 또는 terminate)는 내부 상태를 필요에 따라 디스크에 커밋한 후 에이전트가 종료하게 해요. 이 값이 서버 에이전트에서 true로 설정되면 서버는 피어 집합을 떠나려는 의도를 다른 서버에 알려요. 종료된 서버가 다시는 클러스터에 조인하지 않을 경우에만 서버 에이전트에서 이 값을 true로 설정해야 해요. 이 값이 클라이언트 에이전트에서 true로 설정되고 클라이언트가 drain_on_shutdown으로 구성되면 클라이언트는 종료 전에 워크로드를 드레인해요.
• leave_on_terminate (bool: false) — 에이전트가 terminate 신호를 받을 때 떠날지 여부를 지정해요. 기본적으로 에이전트에 대한 모든 정지 신호는 내부 상태를 디스크에 커밋한 후 에이전트가 종료하게 해요. 이 값이 서버 에이전트에서 true로 설정되면 서버는 피어 집합을 떠나려는 의도를 다른 서버에 알려요. 종료된 서버가 다시는 클러스터에 조인하지 않을 경우에만 서버 에이전트에서 이 값을 true로 설정해야 해요. 이 값이 클라이언트 에이전트에서 true로 설정되고 클라이언트가 drain_on_shutdown으로 구성되면 클라이언트는 종료 전에 워크로드를 드레인해요.
• limits — 에이전트가 적용하는 제한을 구성하는 중첩 객체예요. 다음 매개변수를 사용할 수 있어요.
  • https_handshake_timeout (string: "5s") — 클라이언트와 서버 에이전트 모두의 HTTPS 서버가 클라이언트가 TLS 핸드셰이크를 완료할 때까지 기다리는 제한을 구성해요. tls.http = true를 사용할 때 비인증 공격자가 열 수 있는 연결 수를 제한하므로, 보수적으로 유지해야 해요(프로덕션에서 강력 권장). 기본값은 5s예요. 0이면 HTTP 핸드셰이크 타임아웃을 비활성화해요.
  • http_max_conns_per_client (int: 100) — 단일 클라이언트 IP 주소가 에이전트의 HTTP 서버에 열 수 있는 동시 TCP 연결 수의 제한을 구성해요. 이는 클라이언트와 서버 에이전트 모두의 HTTP 서버에 영향을 줘요. 기본값은 100이에요. 0이면 HTTP 연결 제한을 비활성화해요.
  • rpc_handshake_timeout (string: "5s") — 클라이언트 TCP 연결이 설정된 후 서버가 연결 핸드셰이크를 완료하기 전에 기다리는 제한을 구성해요. TLS를 사용할 때는 초기 프로토콜 협상과 별도로 TLS 핸드셰이크에 같은 타임아웃이 적용돼요. 모든 Nomad 클라이언트는 새 연결을 설정하자마자 이를 수행해야 해요. TLS가 클라이언트 인증에 사용될 때 비인증 공격자가 열 수 있는 연결 수를 제한하므로 보수적으로 유지해야 해요(프로덕션에서 강력 권장). 서버에서 tls.rpc가 true일 때 이는 클라이언트가 성공적으로 인증하기 전에 연결과 관련 고루틴이 열려 유지되는 시간을 제한해요. 기본값은 5s예요. 0이면 RPC 핸드셰이크 타임아웃을 비활성화해요.
  • rpc_max_conns_per_client (int: 100) — 단일 소스 IP 주소가 단일 서버에 열 수 있는 동시 TCP 연결 수의 제한을 구성해요. 클라이언트 에이전트는 RPC TCP 연결을 직접 수락하지 않으므로 영향을 받지 않아요. 이것은 클라이언트 연결과 다른 서버 연결 모두에 영향을 줘요. Nomad 클라이언트는 서버를 통해 라우팅될 때 자체 연결이 필요한 로그 스트리밍 같은 스트리밍 엔드포인트를 제외하고 단일 TCP 연결에 많은 RPC 호출을 멀티플렉싱해요. 서버는 로컬 및 페더레이션 리전의 피어 서버별로 최소 2개의 TCP 연결(1 Raft, 1 RPC)이 필요해요. 서버는 또한 동시에 사용 중인 라우팅된 스트리밍 엔드포인트당 TCP 연결이 필요해요. 스트리밍 엔드포인트는 운영자만 사용하며, 0.10.3 기준으로 Nomad 클라이언트 코드는 사용하지 않아요. 합리적으로 낮은 제한은 비인증 공격자가 많은 연결을 열어 무한한 리소스를 소비하는 능력을 크게 줄여요. WAN 페더레이션 서버가 프록시나 NAT 게이트웨이 등을 통해 연결되어 단일 소스 IP에서 많은 정당한 연결이 발생하면 이 값을 높여야 할 수 있어요. 기본값은 100이며 대부분의 사용자를 지원하도록 설계됐어요. 0이면 RPC 연결 제한을 비활성화해요. 26은 최소값인데, 스트리밍 RPC가 정상 서버 운영을 방해하지 않도록 항상 20개의 연결이 비스트리밍 연결(Raft와 RPC)용으로 예약되기 때문이에요. 이 최소값은 향후 스트리밍 RPC가 자체 TCP 연결을 요구하지 않게 되면 낮아질 수 있어요.
• log_level (string: "INFO") — Nomad 에이전트가 출력할 로그의 구체성을 지정해요. 유효한 로그 수준은 구체성이 높아지는 순서로 WARN, INFO, DEBUG, TRACE예요.
• log_include_location (bool: false) — 각 로그 줄에 파일과 줄 정보를 포함해요.
• log_json (bool: false) — 로그를 JSON 형식으로 출력해요.
• log_file (string: "") — 로깅 경로를 지정해요. 경로에 파일 이름이 없으면 파일 이름은 기본적으로 nomad.log예요. 이 설정은 log_rotate_bytes와 log_rotate_duration과 결합해 세분화된 로그 회전 제어를 할 수 있어요.
• log_rotate_bytes (int: 0) — 회전되기 전에 로그에 기록되어야 하는 바이트 수를 지정해요. 지정하지 않으면 로그 파일에 기록할 수 있는 바이트 수에 제한이 없어요.
• log_rotate_duration (duration: "24h") — 회전되기 전에 로그가 기록되어야 하는 최대 기간을 지정해요. 30s 같은 duration 값이어야 해요.
• log_rotate_max_files (int: 0) — 현재 기록 중인 로그 파일을 제외하고 보관할 이전 로그 파일 아카이브의 최대 수를 지정해요. 0으로 설정하면 어떤 파일도 삭제되지 않아요. stderr와 stdout 각각의 총 로그 파일 수는 log_rotate_max_files 값보다 1 더 크다는 점을 참고해 주세요.
• name (string: [hostname]) — 로컬 노드의 이름을 지정해요. 이 값은 개별 에이전트를 식별하는 데 사용돼요. 서버에 지정될 때 이름은 리전 내에서 고유해야 해요.
• plugin_dir (string: "") — 플러그인을 찾는 데 사용할 디렉터리를 지정해요. 이 매개변수가 비어 있으면 Nomad는 최상위 data_dir에 plugins를 붙여 경로를 생성해요. 예: "/opt/nomad/plugins". 절대 경로여야 해요. exec2 같은 권한 없는 사용자로 실행되는 플러그인을 사용한다면 plugin_dir을 data_dir 밖에 설정하고 실행 가능하도록 허용해야 해요.
• plugin (Plugin: nil) — 특정 플러그인의 구성을 지정해요. plugin 블록은 구성되는 각 플러그인마다 한 번씩 반복될 수 있어요. 블록의 키는 plugin_dir 기준으로 한 플러그인의 실행 파일 이름이에요.
• ports (Port: 설명 참고) — Nomad 에이전트가 필요로 하는 다른 서비스에 사용되는 네트워크 포트를 지정해요.
  • http — HTTP 서버를 실행하는 데 사용되는 포트.
  • rpc — 에이전트와 서버 간, 그리고 합의 알고리즘(raft)을 위한 서버 간 트래픽에 사용되는 내부 RPC 통신 포트.
  • serf — 클러스터 멤버십을 위한 가십 프로토콜에 사용되는 포트. 이 포트에서 서버 노드 간 TCP와 UDP 모두 라우팅 가능해야 해요.
  • 기본값은 다음과 같아요: ports { http = 4646 rpc = 4647 serf = 4648 }
• region (string: "global") — Nomad 에이전트가 멤버인 리전을 지정해요. 리전은 일반적으로 지리적 리전에 매핑되며(예: us), 잠재적으로 us-west, us-east 같은 데이터센터에 매핑되는 여러 존을 가질 수 있어요.

  주의! data_dir에 데이터가 저장된 에이전트의 리전을 변경하면 새 리전에서 덮어쓰기와 데이터 손실이 발생할 수 있으므로 에이전트 시작 후 이 값을 수정하지 마세요. 변경해야 한다면 에이전트를 다시 실행하기 전에 이전 리전의 로컬 상태가 남아 있지 않은지 확인하세요.

• rpc (RPC: nil) — RPC에 특정한 구성을 지정해요. RPC 값을 구성하지 않는 것을 강력히 권장해요. 수천 개 노드의 클러스터에서 프로덕션 검증된 기본값을 사용하세요. 특정 사용 사례를 개선한다고 확신할 구체적인 이유가 있을 때만 rpc 블록을 구성해야 해요.
• sentinel (Sentinel: nil) — Sentinel 정책에 대한 구성을 지정해요.
• server (Server: nil) — Nomad 서버에 특정한 구성을 지정해요.
• syslog_facility (string: "LOCAL0") — 기록할 syslog facility를 지정해요. enable_syslog가 true일 때만 효과가 있어요.
• tls (TLS: nil) — TLS에 대한 구성을 지정해요.
• vault (Vault: nil) — Vault에 연결하기 위한 구성을 지정해요.

구성 리로드 (Configuration Reload)

Nomad 프로세스에 SIGHUP 신호를 보내 구성의 제한된 부분집합을 리로드할 수 있어요. 현재 리로드를 지원하는 필드는 다음과 같아요.

• log_level : 로그 수준은 리로드되지만 다른 로깅 구성 값은 아니에요.
• tls : 이것은 Nomad 에이전트(서버와 클라이언트) 간의 TLS 구성만 리로드하며, Consul 또는 Vault와의 통신을 위한 TLS 구성은 아니에요.
• vault : 이것은 Nomad와 Vault 간의 TLS 구성만 리로드하며, 다른 구성 값은 아니에요.

클라이언트 에이전트는 또한 일부 지문(fingerprint)을 리로드해요: CPU, 메모리, 네트워킹, Consul, Vault, CNI, 동적 호스트 볼륨 플러그인, 시크릿 플러그인, 클라우드 제공자 메타데이터.

다른 구성 값을 리로드하려면 Nomad 에이전트를 재시작해야 해요.

Enterprise — Nomad Enterprise는 라이선스가 필요해요. server.license_path 구성이나 NOMAD_LICENSE_PATH 환경 변수가 설정되어 있으면 구성 리로드 시 라이선스가 파일에서 다시 로드돼요.

Nomad 에이전트가 초기화 중에 SIGHUP을 받으면 충돌할 수 있어요(GH-3885 참고). 구성 리로드를 시도하기 전에 Nomad 에이전트가 RPC 트래픽을 받을 수 있는지 확인하세요.

예시 (Examples)

커스텀 리전과 데이터센터 (Custom region and datacenter)

이 예시는 Nomad 에이전트에 대한 커스텀 리전과 데이터 센터를 구성하는 방법을 보여줘요.

region     = "europe"
datacenter = "ams"

CORS 활성화 (Enable CORS)

이 예시는 HTTP API 엔드포인트에서 CORS를 활성화하는 방법을 보여줘요.

http_api_response_headers {
  "Access-Control-Allow-Origin" = "*"
}

더 알아보기 (Learn more)

• 서버 구성 (Server configuration)
• 클라이언트 구성 (Client configuration)
• TLS 구성 (TLS configuration)