Conectar usando o 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 mais informações sobre como o proxy de autenticação do Cloud SQL funciona, consulte Sobre o proxy do Cloud SQL Auth.

Visão geral

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

  • 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 do Cloud SQL Auth para fornecer conexões para caminhos de IP públicos com criptografia e autorização, incluindo:

Os aplicativos em execução no Google Kubernetes Engine podem se conectar usando o Cloud SQL Auth Proxy.

Consulte o Guia de início rápido para usar o proxy do Cloud SQL Auth para uma introdução básica ao uso.

Também é possível se conectar, com ou sem o proxy do Cloud SQL Auth, usando um cliente mysql 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. Verifique se você tem o papel "Cliente do Cloud SQL" na conta de usuário.

    Acessar a página IAM

  2. Ative a API Cloud SQL Admin.

    Ative a API

  3. Instale e inicialize o Cloud SDK.
  4. Opcional. Instale o cliente Docker do proxy do Cloud SQL Auth.

Faça o download do 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. Se o comando wget não for encontrado, execute sudo apt-get install wget 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 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, várias imagens de contêiner que contêm o proxy do Cloud SQL Auth estão disponíveis no GitHub no repositório do proxy do Cloud SQL Auth. É 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

Dependendo da linguagem e do ambiente, é possível iniciar o proxy do Cloud SQL Auth usando soquetes TCP, soquetes Unix ou a imagem do Docker do proxy do Cloud SQL Auth. O binário de 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 tanto como um soquete TCP como um Unix. Outros aplicativos e serviços, como o código do aplicativo ou as ferramentas de cliente de gerenciamento de banco de dados, podem se conectar a instâncias do Cloud SQL por meio dessas conexões de soquete TCP ou Unix.

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:3306
      
      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:3306 \
                        -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.

Sockets Unix

O proxy do Cloud SQL Auth também pode detectar em um soquete Unix, mecanismo padrão do Posix para usar uma pasta que gerencia a comunicação entre dois processos em execução no mesmo host. As vantagens de usar soquetes Unix são a segurança aprimorada e a latência menor. No entanto, não é possível acessar um soquete Unix de uma máquina externa.

Para criar e usar um soquete Unix, o diretório de destino precisa existir e o proxy do Cloud SQL Auth e o aplicativo precisam ter acesso de leitura e gravação a ele.

  1. Se você estiver usando a especificação explícita de instâncias, copie a 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. Crie o diretório onde ficarão os soquetes do proxy do Cloud SQL Auth:
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  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. Abra uma nova janela de terminal do Cloud Shell e inicie o proxy do Cloud SQL Auth.

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

    • 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 -dir=/cloudsql -instances=INSTANCE_CONNECTION_NAME
      -credential_file=PATH_TO_KEY_FILE &
    • Usando a autenticação do SDK do Cloud e a descoberta automática de instâncias:
      ./cloud_sql_proxy -dir=/cloudsql &

    Inicie o proxy do Cloud SQL Auth no próprio terminal do Cloud Shell para monitorar a saída sem misturá-la com a saída de outros programas.

    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.

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.

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:3306:3306 \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \\
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:3306 -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 o parâmetro do proxy do Cloud SQL Auth..

Estabeleça uma conexão com o cliente MySQL.

  1. Faça o download do MySQL Community Server referente à sua plataforma da página de downloads do MySQL Community Server (em inglês).
    O Community Server inclui o cliente MySQL.
  2. Instale o Community Server, seguindo as instruções na página de downloads.

Para mais informações sobre a instalação do MySQL, consulte Como instalar e fazer upgrade do MySQL.

A string da conexão usada depende de como você iniciou o proxy do Cloud SQL Auth: usando um soquete TCP, Unix ou o Docker.

Sockets TCP

  1. Inicie o cliente MySQL:
    mysql -u USERNAME -p --host 127.0.0.1
    

    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. O prompt do mysql é exibido.

Como usar soquetes Unix

  1. Inicie o cliente MySQL:
    mysql -u USERNAME -p -S /cloudsql/INSTANCE_CONNECTION_NAME
    
  2. Digite a senha.
  3. O prompt do mysql é exibido.

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

Conectar-se com um aplicativo

Você pode se conectar ao proxy do Cloud SQL Auth por qualquer linguagem que permita se conectar a um soquete Unix ou 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.

Temas adicionais

Argumentos da linha de comando do proxy do Cloud SQL Auth

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.

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 --project PROJECT_ID

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

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.

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 um 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. Caso sua instância do Cloud SQL tiver apenas um 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

Criar uma conta de usuário do banco de dados para o proxy do Cloud SQL Auth

Ao se conectar à instância usando o proxy do Cloud SQL Auth, você fornece uma conta de usuário para fazer login na instância. Você pode usar qualquer conta de usuário do banco de dados. Porém, como o proxy do Cloud SQL Auth sempre se conecta a partir de um nome de host que não pode ser acessado, exceto pelo proxy do Cloud SQL Auth, é possível criar uma conta de usuário que pode ser usada apenas pelo proxy do Cloud SQL Auth. A vantagem de fazer isso é que é possível especificar essa conta sem usar uma senha nem comprometer a segurança da instância ou dos dados.

