Vault API を使用したキー値シークレットの管理

IBM Cloud® Secrets Manager では、HashiCorp Vault HTTP API を使用して、鍵ごとに複数のバージョンを管理し、キー値シークレットの履歴とメタデータにアクセスすることができます。

概要

既に Vault API を使用している場合は、その API 形式とガイドラインを使用して Secrets Manager と対話できます。Secrets Manager は KV バージョン 2 のみをサポートします。 Vault 資料で定義されているキー値シークレット・エンジンのエンドポイントは、CLI やその他の適用可能なツールと互換性があります。

認証の詳細については、「 Vault API 」を参照してください。

Secrets Manager の標準 REST API を使用するには、 Secrets Manager API リファレンスをご覧ください。

KV と Secrets Manager の違い

Secrets Manager が使用するキー値シークレット・エンジンは、Vault の KV シークレット・エンジンとは少し異なります。

パスを完全にカスタマイズすることはできません。キー値シークレットへのパスは、以下のようにする必要があります。
- {secret_group_id}/{secret_name} (カスタム・シークレット・グループ内にあるシークレットの場合)。
- /{secret_name} (デフォルト・グループ内のシークレットの場合)。
Vault でキー値エンジンを構成し、構成を読み取るために使用されるメソッドはサポートされません。

キー値シークレットの作成または更新

キー値シークレットのバージョンを作成します。

要求の例

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "data": {
                "key":"value"
            }
    }'

秘密のリクエストパラメータを作成または更新する
要求パラメーター	説明
`instance_id`	Secrets Manager インスタンスの ID。
`region`	Secrets Manager インスタンスが作成されたリージョン。
`secret_name`	キー値シークレットの名前。
`Vault-Token`	Vault から取得された認証トークン。
`data`	必須。シークレットに割り当てる JSON 形式のシークレット・データ。最大ファイル・サイズは512KBです。

応答の例

default シークレット・グループ内のキー値シークレットを更新する要求を実行すると、以下の応答が返されます。

{
    "request_id": "9000000d4-f0000-4c000-000000-800000000f",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "created_time": "2022-02-09T23:41:58.888138788Z",
        "deletion_time": "",
        "destroyed": false,
        "version": 2
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

キー値シークレットのバージョンの読み取り

キー値シークレットのバージョンを取得します。要求が成功すると、指定されたバージョンのシークレットに関連付けられているシークレット・データが、他のメタデータとともに返されます。

要求の例

curl -X GET 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}?version={version}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}'

キー・バリュー秘密リクエスト・パラメータのバージョンを読む
要求パラメーター	説明
`instance_id`	Secrets Manager インスタンスの ID。
`region`	Secrets Manager インスタンスが作成されたリージョン。
`secret_name`	キー値シークレットの名前。
`version`	読み取り対象のバージョン。
`Vault-Token`	Vault から取得された認証トークン。

応答の例

default シークレット・グループ内のキー値シークレットのバージョンを取得する要求は、以下の応答を返します。

{
    "request_id": "400000-60000-8e000-0ad0-00000bc0000caebe",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "data": {
            "key": "value"
        },
        "metadata": {
            "created_time": "2022-01-13T21:31:49.893962888Z",
            "deletion_time": "",
            "destroyed": false,
            "version": 1
        }
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

キー値シークレットの最新バージョンの削除

キー値シークレットの最新バージョンを削除します。バージョンを削除した後は、list または get API 呼び出しを使用してそのバージョンを取得することはできません。ただし、これは一時的な削除であり、基となるデータは削除されません。削除の取り消し API エンドポイントを呼び出すことにより、削除を取り消すことができます。

要求の例

curl -X DELETE 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}'

キー・バリュー秘密リクエスト・パラメータの最新バージョンを削除する。
要求パラメーター	説明
`instance_id`	Secrets Manager インスタンスの ID。
`region`	Secrets Manager インスタンスが作成されたリージョン。
`secret_name`	キー値シークレットの名前。
`Vault-Token`	Vault から取得された認証トークン。

応答の例

default シークレット・グループ内のキー値シークレットの最新バージョンを削除する要求を実行すると、最新バージョンが削除されたことを確認する 204 状況コードを含むブランク応答が返されます。

