Vault 구성 파라미터

개발 모드(development mode)를 제외하면 Vault 서버는 설정 파일을 통해 구성됩니다. 이 파일의 형식은 HCL 또는 JSON입니다.

출처: 문서

본문

Vault 프로세스가 Vault를 실행하는 사용자가 구성 디렉터리와 관련 파일을 소유하고 접근할 수 있는지 자동으로 확인하려면 환경 변수 VAULT_ENABLE_FILE_PERMISSIONS_CHECK를 설정하세요. 파일 권한 검사는 다른 그룹이나 사용자에게 구성 디렉터리나 파일에 대한 쓰기·실행 권한이 없는지도 함께 확인합니다.

플러그인 디렉터리와 플러그인 바이너리에 사용자나 권한이 Vault 프로세스와 달라야 한다면, Vault 구성에서 plugin_file_uid와 plugin_file_permissions 파라미터로 명시적인 사용자와 권한을 지정할 수 있습니다. Vault는 기본적으로 파일 권한을 확인하지 않습니다.

예시 구성은 다음과 같습니다.

참고 멀티 노드 클러스터라면 각 Vault 노드의 루프백 주소(loopback address) 대신 유효하고 라우팅 가능한 IP 주소를 사용하세요. 전체 시나리오는 Vault HA clustering with integrated storage 튜토리얼을 참고하세요.

ui            = true
cluster_addr  = "https://127.0.0.1:8201"
api_addr      = "https://127.0.0.1:8200"
disable_mlock = true

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_id"
}

listener "tcp" {
  address       = "127.0.0.1:8200"
  tls_cert_file = "/path/to/full-chain.pem"
  tls_key_file  = "/path/to/private-key.pem"
}

telemetry {
  statsite_address = "127.0.0.1:8125"
  disable_hostname = true
}

구성이 작성된 후에는 vault server 명령에 -config 플래그를 사용해 구성 위치를 지정합니다.

파라미터

storage ([StorageBackend][storage-backend]: <required>) – Vault 데이터가 저장되는 storage backend를 구성합니다. 사용 가능한 전체 storage backend 목록은 storage backends 문서를 참고하세요. Vault를 HA 모드로 실행하려면 backend가 조정(coordination) 시맨틱을 지원해야 합니다. backend가 HA 조정을 지원한다면 이 파라미터 블록 안에 HA backend 옵션도 지정할 수 있습니다. 지원하지 않는다면 HA를 지원하는 backend로 별도의 ha_storage 파라미터를 구성하고, 그에 맞는 HA 옵션도 함께 지정해야 합니다.
ha_storage ([StorageBackend][storage-backend]: nil) – Vault HA 조정이 일어날 storage backend를 구성합니다. HA를 지원하는 backend여야 합니다. 설정하지 않으면 storage 파라미터에 지정한 backend에서 HA를 시도합니다. storage backend가 HA 조정을 지원하고, storage 파라미터에 HA 전용 옵션이 이미 지정되어 있다면 이 파라미터는 필요하지 않습니다. (사용 예시는 Use Integrated Storage for HA Coordination을 참고하세요.)
listener ([Listener][listener]: <required>) – Vault가 API 요청을 수신하는 방식을 구성합니다.
user_lockout ([UserLockout][user-lockout]: nil) – 로그인 실패 시 사용자 잠금(user-lockout) 동작을 구성합니다. 자세한 내용은 user lockout configuration 문서를 참고하세요.
seal ([Seal][seal]: nil) – 자동 봉인 해제(auto-unsealing)에 사용할 seal 유형과, 데이터 보호의 추가 계층인 seal wrapping을 구성합니다.
reporting ([Reporting][reporting]: nil) – Vault의 라이선스 보고(license reporting) 관련 옵션을 구성합니다.
cluster_name (string: <generated>) – Vault 클러스터의 사람이 읽을 수 있는 식별자를 지정합니다. 생략하면 Vault가 값을 생성합니다. 클러스터 이름은 일부 텔레메트리 메트릭의 라벨로 포함됩니다. 기존 Vault 클러스터에서 클러스터 이름을 갱신해도 안전합니다.
cache_size (string: "131072") – 물리 스토리지 하위 시스템이 사용하는 읽기 캐시의 크기를 지정합니다. 값은 항목 수이므로 전체 캐시 크기는 저장된 항목의 크기에 따라 달라집니다.
disable_cache (bool: false) – 물리 스토리지 하위 시스템이 사용하는 읽기 캐시를 포함해 Vault 내부의 모든 캐시를 비활성화합니다. 성능에 매우 큰 영향을 미칩니다.
disable_mlock (bool: <required>) – Vault가 mlock syscall을 실행하지 못하도록 합니다. mlock은 데이터가 메모리에서 디스크로 스왑되는 것을 막아줍니다. integrated storage를 사용한다면 disable_mlock에 명시적인 값을 반드시 설정해야 합니다. integrated storage를 사용하지 않는 배포에서 mlock을 비활성화하는 것은 권장하지 않습니다.

