server_join 구성 블록

server_join 구성 블록 (Server Join Configuration Block)

이 페이지는 Amazon, Microsoft, Google 클라우드 및 온프레미스에서 Nomad 에이전트가 Nomad 서버를 발견하고 연결하는 방법을 구성하는 방법에 대한 참조 정보를 제공해요. server_join 블록을 사용해 조인할 서버 목록, 재시도 간격, 최대 재조인 시도 횟수를 구성해요.

출처: 문서

본문

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

server_join 매개변수 (Parameters)

  • retry_join (array<string>: []) — 클러스터 멤버로 조인되는 Nomad 서버 주소와 Cloud Auto-join 구성의 목록을 지정해요. start_join과 유사하지만 조인 시도는 retry_max 횟수까지 재시도돼요. 또한 retry_join은 Nomad 서버와 클라이언트 모두에서 사용할 수 있지만, start_join은 Nomad 서버에만 정의돼요. 이것은 주소가 결국 사용 가능해질 것임을 알 때 유용해요. 배열과 함께 retry_join을 start_join의 대체로 사용하고, 두 옵션을 함께 사용하지 마세요. 서버 주소는 서버 주소 형식을 따라야 해요.

    server_join {
  retry_join = [ "1.1.1.1", "2.2.2.2" ]
}

    Auto-join 구성은 Cloud Auto-join 형식을 따라야 해요. go-discover를 사용해 AWS EC2 클러스터에 조인하는 Cloud Auto-join:

    server_join {
  retry_join = [ "provider=aws tag_key=..." ]
}

    go-netaddrs를 사용해 hcloud CLI로 nomad-server=true라는 라벨이 붙은 Hetzner 서버 클러스터에 조인하는 Cloud Auto-join:

    server_join {
  retry_join = [ "exec=hcloud server list -o noheader -o columns=ipv4 -l nomad-server=true | tr '\n' ' '" ]
}

    서버 주소와 Cloud Auto-join 구성을 함께 사용할 수 있어요. 서버 주소와 Cloud Auto-join 구성을 모두 포함하는 혼합 구성:

    server_join {
  retry_join = [ "1.1.1.1", "provider=aws tag_key=..." ]
}

    예상되는 서버 주소 형식에 대한 자세한 내용은 서버 주소 형식, 예상되는 Cloud Auto-join 형식에 대해서는 Cloud Auto-join을 참고해요.

  • retry_interval (string: "30s") — 재시도 조인 시도 사이에 기다리는 시간을 지정해요.

  • retry_max (int: 0) — 반환 코드 1로 종료하기 전에 수행할 최대 조인 시도 횟수를 지정해요. 기본적으로 0으로 설정되며, 이는 무한 재시도로 해석돼요.

  • start_join (array<string>: []) — 시작 시 조인할 서버 주소 목록을 지정해요. Nomad가 지정된 주소 중 어느 것과도 조인할 수 없으면 에이전트 시작이 실패해요. 문자열 형식에 대한 자세한 내용은 서버 주소 형식 섹션을 참고해요. 이 필드는 Nomad 서버에만 정의되며, 클라이언트 구성에 포함하면 구성 파싱 오류가 발생해요.

서버 주소 형식 (Server Address Format)

이 섹션은 Nomad 서버의 위치를 설명하는 데 허용되는 구문과 형식을 설명해요. IP 주소로 직접 참조하거나 DNS로 해석하는 등 Nomad 서버를 참조하는 방법은 여러 가지가 있어요.

IP 주소로 직접 (Directly via IP Address)

다른 Nomad 서버를 IP 주소로 지정할 수 있어요. 이는 ip:port 형식으로 수행돼요. 예:

1.2.3.4:5678

IP 주소가 IPv6 주소라면 대괄호로 둘러싼 URL 형식이어야 해요. 예:

[2001:db8::1]:5678

포트 옵션을 생략하면 기본값은 Serf 포트(다르게 구성하지 않는 한 4648)예요:

1.2.3.4 => 1.2.3.4:4648

도메인 또는 DNS로 (Via Domains or DNS)

다른 Nomad 서버를 DNS 주소로 지정할 수 있어요. 이는 address:port 형식으로 수행돼요. 예:

nomad-01.company.local:5678

포트 옵션을 생략하면 기본값은 Serf 포트(다르게 구성하지 않는 한 4648)예요:

