オプティミスティック同時実行制御にエンティティ タグを使用する

Secret Manager は、オプティミスティック同時実行制御でのエンティティ タグ（ETag）の使用に対応しています。

場合によっては、同じリソースを並行して更新する 2 つのプロセスが互いに干渉することがあり、後のプロセスが前のプロセスの結果を上書きします。

ETag は、リソースに対してアクションを行う前に、リソースが変更されているかどうかをプロセスが確認できるようにすることで、オプティミスティック同時実行制御への手段を提供します。

Secret Manager で ETag を使用する

次のリソース変更リクエストは ETag をサポートします。

secrets.patch リクエストでは、リクエストの ETag が Secret データに埋め込まれます。他のすべてのリクエストは、オプションの etag パラメータを受け入れます。

ETag が指定され、現在のリソースの ETag と一致すると、リクエストは成功します。それ以外の場合は、FAILED_PRECONDITION エラーと HTTP ステータス コード 400 で失敗します。ETag が指定されていない場合、リクエストは現在格納されている ETag 値を確認せずに続行します。

リソース ETag はリソース作成時に生成され（projects.secrets.create、projects.secrets.addVersion）、上記の変更リクエストごとに更新されます。変更リクエストでは、適用先のリソースの ETag のみが更新されます。つまり、シークレット バージョンを更新してもシークレットの ETag には影響せず、その逆も同様です。

オペレーションが不要のリソースを更新すると、リソースの ETag も更新されます。たとえば、次のシナリオを考えてみます。呼び出し元が、知らないうちにすでに有効になっているシークレット バージョンを有効にするリクエストを発行します。リクエストは正常に処理され、バージョンの状態は変更されませんが、バージョン ETag が変更されます。別の呼び出し元が、古い ETag を使用して同じバージョンを無効にしようとします。変更された ETag で無効化リクエストの前にバージョンを有効にするインテントをキャプチャしたため、このリクエストは失敗します。

リソース etag は、リソース（Secret または SecretVersion）が含まれている場合にレスポンスで返されます。

使用方法

ETag を使用してシークレットを削除する

ここでは、シークレットを削除する際に ETag を使用する方法を示しています。シークレットが別のプロセスによって変更されている場合、削除のオペレーションは失敗します。

gcloud

Secret Manager をコマンドラインで使用するには、まず Google Cloud CLI のバージョン 378.0.0 以降をインストールまたはアップグレードします。 Compute Engine または GKE では、cloud-platform スコープを使用して認証する必要があります。

ETag には、引用符を含める必要があります。たとえば、ETag 値が "abc" の場合、シェルのエスケープ値は "\"abc\"" になります。

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

他のシークレットのミューテーション オペレーション中に ETag を指定することもできます。

API

次の例では、API の使用を示すために curl を使用します。gcloud auth print-access-token を使用してアクセス トークンを生成できます。 Compute Engine または GKE では、cloud-platform スコープを使用して認証する必要があります。

etag は、URL のクエリ文字列の一部として指定され、URL エンコードされている必要があります。たとえば、etag 値が "abc" の場合、引用符が %22 としてエンコードされるため、URL エンコード値は %22abc%22 になります。

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

ETag を使用してシークレットを更新する

ここでは、シークレットの更新時に ETag を使用する方法を示しています。シークレットが別のプロセスによって変更されている場合、更新のオペレーションは失敗します。

gcloud

Secret Manager をコマンドラインで使用するには、まず Google Cloud CLI のバージョン 378.0.0 以降をインストールまたはアップグレードします。 Compute Engine または GKE では、cloud-platform スコープを使用して認証する必要があります。

ETag には、引用符を含める必要があります。たとえば、ETag 値が "abc" の場合、シェルのエスケープ値は "\"abc\"" になります。

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

他のシークレットのミューテーション オペレーション中に ETag を指定することもできます。

API

次の例では、API の使用を示すために curl を使用します。gcloud auth print-access-token を使用してアクセス トークンを生成できます。 Compute Engine または GKE では、cloud-platform スコープを使用して認証する必要があります。

ETag は Secret のフィールドとして指定され、引用符を含む必要があります。たとえば、ETag 値が "abc" の場合、JSON のエスケープ値は {"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"}}'

ETag を使用してシークレット バージョンを更新する

ここでは、シークレット バージョンの更新時に ETag を使用する方法を示しています。シークレット バージョンが別のプロセスによって変更されている場合、更新のオペレーションは失敗します。

gcloud

Secret Manager をコマンドラインで使用するには、まず Google Cloud CLI のバージョン 378.0.0 以降をインストールまたはアップグレードします。 Compute Engine または GKE では、cloud-platform スコープを使用して認証する必要があります。

ETag には、引用符を含める必要があります。たとえば、ETag 値が "abc" の場合、シェルのエスケープ値は "\"abc\"" になります。

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

他のシークレット バージョンのミューテーション オペレーション中に ETag を指定することもできます。

API

次の例では、API の使用を示すために curl を使用します。gcloud auth print-access-token を使用してアクセス トークンを生成できます。 Compute Engine または GKE では、cloud-platform スコープを使用して認証する必要があります。

ETag は SecretVersion のフィールドとして指定され、引用符を含む必要があります。たとえば、ETag 値が "abc" の場合、JSON のエスケープ値は {"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"}'

次のステップ