Secret Manager admite el uso de etiquetas de entidad (ETags) para el control de simultaneidad optimista.
En algunos casos, dos procesos que actualizan el mismo recurso en paralelo pueden interferir entre sí, en el que el último proceso reemplaza el esfuerzo del primero.
Los ETag proporcionan un medio para el control de simultaneidad optimista, ya que permiten que los procesos vean si un recurso se modificó antes de tomar medidas en ese recurso.
Usa ETags con Secret Manager
Las siguientes solicitudes de modificación de recursos admiten ETags:
En una solicitud secrets.patch, la solicitud ETag se incorpora en los datos Secret. Todas las demás solicitudes aceptan un parámetro etag
opcional.
Si se proporciona una ETag y coincide con la ETag del recurso actual, la solicitud se realiza de forma correcta. De lo contrario, falla con un error FAILED_PRECONDITION
y un código de estado HTTP 400. Si no se proporciona una ETag, la solicitud continúa sin verificar el valor de ETag almacenado en el momento.
Las ETags de recursos se generan durante la creación de recursos (projects.secrets.create, projects.secrets.addVersion) y se actualizan para cada una de las solicitudes de modificación mencionadas antes. Una solicitud de modificación solo actualiza la ETag del recurso al que se aplica. Es decir, la actualización de una versión del secreto no afecta el ETag de secreto y, de manera similar, la actualización del ETag no afecta la versión del secreto.
Incluso si una actualización no cambia el estado de un recurso, se actualiza la ETag del recurso.
Considera el siguiente ejemplo:
-
El usuario 1 intenta habilitar una versión secreta sin saber que ya está habilitada. El sistema lo procesa, sin cambiar nada más que la ETag de la versión.
-
El usuario 2, que usa la ETag anterior, intenta inhabilitar la versión.
-
Esto falla porque el sistema reconoce la ETag más reciente, que indica un intent más reciente para mantener la versión habilitada.
Incluso las actualizaciones que parecen menores son importantes debido a los cambios en la ETag. Esto garantiza la coherencia de los datos, en especial con varios usuarios o sistemas que interactúan con el mismo recurso.
El recurso etag
se muestra en la respuesta cada vez que se incluye un recurso (Secret o SecretVersion).
Borra un secreto con ETags
En esta sección, se describe cómo usar ETags cuando se borra un secreto. Si otro proceso modificó el secreto, la operación de eliminación fallará.
gcloud
Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:
- SECRET_ID: El ID del secreto o el identificador completamente calificado del secreto.
- LOCATION: Es la ubicación de Google Cloud del secreto.
- ETAG: Es la etiqueta de entidad del secreto. La ETag debe incluir las comillas.
Por ejemplo, si el valor de ETag era
"abc"
, el valor de escape de shell sería"\"abc\""
.
Ejecuta el siguiente 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
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- LOCATION: Es la ubicación de Google Cloud del secreto.
- PROJECT_ID: el ID del proyecto de Google Cloud.
- SECRET_ID: El ID del secreto o el identificador completamente calificado del secreto.
- ETAG: Es la etiqueta de entidad del secreto. La ETag se especifica como parte de la cadena de consulta de la URL y debe estar codificada como URL. Por ejemplo, si el valor de ETag es
"abc"
, el valor codificado en URL sería%22abc%22
porque el carácter de comillas está codificado como%22
.
Método HTTP y URL:
DELETE https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?etag=ETAG
Cuerpo JSON de la solicitud:
{}
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
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
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$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
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{}
Go
Para ejecutar este código, primero configura un entorno de desarrollo de Go e instala el SDK de Go para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.
Java
Para ejecutar este código, primero configura un entorno de desarrollo de Java e instala el SDK de Java para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.
Python
Para ejecutar este código, primero configura un entorno de desarrollo de Python e instala el SDK de Python para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.
Actualiza un secreto con ETags
En esta sección, se describe cómo usar ETags cuando se actualiza un secreto. Si otro proceso modificó el secreto, la operación de actualización fallará.
gcloud
Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:
- SECRET_ID: El ID del secreto o el identificador completamente calificado del secreto.
- LOCATION: Es la ubicación de Google Cloud del secreto.
- KEY: es el nombre de la etiqueta.
- VALUE: Es el valor de la etiqueta correspondiente.
- ETAG: Es la etiqueta de entidad del secreto. La ETag debe incluir las comillas.
Por ejemplo, si el valor de ETag era
"abc"
, el valor de escape de shell sería"\"abc\""
.
Ejecuta el siguiente 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 respuesta muestra el Secret.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- LOCATION: Es la ubicación de Google Cloud del secreto.
- PROJECT_ID: el ID del proyecto de Google Cloud.
- SECRET_ID: El ID del secreto o el identificador completamente calificado del secreto.
- ETAG: Es la etiqueta de entidad del secreto. La ETag se especifica como un campo en Secreto y debe incluir las comillas. Por ejemplo, si el valor de ETag era
"abc"
, el valor de escape de JSON sería{"etag":"\"abc\""}
. - KEY: es el nombre de la etiqueta.
- VALUE: Es el valor de la etiqueta correspondiente.
Método HTTP y URL:
PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=labels
Cuerpo JSON de la solicitud:
{"etag":"ETAG", "labels":{"KEY": "VALUE"}}
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
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
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$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
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{ "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID", "createTime": "2024-09-04T04:06:00.660420Z", "labels": { "KEY": "VALUE" }, "etag": "\"162145a4f894d5\"" }
Go
Para ejecutar este código, primero configura un entorno de desarrollo de Go e instala el SDK de Go para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.
Java
Para ejecutar este código, primero configura un entorno de desarrollo de Java e instala el SDK de Java para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.
Python
Para ejecutar este código, primero configura un entorno de desarrollo de Python e instala el SDK de Python para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.
Actualiza una versión del secreto con ETags
En esta sección, se describe cómo usar ETags cuando se actualiza una versión de un secreto. Si otro proceso modificó la versión del secreto, la operación de actualización fallará.
gcloud
Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:
- VERSION_ID: El ID de la versión del secreto.
- SECRET_ID: El ID del secreto o el identificador completamente calificado del secreto.
- LOCATION: Es la ubicación de Google Cloud del secreto.
- ETAG: Es la etiqueta de entidad. La ETag debe incluir las comillas.
Por ejemplo, si el valor de ETag era
"abc"
, el valor de escape de shell sería"\"abc\""
.
Ejecuta el siguiente 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 respuesta muestra el Secret.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- LOCATION: La ubicación de Google Cloud del secreto
- PROJECT_ID: El ID del proyecto de Google Cloud
- SECRET_ID: El ID del Secret o el identificador completamente calificado del Secret
- VERSION_ID: El ID de la versión del Secret
- ETAG: Es la etiqueta de entidad de la versión del secreto. La ETag se especifica como un campo en SecretVersion y debe incluir las comillas. Por ejemplo, si el valor de ETag era
"abc"
, el valor de escape de JSON sería{"etag":"\"abc\""}
.
Método HTTP y URL:
POST https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID:disable
Cuerpo JSON de la solicitud:
{"etag":"ETAG"}
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
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
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$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
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{ "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID", "createTime": "2024-09-04T06:41:57.859674Z", "state": "DISABLED", "etag": "\"1621457b3c1459\"" }
Go
Para ejecutar este código, primero configura un entorno de desarrollo de Go e instala el SDK de Go para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.
Java
Para ejecutar este código, primero configura un entorno de desarrollo de Java e instala el SDK de Java para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.
Python
Para ejecutar este código, primero configura un entorno de desarrollo de Python e instala el SDK de Python para Secret Manager. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.
En la muestra de código, se describe cómo habilitar una versión secreta con ETags. También puedes especificar ETags durante otras operaciones de mutación de secretos, como cuando inhabilitas o destruyes versiones de secretos. Consulta las muestras de código de Secret Manager.
¿Qué sigue?
- Crea programas de rotación
- Cómo editar un Secret regional
- Cómo configurar notificaciones en un secreto regional