Utiliser des tags d'entité pour un contrôle de simultanéité optimiste

Secret Manager permet d'utiliser des tags d'entité (ETag) pour un contrôle de simultanéité optimiste.

Dans certains cas, deux processus mettant à jour la même ressource en parallèle peuvent interférer les uns avec les autres, ce qui risque d'écraser l'autre processus.

Les ETags offrent un moyen de contrôler la simultanéité optimiste en permettant aux processus de vérifier si une ressource a été modifiée avant d'agir sur cette ressource.

Utiliser des ETags avec Secret Manager

Les requêtes de modification de ressources suivantes sont compatibles avec les ETags :

Dans une requête secrets.patch, l'ETag de la requête est intégré aux données du Secret. Toutes les autres requêtes acceptent un paramètre etag facultatif.

Si un ETag est fourni et correspond à l'ETag actuel de la ressource, la requête aboutit. Sinon, l'opération échoue avec une erreur FAILED_PRECONDITION et un code d'état HTTP 400. Si aucun ETag n'est fourni, la requête continue sans vérifier la valeur ETag actuellement stockée.

Les ETags des ressources sont générés lors de la création de la ressource (projects.secrets.create, projects.secrets.addVersion) et mis à jour pour chacune des requêtes de modifications répertoriées ci-dessus. Une requête de modification ne met à jour que l'ETag de la ressource à laquelle il s'applique. Autrement dit, la mise à jour de la version d'un secret n'affecte pas l'ETag du secret et vice versa.

Une mise à jour de ressource sans opération met également à jour l'ETag de la ressource. Par exemple, considérons le scénario suivant : un appelant émet une requête pour activer une version de secret déjà activée, à son insu. La requête a bien été traitée, mais ne modifie pas l'état de la version, mais modifie l'ETag de la version. Un autre appelant, utilisant l'ancien ETag, tente de désactiver la même version. La requête échoue, car nous avons capturé l'intent pour activer la version avant la requête de désactivation dans l'ETag modifié.

La ressource etag est renvoyée dans la réponse chaque fois qu'une ressource (Secret ou SecretVersion) est incluse.

Utilisation

Important : Pour utiliser Secret Manager avec des charges de travail exécutées sur Compute Engine ou Google Kubernetes Engine, l'instance ou le nœud sous-jacent doit disposer du champ d'application OAuth cloud-platform. Pour en savoir plus, consultez la section Accéder à l'API Secret Manager.

Supprimer un secret avec des ETags

Montre comment utiliser les ETags lors de la suppression d'un secret. Si le secret a été modifié par un autre processus, l'opération de suppression échouera.

gcloud

Pour utiliser Secret Manager dans la ligne de commande, commencez par installer la version 378.0.0 ou une version ultérieure de la Google Cloud CLI, ou la mettre à niveau vers la version 378.0.0. Sur Compute Engine ou GKE, vous devez vous authentifier avec le champ d'application cloud-platform.

L'ETag doit inclure les guillemets environnants. Par exemple, si la valeur etag est "abc", la valeur échappée par l'interface système est "\"abc\"".

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

Vous pouvez également spécifier des ETags lors d'autres opérations de mutation de secrets :

API

Ces exemples utilisent curl pour illustrer l'utilisation de l'API. Vous pouvez générer des jetons d'accès avec gcloud auth print-access-token. Sur Compute Engine ou GKE, vous devez vous authentifier avec le champ d'application cloud-platform.

L'ETag est spécifié dans la chaîne de requête de l'URL et doit être encodé au format URL. Par exemple, si la valeur etag est "abc", la valeur encodée en URL est %22abc%22, car le caractère de guillemet est encodé comme %22.

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

Mettre à jour un secret avec des ETags

Montre comment utiliser les ETags lors de la mise à jour d'un secret. Si le secret a été modifié par un autre processus, l'opération de mise à jour échoue.

gcloud

L'ETag doit inclure les guillemets environnants. Par exemple, si la valeur etag est "abc", la valeur échappée par l'interface système est "\"abc\"".

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

Vous pouvez également spécifier des ETags lors d'autres opérations de mutation de secrets :

API

L'ETag est spécifié en tant que champ dans Secret et doit inclure les guillemets autour. Par exemple, si la valeur etag est "abc", la valeur échappée au format JSON serait {"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"}}'

Mettre à jour une version de secret avec des ETags

Montre comment utiliser les ETags lors de la mise à jour de la version d'un secret. Si la version de secret a été modifiée par un autre processus, l'opération de mise à jour échouera.

gcloud

L'ETag doit inclure les guillemets environnants. Par exemple, si la valeur etag est "abc", la valeur échappée par l'interface système est "\"abc\"".

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

Vous pouvez également spécifier des ETags lors d'autres opérations de mutation de version d'un secret :

API

L'ETag est spécifié en tant que champ dans SecretVersion et doit inclure les guillemets autour. Par exemple, si la valeur etag est "abc", la valeur échappée au format JSON serait {"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"}'

Étapes suivantes

Découvrez comment configurer des calendriers de rotation pour les secrets.
Découvrez comment modifier les secrets.
Découvrez comment configurer des notifications sur un secret.