vault 구성 블록

vault 구성 블록 (Vault Configuration Block)

이 페이지는 Nomad 에이전트 구성의 vault 블록에서 Nomad 서버·클라이언트와 HashiCorp Vault의 통합을 구성하는 방법에 대한 참조 정보를 제공해요. 클러스터 이름과 토큰 생성용 역할을 구성해요. Nomad 클라이언트의 경우 Vault 주소, 네임스페이스, 인증서 또는 TLS 인증을 구성해요. JWT 인증 경로를 지정해요. Nomad 서버의 경우 서버의 기본 워크로드 아이덴티티를 구성하는데, 여기에는 워크로드 아이덴티티 수신자, 워크로드 TTL, 추가 아이덴티티 클레임의 키-값 쌍이 포함돼요.

출처: 문서

본문

구성되면 작업 태스크는 워크로드 아이덴티티를 사용해 Vault ACL 토큰을 자동으로 받을 수 있어요.

Vault 통합에 대한 자세한 내용은 Nomad and Vault Integration 페이지를 참고해요.

vault {
  enabled = true

  default_identity {
    aud = ["vault.io"]
    ttl = "1h"

    extra_claims {
      unique_id = "${job.region}:${job.namespace}:${job.id}"
    }
  }
}

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

vault 매개변수 (Parameters)

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

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

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

name (string: "default") — Enterprise — 작업 제출자가 작업 스펙의 vault.cluster 필드에서 참조할 수 있도록 클러스터의 이름을 지정해요. Nomad Community Edition에서는 "default" 클러스터만 사용되므로 이 필드는 생략해야 해요.
enabled (bool: false) — Vault 통합을 활성화할지 여부를 지정해요.

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

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

namespace (string: "") — Vault 통합이 사용하는 Vault 네임스페이스를 지정해요. 비어 있지 않으면 이 네임스페이스가 모든 Vault API 호출에 사용돼요.
address (string: "https://vault.service.consul:8200") — Vault 서버의 주소를 지정해요. 프로토콜과 호스트/IP, 포트를 protocol://host:port 형식으로 포함해야 해요. Vault 설치가 로드 밸런서 뒤에 있다면 로드 밸런서의 주소여야 해요.
jwt_auth_backend_path (string: "jwt-nomad") — 워크로드 아이덴티티 JWT로 로그인하는 데 사용할 JWT 인증 방법의 마운트 경로를 지정해요.
ca_file (string: "") — Vault 통신에 사용되는 CA 인증서의 선택적 경로를 지정해요. 지정하지 않으면 OS와 버전에 따라 달라지는 기본 시스템 CA 번들로 폴백해요.
ca_path (string: "") — Vault 통신에 사용될 CA 인증서를 담은 폴더의 선택적 경로를 지정해요. 지정하지 않으면 기본 시스템 CA 번들로 폴백해요.
cert_file (string: "") — Vault 통신에 사용되는 인증서의 경로를 지정해요. Vault에서 tls_require_and_verify_client_cert가 활성화된 경우 설정해야 해요.
create_from_role (string: "") — 토큰을 생성할 역할을 지정해요. 이 필드는 작업이 vault.role 값을 정의하지 않을 때 태스크 토큰을 파생하는 데 사용되는 역할을 정의해요. 비어 있으면 기본 Vault 클러스터 역할이 사용돼요.
key_file (string: "") — Vault 통신에 사용되는 개인 키의 경로를 지정해요. 이 값을 설정하면 cert_file도 함께 설정해야 해요. Vault에서 tls_require_and_verify_client_cert가 활성화된 경우 설정해야 해요.
tls_server_name (string: "") — TLS로 Vault에 연결할 때 SNI 호스트를 설정하는 데 사용할 선택적 문자열을 지정해요.
tls_skip_verify (bool: false) — SSL 피어 검증을 강제할지 여부를 지정해요. SSL 검증을 비활성화하는 것은 강력히 권장되지 않아요. 대신 커스텀 CA 번들을 설치하고 그에 대해 검증해야 해요. SSL 검증을 비활성화하면 공격자가 클러스터를 쉽게 손상시킬 수 있어요.

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

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

