Esta página descreve como se conectar à sua instância do Cloud SQL usando o Cloud SQL Auth Proxy.
Para obter mais informações sobre como o Cloud SQL Auth Proxy funciona, consulte Sobre o Cloud SQL Auth Proxy .
Visão geral
O método recomendado para se conectar a uma instância do Cloud SQL é o Proxy de Autenticação do Cloud SQL. O Proxy de Autenticação do Cloud SQL:
- Funciona com endpoints IP públicos e privados
- Valida conexões usando credenciais para uma conta de usuário ou serviço
- Envolve a conexão em uma camada SSL/TLS autorizada para uma instância do Cloud SQL
Alguns Google Cloud serviços e aplicativos usam o Cloud SQL Auth Proxy para fornecer conexões para caminhos IP públicos com criptografia e autorização, incluindo:
Os aplicativos em execução no Google Kubernetes Engine podem se conectar usando o Cloud SQL Auth Proxy.
Consulte o Início rápido para usar o Cloud SQL Auth Proxy para uma introdução básica ao seu uso.
Você também pode se conectar, com ou sem o Cloud SQL Auth Proxy, 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 uma conta de usuário ou serviço, certifique-se de que a conta tenha a função de Cliente do Cloud SQL. Essa função 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. - Opcionalmente, você pode incluir uma condição do IAM na vinculação da política do IAM que concede à conta permissão para se conectar apenas a uma instância específica do Cloud SQL.
- Para uma conta de usuário ou serviço, certifique-se de que a conta tenha a função de Cliente do Cloud SQL. Essa função contém a permissão
-
Enable the Cloud SQL Admin API.
- Instale e inicialize o gcloud CLI .
- Opcional. Instale o cliente Docker do Cloud SQL Auth Proxy .
Baixe o proxy de autenticação do Cloud SQL
Linux de 64 bits
- Baixe o proxy de autenticação do Cloud SQL:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.16.0/cloud-sql-proxy.linux.amd64
- Torne o Cloud SQL Auth Proxy executável:
chmod +x cloud-sql-proxy
Linux 32 bits
- Baixe o proxy de autenticação do Cloud SQL:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.16.0/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 Cloud SQL Auth Proxy executável:
chmod +x cloud-sql-proxy
macOS 64 bits
- Baixe o proxy de autenticação do Cloud SQL:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.16.0/cloud-sql-proxy.darwin.amd64
- Torne o Cloud SQL Auth Proxy executável:
chmod +x cloud-sql-proxy
Mac M1
- Baixe o proxy de autenticação do Cloud SQL:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.16.0/cloud-sql-proxy.darwin.arm64
- Torne o Cloud SQL Auth Proxy executável:
chmod +x cloud-sql-proxy
Windows 64 bits
Clique com o botão direito do mouse em https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.16.0/cloud-sql-proxy.x64.exe e selecione Salvar link como para baixar o Cloud SQL Auth Proxy. Renomeie o arquivo paracloud-sql-proxy.exe
. Windows 32 bits
Clique com o botão direito do mouse em https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.16.0/cloud-sql-proxy.x86.exe e selecione Salvar Link Como para baixar o Cloud SQL Auth Proxy. Renomeie o arquivo paracloud-sql-proxy.exe
. Imagem do Docker do Proxy de Autenticação do Cloud SQL
O Cloud SQL Auth Proxy possui diferentes imagens de contêiner, como distroless
, alpine
e buster
. A imagem de contêiner padrão do Cloud SQL Auth Proxy usa distroless
, que não contém shell. Se precisar de um shell ou ferramentas relacionadas, baixe uma imagem baseada em alpine
ou buster
. Para obter mais informações, consulte Imagens de Contêiner do Cloud SQL Auth Proxy .
Você pode puxar 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.16.0
Outros sistemas operacionais
Para outros sistemas operacionais não incluídos aqui, você pode compilar o Cloud SQL Auth Proxy a partir do código-fonte .Inicie o proxy de autenticação do Cloud SQL
Dependendo do seu idioma e ambiente, você pode iniciar o Cloud SQL Auth Proxy usando soquetes TCP, soquetes Unix ou a imagem Docker do Cloud SQL Auth Proxy. O binário do Cloud SQL Auth Proxy se conecta a uma ou mais instâncias do Cloud SQL especificadas na linha de comando e abre uma conexão local como TCP ou um soquete Unix. Outros aplicativos e serviços, como o código do seu aplicativo ou ferramentas de cliente de gerenciamento de banco de dados, podem se conectar às instâncias do Cloud SQL por meio dessas conexões TCP ou soquete Unix.
Soquetes TCP
Para conexões TCP, o Proxy de Autenticação do Cloud SQL escuta no 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, veja como fazer o Proxy de Autenticação do Cloud SQL escutar 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 seu INSTANCE_CONNECTION_NAME . Ele pode ser encontrado na página Visão geral da sua instância no Google Cloud console 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 Cloud SQL Auth Proxy use o endereço IP privado , forneça a seguinte opção ao iniciar o Cloud SQL Auth Proxy:
--private-ip
- Se você estiver usando uma conta de serviço para autenticar o Cloud SQL Auth Proxy, anote o local na sua máquina cliente do arquivo de chave privada que foi criado quando você criou a conta de serviço.
- Inicie o proxy de autenticação do Cloud SQL.
Algumas possíveis strings de invocação do Cloud SQL Auth Proxy:
- Usando a autenticação do Cloud SDK:
A porta especificada não deve estar em uso, por exemplo, por um servidor de banco de dados local../cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
- Usando uma conta de serviço e incluindo 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 obter mais informações sobre as opções do Cloud SQL Auth Proxy, consulte Opções para autenticação do Cloud SQL Auth Proxy .
- Usando a autenticação do Cloud SDK:
Soquetes Unix
O Cloud SQL Auth Proxy pode escutar em um soquete Unix, que é um mecanismo padrão Posix que usa uma pasta para gerenciar a comunicação entre dois processos em execução no mesmo host. As vantagens de usar soquetes Unix são maior segurança e menor latência; no entanto, você não pode acessar um soquete Unix de uma máquina externa.
Para criar e usar um soquete Unix, o diretório de destino deve existir e tanto o Cloud SQL Auth Proxy quanto o aplicativo devem ter acesso de leitura e gravação a ele.
Copie seu INSTANCE_CONNECTION_NAME . Ele pode ser encontrado na página Visão geral da sua instância no Google Cloud console ou executando o seguinte comando:
gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'
Por exemplo: myproject:myregion:myinstance .
- Crie o diretório onde os soquetes do Cloud SQL Auth Proxy ficarão:
sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
- Se você estiver usando uma conta de serviço para autenticar o Cloud SQL Auth Proxy, anote o local na sua máquina cliente do arquivo de chave privada que foi criado quando você criou a conta de serviço.
- Abra uma nova janela de terminal do Cloud Shell e inicie o Cloud SQL Auth Proxy.
Algumas possíveis strings de invocação do Cloud SQL Auth Proxy:
- Usando a autenticação do Google Cloud SDK:
./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &
- Usando uma conta de serviço:
./cloud-sql-proxy --unix-socket /cloudsql --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
Inicie o Cloud SQL Auth Proxy em seu próprio terminal do Cloud Shell para que você possa monitorar sua saída sem que ela se misture com a saída de outros programas.
Para obter mais informações sobre as opções do Cloud SQL Auth Proxy, consulte Opções para autenticação do Cloud SQL Auth Proxy .
- Usando a autenticação do Google Cloud SDK:
Docker
Para executar o Cloud SQL Auth Proxy em um contêiner do Docker, use a imagem do Docker do Cloud SQL Auth Proxy disponível no Google Container Registry .
Você pode iniciar o Proxy de Autenticação do Cloud SQL usando soquetes TCP ou Unix, com os comandos mostrados abaixo. As opções usam um INSTANCE_CONNECTION_NAME como string de conexão para identificar uma instância do Cloud SQL. Você pode encontrar o INSTANCE_CONNECTION_NAME na página Visão Geral da sua instância no Google Cloud console . ou executando o seguinte comando:
gcloud sql instances describe INSTANCE_NAME
Por exemplo: myproject:myregion:myinstance
.
Dependendo do seu idioma e ambiente, você pode iniciar o Cloud SQL Auth Proxy usando soquetes TCP ou Unix. Soquetes Unix não são compatíveis com aplicativos escritos na linguagem de programação Java ou no ambiente Windows.
Usando 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.16.0 \\ --address 0.0.0.0 --port 5432 \\ --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME
Se você estiver usando as credenciais fornecidas pela sua 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 instances é necessário para tornar a porta acessível de fora do contêiner do Docker.
Usando 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.16.0 --unix-socket=/cloudsql \\ --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME
Se você estiver usando as credenciais fornecidas pela sua 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ê estiver usando uma imagem otimizada para contêiner, use um diretório gravável no lugar de /cloudsql
, por exemplo:
-v /mnt/stateful_partition/cloudsql:/cloudsql
Você pode especificar mais de uma instância, separadas por vírgulas. Você também pode usar metadados do Compute Engine para determinar dinamicamente as instâncias às quais se conectar. Saiba mais sobre os parâmetros do Proxy de Autenticação do Cloud SQL.
Conecte-se com o cliente psql
Debian/Ubuntu
Instale o cliente psql a partir do gerenciador de pacotes:
sudo apt-get update sudo apt-get install postgresql-client
CentOS/RHEL
Instale o cliente psql a partir do gerenciador de pacotes:
sudo yum install postgresql
openSUSE
Instale o cliente psql a partir do gerenciador de pacotes:
sudo zypper install postgresql
Outras plataformas
- Baixe a distribuição principal do PostgreSQL para sua plataforma na página de downloads do PostgreSQL .
A distribuição principal inclui o cliente psql. - Instale o banco de dados PostgreSQL seguindo as instruções na página de download.
A string de conexão que você usa depende se você iniciou o Cloud SQL Auth Proxy usando um soquete TCP, um soquete UNIX ou Docker.
Soquetes TCP
- Inicie o cliente psql:
psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
Embora o parâmetro
sslmode
esteja definido comodisable
, o Cloud SQL Auth Proxy fornece uma conexão criptografada.Quando você se conecta usando soquetes TCP, o Cloud SQL Auth Proxy é acessado por meio de
127.0.0.1
. - Se solicitado, digite a senha.
- O prompt do psql aparece.
Usando soquetes Unix
- Inicie o cliente psql:
psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"
Embora o parâmetro
sslmode
esteja definido comodisable
, o Cloud SQL Auth Proxy fornece uma conexão criptografada. - Digite a senha.
- O prompt do psql aparece.
Precisa de ajuda? Para obter ajuda na solução de problemas do proxy, consulte Solução de problemas de conexões do Cloud SQL Auth Proxy ou consulte nossa página de suporte do Cloud SQL .
Conectar com um aplicativo
Você pode se conectar ao Cloud SQL Auth Proxy a partir de qualquer linguagem que permita a conexão a um soquete Unix ou TCP. Abaixo estão alguns trechos de código de exemplos completos no GitHub para ajudar você a entender como eles funcionam juntos em seu aplicativo.
Tópicos adicionais
Argumentos de linha de comando do Cloud SQL Auth Proxy
Os exemplos acima abrangem os casos de uso mais comuns, mas o Cloud SQL Auth Proxy também possui outras opções de configuração que podem ser definidas com argumentos de linha de comando. Para obter ajuda com argumentos de linha de comando, use a flag --help
para visualizar a documentação mais recente:
./cloud-sql-proxy --help
Consulte o README no repositório GitHub do Cloud SQL Auth Proxy para obter exemplos adicionais de como usar as opções de linha de comando do Cloud SQL Auth Proxy.
Opções para autenticação do Cloud SQL Auth Proxy
Todas essas opções usam um INSTANCE_CONNECTION_NAME como string de conexão para identificar uma instância do Cloud SQL. Você pode encontrar o INSTANCE_CONNECTION_NAME na página "Visão Geral" da sua instância no Google Cloud console . ou executando o seguinte 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 obter instruções sobre como criar um arquivo de credenciais JSON para uma conta de serviço, consulte Criação de uma conta de serviço .
O Cloud SQL Auth Proxy oferece diversas alternativas de autenticação, dependendo do seu ambiente. O Cloud SQL Auth Proxy verifica cada um dos seguintes itens, na seguinte ordem, usando o primeiro que encontrar para tentar autenticar:
Credenciais fornecidas pelo sinalizador credentials-file.
Use uma conta de serviço para criar e baixar o arquivo JSON associado e defina o sinalizador--credentials-file
como o caminho do arquivo ao iniciar o Proxy de Autenticação do Cloud SQL. A conta de serviço deve ter as permissões necessárias para a instância do Cloud SQL.Para usar esta opção na linha de comando, invoque o comando
cloud-sql-proxy
com o sinalizador--credentials-file
definido como o caminho e o nome de um arquivo de credencial JSON. O caminho pode ser absoluto ou relativo ao diretório de trabalho atual. Por exemplo:./cloud-sql-proxy --credentials-file PATH_TO_KEY_FILE \ INSTANCE_CONNECTION_NAME
Para obter instruções detalhadas sobre como adicionar funções do IAM a uma conta de serviço, consulte Concessão de funções a contas de serviço .
Para obter mais informações sobre as funções compatíveis com o Cloud SQL, consulte Funções do IAM para o Cloud SQL .
Credenciais fornecidas por um token de acesso.
Crie um token de acesso e invoque o comandocloud-sql-proxy
com o sinalizador--token
definido como um token de acesso OAuth 2.0. Por exemplo:./cloud-sql-proxy --token ACCESS_TOKEN \ INSTANCE_CONNECTION_NAME
Credenciais fornecidas por uma variável de ambiente.
Esta opção é semelhante ao uso do sinalizador--credentials-file
, exceto que 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 gcloud CLI autenticado.
Se você instalou a CLI do gcloud e se autenticou com sua conta pessoal, o Cloud SQL Auth Proxy poderá usar as mesmas credenciais da conta. Este método é especialmente útil para colocar um ambiente de desenvolvimento em funcionamento.
Para permitir que o Cloud SQL Auth Proxy use suas credenciais do gcloud CLI, use o seguinte comando para autenticar o gcloud CLI:
gcloud auth application-default login
Credenciais associadas à instância do Compute Engine.
Se você estiver se conectando ao Cloud SQL a partir de uma instância do Compute Engine, o Proxy de Autenticação do Cloud SQL poderá usar a conta de serviço associada à instância do Compute Engine. 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 sucesso. 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, você deverá adicionar 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 Cloud SQL Auth Proxy não encontrar credenciais em nenhum dos locais abordados anteriormente, ele seguirá a lógica documentada em Configurando 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 seu aplicativo pode usar para autenticação por padrão. Se você usar uma conta de serviço padrão, ela deverá ter as permissões descritas em Funções e Permissões. Para obter mais informações sobre a abordagem do Google Cloud para autenticação, consulte Visão geral da autenticação .
Criar uma conta de serviço
- No Google Cloud console, vá para a página Contas de serviço .
- Selecione o projeto que contém sua instância do Cloud SQL.
- Clique em Criar conta de serviço .
- No campo Nome da conta de serviço , insira um nome descritivo para a conta de serviço.
- Altere o ID da conta de serviço para um valor exclusivo e reconhecível e clique em Criar e continuar .
- Clique no campo Selecionar uma função e selecione uma das seguintes funções:
- Cloud SQL > Cliente Cloud SQL
- Cloud SQL > Editor do Cloud SQL
- Cloud SQL > Administração do Cloud SQL
- Clique em Concluído para finalizar a criação da conta de serviço.
- Clique no menu de ação da sua nova conta de serviço e selecione Gerenciar chaves .
- Clique no menu suspenso Adicionar chave e depois clique em Criar nova chave .
- Confirme se o tipo de chave é JSON e clique em Criar .
O arquivo da chave privada será baixado para sua máquina. Você pode movê-lo para outro local. Mantenha o arquivo da chave seguro.
Use o Cloud SQL Auth Proxy com IP privado
Para se conectar a uma instância do Cloud SQL usando IP privado, o Cloud SQL Auth Proxy deve estar em um recurso com acesso à mesma rede VPC que a instância.
O Proxy de Autenticação do Cloud SQL usa IP para estabelecer uma conexão com sua instância do Cloud SQL. Por padrão, o Proxy de Autenticação do Cloud SQL tenta se conectar usando um endereço IPv4 público.
Se sua instância do Cloud SQL tiver apenas IP privado ou se a instância tiver IP público e privado configurados, e você quiser que o Cloud SQL Auth Proxy use o endereço IP privado, forneça a seguinte opção ao iniciar o Cloud SQL Auth Proxy:
--private-ip
Use o Cloud SQL Auth Proxy com instâncias que tenham o Private Service Connect habilitado
Você pode usar o Cloud SQL Auth Proxy para se conectar a uma instância do Cloud SQL com o Private Service Connect habilitado.
O Cloud SQL Auth Proxy é um conector que fornece acesso seguro a esta instância sem a necessidade de redes autorizadas ou de 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 fornecido para a instância. O registro DNS é um mapeamento entre um recurso DNS e um nome de domínio.
Para obter mais informações sobre como usar o Cloud SQL Auth Proxy para se conectar a instâncias com o Private Service Connect habilitado, consulte Conectar usando o Cloud SQL Auth Proxy .
Execute o Cloud SQL Auth Proxy 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 abaixo para invocar o Proxy de Autenticação do Cloud SQL em um processo separado.
Linux
No Linux ou macOS, use um &
final na linha de comando para iniciar o Cloud SQL Auth Proxy 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 Cloud SQL Auth Proxy em um processo separado:
Start-Process --filepath "cloud-sql-proxy.exe"
--ArgumentList "
--credentials-file PATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"
Execute o Cloud SQL Auth Proxy em um contêiner do Docker
Para executar o Cloud SQL Auth Proxy em um contêiner do Docker, use a imagem do Docker do Cloud SQL Auth Proxy disponível no Google Container Registry . Você pode instalar a imagem do Docker do Cloud SQL Auth Proxy usando o seguinte comando:
docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.16.0
Você pode iniciar o Cloud SQL Auth Proxy 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.16.0 \ --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.16.0 --unix-socket /cloudsql \ --credentials-file /path/to/service-account-key.json/PATH_TO_KEY_FILE \ INSTANCE_CONNECTION_NAME
Se você estiver usando uma imagem otimizada para contêiner, use um diretório gravável no lugar de /cloudsql
, por exemplo:
v /mnt/stateful_partition/cloudsql:/cloudsql
Se você estiver usando as credenciais fornecidas pela sua 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
.
Executando o Cloud SQL Auth Proxy como um serviço
Executar o Cloud SQL Auth Proxy como um serviço em segundo plano é uma opção para cargas de trabalho de desenvolvimento e produção locais. Em desenvolvimento, quando você precisa acessar sua instância do Cloud SQL, pode iniciar o serviço em segundo plano e interrompê-lo ao concluir.
Para cargas de trabalho de produção, o Cloud SQL Auth Proxy não oferece suporte integrado para execução como um serviço do Windows, mas gerenciadores de serviços de terceiros podem ser usados para executá-lo como um serviço. Por exemplo, você pode usar o NSSM para configurar o Cloud SQL Auth Proxy como um serviço do Windows, e o NSSM monitora o Cloud SQL Auth Proxy e o reinicia automaticamente se ele parar de responder. Consulte a documentação do NSSM para obter mais informações.
Aplicar o uso do Cloud SQL Auth Proxy
Habilite o uso do Cloud SQL Auth Proxy no Cloud SQL usando ConnectorEnforcement .
Se você estiver usando uma instância habilitada para Private Service Connect , haverá uma limitação. Se a instância tiver a imposição do conector habilitada, 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 habilitar a imposição do conector para ela.
gcloud
O comando a seguir impõe o uso de conectores do Cloud SQL.
gcloud sql instances patch INSTANCE_NAME \ --connector-enforcement REQUIRED
Para desabilitar 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 impõe o uso de conectores do Cloud SQL
Antes de usar qualquer um dos dados solicitados, faça as seguintes substituições:
- 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 sua solicitação, expanda uma destas opções:
Você deve receber uma resposta JSON semelhante à seguinte:
{ "kind": "sql#operation", "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id", "status": "PENDING", "user": "[email protected]", "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 desabilitar a imposição, use "connectorEnforcement": "NOT_REQUIRED"
. A atualização não aciona uma reinicialização.
REST v1beta4
O comando a seguir impõe o uso de conectores do Cloud SQL.
Antes de usar qualquer um dos dados solicitados, faça as seguintes substituições:
- 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 sua solicitação, expanda uma destas opções:
Você deve receber uma resposta JSON semelhante à seguinte:
{ "kind": "sql#operation", "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id", "status": "PENDING", "user": "[email protected]", "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 desabilitar a imposição, use "connectorEnforcement": "NOT_REQUIRED"
. A atualização não aciona uma reinicialização.
Dicas para trabalhar com o Cloud SQL Auth Proxy
Invocar o proxy de autenticação do Cloud SQL
Todas as invocações de proxy de exemplo iniciam o Cloud SQL Auth Proxy em segundo plano, portanto, um prompt é retornado. Reserve esse terminal do Cloud Shell para o Cloud SQL Auth Proxy, para evitar que sua saída seja misturada com a saída de outros programas. Além disso, a saída do Cloud SQL Auth Proxy pode ajudar a diagnosticar problemas de conexão, portanto, pode ser útil capturá-la em um arquivo de log. Se você não iniciar o Cloud SQL Auth Proxy em segundo plano, a saída será direcionada para stdout, a menos que seja redirecionada.
Você não precisa usar /cloudsql
como diretório para os soquetes do Cloud SQL Auth Proxy. (Esse nome de diretório foi escolhido para minimizar as diferenças com as strings de conexão do App Engine.) Se você alterar o nome do diretório, no entanto, mantenha o comprimento total no mínimo; ele é incorporado em uma string mais longa, com um limite de comprimento imposto pelo sistema operacional. Depende do sistema, mas geralmente tem entre 91 e 108 caracteres. No Linux, o comprimento geralmente é definido como 108, e você pode usar o seguinte comando para verificar:
cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"
Use o Cloud SQL Auth Proxy para se conectar a várias instâncias
Você pode usar um cliente proxy de autenticação local do Cloud SQL para se conectar a várias instâncias do Cloud SQL. A maneira como você faz isso depende se você está usando soquetes Unix ou TCP.
Soquetes Unix
Para conectar o Proxy de Autenticação do Cloud SQL a várias instâncias, forneça o nome de conexão de cada instância como um argumento para o Proxy de Autenticação do Cloud SQL, em uma lista separada por espaços. O Proxy de Autenticação do Cloud SQL se conecta a cada instância ao ser iniciado.
Você se conecta a cada instância usando seu soquete, no diretório especificado.
Por 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 via TCP, você especifica uma porta na sua máquina para o Proxy de Autenticação do Cloud SQL escutar cada instância do Cloud SQL. Ao se conectar a várias instâncias do Cloud SQL, cada porta especificada deve ser exclusiva e estar disponível para uso na sua máquina.
Por 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
Solucionar problemas de conexões do Cloud SQL Auth Proxy
A imagem do Docker do Cloud SQL Auth Proxy é baseada em uma versão específica do Cloud SQL Auth Proxy. Quando uma nova versão do Cloud SQL Auth Proxy estiver disponível, extraia a nova versão da imagem do Docker do Cloud SQL Auth Proxy para manter seu ambiente atualizado. Você pode ver a versão atual do Cloud SQL Auth Proxy consultando a página de lançamentos do Cloud SQL Auth Proxy no GitHub .
Se você estiver tendo problemas para se conectar à sua instância do Cloud SQL usando o Cloud SQL Auth Proxy, aqui estão algumas coisas que você pode tentar fazer para descobrir a causa do problema.
Verifique se você está usando o endereço IP para se conectar à instância, e não o ponto de extremidade de gravação .
Verifique a saída do Cloud SQL Auth Proxy.
Muitas vezes, a saída do Proxy de Autenticação do Cloud SQL pode ajudar a determinar a origem do problema e como resolvê-lo. Envie a saída para um arquivo ou observe o terminal do Cloud Shell onde 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 Cloud SQL Auth Proxy, verifique se a conta de serviço tem as permissões corretas.Você pode verificar a conta de serviço pesquisando seu ID na página do IAM . Ela deve ter a permissão
cloudsql.instances.connect
. As funções predefinidasCloud SQL Admin
,Client
eEditor
do Cloud SQL têm essa permissão.Se você estiver se conectando pelo App Engine e receber o erro
403 notAuthorized
, verifique o valorcloud_sql_instances
app.yaml
para ver se há um nome de conexão de instância incorreto ou com erro de ortografia. Os nomes de conexão de instância estão sempre no formatoPROJECT:REGION:INSTANCE
.Além disso, verifique se a conta de serviço do App Engine (por exemplo, [email protected]) tem a função IAM do cliente Cloud SQL.
Se o serviço do App Engine residir em um projeto (projeto A) e o banco de dados residir em outro (projeto B), esse erro significa que a conta de serviço do App Engine não recebeu a função IAM do cliente do Cloud SQL no projeto com o banco de dados (projeto B).
Certifique-se de habilitar a API de administração do Cloud SQL.
Caso contrário, você verá uma saída como
Error 403: Access Not Configured
nos seus logs do Cloud SQL Auth Proxy.Se você estiver incluindo várias instâncias na sua lista de instâncias, certifique-se de usar uma vírgula como delimitador, sem espaços. Se estiver usando TCP, certifique-se de especificar portas diferentes para cada instância.
Se você estiver se conectando usando soquetes UNIX, confirme se os soquetes foram criados listando o diretório fornecido quando iniciou o Cloud SQL Auth Proxy.
Se você tiver uma política de firewall de saída, certifique-se de que ela permita conexões à porta 3307 na instância de destino do Cloud SQL.
Você pode confirmar se o Cloud SQL Auth Proxy foi iniciado corretamente observando os logs na seção Operações > Registro > Explorador de logs doGoogle Cloud console. Uma operação bem-sucedida se parece com o seguinte:
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 de administração do Cloud SQL é violada, o Cloud SQL Auth Proxy é 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
Quando um aplicativo se conecta ao proxy, o proxy relata 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 incorretamente e criando novas conexões desnecessariamente) ou entre em contato com o suporte para solicitar um aumento na cota da API de administração do Cloud SQL. Se o erro de cota aparecer na inicialização, você deverá reimplantar o aplicativo para reiniciar o proxy. Se o erro de cota aparecer após a inicialização, a reimplantação não será necessária.
O que vem a seguir
- Saiba mais sobre o Cloud SQL Auth Proxy .
- Saiba mais sobre Gerenciamento de Identidade e Acesso (IAM) .
- 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 à sua instância a partir do seu aplicativo .
- Saiba mais sobre o cliente psql .
- Saiba mais sobre opções de suporte .