# HashiCorp Vault 개발 서버: KV 버전, 읽기 전용 정책

> Vault 개발 서버를 컨테이너로 띄워 KV 저장과 버전, 읽기 전용 정책, 20초짜리 토큰의 만료, 감사 로그에서 값이 해시로 가려지는 것, 재시작하면 데이터가 사라지는 것까지 실행해 확인합니다.

- 주소: https://copyandrun.com/blog/vault-dev-mode-kv-policy/
- 분야: DevSecOps
- 발행일: 2026-10-30
- 태그: Vault, HashiCorp, 비밀값, KV, 정책

비밀번호와 API 키를 코드나 환경 변수에 두지 않으려면 비밀값을 따로 보관하고, 누가 무엇을 읽었는지 남기고, 접근을 짧게 허용하는 서버가 필요합니다. HashiCorp Vault가 그 일을 하는 대표적인 도구입니다. 앞의 [sops와 age 글](/blog/sops-age-encrypted-config/)이 파일에 담긴 비밀을 암호화해 저장소에 두는 방법이었다면, 이 글은 실행 중인 서버에서 비밀을 꺼내 쓰는 방법입니다. 개발 서버(dev mode)를 내 PC의 컨테이너로 띄워서 저장, 버전, 정책, 만료, 감사 로그를 직접 실행해 보고 그 결과를 기록합니다. 개발 서버는 시험용이라 운영에 쓰지 않습니다. 이유도 7번에서 직접 확인합니다.

## 준비물

| 항목 | 확인한 값 |
|---|---|
| Docker | 29.5.3 (Windows 11, Git Bash에서 실행) |
| Vault | 2.2.1 (`hashicorp/vault` 이미지) |
| 실행 방식 | 개발 서버: 메모리 저장(`inmem`), 자동으로 잠금 해제, root 토큰 고정(`root-lab-token`) |
| 파이썬 | 3.12 (토큰 정보와 감사 로그를 읽는 데만 사용) |

모든 명령은 `docker exec`로 컨테이너 안의 `vault` 명령을 실행합니다. 서버 주소는 `http://127.0.0.1:8200`이고, 포트는 바깥에 열지 않았습니다.

## 1. 개발 서버 띄우기

<!-- files: vault_demo.sh -->

```bash
docker run -d --name osk-vault --cap-add IPC_LOCK \
  -e VAULT_DEV_ROOT_TOKEN_ID=root-lab-token \
  -e VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 \
  hashicorp/vault:latest
```

`vault status`로 상태를 보면 `Initialized true`, `Sealed false`, `Storage Type inmem`이 나옵니다. 운영 서버는 처음에 초기화하고 열쇠 조각(unseal key)으로 잠금을 풀어야 하는데, 개발 서버는 이 과정을 자동으로 해 주고 데이터를 메모리에만 둡니다. 편하지만 시험용으로만 씁니다.

## 2. KV v2: 저장, 덮어쓰기, 옛 버전, 삭제와 복구

<!-- files: vault_demo.sh -->

KV 버전 2 저장소는 같은 경로에 쓸 때마다 버전이 올라갑니다.

```bash
vault kv put -mount=secret app/db user=app pass=first
vault kv put -mount=secret app/db user=app pass=second     # version 2
vault kv get -mount=secret -field=pass app/db                # second
vault kv get -mount=secret -version=1 -field=pass app/db     # first
```

두 번째 `put`의 결과에 `version 2`가 나왔고, 현재 값은 `second`, 1번 버전은 `first`였습니다. 값을 덮어써도 옛 값이 남으므로 실수로 바꾼 값을 되돌릴 수 있습니다. 반대로 이미 유출된 옛 값도 남아 있다는 뜻이므로 비밀을 바꿀 때는 옛 버전을 `destroy`해야 합니다(`destroy`는 이 글에서 시험하지 않았습니다).

