创建和管理注释

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

概览

您可以使用注解来存储有关 Secret 的自定义元数据。例如，您可能需要使用 Secret 将要装载到的路径来注释 Secret。注释有助于：

  • 根据 Secret 的用途、环境（开发、预演、生产）或敏感程度对其进行分类。这样一来，您就可以更轻松地在 Secret Manager 中搜索、过滤和整理 Secret。

  • 用于指明 Secret 值的具体格式或结构，帮助工作负载正确解读该值。

  • 提供有关如何使用密钥或处理密钥时需要注意的任何特殊事项的提示。

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

  • environment:production

  • purpose:database_access

  • owner:database_team

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

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

所需的角色

  • 如需在密文上添加注释和更新注释，需要具有密文、项目、文件夹或组织的 Secret Manager 管理员角色 (roles/secretmanager.admin)。

  • 如需查看注释，需要具有密文、项目、文件夹或组织的 Secret Manager 查看者角色 (roles/secretmanager.viewer)。

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

向 Secret 添加注释

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

控制台

  1. 在 Google Cloud 控制台中，前往 Secret Manager 页面。

    前往 Secret Manager

  2. 在 Secret Manager 页面上，点击区域性 Secret 标签页，然后点击创建区域性 Secret。

  3. 在创建区域级 Secret 页面上，在名称字段中输入 Secret 的名称。

  4. 输入 Secret 的值（例如 abcd1234）。您还可以使用上传文件选项上传包含 Secret 值的文本文件。此操作会自动创建 Secret 版本。

  5. 从区域列表中选择您要存储区域级密钥的位置。

  6. 前往注解部分，然后点击添加注解。

  7. 输入键和相应的值。

  8. 点击创建密钥。

gcloud

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

  • SECRET_ID：相应 Secret 的 ID 或完全限定标识符
  • LOCATION：相应 Secret 的 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：相应 Secret 的 Google Cloud 位置
  • PROJECT_ID： Google Cloud 项目 ID
  • SECRET_ID：相应 Secret 的 ID 或完全限定标识符
  • 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

将请求正文保存在名为 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

将请求正文保存在名为 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 个字节。

  • 密钥必须以字母数字字符开头和结尾。

  • 键可以在字母数字字符之间包含短划线、下划线和英文句点。

  • 注解键和值的总大小必须小于 16KiB。

修改注释

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

控制台

  1. 在 Google Cloud 控制台中，前往 Secret Manager 页面。

    前往 Secret Manager

  2. 在 Secret Manager 页面上，点击区域级 Secret 标签页。

  3. 在列表中找到相应 Secret，然后点击与该 Secret 关联的 操作菜单。在操作菜单中，点击修改。

  4. 在修改 Secret 页面上，前往注释部分。您可以在此处更改现有注解的值、删除注解或添加新注解。

  5. 完成更改后，点击更新密钥。

gcloud

修改现有注释

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

  • SECRET_ID：相应 Secret 的 ID 或完全限定标识符
  • LOCATION：相应 Secret 的 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：相应 Secret 的 Google Cloud 位置
  • PROJECT_ID： Google Cloud 项目 ID
  • SECRET_ID：相应 Secret 的 ID 或完全限定标识符

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

将请求正文保存在名为 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 的注释，请使用以下方法之一：

控制台

  1. 在 Google Cloud 控制台中，前往 Secret Manager 页面。

    前往 Secret Manager

  2. 在 Secret Manager 页面上，点击区域性密文标签页，然后点击要查看注释的密文。

  3. 系统会打开 Secret 详情页面。点击概览标签页。 您可以在此处查看附加到 Secret 的注释。键列在左侧，值显示在右侧。

gcloud

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

  • SECRET_ID：相应 Secret 的 ID 或完全限定标识符
  • LOCATION：相应 Secret 的 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：相应 Secret 的 Google Cloud 位置
  • PROJECT_ID： Google Cloud 项目 ID
  • SECRET_ID：相应 Secret 的 ID 或完全限定标识符

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

将请求正文保存在名为 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"
  }
}

后续步骤