API-Referenz zur Instanzverwaltung

Verwenden Sie die API zur Instanzverwaltung von IBM Cloud Secrets Manager, um die Service-Instanzen des Plans Vault Dedicated zu verwalten. Verwenden Sie für Vault-Laufzeitvorgänge wie die Verwaltung von Geheimnissen, Authentifizierungsmethoden und Richtlinien die HashiCorp Vault-API.

Die interaktive API-Referenz mit SDK-Beispielen finden Sie in der Instance Management API-Referenz.

IBM Cloud Secrets Manager API für Instanzverwaltung

Die IBM Cloud Secrets Manager-Instanzverwaltungs-API bietet Control-Plane-Funktionen zur Verwaltung Ihrer Vault Dedicated-Serviceinstanzen. Mit diesen APIs können Sie Instanz-Metadaten abrufen, Admin-Token verwalten und Instanz-Einstellungen konfigurieren.

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung mithilfe eines IAM-Tokens für IBM Cloud. Fügen Sie Ihr IAM-Token in den Header Authorization jeder Anfrage ein:

Authorization: Bearer {iam_token}

Informationen zum Generieren von IAM-Tokens finden Sie unter Erstellen eines IAM-Zugriffstokens für eine Benutzer- oder Dienst-ID.

Basis-URL

Die Basis- URL-Adresse für die Instance Management API ist der Endpunkt des Control-Plane-Dienstes für Ihre Instanz. Sie finden diesen Endpunkt auf der Seite Endpunkte Ihres Secrets Manager-Service-Dashboards.

https://{region}.secrets-manager.cloud.ibm.com

Ersetzen Sie durch {region} die Region, in der Ihre Instanz bereitgestellt ist (zum Beispiel us-south, eu-de).

Instanzdetails abrufen

Verwenden Sie die Instance-Details-API, um Metadaten zu Ihrer Vault Dedicated-Service-Instanz abzurufen, darunter den Cluster-Status, Endpunkte und die Konfiguration des Schlüsselverwaltungsdienstes.

Abrufen von Instanzdetails in der Benutzeroberfläche

  1. Klicken Sie in der IBM Cloud -Konsole auf das Symbol Menü Menüsymbol > Ressourcenliste.
  2. Wählen Sie aus der Liste der Dienste Ihre Vault Dedicated-Instanz aus.
  3. Überprüfen Sie im Instanz-Dashboard den Abschnitt Endpunkte, um den Cluster-Status, den Vault-API-Endpunkt und weitere Instanzdetails zu finden.

Abrufen von Instanzdetails über die CLI

Um die Details Ihrer Vault Dedicated-Instanz mithilfe der IBM Cloud-CLI abzurufen, führen Sie den folgenden Befehl aus.

ibmcloud secrets-manager-instance-management instance-details --id {instance_id}

Abrufen von Instanzdetails über die API

Rufen Sie detaillierte Informationen zu Ihrer Vault Dedicated-Instanz ab.

Anforderung

GET /v2/instances/{id}

Beispielanforderung

curl -X GET \
  -H "Authorization: Bearer {iam_token}" \
  -H "Accept: application/json" \
  "https://{region}.secrets-manager.cloud.ibm.com/v2/instances/{id}"

Antwort

Die Antwort enthält die folgenden Informationen:

  • id: Die Instanz-ID (UUID)
  • name: Der Instanzname
  • instance_crn: Die CRN-Kennung der Instanz
  • Plan: Der Name des Instanzplans (dedicated)
  • vault_cluster: Informationen zum Vault-Cluster, einschließlich ( status``healthy, sealed, oder not_initialized) und version
  • Endpunkte: Öffentliche und private Endpunkt-URLs, die jeweils die Felder vault_ui vault_api und enthalten
  • Verschlüsselung: Konfiguration des Schlüsselverwaltungsdienstes, einschließlich ( mode``service_managed oder customer_managed) sowie optional provider und key_crn für die vom Kunden verwaltete Verschlüsselung

Beispielantwort

{
  "id": "bfc50c2e-d66d-4f37-9ccf-9713f8325b39",
  "name": "my-vault-dedicated-instance",
  "instance_crn": "crn:v1:bluemix:public:secrets-manager:us-south:a/...:bfc50c2e-d66d-4f37-9ccf-9713f8325b39::",
  "plan": "dedicated",
  "vault_cluster": {
    "status": "healthy",
    "version": "2.0.4"
  },
  "endpoints": {
    "public": {
      "vault_api": "https://bfc50c2e-d66d-4f37-9ccf-9713f8325b39.us-south.secrets-manager.appdomain.cloud",
      "vault_ui": "https://bfc50c2e-d66d-4f37-9ccf-9713f8325b39.us-south.secrets-manager.appdomain.cloud/ui"
    },
    "private": {
      "vault_api": "https://private.bfc50c2e-d66d-4f37-9ccf-9713f8325b39.us-south.secrets-manager.appdomain.cloud",
      "vault_ui": "https://private.bfc50c2e-d66d-4f37-9ccf-9713f8325b39.us-south.secrets-manager.appdomain.cloud/ui"
    }
  },
  "encryption": {
    "mode": "service_managed"
  },
  "href": "https://us-south.secrets-manager.cloud.ibm.com/v2/instances/bfc50c2e-d66d-4f37-9ccf-9713f8325b39"
}

Instanzdetails mit Terraform abrufen

Um die Details einer Vault Dedicated-Instanz mit Terraform abzurufen, verwenden Sie die ibm_sm_instance Datenquelle.

data "ibm_sm_instance" "sm_instance" {
  instance_id = "bfc50c2e-d66d-4f37-9ccf-9713f8325b39"
}

