Riferimento all'API per la gestione delle istanze

Utilizza l'API di gestione delle istanze di " IBM Cloud Secrets Manager " per gestire le istanze del servizio del piano " Vault Dedicated ". Per le operazioni di runtime di Vault, quali la gestione dei segreti, i metodi di autenticazione e le politiche, utilizzare l’API HashiCorp Vault.

Per consultare la guida interattiva alle API con esempi relativi all'SDK, consultare la guida alle API di gestione delle istanze.

IBM Cloud Secrets Manager API per la gestione delle istanze

L'API di gestione delle istanze di IBM Cloud Secrets Manager fornisce operazioni del piano di controllo per la gestione delle istanze del servizio Vault Dedicated. Queste API consentono di recuperare i metadati delle istanze, gestire i token di amministrazione e configurare le impostazioni delle istanze.

Autenticazione

Tutte le richieste API richiedono l'autenticazione tramite un token IAM IBM Cloud. Includi il tuo token IAM nell'intestazione Authorization di ogni richiesta:

Authorization: Bearer {iam_token}

Per informazioni sulla generazione dei token IAM, consulta la sezione Creazione di un token di accesso IAM per un utente o un ID di servizio.

URL di base

L' URL e di base per l'API di gestione delle istanze è l'endpoint del servizio del piano di controllo relativo alla propria istanza. Puoi trovare questo endpoint nella pagina "Endpoint " della dashboard del servizio " Secrets Manager ".

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

Sostituisci {region} con la regione in cui è distribuita la tua istanza (ad esempio, us-south, eu-de).

Ottenere i dettagli dell'istanza

Utilizza l'API dei dettagli dell'istanza per recuperare i metadati relativi alla tua istanza del servizio Vault Dedicated, tra cui lo stato del cluster, gli endpoint e la configurazione del servizio di gestione delle chiavi.

Ottenere i dettagli dell'istanza nell'interfaccia utente

Nella console di IBM Cloud, fare clic sull'icona " Menu " > Elenco delle risorse.
Dall'elenco dei servizi, seleziona la tua istanza Vault Dedicated.
Nella dashboard dell'istanza, consulta la sezione " Endpoint " per visualizzare lo stato del cluster, l'endpoint dell'API di Vault e altri dettagli relativi all'istanza.

Ottenere i dettagli di un'istanza dalla CLI

Per recuperare i dettagli della tua istanza Vault Dedicated utilizzando la CLI di IBM Cloud, esegui il seguente comando.

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

Ottenere i dettagli di un'istanza tramite l'API

Recupera informazioni dettagliate sulla tua istanza Vault Dedicated.

Richiesta

GET /v2/instances/{id}

Richiesta di esempio

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

Risposta

La risposta contiene le seguenti informazioni:

id: L'ID dell'istanza (UUID)
nome: Il nome dell'istanza
instance_crn: L'identificatore CRN dell'istanza
piano: il nome del piano dell'istanza (dedicated)
vault_cluster: informazioni sul cluster Vault, tra cui status (healthy, sealed o not_initialized) e version
endpoint: URL di endpoint pubblici e privati, ciascuno contenente i campi vault_api e vault_ui
crittografia: configurazione del servizio di gestione delle chiavi, inclusi mode (service_managed o customer_managed) e, facoltativamente, provider e key_crn per la crittografia gestita dal cliente

Risposta di esempio

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

Ottenere i dettagli di un’istanza con Terraform

Per ottenere i dettagli di un'istanza Vault Dedicated con Terraform, utilizzare la fonte dati " ibm_sm_instance ".

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

Una volta creata la fonte dati, è possibile fare riferimento ai suoi attributi. Ad esempio, per ottenere l'endpoint pubblico dell'API di Vault:

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

Gestione dei token amministrativi

I token di amministrazione garantiscono l'accesso con privilegi di root al cluster Vault Dedicated e sono necessari per la configurazione iniziale e le operazioni amministrative.