아래에 설명된 추가 보안 예방 조치를 따르면서 mlock을 비활성화하세요. 이 값은 환경 변수 VAULT_DISABLE_MLOCK으로도 제공할 수 있습니다.

Vault를 실행하는 시스템이 암호화된 스왑만 사용하거나 스왑을 전혀 사용하지 않는 경우가 아니라면 mlock 비활성화는 권장되지 않습니다. Vault는 mlock() syscall을 지원하는 UNIX 계열 시스템(Linux, FreeBSD 등)에서만 메모리 잠금을 지원합니다. 비 UNIX 계열 시스템(예: Windows, NaCL, Android)은 프로세스의 전체 메모리 주소 공간이 디스크로 유출되지 않게 하는 프리미티브가 없으므로, 지원되지 않는 플랫폼에서는 자동으로 비활성화됩니다.

integrated storage를 사용한다면 mlock 비활성화를 적극 권장합니다. 그 이유는 mlock이 Raft가 상태를 추적하는 데 사용하는 BoltDB가 만드는 메모리 매핑 파일과 잘 맞지 않기 때문입니다. mlock을 사용하면 메모리 매핑 파일이 상주 메모리에 로드되어 Vault의 전체 데이터셋이 메모리로 로드되고, 데이터가 사용 가능한 RAM보다 커지면 메모리 부족 문제가 발생합니다. 이 경우 BoltDB 내부의 데이터는 저장 시 암호화된 상태로 유지되지만, Vault의 다른 인메모리 민감 데이터가 디스크로 덤프되지 않도록 스왑을 비활성화해야 합니다.

mlock을 활성화하면 Vault 실행 파일과 플러그인 디렉터리의 각 플러그인 실행 파일이 mlock syscall을 사용할 수 있어야 합니다.

Linux에서 Vault 실행 파일을 root로 실행하지 않고 mlock syscall을 사용할 수 있게 하려면 다음을 실행하세요:
```
sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault))
```
참고 각 플러그인은 별도 프로세스로 실행되므로 플러그인 디렉터리의 각 플러그인에 대해서도 동일한 작업을 해야 합니다.

