Entitäts-Tags für optimistische Nebenläufigkeitserkennung verwenden

Secret Manager unterstützt für die optimistische Nebenläufigkeitserkennung die Verwendung von Entitäts-Tags.

In einigen Fällen können zwei Prozesse, die dieselbe Ressource parallel aktualisieren, sich gegenseitig beeinträchtigen, wobei der letztere Vorgang die Aktionen des ersten Prozesses überschreibt.

ETags bieten eine Möglichkeit zur optimistischen Nebenläufigkeitserkennung, da sie erkennen können, ob eine Ressource geändert wurde, bevor Maßnahmen für die Ressource durchgeführt werden.

ETags mit Secret Manager verwenden

Die folgenden Ressourcenänderungsanfragen unterstützen ETags:

In einer secrets.patch-Anfrage ist die ETag-Anfrage in die Secret-Daten eingebettet. Alle anderen Anfragen akzeptieren einen optionalen etag-Parameter.

Wenn ein ETag angegeben wird und mit dem aktuellen Ressourcen-ETag übereinstimmt, ist die Anfrage erfolgreich. Andernfalls schlägt sie mit dem Fehler FAILED_PRECONDITION und dem HTTP-Statuscode 400 fehl. Wird kein ETag angegeben, wird die Anfrage fortgesetzt, ohne den aktuell gespeicherten ETag-Wert zu prüfen.

Ressourcen-ETags werden bei der Ressourcenerstellung (projects.secrets.create, projects.secrets.addVersion) generiert und für jede der oben aufgeführten Änderungsanfragen aktualisiert. Bei einer Änderungsanfrage wird nur das ETag der Ressource aktualisiert, auf die sie angewendet wird. Das heißt, das Aktualisieren einer Secret-Version wirkt sich nicht auf das Secret-ETag aus und umgekehrt.

Bei der Aktualisierung einer betriebsfreien Ressourcen wird auch das Ressourcen-ETag aktualisiert. Betrachten Sie beispielsweise das folgende Szenario: Ein Aufrufer gibt eine Anfrage aus, um eine Secret-Version zu aktivieren, die bereits aktiviert ist, ohne dass ihm dies bekannt ist. Die Anfrage wird erfolgreich verarbeitet, ändert nicht den Versionsstatus, aber ändert das Versions-ETag. Ein anderer Aufrufer, der das ältere ETag verwendet, versucht, dieselbe Version zu deaktivieren. Seine Anfrage schlägt fehl, da wir den Intent, die Version zu aktivieren, vor der Deaktivierungsanfrage im geänderten ETag erfasst haben.

Die Ressource etag wird in der Antwort zurückgegeben, wenn eine Ressource (Secret oder SecretVersion) enthalten ist.

Nutzung

Secret mit ETags löschen

Hier wird die Verwendung von ETags beim Löschen eines Secrets erläutert. Wenn das Secret durch einen anderen Prozess geändert wurde, schlägt der Löschvorgang fehl.

gcloud

Wenn Sie Secret Manager in der Befehlszeile verwenden möchten, Installieren Sie die Google Cloud CLI oder führen Sie ein Upgrade auf Version 378.0.0 oder höher durch. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

Das ETag muss die umgebenden Anführungszeichen enthalten. Wenn der ETag-Wert beispielsweise "abc" ist, lautet der Shell-Escape-Wert "\"abc\"".

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

Sie können auch ETags während anderer Vorgänge zur Änderung von Secrets angeben:

API

In diesen Beispielen wird curl verwendet, um die Verwendung mit der API zu demonstrieren. Sie können Zugriffstokens mit gcloud auth print-access-token generieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

Das ETag wird als Teil des Abfragestrings der URL angegeben und muss URL-codiert sein. Wenn der ETag-Wert beispielsweise "abc" lautet, lautet der URL-codierte Wert %22abc%22, da das Anführungszeichen als %22 codiert ist.

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

Secret mit ETags aktualisieren

Dieser Abschnitt zeigt die Verwendung von ETags beim Aktualisieren eines Secrets. Wenn das Secret durch einen anderen Prozess geändert wurde, schlägt der Aktualisierungsvorgang fehl.

gcloud

Wenn Sie Secret Manager in der Befehlszeile verwenden möchten, installieren oder aktualisieren Sie zuerst die Google Cloud CLI auf Version 378.0.0 oder höher. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

Das ETag muss die umgebenden Anführungszeichen enthalten. Wenn der ETag-Wert beispielsweise "abc" ist, lautet der Shell-Escape-Wert "\"abc\"".

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

Sie können auch ETags während anderer Vorgänge zur Änderung von Secrets angeben:

API

In diesen Beispielen wird curl verwendet, um die Verwendung mit der API zu demonstrieren. Sie können Zugriffstokens mit gcloud auth print-access-token generieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

Das ETag wird als Feld für die Secret angegeben und muss die umgebenden Anführungszeichen enthalten. Wenn der ETag-Wert beispielsweise "abc" ist, lautet der JSON-Escape-Wert {"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"}}'

Secret-Version mit ETags aktualisieren

Dieser Abschnitt zeigt die Verwendung von ETags beim Aktualisieren einer Secret-Version. Wenn die Secret-Version durch einen anderen Prozess geändert wurde, schlägt der Aktualisierungsvorgang fehl.

gcloud

Wenn Sie Secret Manager in der Befehlszeile verwenden möchten, installieren oder aktualisieren Sie zuerst die Google Cloud CLI auf Version 378.0.0 oder höher. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

Das ETag muss die umgebenden Anführungszeichen enthalten. Wenn der ETag-Wert beispielsweise "abc" ist, lautet der Shell-Escape-Wert "\"abc\"".

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

Sie können auch ETags während anderer Vorgänge zur Änderung von Secret-Versionen angeben:

API

In diesen Beispielen wird curl verwendet, um die Verwendung mit der API zu demonstrieren. Sie können Zugriffstokens mit gcloud auth print-access-token generieren. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

Das ETag wird als Feld für die SecretVersion angegeben und muss die umgebenden Anführungszeichen enthalten. Wenn der ETag-Wert beispielsweise "abc" ist, lautet der JSON-Escape-Wert {"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"}'

Nächste Schritte