client 구성 블록

client 구성 블록 (Client Configuration Block)

이 페이지는 Nomad 에이전트 구성의 client 블록에서 Nomad 클라이언트를 구성하는 방법에 대한 참조 정보를 제공해요. 클라이언트를 활성화하고, 할당 디렉터리, 아티팩트·템플릿 동작, 네트워킹, 노드 풀, 조인할 서버, 가비지 컬렉션, 워크로드 동작, 클라이언트 리소스, chroot, 호스트 볼륨, 호스트 네트워크, 드라이버별 동작을 구성해요.

출처: 문서

본문

Nomad 에이전트 프로세스와 클러스터의 서버·클라이언트 노드를 구성하는 방법은 Set Server and Client Nodes 및 Nomad Agent 페이지를 참고해요.

client {
  enabled = true
  servers = ["1.2.3.4:4647", "5.6.7.8:4647"]
}

client 매개변수 (Parameters)

• alloc_dir (string: "") — 할당 데이터에 사용할 디렉터리를 지정해요. 이 매개변수가 비어 있으면 Nomad는 최상위 data_dir에 alloc을 붙여 경로를 생성해요. 예: "/opt/nomad/alloc". 절대 경로여야 해요. 에이전트 프로세스가 시작될 때 디렉터리가 존재하지 않으면 Nomad는 호스트에 디렉터리를 만들어요.
• alloc_mounts_dir (string: "") — unveil 파일 격리 모드에 대한 바인딩 마운트에 사용할 디렉터리를 지정해요. 이 매개변수가 비어 있으면 Nomad는 최상위 data_dir의 형제 위치에 alloc_mounts라는 이름으로 경로를 생성해요. 예를 들어 data_dir이 /opt/nomad/data이면 alloc mounts 디렉터리는 /opt/nomad/alloc_mounts예요. 절대 경로여야 하며 Nomad 데이터 디렉터리 안에 있으면 안 돼요. 에이전트 프로세스가 시작될 때 디렉터리가 존재하지 않으면 Nomad는 호스트에 디렉터리를 만들어요.
• chroot_env (ChrootEnv: nil) — Exec과 Java 드라이버를 사용하는 작업에 대한 chroot 환경을 정의하는 키-값 매핑을 지정해요.
• enabled (bool: false) — 클라이언트 모드가 활성화되어 있는지 여부를 지정해요. 다른 모든 클라이언트 구성 옵션은 이 값에 의존해요.
• max_kill_timeout (string: "30s") — 작업이 종료될 때까지 기다릴 수 있는 최대 시간을 지정해요. 개별 작업은 자체 킬 타임아웃을 커스터마이즈할 수 있지만 이 값을 초과할 수는 없어요.
• disable_remote_exec (bool: false) — 클라이언트가 이 클라이언트에서 실행되는 태스크에 대한 원격 태스크 실행을 비활성화할지 여부를 지정해요.
• meta (map[string]string: nil) — 사용자 정의 메타데이터로 주석을 다는 키-값 맵을 지정해요.
• network_interface (string: 다양함) — 네트워크 지문화를 강제할 인터페이스의 이름을 지정해요. dev 모드로 실행할 때는 루프백 인터페이스로 기본 설정돼요. dev 모드가 아니면 기본 경로에 연결된 인터페이스가 사용돼요. 스케줄러는 태스크에 포트를 할당할 때 이 지문화된 IP 주소들에서 선택해요. 이 값은 go-sockaddr/template 형식을 지원해요. Nomad는 지문화된 인터페이스를 "default" host_network에 추가해요. 비로컬 IP 주소가 발견되지 않으면 클라이언트의 "fingerprint.network.disallow_link_local" 구성 값에 따라 Nomad가 링크-로컬 IPv6 주소를 지문화할 수 있어요.
• preferred_address_family (string: "") — 네트워크 인터페이스의 선호 주소 패밀리를 지정해요. 값은 ipv4 또는 ipv6일 수 있어요. 선택된 네트워크 인터페이스에 IPv4와 IPv6 주소가 모두 있으면 이 옵션은 선호 패밀리의 IP 주소를 선택해요. 옵션이 지정되지 않으면 현재 동작이 유지돼요: 패밀리와 관계없이 첫 번째 IP 주소가 선택돼요.
• cpu_disable_dmidecode (bool: false) — 클라이언트가 cpu 감지 방법으로 dmidecode를 사용하지 않도록 지정해요. Nomad는 Linux를 제외한 모든 플랫폼에서 이 필드를 무시해요.
• cpu_total_compute (int: 0) — 총 CPU 컴퓨트에 대한 오버라이드를 지정해요. 이 값은 # Cores * Core MHz로 설정해야 해요. 예를 들어 2 GHz에서 실행되는 쿼드코어는 8000(4 * 2000)의 총 컴퓨트를 가져요. 대부분의 클라이언트는 총 CPU 컴퓨트를 자동으로 결정할 수 있으므로, 대부분의 경우 이 값은 설정하지 않은 채로 두어야 해요.
• memory_total_mb (int: 0) — 총 메모리에 대한 오버라이드를 지정해요. 설정되면 이 값은 감지된 메모리를 덮어써요.
• disk_total_mb (int: 0) — 총 디스크 공간 지문화 속성에 대한 오버라이드를 지정해요. unique.storage.bytestotal 속성에 제약 조건을 설정하지 않으면 이 값은 스케줄러가 사용하지 않아요. 실제 총 디스크 공간은 Read Stats API로 확인할 수 있어요.
• disk_free_mb (int: 0) — 이전에는 할당 스케줄링을 위한 사용 가능한 디스크 공간을 지정했어요. 설정하면 감지된 사용 가능한 디스크 공간을 덮어썼어요. 이 값은 더 이상 사용되지 않으며 이제 Nomad 클라이언트가 무시해요. client.reserved.disk를 대신 사용하세요.
• min_dynamic_port (int: 20000) — 할당할 최소 동적 포트를 지정해요. 개별 포트와 포트 범위는 reserved 매개변수로 동적 포트 할당에서 제외할 수 있어요.
• max_dynamic_port (int: 32000) — 할당할 최대 동적 포트를 지정해요. 개별 포트와 포트 범위는 reserved 매개변수로 동적 포트 할당에서 제외할 수 있어요.
• node_class (string: "") — 사용자 정의 클래스로 클라이언트 노드를 논리적으로 그룹화하는 데 사용되는 임의의 문자열을 지정해요. 이 값은 작업 배치 중 affinity나 constraint 속성으로, 그리고 변수 보간이 지원되는 다른 곳에서 사용할 수 있어요.
• node_max_allocs (int: 0) — 클라이언트 노드에 스케줄링될 수 있는 최대 할당 수를 지정하며, 설정하지 않으면 적용되지 않아요. 이 값은 nomad node status의 Allocated Resources에서 볼 수 있어요.
• node_pool (string: "default") — 클라이언트가 등록되는 노드 풀을 지정해요. 노드 풀이 아직 존재하지 않으면 노드가 권위 리전에 등록될 때 자동으로 생성돼요. 비권위 리전에서는 노드 풀이 생성되고 복제될 때까지 노드가 initializing 상태로 유지돼요. 이미 할당을 실행 중인 클라이언트에서 이 옵션을 변경할 때는 변경 전에 all 노드 풀을 대상으로 하지 않는 모든 할당을 드레인하고 클라이언트를 재시작하세요.
• options (Options: nil) — 드라이버 구성 같은 클라이언트 내부 구성의 키-값 매핑을 지정해요.
• reserved (Reserved: nil) — Nomad가 태스크를 받지 않도록 노드 리소스의 일부를 예약해야 한다고 지정해요. 이는 노드의 특정 용량 사용률을 목표로 하는 데 사용할 수 있어요. 예를 들어 노드 CPU의 20%에 해당하는 값을 예약해 CPU 사용률 80%를 목표로 할 수 있어요.
• servers (array<string>: []) — 이 클라이언트가 조인해야 하는 Nomad 서버 주소 배열을 지정해요. 이 목록은 서버 노드에 클라이언트를 등록하고 사용 가능한 리소스를 알려 에이전트가 작업을 받을 수 있게 하는 데 사용돼요. IP 주소나 DNS로 지정할 수 있고, 포트가 있을 수도 없을 수도 있어요. 포트를 생략하면 기본 포트 4647이 사용돼요. IPv6 주소를 지정하는 경우 대괄호가 있는 URL 형식이어야 해요(예: "[2001:db8::1]").
• server_join (server_join: nil) — Nomad 클라이언트가 Nomad 서버에 연결하는 방법을 지정해요. 클라이언트에서는 start_join 필드가 지원되지 않아요. retry_join 필드는 서버 주소를 직접 지정하거나 자동 발견을 위해 go-discover 구문을 사용할 수 있어요.
• state_dir (string: "") — 클라이언트 상태를 저장하는 데 사용할 디렉터리를 지정해요. 이 매개변수가 비어 있으면 Nomad는 최상위 data_dir에 client를 붙여 경로를 생성해요. 예: "/opt/nomad/client". 절대 경로여야 해요. 에이전트 프로세스가 시작될 때 디렉터리가 존재하지 않으면 Nomad는 호스트에 디렉터리를 만들어요.
• gc_interval (string: "1m") — Nomad가 terminal 할당 디렉터리를 가비지 컬렉션하려고 시도하는 간격을 지정해요.
• gc_disk_usage_threshold (float: 80) — Nomad가 terminal 할당을 가비지 컬렉션해 유지하려는 디스크 사용률(%)을 지정해요. 서버에서 가비지 컬렉션되면 Nomad는 terminal 할당을 즉시 가비지 컬렉션한다는 점을 참고해 주세요.
• gc_inode_usage_threshold (float: 70) — Nomad가 terminal 할당을 가비지 컬렉션해 유지하려는 inode 사용률(%)을 지정해요. 서버에서 가비지 컬렉션되면 Nomad는 terminal 할당을 즉시 가비지 컬렉션한다는 점을 참고해 주세요.
• gc_max_allocs (int: 50) — terminal 할당의 가비지 컬렉션을 촉발하기 전에 클라이언트가 추적할 최대 할당 수를 지정해요. 이는 노드가 한 번에 실행할 수 있는 할당 수를 제한하지는 않지만, gc_max_allocs 이후에는 모든 새 할당이 terminal 할당을 GC되게 해요. 서버에서 가비지 컬렉션되면 Nomad는 terminal 할당을 즉시 가비지 컬렉션한다는 점을 참고해 주세요.
• gc_parallel_destroys (int: 2) — 가비지 컬렉터가 허용하는 최대 병렬 파괴(parallel destroys) 수를 지정해요. 이 값은 가비지 컬렉션 중 높은 리소스 사용을 피하기 위해 상대적으로 낮게 유지해야 해요.
• gc_volumes_on_node_gc (bool: false) — 노드가 가비지 컬렉션될 때 서버가 이 노드의 동적 호스트 볼륨을 삭제해야 한다고 지정해요. 가비지 컬렉션된 노드가 임시 클라우드 호스트처럼 다시는 클러스터에 조인하지 않을 것임을 알 때만 true로 설정해야 해요.
• no_host_uuid (bool: true) — 기본적으로 무작위 노드 UUID가 생성되지만, false로 설정하면 시스템의 UUID를 사용해요.
• cni_path (string: "/opt/cni/bin:/usr/libexec/cni") — CNI 플러그인 발견에 사용되는 검색 경로를 설정해요. 콜론으로 구분된 경로로 여러 경로를 검색할 수 있어요. CNI는 Linux에서만 지원돼요.
• cni_config_dir (string: "/opt/cni/config") — CNI 네트워크 구성이 위치한 디렉터리를 설정해요. 클라이언트는 CNI 네트워크를 지문화할 때 이 경로를 사용해요. 파일 이름은 .conflist 확장자를 사용해야 해요. .conf 또는 .json 확장자의 파일은 개별 플러그인 구성으로 로드돼요.
• bridge_network_name (string: "nomad") — 클라이언트에서 bridge 네트워킹 모드로 실행되는 할당을 위해 Nomad가 만들 브리지의 이름을 설정해요.
• bridge_network_subnet (string: "172.26.64.0/20") — 클라이언트가 IP 주소를 할당하는 데 사용할 서브넷을 지정해요.
• bridge_network_subnet_ipv6 (string: "") — 클라이언트가 IPv6 주소를 할당하는 데 사용할 서브넷을 지정해 Nomad의 브리지 네트워크에서 IPv6를 활성화해요.
• bridge_network_hairpin_mode (bool: false) — 이 클라이언트에서 bridge 네트워킹 모드로 실행되는 할당을 위해 Nomad가 만든 네트워크 브리지에서 hairpin 모드가 활성화되어 있는지 여부를 지정해요. 제약 조건에서 해당 nomad.bridge.hairpin_mode 노드 속성을 사용할 수 있어요. hairpin 모드가 활성화되면 할당이 자신의 IP와 그에 바인드된 모든 포트에 도달할 수 있어요. 이 값을 변경하려면 클라이언트 호스트를 재부팅해야 적용돼요.
• artifact (Artifact: 다양함) — 태스크 artifact 블록의 동작에 대한 제어를 지정해요.
• template (Template: nil) — 태스크 template 블록의 동작에 대한 제어를 지정해요.
• common_plugin_dir (string: "") — common plugins 인터페이스를 따르는 플러그인을 배치해야 하는 디렉터리를 지정해요. 이 매개변수가 비어 있으면 Nomad는 최상위 data_dir에 common_plugins를 붙여 경로를 생성해요. 예: "/opt/nomad/common_plugins". 절대 경로여야 해요.
• fingerprint (Fingerprint: nil) — 클라이언트가 사용하는 지문화자에 대한 구성을 제공하며 "env_aws", "env_azure", "env_digitalocean", "env_gce" 지문화자에 적용돼요.
• host_volume (host_volume: nil) — 작업에 마운트될 수 있는 볼륨으로 호스트의 경로를 노출해요.
• host_volumes_dir (string: "") — 호스트 볼륨 플러그인이 볼륨을 배치해야 하는 디렉터리를 지정해요. 이 매개변수가 비어 있으면 Nomad는 최상위 data_dir에 host_volumes를 붙여 경로를 생성해요. 예: "/opt/nomad/host_volumes". 절대 경로여야 해요.
• host_volume_plugin_dir (string: "") — 호스트 볼륨 플러그인을 찾을 디렉터리를 지정해요. 이 매개변수가 비어 있으면 Nomad는 최상위 data_dir에 host_volume_plugins를 붙여 경로를 생성해요. 예: "/opt/nomad/host_volume_plugins". 절대 경로여야 해요.
• host_network (host_network: nil) — 포트 매핑 시 선택할 수 있는 추가 호스트 네트워크를 노드에 등록해요. 이 매개변수는 기본적으로 nil이지만, Nomad는 network_interface 필드를 사용해 "default"이라는 호스트 네트워크를 만들어요.
• bind_wildcard_default_host_network (bool: true) — 커스텀 host_network 블록이 정의되지 않았을 때, bridge 또는 cni/* 포트 매핑 규칙이 모든 대상 주소(true, 기본값)와 일치할지 아니면 기본 호스트 네트워크의 IP와만 일치할지(false) 제어해요. 하나 이상의 host_network 블록이 정의되면 이 설정은 무시되고 포트 매핑은 항상 선택된 호스트 네트워크 주소를 사용해요. 호스트 포트를 기본 인터페이스 IP에서만 게시해야 할 때만 false로 설정하세요.
• drain_on_shutdown (drain_on_shutdown: nil) — leave_on_interrupt 또는 leave_on_terminate가 설정되고 클라이언트가 해당 신호를 받을 때 클라이언트의 동작을 제어해요.
• cgroup_parent (string: "/nomad") — Nomad가 관리하는 cgroup 하위 시스템이 마운트될 cgroup 부모를 지정해요. 현재 이것은 cpuset 하위 시스템에만 적용돼요. 이 필드는 Linux 플랫폼이 아닌 곳에서는 무시돼요.
• users (Users: nil) — 운영체제 사용자의 Nomad 클라이언트 사용에 관한 옵션을 지정해요.
• default_ineligible (bool: false) — 노드가 클라이언트 초기화 시 부적격(ineligible)으로 표시되어야 함을 지정해요.

chroot_env 매개변수 (Parameters)

Linux에서 격리된 fork/exec 기반 드라이버는 chroot를 사용해 파일시스템 격리를 구현해요. chroot_env 맵을 사용하면 호스트 운영체제의 소스 경로로 chroot 환경을 구성할 수 있어요.

매핑 형식은 다음과 같아요.

source_path -> dest_path

다음 예시는 ls 유틸리티를 실행하기에 충분한 chroot를 지정해요.

client {
  chroot_env {
    "/bin/ls"           = "/bin/ls"
    "/etc/ld.so.cache"  = "/etc/ld.so.cache"
    "/etc/ld.so.conf"   = "/etc/ld.so.conf"
    "/etc/ld.so.conf.d" = "/etc/ld.so.conf.d"
    "/etc/passwd"       = "/etc/passwd"
    "/lib"              = "/lib"
    "/lib64"            = "/lib64"
  }
}

경고 — chroot 제한: Nomad는 기본적으로 /run 디렉터리의 임시 런타임 파일을 복사하지 않아요. 예를 들어 Ubuntu에서 /etc/resolv.conf는 /run/systemd/resolve/stub-resolv.conf에 대한 심볼릭 링크이므로, Nomad는 resolv.conf를 chroot 환경에 복사하지 않아요. 이러한 경우 각 chroot 태스크에 대해 작업의 network 블록을 구성하세요.

chroot_env가 지정되지 않으면 exec 드라이버는 운영체제의 가장 일반적으로 사용되는 부분과 함께 기본 chroot 환경을 사용해요. 전체 목록은 Nomad exec 드라이버 문서를 참고해요.

Nomad는 chroot에 alloc_dir을 임베드하려고 절대 시도하지 않아요. 그렇게 하면 무한 재귀가 발생하기 때문이에요.

options 매개변수 (Parameters)

다음은 Nomad 클라이언트만을 위한 옵션의 완전한 목록이 아니에요. 각 개별 Nomad 드라이버가 지원하는 옵션을 찾으려면 드라이버 문서를 참고해요.

• "driver.allowlist" (string: "") — 허용 목록에 포함된 드라이버의 쉼표로 구분된 목록을 지정해요. 지정되면 허용 목록에 없는 드라이버는 비활성화돼요. 허용 목록이 비어 있으면 해당되는 곳에서 모든 드라이버가 지문화되고 활성화돼요.

  client {
    options = {
      "driver.allowlist" = "docker,qemu"
    }
  }
  

• "driver.denylist" (string: "") — 차단 목록에 포함된 드라이버의 쉼표로 구분된 목록을 지정해요. 지정되면 차단 목록의 드라이버는 비활성화돼요.

  client {
    options = {
      "driver.denylist" = "docker,qemu"
    }
  }
  

• "env.denylist" (string: 설명 참고) — 이러한 태스크에 전달하지 않을 환경 변수 키의 쉼표로 구분된 목록을 지정해요. Nomad는 호스트 환경 변수를 exec, raw_exec, java 태스크에 전달해요. 지정되면 기본값이 덮어써져요. 값이 제공되면 모든 기본값이 덮어써져요(병합되지 않음).

  client {
    options = {
      "env.denylist" = "MY_CUSTOM_ENVVAR"
    }
  }
  

  기본 목록은 다음과 같아요: CONSUL_TOKEN CONSUL_HTTP_TOKEN CONSUL_HTTP_TOKEN_FILE NOMAD_TOKEN VAULT_TOKEN CONSUL_LICENSE NOMAD_LICENSE VAULT_LICENSE CONSUL_LICENSE_PATH NOMAD_LICENSE_PATH VAULT_LICENSE_PATH AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_METADATA_URL GOOGLE_APPLICATION_CREDENTIALS GOOGLE_OAUTH_ACCESS_TOKEN
• "user.denylist" (string: 설명 참고) — 태스크가 실행될 수 없는 사용자 이름의 쉼표로 구분된 차단 목록을 지정해요. 드라이버가 "user.checked_drivers"에 포함된 경우에만 적용돼요. 값이 제공되면 모든 기본값이 덮어써져요(병합되지 않음).

  client {
    options = {
      "user.denylist" = "root,ubuntu"
    }
  }
  

  기본 목록은 root Administrator예요.
• "user.checked_drivers" (string: 설명 참고) — "user.denylist"를 적용할 드라이버의 쉼표로 구분된 목록을 지정해요. 컨테이너를 사용하는 드라이버의 경우 이 적용은 보통 불필요해요. 값이 제공되면 모든 기본값이 덮어써져요(병합되지 않음).

  client {
    options = {
      "user.checked_drivers" = "exec,raw_exec"
    }
  }
  

  기본 목록은 exec qemu java예요.
• "fingerprint.allowlist" (string: "") — 허용 목록에 포함된 지문화자의 쉼표로 구분된 목록을 지정해요. 지정되면 허용 목록에 없는 지문화자는 비활성화돼요. 허용 목록이 비어 있으면 모든 지문화자가 사용돼요.

  client {
    options = {
      "fingerprint.allowlist" = "network"
    }
  }
  

• "fingerprint.denylist" (string: "") — 차단 목록에 포함된 지문화자의 쉼표로 구분된 목록을 지정해요. 지정되면 차단 목록의 지문화자는 비활성화돼요. 지문화 차단 목록의 일반적인 사용 사례는 관련 없는 클라우드 환경의 지문화자를 비활성화해 클라이언트 에이전트 시작 시간을 늦추지 않게 하는 것이에요.

  client {
    options = {
      "fingerprint.denylist" = "env_aws,env_gce,env_azure,env_digitalocean"
    }
  }
  

• "fingerprint.network.disallow_link_local" (string: "false") — 전역 라우팅 가능 주소가 발견되지 않을 때 네트워크 지문화자가 링크-로컬 주소를 무시해야 하는지 여부를 지정해요. 지문화자는 항상 전역 라우팅 가능 주소를 선호해요.

  client {
    options = {
      "fingerprint.network.disallow_link_local" = "true"
    }
  }
  

reserved 매개변수 (Parameters)

• cpu (int: 0) — 예약할 CPU 양(MHz)을 지정해요.
• cores (string: "") — 예약할 CPU 코어의 cpuset을 지정해요. Linux에서만 지원돼요.

  client {
    reserved {
      cores = "0-4"
    }
  }
  

• memory (int: 0) — 예약할 메모리 양(MB)을 지정해요.
• disk (int: 0) — 예약할 디스크 양(MB)을 지정해요.
• reserved_ports (string: "") — 모든 지문화된 네트워크 장치에 예약할 포트의 쉼표로 구분된 목록을 지정해요. 두 포괄적 끝을 구분하는 하이픈으로 범위를 지정할 수 있어요. 특정 호스트 네트워크의 포트 예약은 host_network를 참고해요.

artifact 매개변수 (Parameters)

• http_read_timeout (string: "30m") — HTTP 다운로드 요청이 취소되기 전에 완료되어야 하는 최대 기간을 지정해요. 제한을 적용하지 않으려면 0으로 설정해요.
• http_max_size (string: "100GB") — HTTP로 다운로드된 아티팩트에 허용되는 최대 크기를 지정해요. 제한을 적용하지 않으려면 0으로 설정해요.
• gcs_timeout (string: "30m") — Google Cloud Storage 작업이 취소되기 전에 완료되어야 하는 최대 기간을 지정해요. 제한을 적용하지 않으려면 0으로 설정해요.
• git_timeout (string: "30m") — Git 작업이 취소되기 전에 완료되어야 하는 최대 기간을 지정해요. 제한을 적용하지 않으려면 0으로 설정해요.
• hg_timeout (string: "30m") — Mercurial 작업이 취소되기 전에 완료되어야 하는 최대 기간을 지정해요. 제한을 적용하지 않으려면 0으로 설정해요.
• s3_timeout (string: "30m") — S3 작업이 취소되기 전에 완료되어야 하는 최대 기간을 지정해요. 제한을 적용하지 않으려면 0으로 설정해요.
• decompression_size_limit (string: "100GB") — 오류를 촉발하고 작업을 취소하기 전에 압축 해제될 최대 데이터 양을 지정해요. 제한을 적용하지 않으려면 "0"으로 설정해요.
• decompression_file_count_limit (int: 4096) — 오류를 촉발하고 작업을 취소하기 전에 압축 해제될 최대 파일 수를 지정해요. 제한을 적용하지 않으려면 0으로 설정해요.
• disable_artifact_inspection (bool: false) — 샌드박스 탈출을 위한 아티팩트 검사를 비활성화할지 여부를 지정해요. 플랫폼이 파일시스템 격리를 지원하고 비활성화되지 않았다면, 이 값과 관계없이 아티팩트 검사는 수행되지 않아요.
• disable_filesystem_isolation (bool: false) — 아티팩트 다운로드에 대해 파일시스템 격리를 비활성화해야 하는지 여부를 지정해요. landlock을 통한 파일시스템 격리가 가능한 시스템(Linux 커널 5.13+)에만 적용돼요.
• filesystem_isolation_extra_paths ([]string: nil) — 파일시스템 격리에서 추가 경로를 허용해요. 경로는 [kind]:[mode]:[path] 형식으로 지정하며, kind는 f(파일) 또는 d(디렉터리)여야 하고 mode는 r, w, c, x(읽기, 쓰기, 생성, 실행) 중 0개 이상이어야 해요. 예: f:r:/dev/urandom은 /dev/urandom 파일 읽기를 활성화하고, d:rx:/opt/bin은 /opt/bin 디렉터리에서 읽기·실행을 활성화해요.
• set_environment_variables (string: "") — 아티팩트 샌드박스가 Nomad 클라이언트 환경에서 상속해야 하는 환경 변수의 쉼표로 구분된 목록을 지정해요. 기본적으로 운영체제에 적절한 PATH를 포함한 최소 환경이 설정돼요.

fingerprint 매개변수 (Parameters)

• name (string: "") — 구성이 적용되는 지문화자의 이름이에요. 이 필드는 필수이며 블록 라벨의 일부예요. "env_aws", "env_azure", "env_digitalocean", "env_gce"를 지원해요.
• retry_attempts (int: 0) — 포기하기 전에 만들 최대 재시도 횟수를 지정해요. 이 필드는 무제한 재시도를 위해 -1을 지원하지만, 지문화 소스를 사용할 수 없으면 클라이언트가 시작 시 무기한 중단될 수 있으므로 -1은 권장하지 않아요. 기본값 0은 재시도가 없음을 의미해요.
• retry_interval (string: "2s") — 재시도 시도 사이에 기다리는 시간을 지정해요.
• exit_on_failure (bool: false) — 지문화자가 환경 엔드포인트 서비스를 프로브하지 못하면 클라이언트가 종료해야 하는지 여부를 지정해요. Nomad는 시작 시 환경의 메타데이터 엔드포인트를 프로브해 명명된 환경 내에서 실행 중인지 식별하려고 해요. 엔드포인트에 도달할 수 없으면 기본적으로 Nomad는 해당 환경에 대한 지문화를 건너뛰고 시작을 계속해요. 이 옵션을 true로 설정하면 이런 상황에서 Nomad가 종료돼요. 이는 Nomad가 환경을 성공적으로 지문화할 수 있을 때만 시작되도록 보장하려는 경우 유용해요.

fingerprinter "env_aws" {
  retry_attempts  = "5"
  retry_interval  = "1s"
  exit_on_failure = true
}

template 매개변수 (Parameters)

• function_denylist ([]string: ["plugin", "executeTemplate", "writeToFile"]) — 작업 스펙에서 허용되지 않아야 하는 템플릿 렌더링 함수의 목록을 지정해요. 기본적으로 plugin, executeTemplate, writeToFile 함수는 호스트에 대한 무제한 루트 접근을 허용하거나 재귀 실행을 허용하므로 허용되지 않아요.
• disable_file_sandbox (bool: false) — template이 file 함수를 통해 클라이언트 호스트의 임의 파일에 접근하도록 허용해요. 기본적으로 template은 태스크 작업 디렉터리 내의 파일에만 접근할 수 있어요.
• max_stale (string: "87600h") — "오래된(stale)" 데이터를 허용할 최대 간격이에요. max_stale이 0으로 설정되면 Consul 리더만 질의에 응답하고, 팔로워에 도달한 요청은 리더로 전달돼요. 요청이 많은 대규모 클러스터에서는 이것이 확장성이 좋지 않아요. 이 옵션은 마지막 복제 데이터가 이 범위 내에 있는 한 어떤 팔로워도 질의에 응답할 수 있게 해요. 더 높은 값은 클러스터 부하를 줄이지만 데이터가 오래되었을 가능성이 더 높아요. 이 기본값 10년( 87600h )은 기본 Consul 구성과 일치해요.
• wait (map: { min = "5s" max = "4m" }) — 템플릿을 재렌더링하기 전에 기다릴 최소·최대 시간을 정의해요. Consul Template은 Consul, Nomad, 또는 Vault에서 렌더링된 변수가 변경될 때마다 템플릿을 재렌더링해요. 하지만 태스크가 재시작되거나 리로드되는 빈도를 최소화하기 위해, Nomad는 지정된 min 값과 같은 간격으로 틱하는 백오프 타이머를 Consul Template에 구성해요. Consul Template은 항상 지정된 min 값만큼은 적어도 기다려요. 두 틱 간격 사이에 기본 데이터가 변경되지 않았으면 Consul Template은 재렌더링할 수 있어요. 기본 데이터가 변경되었으면 Consul Template은 데이터가 적어도 한 틱 간격 동안 안정화되거나, 구성된 max 기간이 경과할 때까지 재렌더링을 지연해요. max 기간이 경과하면 Consul Template은 그 시점의 데이터로 템플릿을 재렌더링해요. 이는 Consul이 저하된 상태이거나 참조된 데이터 값이 빠르게 변경되는 시스템에서 템플릿이 렌더링되는 횟수를 줄이므로 유용해요. min과 max를 모두 0으로 설정하면 이 기능이 비활성화돼요. 이 구성은 태스크별 재정의를 허용하기 위해 태스크 template 블록에도 노출돼요.

  wait {
    min = "5s"
    max = "4m"
  }
  

• wait_bounds (map: nil) — 템플릿별 wait 구성에 대한 클라이언트 수준 하한·상한을 정의해요. 개별 템플릿 구성의 min이 wait_bounds.min보다 낮거나 max가 wait_bounds.max보다 크면 경계가 적용되고, 템플릿 wait는 consul-template으로 전송되기 전에 조정돼요.

  wait_bounds {
    min = "5s"
    max = "10s"
  }
  

• block_query_wait (string: "5m") — 블로킹 쿼리의 결과를 기다리는 시간(초)이에요. Consul의 많은 엔드포인트는 "blocking queries"라고 알려진 기능을 지원해요. 블로킹 쿼리는 long polling을 사용해 잠재적 변경을 기다리는 데 사용돼요.
• consul_retry (map: { attempts = 12 backoff = "250ms" max_backoff = "1m" }) — Consul에서 오류가 반환될 때 재시도 동작을 제어해요. 템플릿 러너는 실패에도 종료하지 않아요. 대신 분산 시스템에서 관례적인 것처럼 지수 백오프와 재시도 함수를 사용해 Consul 클러스터가 사용 가능해질 때까지 기다려요.

  consul_retry {
    # This specifies the number of attempts to make before giving up. Each
    # attempt adds the exponential backoff sleep time. Setting this to
    # zero will implement an unlimited number of retries.
    attempts = 12
    # This is the base amount of time to sleep between retry attempts. Each
    # retry sleeps for an exponent of 2 longer than this base. For 5 retries,
    # the sleep times would be: 250ms, 500ms, 1s, 2s, then 4s.
    backoff = "250ms"
    # This is the maximum amount of time to sleep between retry attempts.
    # When max_backoff is set to zero, there is no upper limit to the
    # exponential sleep between retry attempts.
    # If max_backoff is set to 10s and backoff is set to 1s, sleep times
    # would be: 1s, 2s, 4s, 8s, 10s, 10s, ...
    max_backoff = "1m"
  }
  

• use_client_consul_token (bool: false) — 워크로드 아이덴티티가 구성되지 않은 경우 태스크 템플릿이 Nomad 클라이언트 에이전트의 Consul 토큰을 사용하도록 허용해요. Nomad 클라이언트 에이전트의 토큰은 워크로드 템플릿이 요구하는 모든 Consul 읽기를 허용하는 정책을 가져야 해요. 여기에는 서비스 카탈로그 읽기와 모든 Consul 네임스페이스의 Consul KV 읽기가 포함될 수 있어요.
• vault_retry (map: { attempts = 12 backoff = "250ms" max_backoff = "1m" }) — Vault에서 오류가 반환될 때 재시도 동작을 제어해요. Consul Template은 매우 결함 허용적이므로 실패에도 종료하지 않아요. 대신 지수 백오프와 재시도 함수를 사용해 클러스터가 사용 가능해질 때까지 기다려요.

  vault_retry {
    attempts = 12
    backoff = "250ms"
    max_backoff = "1m"
  }
  

• nomad_retry (map: { attempts = 12 backoff = "250ms" max_backoff = "1m" }) — Nomad에서 오류가 반환될 때 재시도 동작을 제어해요. Consul Template은 매우 결함 허용적이므로 실패에도 종료하지 않아요. 대신 지수 백오프와 재시도 함수를 사용해 클러스터가 사용 가능해질 때까지 기다려요.

  nomad_retry {
    attempts = 12
    backoff = "250ms"
    max_backoff = "1m"
  }
  

host_volume 블록 (host_volume Block)

host_volume 블록은 볼륨을 작업에 사용 가능하게 만드는 데 사용돼요. volume create 또는 volume register 명령어로 동적 호스트 볼륨을 구성할 수도 있어요.

블록의 키는 "host" 유형 볼륨과 ACL의 source 매개변수에서 사용할 볼륨 이름에 해당해요. 구성의 호스트 볼륨은 같은 노드의 동적 호스트 볼륨과 같은 이름을 가질 수 없어요.

client {
  host_volume "ca-certificates" {
    path      = "/etc/ssl/certs"
    read_only = true
  }
}

host_volume 매개변수 (Parameters)

• path (string: "", required) — 이 볼륨이 태스크에 마운트될 때 소스로 사용되어야 하는 호스트의 경로를 지정해요. 클라이언트 시작 시 경로가 존재해야 해요.
• read_only (bool: false) — 볼륨이 항상 read_only로만 마운트되어야 하는지, 아니면 쓰기 가능해야 하는지 지정해요.

host_network 블록 (host_network Block)

host_network 블록은 포트 매핑 시 사용할 수 있는 추가 호스트 네트워크를 노드에 등록하는 데 사용돼요. 같은 이름의 host_network 블록을 여러 개 정의해 같은 호스트 네트워크에 여러 인터페이스나 CIDR 범위를 할당할 수 있어요. 작업에서 사용될 때 Nomad는 호스트 네트워크에 대한 첫 번째 사용 가능한 주소에 포트를 예약해요.

블록의 키는 host_network에서 사용되는 네트워크의 이름에 해당해요.

client {
  // Nomad adds interface en1 to the existing "default" host_network
  // created from the "network_interface" field.
  host_network "default" {
    interface      = "en1"
  }

  host_network "public" {
    cidr           = "203.0.113.0/24"
    reserved_ports = "22,80"
  }
}

host_network 매개변수 (Parameters)

• cidr (string: "") — 일치시킬 주소의 cidr 블록을 지정해요. 이 cidr 블록에 포함된 주소가 노드에서 발견되면 해당 호스트 네트워크가 그 주소로 등록돼요.
• interface (string: "") — 특정 인터페이스로 주소 검색을 필터링해요.
• reserved_ports (string: "") — 이 네트워크와 연관된 모든 주소에 예약할 포트의 쉼표로 구분된 목록을 지정해요. 두 포괄적 끝을 구분하는 하이픈으로 범위를 지정할 수 있어요. reserved.reserved_ports도 각 호스트 네트워크에 예약돼요.

drain_on_shutdown 블록 (drain_on_shutdown Block)

drain_on_shutdown 블록은 leave_on_interrupt 또는 leave_on_terminate가 설정될 때 클라이언트의 동작을 제어해요. 기본적으로 drain_on_shutdown은 구성되지 않으며 클라이언트는 어떤 신호에도 드레인하지 않아요.

drain_on_shutdown이 구성되면 노드는 적절한 신호(leave_on_interrupt의 경우 SIGINT 또는 leave_on_terminate의 경우 SIGTERM)를 받을 때 자신을 드레인해요. 기본적으로 이것은 nomad node drain -self -no-deadline을 실행하는 것과 유사하게 동작해요.

데드라인이 설정되지 않았더라도, 드레인이 서비스 종료가 허용하는 것보다 오래 걸리면 init 시스템이 Nomad에 SIGKILL을 보낼 수 있다는 점을 참고해 주세요. 예를 들어 systemd로 Linux에서 실행할 때는 클라이언트가 드레인할 충분한 시간을 확보하도록 nomad.service 유닛 파일에서 TimeoutStopSec 값을 조정해야 해요.

client {
  # Either leave_on_interrupt or leave_on_terminate must be set
  # for this to take effect.
  drain_on_shutdown {
    deadline           = "1h"
    force              = false
    ignore_system_jobs = false
  }
}

• deadline (string: "1h") — 모든 할당이 클라이언트에서 이동되어야 하는 데드라인을 설정해요. 데드라인 이후 남은 할당은 [migrate][] 블록과 관계없이 클라이언트에서 제거돼요. 기본값은 1시간이에요.
• force (bool: false) — true로 설정하면 [migrate][] 블록을 무시하고 클라이언트의 모든 할당을 즉시 드레인해요. 드레인 중인 클라이언트에 같은 작업의 여러 할당이 있고 다른 클라이언트에는 추가 할당이 없다면, 드레인이 완료될 때까지 해당 작업에 중단이 발생한다는 점을 참고해 주세요.
• ignore_system_jobs (bool: false) — true로 설정하면 system 작업 할당을 중지하지 않고 드레인이 완료되도록 해요. 기본적으로 system 작업(및 CSI 플러그인)은 마지막에 중지돼요.

users 블록 (users Block)

users 블록은 운영체제 사용자의 Nomad 클라이언트 사용 측면을 제어해요.

client {
  users {
    dynamic_user_min = 80000
    dynamic_user_max = 89999
  }
}

• dynamic_user_min (int: 80000) — 동적 워크로드 사용자를 사용할 수 있는 태스크 드라이버에 할당할 최저 UID/GID예요.
• dynamic_user_max (int: 89999) — 동적 워크로드 사용자를 사용할 수 있는 태스크 드라이버에 할당할 최고 UID/GID예요.

client 예시 (Examples)

일반 설정 (Common Setup)

이 예시는 클러스터에 조인된 Nomad 클라이언트의 가장 기본적인 구성을 보여줘요.

client {
  enabled = true
  server_join {
    retry_join     = [ "1.1.1.1", "2.2.2.2" ]
    retry_max      = 3
    retry_interval = "15s"
  }
}

예약 리소스 (Reserved Resources)

이 예시는 클라이언트에 리소스를 예약하는 샘플 구성을 보여줘요. 클라이언트 리소스의 일부만 작업에 할당하려는 경우 유용해요.

client {
  enabled = true

  reserved {
    cpu            = 500
    memory         = 512
    disk           = 1024
    reserved_ports = "22,80,8500-8600"
  }
}

커스텀 메타데이터와 노드 클래스 (Custom Metadata and Node Class)

이 예시는 메타데이터와 노드 클래스를 커스터마이즈하는 클라이언트 구성을 보여줘요. 스케줄러는 제약 조건을 처리할 때 이 정보를 사용할 수 있어요. 메타데이터는 완전히 사용자가 구성할 수 있으며, 예시의 값은 설명 목적일 뿐이에요.

client {
  enabled       = true
  node_class    = "prod"

  meta {
    owner           = "ops"
    cached_binaries = "redis,apache,nginx,jq,cypress,nodejs"
    rack            = "rack-12-1"
  }
}

더 알아보기 (Learn more)

• 서버 구성 (Server configuration)
• 에이전트 구성 개요 (Agent configuration overview)
• 노드 풀 (Node pools)