Conectar-se usando o proxy de autenticação do Cloud SQL

MySQL   |  PostgreSQL   |  SQL Server

Nesta página, confira como estabelecer uma conexão com a instância do Cloud SQL usando o proxy de autenticação do Cloud SQL.

Para mais informações sobre como o proxy de autenticação do Cloud SQL funciona, consulte Sobre o proxy de autenticação do Cloud SQL.

Informações gerais

Usar o proxy de autenticação do Cloud SQL é o método recomendado para se conectar a uma instância do Cloud SQL. O proxy de autenticação do Cloud SQL:

• Funciona com endpoints de IP público e particular
• Valida conexões usando credenciais de um usuário ou conta de serviço
• Encapsula a conexão em uma camada SSL/TLS autorizada para uma instância do Cloud SQL

Alguns serviços e aplicativos do Google Cloud usam o proxy de autenticação do Cloud SQL para fornecer conexões a caminhos de IP públicos com criptografia e autorização, incluindo o seguinte:

• Ambiente padrão do App Engine
• Ambiente flexível do App Engine
• Cloud Functions
• Cloud Run

Os aplicativos em execução no Google Kubernetes Engine podem se conectar usando o proxy de autenticação do Cloud SQL.

Observação: para se conectar pelo Google Kubernetes Engine, recomendamos executar o proxy de autenticação do Cloud SQL em um padrão sidecar como um contêiner adicional que compartilha um pod com o aplicativo. Consulte também o guia de início rápido relacionado.

Confira uma introdução básica ao uso do proxy de autenticação no guia de início rápido para uso do proxy de autenticação do Cloud SQL.

Também é possível se conectar, com ou sem o proxy de autenticação do Cloud SQL, usando um cliente sqlcmd por meio de uma máquina local ou do Compute Engine.

Antes de começar

Antes de se conectar a uma instância do Cloud SQL, faça o seguinte:

1. • Para um usuário ou conta de serviço, verifique se a conta tem o papel de cliente do Cloud SQL. Esse papel contém a permissão cloudsql.instances.connect, que autoriza um principal a se conectar a todas as instâncias do Cloud SQL em um projeto.

     Acessar a página IAM

   • Se quiser, é possível incluir uma condição do IAM na vinculação de política do IAM que conceda à conta permissão para se conectar apenas a uma instância específica do Cloud SQL.

2. Enable the Cloud SQL Admin API.

   Enable the API

3. Instale e inicialize a gcloud CLI.
4. Opcional. Instale o cliente Docker do proxy de autenticação do Cloud SQL.

Fazer o download do proxy de autenticação do Cloud SQL

Linux de 64 bits

1. Faça o download do proxy de autenticação do Cloud SQL:

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.linux.amd64

2. Torne o proxy do Cloud SQL Auth executável:

   chmod +x cloud-sql-proxy

Linux de 32 bits

1. Faça o download do proxy de autenticação do Cloud SQL:

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.linux.386

2. Se o comando curl não for encontrado, execute sudo apt install curl e repita o comando de download.
3. Torne o proxy do Cloud SQL Auth executável:

   chmod +x cloud-sql-proxy

macOS de 64 bits

1. Faça o download do proxy de autenticação do Cloud SQL:

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.darwin.amd64

2. Torne o proxy do Cloud SQL Auth executável:

   chmod +x cloud-sql-proxy

Mac M1

1. Faça o download do proxy do Cloud SQL Auth:

     curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.darwin.arm64
     

2. Torne o proxy do Cloud SQL Auth executável:

     chmod +x cloud-sql-proxy
     

Windows de 64 bits

Clique com o botão direito do mouse em https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.x64.exe e selecione Salvar link como para baixar o proxy de autenticação do Cloud SQL. Renomeie o arquivo para cloud-sql-proxy.exe.

Windows de 32 bits

Clique com o botão direito do mouse em https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.x86.exe e selecione Salvar link como para baixar o proxy de autenticação do Cloud SQL. Renomeie o arquivo para cloud-sql-proxy.exe.

Imagem Docker do proxy do Cloud SQL Auth

O proxy do Cloud SQL Auth tem imagens de contêiner diferentes, como distroless, alpine e buster. A imagem de contêiner padrão do proxy do Cloud SQL Auth usa distroless, que não contém shell. Se você precisar de um shell ou de ferramentas relacionadas, faça o download de uma imagem baseada em alpine ou buster. Para mais informações, consulte Imagens de contêiner do proxy do Cloud SQL Auth.