指定されたバージョンのキー値シークレットの削除

指定されたバージョンのキー値シークレットを削除します。バージョンを削除した後は、list または get API 呼び出しを使用してそれらを取得することはできません。ただし、これは一時的な削除であり、基となるデータは削除されません。削除の取り消し API エンドポイントを呼び出すことにより、削除を取り消すことができます。

要求の例

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/delete/test-kv' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -d '{
            "versions": [1, 2]
            }'

指定されたバージョンの key-value シークレットリクエストパラメータを削除する。
要求パラメーター	説明
`instance_id`	Secrets Manager インスタンスの ID。
`region`	Secrets Manager インスタンスが作成されたリージョン。
`secret_name`	キー値シークレットの名前。
`Vault-Token`	Vault から取得された認証トークン。
`versions`	削除される、指定されたバージョン。

応答の例

default シークレット・グループ内の指定されたバージョンのキー値シークレットの削除を要求すると、以下の応答が返されます。

{
    "request_id": "43abde16-6a33-971f-1690-469eccc00d91",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

キー値シークレットの削除の取り消し

以前に削除したバージョンのキー値シークレットを復元します。

要求の例

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/undelete/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "versions": [
                1, 2
                ]
            }

key-value シークレットリクエストパラメータのバージョンを削除解除する。
要求パラメーター	説明
`instance_id`	Secrets Manager インスタンスの ID。
`region`	Secrets Manager インスタンスが作成されたリージョン。
`secret_name`	キー値シークレットの名前。
`Vault-Token`	Vault から取得された認証トークン。
`versions`	削除するキー値シークレットのバージョン。

応答の例

default シークレット・グループ内のキー値シークレットのバージョンを復元する要求を実行すると、指定されたバージョンが復元されたことを確認する 204 状況コードを含むブランク応答が返されます。

シークレットのバージョンの破棄

指定されたバージョンのキー値シークレットを完全に破棄します。シークレットのバージョンを完全にではなく一時的に削除するには、指定したバージョンの削除 API エンドポイントを使用します。

要求の例

curl -X POST 'https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/destroy/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "versions": [1, 3]
            }'

キー・バリューの秘密リクエスト・パラメータの破棄バージョン
要求パラメーター	説明
`instance_id`	Secrets Manager インスタンスの ID。
`region`	Secrets Manager インスタンスが作成されたリージョン。
`secret_name`	キー値シークレットの名前。
`Vault-Token`	Vault から取得された認証トークン。
`versions`	完全に破棄するキー値シークレットのバージョン。

応答の例

default シークレット・グループ内のキー値シークレットのバージョンを完全に破棄する要求を出すと、そのシークレットのバージョンが破棄されたことを確認する 204 状況コードを含むブランク応答が返されます。

キー値シークレットのメタデータの作成または更新

バージョンの最大数やその他のカスタム値など、キー値シークレットのメタデータを作成または更新します。シークレットの実際の内容を更新するには、シークレットの作成または更新メソッドを使用します。

要求の例

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "custom_metadata": {
                "meta1": "data1",
                "meta2": "data2"
                }
            }'

キー・バリュー秘密リクエスト・パラメータのメタデータを更新する。
要求パラメーター	説明
`instance_id`	Secrets Manager インスタンスの ID。
`region`	Secrets Manager インスタンスが作成されたリージョン。
`secret_name`	キー値シークレットの名前。
`Vault-Token`	Vault から取得された認証トークン。

応答の例

default シークレット・グループ内のキー値シークレットのメタデータを更新する要求を実行すると、そのシークレットのメタデータが更新されたことを確認する 204 状況コードを含むブランク応答が返されます。

キー値シークレットのメタデータの読み取り

バージョンの ID を指定して、キー値シークレットのメタデータを取得します。

要求の例

curl -X GET 'https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json'
    -H 'X-Vault-Token: {Vault-Token}'

キー・バリュー秘密リクエスト・パラメータのメタデータを読む
要求パラメーター	説明
`instance_id`	Secrets Manager インスタンスの ID。
`region`	Secrets Manager インスタンスが作成されたリージョン。
`secret_name`	キー値シークレットの名前。
`Vault-Token`	Vault から取得された認証トークン。