최신 systemd를 사용하는 Linux 배포판이라면 "[Service]" 구성 섹션에 다음 지시문을 추가할 수 있습니다:
```
LimitMEMLOCK=infinity
```
plugin_directory (string: "") – 플러그인 로드를 허용하는 디렉터리입니다. 플러그인을 성공적으로 로드하려면 Vault가 이 디렉터리의 파일을 읽을 권한이 있어야 하며, 값은 심볼릭 링크일 수 없습니다. 환경 변수 VAULT_ENABLE_FILE_PERMISSIONS_CHECK를 설정하면 Vault 프로세스가 Vault를 실행하는 사용자가 구성 디렉터리와 관련 파일을 소유하고 접근할 수 있는지 자동으로 확인합니다. 파일 권한 검사는 다른 그룹이나 사용자가 구성 디렉터리나 파일에 대해 쓰기·실행 권한을 갖지 않는지도 확인합니다. 플러그인 디렉터리와 플러그인 바이너리에 Vault 프로세스와 다른 사용자나 권한을 지정해야 한다면 plugin_file_uid와 plugin_file_permissions 파라미터로 명시적으로 설정할 수 있습니다. Vault는 기본적으로 파일 권한을 확인하지 않습니다.
plugin_file_uid (integer: 0) – 플러그인 디렉터리와 플러그인 바이너리를 Vault를 실행하는 사용자가 아닌 다른 사용자가 소유할 때의 UID입니다. 환경 변수 VAULT_ENABLE_FILE_PERMISSIONS_CHECK로 파일 권한 검사를 활성화한 경우에만 설정하면 됩니다.
plugin_file_permissions (string: "") – 그룹이나 기타 사용자에게 쓰기 또는 실행 권한이 있을 때 플러그인 디렉터리와 플러그인 바이너리의 8진수(octal) 권한 문자열입니다. 파일 권한 검사를 활성화한 경우에만 설정하면 됩니다.
plugin_tmpdir (string: "") – 컨테이너화된 외부 플러그인을 시작할 때 Vault가 임시 파일에 사용하는 디렉터리입니다. Vault는 컨테이너화되지 않은 플러그인에는 plugin_tmpdir을 사용하지 않습니다. 기본 OS 임시 디렉터리가 Vault와 플러그인 컨테이너 간에 공유되지 않을 때 두 곳 모두에서 접근 가능한 경로로 plugin_tmpdir을 설정하세요. 환경 변수 VAULT_PLUGIN_TMPDIR로도 디렉터리를 구성할 수 있습니다.
telemetry ([Telemetry][telemetry]: <none>) – 텔레메트리 보고 시스템을 지정합니다.
default_lease_ttl (string: "768h") – 토큰과 시크릿의 기본 임대(lease) 기간을 지정합니다. "30s"나 "1h" 같은 라벨 접미사로 지정합니다. 이 값은 max_lease_ttl보다 커질 수 없습니다.
max_lease_ttl (string: "768h") – 토큰과 시크릿의 가능한 최대 임대 기간을 지정합니다. "30s"나 "1h" 같은 라벨 접미사로 지정합니다. 개별 마운트는 auth 또는 secret 명령의 max-lease-ttl 플래그로 마운트를 튜닝해 이 값을 재정의할 수 있습니다.
default_max_request_duration (string: "90s") – Vault가 요청을 취소하기 전에 허용되는 기본 최대 요청 시간을 지정합니다. 이 값은 각 리스너에서 max_request_duration 값으로 재정의할 수 있습니다.
detect_deadlocks (string: "") – Vault가 잠재적 교착 상태(deadlock)를 모니터링할 내부 뮤텍스 잠금을 나타내는 쉼표로 구분된 문자열입니다. 코어 상태 잠금 시도가 교착 상태로 보이면 Vault는 구성된 값에 대해 POTENTIAL DEADLOCK: 경고를 기록합니다. detect_deadlocks를 활성화하면 각 잠금 시도를 추적하므로 성능에 부정적인 영향을 줄 수 있습니다. 현재 지원되는 값은 다음과 같습니다:
- statelock
- quotas
- expiration
- sealwrap
raw_storage_endpoint (bool: false) – 보안 배리어(security barrier)를 통해 원시 데이터를 암호화/복호화할 수 있는 sys/raw 엔드포인트를 활성화합니다. 매우 높은 권한이 필요한 엔드포인트입니다.
introspection_endpoint (bool: false) – root 토큰이나 sudo 권한이 있는 사용자가 Vault 내부의 특정 하위 시스템을 검사할 수 있게 해주는 sys/internal/inspect 엔드포인트를 활성화합니다.
ui (bool: false) – 모든 리스너(address + port)의 /ui 경로에서 제공되는 내장 웹 UI를 활성화합니다. 표준 Vault API 주소에 접근하는 브라우저는 자동으로 리다이렉트됩니다. 이 값은 환경 변수 VAULT_UI로도 제공할 수 있습니다. 자세한 내용은 ui configuration 문서를 참고하세요.
pid_file (string: "") – Vault 서버의 프로세스 ID(PID)를 저장할 파일 경로입니다.
enable_response_header_hostname (bool: false) – Vault의 모든 HTTP 응답에 HTTP 헤더 X-Vault-Hostname을 추가합니다. 이 헤더는 HTTP 요청을 처리한 Vault 노드의 호스트 이름을 포함합니다. 이 정보는 best-effort이며 항상 존재한다고 보장되지 않습니다. 이 옵션을 활성화했는데 응답에 X-Vault-Hostname 헤더가 없다면 운영 체제에서 호스트 이름을 가져오는 데 오류가 발생한 것입니다.
enable_response_header_raft_node_id (bool: false) – Vault의 모든 HTTP 응답에 HTTP 헤더 X-Vault-Raft-Node-ID를 추가합니다. Vault가 Raft 클러스터(즉 integrated storage 사용)에 참여 중이라면 이 헤더는 요청을 처리한 Vault 노드의 Raft 노드 ID를 포함합니다. Raft 클러스터에 참여하지 않는다면 이 옵션이 활성화되어 있어도 이 헤더는 생략됩니다.
log_level (string: "info") – 로그 상세 수준(verbosity level)입니다. 지원되는 값은 세부 정도가 높은 순서대로 trace, debug, info, warn, error입니다. 환경 변수 VAULT_LOG_LEVEL로도 지정할 수 있습니다.

