Configure a CLI gcloud para Cloud de Confiance

Este guia fornece instruções para configurar a CLI do Google Cloud ( CLI gcloud) para utilização com o Cloud de Confiance. A CLI gcloud ajuda a criar e trabalhar com Cloud de Confiance recursos a partir da linha de comandos.

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

Diferenças da configuração no Google Cloud

Se já conhece a configuração e a utilização da CLI com o Google Cloud, tenha em atenção o seguinte:

  • É necessária alguma 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 em Cloud de Confiance. A CLI gcloud tem de estar instalada na sua máquina local.
  • A inicialização da CLI gcloud num único passo com gcloud init não está disponível.
  • Se uma funcionalidade ou um produto não estiver disponível em Cloud de Confiance, os comandos e os parâmetros da CLI gcloud correspondentes também não estão disponíveis.

Antes de começar

Além dos seus próprios detalhes de início de sessão para o Cloud de Confiance, precisa do seguinte para configurar a CLI gcloud pela primeira vez. Se não for um administrador da sua organização, o administrador deve fornecer-lhe estas informações.

  • O nome do Workload Identity Pool da sua organização.
  • O fornecedor de identidade (IdP) da sua organização.

Instale a CLI gcloud

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

Linux
  1. Confirme que tem uma versão suportada do Python. A CLI gcloud requer o Python 3.9 a 3.14. O pacote Linux x86_64 inclui um intérprete Python integrado que é preferido por predefinição. Para informações sobre como escolher e configurar o seu intérprete Python, consulte a gcloud topic startup documentação.
  2. Transfira uma das seguintes opções:
    Plataforma Nome do pacote Tamanho Soma de verificação SHA256
    Linux (64 bits)

    (x86_64)

    		 google-cloud-cli-linux-x86_64.tar.gz 203,2 MB 00ad1adc3ee30ead317cce7176011ce4fa984339d5c41a08eff9504301f9ee85
    Linux (64 bits)

    (Arm)

    		 google-cloud-cli-linux-arm.tar.gz 58,0 MB 19394fc05dbc4984533a2eea57ff007a8c8dad428d0d283fec1349ffda4941a5
    Linux (32 bits)

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 58,0 MB 8d67ea49ddddfe86ac889acd32fe709ed1af82759cdceef61debcd99ee98c1c5

    Para transferir o ficheiro de 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 ficheiro para o seu sistema de ficheiros, execute o seguinte comando: 
    tar -xf google-cloud-cli-linux-x86_64.tar.gz
     Para substituir uma instalação existente, elimine o diretório google-cloud-sdk existente e, em seguida, extraia o arquivo para a mesma localização.
  4. Execute o script de instalação a partir da raiz da pasta que extraiu: 
    ./google-cloud-sdk/install.sh
     O script pede-lhe que execute as seguintes ações de configuração. Para aceitar, responda Y quando lhe for pedido. Também pode realizar a instalação de forma não interativa através de flags. Para ver as flags disponíveis, execute o seguinte comando: 
    ./google-cloud-sdk/install.sh --help
  5. Opcional: se atualizou o PATH no passo anterior, abra um novo terminal para que as alterações tenham efeito.
