플러그인 등록

외부 플러그인은 외부 코드로 빌드된 인증 또는 시크릿 플러그인이에요. Vault는 일반적으로 사용되는 외부 플러그인(예: kv)을 사전 등록하지만, 다른 외부 플러그인은 Vault 설치에서 사용하기 전에 Vault 플러그인 카탈로그에 수동으로 추가해야 해요.

출처: 문서

본문

사전 등록된 플러그인과 같은 이름으로 외부 플러그인을 등록하면, Vault는 그 이름으로 새 마운트를 활성화할 때 수동으로 등록된 플러그인을 기본으로 사용해요.

Vault Enterprise v1.20.0은 플러그인 등록 API의 download(BETA) 매개변수를 지원해요. 플러그인을 등록할 때 download를 true로 설정하면 Vault가 HashiCorp 릴리스 페이지에서 플러그인 바이너리를 가져오게 할 수 있어요. 자세한 내용은 /sys/plugins/catalog API 레퍼런스를 참조하세요.

시작하기 전에

공식 엔터프라이즈 플러그인을 등록하려면 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단계: 플러그인 카탈로그 업데이트

외부 플러그인을 활성화하기 전에 Vault 카탈로그에 등록해야 해요. 플러그인을 등록하면 Vault가 호출하는 플러그인이 인증되고 무결성을 유지하도록 보장해요.

플러그인 바이너리의 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단계: 플러그인 활성화

클라이언트가 사용할 수 있도록 플러그인을 활성화하세요.

적절한 enable 명령(vault secrets enable 또는 vault auth enable)과 등록된 이름을 사용해 외부 플러그인을 마운트하세요.

$ vault <secrets | auth> enable \
  -path <mount_path>            \
  <plugin_name>

예를 들어 mykv 플러그인을 /custom/kv 경로에 활성화하려면:

$ vault secrets enable \
  -path custom/kv      \
  mykv

Success! Enabled the mykv secrets engine at: custom/kv/

유형과 관련 구성 세부 정보를 JSON 파일로 저장하세요. 예를 들어 mykv 플러그인의 데이터 파일을 만들려면:

$ cat <<-EOF > data.json
{
  "type": "<registered_plugin_name>",
  "config": {
    "plugin_version": "<semantic_version>"
  }
}
EOF

$ cat <<-EOF > data.json
{
  "type": "mykv",
  "config": {
    "plugin_version": "v1.0.0"
  }
}
EOF

적절한 enable 엔드포인트(EnableSecretsEngine 또는 EnableAuthMethod)와 등록된 플러그인 이름을 사용해 외부 플러그인을 마운트하세요.

$ curl                                             \
  --request POST                                   \
  --header "X-Vault-Token: ${VAULT_TOKEN}"         \
  --header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data @data                                     \
  ${VAULT_ADDR}/v1/sys/<mounts | auth>/<mount_path>

예를 들어 mykv 시크릿 플러그인을 /custom/kv 경로에 활성화하려면:

$ curl                                              \
  --request POST                                    \
  --header "X-Vault-Token: ${VAULT_TOKEN}"          \
  --header "X-Vault-Namespace: ${VAULT_NAMESPACE}"  \
  --data @data                                      \
  ${VAULT_ADDR}/v1/sys/mounts/custom/kv

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"
}

플러그인 등록