nomad-01.company.local => nomad-01.company.local:4648

go-discover 인터페이스로 (Via the go-discover interface)

retry_join은 클라우드 제공자 메타데이터를 사용해 자동화된 클러스터 조인을 수행하기 위해 go-discover 라이브러리를 사용하는 통합 인터페이스를 허용해요. 자세한 내용은 Cloud Auto-join을 참고해요.

"provider=aws tag_key=..." => 1.2.3.4:4648

Cloud Auto-join

retry_join의 Cloud Auto-join을 사용하면 Nomad가 클라우드 제공자 메타데이터를 사용해 클러스터 서버 주소를 자동으로 발견할 수 있어요. Cloud Auto-join은 go-discover와 go-netaddrs 형식을 모두 허용해요.

provider= 접두사가 붙은 구성은 go-discover를 사용하고, exec= 접두사가 붙은 구성은 go-netaddrs를 사용해요. go-discover가 지원하지 않는 클라우드 제공자의 경우 go-netaddrs를 사용해요.

go-discover 구성 (go-discover Configurations)

go-discover 구성은 provider= 접두사로 시작해요.

다음 섹션들은 지원되는 클라우드 제공자의 일부에 특정한 Cloud Auto-join retry_join 옵션을 설명해요. 모든 제공자에 대한 정보는 go-discover의 추가 문서를 참고해요.

Amazon EC2

이것은 주어진 리전에서 주어진 tag_key와 tag_value를 가진 모든 서버의 첫 번째 개인 IP 주소를 반환해요.

{
  "retry_join": ["provider=aws tag_key=... tag_value=..."]
}
  • provider (필수) — 제공자의 이름 (여기서는 "aws").
  • tag_key (필수) — 자동 조인할 태그의 키.
  • tag_value (필수) — 자동 조인할 태그의 값.
  • region (선택) — 인증할 AWS 리전.
  • addr_type (선택) — 발견할 주소의 유형: private_v4, public_v4, public_v6. 기본값은 private_v4예요. (>= 1.0)
  • access_key_id (선택) — 인증용 AWS 액세스 키. 아래의 Authentication and Precedence 섹션을 참고해요.
  • secret_access_key (선택) — 인증용 AWS 시크릿 액세스 키. 아래의 Authentication and Precedence 섹션을 참고해요.
인증 및 우선순위 (Authentication and Precedence)
  • 정적 자격 증명 access_key_id=... secret_access_key=...
  • 환경 변수 (AWS_ACCESS_KEY_ID와 AWS_SECRET_ACCESS_KEY)
  • 공유 자격 증명 파일 (~/.aws/credentials 또는 AWS_SHARED_CREDENTIALS_FILE이 지정한 경로)
  • ECS 태스크 역할 메타데이터 (컨테이너 특정).
  • EC2 인스턴스 역할 메타데이터. 유일하게 필요한 IAM 권한은 ec2:DescribeInstances이며, 자동 조인에만 사용되는 전용 키를 만드는 것을 권장해요. 리전을 생략하면 로컬 인스턴스의 EC2 메타데이터 엔드포인트를 통해 발견돼요.
Microsoft Azure

이것은 주어진 테넌트와 구독에서 주어진 tag_key와 tag_value를 가진 모든 서버의 첫 번째 개인 IP 주소를 반환하거나, Virtual Machine Scale Sets의 vm_scale_set의 주어진 resource_group에서 그렇게 해요. 태그를 사용한다면 tag_key와 tag_value는 가상 머신 리소스 자체가 아니라 서버에 연결된 네트워크 인터페이스 리소스에 설정되어야 해요.

{
  "retry_join": [
    "provider=azure tag_name=... tag_value=... tenant_id=... client_id=... subscription_id=... secret_access_key=..."
  ]
}
  • provider (필수) — 제공자의 이름 (여기서는 "azure").
  • tenant_id (필수) — 머신을 조인할 테넌트.
  • client_id (필수) — 인증할 클라이언트.
  • subscription_id (필수) — Azure 구독 ID.
  • secret_access_key (필수) — 시크릿 클라이언트 키.

태그를 사용할 때 다음 구성 매개변수를 사용해요:

  • tag_name — 자동 조인할 태그의 이름.
  • tag_value — 자동 조인할 태그의 값.