`vault kv delete`는 값을 지우는 것이 아니라 삭제 표시를 합니다. 삭제한 뒤에 `kv get`을 하면 값 줄이 0개였고 `deletion_time`만 표시되었습니다. `vault kv undelete -versions=2`를 하자 값 `second`가 돌아왔습니다.

## 3. 읽기 전용 정책과 20초짜리 토큰

<!-- files: vault_demo.sh -->

Vault는 정책(policy) 파일로 접근을 제어합니다. KV v2에서는 값이 `secret/data/...` 아래에 있고 이름 목록과 메타데이터가 `secret/metadata/...` 아래에 있으므로 두 경로를 따로 적어야 합니다. 이 글의 `app-read.hcl`은 `app/` 아래만 읽도록 허용합니다.

```hcl
path "secret/data/app/*" {
  capabilities = ["read"]
}
path "secret/metadata/app/*" {
  capabilities = ["list", "read"]
}
```

정책을 등록하고(`vault policy write app-read`), 이 정책만 가진 토큰을 20초 수명으로 만들었습니다(`vault token create -policy=app-read -ttl=20s`). 이 토큰으로 세 가지를 시도했습니다.

| 시도 | 결과 |
|---|---|
| `secret/app/db` 읽기 | `second` (성공) |
| `secret/app/db`에 쓰기 | `permission denied` |
| `secret/other/key` 읽기(정책 밖 경로) | `permission denied` |

토큰은 자신에게 붙은 정책이 허용한 일만 할 수 있습니다. 앱에는 이렇게 읽기만 되는 토큰을 주고, 쓰기는 관리자 도구만 하게 나눕니다. `vault token lookup`으로 본 남은 수명은 18초였습니다.

처음에 정책 파일을 컨테이너에 넣지 못하고(`docker cp`가 Git Bash의 경로를 알아듣지 못했습니다) 정책 없이 토큰을 만들었을 때는 읽기부터 403이 났습니다. `vault kv get`이 값을 읽기 전에 저장소 정보(`sys/internal/ui/mounts/secret`)를 먼저 물어보는데, 정책이 없으면 이 질문부터 거절되기 때문입니다. 정책이 붙자 바로 해결되었습니다. 이 글의 스크립트는 파일을 표준 입력으로 넘기는 방식으로 바꿨습니다.

## 4. 토큰이 만료되면

<!-- files: vault_demo.sh -->

20초가 지난 뒤 같은 토큰으로 읽기를 시도하면 이런 메시지가 나옵니다.

```text
permission denied
```

"토큰이 만료되었다"는 별도의 문구가 아니라 `permission denied`였습니다. 정책이 막은 것인지 수명이 끝난 것인지 오류 문구만으로는 구분되지 않으므로, 앱이 갑자기 `permission denied`를 받으면 토큰의 수명(`vault token lookup`)도 함께 확인합니다. 수명이 짧은 토큰은 유출되어도 피해가 20초에 그치고, 앱은 주기적으로 새 토큰을 받아야 합니다. 이 글에서는 토큰 갱신(`renew`)은 시험하지 않았습니다.

## 5. 감사 로그

감사 로그는 켜야 남습니다(`vault audit enable file file_path=/tmp/audit.log`). 켠 뒤에 root로 읽기를 한 번, 읽기 전용 토큰으로 쓰기를 한 번 시도한 결과를 로그에서 읽었습니다.

```text
request  read    secret/data/app/db   policies=['root']
request  update  secret/data/app/db   policies=['app-read', 'default']
```

누가(어떤 정책을 가진 토큰이), 어느 경로에, 어떤 동작을 시도했는지가 남습니다. 두 번째 줄이 거절된 쓰기 시도입니다. 정책 밖의 일을 시도한 토큰이 있는지를 로그에서 찾을 수 있습니다. 로그 파일에서 평문 값 `second`와 `hacked`를 찾아보니 0건이었습니다. Vault는 값을 해시로 바꿔 기록하므로 로그가 유출되어도 비밀 값은 읽히지 않습니다. 이 글에서는 해시의 형식이나 비교 방법은 확인하지 않았습니다.

