延遲刪除密鑰版本

本頁說明如何設定密鑰版本延遲刪除、更新或移除延遲刪除時長，以及還原排定刪除的密鑰版本。

根據預設，使用者在 Secret Manager 中選擇刪除密鑰版本時，系統會立即永久刪除密鑰內容。不過，具備 Secret Manager 管理員角色的使用者可以設定密鑰版本延遲刪除，確保系統不會在收到要求後立即刪除密鑰版本，並在可設定的期間內保留密鑰版本，方便日後復原。

如果密鑰已啟用延遲刪除功能，且您刪除密鑰版本，會發生下列情況：

  • 該版本已停用，因此無法使用。

  • 系統會在延遲期間結束時，安排永久刪除該版本。

  • 延遲期間結束後，密鑰版本會永久刪除，且無法復原。

優點

這項功能可帶來下列好處：

  • 多一層保護，防止重要機密資料遭到意外或惡意破壞。具備「Secret Manager Secret Version Manager」角色的使用者可以毀損密鑰版本。這項操作無法復原。設定延遲刪除後，即可避免密鑰版本立即遭到刪除。您可以授予使用者管理密碼版本生命週期所需的最低存取權，以便監控及防止機密資料遭到意外毀損。

  • 銷毀密鑰版本會觸發SECRET_VERSION_DESTROY_SCHEDULED 通知 ，傳送至密鑰上設定的 Pub/Sub 主題。具備 Secret Manager 管理員角色的使用者可以取消排定的刪除作業，並透過啟用或停用密鑰版本來還原密鑰版本。

