Sobre o Cloud SQL Proxy

Esta página fornece uma introdução básica ao Cloud SQL Proxy e descreve as opções de proxy.

Para instruções passo a passo sobre como usar o Cloud SQL Proxy, clique no link de acordo com seu ambiente:

Não é preciso usar o proxy ou configurar o SSL para se conectar ao Cloud SQL a partir do ambiente padrão ou flexível do App Engine.

O que o proxy fornece

O Cloud SQL Proxy dá acesso seguro às instâncias da segunda geração do Cloud SQL sem a necessidade de adicionar redes autorizadas ou configurar o SSL.

O acesso à instância do Cloud SQL pelo Cloud SQL Proxy oferece estas vantagens:

  • Conexões protegidas: o proxy criptografa automaticamente o tráfego de entrada e saída do banco de dados usando TLS 1.2 com uma criptografia AES de 128 bits. Os certificados SSL são usados para verificar as identidades do cliente e do servidor.
  • Gerenciamento de conexões mais fácil: o proxy processa a autenticação com o Cloud SQL, eliminando a necessidade de fornecer endereços IP estáticos.

O proxy não fornece um novo caminho de conectividade. Ele depende da conectividade IP atual. Para se conectar a uma instância do Cloud SQL usando IP privado, o proxy precisa estar em um recurso com acesso à mesma rede VPC que a instância.

Como o Cloud SQL Proxy funciona

O Cloud SQL Proxy funciona com um cliente, chamado proxy, executado no ambiente local. O aplicativo se comunica com o proxy com o protocolo de banco de dados padrão usado por seu banco de dados. O proxy usa um túnel seguro para se comunicar com o processo complementar em execução no servidor.

O diagrama a seguir mostra como o proxy se conecta ao Cloud SQL:

Diagrama do proxy de conexão do software cliente com a instância do SQL

Requisitos para usar o Cloud SQL Proxy

Para usar o proxy, você precisa atender aos seguintes requisitos:

  • A API Cloud SQL precisa estar ativada.
  • É preciso fornecer ao proxy credenciais de autenticação do Google Cloud.
  • Você precisa fornecer ao proxy uma conta de usuário e uma senha válidas para o banco de dados.
  • A instância precisa ter um endereço IPv4 público ou ser configurada para usar IP particular.

    O endereço IP público não precisa estar acessível para nenhum endereço externo (não é necessário adicioná-lo como um endereço de rede autorizado).

Como instalar o Cloud SQL Proxy

Linux de 64 bits

  1. Faça o download do proxy:
        wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
        
  2. Torne o proxy executável:
        chmod +x cloud_sql_proxy
        

Linux de 32 bits

  1. Faça o download do proxy:
        wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
        
  2. Torne o proxy executável:
        chmod +x cloud_sql_proxy
        

macOS de 64 bits

  1. Faça o download do proxy:
        curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
        
  2. Torne o proxy executável:
        chmod +x cloud_sql_proxy
        

macOS de 32 bits

  1. Faça o download do proxy:
        curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
        
  2. Torne o proxy executável:
        chmod +x cloud_sql_proxy
        

Windows de 64 bits

Para fazer o download do proxy, clique com o botão direito do mouse em https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe e selecione Salvar link como. Renomeie o arquivo como cloud_sql_proxy.exe.

Windows de 32 bits

Para fazer o download do proxy, clique com o botão direito do mouse em https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe e selecione Salvar link como. Renomeie o arquivo como cloud_sql_proxy.exe.
Caso seu sistema operacional não esteja incluído aqui, compile o proxy usando a fonte (em inglês).

Opções de inicialização de proxy

Ao iniciar o proxy, você fornece as seguintes informações:

  • Com quais instâncias do Cloud SQL deverá estabelecer conexões
  • Onde ele detecta os dados provenientes do aplicativo para enviá-los ao Cloud SQL
  • Onde estão as credenciais usadas para autenticar o aplicativo no Cloud SQL
  • Se necessário, qual tipo de endereço IP usar