Considerare i token di amministratore come credenziali estremamente sensibili. Generarle solo quando necessario per attività amministrative e revocarle immediatamente dopo l'uso.

Generazione di un token di amministratore nell'interfaccia utente

Nella console di IBM Cloud, fare clic sull'icona " Menu " > Elenco delle risorse.
Dall'elenco dei servizi, seleziona la tua istanza Vault Dedicated.
Nella dashboard dell'istanza, fare clic su "Crea token " nella sezione " Crea nuovo token di amministratore ".
Copia il token di amministratore generato e conservalo in un luogo sicuro. Questo token è necessario per accedere all'interfaccia utente di Vault.

Generazione di un token di amministratore dalla CLI

Per generare un nuovo token di amministratore di Vault utilizzando la CLI di IBM Cloud, eseguire il seguente comando.

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

Il comando restituisce il token di amministratore di Vault. Conservalo in un luogo sicuro: ti servirà questo token per accedere all'interfaccia utente di Vault. Il buono è valido per 1 ora.

Generazione di un token di amministratore tramite l'API

Genera un nuovo token di amministratore Vault per l'autenticazione al tuo cluster Vault Dedicated. Questo token garantisce l'accesso con privilegi di root e deve essere utilizzato esclusivamente per la configurazione iniziale e le operazioni amministrative. Il buono è valido per 1 ora.

Richiesta

POST /v2/instances/{id}/admintokens

Richiesta di esempio

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

Risposta

Una richiesta andata a buon fine restituisce HTTP 201 Created con un oggetto JSON contenente il token di amministratore di Vault.

Risposta di esempio

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

Generazione di un token di amministratore con Terraform

Per generare un token di amministratore Vault con Terraform, utilizzare la risorsa ibm_sm_admin_token. Il token è valido per 1 ora e viene aggiornato automaticamente quando sta per scadere.

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

Una volta creata la risorsa, il token è disponibile nell'attributo token .

Utilizzo del token di amministratore

Utilizza l'endpoint vault_api presente nella risposta dei dettagli dell'istanza per autenticare le chiamate all'API di Vault:

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

Revoca di tutti i token amministrativi dall'interfaccia utente

Nella console di IBM Cloud, fare clic sull'icona " Menu " > Elenco delle risorse.
Dall'elenco dei servizi, seleziona la tua istanza Vault Dedicated.
Nella dashboard dell'istanza, fare clic su "Revoca " nella sezione " Revoca tutti i token di amministratore ".
Confermare la revoca quando richiesto.

La revoca del token ne comporta l'immediata invalidazione e contribuisce a ridurre il rischio di accessi non autorizzati.

Revoca di tutti i token di amministratore dalla CLI

Per revocare tutti i token di amministratore di Vault attivi utilizzando la CLI di IBM Cloud, eseguire il comando seguente.

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

Questa operazione invalida immediatamente tutti i token amministrativi, rendendo necessaria la generazione di nuovi token per i futuri accessi amministrativi.

Revoca di tutti i token amministrativi tramite l'API

Revoca tutti i token di amministratore di Vault attivi per la tua istanza. Questa operazione invalida immediatamente tutti i token amministrativi, rendendo necessaria la generazione di nuovi token per i futuri accessi amministrativi.

Richiesta

DELETE /v2/instances/{id}/admintokens

Richiesta di esempio

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

Risposta

Una revoca riuscita restituisce un codice di stato 204 No Content.

HashiCorp Vault API

Per le operazioni di runtime di Vault, quali la gestione dei segreti, i metodi di autenticazione, le politiche e i motori dei segreti, consultare la documentazione relativa all’API e alla CLI di HashiCorp Vault.

Passi successivi

Consulta la documentazione dell'API di HashiCorp Vault per le operazioni di gestione dei segreti
Scopri di più su Metodi di autenticazione di Vault
Scopri i motori di Vault Secrets