Creare e gestire le annotazioni

Questa pagina descrive come aggiungere annotazioni a un segreto regionale e come modificarle e visualizzarle.

Panoramica

Puoi utilizzare le annotazioni per archiviare metadati personalizzati su un secret. Ad esempio, potresti indicizzare un segreto con il percorso in cui verrà montato. Le annotazioni possono essere utili nei seguenti modi:

  • Per classificare i secret in base allo scopo, all'ambiente (sviluppo, gestione temporanea, produzione) o al livello di sensibilità. In questo modo, è più facile cercare, filtrare e organizzare i secret in Secret Manager.

  • Per indicare il formato o la struttura specifici del valore del segreto, aiutando il carico di lavoro a interpretarlo correttamente.

  • Fornire suggerimenti su come utilizzare la chiave o eventuali considerazioni speciali per la sua gestione.

Ad esempio, se hai un segreto contenente una password del database, puoi aggiungere annotazioni come la seguente:

  • environment:production

  • purpose:database_access

  • owner:database_team

Queste annotazioni consentono di identificare facilmente lo scopo del segreto, il suo ambiente e chi ne è responsabile. Inoltre, un carico di lavoro che accede a questo secret può utilizzare le annotazioni per confermare di utilizzare la password corretta per l'ambiente di produzione.

Le annotazioni non sono le stesse delle etichette. Le etichette vengono utilizzate per ordinare, filtrare e raggruppare le risorse, mentre le annotazioni vengono utilizzate per archiviare metadati non identificativi arbitrari in un segreto. Esiste un limite di caratteri e lunghezza dei caratteri quando si specificano i metadati in un'etichetta. I metadati di un'annotazione possono essere di piccole o grandi dimensioni, strutturati o non strutturati e possono includere caratteri non consentiti dalle etichette.

Ruoli obbligatori

  • L'aggiunta di annotazioni a un secret e l'aggiornamento delle annotazioni richiedono il ruolo Amministratore Secret Manager (roles/secretmanager.admin) per il secret, il progetto, la cartella o l'organizzazione.

  • Per visualizzare le annotazioni è necessario il ruolo Visualizzatore Secret Manager (roles/secretmanager.viewer) per il secret, il progetto, la cartella o l'organizzazione.

I ruoli IAM (Identity and Access Management) non possono essere concessi a una versione del secret. Per ulteriori informazioni, consulta Controllo dell'accesso con IAM.

Aggiungere annotazioni a un secret

Puoi aggiungere annotazioni al momento della creazione di un nuovo secret o dell'aggiornamento di uno esistente. I metadati in un'annotazione vengono memorizzati come coppie chiave-valore. Per aggiungere annotazioni, utilizza uno dei seguenti metodi:

Console

  1. Vai alla pagina Secret Manager nella console Google Cloud.

    Vai a Secret Manager

  2. Nella pagina Secret Manager, fai clic sulla scheda Secret regionali e poi su Crea secret regionale.

  3. Nella pagina Crea secret regionale, inserisci un nome per il secret nel campo Nome.

  4. Inserisci un valore per il secret (ad esempio abcd1234). Puoi anche caricare un file di testo contenente il valore del secret utilizzando l'opzione Carica file. Questa azione crea automaticamente la versione del secret.

  5. Seleziona la posizione in cui vuoi che venga archiviato il secret regionale dall'elenco Regione.

  6. Vai alla sezione Annotazioni e fai clic su Aggiungi annotazione.

  7. Inserisci la chiave e il valore corrispondente.

  8. Fai clic su Crea secret.

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • SECRET_ID: l'ID della secret o l'identificatore completo della secret
  • LOCATION: la località di Google Cloud del segreto
  • KEY: la chiave di annotazione
  • VALUE: il valore corrispondente della chiave di annotazione

Esegui il seguente comando:

Linux, macOS o Cloud Shell

gcloud secrets create SECRET_ID --location=LOCATION \
    --set-annotations=KEY1=VAL1,KEY2=VAL2

Windows (PowerShell)