![vault_demo.sh 실행 결과 앞부분에서 개발 서버 상태, KV 버전과 삭제 복구, 정책 등록, 읽기 전용 토큰의 읽기 성공과 쓰기, 다른 경로 읽기 거절, 만료 뒤의 거절을 확인합니다.](https://copyandrun.com/img/vault-dev-mode-kv-policy/01-vault-저장-버전-정책.png)

## 6. HTTP API로 읽기

<!-- files: vault_demo.sh -->

CLI는 HTTP API를 감싼 것입니다. 앱은 보통 HTTP로 직접 읽습니다. 컨테이너 안의 `wget`으로 헤더에 토큰을 넣어 읽었습니다.

```bash
wget -qO- --header="X-Vault-Token: root-lab-token" http://127.0.0.1:8200/v1/secret/data/app/db
```

응답에서 `version 2`, `pass second`를 읽었습니다. 앱 코드는 이 주소와 `X-Vault-Token` 헤더만 알면 됩니다. 이 글에서는 앱 쪽 코드 라이브러리는 쓰지 않았습니다.

## 7. 개발 서버를 재시작하면

컨테이너를 재시작한 뒤 같은 값을 읽자 이런 응답이 나왔습니다.

```text
No value found at secret/data/app/db
```

개발 서버는 데이터를 메모리에만 두므로 재시작하면 모든 것이 사라집니다. 정책, 토큰, 감사 설정도 같이 사라집니다. 개발 서버를 운영에 쓰면 안 되는 가장 직접적인 이유입니다. 운영에서는 파일이나 통합 저장소(Raft)를 쓰고 열쇠 조각으로 잠금을 풉니다. 이 글에서는 운영 구성을 시험하지 않았습니다.

![vault_demo.sh 실행 결과 뒷부분에서 감사 로그에 root의 읽기와 app-read 토큰의 거절된 쓰기가 남고 평문 값은 0건이며, API로 version 2를 읽고, 재시작 뒤에 값이 없어지는 것을 확인합니다.](https://copyandrun.com/img/vault-dev-mode-kv-policy/02-vault-만료-감사-재시작.png)

## 8. 앱에 연결하는 순서

실제 서비스에서는 보통 이 순서로 씁니다.

1. 비밀을 `secret/app/...`에 넣습니다(관리자 도구).
2. `app-read` 같은 읽기 전용 정책을 만듭니다.
3. 앱마다 그 정책의 토큰(또는 AppRole 같은 인증 방식)을 짧은 수명으로 발급합니다.
4. 앱은 시작할 때 HTTP로 값을 읽습니다.
5. 감사 로그를 켜 두고 `permission denied`가 반복되는 토큰을 살핍니다.

3번의 AppRole 같은 인증 방식은 이 글에서 시험하지 않았습니다. 앞의 [Dockle 글](/blog/dockle-image-best-practice-check/)에서 본 것처럼 비밀을 이미지의 `ENV`에 넣지 않고 실행 시점에 이런 서버에서 받아 오는 것이 올바른 방향입니다.

## 전체 코드

아래 두 파일을 같은 폴더에 두고 `bash vault_demo.sh`를 실행하면 이 글의 출력을 다시 볼 수 있습니다. 이 PC에서 약 1분이 걸렸고(토큰 만료를 기다리는 22초 포함), 끝에 컨테이너를 지웁니다.

`app-read.hcl`

```hcl
# app-read.hcl
# secret/app/ 아래는 읽기와 목록만 허용한다(KV v2 는 data/ 와 metadata/ 경로를 쓴다)
path "secret/data/app/*" {
  capabilities = ["read"]
}
path "secret/metadata/app/*" {
  capabilities = ["list", "read"]
}
```

`vault_demo.sh`

```bash
# vault_demo.sh
#!/usr/bin/env bash
# HashiCorp Vault 개발 서버로 KV 저장, 버전, 읽기 전용 정책, 토큰 만료, 감사 로그를 확인한다.
# 준비: Docker, 같은 폴더에 app-read.hcl. 개발 서버는 메모리에만 저장하고 root 토큰이 고정이므로 내 PC 시험 전용이다.
# 실행(Git Bash): bash vault_demo.sh   (약 1분)
export MSYS_NO_PATHCONV=1
HERE="$(pwd)"
ROOT=root-lab-token
V()  { docker exec -e VAULT_ADDR=http://127.0.0.1:8200 -e VAULT_TOKEN="$ROOT" osk-vault vault "$@"; }
VT() { local t="$1"; shift; docker exec -e VAULT_ADDR=http://127.0.0.1:8200 -e VAULT_TOKEN="$t" osk-vault vault "$@"; }
start() {
  docker rm -f osk-vault >/dev/null 2>&1
  docker run -d --name osk-vault --cap-add IPC_LOCK -e VAULT_DEV_ROOT_TOKEN_ID=$ROOT \
    -e VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 hashicorp/vault:latest >/dev/null
  sleep 4
}
start

echo "## 1. 개발 서버 상태(메모리 저장, 자동 unseal)"
V version | cut -c1-14
V status | grep -E 'Initialized|Sealed|Storage|Version'

echo "## 2. KV v2: 저장, 덮어쓰기(버전 증가), 옛 버전 읽기"
V kv put -mount=secret app/db user=app pass=first >/dev/null
V kv put -mount=secret app/db user=app pass=second | grep -E '^version'
echo -n "  현재 값:    "; V kv get -mount=secret -field=pass app/db; echo
echo -n "  1번 버전:   "; V kv get -mount=secret -version=1 -field=pass app/db; echo
V kv delete -mount=secret app/db >/dev/null
echo -n "  삭제 뒤:    값 줄 수 "; V kv get -mount=secret app/db 2>&1 | grep -c '^pass'; V kv get -mount=secret app/db 2>&1 | grep deletion_time | sed 's/^/              /'
V kv undelete -versions=2 -mount=secret app/db >/dev/null
echo -n "  복구 뒤:    "; V kv get -mount=secret -field=pass app/db; echo

echo "## 3. 읽기 전용 정책과 짧은 수명의 토큰(20초)"
docker exec -i osk-vault sh -c 'cat > /tmp/app-read.hcl' < "$HERE/app-read.hcl"   # docker cp 는 Git Bash 경로에서 실패해서 표준 입력으로 넘긴다
V policy write app-read /tmp/app-read.hcl
V kv put -mount=secret other/key value=hidden >/dev/null
TOK=$(V token create -policy=app-read -ttl=20s -field=token)
echo "  토큰 앞 8자: ${TOK:0:8}..."
echo -n "  읽기 secret/app/db : "; VT "$TOK" kv get -mount=secret -field=pass app/db; echo
echo -n "  쓰기 secret/app/db : "; VT "$TOK" kv put -mount=secret app/db pass=hacked 2>&1 | grep -o 'permission denied' | head -1
echo -n "  읽기 secret/other  : "; VT "$TOK" kv get -mount=secret other/key 2>&1 | grep -o 'permission denied' | head -1
echo -n "  토큰 남은 수명(초) : "; VT "$TOK" token lookup -format=json | python -c "import json,sys; print(json.load(sys.stdin)['data']['ttl'])"

echo "## 4. 20초가 지난 뒤에 같은 토큰으로 읽기"
sleep 22
echo -n "  읽기: "; VT "$TOK" kv get -mount=secret -field=pass app/db 2>&1 | grep -oE 'permission denied|bad token|invalid token' | head -1

echo "## 5. 감사 로그: 켠 뒤의 요청만 남고, 값은 해시로 가려진다"
V audit enable file file_path=/tmp/audit.log >/dev/null
V kv get -mount=secret -field=pass app/db >/dev/null
TOK2=$(V token create -policy=app-read -ttl=60s -field=token)
VT "$TOK2" kv put -mount=secret app/db pass=hacked >/dev/null 2>&1
docker exec osk-vault cat /tmp/audit.log | python -c "
import json, sys
for line in sys.stdin:
    d = json.loads(line)
    r = d.get('request', {})
    if d['type'] == 'request' and r.get('path', '').startswith('secret/data/app'):
        print(f\"  {d['type']:8} {r['operation']:7} {r['path']:20} policies={d.get('auth', {}).get('policies')}\")
" 
echo -n "  로그에 평문 'second' 가 있는가: "; docker exec osk-vault grep -c second /tmp/audit.log
echo -n "  로그에 평문 'hacked' 가 있는가: "; docker exec osk-vault grep -c hacked /tmp/audit.log

echo "## 6. HTTP API 로도 같은 값을 읽는다(wget)"
docker exec osk-vault wget -qO- --header="X-Vault-Token: $ROOT" http://127.0.0.1:8200/v1/secret/data/app/db \
  | python -c "import json,sys; d=json.load(sys.stdin)['data']; print('  version', d['metadata']['version'], 'pass', d['data']['pass'])"

echo "## 7. 개발 서버를 다시 시작하면 데이터가 사라진다"
docker restart osk-vault >/dev/null; sleep 4
echo -n "  재시작 뒤 읽기: "; V kv get -mount=secret app/db 2>&1 | head -1 | cut -c1-70

echo "## 8. 정리"
docker rm -f osk-vault >/dev/null
docker ps -a --format '{{.Names}}' | grep -c osk-vault
```

## 자주 막히는 곳

| 증상 | 원인과 해결 |
|---|---|
| `docker cp`가 `The system cannot find the file specified`로 실패합니다 | Git Bash의 경로를 Windows의 Docker가 알아듣지 못합니다. `docker exec -i ... sh -c 'cat > 파일' < 파일`로 표준 입력으로 넘깁니다 |
| 토큰으로 `kv get`을 하면 `preflight capability check returned 403`이 나옵니다 | 토큰에 정책이 없거나 경로가 정책에 없습니다. KV v2는 `secret/data/...`와 `secret/metadata/...`를 따로 허용합니다 |
| 토큰이 만료되었는데 `permission denied`만 나옵니다 | 만료와 정책 거절이 같은 문구입니다. `vault token lookup`으로 수명을 확인합니다 |
| 감사 로그에 값이 보이지 않습니다 | 의도된 동작입니다. 값은 해시로 기록됩니다 |
| 재시작하니 모두 사라졌습니다 | 개발 서버는 메모리 저장입니다. 시험 데이터는 스크립트로 다시 만들 수 있게 둡니다 |

## 확인 범위

- **해 본 것:** 2026-10-30, Windows 11 · Docker 29.5.3 · Vault 2.2.1 개발 서버에서 KV v2 저장과 버전, 삭제와 복구, 읽기 전용 정책과 20초 토큰(읽기 성공, 쓰기와 정책 밖 읽기 거절), 만료 뒤의 거절, 감사 로그(평문 값 0건), HTTP API 읽기, 재시작 뒤 데이터 손실을 실행했습니다. 전체 스크립트를 세 번 실행해 결과가 같았고, 끝에 컨테이너와 네트워크를 지웠습니다.
- **해 보지 않은 것:** 운영 구성(초기화, unseal key, Raft), 토큰 갱신과 AppRole, 데이터베이스 동적 비밀, 암호화 엔진(transit), `destroy`와 버전 보존 설정, 감사 로그의 해시 비교, 앱 코드 라이브러리 연동, Linux와 macOS.
- **읽을 때 주의:** 이 글의 root 토큰(`root-lab-token`)은 시험용으로 고정한 값이며 실제 환경에서는 쓰지 않습니다. 개발 서버는 TLS 없이 HTTP로 열려 있으므로 같은 네트워크의 다른 장치가 접근할 수 있는 곳에서는 실행하지 않습니다. 오류 문구와 명령 출력은 이 버전(2.2.1)의 것입니다.