Virtual Machine Scale Sets을 사용할 때 다음 구성 매개변수를 사용해요 (Consul 1.0.3 이상):

  • resource_group — 필터링할 리소스 그룹의 이름.
  • vm_scale_set — 필터링할 가상 머신 스케일 세트의 이름.

태그를 사용할 때 유일하게 필요한 권한은 NetworkInterfaces의 ListAll 메서드예요. Virtual Machine Scale Sets을 사용할 때 유일하게 필요한 역할 동작은 Microsoft.Compute/virtualMachineScaleSets/*/read예요.

참고 — Nomad 클러스터가 Azure에서 호스팅되는 경우 Nomad는 환경 변수, 공유 클라이언트 ID·시크릿 대신 Managed Service Identities (MSI)를 사용해 Azure에 접근할 수 있어요. MSI는 Nomad를 호스팅하는 VM 또는 Virtual Machine Scale Sets에서 활성화되어야 해요. MSI는 Azure 자격 증명이 Nomad 구성에 저장되지 않도록 하므로 선호되는 구성이에요. MSI를 사용할 때는 Virtual machines에 대해 tag_name, tag_value, subscription_id를 제공해야 해요. VM이 MSI 권한을 감지하는 데 Azure가 걸리는 시간은 1분에서 1시간 사이일 수 있다는 점을 유의하세요.

Google Compute Engine

이것은 주어진 프로젝트에서 주어진 tag_value를 가진 모든 서버의 첫 번째 개인 IP 주소를 반환해요.

{
  "retry_join": ["provider=gce project_name=... tag_value=..."]
}
  • provider (필수) — 제공자의 이름 (여기서는 "gce").
  • tag_value (필수) — 자동 조인할 태그의 값.
  • project_name (선택) — 자동 조인할 프로젝트의 이름. 설정하지 않으면 발견돼요.
  • zone_pattern (선택) — RE2 호환 정규 표현식으로 존 목록을 제한할 수 있어요. 생략하면 모든 존의 서버가 반환돼요.
  • credentials_file (선택) — 인증용 자격 증명 파일. 자세한 내용은 아래의 Authentication and Precedence 섹션을 참고해요.
인증 및 우선순위 (Authentication and Precedence)
  • 제공되면 credentials_file의 자격 증명을 사용해요.
  • GOOGLE_APPLICATION_CREDENTIALS 환경 변수의 JSON 파일을 사용해요.
  • gcloud 커맨드라인 도구가 알 수 있는 위치의 JSON 파일을 사용해요.
    • Windows에서는 %APPDATA%/gcloud/application_default_credentials.json.
    • 다른 시스템에서는 $HOME/.config/gcloud/application_default_credentials.json.
  • Google Compute Engine에서는 메타데이터 서버의 자격 증명을 사용해요. 이 마지막 경우에는 제공된 범위가 모두 무시돼요.

발견(discovery)에는 GCE 서비스 계정이 필요해요. 자격 증명은 우선순위에 따라 다음 경로로 검색돼요.

go-netaddrs 구성 (go-netaddrs Configurations)

go-netaddrs 구성은 exec= 접두사로 시작해요.

exec= 접두사 뒤에는 실행 가능한 프로그램과 그 인자가 올 수 있어요. go-netaddrs가 실행하는 명령은 공백으로 구분된 IPv4 또는 IPv6 주소 목록을 반환하고, 성공 시 코드 0으로, 실패 시 0이 아닌 코드로 종료해야 해요.

실행 파일을 절대 파일시스템 경로로 참조하거나, 실행 파일의 이름이 Nomad 에이전트의 PATH에서 찾을 수 있다면 그 이름으로 참조할 수 있어요. 조회 동작에 대한 자세한 내용은 "Refer to executables in the current directory"를 참고해요.

go-netaddrs 구성 예시:

server_join {
  retry_join = [ "exec=hcloud server list -o noheader -o columns=ipv4 -l nomad-server=true | tr '\n' ' '" ]
}

여기서 hcloud의 줄바꿈으로 구분된 출력이 출력을 tr로 파이프하여 공백으로 구분된 형태로 재포맷됐어요.

go-netaddrs 실행 파일 예시의 출력:

"1.1.1.1 2.2.2.2"

go-netaddrs 구성에 대한 자세한 내용은 go-netaddrs를 방문해요.

더 알아보기 (Learn more)