Vault KV v1 vs v2 — 경로 차이
Vault 의 KV Secret Engine 은 v1 과 v2 가 있습니다. 둘이 호환이 안 돼서, 운영 중에 혼동하면 API 경로가 달라 에러가 납니다.
v1과 v2의 차이
| 구분 | KV v1 | KV v2 |
|---|---|---|
| 버전 히스토리 | 없음 | 있음 (최대 N개 보관) |
| 경로 | secret/foo |
secret/data/foo(쓰기), secret/metadata/foo(메타) |
| 삭제 | 즉시 삭제 | soft delete (destroy 로 영구 삭제) |
| CAS | 없음 | Check-And-Set (동시 쓰기 방지) |
v2 가 버전 관리와 soft delete 를 지원합니다. 실수로 지운 시크릿을 되살리거나 이전 버전으로 돌아갈 수 있습니다. 대신 경로 구조가 바뀝니다.
경로에 끼어드는 /data/
가장 헷갈리는 건 경로인데, v2 는 데이터와 메타데이터를 분리하느라 실제 HTTP
경로에 /data/ 가 끼어듭니다.
# KV v1
GET /v1/secret/foo
# KV v2 — 내부적으로 /data/ 삽입
GET /v1/secret/data/foovault kv get secret/foo 로 CLI 를 쓰면 v1 이든 v2 든 알아서 처리해줍니다.
그런데 REST API 를 직접 호출하거나 다른 도구에서 경로를 명시할 때는 이
/data/ 를 직접 신경 써야 합니다.
v1 경로에 v2로 접근하면 404
이게 실무에서 사고로 이어지는데, VaultStaticSecret 같은 걸 쓸 때
type: kv-v2 를 명시해 놓고 정작 그 경로가 v1 으로 마운트돼 있으면 v2 방식으로
/data/ 를 붙여 조회하다 404 가 납니다.
시크릿이 분명히 있는데 “not found” 가 나오면, 값이 없는 게 아니라 엔진 버전이 안 맞아서 엉뚱한 경로를 보는 경우를 의심해야 합니다. 마운트가 v1 인지 v2 인지 먼저 확인하고, 도구 설정의 타입을 거기 맞춥니다.
버전이 섞인 환경이면 어느 경로가 어느 버전인지 정리해두는 게 안전합니다.
같은 secret/ 아래라도 마운트마다 다를 수 있습니다.
댓글 0