Utilizzare i tag entità per il controllo ottimistico della contemporaneità

Secret Manager supporta l'utilizzo di tag entità (ETag) per un controllo ottimistico della contemporaneità.

In alcuni casi, due processi che aggiornano la stessa risorsa in parallelo possono interferire l'uno con l'altro, dove il secondo processo sovrascrive lo sforzo del primo.

Gli etag offrono un mezzo per controllo della contemporaneità in modo ottimistico, consentendo ai processi di verificare se una risorsa è stata modificata prima di intraprendere un'azione sulla risorsa.

Utilizzo di ETag con Secret Manager

Le seguenti richieste di modifica delle risorse supportano gli ETag:

In una richiesta secrets.patch, l'ETag della richiesta è incorporato nei dati Secret. Tutte le altre richieste accettano un parametro etag facoltativo.

Se viene fornito un ETag che corrisponde all'attuale ETag della risorsa, la richiesta ha esito positivo; in caso contrario, non riesce e restituisce un errore FAILED_PRECONDITION e un codice di stato HTTP 400. Se non viene fornito un ETag, la richiesta procede senza controllare il valore ETag attualmente memorizzato.

Gli ETag delle risorse vengono generati al momento della creazione della risorsa (projects.secrets.create, projects.secrets.addVersion) e vengono aggiornati per ogni richiesta di modifica riportata sopra. Una richiesta di modifica aggiorna solo l'ETag della risorsa a cui si applica. Ciò significa che l'aggiornamento di una versione del secret non influisce sull'ETag del secret e viceversa.

Un aggiornamento delle risorse non operative aggiorna anche l'ETag della risorsa. Ad esempio, considera lo scenario seguente: un chiamante invia una richiesta di abilitazione di una versione del secret già abilitata, a sua insaputa. La richiesta viene elaborata correttamente, non modifica lo stato della versione, ma cambia l'ETag della versione. Un altro chiamante, utilizzando l'ETag precedente, tenta di disattivare la stessa versione. La richiesta non va a buon fine, poiché abbiamo acquisito l'intento di abilitare la versione prima della richiesta di disattivazione nell'ETag modificato.

La risorsa etag viene restituita nella risposta ogni volta che viene inclusa una risorsa (Secret o SecretVersion).

Utilizzo

Importante: per utilizzare Secret Manager con carichi di lavoro in esecuzione su Compute Engine o Google Kubernetes Engine, l'istanza o il nodo sottostante deve avere l'ambito OAuth cloud-platform. Consulta la pagina relativa all'accesso all'API Secret Manager per maggiori informazioni.

Elimina un secret con etag

In questo modo viene spiegato come utilizzare gli etag durante l'eliminazione di un secret. Se il secret è stato modificato da un altro processo, l'operazione di eliminazione non andrà a buon fine.

gcloud

Per utilizzare Secret Manager nella riga di comando, devi prima installare Google Cloud CLI o eseguirne l'upgrade alla versione 378.0.0 o successiva. In Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.

L'etag deve includere le virgolette circostanti. Ad esempio, se il valore etag era "abc", il valore con escape shell sarebbe "\"abc\"".

gcloud beta secrets delete "SECRET_ID" \
    --etag "ETAG"

Puoi anche specificare gli etag durante altre operazioni di mutazione dei secret:

API

Questi esempi utilizzano curl per dimostrare l'utilizzo dell'API. Puoi generare token di accesso con gcloud auth print-access-token. In Compute Engine o GKE, devi eseguire l'autenticazione con l'ambito cloud-platform.

L'etag viene specificato come parte della stringa di query dell'URL e deve essere codificato come URL. Ad esempio, se il valore etag fosse "abc", il valore codificato nell'URL sarebbe %22abc%22 perché le virgolette sono codificate come %22.

curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?etag=ETAG" \
    --request "DELETE" \
    --header "Authorization: Bearer ACCESS_TOKEN"

Aggiorna un secret con etag

Questa dimostrazione mostra l'utilizzo di etag durante l'aggiornamento di un secret. Se il secret è stato modificato da un altro processo, l'operazione di aggiornamento non andrà a buon fine.

gcloud

L'etag deve includere le virgolette circostanti. Ad esempio, se il valore etag era "abc", il valore con escape shell sarebbe "\"abc\"".

gcloud beta secrets update "SECERT_ID" \
    --update-labels "foo=bar" \
    --etag "ETAG"

Puoi anche specificare gli etag durante altre operazioni di mutazione dei secret:

API

L'etag viene specificato come campo nella sezione Secret e deve includere le virgolette circostanti. Ad esempio, se il valore dell'etag era "abc", il valore con escape JSON sarà {"etag":"\"abc\""}.

curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=labels" \
    --request "PATCH" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data '{"etag":"ETAG", "labels":{"foo": "bar"}}'

Aggiorna una versione del secret con etag

Questa diapositiva illustra l'utilizzo degli etag durante l'aggiornamento di una versione del secret. Se la versione del secret è stata modificata da un altro processo, l'operazione di aggiornamento non andrà a buon fine.

gcloud

L'etag deve includere le virgolette circostanti. Ad esempio, se il valore etag era "abc", il valore con escape shell sarebbe "\"abc\"".

gcloud beta secrets versions disable "VERSION_ID" \
    --secret "SECRET_ID" \
    --etag "ETAG"

Puoi anche specificare gli etag durante altre operazioni di modifica della versione del secret:

API

L'etag viene specificato come campo nella sezione SecretVersion e deve includere le virgolette racchiuse tra loro. Ad esempio, se il valore dell'etag era "abc", il valore con escape JSON sarà {"etag":"\"abc\""}.

curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable" \
    --request "POST" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data '{"etag":"ETAG"}'

Passaggi successivi

Scopri come configurare pianificazioni di rotazione per i secret.
Scopri come modificare i secret.
Scopri come configurare le notifiche su un secret.