Conectar-se usando o proxy de autenticação do Cloud SQL

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.

      Acessar a página IAM

    • 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.
  1. Enable the Cloud SQL Admin API.

    Enable the API

  2. Instale e inicialize a gcloud CLI.
  3. 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

  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.11.2/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.11.2/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.11.2/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.11.2/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.11.2/cloud-sql-proxy.x64.exe e selecione Salvar link como para baixar o proxy do Cloud SQL Auth. 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.11.2/cloud-sql-proxy.x86.exe e selecione Salvar link como para baixar o proxy do Cloud SQL Auth. 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.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
  1. 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.

  2. 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
  3. 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.
  4. 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:
      ./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
      A porta especificada não pode estar em uso, por exemplo, por um servidor de banco de dados local.
    • 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.

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.

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

  2. Crie o diretório onde ficarão os soquetes do proxy de autenticação do Cloud SQL:
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  3. 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.
  4. 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.

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

  1. 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.
  2. 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

  1. 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 como disable, 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.

  2. Se solicitado, digite a senha.
  3. O prompt do psql é exibido.

Como usar soquetes Unix

  1. 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 como disable, o proxy de autenticação do Cloud SQL fornece uma conexão criptografada.

  2. Digite a senha.
  3. 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:

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

  2. Credenciais fornecidas por um token de acesso.

    Crie um token de acesso e invoque o comentário cloud-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
      
  3. 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 ambiente GOOGLE_APPLICATION_CREDENTIALS em vez de usar o argumento de linha de comando --credentials-file.
  4. 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
  5. 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.

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

  1. No Console do Google Cloud, acesse a página Contas de serviço.

    Acessar Contas de serviço

  2. Selecione o projeto que contém a instância do Cloud SQL.
  3. Clique em Criar conta de serviço.
  4. Preencha o campo Nome da conta de serviço.
  5. Altere o ID da conta de serviço para um valor exclusivo e facilmente reconhecível, depois clique em Criar e continuar.
  6. 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
  7. Clique em Concluído para terminar a criação da conta de serviço.
  8. Clique no menu de ações da sua nova conta de serviço e selecione Gerenciar chaves.
  9. Clique no menu suspenso Adicionar chave e clique em Criar nova chave.
  10. 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.

Uso de descoberta automática da instância com credenciais gcloud CLI:
    ./cloud-sql-proxy --unix-socket /cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
 
Como usar a descoberta do projeto com credenciais gcloud CLI:
    ./cloud-sql-proxy --unix-socket /cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
Para uma instância do Compute Engine, com especificação explícita da instância:
    ./cloud-sql-proxy --unix-socket /cloudsql myProject:us-central1:myInstance &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
Para Unix, uso de TCP:
    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" &
    psql -U myUser -h 127.0.0.1
Para Windows (no prompt da linha de comando):
    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 predefinidos Cloud SQL Admin, Client e Editor têm essa permissão.

  • Se você estiver se conectando a partir do App Engine e estiver recebendo um erro 403 notAuthorized, verifique a cloud_sql_instances valor app.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 formato PROJECT: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