gcloud secrets create SECRET_ID --location=LOCATION `
    --set-annotations=KEY1=VAL1,KEY2=VAL2

Windows (cmd.exe)

gcloud secrets create SECRET_ID --location=LOCATION ^
    --set-annotations=KEY1=VAL1,KEY2=VAL2

La risposta contiene il secret e le annotazioni.

REST

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • LOCATION: la località di Google Cloud del segreto
  • PROJECT_ID: l'ID progetto Google Cloud
  • SECRET_ID: l'ID della secret o l'identificatore completo della secret
  • KEY: la chiave di annotazione
  • VALUE: il valore corrispondente della chiave di annotazione

Metodo HTTP e URL: 

PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations

Corpo JSON della richiesta: 

{'annotations': {'KEY1': 'VALUE1', 'KEY2': 'VALUE2' }}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dcd99c386\"",
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  }
}

Per aggiungere annotazioni a un secret esistente, consulta la sezione Modificare le annotazioni di questo documento.

Le chiavi di annotazione hanno i seguenti requisiti:

  • Le chiavi devono essere univoche per un secret. Non puoi ripetere una chiave nello stesso token segreto.

  • Le chiavi devono avere una lunghezza compresa tra 1 e 63 caratteri.

  • Le chiavi devono avere una codifica UTF-8 di massimo 128 byte.

  • Le chiavi devono iniziare e terminare con un carattere alfanumerico.

  • Le chiavi possono contenere trattini, trattini bassi e punti tra i caratteri alfanumerici.

  • La dimensione totale delle chiavi e dei valori delle annotazioni deve essere inferiore a 16 KB.

Modificare le annotazioni

Per modificare le annotazioni, utilizza uno dei seguenti metodi:

Console

  1. Vai alla pagina Secret Manager nella console Google Cloud.

    Vai a Secret Manager

  2. Nella pagina Secret Manager, fai clic sulla scheda Secret regionali.

  3. Individua il segreto nell'elenco e fai clic sul menu Azioni associato al segreto. Nel menu Azioni, fai clic su Modifica.

  4. Nella pagina Modifica secret, vai alla sezione Annotazioni. Qui puoi modificare il valore di un'annotazione esistente, eliminarla o aggiungerne una nuova.

  5. Dopo aver apportato le modifiche, fai clic su Aggiorna segreto.

gcloud

Modificare le annotazioni esistenti

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • SECRET_ID: l'ID del segreto o l'identificatore completo del segreto
  • LOCATION: la località di Google Cloud del segreto
  • KEY: la chiave di annotazione
  • VALUE: il valore corrispondente della chiave di annotazione

Esegui il seguente comando:

Linux, macOS o Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION --update-annotations= KEY=VAL

Windows (PowerShell)

gcloud secrets update SECRET_ID --location=LOCATION --update-annotations= KEY=VAL

Windows (cmd.exe)

gcloud secrets update SECRET_ID --location=LOCATION --update-annotations= KEY=VAL

La risposta modifica il segreto e le annotazioni.

Rimuovere un'annotazione specifica

Per rimuovere le annotazioni, utilizza il seguente comando:

gcloud secrets update SECRET_ID --location=LOCATION --remove-annotations= KEY=VAL

Cancella tutte le annotazioni

Per cancellare tutte le annotazioni, utilizza il seguente comando:

gcloud secrets update SECRET_ID --location=LOCATION --clear-annotations

REST

Per cancellare tutte le annotazioni, utilizza il seguente comando:

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • LOCATION: la località di Google Cloud del segreto
  • PROJECT_ID: l'ID progetto Google Cloud
  • SECRET_ID: l'ID del segreto o l'identificatore completo del segreto

Metodo HTTP e URL: 

PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations

Corpo JSON della richiesta: 

{'annotations': {}}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dd90b37e7\""
}

Visualizza annotazioni

Per visualizzare le annotazioni allegate a un segreto, utilizza uno dei seguenti metodi:

Console

  1. Vai alla pagina Secret Manager nella console Google Cloud.

    Vai a Secret Manager

  2. Nella pagina Secret Manager, fai clic sulla scheda Secret regionali e poi sul secret di cui vuoi visualizzare le annotazioni.

  3. Viene visualizzata la pagina dei dettagli del secret. Fai clic sulla scheda Panoramica. Qui puoi vedere le annotazioni associate al segreto. Le chiavi sono elencate nella colonna a sinistra mentre i valori vengono visualizzati nella colonna a destra.

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • SECRET_ID: l'ID del segreto o l'identificatore completo del segreto
  • LOCATION: la località di Google Cloud del segreto

Esegui il seguente comando:

Linux, macOS o Cloud Shell

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (PowerShell)

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (cmd.exe)

gcloud secrets describe SECRET_ID --location=LOCATION

La risposta contiene il secret e le annotazioni.

REST

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • LOCATION: la località di Google Cloud del segreto
  • PROJECT_ID: l'ID progetto Google Cloud
  • SECRET_ID: l'ID del segreto o l'identificatore completo del segreto

Metodo HTTP e URL: 

GET https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID

Corpo JSON della richiesta: 

{}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dcd99c386\"",
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  }
}

Passaggi successivi