참고 SIGHUP(sudo kill -s HUP pid of vault) 시 유효한 값이 지정되어 있으면 Vault가 기존 로그 수준을 갱신하며, CLI 플래그와 환경 변수(지정된 경우)를 모두 덮어씁니다.

참고 Vault 로깅의 모든 부분이 이렇게 동적으로 로그 수준을 바꿀 수 있는 것은 아닙니다. 특히 secrets/auth 플러그인은 현재 동적으로 갱신되지 않습니다.
log_format – -log-format 명령줄 플래그와 동일합니다.
log_file – -log-file 명령줄 플래그와 동일합니다.
log_rotate_duration – -log-rotate-duration 명령줄 플래그와 동일합니다.
log_rotate_bytes – -log-rotate-bytes 명령줄 플래그와 동일합니다.
log_rotate_max_files – -log-rotate-max-files 명령줄 플래그와 동일합니다.
experiments (string array: []) – 이 노드에서 활성화할 실험 목록입니다. 실험은 프로덕션에서 사용해서는 안 되며, 관련 API는 릴리스 간에 하위 호환성이 깨지는 변경이 있을 수 있습니다. 추가 실험은 VAULT_EXPERIMENTS 환경 변수(쉼표로 구분된 목록)나 -experiment 플래그로도 지정할 수 있습니다.
imprecise_lease_role_tracking (bool: "false") – 역할 기반 quota가 없으면 역할별 임대 카운팅을 건너뜁니다. imprecise_lease_role_tracking을 true로 설정하고 새 역할 기반 quota를 활성화하면 이후 임대 개수가 0부터 시작합니다. imprecise_lease_role_tracking은 역할 기반 임대 개수 quota에 영향을 주지만, 역할 기반 quota를 사용하지 않을 때는 지연 시간을 줄여줍니다.
enable_post_unseal_trace (bool: false) – 디버그 목적으로 core.postUnseal 함수 실행 중에 서버가 Go trace를 생성하도록 활성화합니다. 생성된 trace는 go tool trace 명령으로 볼 수 있습니다. 출력 디렉터리는 post_unseal_trace_directory 파라미터로 지정할 수 있습니다. 성능에 큰 영향을 줄 수 있으므로 디버깅 목적으로만 일시적으로 활성화해야 합니다. 실행 중인 Vault 프로세스에서 SIGHUP 신호로 갱신할 수 있습니다.
post_unseal_trace_directory (string: "") – trace 파일이 기록될 디렉터리를 지정합니다. 디렉터리는 존재해야 하며 Vault 프로세스가 쓰기 가능해야 합니다. 지정하지 않으면 os.TempDir()(보통 Unix 시스템의 /tmp) 결과 아래에 vault-traces 하위 디렉터리를 만듭니다. 실행 중인 Vault 프로세스에서 SIGHUP 신호로 갱신할 수 있습니다.
disable_goroutine_trace_dump (bool: false) – true로 설정하면 정상 종료(SIGTERM 또는 SIGINT) 중에 Vault가 자동으로 기록하는 goroutine pprof dump를 억제합니다. 실행 중인 Vault 프로세스에서 SIGHUP 신호로 갱신할 수 있습니다. 이 dump는 go tool pprof로 읽을 수 있는 pprof goroutine 프로파일이 포함된 goroutine 파일을 os.TempDir() 안의 무작위 이름 디렉터리(예: Linux의 /tmp/vault-goroutine-dump-2738451092)에 기록합니다. goroutine 파일을 다른 위치로 리다이렉트하려면 VAULT_STACKTRACE_FILE_PATH를 기존 디렉터리 경로로 설정하세요.

