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 fornece acesso seguro às instâncias de segunda geração do Cloud SQL, sem a necessidade de colocar endereços IP na lista de permissões ou configurar o SSL.

O acesso à instância do Cloud SQL usando o 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. Por exemplo, não é possível usar o proxy para se conectar a uma instância usando IP particular, a menos que o proxy esteja usando uma rede VPC que tenha sido configurada para acesso a serviços particulares.

Como o Cloud SQL Proxy funciona

O Cloud SQL Proxy funciona com um cliente local, 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 dele, 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.
  • Você precisa fornecer as credenciais de autenticação do GCP ao proxy.
  • 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 não precisa estar acessível para nenhum endereço externo, ou seja, nenhum endereço externo precisa ser colocado na lista de permissões.

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

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. Renomeie o arquivo como 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. Renomeie o arquivo como cloud_sql_proxy.exe.
Se seu sistema operacional não estiver incluído aqui, também é possível compilar o proxy a partir da 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 detectará os dados provenientes do aplicativo para serem enviados ao Cloud SQL.
  • Onde serão encontradas as credenciais que serão usadas para autenticar o aplicativo no Cloud SQL.
  • Se necessário, qual tipo de endereço IP usar.

As opções de inicialização de proxy que você fornece determinam se ele vai detectar em uma porta TCP ou em um soquete Unix. Se estiver detectando em um soquete Unix, ele criará o soquete no local escolhido. Geralmente, o diretório /cloudsql/. No caso de TCP, o proxy detecta no localhost por padrão.

Você pode instalar o proxy em qualquer lugar do ambiente local. O local dos binários do proxy não afeta o local onde ele detecta dados do aplicativo.

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 no comando de invocação de proxy
  2. Credenciais fornecidas pelo ambiente local
  3. Credenciais associadas à instância do Compute Engine
  4. Credenciais de um cliente autenticado do Cloud SDK

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

Credenciais fornecidas no comando de invocação de proxy

É possível criar um arquivo de credenciais usando o Console do Google Cloud Platform e fornecê-lo na linha de comando quando o Cloud SQL Proxy é iniciado com o parâmetro -credential_file. A conta de serviço precisa ter as permissões necessárias para a instância do Cloud SQL.

A vantagem desse método de autenticação é que você pode criar um arquivo de credenciais especificamente para o proxy. Ele está, explícita e permanentemente, vinculado ao proxy, desde que esteja 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 os usuários com a permissão resourcemanager.projects.setIamPolicy, como os proprietários do projeto, podem criar a conta do serviço. Caso seu usuário do GCP não tenha essa permissão, será necessário que outra pessoa crie a conta de serviço para você ou, então, usar 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.

Credenciais fornecidas pelo ambiente local

Esse método é idêntico ao fornecimento de um arquivo de credenciais na linha de comando, exceto que o local do arquivo é fornecido com a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

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.

Credenciais de um cliente autenticado do Cloud SDK

Se você tiver instalado o Cloud SDK e o usado para se autenticar no GCP, o Cloud SQL Proxy poderá usar as mesmas credenciais. Esse método é especialmente útil para colocar um ambiente de desenvolvimento em funcionamento rapidamente. Para um ambiente de produção, use um dos outros métodos de autenticação.

Confirme quais são suas credenciais atuais do SDK do Cloud usando o comando gcloud auth list.

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 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 esse papel são os seguintes:

  • 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 o proxy a quais instâncias você quer se conectar, porque ele se conecta com base nas solicitações de conexão.

Suas 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 de instâncias 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. Compatível 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 somente 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 particular

O proxy estabelece uma conexão com sua instância do Cloud SQL usando o IP. Por padrão, o proxy tenta se conectar usando um endereço IPv4 público. Se o proxy estiver usando a mesma rede VPC da instância do Cloud SQL e a instância tiver um endereço IP particular, o proxy poderá se conectar usando IP particular.

Se sua instância do Cloud SQL tiver apenas IP particular, o proxy 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 use o endereço IP particular, forneça a seguinte opção ao iniciar o proxy:

--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 esse 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 ajudá-lo a diagnosticar problemas de conexão, portanto, pode ser útil capturá-la em um arquivo de registros.

Você não precisa usar /cloudsql como o diretório dos soquetes de 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

Você pode 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 e 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.

Por 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, você especificará a porta em sua 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 você pode especificar outra porta para ela.

Por 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. Você pode ver qual é a versão atual na página de versões do Cloud SQL Proxy no GitHub. Futuras versões de proxy também serão observadas no fórum de anúncios do Cloud SQL nos Grupos do Google.

Uso da API

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

O maior uso de API ocorre quando você inicia o proxy. Isso se verifica especialmente quando você usa a descoberta automática de instâncias ou o parâmetro -projects. Enquanto o proxy está em execução, ele emite duas chamadas à API por hora por instância conectada.

Sobre a criação de 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. Você pode 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 você pode 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 do proxy, especifique o nome do host como 'cloudsqlproxy~[IP_ADDRESS]'. Você também pode 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 sinalizadores 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 saber mais sobre as opções de proxy, consulte as seguintes informações:

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

Os exemplos a seguir mostram invocações de proxy e strings de conexão para um usuário myUser do MySQL, da 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", ou seja, "sistema de arquivos no espaço do usuário". 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. Você pode verificar se esse programa está instalado procurando o arquivo, /dev/fuse/. Caso fusermount não esteja no sistema, instale-o usando o gerenciador de pacotes ou faça a compilação a partir do código-fonte.

No macOS:

Instale o FUSE para macOS.

Como criar uma conta de serviço

Para criar uma conta de serviço:

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

    Acessar a página "Contas de serviço"

  2. Se necessário, 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

    Também é possível usar o papel primitivo de editor ao selecionar Projeto > Editor. No entanto, ele inclui permissões em todo o Google Cloud Platform.

    Se esses papéis não estiverem sendo exibidos, é provável que seu usuário do Google Cloud Platform não tenha a permissão resourcemanager.projects.setIamPolicy. Para verificar suas permissões, acesse a página "IAM" no Console do Google Cloud Platform e procure seu código de usuário.

  6. Altere o código da conta de serviço com um valor exclusivo que você reconhecerá para que possa facilmente encontrar essa conta de serviço mais tarde, se necessário.
  7. Clique em Fornecer uma nova chave privada.
  8. O tipo de chave padrão é JSON, que é o valor correto a ser usado.
  9. Clique em Criar.

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

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

Quando você está usando o Cloud SQL Proxy em um ambiente de produção, pode seguir 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 feito 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, você deve 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

Se você precisar reduzir o tamanho do registro do proxy, poderá definir -verbose=false ao 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 ajudá-lo 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ê está recebendo um erro 403 notAuthorized e está usando uma conta de serviço para autenticar o proxy, certifique-se de que a conta de serviço tenha as permissões corretas.

    Você pode verificar a conta de serviço pesquisando pelo ID dela na página "IAM". Ela precisa ter a permissão cloudsql.instances.connect. Todos os papéis predefinidos do Cloud SQL têm essa permissão, exceto Cloud SQL Viewer. Além disso, os papéis legados Editor e Owner do projeto têm a permissão necessária.

  • Verifique se a API Cloud SQL está ativada.

    Se não estiver, você verá uma saída como Error 403: Access Not Configured nos registros 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.

Próximas etapas

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Cloud SQL para MySQL