Control de simultaneidad optimista con ETags

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.

Las ETags 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 sobre él.

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 ETag 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 viceversa.

Una actualización de recurso sin operación también actualiza la ETag de recurso. Por ejemplo, imagina la siguiente situación: un emisor emite una solicitud para habilitar una versión del secreto que ya está habilitada, sin que lo tenga en cuenta. La solicitud se procesa de forma correcta, no cambia el estado de la versión, pero cambia la versión de ETag. Otro emisor, que usa la ETag anterior, intenta inhabilitar la misma versión. Su solicitud falla, ya que capturamos el intent para habilitar la versión antes de la solicitud de inhabilitación en la ETag modificada.

El recurso etag se muestra en la respuesta cada vez que se incluye un recurso (Secret o SecretVersion).

Uso

Borra un secreto con ETags

Esto demuestra el uso de ETags cuando se borra un secreto. Si otro proceso modificó el secreto, la operación de eliminación fallará.

gcloud

Para usar Secret Manager en la línea de comandos, primero Instala o actualiza a la versión 338.0.0 o superior del SDK de Cloud. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.

La ETag debe incluir las comillas. Por ejemplo, si el valor de Etag era "abc", el valor de escape de shell sería "\"abc\"".

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

También puedes especificar ETags durante otras operaciones de mutación secretas:

API

En estos ejemplos, se usa curl para demostrar el uso de la API. Puedes generar tokens de acceso con gcloud auth print-access-token. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.

La ETag se especifica como parte de la string de consulta de la URL y debe estar codificada como URL. Por ejemplo, si el valor de ETag era "abc", el valor codificado en URL sería %22abc%22 porque el carácter de comillas está codificado como %22.

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

Actualiza un secreto con ETags

A continuación, se demuestra cómo usar ETags cuando se actualiza un secreto. Si otro proceso modificó el secreto, la operación de actualización fallará.

gcloud

Para usar Secret Manager en la línea de comandos, primero Instala o actualiza a la versión 338.0.0 o superior del SDK de Cloud. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.

La ETag debe incluir las comillas. Por ejemplo, si el valor de Etag era "abc", el valor de escape de shell sería "\"abc\"".

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

También puedes especificar ETags durante otras operaciones de mutación secretas:

API

En estos ejemplos, se usa curl para demostrar el uso de la API. Puedes generar tokens de acceso con gcloud auth print-access-token. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.

La ETag se especifica como un campo en Secret y debe incluir las comillas. Por ejemplo, si el valor de ETag era "abc", el valor de escape de JSON sería {"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"}}'

Actualiza una versión del secreto con ETags

A continuación, se demuestra 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

Para usar Secret Manager en la línea de comandos, primero Instala o actualiza a la versión 338.0.0 o superior del SDK de Cloud. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.

La ETag debe incluir las comillas. Por ejemplo, si el valor de Etag era "abc", el valor de escape de shell sería "\"abc\"".

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

También puedes especificar ETags durante otras operaciones de mutación de versiones de secretos:

API

En estos ejemplos, se usa curl para demostrar el uso de la API. Puedes generar tokens de acceso con gcloud auth print-access-token. En Compute Engine o GKE, debes autenticarte con el permiso cloud-platform.

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\""}.

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"}'