設定 Cloud SQL 密碼的自動輪換功能

本頁說明如何設定 Secret Manager 中的 Cloud SQL 資料庫憑證自動輪替。

事前準備

  • 請確認 Cloud SQL 執行個體使用支援的資料庫引擎類型，例如 PostgreSQL 或 SQL Server。
  • 請確認您使用的是區域性 Secret。Cloud SQL 憑證的自動輪換功能僅適用於 Secret Manager 中的區域性密鑰。全域密鑰不支援這項功能。
  • 請確認您已有 Cloud SQL 執行個體和資料庫使用者。詳情請參閱「建立執行個體」和「建立及管理使用者」。
  • 確認您有權管理 Cloud SQL 執行個體的 IAM 政策。詳情請參閱「角色和權限」。

必要的角色

如要取得啟用自動輪替功能所需的權限，請要求管理員授予您具備下列權限的角色：

  • cloudsql.users.list
  • cloudsql.users.update

您可以透過預先定義的角色或自訂角色取得這些權限。 如要瞭解哪些角色與哪些權限相關聯，請參閱「Cloud SQL 的 IAM 角色」。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

建立 Cloud SQL 資料庫憑證密碼

如要啟用自動輪替功能，必須建立 Cloud SQL DB credentials 類型的密鑰。

控制台

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

    前往 Secret Manager

  2. 在「Secret Manager」頁面中，按一下「Regional secrets」(區域密鑰) 分頁標籤，然後按一下 「Create regional secret」(建立區域密鑰)。

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

  4. 選取「設定密鑰類型」核取方塊，然後選擇 Cloud SQL DB credentials 做為密鑰類型。

  5. 從「Region」(區域) 清單中，選擇要儲存區域密鑰的位置。

  6. (選用) 在「Rotation」(輪替) 部分，設定密鑰的輪替排程。 如果未設定輪替時間表，您就必須手動輪替密鑰。

    1. 選取「設定輪替週期」核取方塊。

    2. 在「輪替週期」清單中，選取預設選項或「自訂」，設定自己的輪替時間表。

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

  7. 點選「建立密鑰」。

gcloud

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

  • SECRET_ID：密鑰 ID
  • LOCATION：Secret 的 Cloud de Confiance by S3NS 位置

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud secrets create SECRET_ID \
    --location=LOCATION \
    --secret-type=CLOUD_SQL_DB_CREDENTIALS

Windows (PowerShell)

gcloud secrets create SECRET_ID `
    --location=LOCATION `
    --secret-type=CLOUD_SQL_DB_CREDENTIALS

Windows (cmd.exe)

gcloud secrets create SECRET_ID ^
    --location=LOCATION ^
    --secret-type=CLOUD_SQL_DB_CREDENTIALS

您應該會收到類似以下的回應：

Created secret [projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID].

REST

使用任何要求資料之前，請先修改下列項目的值：

  • LOCATION：Secret 的 Cloud de Confiance by S3NS 位置
  • PROJECT_ID： Cloud de Confiance by S3NS 專案 ID
  • SECRET_ID：密鑰 ID

HTTP 方法和網址：

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

JSON 要求內文：

{
  "secretType": "CLOUD_SQL_DB_CREDENTIALS"
}

如要傳送要求，請選擇以下其中一個選項：

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_NUMBER/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2026-07-28T05:00:00Z",
  "secretType": "CLOUD_SQL_DB_CREDENTIALS",
  "etag": "\"1a2b3c4d\"",
  "policyMember": {
    "iamPolicyUidPrincipal": "principal://secretmanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/LOCATION/secrets/SECRET_UID"
  }
}

將權限授予內建密鑰身分

每個密鑰都有專屬 ID，可與 Cloud de Confiance by S3NS 專案中的所有其他資源區別。您必須授予內建身分必要的權限，才能更新 Cloud SQL 執行個體的憑證。 詳情請參閱「使用內建身分授予資源角色」。

