Configurar a rotação automática para secrets do Cloud SQL

Nesta página, descrevemos como configurar a rotação automática das credenciais do banco de dados do Cloud SQL no Secret Manager.

Antes de começar

  • Verifique se a instância do Cloud SQL usa uma versão compatível do mecanismo de banco de dados, como PostgreSQL ou SQL Server.
  • Verifique se você está usando um secret regional. A rotação automática de credenciais do Cloud SQL está disponível apenas para secrets regionais no Secret Manager. Os secrets globais não são compatíveis com esse recurso.
  • Verifique se você tem uma instância do Cloud SQL e um usuário de banco de dados. Para mais informações, consulte Criar instâncias e Criar e gerenciar usuários.
  • Verifique se você tem permissões para gerenciar as políticas do IAM na sua instância do Cloud SQL. Para mais informações, consulte Papéis e permissões.

Funções exigidas

Para ter as permissões necessárias para ativar a rotação automática, peça ao administrador para conceder a você um papel que contenha as seguintes permissões:

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

Essas permissões podem ser concedidas com papéis predefinidos ou personalizados. Para conferir quais papéis estão associados a quais permissões, consulte Papéis do IAM para o Cloud SQL.

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Criar um secret de credencial do banco de dados do Cloud SQL

Para ativar a rotação automática, crie um secret do tipo Cloud SQL DB credentials.

Console

  1. No console do Cloud de Confiance , acesse a página Secret Manager.

    Acessar o Secret Manager

  2. Na página Secret Manager, clique na guia Secrets regionais e em Criar secret regional.

  3. Na página Criar secret regional, insira um nome para o secret no campo Nome.

  4. Marque a caixa de seleção Definir tipo de secret e escolha Cloud SQL DB credentials como o tipo de secret.

  5. Escolha o local em que você quer armazenar o secret regional na lista Região.

  6. (Opcional) Na seção Rotação, configure a programação de rotação do seu secret. Se você não configurar uma programação de rotação, será necessário fazer isso manualmente.

    1. Marque a caixa de seleção Definir período de rotação.

    2. Na lista Período de rotação, selecione uma das opções padrão ou Personalizado para configurar sua própria programação de rotação.

    3. No campo Iniciar em, insira a data e a hora de início do período de rotação.

  7. Clique em Criar secret.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • SECRET_ID: o ID do secret
  • LOCATION: o Cloud de Confiance by S3NS local do secret

Execute o seguinte comando:

Linux, macOS ou 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

Você receberá uma resposta semelhante a esta

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

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: o Cloud de Confiance by S3NS local do secret
  • PROJECT_ID: o Cloud de Confiance by S3NS ID do projeto
  • SECRET_ID: o ID do secret

Método HTTP e URL: 

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

Corpo JSON da solicitação:

{
  "secretType": "CLOUD_SQL_DB_CREDENTIALS"
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

$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

Você receberá uma resposta JSON semelhante a esta:

{
  "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"
  }
}

Conceder permissões à identidade secreta integrada

Cada secret tem um identificador exclusivo que o distingue de todos os outros recursos no seu projeto Cloud de Confiance by S3NS . Você precisa conceder à identidade integrada as permissões necessárias para atualizar as credenciais na sua instância do Cloud SQL. Para mais informações, consulte Como conceder papéis a recursos com identidades integradas.

Console

  1. Na página de detalhes do secret, acesse a guia Visão geral.

  2. Anote o identificador principal do IAM do secret.

    O identificador tem o seguinte formato: principal://secretmanager.googleapis.com/projects/PROJECT_NUMBER/uid/locations/LOCATION/secrets/SECRET_UID.

  3. No console do Cloud de Confiance , acesse a página IAM.

    Acessar IAM

  4. Clique em Conceder acesso.

    O painel Conceder acesso vai aparecer.

  5. No campo Novos principais, insira o identificador principal do IAM do secret.

  6. Na lista Selecionar um papel, escolha um papel que conceda as permissões necessárias.

    Para mais informações, consulte Papéis necessários.

  7. Clique em Salvar.

gcloud

Receber a identidade secreta

Antes de conceder permissões do IAM, descreva o secret para receber a identidade integrada iamPolicyUidPrincipal. Você especifica essa string de identidade na flag --member ao adicionar a vinculação de política do IAM.

Antes de usar os dados do comando abaixo, faça estas substituições:

  • SECRET_ID: o ID do secret
  • LOCATION: o Cloud de Confiance by S3NS local do secret