事前準備

  1. Enable the Secret Manager API.

    Enable the API

  2. 設定驗證方法。

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

      In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

      At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

      REST

      如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

        After installing the Google Cloud CLI, initialize it by running the following command: 

        gcloud init

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      詳情請參閱 Google Cloud 驗證說明文件中的「Authenticate for using REST」。

      必要的角色

      如要取得設定延遲銷毀密鑰版本所需的權限，請要求管理員為您授予密鑰的 Secret Manager 管理員 (roles/secretmanager.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

      您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

      設定延遲刪除

      您可以在建立或更新密鑰時，啟用密鑰版本延遲刪除功能。如要設定延遲銷毀，請使用下列其中一種做法：

      控制台

      1. 前往 Google Cloud 控制台的「Secret Manager」頁面。

        前往 Secret Manager

      2. 在「Secret Manager」(密鑰管理工具) 頁面中，按一下「Create secret」(建立密鑰)。

      3. 在「建立密鑰」頁面的「名稱」欄位中，輸入密鑰名稱。

      4. 輸入密鑰值 (例如 abcd1234)。您也可以使用「上傳檔案」選項，上傳含有密鑰值的文字檔。這項動作會自動建立密鑰版本。

      5. 前往「延遲刪除密鑰版本」部分，然後選取「設定延遲刪除時間長度」核取方塊。

      6. 在「Destruction delay duration」(刪除延遲時長) 欄位中，以天為單位輸入時長。可輸入的最小值為 1 天，最大值為 1000 天。

      7. 按一下「建立密鑰」。

        如要為現有密鑰啟用這項功能，請前往「編輯密鑰」頁面，然後設定刪除延遲時間。

      gcloud

      使用下方的任何指令資料之前，請先替換以下項目：

      • SECRET_ID：密鑰的 ID 或密鑰的完整 ID。
      • TTL_DURATION：密鑰版本的刪除延遲時間。你可以輸入任何格式的持續時間，例如天數、小時或秒數。最短期限為 1 天，最長期限為 1000 天。

      執行下列指令：

      Linux、macOS 或 Cloud Shell

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

      Windows (PowerShell)

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

      Windows (cmd.exe)

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

      回應包含新建立的密鑰。

      REST

      使用任何要求資料之前，請先替換以下項目：

      • PROJECT_ID：專案 ID。 Google Cloud
      • SECRET_ID：密鑰的 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

      將要求主體儲存在名為 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"
}

      延後銷毀不適用於下列情況：

      • 刪除密鑰後，系統會立即刪除所有密鑰資料和相關密鑰版本。

      • 如果密鑰設有到期日，且密鑰到期，即使密鑰已啟用延遲刪除功能，所有密鑰版本都會立即刪除。

      更新刪除延遲時長

      如要更新銷毀延遲時間，請使用下列其中一種方法：

      控制台

      1. 前往 Google Cloud 控制台的「Secret Manager」頁面。

        前往 Secret Manager

      2. 如要編輯密鑰，請使用下列其中一種做法：

        • 按一下要編輯的密鑰的「動作」，然後按一下「編輯」。

        • 按一下密鑰名稱，前往密鑰詳細資料頁面。在密鑰詳細資料頁面中，按一下「編輯密鑰」。

      3. 在「Edit secret」(編輯密鑰) 頁面中，前往「Delay secret version destroy」(延遲刪除密鑰版本) 部分。 視需要更新延遲時間，然後按一下「更新密鑰」。

      gcloud

      使用下方的任何指令資料之前，請先替換以下項目：

      • SECRET_ID：密鑰的 ID 或密鑰的完整 ID
      • TTL_DURATION：密鑰版本的刪除延遲時間長度

      執行下列指令：

      Linux、macOS 或 Cloud Shell

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

      Windows (PowerShell)

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

      Windows (cmd.exe)

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

      回應包含新建立的密鑰。

      REST

      使用任何要求資料之前，請先替換以下項目：

      • PROJECT_ID：專案 ID Google Cloud
      • SECRET_ID：密鑰的 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"
}

      受刪除延遲時間影響的密鑰版本取決於下列因素：

      • 首次為密鑰設定延遲刪除功能時，刪除延遲時間會影響密鑰的所有有效版本 (已啟用和已停用)。

      • 更新或移除刪除延遲時間後，變更只會反映在嘗試刪除的新密鑰版本上。已排定刪除的密鑰版本仍會在排定的時間刪除。

      停用延遲刪除

      如要停用延遲刪除版本功能，請使用下列其中一種方法：

      控制台

      1. 前往 Google Cloud 控制台的「Secret Manager」頁面。

        前往 Secret Manager

      2. 如要編輯密鑰，請使用下列其中一種做法：

        • 按一下要編輯的密鑰的「動作」，然後按一下「編輯」。

        • 按一下密鑰名稱，前往密鑰詳細資料頁面。在密鑰詳細資料頁面中，按一下「編輯密鑰」。

      3. 在「Edit secret」(編輯密鑰) 頁面中，前往「Delay secret version destroy」(延遲刪除密鑰版本) 部分。 取消勾選「設定延遲刪除時長」核取方塊，然後按一下「更新密鑰」。

      gcloud

      使用下方的任何指令資料之前，請先替換以下項目：

      • SECRET_ID：密鑰的 ID 或密鑰的完整 ID

      執行下列指令：

      Linux、macOS 或 Cloud Shell

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

      Windows (PowerShell)

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

      Windows (cmd.exe)

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

      REST

      使用任何要求資料之前，請先替換以下項目：

      • PROJECT_ID：專案 ID Google Cloud
      • SECRET_ID：密鑰的 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\""
}

      安排延遲刪除密鑰版本

      如要排定密鑰版本延遲刪除時間，請使用下列其中一種方法：

      控制台

      1. 前往 Google Cloud 控制台的「Secret Manager」頁面。

        前往 Secret Manager

      2. 在「Secret Manager」頁面中，按一下密鑰即可存取其版本。您必須為這個密鑰設定延遲刪除版本。

      3. 在密鑰詳細資料頁面的「版本」分頁中，選取要銷毀的密鑰版本。

      4. 按一下「動作」，然後按一下「銷毀」。

      5. 在隨即顯示的確認對話方塊中，輸入密鑰 ID 以進行確認，然後按一下「Schedule selected versions for destruction」(排定銷毀所選版本)。

      gcloud

      使用下方的任何指令資料之前，請先替換以下項目：

      • SECRET_VERSION_ID：版本 ID 或版本的完整 ID
      • SECRET_ID：密鑰的 ID 或密鑰的完整 ID

      執行下列指令：

      Linux、macOS 或 Cloud Shell

      gcloud secrets versions destroy SECRET_VERSION_ID --secret=SECRET_ID

      Windows (PowerShell)

      gcloud secrets versions destroy SECRET_VERSION_ID --secret=SECRET_ID

      Windows (cmd.exe)

      gcloud secrets versions destroy SECRET_VERSION_ID --secret=SECRET_ID

      REST

      使用任何要求資料之前，請先替換以下項目：

      • PROJECT_ID：專案 ID Google Cloud
      • SECRET_ID：密鑰的 ID 或密鑰的完整 ID
      • VERSION_ID：版本 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"
}

      密鑰版本會立即停用，並排定在延遲刪除時長過後刪除。您可以在「版本」表格的「預定刪除日期」欄下方，查看版本確切的刪除日期和時間。

      還原密鑰版本

      如要還原已排定刪除的密鑰版本，請啟用或停用該版本。

      啟用已排定刪除的密鑰版本

      如要啟用預定刪除的密鑰版本，請使用下列其中一種做法：

      控制台

      1. 前往 Google Cloud 控制台的「Secret Manager」頁面。

        前往 Secret Manager

      2. 在「Secret Manager」頁面中，按一下密鑰即可存取其版本。

      3. 在密鑰詳細資料頁面的「版本」分頁中，選取排定要銷毀的密鑰版本。

      4. 按一下「動作」，然後點選「啟用」。

      5. 在隨即顯示的確認對話方塊中，按一下「啟用所選版本」。

      gcloud

      使用下方的任何指令資料之前，請先替換以下項目：

      • SECRET_VERSION_ID：版本 ID 或版本的完整 ID
      • SECRET_ID：密鑰的 ID 或密鑰的完整 ID

      執行下列指令：

      Linux、macOS 或 Cloud Shell

      gcloud secrets versions enable SECRET_VERSION_ID --secret=SECRET_ID

      Windows (PowerShell)

      gcloud secrets versions enable SECRET_VERSION_ID --secret=SECRET_ID

      Windows (cmd.exe)

      gcloud secrets versions enable SECRET_VERSION_ID --secret=SECRET_ID

      REST

      使用任何要求資料之前，請先替換以下項目：

      • PROJECT_ID：專案 ID Google Cloud
      • SECRET_ID：密鑰的 ID 或密鑰的完整 ID
      • VERSION_ID：版本 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\""
}

      停用已排定刪除的密鑰版本

      如要停用預定刪除的密鑰版本，請使用下列其中一種方法：

      控制台

      1. 前往 Google Cloud 控制台的「Secret Manager」頁面。

        前往 Secret Manager

      2. 在「Secret Manager」頁面中，按一下密鑰即可存取其版本。

      3. 在密鑰詳細資料頁面的「版本」分頁中，選取排定要銷毀的密鑰版本。

      4. 按一下「動作」，然後按一下「停用」。

      5. 在隨即顯示的確認對話方塊中，按一下「停用所選版本」。

      gcloud

      使用下方的任何指令資料之前，請先替換以下項目：

      • SECRET_VERSION_ID：版本 ID 或版本的完整 ID
      • SECRET_ID：密鑰的 ID 或密鑰的完整 ID

      執行下列指令：

      Linux、macOS 或 Cloud Shell

      gcloud secrets versions disable SECRET_VERSION_ID --secret=SECRET_ID

      Windows (PowerShell)

      gcloud secrets versions disable SECRET_VERSION_ID --secret=SECRET_ID

      Windows (cmd.exe)

      gcloud secrets versions disable SECRET_VERSION_ID --secret=SECRET_ID

      回應會包含已停用的密鑰版本。

      REST

      使用任何要求資料之前，請先替換以下項目：

      • PROJECT_ID：專案 ID Google Cloud
      • SECRET_ID：密鑰的 ID 或密鑰的完整 ID
      • VERSION_ID：版本 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\""
}

      後續步驟