此页面由 Cloud Translation API 翻译。

创建和管理注释

本页介绍了如何向区域性密钥添加注释，以及如何修改和查看这些注释。

概览

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

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

例如，如果您有一个包含数据库密码的 Secret，则可以添加注解，例如：

environment:production
purpose:database_access
owner:database_team

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

注释与标签不同。标签用于对资源进行排序、过滤和分组，而注解用于在 Secret 中存储任意非身份元数据。在标签中指定元数据时，字符和字符长度受到限制。注解中的元数据可大可小、结构化或非结构化，还可以包含标签不允许使用的字符。

所需的角色

如需为密文添加注释和更新注释，需要具有密文、项目、文件夹或组织的 Secret Manager 管理员角色 (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 的名称。
为 Secret 输入一个值（例如 abcd1234）。您还可以使用上传文件选项上传包含 Secret 值的文本文件。此操作会自动创建 Secret 版本。
从区域列表中，选择要存储区域级密钥的位置。
前往注解部分，然后点击添加注解。
输入键和相应值。
点击创建密钥。

gcloud

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

SECRET_ID：Secret 的 ID 或 Secret 的完全限定标识符
LOCATION：密钥的 Google Cloud 位置
KEY：注解键
VALUE：注解键对应的值

执行以下命令：

Linux、macOS 或 Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

响应包含密钥和注释。

REST

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

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

HTTP 方法和网址：

PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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 的唯一键。您无法在同一 Secret 中重复使用密钥。
键的长度必须介于 1 到 63 个字符之间。
键的 UTF-8 编码不得超过 128 个字节。
密钥必须以字母数字字符开头和结尾。
键可以在字母数字字符之间包含短划线、下划线和英文句点。
注解键和值的总大小必须小于 16 KiB。

修改注释

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

控制台

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

前往 Secret Manager
在 Secret Manager 页面上，点击 Regional secrets（区域级 Secret）标签页。
在列表中找到相应 Secret，然后点击与该 Secret 关联的操作菜单。在操作菜单中，点击修改。
在修改密钥页面上，前往注释部分。您可以在此处更改现有注解的值、删除注解或添加新注解。
完成更改后，点击更新 Secret。

gcloud

修改现有注释

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

SECRET_ID：Secret 的 ID 或 Secret 的完全限定标识符
LOCATION：密钥的 Google Cloud 位置
KEY：注解键
VALUE：注解键对应的值

执行以下命令：

Linux、macOS 或 Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

响应会修改 Secret 和注释。

移除特定注解

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

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

清除所有注释

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

gcloud secrets update SECRET_ID --location=LOCATION --clear-annotations

REST

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

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

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

HTTP 方法和网址：

PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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。
系统会打开 Secret 详情页面。点击概览标签页。您可以在此处查看附加到 Secret 的注解。键列在左侧列中，值则显示在右侧列中。

gcloud

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

SECRET_ID：Secret 的 ID 或 Secret 的完全限定标识符
LOCATION：密钥的 Google Cloud 位置

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (PowerShell)

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (cmd.exe)

gcloud secrets describe SECRET_ID --location=LOCATION

响应包含密钥和注释。

REST

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

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

HTTP 方法和网址：

GET https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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

后续步骤