Sobre o proxy do Cloud SQL Auth

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:

• Guia de início rápido para usar o Proxy do Cloud SQL Auth
• Como se conectar usando o proxy de autenticação do Cloud SQL
• Como se conectar usando o proxy de autenticação do Cloud SQL pelo GKE

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.

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 seguras: o proxy do Cloud SQL Auth criptografa automaticamente o tráfego de entrada e do banco de dados usando TLS 1.3 com a seleção de criptografia determinada pelas Regras do Go. 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.

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:

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).

Se a instância do Cloud SQL à qual você está se conectando estiver usando autoridade certificadora (AC) compartilhada para a configuração serverCaMode, no lado do cliente, será necessário usar o proxy de autenticação do Cloud SQL versão 2.13.0 ou mais recente.

O modo de CA compartilhado está em (pré-lançamento).

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

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

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.

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:

• Opções de autenticação do proxy de autenticação do Cloud SQL
• Exemplo de invocações do proxy de autenticação do Cloud SQL
• Página do GitHub sobre o proxy de autenticação do Cloud SQL
• Ajuda do proxy de autenticação do Cloud SQL, exibida com ./cloud-sql-proxy --help

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.

Se você estiver usando uma instância com o Private Service Connect ativado, haverá uma limitação. Se a instância tiver a aplicação de conector ativada, não será possível criar réplicas de leitura para ela. Da mesma forma, se a instância tiver réplicas de leitura, não será possível ativar a aplicação do conector nela.

Para mais informações sobre como forçar o uso apenas do proxy de autenticação do Cloud SQL ou dos conectores de linguagem do Cloud SQL para se conectar a uma instância, consulte Forçar o uso do proxy de autenticação do Cloud SQL.

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

• Saiba mais sobre o proxy de autenticação do Cloud SQL.