Como conectar o cliente do SQL Server usando a imagem do Docker do proxy do Cloud SQL Auth

Nesta página, descrevemos como usar a imagem Docker do proxy de autenticação do Cloud SQL para conectar um cliente sqlcmd à instância do Cloud SQL a partir de uma máquina cliente que executa a instância do Linux ou do Compute Engine Linux.

Antes de começar

Você precisa:

Funções exigidas

Para receber as permissões necessárias para se conectar a uma instância do Cloud SQL usando a imagem Docker do proxy de autenticação do Cloud SQL, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Conectar um cliente sqlcmd usando a imagem Docker do proxy de autenticação do Cloud SQL

Para se conectar usando a imagem do Docker do proxy de autenticação do Cloud SQL:

  1. Ative a API Cloud SQL Admin, se ainda não estiver ativada.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

  2. Se você usa uma instância do Compute Engine, é necessário prepará-la:
    1. Mostre as propriedades da instância do Compute Engine: 
      gcloud compute instances describe [GCE_INSTANCE_NAME]
    2. Verifique a conta de serviço e os escopos de acesso configurados na instância:
      • Verifique se a conta de serviço anexada à VM tem o papel predefinido do Identity and Access Management (IAM) de cliente do Cloud SQL (roles/cloudsql.client) para se conectar usando o proxy de autenticação do Cloud SQL ou a API Cloud SQL Admin. Se você usar a autenticação de banco de dados do IAM, conceda também o papel de Usuário da instância do Cloud SQL (roles/cloudsql.instanceUser). Para mais informações sobre papéis predefinidos, consulte Papéis necessários.
      • Verifique se o escopo de acesso da VM está definido como cloud-platform (https://www.googleapis.com/auth/cloud-platform ou Permitir acesso total a todas as APIs do Cloud no console do Google Cloud ). Os escopos de acesso são um método legado para especificar a autorização de uma VM e definir apenas o escopo máximo de autorização do OAuth para solicitações. Gerencie o controle de acesso por papéis predefinidos do IAM em vez de escopos de acesso.

      Se a instância do Compute Engine não tiver os papéis de conta de serviço ou o escopo de acesso necessários, será possível atualizar a instância. Para mais informações sobre como alterar a conta de serviço e os escopos de acesso em uma VM, consulte Alterar a conta de serviço anexada na documentação do Compute Engine.

    3. Abra uma conexão de terminal com a instância usando as instruções em Como se conectar a instâncias do Linux.
  3. Instale o cliente sqlcmd na instância do Compute Engine ou na máquina cliente, se isso ainda não foi feito.
  4. Se necessário, instale o cliente Docker: 
    curl https://get.docker.com | sh
sudo usermod -aG docker $USER

    Se você usa uma instância do Compute Engine otimizada para contêineres, ela já tem o cliente Docker instalado.

  5. Instale a imagem Docker do proxy de autenticação do Cloud SQL pelo Google Container Registry. 
    docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.27.0
  6. Se você estiver executando a imagem Docker do proxy de autenticação do Cloud SQL em uma máquina local (e não em uma instância do Compute Engine) ou se a conta de serviço anexada à instância do Compute Engine não tiver os papéis do IAM e o escopo de acesso necessários, crie uma conta de serviço do Google Cloud .
    1. No console Google Cloud , acesse a página Contas de serviço.

      Acesse as 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.

    Forneça o caminho para o arquivo de chave como "PATH_TO_KEY_FILE" quando iniciar o proxy de autenticação do Cloud SQL.

  7. Acesse a página "Instâncias do Cloud SQL" no console do Google Cloud .

    Acesse Instâncias do Cloud SQL

  8. Selecione a instância para abrir a respectiva página Detalhes da instância e copie o Nome da conexão da instância.

    Por exemplo, myproject:us-central1:myinstance.

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

    Soquetes TCP

    docker run -d 
    
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json 
    
  -p 127.0.0.1:1433:1433 
    
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.27.0 
    
  --address 0.0.0.0 --port 1433 
    
  --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. A flag --address 0.0.0.0 é necessária para tornar a porta acessível de fora do contêiner do Docker.

  10. Inicie o cliente:

    A string de conexão que você usa depende de como a inicialização do proxy de autenticação do Cloud SQL foi feita, ou seja, usando um soquete TCP ou o Docker.

    Soquetes TCP

    1. Inicie o cliente sqlcmd: 
      sqlcmd -S tcp:127.0.0.1,1433 -U USERNAME -P PASSWORD

      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. Será exibido o prompt sqlcmd.
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.

Manter a imagem Docker do proxy de autenticação do Cloud SQL atualizada

A imagem 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 de autenticação do Cloud SQL no GitHub.

A seguir