Autorização com o Proxy do Cloud SQL

Nesta página, você verá como autorizar uma conexão do Cloud SQL Proxy. Para informações sobre como se conectar às instâncias do Cloud SQL usando o proxy, consulte Visão geral da conexão. Para informações detalhadas sobre como o proxy funciona e dicas para trabalhar com ele, consulte Sobre o Cloud SQL Proxy.

O Cloud SQL Proxy processa a autenticação com o Cloud SQL, fornecendo acesso seguro a instâncias do Cloud SQL sem a necessidade de gerenciar endereços IP permitidos ou configurar conexões SSL.

Antes de começar

Como instalar o Cloud SQL Proxy

O Cloud SQL Proxy é distribuído como um download gratuito, com executáveis pré-compilados disponíveis para plataformas Linux, macOS e Windows de 32 e 64 bits.

Linux de 64 bits

  1. Faça o download do proxy:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. Torne o proxy executável:
    chmod +x cloud_sql_proxy
    

Linux de 32 bits

  1. Faça o download do proxy:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. Torne o proxy executável:
    chmod +x cloud_sql_proxy
    

macOS de 64 bits

  1. Faça o download do proxy:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. Torne o proxy executável:
    chmod +x cloud_sql_proxy
    

macOS de 32 bits

  1. Faça o download do proxy:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. Torne o proxy executável:
    chmod +x cloud_sql_proxy
    

Windows de 64 bits

Para fazer o download do proxy, clique com o botão direito em https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe e selecione Salvar link como. Renomeie o arquivo para cloud_sql_proxy.exe.

Windows de 32 bits

Para fazer o download do proxy, clique com o botão direito em https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe e selecione Salvar link como. Renomeie o arquivo para cloud_sql_proxy.exe.
Caso seu sistema operacional não esteja incluído aqui, compile o proxy a partir da fonte.

Como ativar a API e definir permissões

O Cloud SQL Proxy usa as permissões do IAM de um usuário ou conta de serviço para autenticar sua conexão com uma instância do Cloud SQL.

  1. Ative a API Cloud SQL Admin.

    Ative a API

  2. Adicione um ou mais dos papéis do IAM necessários à sua conta de usuário ou serviço:

    • Cloud SQL Client (recomendável)
    • Cloud SQL Editor
    • Cloud SQL Admin

    Também é possível atribuir manualmente as seguintes permissões do IAM:

    • cloudsql.instances.connect
    • cloudsql.instances.get

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.

Para mais informações sobre os papéis compatíveis com o Cloud SQL, consulte Controle de acesso do projeto para o Cloud SQL.

Como usar credenciais do Cloud SQL Proxy

Antes de iniciar o Cloud SQL Proxy, você precisa fornecer credenciais de usuário ou conta de serviço que o proxy possa usar para autenticar uma conexão. Há várias opções para especificar quais credenciais são usadas, e o proxy verifica cada opção na seguinte ordem:

Todas essas opções usam um INSTANCE_CONNECTION_NAME como a string de conexão para identificar uma instância do Cloud SQL. A string de conexão está no formato PROJECT_ID:REGION:INSTANCE_ID. Encontre a string de conexão da instância listada na página de visão geral da instância.

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. Se você precisar criar um novo arquivo de credenciais, acesse a página Contas de serviço do projeto no Console do Cloud, clique em Ações para a conta de serviço e selecione Criar chave para fazer o download de um arquivo de credenciais JSON para a conta de serviço.

Arquivo de credenciais na linha de comando

Para usar essa opção, chame o comando cloud_sql_proxy com a sinalização -credential_file definida como o caminho e o nome de arquivo de uma credencial JSON. O caminho pode ser absoluto ou relativo ao diretório de trabalho atual. Exemplo:

./cloud_sql_proxy -credential_file=PATH_TO_KEY_FILE -instances=INSTANCE_CONNECTION_NAME

Token de acesso na linha de comando

Os tokens de acesso são normalmente usados para autorizar o acesso em nome de uma conta de usuário. Para mais informações sobre como criar e usar tokens de acesso do OAuth 2.0, consulte Autorizar solicitações.

Para usar essa opção, chame o comentário cloud_sql_proxy com a sinalização -token definida como um token de acesso do OAuth 2.0. Exemplo:

./cloud_sql_proxy -token=ACCESS_TOKEN -instances=INSTANCE_CONNECTION_NAME

Arquivo de credencial de uma variável de ambiente

Essa opção é semelhante a usar a sinalização -credential_file, mas você especifica o arquivo de credencial JSON na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS em vez de usar o argumento de linha de comando -credential_file.

Credenciais de usuário do SDK do Cloud

Se você tiver instalado a ferramenta de linha de comando gcloud e autenticado com sua conta pessoal, o Cloud SQL Proxy poderá usar as mesmas credenciais da conta. Esse método é especialmente útil para colocar um ambiente para desenvolvedores em funcionamento. Para um ambiente de produção, use um dos outros métodos de autenticação.

Para autenticar o SDK do Cloud, use o comando gcloud auth login, selecione sua conta e faça login. Use o comando gcloud auth list para verificar qual conta está autenticada no SDK do Cloud.

Se nenhuma conta foi selecionada para gcloud auth login, o proxy verifica se há uma conta selecionada para gcloud application-default login.

Conta de serviço padrão do ambiente

Se o proxy não conseguir encontrar credenciais em nenhum dos locais cobertos anteriormente, ele segue 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. Se você usa uma conta de serviço padrão, ela precisa ter as permissões descritas em Como ativar a API e definir permissões.

Para mais informações sobre a abordagem de autenticação do Google Cloud, consulte Visão geral da autenticação.

