此页面由 Cloud Translation API 翻译。

创建和管理注释

本页面介绍了如何向 Secret 添加注释以及如何修改和查看这些注释。

概览

您可以使用注解存储与 Secret 相关的自定义元数据。例如，您可以希望使用将装载密钥的路径为其添加注解。注解在以下方面非常有用：

根据用途、环境（开发、预演、生产）对 Secret 进行分类，敏感级别这样可以更轻松地在 Secret Manager 中搜索、过滤和整理 Secret。
指示 Secret 值的特定格式或结构，帮助工作负载解释正确。
提供有关如何使用 Secret 或处理 Secret 的任何特殊注意事项的提示。

例如，如果您有一个包含数据库密码的密钥，您可以添加如下注释：如下所示：

environment:production
purpose:database_access
owner:database_team

借助这些注释，您可以轻松确定密钥的用途、环境以及负责管理密钥的人员。此外，访问此密钥的工作负载可以使用注解来确认其是否使用了适用于生产环境的正确密码。

注释与标签不同。标签用于对资源进行排序、过滤和分组而注解用于存储密钥上任意且无法用于识别身份的元数据。这里有在标签中指定元数据时限制字符和字符长度。该存储分区中的注解可大可小、结构化或非结构化，还可以包含不允许使用的字符按标签排序。

所需的角色

为 Secret 添加注解和更新注解需要 Secret Manager Admin 针对 Secret、项目、文件夹或组织的角色 (roles/secretmanager.admin)。
如需查看注释，需要具有密文、项目、文件夹或组织的 Secret Manager 查看者角色 (roles/secretmanager.viewer)。

不能对密文版本授予 Identity and Access Management (IAM) 角色。如需了解详情，请参阅使用 IAM 进行访问权限控制。

向 Secret 添加注解

您可以在创建新 Secret 或更新现有 Secret 时添加注释。注解中的元数据以键值对的形式存储。如需添加注释，请使用以下方法之一：

控制台

转到 Google Cloud 控制台中的 Secret Manager 页面。

前往 Secret Manager
在 Secret Manager 页面上，点击创建 Secret。
在创建 Secret 页面的名称字段中，输入 Secret 的名称。
为 Secret 输入一个值（例如 abcd1234）。您还可以使用上传文件选项上传包含 Secret 值的文本文件。此操作会自动创建 Secret 版本。
转到注解部分，然后点击添加注解。
输入键和相应的值。
点击创建密钥。

gcloud

在使用下面的命令数据之前，请先进行以下替换：

SECRET_ID：Secret 的 ID 或 Secret 的完全限定标识符
KEY：注释键
VALUE：注解键的对应值

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud secrets create SECRET_ID \
    --set-annotations= KEY1=VAL1,KEY2=VAL2

Windows (PowerShell)

gcloud secrets create SECRET_ID `
    --set-annotations= KEY1=VAL1,KEY2=VAL2

Windows (cmd.exe)

gcloud secrets create SECRET_ID ^
    --set-annotations= KEY1=VAL1,KEY2=VAL2

响应包含密钥和注释。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：Google Cloud 项目 ID
SECRET_ID：密钥的 ID 或密钥的完全限定标识符
KEY：注释键
VALUE：注解键的对应值

HTTP 方法和网址：

PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations

请求 JSON 正文：

{'annotations': {'KEY1': 'VALUE1', 'KEY2': 'VALUE2' }}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dcd99c386\"",
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  }
}

如需向现有 Secret 添加注释，请参阅本文档的修改注释部分。

注解键具有以下要求：

键必须是 Secret 的唯一键。您不能在同一个密钥中重复使用密钥。
键的长度必须介于 1 到 63 个字符之间。
键的 UTF-8 编码不得超过 128 个字节。
键必须以字母数字字符开头和结尾。
键可以在字母数字字符之间包含短划线、下划线和英文句点。
注释键和值的总大小必须小于 16 KiB。

修改注释

如需修改注释，请使用以下方法之一：

控制台

转到 Google Cloud 控制台中的 Secret Manager 页面。

前往 Secret Manager
在列表中找到相应密钥，然后点击与该密钥关联的操作菜单。在操作菜单中，点击修改。
在修改密钥页面上，前往注释部分。在这里，您可以更改现有注释的值、删除注释或添加新注释。
完成更改后，点击更新 Secret。

gcloud

修改现有注释

在使用下面的命令数据之前，请先进行以下替换：

SECRET_ID：Secret 的 ID 或 Secret 的完全限定标识符
KEY：注释键
VALUE：注解键的对应值

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud secrets update SECRET_ID --update-annotations= KEY=VAL

Windows (PowerShell)

gcloud secrets update SECRET_ID --update-annotations= KEY=VAL

Windows (cmd.exe)

gcloud secrets update SECRET_ID --update-annotations= KEY=VAL

响应会修改 Secret 和注解。

移除特定注释

如需移除注解，请使用以下命令：

gcloud secrets update SECRET_ID --remove-annotations= KEY=VAL

清除所有注释

如要清除所有注释，请使用以下命令：

gcloud secrets update SECRET_ID --clear-annotations

REST

如需清除所有注解，请使用以下命令：

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：Google Cloud 项目 ID
SECRET_ID：密钥的 ID 或密钥的完全限定标识符

HTTP 方法和网址：

PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations

请求 JSON 正文：

{'annotations': {}}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dd90b37e7\""
}

查看注释

如需查看附加到 Secret 的注释，请使用以下方法之一：

控制台

转到 Google Cloud 控制台中的 Secret Manager 页面。

前往 Secret Manager
在 Secret Manager 页面上，点击要查看其注释的 Secret。
系统会打开密钥详情页面。点击概览标签页。您可以在此处查看附加到 Secret 的注解。键列在左侧列中，值则显示在右侧列中。

gcloud

在使用下面的命令数据之前，请先进行以下替换：

SECRET_ID：Secret 的 ID 或 Secret 的完全限定标识符

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud secrets describe SECRET_ID

Windows (PowerShell)

gcloud secrets describe SECRET_ID

Windows (cmd.exe)

gcloud secrets describe SECRET_ID

响应包含 Secret 和注解。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：Google Cloud 项目 ID
SECRET_ID：密钥的 ID 或密钥的完全限定标识符

HTTP 方法和网址：

GET https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID

请求 JSON 正文：

{}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dcd99c386\"",
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  }
}

创建和管理注释

概览

所需的角色

向 Secret 添加注解

控制台

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl

PowerShell

修改注释

控制台

gcloud

修改现有注释

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

移除特定注释

清除所有注释

REST

curl

PowerShell

查看注释

控制台

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl

PowerShell

后续步骤