Secret Manager supporta l'utilizzo dei tag entità (ETag) per 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, analogamente, l'aggiornamento dell'ETag non influisce sulla versione del secret.
Anche se un aggiornamento non modifica lo stato di una risorsa, aggiorna comunque l'ETag della risorsa.
Considera l'esempio seguente:
-
L'utente 1 tenta di attivare una versione del secret senza sapere che è già attivata. Il sistema elabora questa richiesta, senza modificare nulla tranne l'ETag della versione.
-
L'utente 2, utilizzando il vecchio ETag, tenta di disattivare la versione.
-
L'operazione non va a buon fine perché il sistema riconosce l'ETag più recente, che indica un'intenzione più recente di mantenere attiva la versione.
Anche gli aggiornamenti apparentemente minori sono importanti a causa delle modifiche all'ETag. Ciò garantisce la coerenza dei dati, soprattutto con più utenti o sistemi che interagiscono con la stessa risorsa.
La risorsa etag
viene restituita nella risposta ogni volta che è inclusa una risorsa (Secret o SecretVersion).
Eliminare un secret con gli ETag
Questa sezione descrive l'utilizzo degli ETag per l'eliminazione di un secret. Se il segreto è stato modificato da un altro processo, l'operazione di eliminazione non va a buon fine.
gcloud
Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:
- SECRET_ID: l'ID del secret o l'identificatore completo del secret.
- LOCATION: la località di Google Cloud del segreto.
- ETAG: il tag dell'entità del segreto. L'ETag deve includere le virgolette.
Ad esempio, se il valore ETag fosse
"abc"
, il valore con escape shell sarebbe"\"abc\""
.
Esegui il seguente comando:
Linux, macOS o Cloud Shell
gcloud secrets delete SECRET_ID --location=LOCATION \ --etag "ETAG"
Windows (PowerShell)
gcloud secrets delete SECRET_ID --location=LOCATION ` --etag "ETAG"
Windows (cmd.exe)
gcloud secrets delete SECRET_ID --location=LOCATION ^ --etag "ETAG"
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 secret o l'identificatore completo del secret.
- ETAG: il tag dell'entità del segreto. L'ETag viene specificato all'interno della stringa di query dell'URL
e deve essere codificato nell'URL. Ad esempio, se il valore ETag è
"abc"
, il valore con codifica URL sarà%22abc%22
perché il carattere virgolette è codificato come%22
.
Metodo HTTP e URL:
DELETE https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?etag=ETAG
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 DELETE \
-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?etag=ETAG"
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 DELETE `
-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?etag=ETAG" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente:
{}
Go
Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.
Java
Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Java e installare l'SDK Java di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.
Python
Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Python e installare l'SDK Python di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.
Aggiornare un secret con gli ETag
Questa sezione descrive l'utilizzo degli 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
Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:
- SECRET_ID: l'ID del secret o l'identificatore completo del secret.
- LOCATION: la località di Google Cloud del segreto.
- KEY: il nome dell'etichetta.
- VALUE: il valore dell'etichetta corrispondente.
- ETAG: il tag dell'entità del segreto. L'ETag deve includere le virgolette.
Ad esempio, se il valore ETag fosse
"abc"
, il valore con escape shell sarebbe"\"abc\""
.
Esegui il seguente comando:
Linux, macOS o Cloud Shell
gcloud secrets update SECRET_ID --location=LOCATION \ --update-labels "KEY=VALUE" \ --etag "ETAG"
Windows (PowerShell)
gcloud secrets update SECRET_ID --location=LOCATION ` --update-labels "KEY=VALUE" ` --etag "ETAG"
Windows (cmd.exe)
gcloud secrets update SECRET_ID --location=LOCATION ^ --update-labels "KEY=VALUE" ^ --etag "ETAG"
La risposta restituisce il segreto.
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 secret o l'identificatore completo del secret.
- ETAG: il tag dell'entità del segreto. L'ETag è specificato come campo nel
Secret
e deve includere le virgolette. Ad esempio, se il valore ETag fosse
"abc"
, il valore con caratteri JSON speciali sarebbe{"etag":"\"abc\""}
. - KEY: il nome dell'etichetta.
- VALUE: il valore dell'etichetta corrispondente.
Metodo HTTP e URL:
PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=labels
Corpo JSON della richiesta:
{"etag":"ETAG", "labels":{"KEY": "VALUE"}}
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=labels"
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=labels" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente:
{ "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID", "createTime": "2024-09-04T04:06:00.660420Z", "labels": { "KEY": "VALUE" }, "etag": "\"162145a4f894d5\"" }
Go
Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.
Java
Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Java e installare l'SDK Java di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.
Python
Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Python e installare l'SDK Python di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.
Aggiornare una versione del secret con gli ETag
Questa sezione descrive 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
Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:
- VERSION_ID: l'ID della versione del secret.
- SECRET_ID: l'ID del secret o l'identificatore completo del secret.
- LOCATION: la località di Google Cloud del segreto.
- ETAG: il tag dell'entità. L'ETag deve includere le virgolette.
Ad esempio, se il valore ETag fosse
"abc"
, il valore con escape shell sarebbe"\"abc\""
.
Esegui il seguente comando:
Linux, macOS o Cloud Shell
gcloud secrets versions disable VERSION_ID \ --secret SECRET_ID \ --location=LOCATION \ --etag "ETAG"
Windows (PowerShell)
gcloud secrets versions disable VERSION_ID ` --secret SECRET_ID ` --location=LOCATION ` --etag "ETAG"
Windows (cmd.exe)
gcloud secrets versions disable VERSION_ID ^ --secret SECRET_ID ^ --location=LOCATION ^ --etag "ETAG"
La risposta restituisce il segreto.
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
- VERSION_ID: l'ID della versione del secret
- ETAG: il tag entità della versione del secret. L'ETag è specificato come campo in SecretVersion e deve includere le virgolette. Ad esempio, se il valore ETag fosse
"abc"
, il valore con caratteri JSON speciali sarebbe{"etag":"\"abc\""}
.
Metodo HTTP e URL:
POST https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID:disable
Corpo JSON della richiesta:
{"etag":"ETAG"}
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 POST \
-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/versions/VERSION_ID:disable"
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 POST `
-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/versions/VERSION_ID:disable" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente:
{ "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID", "createTime": "2024-09-04T06:41:57.859674Z", "state": "DISABLED", "etag": "\"1621457b3c1459\"" }
Go
Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Go e installare l'SDK Go di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.
Java
Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Java e installare l'SDK Java di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.
Python
Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Python e installare l'SDK Python di Secret Manager. Su Compute Engine o GKE, devi autenticarti con l'ambito cloud-platform.
L'esempio di codice riportato di seguito descrive l'attivazione di una versione del segreto con gli ETag. Puoi anche specificare gli ETag durante altre operazioni di mutazione dei secret, ad esempio quando disattivi o elimini le versioni dei secret. Consulta gli esempi di codice per Secret Manager.
Passaggi successivi
- Creare pianificazioni della rotazione
- Modificare un secret regionale
- Configurare le notifiche su un secret regionale