在 Secret Manager 中建立輪替時間表

Secret Manager 可讓您排定密鑰的定期輪替作業。Secret Manager 會根據您指定的輪替頻率和時間，將通知傳送至與密鑰相關聯的 Pub/Sub 主題，本頁說明如何設定這些輪替時間表。

密鑰輪替通知的運作方式

Secret Manager 會在密碼的 next_rotation_time 觸發 SECRET_ROTATE 訊息，傳送至指定的 Pub/Sub 主題。判斷這個時間戳記的方法有兩種：

  1. 使用者定義：您可以在建立或更新密鑰時指定 next_rotation_time。

  2. 輪替週期：如果您定義 rotation_period，Secret Manager 會自動計算 next_rotation_time。Secret Manager 會在指定 rotation_period 經過後傳送 SECRET_ROTATE 訊息，然後更新 next_rotation_time 來安排下一次輪替。

您必須設定 Pub/Sub 訂閱端，才能接收 SECRET_ROTATE 訊息並採取行動。您可能也需要設定其他工作流程來回應這些通知，例如建立密鑰的新版本，並將變更部署至應用程式。

密鑰輪替排程的需求條件和注意事項

  • 您必須在密鑰上設定 Pub/Sub 主題。如要瞭解如何建立 Pub/Sub 主題和訂閱項目，請參閱 Pub/Sub 快速入門導覽課程。如要瞭解如何設定密鑰的主題，請參閱「Secret Manager 的事件通知」。

  • 如果指定 rotation_period，則必須設定 next_rotation_time。

  • next_rotation_time 的時間必須設定在 5 分鐘後。

  • 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」(密鑰管理工具) 頁面中，按一下「Create secret」(建立密鑰)。

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

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

  5. 前往「輪替」部分，然後選取「設定輪替週期」核取方塊。

  6. 在「輪替週期」清單中，選取預設選項或「自訂」，設定自己的輪替排程。

  7. 在「Starting on」(開始日期) 欄位中，輸入輪替週期的開始日期和時間。

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

gcloud

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

  • SECRET_ID：密鑰的 ID 或密鑰的完整 ID。
  • 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 \
  --replication-policy "automatic" \
  --next-rotation-time="NEXT_ROTATION_TIME" \
  --rotation-period="ROTATION_PERIOD" \
  --topics="FULL_TOPIC_NAME"

Windows (PowerShell)

gcloud secrets create SECRET_ID `
  --replication-policy "automatic" `
  --next-rotation-time="NEXT_ROTATION_TIME" `
  --rotation-period="ROTATION_PERIOD" `
  --topics="FULL_TOPIC_NAME"

Windows (cmd.exe)

gcloud secrets create SECRET_ID ^
  --replication-policy "automatic" ^
  --next-rotation-time="NEXT_ROTATION_TIME" ^
  --rotation-period="ROTATION_PERIOD" ^
  --topics="FULL_TOPIC_NAME"

REST

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

  • PROJECT_ID：專案 ID Google Cloud
  • SECRET_ID：密鑰的 ID 或密鑰的完整 ID
  • TOPIC_NAME：主題名稱

HTTP 方法和網址：

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

JSON 要求主體：

{
  "replication":{
    "automatic":{}
  },
  "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.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/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：這是指密鑰的完整輪替設定。

  • rotation.next_rotation_time：這項標記專門用於指出下一次輪替可能發生的時間戳記。

  • rotation.rotation_period：指定每次旋轉之間的時間長度。

如要更新密鑰的輪替設定，請使用下列其中一種方法：

控制台

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

    前往 Secret Manager

  2. 找出要編輯的密鑰，然後點按與該密鑰相關聯的「動作」選單。在「動作」選單中，按一下「編輯」。

  3. 前往「輪播」部分。視需要更新輪替週期，然後按一下「更新密鑰」。

gcloud

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

  • SECRET_ID：密鑰的 ID 或密鑰的完整 ID。
  • NEXT_ROTATION_TIME：以 ISO 8601 格式表示的完成首次輪替時間戳記，例如 2021-06-01T09:00:00Z。

執行下列指令：

Linux、macOS 或 Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

REST

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

  • PROJECT_ID：專案 ID。 Google Cloud
  • SECRET_ID：密鑰的 ID 或密鑰的完整 ID。
  • NEXT_ROTATION_TIME：以 ISO 8601 格式表示的完成首次輪替時間戳記，例如 2021-06-01T09:00:00Z。

HTTP 方法和網址：

PATCH https://secretmanager.googleapis.com/v1/projects/$PROJECT_ID/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.googleapis.com/v1/projects/$PROJECT_ID/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.googleapis.com/v1/projects/$PROJECT_ID/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"
  }
}

停用密鑰輪替

如要停用密鑰輪替功能，請使用下列其中一種方法：

控制台

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

    前往 Secret Manager

  2. 找出要編輯的密鑰，然後點按與該密鑰相關聯的「動作」選單。在「動作」選單中，按一下「編輯」。

  3. 前往「輪播」部分。取消勾選「設定輪替週期」核取方塊，然後按一下「更新密鑰」。

gcloud

移除密鑰的 next_rotation_time

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

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

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud secrets update SECRET_ID \
    --remove-next-rotation-time

Windows (PowerShell)

gcloud secrets update SECRET_ID `
    --remove-next-rotation-time

Windows (cmd.exe)

gcloud secrets update SECRET_ID ^
    --remove-next-rotation-time

移除密鑰的輪替時間表。這會移除 next_rotation_time 和 rotation_period。

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

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

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud secrets update SECRET_ID \
    --remove-rotation-schedule

Windows (PowerShell)

gcloud secrets update SECRET_ID `
    --remove-rotation-schedule

Windows (cmd.exe)

gcloud secrets update SECRET_ID ^
    --remove-rotation-schedule

REST

移除密鑰的下一個輪替時間

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

  • PROJECT_ID：專案 ID Google Cloud
  • SECRET_ID：密鑰的 ID 或密鑰的完整 ID

HTTP 方法和網址：

PATCH https://secretmanager.googleapis.com/v1/projects/$PROJECT_ID/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.googleapis.com/v1/projects/$PROJECT_ID/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.googleapis.com/v1/projects/$PROJECT_ID/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\""
}

移除密鑰的輪替時間表。這會移除下一個輪替時間和輪替週期。

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

  • PROJECT_ID：專案 ID Google Cloud
  • SECRET_ID：密鑰的 ID 或密鑰的完整 ID

HTTP 方法和網址：

PATCH https://secretmanager.googleapis.com/v1/projects/$PROJECT_ID/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.googleapis.com/v1/projects/$PROJECT_ID/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.googleapis.com/v1/projects/$PROJECT_ID/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\""
}

後續步驟