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.
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.
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.
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
Linux de 64 bits
- 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.14.1/cloud-sql-proxy.linux.amd64
- Torne o proxy do Cloud SQL Auth executável:
chmod +x cloud-sql-proxy
Linux de 32 bits
- 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.14.1/cloud-sql-proxy.linux.386
- Se o comando
curlnão for encontrado, executesudo apt install curle repita o comando de download. - Torne o proxy do Cloud SQL Auth executável:
chmod +x cloud-sql-proxy
macOS de 64 bits
- 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.14.1/cloud-sql-proxy.darwin.amd64
- Torne o proxy do Cloud SQL Auth executável:
chmod +x cloud-sql-proxy
Mac M1
- 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.14.1/cloud-sql-proxy.darwin.arm64
- 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.14.1/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 paracloud-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.14.1/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 paracloud-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.14.1
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.
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.
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.
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.