플러그인 업그레이드
플러그인 업그레이드
카탈로그에서 플러그인을 업그레이드하면 해당 플러그인 버전의 모든 사용에 영향을 줘요. 예를 들어 v1.0.0을 사용하는 customkv 마운트가 5개 있고 v1.1.0으로 업그레이드하면, 바이너리를 덮어쓸 경우 기존 마운트 모두가 새 바이너리를 사용해요. 카탈로그의 플러그인 버전은 명시적으로 덮어쓰기보다 버전 제어 태그처럼 변경 불가능(immutable)하게 취급하는 것을 권장해요.
출처: 문서
본문
플러그인을 업그레이드하기 전에 항상 릴리스 노트에서 지원되지 않는 전환을 확인하세요. Vault 내부의 핵심 시스템이 토큰과 임대(lease) 생명주기를 관리하므로 플러그인은 핵심 시스템이 요청할 때만 토큰과 임대를 갱신하거나 폐기해요. 그 결과 기존 토큰과 임대는 일반적으로 플러그인 업그레이드의 영향을 받지 않아요.
시작하기 전에
- 공식 엔터프라이즈 플러그인을 등록하고 업그레이드하려면 Vault v1.16.21+, 1.17.17+, 1.18.10+, 1.19.4+, 또는 1.20.x+가 있어야 해요.
- 추출된 .zip 파일로 공식 커뮤니티 플러그인을 등록하고 업그레이드하려면 Vault v1.16.21+, 1.17.17+, 1.18.10+, 1.19.5+, 또는 1.20.x+가 있어야 해요.
- Vault에 대한 관리자 권한이 있어야 해요. 구체적으로
plugin register와 적절한 enable 명령을 실행할 수 있어야 해요. - Vault 구성 파일에
plugin_directory가 설정되어 있어야 해요. - Vault 구성 파일에
api_addr가 설정되어 있어야 해요. - 추출된 .zip 파일을 사용할 계획이라면 플러그인 아티팩트가 Vault를 실행하는 시스템과 호환되어야 해요. Vault는 추출된 아티팩트의 등록 과정에서 플러그인 무결성을 검증하고 시스템 호환성을 확인해요.
1단계: 플러그인 준비
구성된 플러그인 디렉터리에 플러그인이 올바르게 설정되어 있어야 해요. Vault는 통합, 라이선스, 파일 형식에 따라 특정 경로 구조를 기대해요.
추출된 .zip 파일을 등록할 계획이라면 추출된 아티팩트 디렉터리 이름이 공식 파일 이름과 일치해야 해요. 예를 들어 vault-plugin-database-oracle_0.11.0+ent_linux_amd64.zip을 등록하려면 플러그인 디렉터리에 vault-plugin-database-oracle_0.11.0+ent_linux_amd64/로 추출해야 해요.
플러그인은 버전과 함께 등록해야 하며, 공식 플러그인은 .zip 파일로 등록하는 것을 강력히 권장해요.
| 통합 | 라이선스 | 소스 | 경로 구조 |
|---|---|---|---|
| 공식 | 엔터프라이즈 | .zip | <plugin_directory>/ |
| 공식 | 커뮤니티 | .zip | <plugin_directory>/ |
| 커뮤니티 | N/A | .zip | 지원되지 않음 |
| 공식 | 엔터프라이즈 | 바이너리 | 지원되지 않음 |
| 공식 | 커뮤니티 | 바이너리 | <plugin_directory>/ |
| 커뮤니티 | N/A | 바이너리 | <plugin_directory>/ |
2단계: 플러그인 카탈로그 업데이트
기존 플러그인 버전과 같은 플러그인 유형 및 이름으로, 업데이트된 버전 번호를 가진 새 플러그인 바이너리나 zip 파일을 등록하세요.
- 플러그인 바이너리의 SHA를 저장하세요.
$ PLUGIN_SHA=$(sha256sum <path_to_plugin_binary> | awk '{print $1;}')
vault plugin register를 사용해 플러그인을 카탈로그에 추가하세요. 예를 들어 명령줄에서mykvplugin으로 실행되는mykv라는 시크릿 플러그인을 등록하려면:
$ vault plugin register \
-command <command_to_run_plugin_binary> \
-sha256 "${PLUGIN_SHA[0]}" \
-version "<semantic_version>" \
<plugin_type> \
<plugin_name> \
$ vault plugin register \
-command mykvplugin \
-sha256 ${PLUGIN_SHA} \
-version "v1.0.1" \
secret \
mykv
Success! Registered plugin: mykv
- 플러그인 바이너리의 SHA, 버전, 실행 명령을 JSON 파일로 저장하세요. 예를 들어 명령줄에서
mykvplugin으로 실행되는 플러그인의 데이터 파일을 만들려면:
$ cat <<-EOF > data.json
{
"sha256": "$(sha256sum <path_to_plugin_binary> | awk '{print $1;}')",
"command": "<command_to_run_plugin_binary>",
"version": "<semantic_version>"
}
EOF
$ cat <<-EOF > data.json
{
"sha256": "$(sha256sum mykvplugin | awk '{print $1;}')",
"command": "mykvplugin",
"version": "v1.0.1"
}
EOF
- RegisterPlugin 엔드포인트를 호출해 플러그인을 카탈로그에 추가하세요. 예를 들어
mykv라는 시크릿 플러그인을 등록하려면:
$ curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--data @data.json \
${VAULT_ADDR}/v1/sys/plugins/catalog/<plugin_type>/<plugin_name>
$ curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--data @data.json \
${VAULT_ADDR}/v1/sys/plugins/catalog/secret/mykv
- ListPlugins 엔드포인트를 호출해 등록을 확인하세요. 예를 들면:
$ curl \
--request GET \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
${VAULT_ADDR}/v1/sys/plugins/catalog \
| jq '.data.detailed | .[] | select(.name =="mykv")'
$ curl \
--request GET \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
${VAULT_ADDR}/v1/sys/plugins/catalog \
| jq '.data.detailed | .[] | select(.name =="mykv")'
{
"builtin": false,
"name": "mykv",
"sha256": "4b7c6993b7147d84d958f30438f9d0c34f34aa400300693b193e62774e4338d7",
"type": "secret",
"version": "v1.0.1"
}
-version을 사용해vault plugin register로 플러그인을 카탈로그에 추가하세요. SHA 값은 제공하지 마세요.
$ vault plugin register
-version "<semantic_version>"
<plugin_type>
<plugin_name>
예를 들어 추출된 아티팩트 디렉터리 vault-plugin-secrets-keymgmt_0.16.0+ent_linux_amd64/로 vault-plugin-secrets-keymgmt 플러그인을 등록하려면:
$ vault plugin register \
-version "v0.16.0+ent" \
secret \
vault-plugin-secrets-keymgmt
Success! Registered plugin: vault-plugin-secrets-keymgmt
- 추출된 플러그인 폴더의 버전 정보를 JSON 파일로 저장하세요. 예를 들어 추출된 아티팩트 디렉터리가
vault-plugin-secrets-keymgmt_0.16.0+ent_linux_amd64/인vault-plugin-secrets-keymgmt플러그인의 데이터 파일을 만들려면:
$ cat <<-EOF > data.json
{
"version": "<semantic_version>"
}
EOF
$ cat <<-EOF > data.json
{
"version": "v0.16.0+ent"
}
EOF
- RegisterPlugin 엔드포인트를 호출해 플러그인을 카탈로그에 추가하세요. 예를 들어 추출된 아티팩트 디렉터리가
vault-plugin-secrets-keymgmt_0.16.0+ent_linux_amd64/인vault-plugin-secrets-keymgmt플러그인을 등록하려면:
$ curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--data @data.json \
${VAULT_ADDR}/v1/sys/plugins/catalog/<plugin_type>/<plugin_name>
$ curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--data @data.json \
${VAULT_ADDR}/v1/sys/plugins/catalog/secret/vault-plugin-secrets-keymgmt
- ListPlugins 엔드포인트를 호출해 등록을 확인하세요. 예를 들면:
$ curl \
--request GET \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
${VAULT_ADDR}/v1/sys/plugins/catalog \
| jq '.data.detailed | .[] | select(.name =="<plugin_name>")'
$ curl \
--request GET \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
${VAULT_ADDR}/v1/sys/plugins/catalog \
| jq '.data.detailed | .[] | select(.name =="vault-plugin-secrets-keymgmt")'
{
"builtin": false,
"name": "vault-plugin-secrets-keymgmt",
"sha256": "95f051152c4b69c720afef2fef26469f83a2e084842bdfad0f795850047fc84f",
"type": "secret",
"version": "v0.16.0+ent"
}
3단계: 플러그인 재로드
플러그인을 재로드할 때까지 Vault는 마운트 경로에서 이전 플러그인 버전을 계속 실행해요. 재로드를 트리거하면 Vault가 활성 플러그인 프로세스를 종료하고 해당 플러그인의 고정된(pinned) 버전으로 새 플러그인 프로세스를 시작해요.
- /sys/plugins/pins/{type}/{name} 엔드포인트 경로로
vault write를 호출해 현재 클러스터의 새 플러그인 버전을 고정하세요. 루트 네임스페이스에서 엔드포인트를 명시적으로 호출해야 해요. 그렇지 않으면 Vault가404: unsupported path오류를 반환해요. 예를 들어mykv라는 시크릿 플러그인을 버전 1.0.0으로 고정하려면:
$ vault write \
-namespace root \
/sys/plugins/pins/<secret | auth | database>/<registered_name> \
version="<semantic_version>"
$ vault write \
-namespace root \
sys/plugins/pins/secret/mykv \
version="v1.0.0"
vault plugin reload를 호출해 다운그레이드된 플러그인의 모든 인스턴스에 대한 전역 새로고침을 트리거하세요. 예를 들어mykv플러그인을 새로고침하려면:
$ vault plugin reload \
-type <secret | auth | database> \
-plugin <registered_plugin_name> \
-scope global
$ vault plugin reload \
-type secret \
-plugin mykv \
-scope global
Success! Reloading plugin: mykv, reload_id: 1b7e989a-e1f9-2047-d41c-307ce64194e9
- SetPinnedVersion 엔드포인트를 호출해 현재 클러스터의 새 플러그인 버전을 고정하세요. 예를 들어
mykv라는 시크릿 플러그인을 버전 1.0.1로 고정하려면:
$ curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--data '{"version":"<semantic_version>"}' \
${VAULT_ADDR}/v1/sys/plugins/pins/<plugin_type>/<plugin_name>
$ curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--data '{"version":"v1.0.1"}' \
${VAULT_ADDR}/v1/sys/plugins/pins/secret/mykv | jq
{
"request_id": "f81013b1-e324-215c-07c6-f66b5b6fdc56",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"wrap_info": null,
"warnings": null,
"auth": null,
"mount_type": "system"
}
- ReloadPlugins 엔드포인트를 호출해 다운그레이드된 플러그인의 모든 인스턴스에 대한 전역 새로고침을 트리거하세요. 예를 들어
mykv플러그인을 새로고침하려면:
$ curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--data '{"scope":"global"}' \
${VAULT_ADDR}/v1/sys/plugins/reload/<plugin_type>/<plugin_name>
$ curl \
--request POST \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--data '{"scope":"global"}' \
${VAULT_ADDR}/v1/sys/plugins/reload/secret/mykv | jq
{
"request_id": "1b543f61-22a3-bfe9-d182-50ce75459373",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"reload_id": "1b543f61-22a3-bfe9-d182-50ce75459373"
},
"wrap_info": null,
"warnings": null,
"auth": null,
"mount_type": ""
}
4단계: 플러그인 상태 확인
적절한 list 명령(vault secrets list 또는 vault auth list)을 사용해 등록된 플러그인의 버전과 마운트 경로를 확인하세요.
$ vault <secrets | auth> list
예를 들어 mykv 플러그인을 확인하려면:
$ vault secrets list
Path Type Accessor Description
---- ---- -------- -----------
cubbyhole/ ns_cubbyhole ns_cubbyhole_dd6729a7 per-token private secret storage
custom/mykv/ mykv mykv_7121a3d5 n/a
identity/ ns_identity ns_identity_f000c24d identity store
private/ kv kv_4a4118d8 n/a
shared/ kv kv_60208c6d n/a
sys/ ns_system ns_system_b9a3364f system endpoints used for control, policy and debugging
list 서브명령은 출력의 특정 필드 필터링을 지원하지 않아요. 버전이나 실행 중인 버전을 확인하려면 -detailed 플래그를 사용하고 관련 플러그인을 필터링한 뒤 인덱스로 원하는 상태 열을 출력하세요.
| 인덱스 | 상세 열 |
|---|---|
| 0 | Path |
| 1 | Plugin |
| 2 | Accessor |
| 3 | Default TTL |
| 4 | Max TTL |
| 5 | Force No Cache |
| 6 | Replication |
| 7 | Seal Wrap |
| 8 | External Entropy Access |
| 9 | Options |
| 10 | Description |
| 11 | UUID |
| 12 | Version |
| 13 | Running Version |
| 14 | Running SHA256 |
| 15 | Deprecation Status |
예를 들어 mykv의 실행 중인 버전을 출력하려면:
$ row=($(vault secrets list -detailed | grep mykv)) ; \
echo "${row[0]}: ${row[1]} (${row[13]})"
custom/mykv/: mykv (v1.0.1)
적절한 list 엔드포인트(ListSecretsEngines 또는 ListAuthMethods)를 사용해 등록된 플러그인의 마운트 경로를 확인하세요.
$ curl -s \
--request GET \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
${VAULT_ADDR}/v1/sys/<mounts | auth> | jq '.data."<mount_path>"'
예를 들어 /custom/kv 경로의 mykv 시크릿 플러그인을 확인하려면:
$ curl -s \
--request GET \
--header "X-Vault-Token: ${VAULT_TOKEN}" \
--header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
${VAULT_ADDR}/v1/sys/mounts | jq '.data."custom/mykv/"'
{
"accessor": "mykv_7121a3d5",
"config": {
"default_lease_ttl": 0,
"force_no_cache": false,
"max_lease_ttl": 0
},
"description": "",
"external_entropy_access": false,
"local": false,
"options": {},
"plugin_version": "v1.0.1",
"running_plugin_version": "v1.0.1",
"running_sha256": "4b7c6993b7147d84d958f30438f9d0c34f34aa400300693b193e62774e4338d7",
"seal_wrap": false,
"type": "mykv",
"uuid": "61c79aea-5b39-1cbb-b470-96edd9f6bfeb"
}