Você pode extrair a imagem mais recente para sua máquina local usando o Docker usando o seguinte comando:

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2

Observação: o proxy do Cloud SQL Auth usa um repositório que oferece suporte ao domínio gcr.io, mas disponibiliza imagens do Artifact Registry. Para mais informações, consulte Transição do Container Registry.

Outros SOs

Para outros sistemas operacionais não incluídos aqui, compile o proxy do Cloud SQL Auth a partir do código-fonte.

Iniciar o proxy de autenticação do Cloud SQL

Inicie o proxy de autenticação do Cloud SQL usando soquetes TCP ou a imagem Docker desse serviço. O binário do proxy de autenticação do Cloud SQL se conecta a uma ou mais instâncias do Cloud SQL especificadas na linha de comando e abre uma conexão local como um soquete TCP. Outros aplicativos e serviços, como o código do aplicativo ou as ferramentas de cliente do gerenciamento de banco de dados, podem se conectar a instâncias do Cloud SQL usando a conexão de soquete TCP.

Aviso: tenha cuidado ao vincular o proxy de autenticação do Cloud SQL a uma interface externa. Qualquer um com acesso a essa interface/porta será autorizado a se conectar à instância.

Soquetes TCP

Para conexões TCP, o proxy de autenticação do Cloud SQL faz a detecção em localhost(127.0.0.1) por padrão. Portanto, quando você especifica --port PORT_NUMBER para uma instância, a conexão local é em 127.0.0.1:PORT_NUMBER.

Como alternativa, você pode especificar um endereço diferente para a conexão local. Por exemplo, confira como fazer o proxy de autenticação do Cloud SQL realizar as detecções em 0.0.0.0:1234 para a conexão local:

./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME

1. Copie o INSTANCE_CONNECTION_NAME. Isso pode ser encontrado na página Visão geral da instância no console do Google Cloud ou executando o seguinte comando: .

       gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'

   .

   Por exemplo, myproject:myregion:myinstance.

2. Se a instância tiver IP público e privado configurados e você quiser que o proxy de autenticação do Cloud SQL use o endereço IP privado, forneça a seguinte opção ao iniciar o proxy de autenticação do Cloud SQL:

   --private-ip

3. Se você estiver usando uma conta de serviço para autenticar o proxy de autenticação do Cloud SQL, anote o local em que o arquivo da chave privada foi criado na máquina do cliente durante a criação da conta de serviço.
4. Inicie o proxy de autenticação do Cloud SQL.

   Algumas strings de invocação possíveis do proxy de autenticação do Cloud SQL:

   • Usando autenticação do SDK do Cloud:

     ./cloud-sql-proxy --port 1433 INSTANCE_CONNECTION_NAME

     A porta especificada não pode estar em uso, por exemplo, por um servidor de banco de dados local.
   • Usar uma conta de serviço e incluir explicitamente o nome da conexão da instância (recomendado para ambientes de produção):

     ./cloud-sql-proxy \
     --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &

   Para mais informações sobre as opções do proxy de autenticação do Cloud SQL, consulte Opções de autenticação do proxy de autenticação do Cloud SQL e Opções para especificar instâncias.

Docker

Para executar o proxy de autenticação do Cloud SQL em um contêiner do Docker, use a respectiva imagem Docker disponível no Google Container Registry.

Inicie o proxy de autenticação do Cloud SQL usando soquetes TCP ou Unix, com os comandos mostrados abaixo. As opções usam uma INSTANCE_CONNECTION_NAME como a string de conexão para identificar uma instância do Cloud SQL. Encontre o INSTANCE_CONNECTION_NAME na página Visão geral da instância no console do Google Cloud ou executando este comando:

gcloud sql instances describe INSTANCE_NAME

.

Por exemplo, myproject:myregion:myinstance.

Observação: o proxy de autenticação do Cloud SQL não oferece suporte à detecção em soquetes de domínio Unix no Windows.

Dependendo da linguagem e do ambiente, inicie o proxy de autenticação do Cloud SQL usando os soquetes TCP ou Unix. Os soquetes Unix não são compatíveis com aplicativos desenvolvidos na linguagem de programação Java ou com o ambiente Windows.

Como usar soquetes TCP

