Configurar a Google Cloud CLI para Cloud de Confiance

Este guia fornece instruções para configurar a Google Cloud CLI (CLI gcloud) para uso com o Cloud de Confiance. A CLI gcloud ajuda você a criar e trabalhar com recursos do Cloud de Confiance na linha de comando.

Para mais informações gerais sobre como configurar e usar a CLI gcloud, consulte a documentação da CLI gcloud.

Diferenças da configuração no Google Cloud

Se você já sabe como configurar e usar a CLI com o Google Cloud, observe o seguinte:

  • É necessário fazer uma configuração inicial adicional para usar a CLI gcloud com Cloud de Confiance, conforme descrito neste guia.
  • O Cloud Shell não está disponível em Cloud de Confiance. A CLI gcloud precisa estar instalada na sua máquina local.
  • Não é possível inicializar a CLI gcloud em uma etapa com gcloud init.
  • Se um recurso ou produto não estiver disponível em Cloud de Confiance, os comandos e parâmetros correspondentes da CLI gcloud também não estarão.

Antes de começar

Além dos seus próprios detalhes de login para Cloud de Confiance, você precisa do seguinte para configurar a CLI gcloud pela primeira vez. Se você não for administrador da sua organização, peça essas informações a ele.

  • O nome do pool de identidades da carga de trabalho da sua organização.
  • O provedor de identidade (IdP) da sua organização.

Instalar a CLI gcloud

Instale a CLI gcloud seguindo as instruções para seu SO.

Linux
  1. Confirme se você tem uma versão compatível do Python. A CLI do Google Cloud requer o Python de 3.9 a 3.14. O pacote Linux x86_64 inclui um intérprete de Python em pacote que terá preferência por padrão. Para informações sobre como escolher e configurar o interpretador do Python, consulte gcloud topic startup.
  2. Faça o download de um dos seguintes itens:
    Plataforma Nome do pacote Tamanho Soma de verificação SHA256
    Linux de 64 bits

    (x86_64)

    		 google-cloud-cli-linux-x86_64.tar.gz 150,5 MB 31000673c1f9e18ec7b38823748031c58949cb0479d36ede999ae8cad6097ae3
    Linux de 64 bits

    (Arm)

    		 google-cloud-cli-linux-arm.tar.gz 57,1 MB a1c1a88274e8bf11561771b9373b566cbb044f1cb3884e454625ec9449ea33f2
    Linux de 32 bits

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 57,1 MB 32ff2bea65cd5c79aa86b948219c1e861a0434cc99011f4d977c4a9810e595de

    Para fazer o download do arquivo do Linux, execute o seguinte comando: 

    curl -O https://storage.s3nsapis.fr/cloud-sdk-release/google-cloud-cli-linux-x86_64.tar.gz

    Consulte a tabela acima e substitua google-cloud-cli-linux-x86_64.tar.gz pelo nome do pacote *.tar.gz que se aplica à sua configuração.

  3. Para extrair o conteúdo do arquivo para o sistema de arquivos (preferencialmente para seu diretório inicial), execute o seguinte comando: 
    tar -xf google-cloud-cli-linux-x86_64.tar.gz
     Opcional: para substituir uma instalação, remova o diretório google-cloud-sdk e extraia o arquivo para o mesmo local.
  4. (Opcional) Adicione a CLI gcloud ao seu PATH. Também é possível ativar a conclusão do comando no shell e a coleta de estatísticas de uso. Execute o script de instalação (na raiz da pasta extraída na última etapa) usando o seguinte comando: 
    ./google-cloud-sdk/install.sh
     Isso também pode ser feito de maneira não interativa (por exemplo, usando um script) e fornecendo preferências como sinalizações. Para ver as flags disponíveis, execute: 
    ./google-cloud-sdk/install.sh --help
    • (Opcional) Para enviar estatísticas de uso anônimas para ajudar a melhorar a CLI gcloud, responda Y quando solicitado.
    • Para adicionar a CLI gcloud ao PATH e ativar o preenchimento do comando, responda Y quando solicitado.
  5. Se você atualizou o PATH na etapa anterior, abra um novo terminal para que as mudanças entrem em vigor.
  6. Opcional: instale componentes extras usando o gerenciador de componentes.
