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]
            }'

키-값 비밀 요청 매개변수의 지정된 버전을 삭제합니다
요청 매개변수	설명
`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
                ]
            }

키-값 비밀 요청 매개변수의 버전 삭제 취소
요청 매개변수	설명
`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
}