Como executar o Cloud SQL Proxy

O binário de 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 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.

Veja abaixo exemplos de uso da linha de comando do Cloud SQL Proxy.

Como configurar o TCP

Para se conectar a uma instância do Cloud SQL com TCP, use o argumento de linha de comando -instances para especificar uma lista de strings de conexão separadas por vírgulas, conforme mostrado neste exemplo de porta TCP:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER

Para conexões TCP, o proxy detecta em localhost (127.0.0.1) por padrão. Portanto, quando você especifica =tcp: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 detectar a conexão local em 0.0.0.0:1234:

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234

Para se conectar a várias instâncias, use o Cloud SQL Proxy especificando uma lista separada por vírgulas de nomes de conexão de instância no argumento -instances. Cada instância precisa ter seu próprio número de porta, conforme mostrado neste exemplo:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME_1=tcp:1433,INSTANCE_CONNECTION_NAME_2=tcp:1434

Como configurar um soquete Unix

O Cloud SQL Proxy também pode detectar em um soquete Unix, que é um mecanismo padrão do Posix para usar uma pasta para 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 e o aplicativo precisam ter acesso de leitura e gravação a ele. Para criar um novo diretório e definir as permissões necessárias, use estes comandos:

sudo mkdir ~/cloudsql
sudo chmod a+rw ~/cloudsql

Há duas opções para especificar o diretório do soquete ao iniciar o proxy. Uma opção é usar o argumento de linha de comando -dir, conforme mostrado aqui:

./cloud_sql_proxy -dir=PATH_TO_TARGET_FOLDER -instances=INSTANCE_CONNECTION_NAME

Como alternativa, você pode anexar o diretório do soquete ao argumento da string de conexão:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=unix:/PATH_TO_TARGET_FOLDER

Como escolher IP público ou particular

As instâncias do Cloud SQL usam conectividade de IP público por padrão, mas também é possível configurar uma instância para ser compatível com conectividade de IP particular. O IP particular usa endereços IP internos hospedados em uma rede VPC, que só podem ser acessados a partir de outros recursos dentro da mesma rede VPC. Os benefícios do IP particular incluem maior segurança, porque o tráfego IP nunca é exposto à Internet e melhor desempenho, porque o IP particular oferece menor latência do que o IP público em alguns cenários.

Para configurar sua instância do Cloud SQL para usar IP particular, consulte Como configurar o IP particular.

A sinalização de linha de comando -ip_address_types do proxy especifica a ordem preferencial de IP usada ao se conectar a uma instância do Cloud SQL. A configuração padrão é -ip_address_types=PUBLIC,PRIVATE, o que significa que o proxy tentará se conectar com o IP público primeiro se a instância tiver o IP público ativado e, em seguida, o proxy tentará se conectar com o IP particular se a instância tiver o IP particular ativado. Para especificar que o proxy tente se conectar apenas com o IP particular, use a sinalização -ip_address_types=PRIVATE, conforme mostrado neste exemplo:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:1433 -ip_address_types=PRIVATE

Outros argumentos de linha de comando

Os exemplos acima abrangem os casos de uso mais comuns, mas o Cloud SQL Proxy 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 Cloud SQL Proxy no GitHub (em inglês) para ver outros exemplos de como usar as opções de linha de comando do Cloud SQL Proxy.

Mais informações

Como executar o proxy em um processo separado

Executar o Cloud SQL Proxy em um processo de terminal separado 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 em um processo separado.

Linux

No Linux ou no macOS, use um & à direita na linha de comando para iniciar o proxy em um processo separado:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE &

Windows

No Windows PowerShell, use o comando Start-Process para iniciar o proxy em um processo separado:

Start-Process -filepath "cloud_sql_proxy.exe"
  -ArgumentList "-instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE"

Como executar o Cloud SQL Proxy em um contêiner do Docker

Para executar o Cloud SQL Proxy em um contêiner do Docker, use a imagem do Proxy Docker disponível no Google Container Registry. Você pode instalar a imagem do Proxy Docker com este comando gcloud:

docker pull gcr.io/cloudsql-docker/gce-proxy:1.16

Você pode iniciar o proxy usando soquetes TCP ou soquetes Unix, com os comandos mostrados abaixo.

Soquetes TCP

docker run -d \
  -v PATH_TO_KEY_FILE:/config \
  -p 127.0.0.1:1433:1433 \
  gcr.io/cloudsql-docker/gce-proxy:1.16 /cloud_sql_proxy \
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1433 \
  -credential_file=/config

Soquetes Unix

docker run -d \
  -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
  -v PATH_TO_KEY_FILE:/config \
  gcr.io/cloudsql-docker/gce-proxy:1.16 /cloud_sql_proxy -dir=/cloudsql \
  -instances=INSTANCE_CONNECTION_NAME
  -credential_file=/config/PATH_TO_KEY_FILE

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:/config</span>.

Como executar o Cloud SQL Proxy como um serviço

Executar o proxy como um serviço em segundo plano pode ser conveniente para desenvolvimento e teste locais. Quando você precisar acessar sua instância do Cloud SQL, poderá iniciar o serviço em segundo plano e interrompê-lo quando terminar.

Windows

No momento, o Cloud SQL Proxy não é compatível com a execução como um serviço do Windows, mas os gerenciadores de serviço de terceiros podem ser usados para executá-lo como um serviço. Por exemplo, você pode usar o NSSM (em inglês) para configurar o proxy como um serviço do Windows, e o NSSM monitora o proxy e o reinicia automaticamente se ele parar de responder. Consulte a documentação do NSSM para mais informações.

A seguir