docker run -d \\
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\
  -p 127.0.0.1:1433:1433 \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 \\
  --address 0.0.0.0 --port 1433 \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro --credentials-file e a linha -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Sempre especifique o prefixo 127.0.0.1 em -p para que o proxy de autenticação do Cloud SQL não seja exposto fora do host local. O "0.0.0.0" no parâmetro das instâncias é necessário para tornar a porta acessível de fora do contêiner do Docker.

Como usar soquetes Unix

docker run -d -v /cloudsql:/cloudsql \\
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 --unix-socket=/cloudsql \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro --credentials-file e a linha -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Se você usa uma imagem otimizada para contêiner, utilize um diretório gravável em vez de /cloudsql. Por exemplo:

-v /mnt/stateful_partition/cloudsql:/cloudsql

É possível especificar mais de uma instância, separadas por vírgulas. Também é possível usar metadados do Compute Engine para determinar dinamicamente a quais instâncias se conectar. Saiba mais sobre os parâmetros do proxy de autenticação do Cloud SQL..

Conectar-se com o cliente sqlcmd

Debian/Ubuntu

Para Debian/Ubuntu, instale as ferramentas de linha de comando aplicáveis do SQL Server.

CentOS/RHEL

Para o CentOS/RHEL, instale as ferramentas de linha de comando aplicáveis do SQL Server.

openSUSE

Para o openSUSE, instale as ferramentas de linha de comando aplicáveis do SQL Server.

Outras plataformas

Consulte a página de destino e a página de downloads do SQL Server para instalar o SQL Server.

A string de conexão que você usa depende de como a inicialização do proxy de autenticação do Cloud SQL foi feita, ou seja, usando um soquete TCP ou o Docker.

Soquetes TCP

1. Inicie o cliente sqlcmd:

   sqlcmd -S tcp:127.0.0.1,1433 -U USERNAME -P PASSWORD

   Quando você se conecta usando soquetes TCP, o proxy de autenticação do Cloud SQL é acessado por meio de 127.0.0.1.

2. Se solicitado, digite a senha.
3. Será exibido o prompt sqlcmd.

Precisa de ajuda? Para receber ajuda na solução de problemas do proxy, consulte Solução de problemas de conexões do proxy de autenticação do Cloud SQL ou a página Suporte do Cloud SQL.

Conectar-se com um aplicativo

É possível se conectar ao proxy de autenticação do Cloud SQL por meio de qualquer linguagem que permita a conexão com um soquete TCP. Veja abaixo alguns snippets de código de exemplos completos no GitHub para ajudar você a entender como eles funcionam em conjunto no aplicativo.

Como se conectar com TCP

Instrução de invocação do proxy de autenticação do Cloud SQL:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

import os

import sqlalchemy

def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of SQL Server."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_host = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 1433

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # mssql+pytds://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="mssql+pytds",
            username=db_user,
            password=db_pass,
            database=db_name,
            host=db_host,
            port=db_port,
        ),
        # ...
    )

    return pool

Java

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

Observação:

