Como se conectar pelo proxy do Cloud SQL Auth

Nesta página, você verá como estabelecer uma conexão com a instância do Cloud SQL usando o proxy do Cloud SQL Auth.

Para informações sobre como conectar um cliente sqlcmd a uma instância do Cloud SQL usando um IP público, consulte Como se conectar usando um cliente de banco de dados.

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

Antes de começar

Antes de se conectar a uma instância do Cloud SQL, é necessário:

Opções para autenticar o proxy do Cloud SQL Auth

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 Visão geral da sua instância no Google Cloud Console ou executando o comando a seguir:

gcloud sql instances describe INSTANCE_NAME

Por exemplo, myproject:myregion: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 do Cloud SQL Auth fornece várias alternativas para autenticação, dependendo do seu ambiente. O proxy do Cloud SQL Auth verifica cada um dos itens a seguir, na ordem a seguir, usando o primeiro item encontrado para tentar autenticar:

  1. Credenciais fornecidas pela sinalização credential_file.

    Use uma conta de serviço para criar e fazer o download do arquivo JSON associado e defina a sinalização -credential_file para o caminho do arquivo quando iniciar o proxy do Cloud SQL Auth. 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 sinalização -credential_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 -credential_file=PATH_TO_KEY_FILE -instances=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.

    Para mais informações sobre os papéis compatíveis com o Cloud SQL, consulte Controle de acesso do projeto 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 sinalização -token definida como um token de acesso do OAuth 2.0. Exemplo:
    ./cloud_sql_proxy -token=ACCESS_TOKEN -instances=INSTANCE_CONNECTION_NAME
      
  3. Credenciais fornecidas por uma variável de ambiente.

    Essa opção é semelhante a usar a sinalização -credential_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 -credential_file.
  4. Credenciais de um cliente autenticado do Cloud SDK.

    Se você tiver instalado a ferramenta de linha de comando do Cloud e tiver autenticado sua conta pessoal, o proxy do Cloud SQL Auth poderá usar as mesmas credenciais da conta. Esse método é especialmente útil para colocar um ambiente para desenvolvedores em funcionamento.

    Se nenhuma conta foi selecionada para gcloud auth login, o proxy do Cloud SQL Auth verificará se há uma conta selecionada para 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 do Cloud SQL Auth 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 do Cloud SQL Auth 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 do Cloud SQL Auth. 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 do Cloud SQL Auth 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

  1. Acesse a página Contas de serviço no Console do Google Cloud.

    Acessar a página "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. Na caixa de diálogo Criar conta de serviço, forneça um nome descritivo para a conta.
  5. Altere o ID da conta de serviço para um valor exclusivo e reconhecível e, em seguida, clique em Criar.
  6. Em Papel, selecione um dos seguintes papéis, clique em Continuar e em Concluído:
    • Cloud SQL > Cliente do Cloud SQL
    • Cloud SQL > Editor do Cloud SQL
    • Cloud SQL > Administrador do Cloud SQL
  7. Clique no menu de ações da sua nova conta de serviço e selecione Gerenciar chaves.
  8. Clique no menu suspenso Adicionar chave e clique em Criar nova chave.
  9. 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.

Instalar o proxy do Cloud SQL Auth

Linux de 64 bits

  1. Faça o download do proxy do Cloud SQL Auth:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  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 do Cloud SQL Auth:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. 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 do Cloud SQL Auth:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. Torne o proxy do Cloud SQL Auth executável:
    chmod +x cloud_sql_proxy
    

macOS de 32 bits

  1. Faça o download do proxy do Cloud SQL Auth:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  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://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe e selecione Salvar link como para fazer o download do proxy do Cloud SQL Auth. Renomeie o arquivo para cloud_sql_proxy.exe.

Windows de 32 bits

Clique com o botão direito do mouse em https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe e selecione Salvar link como para fazer o download do proxy do Cloud SQL Auth. Renomeie o arquivo para cloud_sql_proxy.exe.