macOS
  1. Confirme que tem uma versão suportada do Python. A CLI gcloud requer o Python 3.9 a 3.14.

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

    O script de instalação pode instalar o Python por si, se necessário. Isto requer as ferramentas de linha de comandos do Xcode. Para os instalar, execute sudo xcode-select --install. Em alternativa, pode instalar uma versão do Python suportada a partir de python.org.

    Para mais informações sobre a configuração do seu intérprete Python, especialmente se tiver várias versões instaladas, consulte a gcloud topic startupdocumentação.

  2. Transfira uma das seguintes opções:
    Plataforma Pacote Tamanho Soma de verificação SHA256
    macOS de 64 bits

    (x86_64)

    		 google-cloud-cli-darwin-x86_64.tar.gz 58,1 MB f495ade56c47e0a8026d47efe32fda493f94a59cf00ea83527a386acded8b789
    macOS de 64 bits

    (ARM64, Apple silicon)

    		 google-cloud-cli-darwin-arm.tar.gz 58,0 MB 5204d57d199187b19b95b977fcf1b03e962cf5a531a9aba99c4f498b9342e791
    macOS de 32 bits

    (x86)

    		 google-cloud-cli-darwin-x86.tar.gz 56,5 MB 01e3b9110fef34ea29bca9e11f24137df0ae9240ebc119ce089680147283bb0a

    Em alternativa, pode transferir o arquivo a partir da linha de comandos. 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 ficheiro para a localização preferida no seu sistema de ficheiros. Uma prática comum é extraí-lo para o seu diretório inicial.

    No macOS, pode fazê-lo abrindo o ficheiro .tar.gz transferido na sua localização preferida. Em alternativa, na linha de comandos, execute: 

    tar -xf FILE_NAME

    Para substituir uma instalação existente, elimine o diretório google-cloud-sdk existente e, em seguida, extraia o arquivo para a mesma localização.

  4. Execute o script de instalação a partir da raiz da pasta que extraiu: 
    ./google-cloud-sdk/install.sh
     O script pede-lhe que execute as seguintes ações de configuração. Para aceitar, responda Y quando lhe for pedido.
    • Instale o Python 3.13 e os módulos recomendados, se necessário.
    • Adicione a CLI gcloud ao seu PATH e ative a conclusão de comandos.
    • Ative o envio de estatísticas de utilização anónimas para ajudar a melhorar a CLI gcloud.
    Também pode realizar a instalação de forma não interativa através de flags. Para ver as flags disponíveis, execute o seguinte comando: 
    ./google-cloud-sdk/install.sh --help
     Para executar o script de instalação com o modo de leitor de ecrã ativado: 
    ./google-cloud-sdk/install.sh --screen-reader=true
  5. Opcional: se atualizou o PATH no passo anterior, abra um novo terminal para que as alterações tenham efeito.
Windows

A CLI Google Cloud no Windows requer o Windows 8.1 e posterior ou o Windows Server 2012 e posterior.

  1. Transfira o instalador da CLI do Google Cloud.

    Em 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 as instruções. O instalador é assinado pela Google LLC.

    • Se estiver a usar um leitor de ecrã, selecione a caixa de verificação Ativar modo de leitor de ecrã. Esta opção configura o gcloud para usar indicadores de estado em vez de ícones de carregamento Unicode, apresentar o progresso como uma percentagem e simplificar as tabelas. Para mais informações, consulte o guia de funcionalidades de acessibilidade.
    • A CLI gcloud requer o Python. As versões suportadas são o Python 3.9 a 3.14. Por predefinição, a versão do Windows da CLI do Google Cloud é fornecida com o Python 3. Para usar a Google Cloud CLI, o seu sistema operativo tem de conseguir executar uma versão suportada do Python.
    • O instalador instala todas as dependências necessárias, incluindo a versão do Python necessária. Embora a Google Cloud CLI instale e faça a gestão do Python 3 por predefinição, pode usar uma instalação do Python existente, se necessário, desmarcando a opção para instalar o Python integrado. Consulte gcloud topic startup para saber como usar uma instalação do Python existente.
  3. Após a conclusão da instalação, o instalador dá-lhe a opção de criar atalhos no menu Iniciar e no ambiente de trabalho, iniciar a shell da CLI gcloud e configurar a CLI gcloud. Deixe as opções para iniciar a shell e configurar a instalação selecionadas. O instalador inicia uma janela de terminal e executa o comando gcloud init para inicializar, autorizar e configurar a CLI gcloud.
  4. A instalação predefinida não inclui as extensões do App Engine necessárias para implementar uma aplicação através de comandos gcloud. Estes componentes podem ser instalados através do gestor de componentes da CLI gcloud.

