`kv` — KV 시크릿 엔진 하위 명령어 모음

vault kv는 Vault의 키/값(key/value) 시크릿 엔진과 상호작용하기 위한 하위 명령어(subcommand)들을 그룹으로 묶은 명령어예요. KV 버전 1과 KV 버전 2를 모두 다뤄요.

출처: 문서

본문

문법 (Syntax)

하위 명령어의 옵션 플래그는 하위 명령어 뒤, 인자 앞에 붙여요.

시크릿 엔진이 마운트된 경로는 -mount 플래그로 지정할 수 있어요. 예: vault kv get -mount=secret creds.

예전 방식의 경로 문법(vault kv get secret/creds)도 쓸 수는 있지만, KV v2에서는 피하는 게 좋아요. 실제로는 그것이 시크릿의 완전한 API 경로(secret/data/foo)가 아니라서 혼란을 일으킬 수 있거든요.

정의되지 않은 플래그라는 뜻의 -mount 오류가 난다면, 마운트 플래그 문법이 도입되기 이전의 오래된 Vault 버전을 쓰고 있다는 뜻이에요. 최소한 Vault 1.11 이상으로 업그레이드하거나, 마운트 경로를 예전 문법으로만 다루는 이전 버전 문서를 참고하세요.

마운트 플래그 문법 (Mount flag syntax, KV)

모든 kv 명령어는 $ vault kv get -mount=secret password처럼 플래그 문법으로 KV 시크릿 엔진 경로를 가리킬 수도 있어요(예전 방식은 $ vault kv get secret/password). 마운트 플래그 문법은 KV v2 시크릿의 완전한 경로가 정책(policy)이나 원시 API 호출에서 실제로 중첩된 /data/ 요소를 포함한다는 사실(예: secret/data/password) 때문에 생기는 혼란을 줄이기 위해 만들어졌어요. 위처럼 KV v1 스타일의 문법(secret/password)을 쓰면 이 점을 쉽게 놓칠 수 있거든요. 이 혼란을 피하기 위해 모든 KV 문서 페이지는 -mount 플래그를 사용해요.

종료 코드 (Exit codes)

Vault CLI는 달리 문서화되지 않는 한 일관되고 안정적인 동작을 지향해요.

잘못된 플래그, 실패한 검증, 잘못된 인자 개수 같은 로컬 오류는 종료 코드 1을 반환해요.
API 실패, 잘못된 TLS, 잘못된 API 파라미터 같은 원격 오류는 종료 상태 2를 반환해요.
상황에 따라 이 기본값을 무시하는 명령어도 있으며, 그런 명령어들은 이 예외를 문서화해요.

예시 (Examples)

"secret"에 활성화된 KV 버전 2에서 "creds"라는 키를 값 passcode=my-long-passcode로 생성 또는 업데이트해요:

$ vault kv put -mount=secret creds passcode=my-long-passcode
== Secret Path ==
secret/data/creds

======= Metadata =======
Key                Value
---                -----
created_time       2022-06-15T20:14:17.107852Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

이 값을 다시 읽어오면:

$ vault kv get -mount=secret creds
== Secret Path ==
secret/data/creds

======= Metadata =======
Key                Value
---                -----
created_time       2022-06-15T20:14:17.107852Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

====== Data ======
Key         Value
---         -----
passcode    my-long-passcode

"creds" 키의 메타데이터를 가져오려면:

$ vault kv metadata get -mount=secret creds
=== Metadata Path ===
secret/metadata/creds

========== Metadata ==========
Key                     Value
---                     -----
cas_required            false
created_time            2022-06-15T20:14:17.107852Z
current_version         1
custom_metadata         <nil>
delete_version_after    0s
max_versions            0
oldest_version          0
updated_time            2022-06-15T20:14:17.107852Z

====== Version 1 ======
Key              Value
---              -----
created_time     2022-06-15T20:14:17.107852Z
deletion_time    n/a
destroyed        false

"creds" 키의 특정 버전을 가져오려면:

$ vault kv get -mount=secret -version=1 creds
== Secret Path ==
secret/data/creds

======= Metadata =======
Key                Value
---                -----
created_time       2022-06-15T20:14:17.107852Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

====== Data ======
Key         Value
---         -----
passcode    my-long-passcode

사용법 (Usage)

Usage: vault kv <subcommand> [options] [args]

  # ...

Subcommands:
    delete               Deletes versions in the KV store
    destroy              Permanently removes one or more versions in the KV store
    enable-versioning    Turns on versioning for a KV store
    get                  Retrieves data from the KV store
    list                 List data or secrets
    metadata             Interact with Vault's Key-Value storage
    patch                Sets or updates data in the KV store without overwriting
    put                  Sets or updates data in the KV store
    rollback             Rolls back to a previous version of data
    undelete             Undeletes versions in the KV store

하위 명령어에 대한 자세한 정보, 예시, 사용법은 사이드바에서 해당 하위 명령어 이름을 클릭해 확인할 수 있어요.

더 알아보기 (Learn more)

vault kv get — 데이터 조회
vault kv put — 데이터 작성
vault kv metadata — 버전 메타데이터 관리

`kv` — KV 시크릿 엔진 하위 명령어 모음