참고 Vault 시작 전에 VAULT_STACKTRACE_WRITE_TO_FILE 환경 변수를 비어 있지 않은 값으로 설정하면 SIGUSR2를 Vault 프로세스에 보내 별도의 goroutine dump를 온디맨드로 트리거할 수 있습니다. disable_goroutine_trace_dump 구성 파라미터로는 SIGUSR2 dump에 영향을 줄 수 없습니다.
allow_audit_log_prefixing (bool: false) – 파일 싱크(file sinks)의 audit 로그 항목에 접두사를 허용하려면 활성화합니다.
enable_unauthenticated_access (string array: []) – Vault가 인증되지 않은 것으로 취급하려는 인증된 엔드포인트 패밀리 이름 목록입니다. enable_unauthenticated_access 파라미터는 이전 Vault 버전에서 인증되지 않았던 엔드포인트에 대한 하위 호환성을 제공합니다. 실행 중인 Vault 프로세스에서 SIGHUP 신호로 갱신할 수 있습니다. 지원되는 엔드포인트 패밀리: "rekey", "generate-root", "generate-operation-token".
deny_slash_in_templated_paths (bool: false) – 템플릿화된 정책 경로(templated policy paths)에 슬래시(/)가 포함될 때 Vault가 "permission denied"를 반환할지 제어합니다. 환경 변수 VAULT_DENY_SLASH_IN_TEMPLATED_PATHS로도 설정할 수 있습니다.

고가용성(High availability) 파라미터

다음 파라미터는 고가용성을 지원하는 backend에서 사용됩니다.

api_addr (string: "") – 클라이언트 리다이렉션을 위해 클러스터의 다른 Vault 서버에 알릴 주소(전체 URL)를 지정합니다. 이 값은 플러그인 backend에도 사용됩니다. 환경 변수 VAULT_API_ADDR로도 제공할 수 있습니다. 일반적으로 listener 주소 값을 가리키는 전체 URL로 설정해야 합니다. 런타임에 해석되는 go-sockaddr 템플릿으로 동적으로 정의할 수 있습니다.
cluster_addr (string: "") – 요청 포워딩(request forwarding)을 위해 클러스터의 다른 Vault 서버에 알릴 주소를 지정합니다. 환경 변수 VAULT_CLUSTER_ADDR로도 제공할 수 있습니다. api_addr처럼 전체 URL이지만, Vault는 스킴(scheme)을 무시합니다(모든 클러스터 멤버는 항상 개인 키/인증서로 TLS를 사용합니다). 런타임에 해석되는 go-sockaddr 템플릿으로 동적으로 정의할 수 있습니다.
disable_clustering (bool: false) – 요청 포워딩 같은 클러스터링 기능을 활성화할지 지정합니다. 한 Vault 노드에서 true로 설정하면 그 노드가 active 노드일 때만 이 기능을 비활성화합니다. storage 유형이 raft라면 이 파라미터는 true로 설정할 수 없습니다.

Vault Enterprise 파라미터

다음 파라미터는 Vault Enterprise에서만 사용됩니다.

disable_sealwrap (bool: false) – root 키를 제외한 모든 값에 seal wrapping을 사용하지 않도록 비활성화합니다. 이 값을 토글하면 새 동작은 지연(lazily, 값이 읽히거나 쓰일 때) 적용됩니다.
disable_performance_standby (bool: false) – 이 노드에서 performance standby를 비활성화할지 지정합니다. 한 Vault 노드에서 true로 설정하면 이 노드가 Active 또는 Standby일 때 이 기능을 비활성화합니다. 이 설정은 클러스터의 모든 노드에 동기화하는 것이 좋습니다.
license_path (string: "") – 라이선스 파일 경로입니다. 환경 변수 VAULT_LICENSE_PATH로도 제공할 수 있으며, 라이선스 자체를 환경 변수 VAULT_LICENSE에 제공할 수도 있습니다.
administrative_namespace_path (string: "") – Administrative namespace로 사용할 Vault namespace의 절대 경로를 지정합니다.
remove_irrevocable_lease_after (string: "") – 되돌릴 수 없는(irrevocable) 임대의 자동 삭제를 활성화합니다. 구성된 기간이 되돌릴 수 없는 임대의 만료 시간을 초과하면 Vault가 임대를 삭제합니다. remove_irrevocable_lease_after의 최솟값은 2일(2d)입니다. 최솟값보다 작은 값을 설정하면 Vault는 값을 2d로 덮어씁니다. 임대를 삭제하면 Vault가 외부 리소스를 고아(orphan)로 만들 수 있습니다.

Vault 구성 파라미터