macOS
  1. Confirme se você tem uma versão compatível do Python:
    • Para verificar a versão atual do Python, execute python3 -V ou python -V. As versões compatíveis são Python 3.9 a 3.14.
    • O script de instalação principal oferece a instalação do Python 3.12 do CPython.
      • As ferramentas de linha de comando do Xcode são necessárias para instalar o Python.
      • Verifique se as ferramentas de linha de comando do Xcode estão instaladas executando: xcode-select -p.
      • Se as ferramentas de linha de comando do Xcode não estiverem instaladas, execute sudo xcode-select --install para instalá-las.
    • Caso contrário, para instalar uma versão compatível do Python, acesse as versões do Python para macOS (link em inglês) do Python.org.
    • Se você tem vários intérpretes de Python instalados na sua máquina, defina a variável de ambiente CLOUDSDK_PYTHON no shell para apontar para o caminho do intérprete preferido.
    • Para informações sobre como escolher e configurar o interpretador do Python, consulte gcloud topic startup.
  2. Faça o download de um dos seguintes itens:

    3. Plataforma Pacote Tamanho Soma de verificação SHA256
    macOS de 64 bits

    (x86_64)

    		 google-cloud-cli-darwin-x86_64.tar.gz 57,2 MB b24a11aa4f1816bff3122b3560c909c1eb7109bf8979821251d8bc5679582f10
    macOS de 64 bits

    (ARM64, Apple silicon)

    		 google-cloud-cli-darwin-arm.tar.gz 57,1 MB b4d2b8b63593ad226cf1c4da0667ffa4a9cb923bd41ec269e67891491aeb126a
    macOS de 32 bits

    (x86)

    		 google-cloud-cli-darwin-x86.tar.gz 55,7 MB 6e66bdc92029fd3a3856e6a9bc03f2799079184ff3fe436c7ade1ef1a8f03452
  3. Extraia o arquivo para qualquer local no seu sistema de arquivos, de preferência no diretório principal. No macOS, isso pode ser feito abrindo o arquivo .tar.gz salvo no local de preferência. Ou execute o seguinte comando: 
    tar -xf google-cloud-cli-darwin-arm.tar.gz

    Opcional: para substituir uma instalação, remova o diretório google-cloud-sdk e extraia o arquivo para o mesmo local.

  4. Execute o script de instalação (na raiz da pasta extraída na última etapa) usando o seguinte comando: 
    ./google-cloud-sdk/install.sh

    O script vai pedir para instalar o Python 3.12 e alguns módulos recomendados.

    A instalação também pode ser feita de maneira não interativa (por exemplo, usando um script) e fornecendo preferências como flags. Para descrever as sinalizações disponíveis, execute: 
    ./google-cloud-sdk/install.sh --help
     Para executar o script de instalação com o modo de leitor de tela ativado: 
    ./google-cloud-sdk/install.sh --screen-reader=true
     Opcional:
    • (Opcional) Para enviar estatísticas de uso anônimas para ajudar a melhorar a gcloud CLI, responda Y quando solicitado.
    • Para adicionar a CLI gcloud ao PATH e ativar o preenchimento do comando, responda Y quando solicitado.
  5. Se você atualizou o PATH na etapa anterior, abra um novo terminal para que as mudanças entrem em vigor.
  6. Opcional. Instale componentes extras usando o gerenciador de componentes.
Windows
    A Google Cloud CLI funciona no Windows 8.1 e versões mais recentes e no Windows Server 2012 e versões mais recentes.

  1. Faça o download do Instalador da CLI do Google Cloud.

    Se preferir, abra um terminal do PowerShell e execute os comandos a seguir:

    (New-Object Net.WebClient).DownloadFile("https://storage.s3nsapis.fr/cloud-sdk-release/GoogleCloudSDKInstaller.exe", "$env:Temp\GoogleCloudSDKInstaller.exe")

& $env:Temp\GoogleCloudSDKInstaller.exe

  2. Inicie o instalador e siga os prompts. O instalador é assinado pela Google LLC.

    Se você estiver usando um leitor de tela, marque a caixa de seleção Ativar modo leitor de tela. Essa opção configura gcloud para usar rastreadores de status em vez de spinners unicode, exibir o progresso como uma porcentagem e nivelar tabelas. Para mais informações, consulte o Guia de recursos de acessibilidade.

  3. A Google Cloud CLI requer Python. As versões compatíveis são Python 3.9 a 3.14. Por padrão, a versão para Windows da CLI do Google Cloud vem com o Python 3. Para usar a CLI do Google Cloud, seu sistema operacional precisa executar uma versão compatível do Python.

    O instalador instala todas as dependências necessárias, incluindo a versão necessária do Python. Embora o SDK da CLI do Google Cloud instale e gerencie o Python 3 por padrão, é possível usar uma instalação atual do Python ao desmarcar a opção de instalar o Bundled Python, se necessário. Consulte gcloud topic startup para saber como usar uma instalação existente do Python.

  4. Depois que a instalação for concluída, o instalador oferecerá a opção de criar os atalhos do menu e da área de trabalho, iniciar o shell da CLI do Google Cloud e configurar a CLI gcloud. Deixe as opções para iniciar o shell e configurar a instalação selecionadas. O instalador inicia uma janela de terminal e executa o comando gcloud init.

  5. A instalação padrão não inclui as extensões do App Engine necessárias para implantar um aplicativo usando comandos gcloud. Para instalar esses componentes, use o gerenciador de componentes da CLI gcloud.
