키/값 v2 플러그인 설정하기

vault secrets enable을 사용해 kv 플러그인의 인스턴스를 활성화해요. 버전 2를 지정하려면 -version 플래그를 사용하거나 플러그인 유형으로 kv-v2를 지정해요.

또한 dev-mode 서버를 실행 중이면 demo/ 경로에서 v2 kv 시크릿 엔진이 기본적으로 활성화돼요(비 dev 서버의 경우 현재 v1이에요). 이 엔진은 비활성화하거나, 이동하거나, 다른 경로에 여러 번 활성화할 수 있어요. KV 시크릿 엔진의 각 인스턴스는 격리되고 고유해요.

시작 전에(Before you start)

ACL 정책을 업데이트할 권한이 있어야 해요.
플러그인을 활성화할 권한이 있어야 해요.

출처: 문서

본문

1단계: 플러그인 활성화하기(Enable the plugin)

vault secrets enable을 사용해 kv 플러그인의 새 인스턴스를 만들고, key/value 버전 2를 지정하려면 -version 플래그를 사용하거나 플러그인 유형으로 kv-v2를 사용해요.

옵션 1: -version 플래그 사용:

$ vault secrets enable -path <mount_path> -version=2 kv

옵션 2: kv-v2 플러그인 유형 사용:

$ vault secrets enable -path <mount_path> kv-v2

API로는 kv v2 인스턴스의 유형과 구성 정보가 담긴 JSON 파일을 만든 뒤 options 필드로 선택적 플래그를 설정하고, JSON 데이터로 /sys/mounts/{plugin_mount_path}에 POST 호출을 해요.

$ curl                                      \
     --request POST                            \
     --header "X-Vault-Token: ${VAULT_TOKEN}"  \
     --data @data.json                         \
     ${VAULT_ADDR}/v1/sys/mounts/<plugin_mount_path>

예를 들어:

{
  "type": "kv",
  "options": {
    "version": "2"
  }
}

$ curl                                        \
    --request POST                            \
    --header "X-Vault-Token: ${VAULT_TOKEN}"  \
    --data @data.json                         \
    ${VAULT_ADDR}/v1/sys/mounts/shared | jq

/sys/mounts/{plugin_mount_path}은 성공 시 데이터를 반환하지 않아요.

2단계: ACL 정책 파일 만들기(Create an ACL policy file)

참고: kv 플러그인의 ACL 정책은 allowed_parameters, denied_parameters, required_parameters 정책 필드를 지원하지 않아요.

필요에 따라 정책 정의 파일을 만들어요. 예를 들어 shared/에 마운트된 kv 플러그인의 /dev/square-api 경로에 API 키가 저장돼 있다고 가정해요. 다음 정책은 클라이언트가 최신 버전의 API 키를 읽고 패치하며, API 키의 모든 버전 메타데이터를 읽을 수 있게 해요.

# 최신 버전의 API 키를 읽고 패치할 권한 부여
path "shared/data/dev/square-api/*" {
  capabilities = ["read", "patch"]
}

# 모든 버전의 API 키 메타데이터를 읽을 권한 부여
path "shared/metadata/dev/square-api/" {
  capabilities = ["read"]
}

사용 가능한 경로 접두사(Available path prefixes)

경로 접두사	정책 효과
data	최신 버전의 데이터에 권한 적용.
undelete	클라이언트가 모든 버전의 데이터에 un-delete 명령/엔드포인트 사용 가능.
destroy	클라이언트가 모든 버전의 데이터에 destroy 명령/엔드포인트 사용 가능.
metadata	클라이언트가 모든 버전의 데이터에 metadata 명령/엔드포인트 사용 가능.

사용 가능한 권한(Available permissions)

권한	HTTP 작업	결과
create	POST/PUT	클라이언트가 경로에 새 데이터 작성 가능.
delete	DELETE	클라이언트가 경로에서 데이터 제거 가능.
deny	N/A	클라이언트가 경로에 접근할 수 없음. `deny`는 다른 모든 권한(수퍼유저 `sudo` 포함)보다 우선.
list	LIST	클라이언트가 경로의 데이터 나열 가능. 모든 플러그인이 `list`를 지원하진 않음.
patch	PATCH	클라이언트가 기존 경로의 명시적 키/값 쌍을 업데이트하거나 작성 가능.
read	GET	클라이언트가 경로에서 데이터 읽기 가능.
subscribe	N/A	클라이언트가 경로에서 플러그인의 이벤트 스트림 접근을 요청할 수 있음. 모든 플러그인이 `subscribe`를 지원하진 않음.
sudo	N/A	클라이언트가 관련 권한 동사와 함께 루트 보호 경로에 접근 가능.
update	POST/PUT	클라이언트가 기존 경로의 데이터를 완전히 덮어쓸 수 있음.

경고: list 작업에 반환된 데이터는 ACL 정책에 대해 필터링되지 않아요. 키 이름에 민감한 정보를 인코딩하지 마세요.

필요한 권한이 확실하지 않으면 Vault CLI로 기존 kv 플러그인을 대상으로 -output-policy 플래그와 함께 예시 데이터로 명령을 실행해 최소 정책을 생성해요.

$ vault kv patch      \
    -output-policy    \
    -mount private    \
    test-path         \
    test=test

path "private/data/test-path" {
  capabilities = ["patch"]
}

3단계: ACL 정책 저장하기(Save the ACL policy)

정책 정의 파일로 vault policy write을 사용해 새 ACL 정책을 만들어요.

$ vault policy write <name> <path_to_policy_file>

예를 들어:

$ vault policy write "KV-access-policy" ./kv-policy.hcl

팁: Vault API로 정책을 수정할 예정이라면 정책 이름에 공백과 특수 문자를 피하세요. 정책 이름이 API 엔드포인트 경로의 일부가 되거든요.

정책 파일을 이스케이프하고 정책 세부 정보로 /sys/policy/{policy_name}에 POST 호출을 해요.

$ jq -Rs '{ "policy": . | gsub("[\\r\\n\\t]"; "") }' <path_to_policy_file> |
  curl                                        \
    --request POST                            \
    --header "X-Vault-Token: ${VAULT_TOKEN}"  \
    "$(</dev/stdin)"                          \
    ${VAULT_ADDR}/v1/sys/policy/<policy_name>

다음 단계(Next steps)

플러그인에 대한 인증 매핑 만들기

더 알아보기 (Learn more)

KV v2 시크릿 엔진 개요와 쿡북 예시를 살펴보세요.
KV v2 API 문서에서 마운트·정책 관련 엔드포인트를 확인해 보세요.