推迟销毁密钥版本

本页面介绍了如何设置 Secret 版本的延迟销毁、更新或移除销毁延迟时长，以及恢复处于已安排销毁状态的 Secret 版本。

当您销毁某个密钥版本时，该密钥材料会立即被永久销毁。作为 Secret Manager 管理员，您可以设置延迟销毁 Secret 版本，使 Secret 版本不会在收到请求后立即销毁，并且可在可配置的时长内恢复。

如果对密钥启用延迟销毁，并且您销毁了密钥版本，则会发生以下情况：

此版本已停用，因此无法使用。
系统会在延迟期结束时安排永久销毁该版本。
延迟期结束后，密钥版本将被永久且不可撤消地销毁。

优势

此功能具有以下优势：

防止意外或恶意销毁关键机密材料的额外保护。拥有 Secret Manager Secret Version Manager 角色的任何用户都可以销毁 Secret 版本。此操作无法撤消。通过设置延迟销毁，可以防止密钥版本被立即销毁。您可以授予用户管理 Secret 版本的生命周期所需的最低访问权限，因为您可以监控并防止敏感数据的任何意外销毁。
销毁某个 Secret 版本会触发系统向在该 Secret 上配置的 Pub/Sub 主题发出 SECRET_VERSION_DESTROY_SCHEDULED 通知。作为 Secret Manager 管理员，您可以通过启用或停用 Secret 版本来取消计划的销毁并恢复 Secret 版本。

准备工作

启用 Secret Manager API。
启用 API
设置身份验证。

选择标签页以了解您打算如何使用本页面上的示例：
控制台

当您使用 Google Cloud 控制台访问 Google Cloud 服务和 API 时，无需设置身份验证。
gcloud

您可以从以下任一开发环境使用本页面上的 gcloud CLI 示例：
- Cloud Shell：如需使用已设置 gcloud CLI 的在线终端，请激活 Cloud Shell。
  
  Cloud Shell 会话会在页面底部启动，并显示命令行提示符。该会话可能需要几秒钟来完成初始化。
- 本地 shell：如需在本地开发环境中使用 gcloud CLI，请安装并初始化 gcloud CLI。
REST

如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭据。

所需的角色

如需获取设置 Secret 版本的延迟销毁功能所需的权限，请让管理员授予您针对该 Secret 的 Secret Manager Admin (roles/secretmanager.admin) IAM 角色。如需详细了解如何授予角色，请参阅管理访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

设置延迟销毁

您可以在创建 Secret 或更新 Secret 时启用 Secret 版本的延迟销毁。

控制台

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

转到 Secret Manager
按照创建 Secret 所需的步骤进行操作。
转到延迟密钥版本销毁部分。
选中设置推迟销毁复选框。
在销毁推迟时长字段中，输入时长（以天为单位）。您可以输入的最小值为 1 天，最大值为 1000 天。
点击创建密钥。

如需为现有密钥启用此功能，请转到修改密钥页面，然后配置销毁推迟时长。

gcloud

如需为密钥配置销毁推迟时长，请使用 gcloud beta secrets create 命令。

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

SECRET_ID：密钥的 ID 或密钥的完全限定标识符。
TTL_DURATION：密钥版本的销毁推迟时长。您可以采用任何格式输入时长，例如天、小时或秒。时长下限为 1 天，时长上限为 1,000 天。

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud beta secrets create SECRET_ID --version-destroy-ttl=TTL_DURATION

Windows (PowerShell)

gcloud beta secrets create SECRET_ID --version-destroy-ttl=TTL_DURATION

Windows (cmd.exe)

gcloud beta secrets create SECRET_ID --version-destroy-ttl=TTL_DURATION

响应中包含新创建的 Secret。

REST

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

PROJECT_ID：您要在其中创建 Secret 的 Google Cloud 项目的 ID
SECRET_ID：密钥的 ID 或密钥的完全限定标识符。
TTL_DURATION：密钥版本的销毁推迟时长。输入时长（以秒为单位）。请注意，所需的最短时长为 1 天，而最长时长可设置为 1000 天。

HTTP 方法和网址：

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

请求 JSON 正文：

{"replication": {"automatic": {}}, "version_destroy_ttl":"TTL_DURATION"}

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

curl

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

将请求正文保存在名为 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.googleapis.com/v1/projects/PROJECT_ID/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.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID" | Select-Object -Expand Content

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