Nachdem Sie Ihre Datenquelle erstellt haben, können Sie auf deren Attribute verweisen. Beispiel: So rufen Sie den öffentlichen Vault-API-Endpunkt ab:

data.ibm_sm_instance.sm_instance.endpoints.0.public.0.vault_api

Verwaltung von Admin-Tokens

Admin-Token gewähren Root-Zugriff auf Ihren Vault Dedicated-Cluster und sind für die Ersteinrichtung sowie für Verwaltungsvorgänge erforderlich.

Behandeln Sie Admin-Token als äußerst sensible Anmeldedaten. Erstellen Sie diese nur, wenn sie für administrative Aufgaben benötigt werden, und widerrufen Sie sie unmittelbar nach der Verwendung.

Erstellen eines Admin-Tokens in der Benutzeroberfläche

  1. Klicken Sie in der IBM Cloud -Konsole auf das Symbol Menü Menüsymbol > Ressourcenliste.
  2. Wählen Sie aus der Liste der Dienste Ihre Vault Dedicated-Instanz aus.
  3. Klicken Sie im Instanz-Dashboard im Abschnitt Neues Admin-Token erstellen auf Token erstellen.
  4. Kopieren Sie das generierte Admin-Token und bewahren Sie es sicher auf. Sie benötigen dieses Token, um sich bei der Vault-Benutzeroberfläche anzumelden.

Erstellen eines Admin-Tokens über die CLI

Um mithilfe der CLI IBM Cloud ein neues Vault-Admin-Token zu generieren, führen Sie den folgenden Befehl aus.

ibmcloud secrets-manager-instance-management admin-token-create --id {instance_id}

Der Befehl gibt das Vault-Admin-Token zurück. Bewahren Sie es sicher auf – Sie benötigen dieses Token, um sich bei der Vault-Benutzeroberfläche anzumelden. Das Token ist 1 Stunde lang gültig.

Erstellen eines Admin-Tokens mit der API

Generieren Sie ein neues Vault-Admin-Token für die Authentifizierung bei Ihrem Vault Dedicated-Cluster. Dieses Token gewährt Zugriff auf Root-Ebene und sollte ausschließlich für die Ersteinrichtung und administrative Vorgänge verwendet werden. Das Token ist 1 Stunde lang gültig.

Anforderung

POST /v2/instances/{id}/admintokens

Beispielanforderung

curl -X POST \
  -H "Authorization: Bearer {iam_token}" \
  -H "Accept: application/json" \
  "https://{region}.secrets-manager.cloud.ibm.com/v2/instances/{id}/admintokens"

Antwort

Eine erfolgreiche Anfrage gibt HTTP zurück, zusammen 201 Created mit einem JSON-Objekt, das das Vault-Admin-Token enthält.

Beispielantwort

{
  "token": "hvs.CAESIJ..."
}

Erstellen eines Admin-Tokens mit Terraform

Um mit Terraform ein Vault-Admin-Token zu generieren, verwenden Sie die Ressource ibm_sm_admin_token. Das Token ist 1 Stunde lang gültig und wird automatisch aktualisiert, wenn es kurz vor dem Ablauf steht.

resource "ibm_sm_admin_token" "sm_admin_token" {
  instance_id = "bfc50c2e-d66d-4f37-9ccf-9713f8325b39"
}

Nachdem die Ressource erstellt wurde, ist das Token im Attribut token verfügbar.

Verwendung des Admin-Tokens

Verwenden Sie den Endpunkt vault_api aus der Antwort zu den Instanzdetails, um Vault-API-Aufrufe zu authentifizieren:

curl -X GET \
  -H "X-Vault-Token: hvs.CAESIJ..." \
  "{vault_api_endpoint}/v1/sys/health"

Alle Admin-Token in der Benutzeroberfläche widerrufen

  1. Klicken Sie in der IBM Cloud -Konsole auf das Symbol Menü Menüsymbol > Ressourcenliste.
  2. Wählen Sie aus der Liste der Dienste Ihre Vault Dedicated-Instanz aus.
  3. Klicken Sie im Instanz-Dashboard im Abschnitt Alle Admin-Token widerrufen auf Widerrufen.
  4. Bestätigen Sie den Widerruf, wenn Sie dazu aufgefordert werden.

Durch das Widerrufen des Tokens wird dieses sofort ungültig, wodurch das Risiko eines unbeabsichtigten Zugriffs verringert wird.

Alle Admin-Token über die CLI widerrufen

Um alle aktiven Vault-Admin-Token mithilfe der CLI IBM Cloud zu widerrufen, führen Sie den folgenden Befehl aus.

ibmcloud secrets-manager-instance-management admin-tokens-delete --id {instance_id}

Dieser Vorgang macht alle Admin-Token sofort ungültig, sodass für den künftigen Administratorzugriff neue Token generiert werden müssen.

Alle Admin-Token über die API widerrufen

Widerrufen Sie alle aktiven Vault-Admin-Token für Ihre Instanz. Dieser Vorgang macht alle Admin-Token sofort ungültig, sodass für den künftigen Administratorzugriff neue Token generiert werden müssen.

Anforderung

DELETE /v2/instances/{id}/admintokens

Beispielanforderung

curl -X DELETE \
  -H "Authorization: Bearer {iam_token}" \
  "https://{region}.secrets-manager.cloud.ibm.com/v2/instances/{id}/admintokens"

Antwort

Bei einer erfolgreichen Sperrung wird ein 204 No Content Statuscode zurückgegeben.

HashiCorp Vault API

Für Vault-Laufzeitvorgänge wie die Verwaltung von Geheimnissen, Authentifizierungsmethoden, Richtlinien und Geheimnis-Engines verwenden Sie die Dokumentation zur HashiCorp Vault-API und zur Befehlszeilenschnittstelle (CLI).

Nächste Schritte