Sobre o proxy de autenticação do Cloud SQL

Esta página resume o proxy de autenticação do Cloud SQL e descreve como usá-lo para estabelecer conexões autorizadas, criptografadas e seguras com as instâncias.

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

Não é preciso usar o proxy de autenticação do Cloud SQL ou configurar o SSL para se conectar ao Cloud SQL por meio 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

Benefícios do proxy de autenticação do Cloud SQL

O proxy de autenticação do Cloud SQL é um conector do Cloud SQL que fornece acesso seguro às suas instâncias sem a necessidade de redes autorizadas ou configuração do SSL.

O proxy de autenticação do Cloud SQL e outros conectores do Cloud SQL têm as seguintes vantagens:

  • Conexões protegidas: o proxy de autenticação do Cloud SQL criptografa automaticamente o tráfego de entrada e saída do banco de dados usando TLS 1.3 com uma criptografia AES de 256 bits. Eles são usados para verificar as identidades do cliente e do servidor. Além disso, eles são independentes dos protocolos de banco de dados. Não será necessário gerenciar certificados SSL.
  • Autorização de conexão mais fácil: o proxy de autenticação do Cloud SQL usa permissões do IAM para controlar quem e o que pode se conectar às instâncias do Cloud SQL. Assim, o proxy de autenticação do Cloud SQL processa a autenticação com o Cloud SQL, eliminando a necessidade de fornecer endereços IP estáticos.
  • Autenticação do banco de dados do IAM Opcionalmente, o proxy de autenticação do Cloud SQL é compatível com uma atualização automática de tokens de acesso do OAuth 2.0. Para informações sobre essa funcionalidade, consulte Autenticação de banco de dados do IAM do Cloud SQL.

O proxy de autenticação do Cloud SQL 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 de autenticação do Cloud SQL precisa estar em um recurso com acesso à mesma rede VPC que a instância.

Como o proxy de autenticação do Cloud SQL funciona

O proxy de autenticação do Cloud SQL funciona com um cliente local em execução no ambiente local. O aplicativo se comunica com o proxy de autenticação do Cloud SQL com o protocolo de banco de dados padrão usado por seu banco de dados.

O proxy de autenticação do Cloud SQL usa um túnel seguro para se comunicar com o processo complementar em execução no servidor. Cada conexão estabelecida pelo proxy de autenticação do Cloud SQL cria uma conexão com a instância do Cloud SQL.

Quando um aplicativo se conecta ao proxy de autenticação do Cloud SQL, ele verifica se uma conexão entre ele e a instância de destino do Cloud SQL está disponível. Se não houver uma conexão, ela chamará as APIs Cloud SQL Admin para receber um certificado SSL temporário e usá-lo para se conectar ao Cloud SQL. Os certificados SSL temporários expiram em aproximadamente uma hora. O proxy de autenticação do Cloud SQL atualiza esses certificados antes da expiração deles.

Embora o proxy de autenticação do Cloud SQL possa fazer detecções em qualquer porta, ele cria conexões de entrada ou de saída com a instância do Cloud SQL somente na porta 3307. Como o proxy de autenticação do Cloud SQL chama APIs por meio do nome de domínio sqladmin.googleapis.com, que não tem um endereço IP fixo, todas as conexões TCP de saída na porta 443 precisam ser permitidas. 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 proxy de autenticação do Cloud SQL não fornece pooling de conexão, mas pode ser pareado com outro pooling de conexão para aumentar a eficiência.

O diagrama a seguir mostra como o proxy de autenticação do Cloud SQL se conecta ao Cloud SQL:

Diagrama do proxy de autenticação do Cloud SQL conectado pelo software cliente à instância do SQL

Requisitos para usar o proxy de autenticação do Cloud SQL

Para usar o proxy de autenticação do Cloud SQL, é preciso atender aos seguintes requisitos:

  • A API Cloud SQL precisa estar ativada.
  • É preciso fornecer ao proxy de autenticação do Cloud SQL Auth a credenciais de autenticação do Google Cloud.
  • Você precisa fornecer ao proxy de autenticação do Cloud SQL 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).

Fazer o download e instalar o proxy de autenticação do Cloud SQL