控制台

  1. 在密鑰詳細資料頁面中，前往「總覽」分頁標籤。

  2. 記下密鑰的 IAM 主體 ID。

    ID 的格式如下：principal://secretmanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/LOCATION/secrets/SECRET_UID。

  3. 前往 Cloud de Confiance 控制台的「IAM」(身分與存取權管理) 頁面。

    前往「IAM」頁面

  4. 按一下「授予存取權」。

    系統隨即會顯示「授予存取權」面板。

  5. 在「New principals」(新增主體) 欄位中，輸入密碼的 IAM 主體 ID。

  6. 在「Select a role」(選取角色) 清單中，選取具備必要權限的角色。

    詳情請參閱「必要的角色」。

  7. 按一下 [儲存]。

gcloud

取得密鑰身分

授予 IAM 權限前，請先說明密碼，取得 iamPolicyUidPrincipal 內建身分。新增 IAM 政策繫結時，請在 --member 旗標中指定這個身分字串。

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

  • SECRET_ID：密鑰 ID
  • LOCATION：Secret 的 Cloud de Confiance by S3NS 位置

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud secrets describe SECRET_ID \
    --location=LOCATION \
    --format="value(policyMember.iamPolicyUidPrincipal)"

Windows (PowerShell)

gcloud secrets describe SECRET_ID `
    --location=LOCATION `
    --format="value(policyMember.iamPolicyUidPrincipal)"

Windows (cmd.exe)

gcloud secrets describe SECRET_ID ^
    --location=LOCATION ^
    --format="value(policyMember.iamPolicyUidPrincipal)"

您應該會收到類似以下的回應：

principal://secretmanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/LOCATION/secrets/SECRET_UID

將 IAM 角色授予密鑰身分

將包含必要 Cloud SQL 權限 (例如 cloudsql.users.update 和 cloudsql.users.list，或預先定義的 roles/cloudsql.admin 角色) 的 IAM 角色，授予上一個步驟中擷取的密鑰身分主體：

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

  • PROJECT_ID： Cloud de Confiance by S3NS 專案 ID
  • PROJECT_NUMBER： Cloud de Confiance by S3NS 專案編號 (數字)
  • LOCATION：Secret 的 Cloud de Confiance by S3NS 位置
  • SECRET_UID：系統產生的密鑰資源專屬 ID
  • ROLE：授予密碼身分的 IAM 角色

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="principal://secretmanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/LOCATION/secrets/SECRET_UID" \
    --role="ROLE"

Windows (PowerShell)

gcloud projects add-iam-policy-binding PROJECT_ID `
    --member="principal://secretmanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/LOCATION/secrets/SECRET_UID" `
    --role="ROLE"

Windows (cmd.exe)

gcloud projects add-iam-policy-binding PROJECT_ID ^
    --member="principal://secretmanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/LOCATION/secrets/SECRET_UID" ^
    --role="ROLE"

REST

取得密鑰身分

授予 IAM 權限前，請先擷取密鑰詳細資料，取得 iamPolicyUidPrincipal 內建身分。設定 IAM 政策時，您會在要求 JSON 中指定這個身分字串。

使用任何要求資料之前，請先修改下列項目的值：

  • LOCATION：Secret 的 Cloud de Confiance by S3NS 位置
  • PROJECT_ID： Cloud de Confiance by S3NS 專案 ID
  • SECRET_ID：密鑰 ID

HTTP 方法和網址：

GET https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID

JSON 要求內文：

{
  "policy": {
    "bindings": [
      {
        "role": "ROLE",
        "members": [
          "principal://secretmanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/LOCATION/secrets/SECRET_UID"
        ]
      }
    ]
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X GET \
     -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"

PowerShell

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

Invoke-WebRequest `
    -Method GET `
    -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" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2026-07-28T05:00:00Z",
  "secretType": "CLOUD_SQL_DB_CREDENTIALS",
  "etag": "\"1a2b3c4d\"",
  "policyMember": {
    "iamPolicyUidPrincipal": "principal://secretmanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/LOCATION/secrets/SECRET_UID"
  }
}

將 IAM 角色授予密鑰身分

將包含必要 Cloud SQL 權限 (例如 cloudsql.users.update 和 cloudsql.users.list，或預先定義的 roles/cloudsql.admin 角色) 的 IAM 角色，授予上一個步驟中擷取的密鑰身分主體：

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID： Cloud de Confiance by S3NS 專案 ID
  • ROLE：授予密碼身分的 IAM 角色
  • PROJECT_NUMBER： Cloud de Confiance by S3NS 專案編號 (數字)
  • LOCATION：Secret 的 Cloud de Confiance by S3NS 位置
  • SECRET_UID：系統產生的密鑰資源專屬 ID

HTTP 方法和網址：

POST https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:setIamPolicy

JSON 要求內文：

{
  "policy": {
    "bindings": [
      {
        "role": "ROLE",
        "members": [
          "principal://secretmanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/LOCATION/secrets/SECRET_UID"
        ]
      }
    ]
  }
}

如要傳送要求，請選擇以下其中一個選項：

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://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:setIamPolicy"

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://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:setIamPolicy" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "version": 1,
  "etag": "BwWWv0I7vBw=",
  "bindings": [
    {
      "role": "roles/cloudsql.admin",
      "members": [
        "principal://secretmanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/LOCATION/secrets/SECRET_UID"
      ]
    }
  ]
}

