为 Cloud SQL Secret 配置自动轮换

本页面介绍了如何在 Secret Manager 中为 Cloud SQL 数据库凭据配置自动轮换。

准备工作

  • 确保您的 Cloud SQL 实例使用受支持的数据库引擎版本，例如 PostgreSQL 或 SQL Server。
  • 确保您使用的是区域级 Secret。Cloud SQL 凭据的自动轮替仅适用于 Secret Manager 中的区域级密文。全局 Secret 不支持此功能。
  • 确保您已拥有 Cloud SQL 实例和数据库用户。如需了解详情，请参阅创建实例和创建和管理用户。
  • 确保您拥有管理 Cloud SQL 实例的 IAM 政策的权限。如需了解详情，请参阅角色和权限。

所需的角色

如需获得启用自动轮换所需的权限，请让管理员为您授予包含以下权限的角色：

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

您可以通过预定义角色或自定义角色获取这些权限。 如需查看哪些角色与哪些权限相关联，请参阅 Cloud SQL 的 IAM 角色。

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

创建 Cloud SQL 数据库凭据 Secret

如需启用自动轮换，您必须创建类型为 Cloud SQL DB credentials 的 Secret。

控制台

  1. 在 Cloud de Confiance 控制台中，前往 Secret Manager 页面。

    前往 Secret Manager

  2. 在 Secret Manager 页面上，点击区域性 Secret 标签页，然后点击 创建区域性 Secret。

  3. 在创建区域级 Secret 页面的名称字段中，输入 Secret 的名称。

  4. 选中 Set secret type 复选框，然后选择 Cloud SQL DB credentials 作为 Secret 类型。

  5. 从区域列表中选择您要存储区域级密钥的位置。

  6. （可选）在轮替部分，为密文配置轮替时间表。 如果您未配置轮替时间表，则必须手动轮替密文。

    1. 选中设置轮替周期复选框。

    2. 在轮替周期列表中，从默认选项中进行选择，或选择自定义以配置您自己的轮替时间表。

    3. 在开始日期字段中，输入轮替周期的开始日期和时间。

  7. 点击创建密钥。

gcloud

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

  • SECRET_ID：相应 Secret 的 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：相应 Secret 的 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"
  }
}

向内置 Secret 身份授予权限

每个 Secret 都有一个唯一标识符，用于将其与 Cloud de Confiance by S3NS 项目中的所有其他资源区分开来。您必须向内置身份授予更新 Cloud SQL 实例上的凭据所需的必要权限。如需了解详情，请参阅为具有内置身份的资源授予角色。

控制台

  1. 在密文详情页面上，前往概览标签页。

  2. 记下相应 Secret 的 IAM 主账号标识符。

    标识符具有以下格式：principal://secretmanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/LOCATION/secrets/SECRET_UID。

  3. 在 Cloud de Confiance 控制台中，前往 IAM 页面。

    进入 IAM

  4. 点击授予访问权限。

    系统随即会显示授予访问权限面板。

  5. 在新的主账号字段中，输入相应 Secret 的 IAM 主账号标识符。

  6. 从选择角色列表中，选择可授予必要权限的角色。

    如需了解详情，请参阅必需的角色。

  7. 点击保存。

gcloud

获取 Secret 身份

在授予 IAM 权限之前，请描述密文以获取 iamPolicyUidPrincipal 内置身份。添加 IAM 政策绑定时，您可以在 --member 标志中指定此身份字符串。

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

  • SECRET_ID：相应 Secret 的 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 角色

向在上一步中检索到的 Secret Identity 主账号授予包含所需 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：Secret 资源的系统生成的唯一标识符
  • 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

获取 Secret 身份

在授予 IAM 权限之前，请检索 Secret 详细信息以获取 iamPolicyUidPrincipal 内置身份。您可以在设置 IAM 政策时在请求 JSON 中指定此身份字符串。

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

  • LOCATION：相应 Secret 的 Cloud de Confiance by S3NS 位置
  • PROJECT_ID： Cloud de Confiance by S3NS 项目 ID
  • SECRET_ID：相应 Secret 的 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 角色

向在上一步中检索到的 Secret Identity 主账号授予包含所需 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：Secret 资源的系统生成的唯一标识符

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 Secret 的轮替状态为 Disabled。您必须手动轮替密钥，以验证权限并启动自动轮替计划。

控制台

  1. 在 Cloud de Confiance 控制台中，前往 Secret Manager 页面。

    前往 Secret Manager

  2. 在 Secret Manager 页面上，点击区域性密文标签页。

  3. 点击相应 Secret 的名称，前往该 Secret 的详情页面。

  4. 点击 轮替。

    系统随即会显示轮替密文面板。

  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：相应 Secret 的 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

启用托管式轮替

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

  • LOCATION：相应 Secret 的 Cloud de Confiance by S3NS 位置
  • PROJECT_ID： Cloud de Confiance by S3NS 项目 ID
  • SECRET_ID：相应 Secret 的 ID
  • INSTANCE_ID：Cloud SQL 实例 ID
  • USERNAME：Cloud SQL 数据库用户账号名称

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：相应 Secret 的 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，并且预定的自动轮替计时器会开始计时。

后续步骤