Linux de 64 bits

  1. Faça o download do proxy de autenticação do Cloud SQL: 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.linux.amd64
  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 de autenticação do Cloud SQL: 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.linux.386
  2. Se o comando curl não for encontrado, execute sudo apt install curl 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 de autenticação do Cloud SQL: 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.darwin.amd64
  2. Torne o proxy do Cloud SQL Auth executável: 
    chmod +x cloud-sql-proxy

Mac M1

  1. Faça o download do proxy do Cloud SQL Auth: 
      curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.darwin.arm64
  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://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.x64.exe e selecione Salvar link como para baixar o proxy de autenticação do Cloud SQL. Renomeie o arquivo para cloud-sql-proxy.exe.

Windows de 32 bits

Clique com o botão direito do mouse em https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.2/cloud-sql-proxy.x86.exe e selecione Salvar link como para baixar o proxy de autenticação do Cloud SQL. Renomeie o arquivo para cloud-sql-proxy.exe.

Imagem Docker do proxy do Cloud SQL Auth

O proxy do Cloud SQL Auth tem imagens de contêiner diferentes, como distroless, alpine e buster. A imagem de contêiner padrão do proxy do Cloud SQL Auth usa distroless, que não contém shell. Se você precisar de um shell ou de ferramentas relacionadas, faça o download de uma imagem baseada em alpine ou buster. Para mais informações, consulte Imagens de contêiner do proxy do Cloud SQL Auth.

Você pode extrair a imagem mais recente para sua máquina local usando o Docker usando o seguinte comando:

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2

Outros SOs

Para outros sistemas operacionais não incluídos aqui, compile o proxy de autenticação do Cloud SQL com base no código-fonte.

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

Ao iniciar o proxy de autenticação do Cloud SQL, 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 de autenticação do Cloud SQL que você fornece determinam se ele fará detecções 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 TCP, o proxy de autenticação do Cloud SQL faz detecções 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 de autenticação do Cloud SQL em qualquer lugar no ambiente local. O local dos binários do proxy de autenticação do Cloud SQL não afeta o local em que ele detecta dados do aplicativo.

Para mais informações sobre como iniciar o proxy de autenticação do Cloud SQL, consulte Iniciar o proxy de autenticação do Cloud SQL.

Usar uma conta de serviço para autenticação

O proxy de autenticação do Cloud SQL requer autenticação como uma identidade do IAM do Cloud SQL para autorizar as conexões com uma instância do Cloud SQL.

A vantagem de usar uma conta de serviço para esse fim é que é possível criar um arquivo de credencial especificamente para o proxy de autenticação do Cloud SQL. Esse arquivo fica vinculado de maneira explícita e permanente ao proxy de autenticação do Cloud SQL, 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 de autenticação do Cloud SQL 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 que você use outro método para autenticar o proxy de autenticação do Cloud SQL.

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 do proxy de autenticação do Cloud SQL, 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 de autenticação do Cloud SQL 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 de autenticação do Cloud SQL 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 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 do proxy de autenticação do Cloud SQL aumenta. A CLI gcloud deve estar instalada e autenticada, com um projeto padrão definido. É necessário reiniciar o proxy de autenticação do Cloud SQL para adicionar a nova instância. Compatível Não Não Não recomendado para instâncias de produção.
Instâncias especificadas na invocação do proxy de autenticação do Cloud SQL Lista de instâncias conhecida e estática. É necessário reiniciar o proxy de autenticação do Cloud SQL para adicionar uma nova instância. Compatível Compatível com soquetes TCP Compatível com soquetes TCP Para várias instâncias, use uma lista separada por vírgulas, sem espaços. Saiba mais.
Consulte amostras de invocações e strings de conexão.

Manter o proxy de autenticação do Cloud SQL atualizado

Ocasionalmente, o Google lança novas versões do proxy de autenticação do Cloud SQL. É possível ver qual é a versão atual na página de versões do proxy de autenticação do Cloud SQL 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 de autenticação do Cloud SQL emite solicitações à API Cloud SQL Admin. Essas solicitações são deduzidas da cota de API do projeto.