輪替密鑰

新建立的 Cloud SQL 密鑰輪換狀態為 Disabled，直到首次輪換成功為止。您必須手動輪替密鑰，才能驗證權限並啟動自動輪替排程。

控制台

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

    前往 Secret Manager

  2. 在「Secret Manager」頁面中，按一下「Regional secrets」分頁標籤。

  3. 按一下密鑰名稱，前往密鑰詳細資料頁面。

  4. 按一下「旋轉」。

    系統會顯示「Rotate secret」(輪替密鑰) 面板。

  5. 指定要更新的 Cloud SQL 執行個體 ID 和使用者名稱。

  6. (選用) 展開「其他設定」部分，輸入特定密碼。 如果留空，Secret Manager 會自動產生隨機高強度密碼。

  7. 按一下「旋轉」。

gcloud

啟用代管輪換功能

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

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud secrets enable-managed-rotation SECRET_ID \
    --location=LOCATION \
    --instance-id=INSTANCE_ID \
    --username=USERNAME

Windows (PowerShell)

gcloud secrets enable-managed-rotation SECRET_ID `
    --location=LOCATION `
    --instance-id=INSTANCE_ID `
    --username=USERNAME

Windows (cmd.exe)

gcloud secrets enable-managed-rotation SECRET_ID ^
    --location=LOCATION ^
    --instance-id=INSTANCE_ID ^
    --username=USERNAME

手動輪替密鑰

立即觸發手動輪替，產生初始密鑰版本並驗證連線。

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

  • SECRET_ID：密鑰 ID
  • LOCATION：Secret 的 Cloud de Confiance by S3NS 位置

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud secrets rotate-secret SECRET_ID \
    --location=LOCATION

Windows (PowerShell)

gcloud secrets rotate-secret SECRET_ID `
    --location=LOCATION

Windows (cmd.exe)

gcloud secrets rotate-secret SECRET_ID ^
    --location=LOCATION

您應該會收到類似以下的回應：

Name: projects/PROJECT_NUMBER/locations/LOCATION/secrets/SECRET_ID/versions/1
State: ENABLED

REST

啟用代管輪換功能

使用任何要求資料之前，請先修改下列項目的值：

HTTP 方法和網址：

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

JSON 要求內文：

{
  "cloudSqlSingleUserCredentials": {
    "instanceId": "INSTANCE_ID",
    "username": "USERNAME"
  }
}

如要傳送要求，請選擇以下其中一個選項：

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/SECRET_ID:enableManagedRotation"

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/SECRET_ID:enableManagedRotation" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/secrets/SECRET_ID/versions/1",
  "createTime": "2026-07-28T05:00:00Z",
  "state": "ENABLED"
}

手動輪替密鑰

立即觸發手動輪替，產生初始密鑰版本並驗證連線。

使用任何要求資料之前，請先修改下列項目的值：

  • LOCATION：Secret 的 Cloud de Confiance by S3NS 位置
  • PROJECT_ID： Cloud de Confiance by S3NS 專案 ID
  • SECRET_ID：密鑰 ID

HTTP 方法和網址：

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

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID:rotateSecret"

PowerShell

執行下列指令： 

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID:rotateSecret" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/secrets/SECRET_ID/versions/1",
  "createTime": "2026-07-28T05:00:00Z",
  "state": "ENABLED"
}

Secret Manager 會嘗試更新 Cloud SQL 執行個體中的憑證。如果成功，輪替狀態會變更為 Enabled，並開始計時，等待排定的自動輪替時間到來。

後續步驟