As opções de inicialização determinam se o proxy faz a detecção em uma porta TCP ou em um soquete Unix. Se for em um soquete Unix, ele criará o soquete no local escolhido. Geralmente, o diretório /cloudsql/. Para o TCP, o proxy detecta localhost por padrão.

Você pode instalar o proxy em qualquer lugar do ambiente local. O local dos binários do proxy não interfere na detecção dos dados do aplicativo.

Como usar uma conta de serviço para autenticação

O proxy requer autenticação. A vantagem de usar uma conta de serviço para esse fim é que você pode criar um arquivo de credencial especificamente para o proxy. Esse arquivo fica vinculado de forma explícita e permanente enquanto o proxy estiver em execução. Por esse motivo, esse é o método recomendado para instâncias de produção que não estejam em execução em uma instância do Compute Engine.

O arquivo de credenciais poderá ser duplicado em uma imagem do sistema, se for necessário invocar o Cloud SQL Proxy de várias máquinas.

Para usar esse método, o arquivo de credenciais precisa ser criado e gerenciado. Somente usuários com a permissão resourcemanager.projects.setIamPolicy, como proprietários do projeto, podem criar a conta de serviço. Se o usuário do Google Cloud não tiver essa permissão, é necessário que outra pessoa crie a conta de serviço para você ou use outro método para autenticar o proxy.

Consulte Como criar uma conta de serviço se precisar de ajuda para criar um arquivo de credenciais.

Opções para autenticar o Cloud SQL Proxy

O Cloud SQL Proxy fornece várias alternativas para autenticação, dependendo do seu ambiente. O proxy verifica cada um dos itens a seguir, nesta ordem, usando o primeiro que encontra 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 Cloud SQL Proxy. A conta de serviço precisa ter as permissões necessárias para a instância do Cloud SQL.
  2. Credenciais fornecidas por um token de acesso.

    Crie um token de acesso e forneça-o na linha de comando com a sinalização -token ao iniciar o Cloud SQL Proxy.
  3. Credenciais fornecidas por uma variável de ambiente.

    É possível definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para o caminho do arquivo de chave json criado para uma conta de serviço.
  4. Credenciais de um cliente autenticado do Cloud SDK.

    Se você instalou o Cloud SDK e o usou para autenticar no Google Cloud, o Cloud SQL Proxy pode usar as mesmas credenciais. Esse método é especialmente útil para colocar um ambiente de desenvolvimento em funcionamento rapidamente. Para um ambiente de produção, você precisa usar um dos outros métodos para autenticar.
  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 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 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 primeira terá as permissões necessárias para autenticar o proxy. 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.

Permissões necessárias para contas de serviço

Caso queira usar uma conta de serviço para fornecer as credenciais ao proxy, você precisará criá-la com permissões suficientes. Se estiver usando papéis de Identity Access and Management (IAM) mais refinados para gerenciar permissões do Cloud SQL, atribua à conta de serviço um papel que inclua a permissão cloudsql.instances.connect. Os papéis predefinidos do Cloud SQL que incluem essa permissão são:

  • Cliente do Cloud SQL
  • Editor do Cloud SQL
  • Administrador do Cloud SQL

Se você estiver usando os papéis legados (leitor, editor e proprietário), a conta de serviço precisará ter pelo menos o papel de editor.

Opções para especificar instâncias do Cloud SQL

Há várias maneiras de informar ao proxy a quais instâncias você quer se conectar. Algumas são explícitas e outras, implícitas. Em algumas configurações, não é necessário informar ao proxy a quais instâncias você quer se conectar, porque ele se conecta com base nas solicitações de conexão.

As opções de especificação de instância dependem do sistema operacional e do ambiente:

