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 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. Tenha em atenção que o pacote Linux x86_64 inclui um intérprete Python integrado que é o preferido por predefinição. Para informações sobre como escolher e configurar o seu intérprete Python, consulte gcloud topic startup.
  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 150,5 MB 829dfe40f9dcc1f293642bc1fa816e3bf3cec065416df5e5df80b26ea2469eb9
    Linux (64 bits)

    (Arm)

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

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 57,2 MB 6966bdb953764083f3e5d49f1ed0f7a13f34a3f193a24394ae69ab2c52dfba84

    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 (de preferência, para o diretório principal), execute o seguinte comando: 
    tar -xf google-cloud-cli-linux-x86_64.tar.gz
     Opcional: para substituir uma instalação existente, remova o diretório google-cloud-sdk existente e, em seguida, extraia o arquivo para a mesma localização.
  4. (Opcional) Adicione a CLI gcloud ao seu PATH. Também pode optar pela conclusão de comandos para a recolha de estatísticas de utilização e do shell. Execute o script de instalação (a partir da raiz da pasta que extraiu no último passo) através do seguinte comando: 
    ./google-cloud-sdk/install.sh
     Isto também pode ser feito de forma não interativa (por exemplo, através de um script) e fornecendo preferências como flags. Para ver as flags disponíveis, execute o seguinte comando: 
    ./google-cloud-sdk/install.sh --help
    • Para enviar estatísticas de utilização anónimas para ajudar a melhorar a CLI gcloud, responda Y quando lhe for pedido.
    • Para adicionar a CLI gcloud ao seu PATH e ativar a conclusão de comandos, responda Y quando lhe for pedido.
  5. Se atualizou o PATH no passo anterior, abra um novo terminal para que as alterações tenham efeito.
  6. Opcional: instale componentes adicionais através do gestor de componentes.
macOS
  1. Confirme que tem uma versão suportada do Python:
    • Para verificar a sua versão atual do Python, execute python3 -V ou python -V. As versões suportadas 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 comandos do Xcode são necessárias para instalar o Python.
      • Verifique se as ferramentas de linha de comandos do Xcode estão instaladas executando: xcode-select -p.
      • Se as ferramentas de linha de comandos do Xcode não estiverem instaladas, instale-as executando: sudo xcode-select --install.
    • Caso contrário, para instalar uma versão do Python suportada, visite a página Python Releases for macOS em Python.org.
    • Se tiver vários intérpretes Python instalados no seu computador, defina a variável de ambiente CLOUDSDK_PYTHON no shell para apontar para o caminho do seu intérprete preferencial.
    • Para mais informações sobre como escolher e configurar o seu intérprete Python, consulte gcloud topic startup.
  2. Transfira um dos seguintes:

    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 54182decb607e47a60029fe8c76158a5647f2023cea3ab6296f31c4ef5fe2410
    macOS de 64 bits

    (ARM64, Apple silicon)

    		 google-cloud-cli-darwin-arm.tar.gz 57,2 MB 332559d0d0e6f35ecc6b99290a3cfe6396151b4e222b4364c0f6a379020bbbe5
    macOS de 32 bits

    (x86)

    		 google-cloud-cli-darwin-x86.tar.gz 55,7 MB 9d905af3f7f520adfdf2341d6e91528e6aba67cd4be03cfe99484675606c6dac
  3. Extraia o arquivo para qualquer localização no seu sistema de ficheiros (de preferência, o diretório inicial). No macOS, isto pode ser conseguido abrindo o ficheiro de arquivo .tar.gz transferido na localização preferida. Em alternativa, execute o seguinte comando: 
    tar -xf google-cloud-cli-darwin-arm.tar.gz

    Opcional: para substituir uma instalação existente, remova 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 no último passo) com o seguinte comando: 
    ./google-cloud-sdk/install.sh

    O script pede-lhe que instale o Python 3.12 e determinados módulos recomendados.

    A instalação também pode ser feita de forma não interativa (por exemplo, através de um script) fornecendo preferências como flags. Para descrever 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
     Opcional:
    • Para enviar estatísticas de utilização anónimas para ajudar a melhorar a CLI gcloud, responda Y quando lhe for pedido.
    • Para adicionar a CLI gcloud ao seu PATH e ativar a conclusão de comandos, responda Y quando lhe for pedido.
  5. Se atualizou o PATH no passo anterior, abra um novo terminal para que as alterações tenham efeito.
  6. Opcional. Instale componentes adicionais através do gestor de componentes.
Windows
    A CLI Google Cloud funciona no Windows 8.1 e posterior, e no 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.

  3. 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.

  4. 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. Certifique-se de que deixa selecionadas as opções para iniciar a shell e configurar a sua instalação. O instalador inicia uma janela de terminal e executa o comando gcloud init.

  5. 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 Confiancee 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 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 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?