Execute o seguinte comando:

Linux, macOS ou 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)"

Você receberá uma resposta semelhante a esta:

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

Conceder papel do IAM à identidade secreta

Conceda um papel do IAM que contenha as permissões necessárias do Cloud SQL (como cloudsql.users.update e cloudsql.users.list ou o papel predefinido roles/cloudsql.admin) ao principal da identidade secreta recuperado na etapa anterior:

Antes de usar os dados do comando abaixo, faça estas substituições:

  • PROJECT_ID: o Cloud de Confiance by S3NS ID do projeto
  • PROJECT_NUMBER: o número Cloud de Confiance by S3NS numérico do projeto
  • LOCATION: o Cloud de Confiance by S3NS local do secret
  • SECRET_UID: o identificador exclusivo gerado pelo sistema do recurso secreto.
  • ROLE: o papel do IAM concedido à identidade secreta

Execute o seguinte comando:

Linux, macOS ou 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

Receber a identidade secreta

Antes de conceder permissões do IAM, recupere os detalhes do secret para receber a identidade integrada iamPolicyUidPrincipal. Você especifica essa string de identidade no JSON da solicitação ao definir a política do IAM.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: o Cloud de Confiance by S3NS local do secret
  • PROJECT_ID: o Cloud de Confiance by S3NS ID do projeto
  • SECRET_ID: o ID do secret

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

$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

Você receberá uma resposta JSON semelhante a esta:

{
  "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"
  }
}

Conceder papel do IAM à identidade secreta

Conceda um papel do IAM que contenha as permissões necessárias do Cloud SQL (como cloudsql.users.update e cloudsql.users.list ou o papel predefinido roles/cloudsql.admin) ao principal da identidade secreta recuperado na etapa anterior:

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o Cloud de Confiance by S3NS ID do projeto
  • ROLE: o papel do IAM concedido à identidade secreta
  • PROJECT_NUMBER: o número Cloud de Confiance by S3NS numérico do projeto
  • LOCATION: o Cloud de Confiance by S3NS local do secret
  • SECRET_UID: o identificador exclusivo gerado pelo sistema do recurso secreto.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

$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

Você receberá uma resposta JSON semelhante a esta:

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

Mudar a senha

O status de rotação dos secrets do Cloud SQL recém-criados é Disabled até a primeira rotação bem-sucedida. Você precisa fazer a rotação manual do seu secret para verificar as permissões e iniciar a programação de rotação automática.

Console

  1. No console do Cloud de Confiance , acesse a página Secret Manager.

    Acessar o Secret Manager

  2. Na página Secret Manager, clique na guia Secrets regionais.

  3. Clique no nome do secret para acessar a página de detalhes dele.

  4. Clique em Girar.

    O painel Fazer rotação do secret aparece.

  5. Especifique o ID da instância e o nome de usuário da instância do Cloud SQL que você quer atualizar.

  6. (Opcional) Expanda a seção Configurações adicionais para inserir uma senha específica. Se deixado em branco, o Secret Manager vai gerar automaticamente uma senha forte e aleatória.

  7. Clique em Girar.

gcloud

Ativar a rotação gerenciada

Antes de usar os dados do comando abaixo, faça estas substituições:

Execute o seguinte comando:

Linux, macOS ou 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

Fazer a rotação manual do seu secret

Acione uma rotação manual imediata para gerar a versão inicial do secret e verificar a conectividade.

Antes de usar os dados do comando abaixo, faça estas substituições:

  • SECRET_ID: o ID do secret
  • LOCATION: o Cloud de Confiance by S3NS local do secret

Execute o seguinte comando:

Linux, macOS ou 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

Você receberá uma resposta semelhante a esta

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

REST

Ativar a rotação gerenciada

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

$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

Você receberá uma resposta JSON semelhante a esta:

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

Fazer a rotação manual do seu secret

Acione uma rotação manual imediata para gerar a versão inicial do secret e verificar a conectividade.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: o Cloud de Confiance by S3NS local do secret
  • PROJECT_ID: o Cloud de Confiance by S3NS ID do projeto
  • SECRET_ID: o ID do secret

Método HTTP e URL: 

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

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte comando:

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

Execute o seguinte comando: 

$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

Você receberá uma resposta JSON semelhante a esta:

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

O Secret Manager tenta atualizar as credenciais na sua instância do Cloud SQL. Se a operação for bem-sucedida, o Status da rotação vai mudar para Enabled, e o timer de rotação automática programada vai começar.

A seguir