• CLOUD_SQL_CONNECTION_NAME precisa ser representado como <MEU-PROJETO>:<REGIÃO-DA-INSTÂNCIA>:<NOME-DA-INSTÂNCIA>
• O uso do argumento ipTypes=PRIVATE forçará o SocketFactory a se conectar ao IP privado associado de uma instância
• Consulte os requisitos de versão de fábrica do soquete JDBC para o arquivo pom.xml aqui.

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");

  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(
        String.format("jdbc:sqlserver://%s:%s;databaseName=%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "sqlserver"
    config.setPassword(DB_PASS); // e.g. "my-password"

    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

const mssql = require('mssql');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of SQL Server.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    server: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
    port: parseInt(process.env.DB_PORT), // e.g. 1433
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    options: {
      trustServerCertificate: true,
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return mssql.connect(dbConfig);
};

Go

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"
	"strings"

	_ "github.com/denisenkom/go-mssqldb"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of SQL Server.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.\n", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
		dbPort    = mustGetenv("DB_PORT")       // e.g. '1433'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("server=%s;user id=%s;password=%s;port=%s;database=%s;",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("sqlserver", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

C#

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

using Microsoft.Data.SqlClient;
using System;

namespace CloudSql
{
    public class SqlServerTcp
    {
        public static SqlConnectionStringBuilder NewSqlServerTCPConnectionString()
        {
            // Equivalent connection string:
            // "User Id=<DB_USER>;Password=<DB_PASS>;Server=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new SqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                DataSource = Environment.GetEnvironmentVariable("INSTANCE_HOST"), // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                UserID = Environment.GetEnvironmentVariable("DB_USER"),         // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"),       // e.g. 'my-db-password'
                InitialCatalog = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance
                Encrypt = false,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

tcp: &tcp
  adapter: sqlserver
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("INSTANCE_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 1433 }%> 

PHP

Para conferir esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub.

namespace Google\Cloud\Samples\CloudSQL\SQLServer;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseTcp
{
    public static function initTcpDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceHost = getenv('INSTANCE_HOST'); // e.g. '127.0.0.1' ('172.17.0.1' for GAE Flex)

            // Connect using TCP
            $dsn = sprintf(
                'sqlsrv:server=%s;Database=%s',
                $instanceHost,
                $dbName
            );

            // Connect to the database
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, and $instanceHost (for TCP mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/sqlserver/connect-external-app',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Temas adicionais

Argumentos da linha de comando do proxy de autenticação do Cloud SQL

Os exemplos acima abrangem os casos de uso mais comuns, mas o proxy de autenticação do Cloud SQL também tem outras opções de configuração que podem ser definidas com argumentos de linha de comando. Para receber ajuda sobre argumentos de linha de comando, use a sinalização --help para ver a documentação mais recente:

./cloud-sql-proxy --help

Consulte o README no repositório do proxy de autenticação do Cloud SQL no GitHub para conferir outros exemplos de como usar as opções de linha de comando desse proxy.

Opções de autenticação do proxy de autenticação do Cloud SQL

Quando você autentica o proxy de autenticação do Cloud SQL, você permite que ele acesse o Google Cloud em nome do aplicativo usando um conjunto de credenciais do Google. Isso é diferente da autenticação do usuário do banco de dados.

Todas essas opções usam um INSTANCE_CONNECTION_NAME como a string de conexão para identificar uma instância do Cloud SQL. Encontre o INSTANCE_CONNECTION_NAME na página Visão geral da instância no console do Google Cloud ou executando este comando:

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME

Por exemplo: gcloud sql instances describe --project myproject myinstance.

Algumas dessas opções usam um arquivo de credenciais JSON que inclui a chave privada RSA da conta. Para instruções sobre como criar um arquivo de credenciais JSON para uma conta de serviço, consulte Como criar uma conta de serviço.

O proxy de autenticação do Cloud SQL fornece várias alternativas para autenticação, de acordo com o ambiente. O proxy de autenticação do Cloud SQL verifica cada um dos itens a seguir, na seguinte ordem, usando o primeiro item encontrado para tentar realizar a autenticação:

1. Credenciais fornecidas pela flag credentials-file.

   Use uma conta de serviço para criar e fazer o download do arquivo JSON associado e defina a flag --credentials-file para o caminho do arquivo ao iniciar o proxy de autenticação do Cloud SQL. A conta de serviço precisa ter as permissões necessárias para a instância do Cloud SQL.

   Para usar essa opção na linha de comando, invoque o comando cloud-sql-proxy com a flag --credentials-file definida para o caminho e o nome de um arquivo de credencial JSON. O caminho pode ser absoluto ou relativo ao diretório de trabalho atual. Exemplo:

   ./cloud-sql-proxy --credentials-file PATH_TO_KEY_FILE \
   INSTANCE_CONNECTION_NAME
     

   Para instruções detalhadas sobre como adicionar papéis do IAM a uma conta de serviço, consulte Como conceder papéis a contas de serviço.

   Saiba mais sobre os papéis compatíveis com o Cloud SQL em Papéis do IAM para o Cloud SQL.

2. Credenciais fornecidas por um token de acesso.

   Crie um token de acesso e invoque o comentário cloud-sql-proxy com a flag --token definida como um token de acesso do OAuth 2.0. Exemplo:

   ./cloud-sql-proxy --token ACCESS_TOKEN \
   INSTANCE_CONNECTION_NAME
     

3. Credenciais fornecidas por uma variável de ambiente.

   Essa opção é semelhante a usar a flag --credentials-file, mas, neste caso você especifica o arquivo de credencial JSON definido na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS em vez de usar o argumento de linha de comando --credentials-file.

4. Credenciais de um cliente CLI gcloud autenticado.

   Se você tiver instalado a CLI gcloud e realizado a autenticação com sua conta pessoal, o proxy de autenticação do Cloud SQL poderá usar as mesmas credenciais de conta. Esse método é especialmente útil para colocar um ambiente para desenvolvedores em funcionamento.

   Para permitir que o proxy de autenticação do Cloud SQL use as credenciais da CLI gcloud, use o comando a seguir para autenticá-la:

   gcloud auth application-default login

5. Credenciais associadas à instância do Compute Engine

   Se você estiver usando uma instância do Compute Engine para se conectar ao Cloud SQL, o proxy de autenticação do Cloud SQL poderá usar a conta de serviço associada a essa instância. Se a conta de serviço tiver as permissões necessárias para a instância do Cloud SQL, o proxy de autenticação do Cloud SQL será autenticado com êxito.

   Se a instância do Compute Engine estiver no mesmo projeto que a instância do Cloud SQL, a conta de serviço padrão da instância do Compute Engine terá as permissões necessárias para autenticar o proxy de autenticação do Cloud SQL. Se as duas instâncias estiverem em projetos diferentes, adicione a conta de serviço da instância do Compute Engine ao projeto que contém a instância do Cloud SQL.

6. Conta de serviço padrão do ambiente

   Se o proxy de autenticação do Cloud SQL não conseguir encontrar credenciais em nenhum dos locais cobertos anteriormente, ele seguirá a lógica documentada em Como configurar a autenticação para aplicativos de produção de servidor para servidor. Alguns ambientes (como Compute Engine, App Engine e outros) fornecem uma conta de serviço padrão que o aplicativo pode usar para autenticar por padrão. Para usar uma conta de serviço padrão, ela precisa ter as permissões descritas em papéis e permissões. Para mais informações sobre a abordagem do Google Cloud para autenticação, consulte Visão geral da autenticação.

Crie uma conta de serviço

Se você estiver se conectando do Compute Engine, verifique se a VM tem o scope apropriado para se conectar usando a API Cloud SQL Admin.

Configure a conta de serviço para ter um dos seguintes escopos de acesso:

• https://www.googleapis.com/auth/sqlservice.admin
• https://www.googleapis.com/auth/cloud-platform

1. No Console do Google Cloud, acesse a página Contas de serviço.

   Acessar Contas de serviço

2. Selecione o projeto que contém a instância do Cloud SQL.
3. Clique em Criar conta de serviço.
4. Preencha o campo Nome da conta de serviço.
5. Altere o ID da conta de serviço para um valor exclusivo e facilmente reconhecível, depois clique em Criar e continuar.
6. Clique no campo Selecionar papel e escolha um dos seguintes papéis:
   • Cloud SQL > Cliente do Cloud SQL
   • Cloud SQL > Editor do Cloud SQL
   • Cloud SQL > Administrador do Cloud SQL
   Observação: para criar uma conta de serviço com as permissões necessárias, você precisa ter a permissão resourcemanager.projects.setIamPolicy. Essa permissão está incluída nos papéis de proprietário do projeto, administrador do IAM do projeto e administrador da organização.
   Você também precisa ativar a API Cloud SQL Admin. Se você estiver usando os papéis legados (visualizador, editor e proprietário) do projeto, a conta de serviço precisará ter pelo menos o papel de editor.
7. Clique em Concluído para terminar a criação da conta de serviço.
8. Clique no menu de ações da sua nova conta de serviço e selecione Gerenciar chaves.
9. Clique no menu suspenso Adicionar chave e clique em Criar nova chave.
10. Confirme se o tipo de chave é JSON e clique em Criar.

    O arquivo da chave privada é transferido para sua máquina. Você pode movê-lo para outro local. Mantenha-o seguro.

Usar o proxy de autenticação do Cloud SQL com um IP privado

Para se conectar a uma instância do Cloud SQL usando o IP particular, o proxy do Cloud SQL Auth precisa estar em um recurso com acesso à mesma rede VPC que a instância.

O proxy de autenticação do Cloud SQL usa um IP para estabelecer uma conexão com a instância do Cloud SQL. Por padrão, ele tenta se conectar usando um endereço IPv4 público.

Se a instância do Cloud SQL tiver apenas um IP privado ou tiver um IP público e um privado configurados e você quiser que o proxy do Cloud SQL Auth usar o endereço IP privado, forneça a seguinte opção ao iniciar o proxy do Cloud SQL Auth:

--private-ip

Usar o proxy de autenticação do Cloud SQL com instâncias que tenham o Private Service Connect ativado

Use o proxy do Cloud SQL Auth para se conectar a uma instância do Cloud SQL com o Private Service Connect ativado.

O proxy de autenticação do Cloud SQL é um conector que fornece acesso seguro a essa instância sem a necessidade de redes autorizadas ou configuração de SSL.

Para permitir conexões de cliente do proxy de autenticação do Cloud SQL, você precisa configurar um registro DNS que corresponda ao nome DNS recomendado que foi fornecido para a instância. O registro DNS é um mapeamento entre um recurso de DNS e um nome de domínio.

Para mais informações sobre como usar o proxy do Cloud SQL Auth para se conectar a instâncias com o Private Service Connect ativado, consulte Conectar usando o proxy de autenticação do Cloud SQL.

Executar o proxy de autenticação do Cloud SQL em um processo separado

Executar o proxy de autenticação do Cloud SQL em um processo de terminal separado do Cloud Shell pode ser útil para evitar misturar a saída do console com a saída de outros programas. Use a sintaxe mostrada abaixo para invocar o proxy de autenticação do Cloud SQL em um processo separado.

Linux

No Linux ou no macOS, use um & à direita na linha de comando para iniciar o proxy de autenticação do Cloud SQL em um processo separado:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME
  --credentials-file PATH_TO_KEY_FILE &

Windows

No Windows PowerShell, use o comando Start-Process para iniciar o proxy de autenticação do Cloud SQL em um processo separado:

Start-Process --filepath "cloud-sql-proxy.exe"
  --ArgumentList "
  --credentials-file PATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"

Executar o proxy de autenticação do Cloud SQL em um contêiner do Docker

Para executar o proxy de autenticação do Cloud SQL em um contêiner do Docker, use a respectiva imagem Docker disponível no Google Container Registry. É possível instalar a imagem Docker do proxy de autenticação do Cloud SQL com este comando gcloud:

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2

Inicie o proxy de autenticação do Cloud SQL usando soquetes TCP ou Unix, com os comandos mostrados abaixo.

Observação: os soquetes Unix não são compatíveis com aplicativos desenvolvidos na linguagem de programação Java ou com o ambiente Windows.

Soquetes TCP

    docker run -d \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      -p 127.0.0.1:1433:1433 \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 \
      --address 0.0.0.0 \
      --credentials-file /path/to/service-account-key.json \
      INSTANCE_CONNECTION_NAME

Soquetes Unix

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 --unix-socket /cloudsql \
      --credentials-file /path/to/service-account-key.json/PATH_TO_KEY_FILE \
      INSTANCE_CONNECTION_NAME

Se você usa uma imagem otimizada para contêiner, utilize um diretório gravável em vez de /cloudsql. Por exemplo:

v /mnt/stateful_partition/cloudsql:/cloudsql

Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro credential_file e a linha -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Como executar o proxy de autenticação do Cloud SQL como um serviço

Executar o proxy de autenticação do Cloud SQL como um serviço em segundo plano é uma opção para cargas de trabalho de desenvolvimento e produção locais. Em desenvolvimento, quando você precisar acessar sua instância do Cloud SQL, inicie o serviço em segundo plano e interrompa-o quando terminar.

No momento, no caso das cargas de trabalho de produção, o proxy de autenticação do Cloud SQL não é compatível com a execução como um serviço do Windows, mas gerenciadores de serviço de terceiros podem ser usados para executá-lo como um serviço. Por exemplo, use o NSSM para configurar o proxy de autenticação do Cloud SQL como um serviço do Windows. O NSSM monitora o proxy de autenticação do Cloud SQL e o reinicia automaticamente quando ele deixa de responder. Consulte a documentação do NSSM para mais informações.

Observação: se você executar o proxy de autenticação do Cloud SQL como um serviço, lembre-se de que ele usa uma conexão segura para se comunicar com as instâncias do Cloud SQL. No entanto, as conexões do aplicativo com o proxy de autenticação do Cloud SQL não são criptografadas. Por esse motivo, garanta que apenas usuários confiáveis possam acessar o endereço e a porta por onde o proxy de autenticação do Cloud SQL faz as detecções.

Conectar quando o SSL for necessário

Observação: se uma instância do SQL Server tiver a opção Exigir SSL/TLS marcada, mesmo com o proxy de autenticação do Cloud SQL ou os conectores do Cloud SQL, o aplicativo cliente precisará ter o TLS/SSL configurado como se o proxy de autenticação do Cloud SQL ou os conectores do Cloud SQL não estivessem envolvidos, caso contrário, uma tentativa de conexão poderá falhar. Para conexões bem-sucedidas, o proxy do Cloud SQL Auth ou os conectores do Cloud SQL adicionam outra camada de criptografia além da criptografia nativa do SQL Server. Em outras palavras, a conexão entre os conectores do cliente proxy/Cloud SQL e o servidor proxy seria criptografada duas vezes.
A criptografia dupla pode afetar negativamente o desempenho do SQL Server. Sugerimos uma consideração cuidadosa antes de exigir SSL e usar o proxy de autenticação do Cloud SQL ou os conectores do Cloud SQL ao mesmo tempo.

Exigir o uso do proxy de autenticação do Cloud SQL

Ative o uso do proxy de autenticação do Cloud SQL no Cloud SQL usando ConnectorEnforcement.

gcloud

O comando a seguir impõe o uso dos conectores do Cloud SQL.

    gcloud sql instances patch INSTANCE_NAME \
    --connector-enforcement REQUIRED
  

Para desativar a aplicação, use a seguinte linha de código: --connector-enforcement NOT_REQUIRED A atualização não aciona uma reinicialização.

REST v1

O comando a seguir aplica o uso dos conectores do Cloud SQL

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

• project-id: o ID do projeto.
• instance-id: o ID da instância

Método HTTP e URL:

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Corpo JSON da solicitação:

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud . É possível verificar a conta ativa atual executando gcloud auth list.

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

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

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

$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://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Para desativar a aplicação, use "connectorEnforcement": "NOT_REQUIRED". A atualização não aciona uma reinicialização.

REST v1beta4

O comando a seguir impõe o uso dos conectores do Cloud SQL.

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

• project-id: o ID do projeto.
• instance-id: o ID da instância

Método HTTP e URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Corpo JSON da solicitação:

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud . É possível verificar a conta ativa atual executando gcloud auth list.

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

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

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

$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://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Para desativar a aplicação, use "connectorEnforcement": "NOT_REQUIRED". A atualização não aciona uma reinicialização.

Dicas para trabalhar com o proxy de autenticação do Cloud SQL

Usar o proxy de autenticação do Cloud SQL para a conexão com várias instâncias

Use um cliente local do proxy de autenticação do Cloud SQL para se conectar a várias instâncias do Cloud SQL. A maneira de fazer isso dependerá do uso de soquetes Unix ou TCP.

Soquetes TCP

Ao se conectar usando TCP, você especificará uma porta na máquina para que o proxy de autenticação do Cloud SQL faça a detecção para cada instância do Cloud SQL. Ao se conectar a várias instâncias do Cloud SQL, cada porta especificada precisa ser exclusiva e estar disponível para uso em sua máquina.

Exemplo:

    # Start the Cloud SQL Auth Proxy to connect to two different Cloud SQL instances.
    # Give the Cloud SQL Auth Proxy a unique port on your machine to use for each Cloud SQL instance.

    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=1433" \
    "myProject:us-central1:myInstance2?port=1234"

    # Connect to "myInstance" using port 1433 on your machine:
    sqlcmd -U myUser -S "127.0.0.1,1433"

    # Connect to "myInstance2" using port 1234 on your machine:
    sqlcmd -U myUser -S "127.0.0.1,1234"
  

Resolver problemas de conexões do proxy de autenticação do Cloud SQL

A imagem do Docker do proxy de autenticação do Cloud SQL é baseada em uma versão específica do proxy. Quando uma nova versão do proxy de autenticação do Cloud SQL estiver disponível, extraia a nova versão da imagem Docker do proxy de autenticação do Cloud SQL para manter o ambiente atualizado. Você pode ver qual é a versão atual na página de versões do proxy do Cloud SQL Auth no GitHub.

Se você tiver problemas para se conectar à instância do Cloud SQL usando o proxy de autenticação do Cloud SQL, tente aplicar as opções a seguir para encontrar o motivo.

• Verifique a saída do proxy de autenticação do Cloud SQL.

  Muitas vezes, a saída do proxy pode ajudar você a determinar a origem do problema e saber como resolvê-lo. Redirecione a saída para um arquivo ou observe o terminal do Cloud Shell em que você iniciou o proxy de autenticação do Cloud SQL.

• Se você estiver recebendo um erro 403 notAuthorized e estiver usando uma conta de serviço para autenticar o proxy de autenticação de Cloud SQL, verifique se a conta de serviço tem as permissões corretas.

  Você pode verificar a conta de serviço pesquisando pelo ID dela na página "IAM". A conta precisa ter a permissão cloudsql.instances.connect. Os papéis predefinidos Cloud SQL Admin, Client e Editor têm essa permissão.

• Se você estiver se conectando a partir do App Engine e estiver recebendo um erro 403 notAuthorized, verifique a cloud_sql_instances valor app.yaml quanto a um nome de conexão de instância incorreto ou incorreto. Os nomes das conexões de instâncias estão sempre no formato PROJECT:REGION:INSTANCE.

  Além disso, verifique se a conta de serviço do App Engine (por exemplo, $[e-mail]) tem o papel de Cliente do Cloud SQL do IAM.

  Se o serviço do App Engine residir em um projeto (projeto A) e o banco de dados em outro (projeto B), esse erro significa que a conta de serviço do App Engine não recebeu o papel de Cliente do Cloud SQL do IAM no projeto com o banco de dados (projeto B).

• Certifique-se de ativar a API Cloud SQL Admin.

  Caso contrário, você verá uma saída como Error 403: Access Not Configured nos registros do proxy de autenticação do Cloud SQL.

• Se você estiver incluindo várias instâncias na lista de instâncias, use a vírgula como delimitador, sem espaços. Se você estiver usando o TCP, especifique portas diferentes para cada instância.

• Se você estiver se conectando com soquetes UNIX, confirme se eles foram criados listando o diretório fornecido quando você iniciou o proxy de autenticação do Cloud SQL.

• Se você tiver uma política de firewall para o tráfego de saída, verifique se ela permite conexões com a porta 3307 na instância do Cloud SQL de destino.

  Observação: o proxy de autenticação do Cloud SQL usa a porta 3307 para se conectar ao servidor do proxy de autenticação do Cloud SQL. A porta 1433 é a porta padrão do protocolo do SQL Server em uma conexão TCP direta (que não usa o proxy de autenticação do Cloud SQL).

• É possível confirmar se o proxy de autenticação do Cloud SQL foi iniciado corretamente procurando nos registros na seção Operações > Logging > Análise de registros do console do Google Cloud. Uma operação bem-sucedida é semelhante a esta:

  2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/1433 for $PROJECT_ID:$REGION:$INSTANCE_NAME
  2021/06/14 15:47:56 Ready for new connections
  

• Problemas de cota: quando a cota da API Cloud SQL Admin é violada, o proxy de autenticação do Cloud SQL é iniciado com a seguinte mensagem de erro:

  There was a problem when parsing a instance configuration but ignoring due
  to the configuration. Error: googleapi: Error 429: Quota exceeded for quota
  metric 'Queries' and limit 'Queries per minute per user' of service
  'sqladmin.googleapis.com' for consumer 'project_number:$PROJECT_ID.,
  rateLimitExceeded
  

  Depois que um aplicativo se conecta ao proxy, o proxy informa o seguinte erro:

  failed to refresh the ephemeral certificate for $INSTANCE_CONNECTION_NAME:
  googleapi: Error 429: Quota exceeded for quota metric 'Queries' and limit
  'Queries per minute per user' of service 'sqladmin.googleapis.com' for
  consumer 'project_number:$PROJECT_ID., rateLimitExceeded
  

  Solução: identifique a origem do problema de cota, por exemplo, um aplicativo está usando o conector de maneira incorreta e criando novas conexões desnecessariamente, ou entre em contato com o suporte para solicitar um aumento na cota da API Cloud SQL Admin. Se o erro de cota aparecer na inicialização, você precisará reimplantar o aplicativo para reiniciar o proxy. Se o erro de cota aparecer após a inicialização, a reimplantação será desnecessária.

A seguir

• Saiba mais sobre o proxy de autenticação do Cloud SQL.
• Saiba mais sobre o Gerenciamento de identidade e acesso.
• Saiba mais sobre Contas de serviço.
• Saiba mais sobre os dois níveis de controle de acesso para instâncias do Cloud SQL.
• Crie usuários e bancos de dados.
• Saiba mais sobre como se conectar à instância pelo aplicativo.
• Conheça as opções de suporte.