使用实体标记实现乐观并发控制

Secret Manager 支持使用实体标记 (ETag) 实现乐观并发控制。

在某些情况下，并行更新同一资源的两个进程可能会相互干扰，其中后一个进程会覆盖前一个进程的工作量。

ETag 提供了一种允许乐观并发控制的方法，即允许进程在对资源执行操作之前查看资源是否已修改。

将 ETag 与 Secret Manager 搭配使用

以下资源修改请求支持 ETag：

在 secrets.patch 请求中，请求 ETag 嵌入在密文数据中。其他所有请求均接受可选 etag 参数。

如果提供 ETag 且与当前资源 ETag 匹配，则请求成功；否则，请求将失败并显示 FAILED_PRECONDITION 错误和 HTTP 状态代码 400。如果未提供 ETag，则请求将继续而不检查当前存储的 ETag 值。

资源 ETag 在创建资源时生成（projects.secrets.create、projects.secrets.addVersion），并针对上面列出的每个修改请求进行更新。修改请求仅更新它适用于的资源的 ETag。也就是说，更新 Secret 版本不会影响 Secret ETag，反之亦然。

无操作资源更新也会更新资源 ETag。例如，请考虑以下情况：调用者发出一个请求来启用已启用的 Secret 版本，但他们并不知道该版本已启用。请求处理成功，不会更改版本状态，但会更改版本 ETag。另一个使用旧版 ETag 的调用者尝试停用同一版本。他们的请求失败，因为我们在修改后的 ETag 中停用请求之前捕获了启用版本的意图。

每当包含资源（Secret 或 SecretVersion）时，响应中都会返回资源 etag。

使用情况

使用 ETag 删除密文

本部分演示了如何在删除密文时使用 ETag。如果密文被其他进程修改，则删除操作将失败。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 Google Cloud CLI 378.0.0 或更高版本。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

ETag 必须包含括起的英文引号。例如，如果 ETag 值为 "abc"，则 shell 转义值将为 "\"abc\""。

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

您还可以在其他密文变更操作期间指定 ETag：

API

这些示例使用 curl 来使用 API 演示。 您可以使用 gcloud auth print-access-token 生成访问令牌。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

ETag 被指定为网址查询字符串的一部分，并且必须采用网址编码。例如，如果 ETag 值为 "abc"，则网址编码值将为 %22abc%22，因为英文引号字符编码为 %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"，则 shell 转义值将为 "\"abc\""。

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

您还可以在其他密文变更操作期间指定 ETag：

API

这些示例使用 curl 来使用 API 演示。 您可以使用 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 更新 Secret 版本

本部分演示了如何在更新密文版本时使用 ETag。如果密文版本被其他进程修改，则更新操作将失败。

gcloud

如需在命令行中使用 Secret Manager，请先安装或升级到 Google Cloud CLI 378.0.0 或更高版本。在 Compute Engine 或 GKE 上，您必须使用 cloud-platform 范围进行身份验证。

ETag 必须包含括起的英文引号。例如，如果 ETag 值为 "abc"，则 shell 转义值将为 "\"abc\""。

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

您还可以在其他密文版本变更操作期间指定 ETag：

API

这些示例使用 curl 来使用 API 演示。 您可以使用 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"}'

后续步骤