Nesta página, confira como estabelecer uma conexão com a instância do Cloud SQL usando o proxy de autenticação do Cloud SQL.
Para mais informações sobre como o proxy de autenticação do Cloud SQL funciona, consulte Sobre o proxy de autenticação do Cloud SQL.
Informações gerais
Usar o proxy de autenticação do Cloud SQL é o método recomendado para se conectar a uma instância do Cloud SQL. O proxy de autenticação do Cloud SQL:
- Funciona com endpoints de IP público e particular
- Valida conexões usando credenciais de um usuário ou conta de serviço
- Encapsula a conexão em uma camada SSL/TLS autorizada para uma instância do Cloud SQL
Alguns serviços e aplicativos do Google Cloud usam o proxy de autenticação do Cloud SQL para fornecer conexões a caminhos de IP públicos com criptografia e autorização, incluindo o seguinte:
Os aplicativos em execução no Google Kubernetes Engine podem se conectar usando o proxy de autenticação do Cloud SQL.
Confira uma introdução básica ao uso do proxy de autenticação no guia de início rápido para uso do proxy de autenticação do Cloud SQL.
Também é possível se conectar, com ou sem o proxy de autenticação do Cloud SQL, usando um cliente psql de uma máquina local ou do Compute Engine.
Antes de começar
Antes de se conectar a uma instância do Cloud SQL, faça o seguinte:
-
- Para um usuário ou conta de serviço, verifique se a conta tem o
papel de cliente do Cloud SQL. Esse papel contém a
permissão
cloudsql.instances.connect
, que autoriza um principal a se conectar a todas as instâncias do Cloud SQL em um projeto. - Se quiser, é possível incluir uma condição do IAM na vinculação de política do IAM que conceda à conta permissão para se conectar apenas a uma instância específica do Cloud SQL.
- Para um usuário ou conta de serviço, verifique se a conta tem o
papel de cliente do Cloud SQL. Esse papel contém a
permissão
-
Enable the Cloud SQL Admin API.
- Instale e inicialize a gcloud CLI.
- Opcional. Instale o cliente Docker do proxy de autenticação do Cloud SQL.
Fazer o download do 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.11.2/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.11.2/cloud-sql-proxy.linux.386
- Se o comando
curl
não for encontrado, executesudo apt install curl
e 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.11.2/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.11.2/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.11.2/cloud-sql-proxy.x64.exe e selecione Salvar link como para baixar o proxy do Cloud SQL Auth. 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.11.2/cloud-sql-proxy.x86.exe e selecione Salvar link como para baixar o proxy do Cloud SQL Auth. 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.11.2
Outros SOs
Para outros sistemas operacionais não incluídos aqui, compile o proxy do Cloud SQL Auth a partir do código-fonte.Iniciar o proxy do Cloud SQL Auth.
Dependendo da linguagem e do ambiente, é possível iniciar o proxy de autenticação do Cloud SQL usando soquetes TCP, soquetes Unix ou a respectiva imagem Docker. O binário do proxy de autenticação do Cloud SQL se conecta a uma ou mais instâncias do Cloud SQL especificadas na linha de comando e abre uma conexão local tanto como um soquete TCP como um soquete Unix. Outros aplicativos e serviços, como o código do aplicativo ou as ferramentas de cliente de gerenciamento de banco de dados, podem se conectar a instâncias do Cloud SQL por meio dessas conexões de soquete TCP ou Unix.
Soquetes TCP
Para conexões TCP, o proxy de autenticação do Cloud SQL faz a detecção em localhost
(127.0.0.1
) por padrão.
Portanto, quando você especifica --port PORT_NUMBER
para uma instância, a conexão local é em 127.0.0.1:PORT_NUMBER
.
Como alternativa, você pode especificar um endereço diferente para a conexão local.
Por exemplo, confira como fazer o proxy de autenticação do Cloud SQL realizar as detecções em 0.0.0.0:1234
para a
conexão local:
./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME
Copie o INSTANCE_CONNECTION_NAME. Isso pode ser encontrado na página Visão geral da instância no console do Google Cloud ou executando o seguinte comando: .
.gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
Por exemplo, myproject:myregion:myinstance.
- Se a instância tiver IP público e privado configurados e você quiser que o
proxy de autenticação do Cloud SQL use o endereço IP privado,
forneça a seguinte opção ao iniciar o proxy de autenticação do Cloud SQL:
--private-ip
- Se você estiver usando uma conta de serviço para autenticar o proxy de autenticação do Cloud SQL, anote o local em que o arquivo da chave privada foi criado na máquina do cliente durante a criação da conta de serviço.
- Inicie o proxy de autenticação do Cloud SQL.
Algumas strings de invocação possíveis do proxy de autenticação do Cloud SQL:
- Usando autenticação do SDK do Cloud:
A porta especificada não pode estar em uso, por exemplo, por um servidor de banco de dados local../cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
- Usar uma conta de serviço e incluir explicitamente o nome da conexão da instância
(recomendado para ambientes de produção):
./cloud-sql-proxy \ --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
Para mais informações sobre as opções do proxy de autenticação do Cloud SQL, consulte Opções de autenticação do proxy de autenticação do Cloud SQL e Opções para especificar instâncias.
- Usando autenticação do SDK do Cloud:
Soquetes Unix
O proxy de autenticação do Cloud SQL também pode fazer detecções em um soquete Unix, um mecanismo padrão do Posix para usar uma pasta a fim de gerenciar a comunicação entre dois processos em execução no mesmo host. As vantagens de usar soquetes Unix são a segurança aprimorada e a latência menor. No entanto, não é possível acessar um soquete Unix de uma máquina externa.
Para criar e usar um soquete Unix, o diretório de destino precisa existir e o proxy de autenticação do Cloud SQL e o aplicativo precisam ter acesso de leitura e gravação a ele.
- Se você estiver usando a especificação explícita de instâncias, copie a INSTANCE_CONNECTION_NAME.
Isso está disponível na página Visão geral da
instância no console do Google Cloud ou executando o
seguinte comando:
gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
Por exemplo, myproject:myregion:myinstance.
- Crie o diretório onde ficarão os soquetes do proxy de autenticação do Cloud SQL:
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
- Se você estiver usando uma conta de serviço para autenticar o proxy de autenticação do Cloud SQL, anote o local em que o arquivo da chave privada foi criado na máquina do cliente durante a criação da conta de serviço.
- Abra uma nova janela de terminal do Cloud Shell e inicie o proxy de autenticação do Cloud SQL.
Algumas strings de invocação possíveis do proxy de autenticação do Cloud SQL:
- Usar uma conta de serviço e incluir explicitamente o nome da conexão da instância
(recomendado para ambientes de produção):
./cloud-sql-proxy --unix-socket /cloudsql --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
- Usando a autenticação do SDK do Cloud e a descoberta automática de instâncias:
./cloud-sql-proxy --unix-socket /cloudsql &
Inicie o proxy de autenticação do Cloud SQL no próprio terminal do Cloud Shell para monitorar a saída dele sem misturá-la com a saída de outros programas.
Para mais informações sobre as opções do proxy de autenticação do Cloud SQL, consulte Opções de autenticação do proxy de autenticação do Cloud SQL e Opções para especificar instâncias.
- Usar uma conta de serviço e incluir explicitamente o nome da conexão da instância
(recomendado para ambientes de produção):
Docker
Para executar o proxy de autenticação do Cloud SQL em um contêiner do Docker, use a respectiva imagem Docker disponível no Google Container Registry.
Inicie o proxy de autenticação do Cloud SQL usando soquetes TCP ou Unix, com os comandos mostrados abaixo. As opções usam uma INSTANCE_CONNECTION_NAME como a string de conexão para identificar uma instância do Cloud SQL. Encontre o INSTANCE_CONNECTION_NAME na página Visão geral da instância no console do Google Cloud ou executando este comando:
gcloud sql instances describe INSTANCE_NAME
Por exemplo, myproject:myregion:myinstance
.
Dependendo da linguagem e do ambiente, inicie o proxy de autenticação do Cloud SQL usando os soquetes TCP ou Unix. Os soquetes Unix não são compatíveis com aplicativos desenvolvidos na linguagem de programação Java ou com o ambiente Windows.
Como usar soquetes TCP
docker run -d \\ -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\ -p 127.0.0.1:5432:5432 \\ gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 \\ --address 0.0.0.0 --port 5432 \\ --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME
Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro --credentials-file
e a linha -v PATH_TO_KEY_FILE:/path/to/service-account-key.json
.
Sempre especifique o prefixo 127.0.0.1
em -p para que o proxy de autenticação do Cloud SQL não seja
exposto fora do host local. O "0.0.0.0" no parâmetro das instâncias é necessário para tornar a porta acessível de fora do contêiner do Docker.
Como usar soquetes Unix
docker run -d -v /cloudsql:/cloudsql \\ -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\ gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 --unix-socket=/cloudsql \\ --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME
Se você usa as credenciais fornecidas pela instância do Compute Engine, não inclua o parâmetro --credentials-file
e a linha -v PATH_TO_KEY_FILE:/path/to/service-account-key.json
.
Se você usa uma imagem otimizada para contêiner, utilize um diretório gravável em vez de /cloudsql
. Por exemplo:
-v /mnt/stateful_partition/cloudsql:/cloudsql
É possível especificar mais de uma instância, separadas por vírgulas. Também é possível usar metadados do Compute Engine para determinar dinamicamente a quais instâncias se conectar. Saiba mais sobre os parâmetros do proxy de autenticação do Cloud SQL..
Estabeleça conexão com o cliente psql
Debian/Ubuntu
Instale o cliente psql do gerenciador de pacotes:
sudo apt-get update sudo apt-get install postgresql-client
CentOS/RHEL
Instale o cliente psql do gerenciador de pacotes:
sudo yum install postgresql
openSUSE
Instale o cliente psql do gerenciador de pacotes:
sudo zypper install postgresql
Outras plataformas
- Faça o download da PostgreSQL Core Distribution referente à sua plataforma na página de downloads do PostgreSQL (em inglês).
A Core Distribution inclui o cliente psql. - Instale o banco de dados PostgreSQL de acordo com as orientações contidas na página de download.
A string de conexão usada depende de como você iniciou o proxy de autenticação do Cloud SQL, ou seja, usando um soquete TCP, um soquete Unix ou o Docker.
Soquetes TCP
- Inicie o cliente psql:
psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
Mesmo que o parâmetro
sslmode
esteja definido comodisable
, o proxy de autenticação do Cloud SQL fornece uma conexão criptografada.Quando você se conecta usando soquetes TCP, o proxy de autenticação do Cloud SQL é acessado por meio de
127.0.0.1
. - Se solicitado, digite a senha.
- O prompt do psql é exibido.
Como usar soquetes Unix
- Inicie o cliente psql:
psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"
Mesmo que o parâmetro
sslmode
esteja definido comodisable
, o proxy de autenticação do Cloud SQL fornece uma conexão criptografada. - Digite a senha.
- O prompt do psql é exibido.
Precisa de ajuda? Para receber ajuda na solução de problemas do proxy, consulte Solução de problemas de conexões do proxy de autenticação do Cloud SQL ou a página Suporte do Cloud SQL.
Conectar-se com um aplicativo
É possível se conectar ao proxy de autenticação do Cloud SQL por meio de qualquer linguagem que permita a conexão com um soquete Unix ou TCP. Veja abaixo alguns snippets de código de exemplos completos no GitHub para ajudar você a entender como eles funcionam em conjunto no aplicativo.
Temas adicionais
Argumentos da linha de comando do proxy de autenticação do Cloud SQL
Os exemplos acima abrangem os casos de uso mais comuns, mas o proxy de autenticação do Cloud SQL
também tem outras opções de configuração que podem ser definidas com argumentos de linha de
comando. Para receber ajuda sobre argumentos de linha de comando, use a sinalização --help
para ver a documentação mais recente:
./cloud-sql-proxy --help
Consulte o README no repositório do proxy de autenticação do Cloud SQL no GitHub para conferir outros exemplos de como usar as opções de linha de comando desse proxy.
Opções de autenticação do proxy de autenticação do Cloud SQL
Todas essas opções usam um INSTANCE_CONNECTION_NAME como a string de conexão para identificar uma instância do Cloud SQL. Encontre o INSTANCE_CONNECTION_NAME na página Visão geral da instância no console do Google Cloud ou executando este comando:
gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME
Por exemplo: gcloud sql instances describe --project myproject myinstance
.
Algumas dessas opções usam um arquivo de credenciais JSON que inclui a chave privada RSA da conta. Para instruções sobre como criar um arquivo de credenciais JSON para uma conta de serviço, consulte Como criar uma conta de serviço.
O proxy de autenticação do Cloud SQL fornece várias alternativas para autenticação, de acordo com o ambiente. O proxy de autenticação do Cloud SQL verifica cada um dos itens a seguir, na seguinte ordem, usando o primeiro item encontrado para tentar realizar a autenticação:
Credenciais fornecidas pela flag credentials-file.
Use uma conta de serviço para criar e fazer o download do arquivo JSON associado e defina a flag--credentials-file
para o caminho do arquivo ao iniciar o proxy de autenticação do Cloud SQL. A conta de serviço precisa ter as permissões necessárias para a instância do Cloud SQL.Para usar essa opção na linha de comando, invoque o comando
cloud-sql-proxy
com a flag--credentials-file
definida para o caminho e o nome de um arquivo de credencial JSON. O caminho pode ser absoluto ou relativo ao diretório de trabalho atual. Exemplo:./cloud-sql-proxy --credentials-file PATH_TO_KEY_FILE \ INSTANCE_CONNECTION_NAME
Para instruções detalhadas sobre como adicionar papéis do IAM a uma conta de serviço, consulte Como conceder papéis a contas de serviço.
Saiba mais sobre os papéis compatíveis com o Cloud SQL em Papéis do IAM para o Cloud SQL.
Credenciais fornecidas por um token de acesso.
Crie um token de acesso e invoque o comentáriocloud-sql-proxy
com a flag--token
definida como um token de acesso do OAuth 2.0. Exemplo:./cloud-sql-proxy --token ACCESS_TOKEN \ INSTANCE_CONNECTION_NAME
Credenciais fornecidas por uma variável de ambiente.
Essa opção é semelhante a usar a flag--credentials-file
, mas, neste caso você especifica o arquivo de credencial JSON definido na variável de ambienteGOOGLE_APPLICATION_CREDENTIALS
em vez de usar o argumento de linha de comando--credentials-file
.Credenciais de um cliente CLI gcloud autenticado.
Se você tiver instalado a CLI gcloud e realizado a autenticação com sua conta pessoal, o proxy de autenticação do Cloud SQL poderá usar as mesmas credenciais de conta. Esse método é especialmente útil para colocar um ambiente para desenvolvedores em funcionamento.
Para permitir que o proxy de autenticação do Cloud SQL use as credenciais da CLI gcloud, use o comando a seguir para autenticá-la:
gcloud auth application-default login
Credenciais associadas à instância do Compute Engine
Se você estiver usando uma instância do Compute Engine para se conectar ao Cloud SQL, o proxy de autenticação do Cloud SQL poderá usar a conta de serviço associada a essa instância. Se a conta de serviço tiver as permissões necessárias para a instância do Cloud SQL, o proxy de autenticação do Cloud SQL será autenticado com êxito.Se a instância do Compute Engine estiver no mesmo projeto que a instância do Cloud SQL, a conta de serviço padrão da instância do Compute Engine terá as permissões necessárias para autenticar o proxy de autenticação do Cloud SQL. Se as duas instâncias estiverem em projetos diferentes, adicione a conta de serviço da instância do Compute Engine ao projeto que contém a instância do Cloud SQL.
Conta de serviço padrão do ambiente
Se o proxy de autenticação do Cloud SQL não conseguir encontrar credenciais em nenhum dos locais cobertos anteriormente, ele seguirá a lógica documentada em Como configurar a autenticação para aplicativos de produção de servidor para servidor. Alguns ambientes (como Compute Engine, App Engine e outros) fornecem uma conta de serviço padrão que o aplicativo pode usar para autenticar por padrão. Para usar uma conta de serviço padrão, ela precisa ter as permissões descritas em papéis e permissões. Para mais informações sobre a abordagem do Google Cloud para autenticação, consulte Visão geral da autenticação.
Crie uma conta de serviço
- No Console do Google Cloud, acesse a página Contas de serviço.
- Selecione o projeto que contém a instância do Cloud SQL.
- Clique em Criar conta de serviço.
- Preencha o campo Nome da conta de serviço.
- Altere o ID da conta de serviço para um valor exclusivo e facilmente reconhecível, depois clique em Criar e continuar.
-
Clique no campo Selecionar papel e escolha um dos seguintes papéis:
- Cloud SQL > Cliente do Cloud SQL
- Cloud SQL > Editor do Cloud SQL
- Cloud SQL > Administrador do Cloud SQL
- Clique em Concluído para terminar a criação da conta de serviço.
- Clique no menu de ações da sua nova conta de serviço e selecione Gerenciar chaves.
- Clique no menu suspenso Adicionar chave e clique em Criar nova chave.
-
Confirme se o tipo de chave é JSON e clique em Criar.
O arquivo da chave privada é transferido para sua máquina. Você pode movê-lo para outro local. Mantenha-o seguro.
Usar o proxy de autenticação do Cloud SQL com um IP privado
Para se conectar a uma instância do Cloud SQL usando o IP particular, o proxy do Cloud SQL Auth precisa estar em um recurso com acesso à mesma rede VPC que a instância.
O proxy de autenticação do Cloud SQL usa um IP para estabelecer uma conexão com a instância do Cloud SQL. Por padrão, ele tenta se conectar usando um endereço IPv4 público.
Se a instância do Cloud SQL tiver apenas um IP privado ou tiver um IP público e um privado configurados e você quiser que o proxy do Cloud SQL Auth usar o endereço IP privado, forneça a seguinte opção ao iniciar o proxy do Cloud SQL Auth:
--private-ip
Usar o proxy de autenticação do Cloud SQL com instâncias que tenham o Private Service Connect ativado
Use o proxy do Cloud SQL Auth para se conectar a uma instância do Cloud SQL com o Private Service Connect ativado.
O proxy de autenticação do Cloud SQL é um conector que fornece acesso seguro a essa instância sem a necessidade de redes autorizadas ou configuração de SSL.
Para permitir conexões de cliente do proxy de autenticação do Cloud SQL, você precisa configurar um registro DNS que corresponda ao nome DNS recomendado que foi fornecido para a instância. O registro DNS é um mapeamento entre um recurso de DNS e um nome de domínio.
Para mais informações sobre como usar o proxy do Cloud SQL Auth para se conectar a instâncias com o Private Service Connect ativado, consulte Conectar usando o proxy de autenticação do Cloud SQL.
Executar o proxy de autenticação do Cloud SQL em um processo separado
Executar o proxy de autenticação do Cloud SQL em um processo de terminal separado do Cloud Shell pode ser útil para evitar misturar a saída do console com a saída de outros programas. Use a sintaxe mostrada abaixo para invocar o proxy de autenticação do Cloud SQL em um processo separado.
Linux
No Linux ou no macOS, use um &
à direita na linha de comando para
iniciar o proxy de autenticação do Cloud SQL em um processo separado:
./cloud-sql-proxy INSTANCE_CONNECTION_NAME
--credentials-file PATH_TO_KEY_FILE &
Windows
No Windows PowerShell, use o comando Start-Process
para iniciar
o proxy de autenticação do Cloud SQL em um processo separado:
Start-Process --filepath "cloud-sql-proxy.exe"
--ArgumentList "
--credentials-file PATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"
Executar o proxy de autenticação do Cloud SQL em um contêiner do Docker
Para executar o proxy de autenticação do Cloud SQL em um contêiner do Docker, use a respectiva imagem Docker
disponível no Google Container Registry.
É possível instalar a imagem Docker do proxy de autenticação do Cloud SQL com este comando gcloud
:
docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2
Inicie o proxy de autenticação do Cloud SQL usando soquetes TCP ou Unix, com os comandos mostrados abaixo.
Soquetes TCP
docker run -d \ -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \ -p 127.0.0.1:5432:5432 \ gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 \ --address 0.0.0.0 \ --credentials-file /path/to/service-account-key.json \ INSTANCE_CONNECTION_NAME
Soquetes Unix
docker run -d \ -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \ -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \ gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.2 --unix-socket /cloudsql \ --credentials-file /path/to/service-account-key.json/PATH_TO_KEY_FILE \ INSTANCE_CONNECTION_NAME
Se você usa uma imagem otimizada para contêiner, utilize um diretório gravável em vez de /cloudsql
. Por exemplo:
v /mnt/stateful_partition/cloudsql:/cloudsql
Se você usa as credenciais fornecidas pela instância do Compute Engine,
não inclua o parâmetro credential_file
e a
linha -v PATH_TO_KEY_FILE:/path/to/service-account-key.json
.
Como executar o proxy de autenticação do Cloud SQL como um serviço
Executar o proxy de autenticação do Cloud SQL como um serviço em segundo plano é uma opção para cargas de trabalho de desenvolvimento e produção locais. Em desenvolvimento, quando você precisar acessar sua instância do Cloud SQL, inicie o serviço em segundo plano e interrompa-o quando terminar.
No momento, no caso das cargas de trabalho de produção, o proxy de autenticação do Cloud SQL não é compatível com a execução como um serviço do Windows, mas gerenciadores de serviço de terceiros podem ser usados para executá-lo como um serviço. Por exemplo, use o NSSM para configurar o proxy de autenticação do Cloud SQL como um serviço do Windows. O NSSM monitora o proxy de autenticação do Cloud SQL e o reinicia automaticamente quando ele deixa de responder. Consulte a documentação do NSSM para mais informações.
Exigir o uso do proxy de autenticação do Cloud SQL
Ative o uso do proxy de autenticação do Cloud SQL no Cloud SQL usando ConnectorEnforcement.
gcloud
O comando a seguir impõe o uso dos conectores do Cloud SQL.
gcloud sql instances patch INSTANCE_NAME \ --connector-enforcement REQUIRED
Para desativar a aplicação, use a seguinte linha de código:
--connector-enforcement NOT_REQUIRED
A atualização não aciona uma reinicialização.
REST v1
O comando a seguir aplica o uso dos conectores do Cloud SQL
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- project-id: o ID do projeto.
- instance-id: o ID da instância
Método HTTP e URL:
PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id
Corpo JSON da solicitação:
{ "settings": { "connectorEnforcement": "REQUIRED" } }
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ "kind": "sql#operation", "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id", "status": "PENDING", "user": "user@example.com", "insertTime": "2020-01-16T02:32:12.281Z", "operationType": "UPDATE", "name": "operation-id", "targetId": "instance-id", "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id", "targetProject": "project-id" }
Para desativar a aplicação,
use "connectorEnforcement": "NOT_REQUIRED"
. A atualização não aciona uma reinicialização.
REST v1beta4
O comando a seguir impõe o uso dos conectores do Cloud SQL.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- project-id: o ID do projeto.
- instance-id: o ID da instância
Método HTTP e URL:
PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id
Corpo JSON da solicitação:
{ "settings": { "connectorEnforcement": "REQUIRED" } }
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ "kind": "sql#operation", "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id", "status": "PENDING", "user": "user@example.com", "insertTime": "2020-01-16T02:32:12.281Z", "operationType": "UPDATE", "name": "operation-id", "targetId": "instance-id", "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id", "targetProject": "project-id" }
Para desativar a aplicação,
use "connectorEnforcement": "NOT_REQUIRED"
. A atualização não aciona uma reinicialização.
Dicas para trabalhar com o proxy de autenticação do Cloud SQL
Invocar o proxy de autenticação do Cloud SQL
Todas as invocações de proxy de exemplo iniciam o proxy de autenticação do Cloud SQL em segundo plano. Devido a isso, um prompt é retornado. Reserve o terminal do Cloud Shell para o proxy de autenticação do Cloud SQL a fim de evitar que a saída seja confundida com a de outros programas. Além disso, a saída do proxy de autenticação do Cloud SQL pode ajudar você a diagnosticar problemas de conexão. Portanto, pode ser útil capturá-la em um arquivo de registro. Se você não iniciar o proxy de autenticação do Cloud SQL em segundo plano, a saída irá para stdout, a menos que seja redirecionada.
Não é necessário usar /cloudsql
como o diretório dos soquetes do proxy de autenticação do Cloud SQL. Esse nome de diretório foi escolhido para minimizar as diferenças com as strings de conexão do App Engine. Porém, se você alterar o nome do diretório, mantenha um tamanho total mínimo, visto que é incorporado a uma string mais longa com limite de tamanho imposto pelo sistema operacional. Depende do sistema, mas geralmente é
entre 91 e 108 caracteres. No Linux, o tamanho geralmente é definido como 108.
Use o seguinte comando para verificar:
cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"
Usar o proxy de autenticação do Cloud SQL para a conexão com várias instâncias
Use um cliente local do proxy de autenticação do Cloud SQL para se conectar a várias instâncias do Cloud SQL. A maneira de fazer isso dependerá do uso de soquetes Unix ou TCP.
Soquetes Unix
Para conectar o proxy do Cloud SQL Auth a várias instâncias, informe a ele o nome de conexão de cada instância como um argumento, em uma lista separada por vírgulas. O proxy de autenticação do Cloud SQL se conecta a cada instância quando é iniciado.
Conecte-se a cada instância usando o soquete correspondente no diretório especificado.
Exemplo:
./cloud-sql-proxy --unix-socket /cloudsql \ myProject:us-central1:myInstance myProject:us-central1:myInstance2 & psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2
Soquetes TCP
Ao se conectar usando TCP, você especificará uma porta na máquina para que o proxy de autenticação do Cloud SQL faça a detecção para cada instância do Cloud SQL. Ao se conectar a várias instâncias do Cloud SQL, cada porta especificada precisa ser exclusiva e estar disponível para uso em sua máquina.
Exemplo:
# Start the Cloud SQL Auth Proxy to connect to two different Cloud SQL instances # Give the Cloud SQL Auth Proxy a unique port on your machine to use for each Cloud SQL instance. ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" \ "myProject:us-central1:myInstance2?port=1234" # Connect to "myInstance" using port 5432 on your machine: psql -U myUser -h 127.0.0.1 --port 5432 # Connect to "myInstance2" using port 1234 on your machine: psql -U myUser -h 127.0.0.1 --port 1234
Invocações do proxy de autenticação do Cloud SQL e strings de conexão do cliente psql
É possível usar strings de conexão e invocações do proxy de autenticação do Cloud SQL, por exemplo, em comandos
para um usuário myUser
do PostgreSQL, para a instância myInstance
, localizada em
us-central1
, no projeto myProject
.
./cloud-sql-proxy --unix-socket /cloudsql & psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
./cloud-sql-proxy --unix-socket /cloudsql & psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
./cloud-sql-proxy --unix-socket /cloudsql myProject:us-central1:myInstance & psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" & psql -U myUser -h 127.0.0.1
cloud-sql-proxy.exe "myProject:us-central1:myInstance?port=5432" psql -U myUser -h 127.0.0.1
Para mais informações sobre as opções e as strings de conexão do proxy de autenticação do Cloud SQL, consulte a página do proxy de autenticação do Cloud SQL no GitHub.
Resolver problemas de conexões do proxy de autenticação do Cloud SQL
A imagem do 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 do Cloud SQL Auth no GitHub.
Se você tiver problemas para se conectar à instância do Cloud SQL usando o proxy de autenticação do Cloud SQL, tente aplicar as opções a seguir para encontrar o motivo.
Verifique a saída do proxy de autenticação do Cloud SQL.
Muitas vezes, a saída do proxy pode ajudar você a determinar a origem do problema e saber como resolvê-lo. Redirecione a saída para um arquivo ou observe o terminal do Cloud Shell em que você iniciou o proxy de autenticação do Cloud SQL.
Se você estiver recebendo um erro
403 notAuthorized
e estiver usando uma conta de serviço para autenticar o proxy de autenticação de Cloud SQL, verifique se a conta de serviço tem as permissões corretas.Você pode verificar a conta de serviço pesquisando pelo ID dela na página "IAM". A conta precisa ter a permissão
cloudsql.instances.connect
. Os papéis predefinidosCloud SQL Admin
,Client
eEditor
têm essa permissão.Se você estiver se conectando a partir do App Engine e estiver recebendo um erro
403 notAuthorized
, verifique acloud_sql_instances
valorapp.yaml
quanto a um nome de conexão de instância incorreto ou incorreto. Os nomes das conexões de instâncias estão sempre no formatoPROJECT:REGION:INSTANCE
.Além disso, verifique se a conta de serviço do App Engine (por exemplo, $PROJECT_ID@appspot.gserviceaccount.com) tem o papel de Cliente do Cloud SQL do IAM.
Se o serviço do App Engine residir em um projeto (projeto A) e o banco de dados em outro (projeto B), esse erro significa que a conta de serviço do App Engine não recebeu o papel de Cliente do Cloud SQL do IAM no projeto com o banco de dados (projeto B).
Certifique-se de ativar a API Cloud SQL Admin.
Caso contrário, você verá uma saída como
Error 403: Access Not Configured
nos registros do proxy de autenticação do Cloud SQL.Se você estiver incluindo várias instâncias na lista de instâncias, use a vírgula como delimitador, sem espaços. Se você estiver usando o TCP, especifique portas diferentes para cada instância.
Se você estiver se conectando com soquetes UNIX, confirme se eles foram criados listando o diretório fornecido quando você iniciou o proxy de autenticação do Cloud SQL.
Se você tiver uma política de firewall para o tráfego de saída, verifique se ela permite conexões com a porta 3307 na instância do Cloud SQL de destino.
É possível confirmar se o proxy de autenticação do Cloud SQL foi iniciado corretamente procurando nos registros na seção Operações > Logging > Análise de registros do console do Google Cloud. Uma operação bem-sucedida é semelhante a esta:
2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/5432 for $PROJECT_ID:$REGION:$INSTANCE_NAME 2021/06/14 15:47:56 Ready for new connections
Problemas de cota: quando a cota da API Cloud SQL Admin é violada, o proxy de autenticação do Cloud SQL é iniciado com a seguinte mensagem de erro:
There was a problem when parsing a instance configuration but ignoring due to the configuration. Error: googleapi: Error 429: Quota exceeded for quota metric 'Queries' and limit 'Queries per minute per user' of service 'sqladmin.googleapis.com' for consumer 'project_number:$PROJECT_ID., rateLimitExceeded
Depois que um aplicativo se conecta ao proxy, o proxy informa o seguinte erro:
failed to refresh the ephemeral certificate for $INSTANCE_CONNECTION_NAME: googleapi: Error 429: Quota exceeded for quota metric 'Queries' and limit 'Queries per minute per user' of service 'sqladmin.googleapis.com' for consumer 'project_number:$PROJECT_ID., rateLimitExceeded
Solução: identifique a origem do problema de cota, por exemplo, um aplicativo está usando o conector de maneira incorreta e criando novas conexões desnecessariamente, ou entre em contato com o suporte para solicitar um aumento na cota da API Cloud SQL Admin. Se o erro de cota aparecer na inicialização, você precisará reimplantar o aplicativo para reiniciar o proxy. Se o erro de cota aparecer após a inicialização, a reimplantação será desnecessária.
A seguir
- Saiba mais sobre o proxy de autenticação do Cloud SQL.
- Saiba mais sobre o Gerenciamento de identidade e acesso.
- Saiba mais sobre Contas de serviço.
- Saiba mais sobre os dois níveis de controle de acesso para instâncias do Cloud SQL.
- Crie usuários e bancos de dados.
- Saiba mais sobre como se conectar à instância pelo aplicativo.
- Saiba mais sobre o cliente psql (em inglês).
- Conheça as opções de suporte.