Sobre o proxy do Cloud SQL Auth

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

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

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

Faça um teste

Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho do Cloud SWL em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Faça uma avaliação gratuita do Cloud SQL

O que o proxy do Cloud SQL Auth fornece

O proxy do Cloud SQL Auth fornece acesso seguro às instâncias sem a necessidade de redes autorizadas ou de configuração de SSL.

O acesso à instância do Cloud SQL usando o proxy do Cloud SQL Auth oferece as seguintes vantagens:

  • Conexões protegidas: o proxy do Cloud SQL Auth criptografa automaticamente o tráfego de entrada e saída do banco de dados usando TLS 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 Auth, eliminando a necessidade de fornecer endereços IP estáticos.

O proxy do Cloud SQL Auth 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 o IP particular, o proxy precisa estar em um recurso com acesso à mesma rede VPC que a instância.

Como o proxy do Cloud SQL Auth funciona

O proxy do Cloud SQL Auth funciona com um cliente local em execução no ambiente local. O aplicativo se comunica com o proxy do Cloud SQL Auth com o protocolo de banco de dados padrão usado por seu banco de dados. O proxy do Cloud SQL Auth usa um túnel seguro para se comunicar com o processo complementar em execução no servidor. Cada conexão estabelecida pelo proxy do Cloud SQL Auth cria uma conexão com a instância do Cloud SQL. O proxy do Cloud SQL Auth não fornece pooling de conexão, mas pode ser pareado com outro pooling de conexão para aumentar a eficiência.

O proxy do Cloud SQL Auth pode detectar em qualquer porta, mas apenas cria conexões de saída para a instância do Cloud SQL na porta 3307. Se a máquina cliente tiver uma política de firewall de saída, verifique se ela permite conexões de saída com a porta 3307 no IP da instância do Cloud SQL.

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

Diagrama do proxy do Cloud SQL Auth conectado pelo software cliente à instância do SQL

Requisitos para usar o proxy do Cloud SQL Auth

Para usar o proxy do Cloud SQL Auth, é preciso atender aos seguintes requisitos:

  • A API Cloud SQL precisa estar ativada.
  • É preciso fornecer ao proxy do Cloud SQL Auth as credenciais de autenticação do Google Cloud.
  • Você precisa fornecer ao proxy do Cloud SQL Auth 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 (ele não precisa ser adicionado como um endereço de rede autorizado).

Faça o download e instale o proxy de autenticação do Cloud SQL

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 da origem.

Opções de inicialização do proxy do Cloud SQL Auth

Ao iniciar o proxy do Cloud SQL Auth, você fornece as seguintes informações:

  • Com que instâncias do Cloud SQL as conexões serão feitas.
  • Onde o proxy 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 do proxy do Cloud SQL Auth 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/. Para conexões TCP, o proxy do Cloud SQL Auth detecta em localhost por padrão.

Execute o executável cloud_sql_proxy com o argumento --help para ver a lista completa de opções de inicialização.

Instale o proxy do Cloud SQL Auth em qualquer lugar no seu ambiente local. O local dos binários do proxy do Cloud SQL Auth não afeta o local onde eles detectam dados do aplicativo.

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

O proxy do Cloud SQL Auth requer autenticação. A vantagem de usar uma conta de serviço para esse fim é que é possível criar um arquivo de credencial especificamente para o proxy do Cloud SQL Auth. Esse arquivo fica vinculado de forma explícita e permanente ao proxy do Cloud SQL Auth, desde que esteja em execução. Por esse motivo, o uso de uma conta de serviço é o método recomendado para instâncias de produção não executadas 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 proxy do Cloud SQL Auth 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. Caso seu usuário do Google Cloud não tenha essa permissão, será necessário que outra pessoa crie a conta de serviço para você ou use outro método para autenticar o proxy do Cloud SQL Auth.

Saiba como criar uma conta de serviço

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

Ao usar uma conta de serviço para fornecer as credenciais para o proxy, crie-a 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 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 do Cloud SQL Auth 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 com antecedência ao proxy do Cloud SQL Auth a quais instâncias você quer se conectar, porque o proxy do Cloud SQL Auth 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 Observações
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 Cloud SQL Auth Proxy aumenta. É preciso ter o Cloud SDK instalado e autenticado com um projeto padrão definido. É necessário reiniciar o proxy do Cloud SQL Auth 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 Cloud SQL Auth Proxy aumenta. É preciso ter o Cloud SDK instalado e autenticado. É necessário reiniciar o proxy do Cloud SQL Auth para adicionar uma 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 do Cloud SQL Auth Lista de instâncias conhecida e estática. É necessário reiniciar o proxy do Cloud SQL Auth para adicionar uma 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 do Cloud SQL Auth. 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 manter o proxy do Cloud SQL Auth atualizado

Em certos casos, o Google lança novas versões do proxy do Cloud SQL Auth. É possível ver qual é a versão atual na página de versões do proxy do Cloud SQL Auth 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.

Uso da API

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

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

Sobre a criação de uma conta de usuário especial para o proxy do Cloud SQL Auth

Ao se conectar à instância usando o proxy do Cloud SQL Auth, 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 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 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 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. 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 proxy do Cloud SQL Auth

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

Para ajuda com as opções do proxy do Cloud SQL Auth, consulte as seguintes informações:

Como o FUSE é usado com o proxy do Cloud SQL Auth

FUSE significa "Filesystem in User Space" (Sistema de arquivos no espaço do usuário, em português). Dependendo de como é invocado, o proxy do Cloud SQL Auth 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 proxy do Cloud SQL Auth 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 proxy do Cloud SQL Auth.

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

  • O proxy do Cloud SQL Auth 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 usar o proxy do Cloud SQL Auth em um ambiente de produção

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

Certifique-se de que o proxy do Cloud SQL Auth seja executado como um serviço persistente

Se o processo do proxy do Cloud SQL Auth for interrompido, 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 do Cloud SQL Auth. Para evitar esse cenário, execute o proxy do Cloud SQL Auth como um serviço persistente, de modo que, se o proxy do Cloud SQL Auth sair por qualquer motivo, ele será reiniciado automaticamente. Isso pode ser realizado usando um serviço como systemd, upstart ou supervisor. Para o sistema operacional Windows, execute o proxy do Cloud SQL Auth como um serviço do Windows. Em geral, verifique se o proxy do Cloud SQL Auth tem os mesmos requisitos de tempo de atividade do processo do aplicativo.

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

Não é necessário criar um processo de proxy para cada processo de aplicativo, já que muitos processos desse tipo podem compartilhar um único processo de proxy. Execute um processo do cliente do proxy do Cloud SQL Auth por estação de trabalho ou máquina virtual.

Se você estiver usando o escalonamento automático para máquinas virtuais, verifique se o proxy do Cloud SQL Auth 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 do Cloud SQL Auth.

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 do Cloud SQL Auth não coloca nenhuma limitação em novas taxas de conexão ou contagem de conexão persistente.

Como reduzir a saída do proxy do Cloud SQL Auth

Se você precisar reduzir o tamanho do registro do proxy do Cloud SQL Auth, poderá definir -verbose=false ao iniciar o proxy do Cloud SQL Auth. No entanto, lembre-se de que isso reduz a eficácia da saída do proxy no diagnóstico de problemas de conexão.

Como o failover afeta o proxy do Cloud SQL Auth

Se você estiver executando o proxy do Cloud SQL Auth em uma instância configurada para alta disponibilidade e ocorrer um failover, as conexões que usam o proxy do Cloud SQL Auth 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.

Como manter a imagem do Docker do proxy do Cloud SQL Auth atualizada

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.

A seguir