Imagem do Docker do proxy do Cloud SQL Auth

Por conveniência, a equipe do Cloud SQL mantém várias imagens de contêiner com o proxy do Cloud SQL Auth para uso dos nossos clientes. Para mais informações sobre essas imagens, consulte o repositório do proxy do Cloud SQL Auth no GitHub. É possível extrair a imagem mais recente na sua máquina local usando o Docker com o seguinte comando:
docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1

Outros SOs

Para outros sistemas operacionais não incluídos aqui, compile o proxy do Cloud SQL Auth na origem.

Iniciar o proxy do Cloud SQL Auth

Inicie o proxy do Cloud SQL Auth usando soquetes TCP ou a imagem do Docker desse serviço. O binário do proxy do Cloud SQL Auth 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.

Sockets TCP

Para conexões TCP, o proxy do Cloud SQL Auth detecta em localhost(127.0.0.1) por padrão. Portanto, quando você especifica tcp: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, veja como fazer o proxy do Cloud SQL Auth detectar em 0.0.0.0:1234 para a conexão local:

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234
  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
    .

    Por exemplo, myproject:myregion:myinstance.

  2. Se a instância tiver IP público e particular configurados e você quiser que o proxy do Cloud SQL Auth use o endereço IP particular, forneça a opção a seguir ao iniciar o proxy do Cloud SQL Auth:
    -ip_address_types=PRIVATE
  3. Se você estiver usando uma conta de serviço para autenticar o proxy do Cloud SQL Auth, 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. Iniciar o proxy do Cloud SQL Auth.

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

    • Usando autenticação do SDK do Cloud:
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:1433
      
      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 -instances=INSTANCE_CONNECTION_NAM=tcp:1433 \
                        -credential_file=PATH_TO_KEY_FILE &
      

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

Imagem do Docker do proxy do Cloud SQL Auth

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

Inicie o proxy do Cloud SQL Auth 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 Visão geral da sua instância no Google Cloud Console ou executando o comando a seguir:

gcloud sql instances describe INSTANCE_NAME
.

Por exemplo, myproject:myregion:myinstance.

Dependendo da linguagem e do ambiente, inicie o proxy do Cloud SQL Auth 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:/config \\
  -p 127.0.0.1:1433:1433 \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \\
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1433 -credential_file=/config

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:/config.

Sempre especifique o prefixo 127.0.0.1 em -p para que o proxy do Cloud SQL Auth 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:/config \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy -dir=/cloudsql \\
  -instances=INSTANCE_CONNECTION_NAME -credential_file=/config

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:/config.

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 do Cloud SQL Auth.

Outros argumentos de linha de comando

Os exemplos acima abrangem os casos de uso mais comuns, mas o proxy do Cloud SQL Auth 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 do Cloud SQL Auth no GitHub para ver outros exemplos de como usar as opções de linha de comando do proxy do Cloud SQL Auth.

Conectar-se ao proxy do Cloud SQL Auth

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

Sockets 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 do Cloud SQL Auth é acessado por 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 com o proxy, consulte Como solucionar problemas nas conexões do proxy do Cloud SQL Auth. ou veja a página de suporte do Cloud SQL.

Amostras de código específicas da linguagem

É possível se conectar ao proxy do Cloud SQL Auth por qualquer linguagem que permita se conectar a 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 do Cloud SQL Auth:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:1433 &

Python

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

# Remember - storing secrets in plaintext is potentially unsafe. Consider using
# something like https://cloud.google.com/secret-manager/docs/overview to help keep
# secrets secret.
db_user = os.environ["DB_USER"]
db_pass = os.environ["DB_PASS"]
db_name = os.environ["DB_NAME"]
db_host = os.environ["DB_HOST"]

# Extract host and port from environment variable DB_HOST
host_args = db_host.split(":")
db_hostname, db_port = host_args[0], int(host_args[1])

