创建轮替时间表

借助 Secret Manager，您可以安排定期轮替密文。Secret Manager 会根据您指定的轮替频率和时间，向与您的密文关联的 Pub/Sub 主题发送通知，以此来实现轮替。本页介绍了如何设置这些轮替时间表。

密文轮替通知的运作方式

Secret Manager 会在密文的 next_rotation_time 时向指定的 Pub/Sub 主题触发 SECRET_ROTATE 消息。您可以通过以下两种方式确定此时间戳：

  1. 用户定义：您可以在创建或更新 Secret 时指定 next_rotation_time。

  2. 轮替周期：如果您定义了 rotation_period，Secret Manager 会自动计算 next_rotation_time。Secret Manager 会在指定的 rotation_period 过后发送 SECRET_ROTATE 消息，然后更新 next_rotation_time 以安排下一次轮替。

您必须配置 Pub/Sub 订阅方来接收 SECRET_ROTATE 消息并对其执行操作。您可能还需要设置其他工作流来响应这些通知，例如创建新版本的 Secret 并将更改部署到应用。

密钥轮替时间表的要求和注意事项

  • 必须在密文上配置 Pub/Sub 主题。如需了解如何创建 Pub/Sub 主题和订阅，请参阅 Pub/Sub 快速入门。 如需了解如何在密文上配置主题，请参阅 Secret Manager 的事件通知。

  • 如果指定了 rotation_period，则必须设置 next_rotation_time。

  • next_rotation_time 不能设置为将来不到五分钟的时间。

  • rotation_period 的时长不能小于一小时。如需了解时间戳格式设置指导信息，请参阅 Google Cloud datetime 参考文档

  • 虽然 Secret Manager 会自动重试失败的消息传送尝试，但如果密文、主题配置、权限或配额存在配置错误，我们无法保证成功传送。

  • 进行中的轮替必须先完成，然后才能开始另一次轮替，以防止并发轮替产生意外行为。当 Secret Manager 尝试向 Pub/Sub 发送消息时，通知被视为进行中。如果存在进行中的轮替，则跳过计划轮替。 Secret Manager 会自动重试失败发送消息尝试，最多尝试七天，之后轮替将取消。

为密文配置轮替

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 Secret Manager API 配置轮替时间表。

控制台

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

    前往 Secret Manager

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

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

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

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

  6. 前往轮替部分，然后选中设置轮替周期复选框。

  7. 在轮替周期列表中，从默认选项中进行选择，或选择自定义以配置自己的轮替时间表。

  8. 在开始日期字段中，输入轮替周期的开始日期和时间。

  9. 点击创建密钥。

gcloud

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

  • SECRET_ID：密钥的 ID 或密钥的完全限定标识符。
  • LOCATION：密钥的 Google Cloud 位置。
  • NEXT_ROTATION_TIME：完成首次轮替的时间戳（采用 ISO 8601 格式），例如 2021-06-01T09:00:00Z。
  • ROTATION_PERIOD：密钥轮替间隔（以秒为单位）。例如，如需每 2592000 秒轮替一次密钥，您将设置值为 2592000s。
  • FULL_TOPIC_NAME：Pub/Sub 主题的完整名称，格式为 projects/your-project-id/topics/your-topic-name。

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud secrets create SECRET_ID --location=LOCATION \
  --next-rotation-time="NEXT_ROTATION_TIME" \
  --rotation-period="ROTATION_PERIOD" \
  --topics="FULL_TOPIC_NAME"

Windows (PowerShell)