{
  "name":"projects/PROJECT_ID/secrets/SECRET_ID",
  "replication":{
     "automatic":{

     }
  },
  "createTime":"2023-10-16T17:10:16.345401Z",
  "etag":"\"1607d90ee3d84c\"",
  "versionDestroyTtl":"TTL_DURATION"
}

推迟销毁功能不适用于以下情况：

删除密钥时，所有密钥材料和相关密钥版本都将被立即删除。
如果对密钥设置了失效日期，且密钥到期，那么即使针对密钥启用了延迟销毁功能，所有密钥版本也会立即销毁。

更新销毁推迟时长

控制台

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

转到 Secret Manager
使用以下任一选项修改您的 Secret：
- 点击与要修改的 Secret 关联的 更多操作，然后从菜单中选择 Edit。
- 点击密钥名称以转到密钥详情页面。在 Secret 详情页面上，点击 修改密钥。
转到延迟密钥版本销毁部分。
在销毁推迟时长字段中，输入更新后的时长。
点击更新密钥。

gcloud

如需更新销毁推迟时长，请使用 gcloud beta secrets update 命令。

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

SECRET_ID：密钥的 ID 或密钥的完全限定标识符
TTL_DURATION：密钥版本的销毁推迟时长

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud beta secrets update SECRET_ID --version-destroy-ttl=TTL_DURATION

Windows (PowerShell)

gcloud beta secrets update SECRET_ID --version-destroy-ttl=TTL_DURATION

Windows (cmd.exe)

gcloud beta secrets update SECRET_ID --version-destroy-ttl=TTL_DURATION

响应中包含更新后的 Secret。

REST

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

PROJECT_ID：Google Cloud 项目 ID
SECRET_ID：密钥的 ID 或密钥的完全限定标识符
TTL_DURATION：密钥版本的销毁推迟时长

HTTP 方法和网址：

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

请求 JSON 正文：

{
  "version_destroy_ttl":"TTL_DURATION"
}

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

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

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.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl" | Select-Object -Expand Content

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

{
  "name":"projects/PROJECT_ID/secrets/SECRET_ID",
  "replication":{
     "automatic":{

     }
  },
  "createTime":"2023-10-16T17:10:16.345401Z",
  "etag":"\"1607d90ee3d84c\"",
  "versionDestroyTtl":"TTL_DURATION"
}

受销毁推迟时长影响的密钥版本取决于以下因素：

首次对 Secret 设置延迟销毁时，销毁延迟时长会影响该 Secret 的所有有效（已启用和已停用）版本。
更新或移除销毁推迟时长后，相应更改只会反映在尝试执行销毁操作的新 Secret 版本上。已安排销毁的 Secret 版本将在安排的销毁时间继续被销毁。

停用延迟销毁

控制台

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

转到 Secret Manager
使用以下任一选项修改您的 Secret：
- 点击与要修改的 Secret 关联的 更多操作，然后从菜单中选择 Edit。
- 点击密钥名称以转到密钥详情页面。在 Secret 详情页面上，点击 修改密钥。
转到延迟密钥版本销毁部分。
取消选中设置推迟销毁复选框。
点击更新密钥。

gcloud

如需移除销毁推迟时长，请使用 gcloud beta secrets update 命令。

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

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

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud beta secrets update SECRET_ID --remove-version-destroy-ttl

Windows (PowerShell)

gcloud beta secrets update SECRET_ID --remove-version-destroy-ttl

Windows (cmd.exe)

gcloud beta secrets update SECRET_ID --remove-version-destroy-ttl

响应中包含更新后的 Secret。

REST

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

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

HTTP 方法和网址：

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

请求 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.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl"

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.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=version_destroy_ttl" | Select-Object -Expand Content

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

{
  "name":"projects/PROJECT_ID/secrets/SECRET_ID",
  "replication":{
     "automatic":{

     }
  },
  "createTime":"2023-10-16T17:10:16.345401Z",
  "etag":"\"1607d90ee3d84c\""
}

测试延迟销毁密钥版本的情况

控制台

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

转到 Secret Manager
点击密钥名称。随即会出现 Secret 详情页面。
在密钥详情页面的版本表格中，选择一个密钥版本。
在操作列中，点击 查看更多，然后点击销毁。
在随即显示的对话框中，点击安排销毁所选版本。

gcloud