Opção Benefícios Restrições e requisitos Linux/macOS
(soquetes Unix)
Java Windows Notas
FUSE
(Sistema de arquivos no espaço do usuário)
Criação dinâmica do soquete com base em solicitações de conexão, sem reinicializações de proxy necessárias à medida que as instâncias são alteradas. O FUSE deve ser instalado. Compatível Não Não Use a sinalização -fuse.
Descoberta automática da instância Não é necessário especificar instâncias, e os soquetes são criados para todas as instâncias no projeto padrão. O uso da API Proxy aumenta. É preciso ter o Cloud SDK instalado e autenticado com um projeto padrão definido. É necessário reiniciar o proxy para adicionar a nova instância. Suporte Não Não Não recomendado para instâncias de produção.
Descoberta do projeto Não é necessário especificar instâncias, e os soquetes são criados para todas as instâncias em projetos especificados. O uso da API Proxy aumenta. É preciso ter o Cloud SDK instalado e autenticado. É necessário reiniciar o proxy para adicionar a nova instância. Compatível Não Não Use o parâmetro -projects. Não recomendado para instâncias de produção.
Instâncias especificadas na invocação do proxy Lista de instâncias conhecida e estática. É necessário reiniciar o proxy para adicionar a nova instância. Compatível Compatível com soquetes TCP Compatível com soquetes TCP Use o parâmetro -instances. Para várias instâncias, use uma lista separada por vírgulas, sem espaços. Saiba mais.
Instâncias especificadas com metadados do Compute Engine A lista de instâncias pode ser atualizada ao alterar o valor dos metadados, sem reiniciar o proxy. Disponível no Compute Engine. Compatível Compatível com soquetes TCP Compatível com soquetes TCP Use a sinalização -instances_metadata. Saiba mais.

Consulte amostras de invocações e strings de conexão.

Como usar o proxy com IP privado

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

O proxy estabelece uma conexão com sua instância do Cloud SQL usando IP. Por padrão, o proxy tenta se conectar usando um endereço IPv4 público. Se sua instância do Cloud SQL tiver apenas IP privado, o proxy usará o endereço IP privado para se conectar.

Se a instância tiver IP público e privado configurados e você quiser que o proxy use o endereço IP privado, forneça a seguinte opção ao iniciá-lo:

-ip_address_types=PRIVATE
    

Dicas para trabalhar com o Cloud SQL Proxy

Invocação do Cloud SQL Proxy

Todas as invocações de proxy de exemplo iniciam o proxy em segundo plano. Assim, um prompt é retornado. É preferível reservar este terminal para o proxy, a fim de evitar que a saída seja confundida com a saída de outros programas. Além disso, a saída do proxy pode ajudar a diagnosticar problemas de conexão, portanto, é uma boa ideia capturá-la em um arquivo de registros. Se você não iniciar o proxy em segundo plano, a saída será stdout, a menos que seja redirecionada.