O maior uso de API ocorre quando você inicia o proxy de autenticação do Cloud SQL. Enquanto o proxy de autenticação do Cloud SQL 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 de autenticação do Cloud SQL

Ao se conectar à instância usando o proxy de autenticação do Cloud SQL, 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 de autenticação do Cloud SQL sempre se conecta por meio de um nome de host que não pode ser acessado, exceto por ele mesmo, é possível criar uma conta de usuário que possa ser usada apenas pelo proxy de autenticação do Cloud SQL. 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 de autenticação do Cloud SQL, 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 flags do proxy de autenticação do Cloud SQL

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

Para receber ajuda com as opções do proxy de autenticação do Cloud SQL, consulte as seguintes informações:

Como o FUSE é usado com o proxy de autenticação do Cloud SQL

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

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

  • O proxy de autenticação do Cloud SQL intercepta a solicitação e, em retorno, informa que /cloudsql/$INSTANCE é um link simbólico que aponta 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.

Instalar o 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.

Usar o proxy de autenticação do Cloud SQL em um ambiente de produção

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

Verifique se o proxy de autenticação do Cloud SQL é executado como um serviço persistente

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

Quantas cópias do proxy de autenticação do Cloud SQL 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 do proxy de autenticação do Cloud SQL. Execute um processo do cliente do proxy de autenticação do Cloud SQL 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 de autenticação do Cloud SQL 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 do proxy de autenticação do Cloud SQL.

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

Reduzir a saída do proxy de autenticação do Cloud SQL

Se você precisar reduzir o tamanho do registro do proxy de autenticação do Cloud SQL, defina --quiet ao iniciar o proxy. No entanto, lembre-se de que isso reduz a eficácia da saída do proxy de autenticação do Cloud SQL no diagnóstico de problemas de conexão.

Como o failover afeta o proxy de autenticação do Cloud SQL

Se você estiver executando o proxy de autenticação do Cloud SQL em uma instância configurada para alta disponibilidade e ocorrer um failover, as conexões que o usam serão afetadas da mesma forma que as conexões por IP: todas as conexões atuais 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.

Manter a imagem Docker do proxy de autenticação do Cloud SQL atualizada

A imagem Docker do proxy de autenticação do Cloud SQL é baseada em uma versão específica do proxy. Quando uma nova versão do proxy de autenticação do Cloud SQL estiver disponível, extraia a nova versão da imagem Docker do proxy de autenticação do Cloud SQL para manter o ambiente atualizado. Você pode ver qual é a versão atual na página de versões do proxy de autenticação do Cloud SQL no GitHub.

Como aplicar o uso do proxy de autenticação do Cloud SQL

É possível aplicar o uso do proxy de autenticação do Cloud SQL nas conexões da instância do Cloud SQL com ConnectorEnforcement. Com a aplicação do conector, a conexão direta ao banco de dados é rejeitada.

Para usar a aplicação do conector, use o campo ConnectorEnforcement na API instances.

Para mais informações, consulte Editar instâncias.

Sobre o operador do Cloud SQL Proxy

O Operador de proxy do Cloud SQL é um operador de código aberto do Kubernetes que automatiza a conexão de cargas de trabalho em um cluster do GKE aos bancos de dados do Cloud SQL. O operador do proxy de autenticação do Cloud SQL utiliza um recurso personalizado AuthProxyWorkload que especifica a configuração do proxy de autenticação do Cloud SQL para uma carga de trabalho específica. Esse operador lê o recurso e adiciona um contêiner do proxy de autenticação do Cloud SQL com a configuração necessária para as cargas de trabalho apropriadas.

Quando você instala o operador no cluster do GKE e configura as cargas de trabalho e as instâncias do Cloud SQL, o operador do proxy de autenticação do Cloud SQL configura automaticamente o proxy de autenticação do Cloud SQL e conecta as cargas de trabalho do GKE às instâncias do Cloud SQL.

O operador do proxy de autenticação do Cloud SQL também verifica o status do proxy. Quando o proxy de autenticação do Cloud SQL não consegue se conectar, o operador do proxy gera informações de depuração e fornece orientação para solucionar problemas comuns de configuração.

Para mais informações, consulte Conectar usando o operador de proxy do Cloud SQL.

A seguir