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 Cloud de Confiance. A CLI gcloud ajuda a criar e trabalhar com Cloud de Confiance recursos na linha de comando.

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

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 o Cloud de Confiance, conforme descrito neste guia.
  • O Cloud Shell não está disponível no Cloud de Confiance. A CLI gcloud precisa ser instalada na sua máquina local.
  • A inicialização da CLI gcloud em uma etapa com gcloud init não está disponível.
  • Se um recurso ou produto não estiver disponível no 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 detalhes de login para o Cloud de Confiance, você precisa do seguinte para configurar a CLI gcloud pela primeira vez. Se você não for um administrador da sua organização, peça essas informações ao administrador.

  • 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 3.10 a 3.15. 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 a gcloud topic startup documentação.
  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 93,5 MB 817026aec0adea0e2ee8ed3a1ba3eabfe9e5177581fbe16595a8fe495a601300
    Linux de 64 bits

    (Arm)

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

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 54,1 MB 69f2e18bd0e706a6b31d005381bdf6b17ede01bcf6ce1804a42e2e7cef09bd9c

    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 *.tar.gz nome do pacote que se aplica à sua configuração.

  3. Para extrair o conteúdo do arquivo para o sistema de arquivos, execute o seguinte comando: 
    tar -xf google-cloud-cli-linux-x86_64.tar.gz
     Para substituir uma instalação atual, exclua 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: 
    ./google-cloud-sdk/install.sh
     O script solicita que você execute as seguintes ações de configuração. Para aceitar, responda Y quando solicitado.
    • Adicione a CLI gcloud ao seu PATH.
    • Ative o preenchimento do comando.
    • Aceite enviar estatísticas de uso anônimas para ajudar a melhorar a CLI gcloud.
    Também é possível realizar a instalação de forma não interativa fornecendo flags. Para conferir as flags disponíveis, execute: 
    ./google-cloud-sdk/install.sh --help
  5. Opcional: se você atualizou o PATH na etapa anterior, abra um novo terminal para que as mudanças entrem em vigor.
macOS
  1. Confirme se você tem uma versão compatível do Python. A CLI do Google Cloud requer o Python 3.10 a 3.15.

    Para verificar a versão do Python, execute python3 -V ou python -V.

    O instalador da gcloud instala o Python v3.14 e os módulos de extensão necessários por padrão.

    Para mais informações sobre como configurar o interpretador do Python, consulte a gcloud topic startup documentação.

  2. Faça o download de um dos seguintes itens:
    Plataforma Pacote Tamanho Soma de verificação SHA256
    macOS de 64 bits

    (x86_64)

    		 google-cloud-cli-darwin-x86_64.tar.gz 54,3 MB b49e8cb9d348267d46fade7b9c916a1aed7ce0ec07e142ce41cc0d24a95a9651
    macOS de 64 bits

    (ARM64, Apple silicon)

    		 google-cloud-cli-darwin-arm.tar.gz 54,2 MB 71b37ca07ab0f9bc43898e42c913e10f143166230ab31e0bbea3632dbc77b010
    macOS de 32 bits

    (x86)

    		 google-cloud-cli-darwin-x86.tar.gz 52,6 MB bc9d328fbf56f650b57d9a70eb267993c98d0a9cbd15864b0b8fee949ea1039f

    Como alternativa, faça o download do arquivo na linha de comando. Substitua FILE_NAME pelo nome do pacote da sua plataforma na tabela acima. 

    curl -O https://storage.s3nsapis.fr/cloud-sdk-release/FILE_NAME
  3. Extraia o conteúdo do arquivo para o local de preferência no sistema de arquivos. Uma prática comum é extrair para o diretório inicial.

    No macOS, isso pode ser feito abrindo o arquivo .tar.gz salvo no local de preferência. Como alternativa, na linha de comando, execute: 

    tar -xf FILE_NAME

    Para substituir uma instalação atual, exclua 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: 
    ./google-cloud-sdk/install.sh
     O script solicita que você execute as seguintes ações de configuração. Para aceitar, responda Y quando solicitado.
    • Instale o Python 3.14 e os módulos recomendados, se necessário.
    • Adicione a CLI gcloud ao seu PATH e ative o preenchimento do comando.
    • Aceite enviar estatísticas de uso anônimas para ajudar a melhorar a CLI gcloud.
    Também é possível realizar a instalação de forma não interativa fornecendo flags. Para conferir as flags 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
  5. Opcional: se você atualizou o PATH na etapa anterior, abra um novo terminal para que as mudanças entrem em vigor.
Windows

A CLI do Google Cloud no Windows requer o Windows 8.1 e versões mais recentes ou o Windows Server 2012 e versões mais recentes.

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

    Como alternativa, abra um terminal do PowerShell e execute os seguintes comandos do PowerShell: 

    (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 indicadores de carregamento Unicode, mostrar o progresso como uma porcentagem e achatar tabelas. Para mais informações, consulte o Guia de recursos de acessibilidade.
    • A Google Cloud CLI requer Python. versões compatíveis são o Python 3.10 a 3.15. Por padrão, a versão para Windows da Google Cloud CLI vem com o Python 3. Para usar a Google Cloud CLI, 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 atual do Python.
  3. 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 Google Cloud CLI e configurar a CLI gcloud. Deixe as opções para iniciar o shell e configurar a instalação selecionadas. O instalador inicia uma janela do terminal e executa o gcloud init comando para inicializar, autorizar e configurar a CLI gcloud.
  4. A instalação padrão não inclui as extensões do App Engine necessárias para implantar um aplicativo usando gcloud comandos. 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.

(Opcional) Criar uma configuração específica do universo

Se você precisar usar a instalação da CLI gcloud com vários universos (por exemplo, com o Google Cloud e o Cloud de Confiance), crie uma configuração específica da CLI gcloud para as Cloud de Confiance configurações.

Para criar e mudar para uma nova configuração, execute os seguintes comandos:

gcloud config configurations create CONFIG_NAME
gcloud config configurations activate CONFIG_NAME

Substitua:

  • CONFIG_NAME: o nome exclusivo escolhido para sua configuração.

Se você não criar uma configuração específica do universo, o restante dessas etapas usará a configuração padrão da CLI gcloud (chamada default).

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 Confiance e o IdP configurado para sua organização.

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

  • Defina o domínio do universo para a CLI gcloud na configuração ativa:

    gcloud config set universe_domain s3nsapis.fr

  • Execute os comandos a seguir:

    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, desde que você faça 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, na sigla em inglês), 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 que você possa fazer login com seus detalhes de login. Depois de fazer login, você pode configurar e usar 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 regem 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 seguinte comando, 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 a zona padrão, execute o seguinte comando:

    gcloud config set compute/zone ZONE

  3. Para conferir as propriedades da 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 configurations. 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 CLI gcloud:

    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 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 que contém uma descrição do comando, uma lista de flags e argumentos dele, além de exemplos de uso.

A seguir