Não é necessário usar /cloudsql como o diretório dos soquetes do proxy. (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.

Como usar o proxy para se conectar a várias instâncias

É possível usar um cliente de proxy local 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 Unix

Para conectar o proxy 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 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
    

TCP

Ao se conectar usando TCP, especifique a porta da máquina que será usada para se conectar à instância. É necessário que cada instância tenha a própria porta. Por padrão, a ferramenta mysql usa 3306, mas é possível especificar outra porta para ela.

Exemplo:

./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:3306,myProject:us-central1:myInstance2=tcp:3307 &
    mysql -u myUser --host 127.0.0.1  --port 3307
    

Como manter o Cloud SQL Proxy atualizado

De vez em quando, o Google libera novas versões do proxy. É possível ver qual é a versão atual na página de versões do Cloud SQL Proxy no GitHub. As futuras versões de proxy também serão divulgadas no fórum de anúncios do Cloud SQL nos Grupos dos Google (em inglês).

Uso da API

O Cloud SQL Proxy emite solicitações à API do Cloud SQL. Elas são deduzidas da cota de API do projeto.

O uso mais alto da API ocorre ao iniciar o proxy. Isso se aplica especialmente ao usar a descoberta automática de instância ou o parâmetro -projects. Enquanto o proxy está em execução, ele emite duas chamadas à API por hora por instância conectada.

Como criar uma conta de usuário especial para o proxy

Ao se conectar à instância usando o proxy, forneça a conta de usuário usada para fazer login na instância. É possível usar qualquer conta de usuário do banco de dados. Porém, como o proxy sempre se conecta a partir de um nome de host que não pode ser acessado, exceto pelo próprio proxy, convém criar uma conta de usuário que pode ser usada apenas pelo proxy. 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 para conexões de proxy, 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. Para informações sobre contas de usuário do MySQL, consulte Proteção das contas iniciais do MySQL na documentação do MySQL.

Parâmetros e sinalizações do Cloud SQL Proxy

O Cloud SQL Proxy aceita diversos parâmetros e sinalizações quando iniciado. Essas opções determinam onde e como o Cloud SQL Proxy cria os soquetes usados na comunicação com o Cloud SQL, e como ele se autentica.

Para ajuda com opções de proxy, consulte as seguintes informações:

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

É possível usar invocações de proxy e strings de conexão, por exemplo, em comandos para um usuário do 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:myInstance
    
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 Cloud SQL Proxy, consulte a página do Cloud SQL Proxy no GitHub.

Como o FUSE é usado com o Cloud SQL Proxy

FUSE significa "Filesystem in User Space" (Sistema de arquivos no espaço do usuário, em português). Dependendo de como é invocado, o Cloud SQL Proxy pode usar o FUSE para criar os soquetes que usa na conexão com o Cloud SQL.

Durante a conexão pelo Compute Engine ou por ambientes de desenvolvimento locais, o Cloud SQL Proxy usa o FUSE para acessar instâncias do Cloud SQL da seguinte maneira:

  • O diretório “/cloudsql” é montado como um sistema de arquivos no espaço do usuário, ou FUSE, pelo Cloud SQL Proxy.

  • Um processo (por exemplo, mysql) tenta pesquisar um arquivo chamado $INSTANCE.

  • O proxy intercepta a solicitação e retorna que “/cloudsql/$INSTANCE” é um link simbólico apontando para um soquete Unix localizado em outro lugar do sistema de arquivos.

  • O processo (por exemplo, mysql) segue o link, abre o soquete Unix de destino e se conecta.

Instalação do FUSE

No Linux:

O FUSE exige o programa fusermount e um módulo do kernel para funcionar. É possível verificar se este programa está instalado procurando o arquivo, /dev/fuse/. Se fusermount não estiver em seu sistema, é possível instalá-lo usando o gerenciador de pacotes ou compilá-lo a partir da origem.

No macOS:

Instale o FUSE para macOS.

Como criar uma conta de serviço e gerar um arquivo de chave

Para criar uma conta de serviço:

Caso queira usar uma conta de serviço para fornecer as credenciais ao proxy, você precisará criá-la com permissões suficientes. Se você estiver usando os papéis mais detalhados de gerenciamento de identidade e acesso (IAM) para gerenciar suas permissões do Cloud SQL, atribua à conta de serviço um papel que inclua a permissão cloudsql.instances.connect. Os papéis predefinidos do Cloud SQL que incluem essa permissão são os seguintes:

  • Cliente do Cloud SQL
  • Editor do Cloud SQL
  • Administrador do Cloud SQL

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.

  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. Em Papel, selecione um dos seguintes papéis:
    • Cloud SQL > Cliente do Cloud SQL
    • Cloud SQL > Editor do Cloud SQL
    • Cloud SQL > Administrador do Cloud SQL

    Como alternativa, é possível usar o papel primitivo de editor selecionando Projeto > Editor, mas esse papel inclui permissões no Google Cloud.

    Caso não veja esses papéis, talvez o usuário do Google Cloud não tenha a permissão resourcemanager.projects.setIamPolicy. Para verificar suas permissões, acesse a página do IAM no Console do Google Cloud e pesquise seu ID de usuário.

  6. Altere o ID da conta de serviço para um valor exclusivo e facilmente reconhecível.
  7. Clique em Fornecer uma nova chave privada e confirme se o tipo de chave é JSON.
  8. Clique em Criar.

    O arquivo da chave privada é transferido para sua máquina. É possível movê-lo para outro local. Mantenha-o seguro.

Para mais informações sobre contas de serviço, consulte a documentação de autenticação.

Como usar o Cloud SQL Proxy em um ambiente de produção

Ao usar o Cloud SQL Proxy em um ambiente de produção, siga algumas etapas para garantir que o proxy forneça a disponibilidade necessária para o aplicativo.

Certificar-se de que o Cloud SQL Proxy seja executado como um serviço persistente

Se o processo do proxy for encerrado, todas as conexões existentes por meio dele serão descartadas e o aplicativo não poderá criar mais nenhuma conexão com a instância do Cloud SQL usando o proxy. Para evitar esse cenário, execute o proxy como um serviço persistente, de modo que, se o proxy sair por qualquer motivo, ele será reiniciado automaticamente. Isso pode ser realizado usando um serviço como systemd, upstart ou supervisor. No Windows, execute o proxy como um serviço desse sistema operacional. Em geral, o proxy deve ter os mesmos requisitos de tempo de atividade do processo do aplicativo.

Quantas cópias do Cloud SQL Proxy são necessárias ao aplicativo

Não é necessário criar um processo de proxy para cada processo de aplicativo, já que muitos processos de aplicativo podem compartilhar um único processo de proxy. Em geral, é necessário executar um processo do cliente proxy por estação de trabalho ou máquina virtual.

Se você estiver usando escalonamento automático para máquinas virtuais, verifique se o proxy está incluído na configuração da máquina virtual. Assim, sempre que uma nova máquina virtual for iniciada, ela terá o próprio processo de proxy.

Depende de você gerenciar o número de conexões necessárias ao aplicativo, seja por limitação ou uso de pool de conexões. O proxy não coloca nenhuma limitação em novas taxas de conexão ou contagem de conexão persistente.

Como reduzir a saída do Cloud SQL Proxy

Caso seja necessário reduzir o tamanho do registro do proxy, defina -verbose=false quando iniciar o proxy. Tenha em mente, no entanto, que isso reduz a eficácia da saída do proxy para diagnosticar problemas de conexão.

Como o failover afeta o Cloud SQL Proxy

Se você estiver executando o proxy em uma instância configurada para alta disponibilidade e ocorrer um failover, as conexões por meio do proxy serão afetadas da mesma forma que as conexões por IP: todas as conexões existentes serão perdidas e o aplicativo precisará estabelecer novas conexões. Porém, nenhuma intervenção manual é necessária: o aplicativo pode continuar usando as mesmas strings de conexão de antes.

Solução de problemas de conexões do Cloud SQL Proxy

Se você tiver problemas para se conectar à instância do Cloud SQL usando o Cloud SQL Proxy, tente estas opções para encontrar o motivo.

  • Verifique a saída do proxy.

    Muitas vezes, a saída do proxy pode ajudar a determinar a origem do problema e como solucioná-lo. Redirecione a saída para um arquivo ou observe o terminal onde você iniciou o proxy.

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

    É possível verificar a conta de serviço pesquisando pelo ID na página IAM. Ela deve ter a permissão cloudsql.instances.connect. Todas os papéis predefinidos do Cloud SQL têm essa permissão, exceto Cloud SQL Viewer. Além disso, os papéis de projeto legados de Editor e Owner têm a permissão necessária.

  • Ative a API Cloud SQL Admin.

    Se não estiver ativada, você verá a saída como Error 403: Access Not Configured nos logs do proxy.

  • 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 tentando se conectar de um aplicativo, primeiro use um cliente administrativo para eliminar qualquer problema com o aplicativo.

  • Se você estiver se conectando usando soquetes UNIX, liste o diretório fornecido quando iniciou o proxy para confirmar se os soquetes foram criados.

  • 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 máquina de destino.

A seguir