Dicas de solução de problemas:
  • Se a instalação não for bem-sucedida devido ao comando find não ter sido reconhecido, verifique se sua variável de ambiente PATH está definida para incluir a pasta que contém find. Geralmente, isso é C:\WINDOWS\system32;.
  • Se você desinstalou a CLI gcloud, é necessário reinicializar o sistema antes de instalá-la novamente.
  • Se a descompactação falhar, execute o instalador como um administrador.

Criar o arquivo de configuração de login

Para configurar o acesso ao seu universo, crie um arquivo de configuração JSON para a CLI gcloud, incluindo os domínios usados pelo Cloud de Confiancee o IdP configurado para sua organização.

Para criar o arquivo de configuração de login:

  • Execute os comandos a seguir:

    gcloud config set universe_domain s3nsapis.fr

AUDIENCE=locations/global/workforcePools/POOL_ID/providers/PROVIDER_ID
UNIVERSE_WEB_DOMAIN="cloud.s3nscloud.fr"
UNIVERSE_API_DOMAIN="s3nsapis.fr"

gcloud iam workforce-pools create-login-config \
$AUDIENCE \
--universe-cloud-web-domain="$UNIVERSE_WEB_DOMAIN" \
--universe-domain="$UNIVERSE_API_DOMAIN" \
--output-file="wif-login-config.json"

    Substitua:

    • POOL_ID: o identificador exclusivo do pool de identidades da carga de trabalho da sua organização.
    • PROVIDER_ID: o provedor de identidade (IdP) da sua organização.

O resultado será assim:

Created login configuration file [wif-login-config.json].

Depois de criar o arquivo de configuração, não é necessário repetir essa etapa enquanto você fizer login na mesma máquina.

Fazer login no Cloud de Confiance com a CLI gcloud

Agora você pode usar o arquivo de configuração sempre que precisar fazer login no Cloud de Confiance:

  • Para fazer login na linha de comando, execute o seguinte comando:

    gcloud auth login -–login-config=wif-login-config.json

  • Se você precisar usar as Credenciais padrão do aplicativo (ADC) (necessárias para executar módulos do Terraform), execute o seguinte comando:

    gcloud auth application-default login --login-config=wif-login-config.json

Uma página da Web será aberta para você fazer login com seus dados. Depois de fazer login, configure e use a CLI gcloud conforme descrito no restante da documentação.

(Opcional) Configurar propriedades padrão

Ao configurar a CLI gcloud, você recebe uma configuração chamada default, que pode ser usada para propriedades que fornecem valores de flag padrão ou controlam o comportamento da ferramenta. Embora seja opcional, recomendamos configurar algumas propriedades padrão para a CLI gcloud, como o projeto padrão, antes de usar a ferramenta. As propriedades padrão são úteis se você não quiser especificar o projeto ou o local de computação preferido sempre que executar um comando.

As etapas a seguir definem as mesmas propriedades configuradas por gcloud init para usuários do Google Cloud:

  1. Para definir o projeto padrão, execute o comando a seguir, especificando o ID do projeto escolhido:

    gcloud config set project PROJECT_ID

  2. Se você usa o Compute Engine ou o GKE, alguns comandos exigem que você especifique uma região ou zona de computação. Para definir a região padrão para comandos, execute o seguinte comando:

    gcloud config set compute/region u-france-east1

    Para definir sua zona padrão, execute o seguinte comando:

    gcloud config set compute/zone ZONE

  3. Para conferir as propriedades da sua configuração atual, incluindo o usuário autenticado, execute o seguinte comando:

    gcloud config list

Saiba como as configurações da CLI gcloud funcionam e como criar e usar outras configurações em Gerenciar configurações da CLI gcloud. Saiba mais sobre como especificar propriedades em Gerenciar propriedades da CLI gcloud.

(Opcional) Executar comandos

Execute comandos principais para conferir informações sobre a instalação da CLI gcloud:

  1. Liste as contas com credenciais armazenadas no sistema local:

    gcloud auth list

    A CLI gcloud mostra uma lista de contas credenciadas:

    Credentialed Accounts
ACTIVE             ACCOUNT
*                  principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/my-user@example.com

  2. Liste as propriedades na configuração ativa da gcloud CLI:

    gcloud config list

    A CLI gcloud mostra a lista de propriedades:

    [core]
account = principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/my-user@example.com
disable_usage_reporting = False
project = my-project

  3. Confira informações sobre os comandos gcloud e outros tópicos:

    gcloud help

    Por exemplo, para visualizar a ajuda para gcloud compute instances create:

    gcloud help compute instances create

    A CLI gcloud mostra um tópico de ajuda com uma descrição do comando, uma lista de flags e argumentos e exemplos de como usar o comando.

A seguir