要销毁密钥版本，请使用 gcloud beta Secretsversions destroy 命令。

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

SECRET_VERSION_ID：版本的 ID 或版本的完全限定标识符
SECRET_ID：密钥的 ID 或密钥的完全限定标识符

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud beta secrets versions destroy SECRET_VERSION_ID --secret=SECRET_ID

Windows (PowerShell)

gcloud beta secrets versions destroy SECRET_VERSION_ID --secret=SECRET_ID

Windows (cmd.exe)

gcloud beta secrets versions destroy SECRET_VERSION_ID --secret=SECRET_ID

响应包含密钥的已销毁版本。

REST

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

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

HTTP 方法和网址：

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID/:destroy

请求 JSON 正文：

{}

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

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.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID/:destroy"

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.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID/:destroy" | Select-Object -Expand Content

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

{
  "name":"projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID",
  "createTime":"2023-10-16T17:21:55.920036Z",
  "state":"DISABLED",
  "replicationStatus":{
     "automatic":{

     }
  },
  "etag":"\"1607d8b2fc1cf4\"",
  "scheduledDestroyTime":"2023-10-16T17:26:57.459395960Z"
}

销毁推迟时长结束后，密钥版本会立即停用，并安排销毁。您可以在版本表的计划销毁列下查看销毁版本的确切日期和时间。

恢复 Secret 版本

您可以通过启用或停用密钥版本来恢复安排销毁的 Secret 版本。

启用已安排销毁的 Secret 版本

控制台

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

转到 Secret Manager
点击密钥名称。随即会出现 Secret 详情页面。
在 Secret 详情页面的版本表中，选择已安排销毁的 Secret 版本。
在操作列中，点击 查看更多，然后点击启用。
在出现的对话框中，点击启用所选版本。

gcloud

如需启用已安排销毁的 Secret 版本，请使用 gcloud beta secretsversions enable 命令。

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

SECRET_VERSION_ID：版本的 ID 或版本的完全限定标识符
SECRET_ID：密钥的 ID 或密钥的完全限定标识符

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud beta secrets versions enable SECRET_VERSION_ID --secret=SECRET_ID

Windows (PowerShell)

gcloud beta secrets versions enable SECRET_VERSION_ID --secret=SECRET_ID

Windows (cmd.exe)

gcloud beta secrets versions enable SECRET_VERSION_ID --secret=SECRET_ID

响应中包含已启用的 Secret 版本。

REST

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

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

HTTP 方法和网址：

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID/:enable

请求 JSON 正文：

{}

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

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.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID/:enable"

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.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID/:enable" | Select-Object -Expand Content

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

{
  "name":"projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID",
  "createTime":"2023-10-16T17:21:55.920036Z",
  "state":"ENABLED",
  "replicationStatus":{
     "automatic":{

     }
  },
  "etag":"\"1607d8b3e8e1bc\""
}

停用处于安排销毁状态的 Secret 版本

控制台

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

转到 Secret Manager
点击密钥名称。随即会出现 Secret 详情页面。
在 Secret 详情页面的版本表中，选择已安排销毁的 Secret 版本。
在操作列中，点击 查看更多，然后点击停用。
在出现的对话框中，点击停用所选版本。

gcloud

如需停用已安排销毁的密钥版本，请使用 gcloud beta secrets 版本停用命令。

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

SECRET_VERSION_ID：版本的 ID 或版本的完全限定标识符
SECRET_ID：密钥的 ID 或密钥的完全限定标识符

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud beta secrets versions disable SECRET_VERSION_ID --secret=SECRET_ID

Windows (PowerShell)

gcloud beta secrets versions disable SECRET_VERSION_ID --secret=SECRET_ID

Windows (cmd.exe)

gcloud beta secrets versions disable SECRET_VERSION_ID --secret=SECRET_ID

响应中包含已停用的密钥版本。

REST

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

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

HTTP 方法和网址：

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID/:disable

请求 JSON 正文：

{}

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

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.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID/:disable"

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.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID/:disable" | Select-Object -Expand Content

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

{
  "name":"projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID",
  "createTime":"2023-10-16T17:21:55.920036Z",
  "state":"DISABLED",
  "replicationStatus":{
     "automatic":{

     }
  },
  "etag":"\"1607d8b3e8e1bc\""
}

后续步骤

了解如何确保数据完整性。
了解最佳实践。