Conectar a partir do Compute Engine

Nesta página, descrevemos como usar o cliente psql, instalado em uma instância do Compute Engine, para se conectar ao Cloud SQL.

É possível usar IP particular, IP público, o proxy de autenticação do Cloud SQL ou a imagem Docker do proxy de autenticação do Cloud SQL.

Para instruções detalhadas sobre como executar um aplicativo da Web de amostra do Compute Engine conectado ao Cloud SQL, consulte o guia de início rápido para se conectar do Compute Engine

Antes de começar

Essa tarefa não inclui instruções para a configuração da instância do Google Compute Engine. Se você precisar de ajuda para criar e configurar uma instância do Google Compute Engine, consulte a documentação do Google Compute Engine.

IP particular

Para se conectar ao Cloud SQL por uma instância do Compute Engine usando IP particular, o acesso a serviços particulares precisa ser configurado para o ambiente, e a instância do Cloud SQL precisa ser configurada para usar IP particular. A instância do Compute Engine precisa estar na mesma região da instância do Cloud SQL e na rede configurada para uma conexão particular. Saiba mais.

1. Configure a instância para usar IP privado

Siga as instruções em Como configurar a conectividade do IP privado.

2. Abrir uma conexão de terminal do Cloud Shell com a instância do Compute Engine.

Use as instruções apropriadas, dependendo do sistema operacional da instância:

Se a instância do Compute Engine estiver executando uma imagem pública do RHEL ou do CentOS, o SELinux poderá bloquear a conexão de proxy. Se isso acontecer, será necessário configurar o recurso SELinux para permitir a conexão.

Para mais informações sobre o SELinux para RHEL, consulte a documentação do RHEL (em inglês). Para mais informações sobre o SELinux para CentOS, consulte a documentação do CentOS (em inglês).

3. Instale o cliente psql na instância do Compute Engine, se ele ainda não estiver instalado.

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.

4. Estabeleça conexão com o cliente psql.

psql -h CLOUD_SQL_PRIVATE_IP_ADDRESS -U USERNAME

É possível encontrar o endereço IP privado na página de instâncias do Cloud SQL ou executando o seguinte comando gcloud:

gcloud sql instances list

IP público

Para se conectar usando IP público:

1. Adicione um endereço IPv4 estático à instância do Compute Engine, se ela ainda não tiver um.

Não é possível estabelecer uma conexão com o Compute Engine usando IPv6. Para informações sobre como adicionar um endereço IP estático, consulte Como reservar um novo endereço IP externo estático na documentação do Compute Engine.

2. Autorize o endereço IP estático da instância do Compute Engine como uma rede com permissão para conectar-se à instância do Cloud SQL.

Para mais informações, consulte Como configurar o acesso para conexões IP públicas.

3. Abrir uma conexão de terminal do Cloud Shell com a instância do Compute Engine.

Use as instruções apropriadas, dependendo do sistema operacional da instância:

Se a instância do Compute Engine estiver executando uma imagem pública do RHEL ou do CentOS, o SELinux poderá bloquear a conexão de proxy. Se isso acontecer, será necessário configurar o recurso SELinux para permitir a conexão.

Para mais informações sobre o SELinux para RHEL, consulte a documentação do RHEL (em inglês). Para mais informações sobre o SELinux para CentOS, consulte a documentação do CentOS (em inglês).

4. Instale o cliente psql na instância do Compute Engine, se ele ainda não estiver instalado.

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.

5. Estabeleça conexão com o cliente psql.

psql -h CLOUD_SQL_PUBLIC_IP_ADDR -U USERNAME

É possível encontrar o endereço IP privado na página de instâncias do Cloud SQL ou executando o seguinte comando gcloud:

gcloud sql instances list

Para um exemplo de como estabelecer uma conexão usando SSL, consulte Como se conectar com SSL.

6. O prompt do psql é exibido.

7. Se você precisar manter as conexões não utilizadas ativas:

Configure o TCP keepalive.

Para mais informações, consulte Como estabelecer comunicação entre as suas instâncias e a Internet na documentação do Compute Engine.

