Sobre o proxy do Cloud SQL Auth

MySQL   |  PostgreSQL   |  SQL Server

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 do Cloud SQL Auth é um conector do Cloud SQL que fornece acesso seguro às suas instâncias sem a necessidade de redes autorizadas ou configuração SSL.

Observação: o Cloud SQL para SQL Server não é compatível com a autenticação do banco de dados do IAM.

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 do Cloud SQL Auth processa a autenticação com o Cloud SQL, 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.

Observação: se uma instância do SQL Server tiver a opção Exigir SSL/TLS marcada, mesmo com o proxy do Cloud SQL Auth ou os conectores do Cloud SQL, o aplicativo cliente precisará ter o TLS/SSL configurado da mesma forma como se o proxy do Cloud SQL Auth ou os conectores do Cloud SQL não estiverem envolvidos, caso contrário, uma tentativa de conexão poderá falhar. Para conexões bem-sucedidas, o proxy do Cloud SQL Auth ou os conectores do Cloud SQL adicionam outra camada de criptografia além da criptografia nativa do SQL Server. Em outras palavras, a conexão entre os conectores do cliente proxy/Cloud SQL e o servidor proxy seria criptografada duas vezes.
A criptografia dupla pode afetar negativamente o desempenho do SQL Server. Sugerimos que os clientes considerem cuidadosamente antes de exigir SSL e usar o proxy do Cloud SQL Auth ou os conectores do Cloud SQL ao mesmo tempo.

Se você estiver usando as linguagens Java, Python ou Go, conecte-se ao conector correspondente em vez do proxy do Cloud SQL Auth.

Como o proxy do Cloud SQL Auth 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.

Observação: a conexão entre os aplicativos cliente e o cliente do proxy de autenticação do Cloud SQL na máquina cliente não é criptografada. Recomendamos que você execute o proxy na mesma máquina que contém a carga de trabalho.

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

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.13.0/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.13.0/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.13.0/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.13.0/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.13.0/cloud-sql-proxy.x64.exe e selecione Salvar link como para fazer o download do 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.13.0/cloud-sql-proxy.x86.exe e selecione Salvar link como para fazer o download do 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.13.0

Observação: o proxy do Cloud SQL Auth usa um repositório que oferece suporte ao domínio gcr.io, mas disponibiliza imagens do Artifact Registry. Para mais informações, consulte Transição do Container Registry.

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.

Observação: o proxy de autenticação do Cloud SQL não é compatível com soquetes Unix no Windows. Os sistemas operacionais baseados em Linux têm um tamanho máximo de 108 caracteres para o caminho do soquete. Se o comprimento total do caminho exceder esse tamanho, não será possível se conectar.

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
• Cloud SQL Admin

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.

Observação: é necessário executar a versão 1.12 ou posterior para se conectar usando IP particular.

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.

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

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.

Observação: o proxy de autenticação do Cloud SQL é um executável do Windows, mas não é um serviço desse SO. Há várias ferramentas disponíveis que podem envolver um binário de aplicativo regular como um serviço.

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

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