轮替时间表简介

本主题介绍 Secret 轮替的概念。在开始之前，我们建议您查看 Platform 概览，从整体上了解 Google Cloud。我们还建议您阅读 Secret Manager 产品概览。

简介

定期轮替有助于：

• 限制密文泄露时的影响。
• 确保不再需要访问 Secret 的个人无法使用旧 Secret 值。
• 持续执行轮替流程，以降低紧急轮替时发生中断的可能性。

Secret Manager 具有密文、密文版本和轮替时间表概念，为构建支持轮替密文的工作负载奠定了基础。

本主题提供了有关轮替存储在 Secret Manager 中的 Secret 的建议。以下部分将探讨以下方面的优缺点：

• 将 Secret 版本绑定到应用的方法。
• 轮替 Secret 的方法。

绑定到 Secret 版本

Secret Manager 中的 Secret 可以有多个 Secret 版本。Secret 版本包含不可变的载荷（实际的 Secret 字节字符串），会进行排序和编号。如需轮替 Secret，请向现有 Secret 添加新的 Secret 版本。

您可以使用 latest 别名引用密文中最近添加的密文版本。虽然 latest 别名可便于开发，但对于某些生产工作负载而言，它可能存在问题，因为错误值可能会立即发布并造成服务范围的中断。以下场景介绍了绑定到密文版本的其他方法。

逐步发布

对于以下情形，逐步发布是指导原则。通过选择较慢的 Secret 发布速度，破坏风险较低，但恢复时间也会更慢。某些 Secret 在可能由您控制或无法恢复的外部系统（例如跟踪有效 Secret 值的 API 或数据库）中可能会失效，而在这些情况下需要发布。

在手动或自动轮替期间可能会发布错误密文。强大的轮替工作流应该能够自动检测中断（例如 HTTP 错误率）并回滚以使用旧密文版本（通过之前的配置部署）。

新 Secret 版本的发布取决于 Secret 与应用的绑定方式。

方法 1：在现有发布流程中解析

解析密文版本并将其与您的应用的版本绑定。对于大多数部署，这涉及将最新密文版本解析为完整的密文版本资源名称，并将其与应用一起作为标志或在配置文件中发布。我们建议在轮替时解析密文版本名称，将资源名称存储在持久位置（例如，提交到 Git），并在推送期间将版本名称拉取到部署配置中以防止部署被阻止。

在应用启动时，使用特定的 Secret 版本名称调用 Secret Manager 以访问 Secret 值。

此方法具有以下优势：

• 您的应用在重启时使用相同的密文版本，从而可提高可预测性并降低运营复杂性。
• 现有的发布和回滚变更管理流程可以重复用于密文轮替和密文版本部署。
• 值可以逐步发布，从而可减少部署错误值的影响。

注意 ：如果最新的密钥存在恶意版本，则在部署时解析最新版本可能会阻止部署。解决部署期间的问题可能独立性较低，或者可重现性较差，因为发布成功取决于 Secret Manager 中的 Secret 版本状态。如果之前的 Secret 版本有效，请创建具有相同值的新 Secret 版本，然后等待其发布。这本质上是一种“前滚”，并且需要密钥的 secretmanager.versions.access 权限才能将值从旧版本复制到新版本。

方法 2：在应用启动时解析

在应用启动时提取最新密文载荷，并在应用的生命周期内继续使用该密文。

此方法的优点是，它不需要修改 CI/CD 流水线来解析密文版本，但如果发布了错误密文，则应用将无法在实例重启或服务扩容时启动，并且可能会级联成服务中断。

方法 3：持续解析

在应用中持续轮询最新密文版本，并立即使用新的密文值。

这种方法可能会导致立即发生服务范围的中断，因为无法逐步采用新的密文值。

轮替密文

如果您的 Secret 可以动态更新（例如，如果验证 Secret 的外部系统提供 Admin API），我们建议您设置定期运行的轮替作业。以下部分以 Cloud Run 作为示例计算环境，概述了常规步骤。

为密文配置轮替时间表

为您的密钥设置轮替时间表。必须针对 Secret 配置 Pub/Sub 主题，才能在需要轮替 Secret 时收到通知。如需了解如何配置有关 Secret 的主题，请参阅事件通知指南。

启动 Cloud Run 以创建新的 Secret 版本

创建并配置 Cloud Run 服务以接收轮替通知并执行轮替步骤：

1. 在外部系统（例如数据库、API 提供方）中获取或创建新的 Secret。

   确保这不会使现有密文失效，从而不会影响现有工作负载。

2. 使用新密文更新 Secret Manager。

   在 Secret Manager 中创建新的 SecretVersion。此操作还会将 latest 别名更新为指向新创建的 Secret。

重试和并发

由于轮替流程可能会随时终止，因此 Cloud Run 服务必须能够从其中断的位置重启该流程（必须是可重入）。

我们建议您在 Pub/Sub 中配置重试，以便能够重新执行失败或中断的轮替。此外，请在 Cloud Run 服务上配置最大并发和最大实例数，以尽可能降低并发执行轮替相互干扰的可能性。

您可能会发现，为了构建可重入旋转函数，保存状态以允许旋转过程继续进行。有两项 Secret Manager 功能可帮助您实现此目的：

• 对密文使用标签，以在轮替期间保存状态。为密文添加标签，以跟踪轮替工作流期间上次成功添加的版本数量（即 ROTATING_TO_NEW_VERSION_NUMBER=3）。轮替完成后，请移除轮替跟踪标签。
• 使用 ETag 来验证其他流程在轮替工作流期间不会并发修改密文。详细了解密文和密文版本的 ETag。

注意：密文和密文版本的 ETag 彼此独立。换句话说，添加新版本不会修改父级密文的 ETag。

Identity and Access Management 权限

轮替流程需要 secretmanager.versions.add 权限才能添加新的密文版本，并且可能需要 secretmanager.versions.access 才能读取之前的密文版本。

默认的 Cloud Run 服务帐号具有 Editor 角色，该角色包括添加但不访问 Secret 版本的权限。为了遵循最小权限原则，我们建议不要使用默认服务帐号。您可以为 Cloud Run 服务设置单独的服务帐号，并根据需要授予 Secret Manager 角色（可以是以下一个或多个角色）：

• roles/secretmanager.secretVersionAdder
• roles/secretmanager.secretVersionManager
• roles/secretmanager.secretAdmin
• roles/secretmanager.secretAccessor

向工作负载发布新的 SecretVersion

现在，已在外部系统中注册了新的有效 SecretVersion 并将其存储在 Secret Manager 中，接下来将其发布到您的应用。此发布因密文绑定方法而异（请参阅绑定到密文版本部分），通常不需要人工干预。

清理旧的 Secret 版本

一旦所有应用停用旧 Secret 版本，此版本即可安全地进行清理。清理过程取决于 Secret 的类型，但一般而言：

1. 确保新的 Secret 版本已完全发布到所有应用。
2. 在 Secret Manager 中停用旧密文版本，并验证应用不会中断（如果停用会中断使用方，请等待合理的一段时间以允许人工干预）。
3. 从外部系统中移除或取消注册旧 Secret 版本。
4. 在 Secret Manager 中销毁旧 Secret 版本。

后续步骤

• 了解如何为 Secret 设置轮替时间表。