gcloud secrets create SECRET_ID --location=LOCATION `
  --next-rotation-time="NEXT_ROTATION_TIME" `
  --rotation-period="ROTATION_PERIOD" `
  --topics="FULL_TOPIC_NAME"

Windows (cmd.exe)

gcloud secrets create SECRET_ID --location=LOCATION ^
  --next-rotation-time="NEXT_ROTATION_TIME" ^
  --rotation-period="ROTATION_PERIOD" ^
  --topics="FULL_TOPIC_NAME"

REST

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

  • LOCATION：密钥的 Google Cloud 位置
  • PROJECT_ID：Google Cloud 项目 ID
  • SECRET_ID：Secret 的 ID 或 Secret 的完全限定标识符
  • TOPIC_NAME：主题名称

HTTP 方法和网址：

POST https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets?secretId=SECRET_ID

请求 JSON 正文： 

{
  "topics": {"name" : "projects/$PROJECT_ID/topics/$TOPIC_NAME"},
  "rotation":
    {
      "next_rotation_time": "2021-06-01T09:00:00Z",
      "rotation_period" : '2592000s'
    },
}

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

curl

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

curl -X POST \
     -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?secretId=SECRET_ID"

PowerShell

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

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

Invoke-WebRequest `
    -Method POST `
    -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?secretId=SECRET_ID" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-04T04:06:00.660420Z",
  "topics": [
    {
      "name": "projects/PROJECT_ID/topics/TOPIC_NAME"
    }
  ],
  "etag": "\"1621434abc8dc4\"",
  "rotation": {
    "nextRotationTime": "2024-09-10T09:00:00Z",
    "rotationPeriod": "2592000s"
  }
}

更新密文的轮替设置

您可以在发出更新请求时更新以下轮替设置：

  • rotation：这表示 Secret 的整个轮替配置。

  • rotation.next_rotation_time：这会专门定位到指示下次轮替可能发生时间的时间戳。

  • rotation.rotation_period：用于指定每次旋转之间的时长。

如需更新密钥的轮替设置，请使用以下方法之一：

控制台

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

    前往 Secret Manager

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

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

  4. 前往轮替部分。根据需要更新轮替周期，然后点击更新 Secret。

gcloud

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

  • SECRET_ID：密钥的 ID 或密钥的完全限定标识符。
  • LOCATION：密钥的 Google Cloud 位置。
  • NEXT_ROTATION_TIME：完成首次轮替的时间戳（采用 ISO 8601 格式），例如 2021-06-01T09:00:00Z。

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
  --next-rotation-time="NEXT_ROTATION_TIME"

Windows (PowerShell)

gcloud secrets update SECRET_ID --location=LOCATION `
  --next-rotation-time="NEXT_ROTATION_TIME"

Windows (cmd.exe)

gcloud secrets update SECRET_ID --location=LOCATION ^
  --next-rotation-time="NEXT_ROTATION_TIME"

REST

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

  • LOCATION：密钥的 Google Cloud 位置。
  • PROJECT_ID：Google Cloud 项目 ID。
  • SECRET_ID：密钥的 ID 或密钥的完全限定标识符。
  • NEXT_ROTATION_TIME：完成首次轮替的时间戳（采用 ISO 8601 格式），例如 2021-06-01T09:00:00Z。

HTTP 方法和网址：

PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/$PROJECT_ID/locations/LOCATION/secrets/$SECRET_ID?updateMask=rotation.next_rotation_time

请求 JSON 正文： 

{
  "rotation": {"next_rotation_time": "NEXT_ROTATION_TIME"}
}

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

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=rotation.next_rotation_time"

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=rotation.next_rotation_time" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-04T04:06:00.660420Z",
  "topics": [
    {
      "name": "projects/PROJECT_ID/topics/TOPIC_NAME"
    }
  ],
  "etag": "\"1621434abc8dc4\"",
  "rotation": {
    "nextRotationTime": "2024-09-10T09:00:00Z",
    "rotationPeriod": "2592000s"
  }
}

为密文停用轮替

如需停用 Secret 轮替，请使用以下方法之一：

控制台

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

    前往 Secret Manager

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

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

  4. 前往轮替部分。清除设置轮替周期复选框，然后点击更新密钥。

gcloud

移除密文的 next_rotation_time

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

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

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
    --remove-next-rotation-time

Windows (PowerShell)

gcloud secrets update SECRET_ID --location=LOCATION `
    --remove-next-rotation-time

Windows (cmd.exe)

gcloud secrets update SECRET_ID --location=LOCATION ^
    --remove-next-rotation-time

移除密文的轮替时间表。这会同时移除 next_rotation_time 和 rotation_period。

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

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

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
    --remove-rotation-schedule

Windows (PowerShell)

gcloud secrets update SECRET_ID --location=LOCATION `
    --remove-rotation-schedule

Windows (cmd.exe)

gcloud secrets update SECRET_ID --location=LOCATION ^
    --remove-rotation-schedule

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=rotation.next_rotation_time

请求 JSON 正文： 

{}

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

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=rotation.next_rotation_time"

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=rotation.next_rotation_time" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-04T04:06:00.660420Z",
  "topics": [
    {
      "name": "projects/PROJECT_ID/topics/TOPIC_NAME"
    }
  ],
  "etag": "\"16214530fa18d3\""
}

移除密文的轮替时间表。这会同时移除下次轮替时间和轮替周期。

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

  • 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=rotation

请求 JSON 正文： 

{}

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

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=rotation"

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=rotation" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-04T04:06:00.660420Z",
  "topics": [
    {
      "name": "projects/PROJECT_ID/topics/TOPIC_NAME"
    }
  ],
  "etag": "\"16214530fa18d3\""
}

后续步骤