As conexões são mantidas ativas automaticamente para instâncias.

Proxy do Cloud SQL Auth

Para se conectar usando o proxy de autenticação do Cloud SQL por meio do Compute Engine:

1. Ative a API Cloud SQL Admin.

Enable the API

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

Se a instância do Google Compute Engine estiver em um projeto diferente da instância do Cloud SQL, verifique se a respectiva conta de serviço tem as permissões adequadas no projeto que contém a instância do Cloud SQL:

  1. Acesse a listagem de instâncias do Compute Engine no Console do Google Cloud.

    Acessar a listagem de instâncias do Compute Engine

  2. Se necessário, selecione o projeto associado à instância do Compute Engine.
  3. Selecione a instância do Compute Engine para exibir as propriedades dela.
  4. Nas propriedades da instância do Compute Engine, copie o nome da conta de serviço.
  5. Acesse a página Projetos do IAM e do administrador no Console do Google Cloud.

    Acessar a página "Projetos do IAM e do administrador"

  6. Selecione o projeto que contém a instância do Cloud SQL.
  7. Procure o nome da conta de serviço.

  8. Se a conta de serviço já estiver lá e tiver um papel que inclua a permissão cloudsql.instances.connect, prossiga para a etapa 4.

    Os papéis Cloud SQL Client, Cloud SQL Editor e Cloud SQL Admin fornecem a permissão necessária, assim como os papéis de projeto Editor e Owner herdados.

  9. Caso contrário, clique em Adicionar para adicioná-la.

  10. Na caixa de diálogo Adicionar membros , forneça o nome da conta de serviço e selecione uma função que inclua a permissão cloudsql.instances.connect (qualquer papel predefinido do Cloud SQL que não seja o Leitor funcionará).

    Como alternativa, é possível usar o papel básico de Editor ao selecionar Projeto > Editor. No entanto, ele inclui permissões em todo o Google Cloud.

    Caso não veja esses papéis, talvez o usuário do Google Cloud não tenha a permissão resourcemanager.projects.setIamPolicy. Para verificar suas permissões, acesse a página do IAM no Console do Google Cloud e pesquise seu ID de usuário.

  11. Clique em Adicionar.

    Você verá a conta de serviço listada com o papel especificado.

3. Abra uma conexão de terminal com a instância do Compute Engine.

Use as instruções apropriadas, dependendo do sistema operacional da instância:

Se a instância do Compute Engine estiver executando uma imagem pública do RHEL ou do CentOS, o SELinux poderá bloquear a conexão de proxy. Se isso acontecer, será necessário configurar o recurso SELinux para permitir a conexão.

Para mais informações sobre o SELinux para RHEL, consulte a documentação do RHEL (em inglês). Para mais informações sobre o SELinux para CentOS, consulte a documentação do CentOS (em inglês).

4. Instale o cliente psql na instância do Compute Engine, se ele ainda não estiver instalado.

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.

5. Instale o proxy de autenticação do Cloud SQL na instância do Compute Engine.

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.14.1/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.14.1/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

Windows de 64 bits

Clique com o botão direito do mouse em https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.14.1/cloud-sql-proxy.x64.exe e selecione Salvar link como para fazer o download do proxy de autenticação do Cloud SQL. Renomeie o arquivo 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.14.1/cloud-sql-proxy.x86.exe e selecione Salvar link como para fazer o download do proxy de autenticação do Cloud SQL. Renomeie o arquivo 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.14.1

Outros SOs

Para outros sistemas operacionais não incluídos aqui, compile o proxy do Cloud SQL Auth a partir do código-fonte.

6. Inicie o proxy de autenticação do Cloud SQL.

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 para autenticar o proxy de autenticação do Cloud SQL.

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

    • Usando a autenticação do SDK Google Cloud: 
      ./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 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 para autenticar o proxy de autenticação do Cloud SQL.

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.14.1 \\
  --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.14.1 --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.

7. Inicie a sessão psql.

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.

A seguir