Conectar do Compute Engine

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

Você pode usar IP privado, IP público, o Cloud SQL Auth Proxy ou a imagem do Docker do Cloud SQL Auth Proxy.

Para obter instruções passo a passo sobre como executar um aplicativo Web de exemplo do Compute Engine conectado ao Cloud SQL, consulte o início rápido para conexão do Compute Engine .

Antes de começar

Esta tarefa não inclui instruções para configurar sua instância do Compute Engine. Se precisar de ajuda para criar e configurar uma instância do Compute Engine, consulte a documentação do Compute Engine .

IP privado

Para se conectar ao Cloud SQL a partir de uma instância do Compute Engine usando um IP privado, o acesso a serviços privados deve ser configurado para o seu ambiente e sua instância do Cloud SQL deve ser configurada para usar um IP privado. Sua instância do Compute Engine deve estar na mesma região que sua instância do Cloud SQL e na rede configurada para uma conexão privada. Saiba mais .

1. Configure sua instância para usar IP privado

Use as instruções em Configurando conectividade IP privada .

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

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

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

Para obter mais informações sobre o SELinux para RHEL, consulte a documentação do RHEL . Para obter mais informações sobre o SELinux para CentOS, consulte a documentação do CentOS .

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

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 do gerenciador de pacotes:

sudo yum install postgresql

openSUSE

Instale o cliente psql do gerenciador de pacotes:

sudo zypper install postgresql

Outras plataformas

  1. 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.
  2. Instale o banco de dados PostgreSQL seguindo as instruções na página de download.

4. Conecte-se ao cliente psql. 

psql -h CLOUD_SQL_PRIVATE_IP_ADDRESS -U USERNAME

Você pode 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 conectar usando IP público:

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

Não é possível se conectar ao Compute Engine usando IPv6. Para obter informações sobre como adicionar um endereço IP estático, consulte "Reservando 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 que pode se conectar à sua instância do Cloud SQL.

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

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

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

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

Para obter mais informações sobre o SELinux para RHEL, consulte a documentação do RHEL . Para obter mais informações sobre o SELinux para CentOS, consulte a documentação do CentOS .

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

  1. 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.
  2. Instale o banco de dados PostgreSQL seguindo as instruções na página de download.

5. Conecte-se com o cliente psql. 

psql -h CLOUD_SQL_PUBLIC_IP_ADDR -U USERNAME

Você pode encontrar o endereço IP público na página de instâncias do Cloud SQL ou executando o seguinte comando gcloud : 

gcloud sql instances list

Para um exemplo de como se conectar usando SSL, consulte Conectando com SSL .

6. O prompt do psql é exibido.

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

Defina o TCP keepalive .

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

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

Proxy de autenticação do Cloud SQL

Para conectar usando o Cloud SQL Auth Proxy do Compute Engine:

1. Habilite a API de administração do Cloud SQL.

Enable the API

2. Crie uma conta de serviço.

  1. No Google Cloud console, vá para a página Contas de serviço .

    Ir para contas de serviço

  2. Selecione o projeto que contém sua instância do Cloud SQL.
  3. Clique em Criar conta de serviço .
  4. No campo Nome da conta de serviço , insira um nome descritivo para a conta de serviço.
  5. Altere o ID da conta de serviço para um valor exclusivo e reconhecível e clique em Criar e continuar .
  6. 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

  7. Clique em Concluído para finalizar a criação da conta de serviço.
  8. Clique no menu de ação da sua nova conta de serviço e selecione Gerenciar chaves .
  9. Clique no menu suspenso Adicionar chave e depois clique em Criar nova chave .
  10. 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.

Se a instância do Compute Engine estiver em um projeto diferente da instância do Cloud SQL, certifique-se de que sua conta de serviço tenha 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 em Google Cloud console.

    Acesse 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 suas propriedades.
  4. Nas propriedades da instância do Compute Engine, copie o nome da conta de serviço.
  5. Acesse a página Projetos IAM e Admin no Google Cloud console.

    Acesse a página Projetos do IAM e Admin

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

  8. Se a conta de serviço já estiver lá e tiver uma função que inclua a permissão cloudsql.instances.connect , você poderá prosseguir para a etapa 4 .

    As funções Cloud SQL Client , Cloud SQL Editor e Cloud SQL Admin fornecem a permissão necessária, assim como as funções de Editor e Owner do projeto legado.

  9. Caso contrário, adicione a conta de serviço clicando em Adicionar .

  10. Na caixa de diálogo Adicionar principais , forneça o nome da conta de serviço e selecione uma função que inclua a permissão cloudsql.instances.connect (qualquer função predefinida do Cloud SQL diferente de Visualizador funcionará).

    Como alternativa, você pode usar a função básica de Editor selecionando Projeto > Editor , mas a função de Editor inclui permissões em Google Cloud.

    Se você não vê essas funções, seu Google Cloud O usuário pode não ter a permissão resourcemanager.projects.setIamPolicy . Você pode verificar suas permissões acessando a página do IAM no Google Cloud console e procurando seu ID de usuário.

  11. Clique em Adicionar .

    Agora você vê a conta de serviço listada com a função especificada.

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

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

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

Para obter mais informações sobre o SELinux para RHEL, consulte a documentação do RHEL . Para obter mais informações sobre o SELinux para CentOS, consulte a documentação do CentOS .

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

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

  1. 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.
  2. Instale o banco de dados PostgreSQL seguindo as instruções na página de download.

5. Instale o Cloud SQL Auth Proxy na instância do Compute Engine.

Linux de 64 bits

  1. 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
  2. Torne o Cloud SQL Auth Proxy executável: 
    chmod +x cloud-sql-proxy

Linux 32 bits

  1. 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
  2. Se o comando curl não for encontrado, execute sudo apt install curl e repita o comando de download.
  3. 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 para cloud-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 para cloud-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 .

6. Inicie o Cloud SQL Auth Proxy.

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

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

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

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.

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

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

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.

7. Inicie a sessão psql.

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

  1. Inicie o cliente psql:
    psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"

    Embora o parâmetro sslmode esteja definido como disable , 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 .

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

Usando soquetes Unix

  1. Inicie o cliente psql:
    psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"

    Embora o parâmetro sslmode esteja definido como disable , o Cloud SQL Auth Proxy fornece uma conexão criptografada.

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

O que vem a seguir