default_identity (Identity: nil) — vault 블록을 가진 태스크가 vault_<name>이라는 이름의 identity 블록을 지정하지 않을 때 사용할 기본 워크로드 아이덴티티 구성을 지정해요. 여기서 <name>은 이 vault 블록 name 매개변수의 값과 일치해요. 기본 아이덴티티를 설정하면 allow_unauthenticated의 값이 무시돼요.

default_identity 매개변수 (Parameters)

aud (array<string>: []) — 이 워크로드 아이덴티티의 유효 수신자 목록이에요. 이 값은 Vault JWT 인증 방법의 bound_audiences 구성과 일치해야 해요. 아이덴티티가 사용될 수 있는 위치를 최소화하기 위해 정확히 하나의 오디언스만 제공하는 것을 권장해요.
env (bool: false) — true이면 워크로드 아이덴티티를 태스크의 NOMAD_TOKEN_vault 환경 변수에서 사용할 수 있어요.
file (bool: false) — true이면 워크로드 아이덴티티를 태스크 파일시스템의 secrets/nomad_vault.jwt 경로에서 사용할 수 있어요. task.user 매개변수가 설정되면 토큰 파일은 해당 사용자만 읽을 수 있어요. 그렇지 않으면 파일은 모든 사람이 읽을 수 있지만 부모 디렉터리 권한으로 보호돼요.
ttl (string: "") — 워크로드 아이덴티티가 만료되기 전에 유효한 것으로 간주되는 기간을 지정해요.
extra_claims (map[string]string: optional) — 워크로드에 대한 추가 아이덴티티 클레임으로 제공될 키-값 쌍 집합이에요. Vault 역할 구성에서 키를 사용자 클레임으로 사용할 수 있어요. 값은 보간(interpolate)돼요. 예를 들어 unique_id = "${job.region}:${job.namespace}:${job.id}"라는 추가 클레임을 포함하면 user claim 필드를 /extra_claims/unique_id로 설정해 해당 식별자를 엔티티 별칭에 매핑할 수 있어요. 보간에 사용 가능한 속성은 다음과 같아요.
- ${job.region} — 작업이 실행 중인 리전.
- ${job.namespace} — 작업의 네임스페이스.
- ${job.id} — 작업의 ID.
- ${job.node_pool} — 할당이 실행 중인 노드 풀.
- ${job.meta.<key>} — 주어진 <key>의 작업 메타데이터 값.
- ${group.name} — Vault를 사용하는 태스크의 태스크 그룹 이름.
- ${alloc.id} — 할당의 ID.
- ${task.name} — Vault를 사용하는 태스크의 이름.
- ${node.id} — 할당이 실행 중인 노드의 ID.
- ${node.datacenter} — 할당이 실행 중인 노드의 데이터센터.
- ${node.pool} — 할당이 실행 중인 노드의 노드 풀.
- ${node.class} — 할당이 실행 중인 노드의 클래스.
- ${vault.cluster} — Vault 클러스터 이름.
- ${vault.namespace} — Vault 네임스페이스.
- ${vault.role} — Vault 역할.

vault 예시 (Examples)

다음 예시는 vault 블록만 보여줘요. vault 블록은 위에 나열된 배치 위치에서만 유효하다는 점을 기억하세요.

Nomad 서버 (Nomad Server)

이 예시는 워크로드 아이덴티티 인증 흐름을 사용하는 Nomad 서버용 Vault 구성을 보여줘요.

server {
  enabled = true
  # ...
}

vault {
  enabled = true

  # Provide a default workload identity configuration so jobs don't need to
  # specify one.
  default_identity {
    aud  = ["vault.io"]
    env  = false
    file = true
    ttl  = "1h"
  }
}

Nomad 클라이언트 (Nomad Client)

이 예시는 Nomad 클라이언트용 Vault 구성을 보여줘요.

client {
  enabled = true
  # ...
}

vault {
  enabled   = true
  address   = "https://vault.service.consul:8200"
  ca_path   = "/etc/certs/ca"
  cert_file = "/var/certs/vault.crt"
  key_file  = "/var/certs/vault.key"
}

vault 구성 리로드 (vault Configuration Reloads)

Vault 구성은 서버에서 리로드할 수 있어요. 이는 서버를 재시작하지 않고 새 토큰을 서버에 제공해야 할 때 유용할 수 있어요. 프로세스에 SIGHUP 신호를 보내 리로드를 수행할 수 있어요.

vault 구성 블록