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 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 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,3 MB c95e0277ba3792b83709aa43d8f95486de92b0a913d2393dbfca48f28b0bab39
    Linux (64 bits)

    (Arm)

    		 google-cloud-cli-linux-arm.tar.gz 58,1 MB a911104ae2b09392bfee61c79c128d5ad23e35bbfb792aadfe2a80024cece201
    Linux (32 bits)

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 58,1 MB e4ad30317c09cdc36dfc0c366034403e06d671ef5de2e6372bc01d7284b1a6a1

    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,2 MB 5fe9406ca194ddfad542694be0639d5c2ab2206d2683ea3365cdd1db5c6c4600
    macOS de 64 bits

    (ARM64, Apple silicon)

    		 google-cloud-cli-darwin-arm.tar.gz 58,1 MB 7ad3658d883c13ad93fc82fbec671ac7e3b9972c6be4efa3f9d4cc489d4a944b
    macOS de 32 bits

    (x86)

    		 google-cloud-cli-darwin-x86.tar.gz 56,7 MB d74e5df73277cc88bb9ef0354f90085a0612892561fb3b8ae2d998990f11cdce

    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 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 as 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 sinalização 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 preferencial 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 do 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?