応答の例

default シークレット・グループ内のキー値シークレットのメタデータを取得する要求を実行すると、以下の応答が返されます。

{
    "request_id": "400000-60000-8e000-0ad0-00000bc0000caebe",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "cas_required": false,
        "created_time": "2022-01-13T21:31:49.893962888Z",
        "current_version": 3,
        "custom_metadata" : {
              "meta1": "data1",
              "meta2": "data2"    
        },
        "delete_version_after": "0s",
        "max_versions": 0,
        "oldest_version": 0,
        "updated_time": "2022-02-09T23:54:16.313286558Z",
        "versions": {
            "1": {
                "created_time": "2022-01-13T21:31:49.893962888Z",
                "deletion_time": "",
                "destroyed": false
            },
            "2": {
                "created_time": "2022-02-09T23:41:58.888138788Z",
                "deletion_time": "",
                "destroyed": false
            },
            "3": {
                "created_time": "2022-02-09T23:54:16.313286558Z",
                "deletion_time": "",
                "destroyed": false
            }
        }
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

キー値シークレットのメタデータとすべてのバージョンの削除

指定されたキー値シークレットのメタデータとすべてのバージョン・データを完全に削除します。この API エンドポイントを使用すると、すべてのバージョン履歴が削除されます。

要求の例

curl -X DELETE 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json'
    -H 'X-Vault-Token: {Vault-Token}'

キー・バリュー秘密リクエスト・パラメータのメタデータを削除する。
要求パラメーター	説明
`instance_id`	Secrets Manager インスタンスの ID。
`region`	Secrets Manager インスタンスが作成されたリージョン。
`secret_name`	キー値シークレットの名前。
`Vault-Token`	Vault から取得された認証トークン。

応答の例

default シークレット・グループ内のキー値シークレットのメタデータおよびすべてのバージョンの削除を要求すると、以下の応答が返されます。

{
    "request_id": "62b1e2c2-801a-6592-0526-edb38896a546",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

キー値シークレットのキー名の一覧表示

キー値シークレットのキー名のリストを取得します。キー名には機密情報をエンコードしないでください。このコマンドを使用してキーの値にアクセスすることはできません。

{sm-short} では、LIST HTTP 動詞を使ってキー名のリストを取得することはできない。これは、Vault の KV API でのみ行うことができます。

要求の例

curl -X GET "https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/metadata/?list=true" \
    -H 'Accept: application/json'\
    -H 'X-Vault-Token: {Vault-Token}'

キーと値の秘密のリクエストパラメーターのキー名をリストアップする。
要求パラメーター	説明
`instance_id`	Secrets Manager インスタンスの ID。
`region`	Secrets Manager インスタンスが作成されたリージョン。
`Vault-Token`	Vault から取得された認証トークン。

応答の例

default シークレット・グループ内のキー値シークレットのキー名をリストする要求を実行すると、以下の応答が返されます。

{
    "request_id": "a21993df-a4b7-21f1-95a9-c1af7be87d1b",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "keys": [
            "secret1",
            "secret2"
        ]
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

鍵値シークレットにパッチを適用します

変更する詳細のみを指定して、既存のキーと値のシークレットを更新します。シークレットにパッチを適用すると、新しいバージョンが作成されます。変更しないデータは、シークレットの前のバージョンとまったく同じままです。

要求の例

curl -X PATCH 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
            "data": {
                "key":"value"
            }
    }'

秘密のリクエストパラメータを作成または更新する
要求パラメーター	説明
`instance_id`	Secrets Manager インスタンスの ID。
`region`	Secrets Manager インスタンスが作成されたリージョン。
`secret_name`	キー値シークレットの名前。
`Vault-Token`	Vault から取得された認証トークン。
`data`	必須。シークレットにパッチを適用するための JSON 形式のシークレット・データ。最大ファイル・サイズは512KBです。

応答の例

default シークレット・グループ内のキー値シークレットを更新する要求を実行すると、以下の応答が返されます。

{
    "request_id": "9000000d4-f0000-4c000-000000-800000000f",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "created_time": "2022-02-09T23:41:58.888138788Z",
        "deletion_time": "",
        "destroyed": false,
        "version": 2
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}