Sugestões de resolução de problemas

  • Se a instalação não for bem-sucedida porque o comando find não é reconhecido, certifique-se de que a variável de ambiente PATH está definida para incluir a pasta que contém find. Normalmente, este valor é C:\WINDOWS\system32;.
  • Se desinstalou a CLI gcloud, tem de reiniciar o sistema antes de instalar novamente a CLI gcloud.
  • Se a descompressão falhar, execute o instalador como administrador.

Crie o seu ficheiro de configuração de início de sessão

Para configurar o acesso ao seu universo, tem de criar um ficheiro de configuração JSON para a CLI gcloud, incluindo os domínios usados pelo Cloud de Confiance e o IdP configurado para a sua organização.

Para criar o ficheiro de configuração de início de sessão:

  • Execute os seguintes comandos:

    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 o seguinte:

    • POOL_ID: o identificador exclusivo do Workload Identity Pool da sua organização.
    • PROVIDER_ID: o fornecedor de identidade (IdP) da sua organização.

O resultado é semelhante ao seguinte:

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

Depois de criar o ficheiro de configuração, não precisa de repetir este passo desde que inicie sessão a partir do mesmo computador.

Inicie sessão no Cloud de Confiance com a CLI gcloud

Agora, pode usar o ficheiro de configuração sempre que precisar de iniciar sessão em Cloud de Confiance:

  • Para iniciar sessão a partir da linha de comandos, execute o seguinte comando:

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

  • Se precisar de usar Credenciais padrão da aplicação (ADC) (necessárias para executar módulos do Terraform), execute o seguinte comando:

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

É aberta uma página Web onde pode iniciar sessão com os seus detalhes de início de sessão. Depois de iniciar sessão, pode configurar e usar a CLI gcloud conforme descrito no resto da respetiva documentação.

(Opcional) Configure propriedades predefinidas

Quando configura a CLI gcloud, é-lhe fornecida uma configuração denominada default que pode usar para propriedades que fornecem valores de flags predefinidos ou regem o comportamento da ferramenta. Embora seja opcional, recomendamos que configure algumas propriedades predefinidas para a CLI gcloud, como o seu projeto predefinido, antes de usar a ferramenta. As propriedades predefinidas são úteis se não quiser ter de especificar o seu projeto ou localização de computação preferida sempre que executar um comando.

Os passos seguintes definem as mesmas propriedades que são configuradas por gcloud init para utilizadores do Google Cloud:

  1. Para definir o projeto predefinido, execute o seguinte comando, especificando o ID do projeto escolhido:

    gcloud config set project PROJECT_ID

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

    gcloud config set compute/region u-france-east1

    Para definir a sua zona predefinida, execute o seguinte comando:

    gcloud config set compute/zone ZONE

  3. Para ver as propriedades da sua configuração atual, incluindo o utilizador autenticado, execute o seguinte comando:

    gcloud config list

Pode saber como funcionam as configurações da CLI gcloud e como criar e usar configurações adicionais em Gerir configurações da CLI gcloud. Pode saber mais sobre como especificar propriedades em Faça a gestão das propriedades da CLI gcloud.

(Opcional) Execute comandos

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

  1. Apresente uma lista das contas cujas credenciais estão armazenadas no sistema local:

    gcloud auth list

    A CLI gcloud apresenta uma lista de contas com credenciais:

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

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

    gcloud config list

    A CLI gcloud apresenta 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. Veja informações sobre os comandos gcloud e outros tópicos:

    gcloud help

    Por exemplo, para ver a ajuda de gcloud compute instances create:

    gcloud help compute instances create

    A CLI gcloud apresenta um tópico de ajuda que contém uma descrição do comando, uma lista de argumentos e flags de comando, e exemplos de como usar o comando.

O que se segue?