使用 ETag 实现乐观并发控制

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

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

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

将 ETag 与 Secret Manager 结合使用

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

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

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

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

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

每当包含资源(SecretSecretVersion)时,响应中都会返回资源 etag

用量

使用 ETag 删除密文

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

gcloud

要在命令行上使用 Secret Manager,请先安装或升级到 Cloud SDK 版本 338.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,请先安装或升级到 Cloud SDK 版本 338.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,请先安装或升级到 Cloud SDK 版本 338.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"}'