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

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

In alcuni casi, due processi che aggiornano la stessa risorsa in parallelo possono interferire tra loro, in quanto il secondo processo sovrascrive l'attività del primo.

Gli ETag forniscono un mezzo per controllo della contemporaneità ottimistico consentendo ai processi di vedere se una risorsa è stata modificata prima di intervenire.

Utilizzare gli 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 del secret. Tutte le altre richieste accettano un parametro etag facoltativo.

Se viene fornito un ETag che corrisponde all'ETag della risorsa corrente, la richiesta riesce. In caso contrario, non va a buon fine con 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 aggiornati per ciascuna delle richieste di modifica elencate sopra. Una richiesta di modifica aggiorna solo l'ETag della risorsa a cui si applica. In altre parole, l'aggiornamento di una versione del secret non influisce sull'ETag del secret e viceversa.

Un aggiornamento della risorsa senza operazioni aggiorna anche l'ETag della risorsa. Ad esempio, consideriamo il seguente scenario: un chiamante invia una richiesta per attivare una versione di un segreto già attivata, senza esserne a conoscenza. La richiesta viene elaborata correttamente, non modifica lo stato della versione, ma modifica l'ETag della versione. Un altro chiamante, che utilizza l'ETag precedente, tenta di disattivare la stessa versione. La richiesta non va a buon fine perché abbiamo rilevato l'intenzione di attivare la versione precedente alla richiesta di disattivazione nell'ETag modificato.

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

Utilizzo

Eliminare un secret con gli etag

Questo esempio mostra l'utilizzo di ETag durante l'eliminazione di un secret. Se il secret è stato modificato da un'altra procedura, l'operazione di eliminazione non andrà a buon fine.

gcloud

Per utilizzare Secret Manager sulla riga di comando, installa o esegui l'upgrade alla versione 378.0.0 o successiva di Google Cloud CLI. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.

L'etag deve includere le virgolette. Ad esempio, se il valore etag fosse "abc", il valore con caratteri di escape della 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. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.

L'etag viene specificato all'interno della stringa di query dell'URL e deve essere con codifica URL. Ad esempio, se il valore etag fosse "abc", il valore con codifica URL sarebbe %22abc%22 perché il carattere virgolette è codificato come %22.

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

Aggiornare un secret con gli ETag

Questo esempio 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

Per utilizzare Secret Manager sulla riga di comando, installa o esegui l'upgrade alla versione 378.0.0 o successiva di Google Cloud CLI. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.

L'etag deve includere le virgolette. Ad esempio, se il valore etag fosse "abc", il valore con caratteri di escape della 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

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

L'etag viene specificato come campo in Secret e deve includere le virgolette di delimitazione. Ad esempio, se il valore etag fosse "abc", il valore con caratteri di escape JSON sarebbe {"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"}}'

Aggiornare una versione del secret con gli ETag

Questo esempio mostra l'utilizzo di ETag durante l'aggiornamento di una versione del secret. Se la versione del segreto è stata modificata da un altro processo, l'operazione di aggiornamento non andrà a buon fine.

gcloud

Per utilizzare Secret Manager sulla riga di comando, installa o esegui l'upgrade alla versione 378.0.0 o successiva di Google Cloud CLI. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.

L'etag deve includere le virgolette. Ad esempio, se il valore etag fosse "abc", il valore con caratteri di escape della shell sarebbe "\"abc\"".

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

Puoi anche specificare gli ETag durante altre operazioni di mutazione delle versioni dei secret:

API

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

L'etag viene specificato come campo in SecretVersion e deve includere le virgolette. Ad esempio, se il valore etag fosse "abc", il valore con caratteri di escape JSON sarebbe {"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