Para criar uma conta de usuário que só pode ser usada com o proxy do Cloud SQL Auth, especifique o nome do host como 'cloudsqlproxy~[IP_ADDRESS]'. Também é possível usar o caractere curinga do endereço IP, o que resultaria em 'cloudsqlproxy~%'. O nome de conta do usuário completo seria:

'[USER_NAME]'@'cloudsqlproxy~%'

ou

'[USER_NAME]'@'cloudsqlproxy~[IP_ADDRESS]'

Para ajudar na criação de um usuário, consulte Criação e gerenciamento de usuários. Para informações sobre como o Cloud SQL funciona com contas de usuário, consulte Usuários.

Executar o proxy do Cloud SQL Auth em um processo separado

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

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 do proxy do Cloud SQL Auth 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:3306:3306 \
      gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \
      -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:3306 \
      -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.

Dicas para trabalhar com o proxy do Cloud SQL Auth

Invocar o proxy do Cloud SQL Auth

Todas as invocações de proxy de exemplo iniciam o proxy do Cloud SQL Auth em segundo plano. E, então, um prompt é retornado. Reserve o terminal do Cloud Shell para o proxy do Cloud SQL Auth para evitar que a saída seja confundida com a saída de outros programas. Além disso, a saída do proxy do Cloud SQL Auth pode ajudá-lo a diagnosticar problemas de conexão. Portanto, pode ser útil capturá-la em um arquivo de registros. Se você não iniciar o proxy do Cloud SQL Auth em segundo plano, a saída irá para stdout, a menos que seja redirecionada.

Não é necessário usar /cloudsql como o diretório dos soquetes do proxy do Cloud SQL Auth. Esse nome de diretório foi escolhido para minimizar as diferenças com as strings de conexão do App Engine. Porém, se você alterar o nome do diretório, mantenha um tamanho total mínimo, visto que é incorporado a uma string mais longa com limite de tamanho imposto pelo sistema operacional. Depende do sistema, mas geralmente é entre 91 e 108 caracteres. No Linux, o tamanho geralmente é definido como 108. Use o seguinte comando para verificar:

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

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 Unix

Para conectar o proxy do Cloud SQL Auth a várias instâncias, forneça os nomes de conexão da instância com o parâmetro "-instances" em uma lista separada por vírgulas (sem espaços). O proxy do Cloud SQL Auth se conecta a cada instância quando é iniciado.

Conecte-se a cada instância usando o soquete correspondente no diretório especificado.

Exemplo:

      ./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance,myProject:us-central1:myInstance2 &
      mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance2
  

Sockets TCP

Ao se conectar usando TCP, você especificará uma porta na sua máquina para que o proxy do Cloud SQL Auth detecte 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 -instances=myProject:us-central1:myInstance=tcp:3306,myProject:us-central1:myInstance2=tcp:1234

    # Connect to "myInstance" using port 3306 on your machine:
    mysql -u myInstanceUser --host 127.0.0.1  --port 3306

    # Connect to "myInstance2" using port 1234 on your machine:
    mysql -u myInstance2User --host 127.0.0.1  --port 1234
  

Invocações do proxy do Cloud SQL Auth e strings de conexão do cliente MySQL

É possível usar invocações do proxy do Cloud SQL Auth e strings de conexão, por exemplo, em comandos para um usuário MySQL myUser, para a instância myInstance, localizada em us-central1, no projeto myProject.

Uso de descoberta automática da instância com credenciais gcloud:
    ./cloud_sql_proxy -dir=/cloudsql &
    mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance
Como usar a descoberta do projeto com credenciais gcloud:
    ./cloud_sql_proxy -dir=/cloudsql -projects=myProject &
    mysql -u myUser -S /cloudsql/myProject:us-central1:

Para uma instância do Compute Engine, com especificação explícita da instância:
    ./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance &
    mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance
Para Unix, uso de TCP:
    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:3306 &
    mysql -u myUser --host 127.0.0.1
Para Windows (no prompt da linha de comando):
    cloud_sql_proxy.exe -instances=myProject:us-central1:myInstance=tcp:3306
    mysql -u myUser --host 127.0.0.1

Para mais informações sobre opções e strings de conexão do proxy do Cloud SQL Auth, consulte a Página do proxy do Cloud SQL Auth no GitHub.

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 do Cloud Shell 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 de 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.

  • 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, $PROJECT_ID@appspot.gserviceaccount.com) 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 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 com soquetes UNIX, confirme se eles foram criados listando o diretório fornecido quando você 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.

  • É possível confirmar se o proxy de autenticação do Cloud SQL foi iniciado corretamente procurando nos registros na seção Operações > Logging > Explorador 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/3306 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 do Cloud SQL Auth é 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