# SQL Server drivers don't account for this
if db_hostname == "localhost":
    db_hostname = "127.0.0.1"

# The SQLAlchemy engine will help manage interactions, including automatically
# managing a pool of connections to your database
pool = sqlalchemy.create_engine(
    # Equivalent URL:
    # mssql+pytds://<db_user>:<db_pass>@/<host>:<port>/<db_name>?driver=ODBC+Driver+17+for+SQL+Server
    sqlalchemy.engine.url.URL(
        "mssql+pytds",
        username=db_user,
        password=db_pass,
        database=db_name,
        host=db_hostname,
        port=db_port,
    ),
    **db_config
)

Java

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

// Note: For Java users, the Cloud SQL JDBC Socket Factory can provide authenticated connections
// which is preferred to using the Cloud SQL Proxy with Unix sockets.
// See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.

// The configuration object specifies behaviors for the connection pool.
HikariConfig config = new HikariConfig();

// The following is equivalent to setting the config options below:
// jdbc:sqlserver://;user=<DB_USER>;password=<DB_PASS>;databaseName=<DB_NAME>;
// socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;
// socketFactoryConstructorArg=<CLOUD_SQL_CONNECTION_NAME>

// See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
// https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

// Configure which instance and what database user to connect with.
config
    .setDataSourceClassName("com.microsoft.sqlserver.jdbc.SQLServerDataSource");
config.setUsername(DB_USER); // e.g. "root", "sqlserver"
config.setPassword(DB_PASS); // e.g. "my-password"
config.addDataSourceProperty("databaseName", DB_NAME);

config.addDataSourceProperty("socketFactoryClass",
    "com.google.cloud.sql.sqlserver.SocketFactory");
config.addDataSourceProperty("socketFactoryConstructorArg", CLOUD_SQL_CONNECTION_NAME);

// ... Specify additional connection properties here.

// ...

// Initialize the connection pool using the configuration object.
DataSource pool = new HikariDataSource(config);

Node.js

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

const createPool = async () => {
  const config = {pool: {}};
  config.user = process.env.DB_USER; // e.g. 'my-db-user'
  config.password = process.env.DB_PASS; // e.g. 'my-db-password'
  config.database = process.env.DB_NAME; // e.g. 'my-database'
  // set the server to '172.17.0.1' when connecting from App Engine Flex
  config.server = process.env.DEPLOYED ? '172.17.0.1' : '127.0.0.1';
  config.port = 1433;

  // ...
  return await mssql.connect(config);
};

Go

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

var (
	dbUser    = mustGetenv("DB_USER") // e.g. 'my-db-user'
	dbPwd     = mustGetenv("DB_PASS") // e.g. 'my-db-password'
	dbTCPHost = mustGetenv("DB_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'
)

var dbURI string
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("mssql", dbURI)
if err != nil {
	return nil, fmt.Errorf("sql.Open: %v", err)
}

// ...

return dbPool, nil

C#

Para ver esse snippet no contexto de um aplicativo da Web, consulte o README no GitHub (em inglês).

            // Equivalent connection string:
            // "User Id=<DB_USER>;Password=<DB_PASS>;Server=<DB_HOST>;Database=<DB_NAME>;"
            var connectionString = new SqlConnectionStringBuilder()
            {
                // Remember - storing secrets in plain text is potentially unsafe. Consider using
                // something like https://cloud.google.com/secret-manager/docs/overview to help keep
                // secrets secret.
                DataSource = Environment.GetEnvironmentVariable("DB_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;
            // ...
            return connectionString;

Ruby

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

development:
  adapter: sqlserver
  # Configure additional properties here.
  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("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 1433 }%> 

PHP

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

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

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

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);

Tópicos adicionais:

Como usar o proxy do Cloud SQL Auth com 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 do Cloud SQL Auth usa IP para estabelecer uma conexão com sua instância do Cloud SQL. Por padrão, o proxy do Cloud SQL Auth tenta se conectar usando um endereço IPv4 público. Se sua instância do Cloud SQL tiver apenas IP particular, o proxy do Cloud SQL Auth usará o endereço IP particular para se conectar.

Se a instância tiver IP público e particular configurados e você quiser que o proxy do Cloud SQL Auth use o endereço IP particular, forneça a opção a seguir ao iniciar o proxy do Cloud SQL Auth:

-ip_address_types=PRIVATE

Como executar o proxy do Cloud SQL Auth em um processo separado

Executar o proxy do Cloud SQL Auth em um processo de terminal separado 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 do Cloud SQL Auth em um processo separado.

Linux

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

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE &

Windows

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

Start-Process -filepath "cloud_sql_proxy.exe"
  -ArgumentList "-instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE"

Como executar o proxy do Cloud SQL Auth em um contêiner do Docker

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

docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1

Inicie o proxy do Cloud SQL Auth usando soquetes TCP ou Unix, com os comandos mostrados abaixo.

Soquetes TCP

    docker run -d \
      -v PATH_TO_KEY_FILE:/config \
      -p 127.0.0.1:1433:1433 \
      gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \
      -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1433 \
      -credential_file=/config

Soquetes Unix

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/config \
      gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy -dir=/cloudsql \
      -instances=INSTANCE_CONNECTION_NAME
      -credential_file=/config/PATH_TO_KEY_FILE

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:/config.

Como executar o proxy do Cloud SQL Auth como um serviço

A execução do proxy do Cloud SQL Auth como um serviço em segundo plano pode ser conveniente para o desenvolvimento e os testes locais. Quando você precisar acessar sua instância do Cloud SQL, poderá iniciar o serviço em segundo plano e interrompê-lo quando terminar.

  • No momento, o proxy do Cloud SQL Auth não é compatível com a execução como um serviço do Windows, mas os 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 do Cloud SQL Auth como um serviço do Windows. O NSSM monitora o proxy do Cloud SQL Auth e o reinicia automaticamente se ele parar de responder. Consulte a documentação do NSSM para mais informações.

Como se conectar quando o SSL for necessário

Dicas para trabalhar com o proxy do Cloud SQL Auth

Como usar o proxy do Cloud SQL Auth para se conectar a várias instâncias

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

Sockets TCP

Ao se conectar usando TCP, você especifica a porta na máquina que será usada para se conectar à instância. É necessário que cada instância tenha a própria porta. A ferramenta sqlcmd usa 1433 por padrão, mas é possível especificar outra porta para ela usar.

Exemplo:

    # Start the Cloud SQL Auth proxy for two instances, each with its own port:

    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:1433,myProject:us-central1:myInstance2=tcp:1234

    # Connect to "myInstance" on port 1433, and "myInstance2" on port 1234

    sqlcmd -U myUser -S "127.0.0.1,1433"
    sqlcmd -U myUser -S "127.0.0.1,1234"
  

Como solucionar problemas de conexões de proxy do Cloud SQL Auth

A imagem do Docker do proxy do Cloud SQL Auth é baseada em uma versão específica do proxy. Quando uma nova versão do proxy do Cloud SQL Auth estiver disponível, extraia a nova versão da imagem do Docker do proxy do Cloud SQL Auth para manter seu 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 do Cloud SQL Auth, tente estas opções para encontrar o motivo.

  • Verifique a saída do proxy do Cloud SQL Auth.

    Muitas vezes, a saída do proxy do Cloud SQL Auth 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 em que você iniciou o proxy do Cloud SQL Auth.

  • Se você estiver recebendo um erro 403 notAuthorized e estiver usando uma conta de serviço para autenticar o proxy do Cloud SQL Auth, 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.

  • 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 do Cloud SQL Auth.

  • 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 usando soquetes UNIX, confirme se os soquetes foram criados listando o diretório fornecido quando iniciou o proxy do Cloud SQL Auth.

  • 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.

A seguir