Como realizar o script de comandos da CLI gcloud

Além de executar os comandos do Google Cloud CLI pela linha de comando, é possível executá-los em scripts ou outras automações, por exemplo, ao usar o Jenkins para orientar a automação de tarefas do Google Cloud.

A CLI gcloud vem com várias ferramentas, como filtragem, formatação e a sinalização --quiet, permitindo que você gerencie efetivamente a saída e automatize tarefas.

Observação :a execução paralela de vários comandos da CLI gcloud não é compatível.

Noções básicas de script com a CLI gcloud

Para conferir um guia explicativo sobre como criar scripts básicos com a CLI gcloud, consulte esta postagem do blog: Scripts com a gcloud: guia para iniciantes para automatizar tarefas do Google Cloud (em inglês).

Autorização

Ao criar scripts com a CLI gcloud, você precisa considerar métodos de autorização. A CLI gcloud oferece duas opções:

• Autorização da conta de usuário
• autorização da conta de serviço

É recomendável usar a autorização da conta de usuário se você estiver executando um script ou outra automação em uma única máquina.

Para autorizar o acesso e executar outras etapas comuns de configuração da CLI gcloud:

gcloud init

A autorização da conta de serviço será recomendada se você estiver implantando um script ou outra automação entre máquinas em um ambiente de produção. Ela também é o método de autorização recomendado se você estiver executando comandos da CLI gcloud em uma instância de máquina virtual do Compute Engine em que todos os usuários tenham acesso a root.

Para usar a autorização de conta de serviço, use uma conta de serviço atual ou crie uma nova na página "Contas de serviço":

Acesse a página Contas de serviço

Para criar e fazer o download da chave privada associada como um arquivo de chave formatado em JSON, escolha Gerenciar chaves no menu de ações da conta de serviço.

Para executar a autorização, execute gcloud auth activate-service-account:

gcloud auth activate-service-account --key-file [KEY_FILE]

É possível se conectar via SSH à sua instância de VM usando gcloud compute ssh, que cuida da autenticação. Os arquivos de configuração SSH podem ser configurados usando gcloud compute config-ssh.

Para instruções detalhadas sobre autorização de ferramentas da CLI gcloud, consulte Como autorizar a CLI gcloud.

Desativar prompts

Alguns comandos da CLI da gcloud são interativos e solicitam que os usuários confirmem uma operação ou entradas complementares para um comando inserido.

Na maioria dos casos, isso não é conveniente para a execução de comandos em um script ou outra automação. Desative as solicitações dos comandos da CLI gcloud definindo a propriedade disable_prompts na configuração como True ou usando a sinalização global --quiet ou -q. A maioria dos comandos interativos tem valores padrão quando a confirmação extra ou a entrada é obrigatória. Caso os prompts estejam desativados, os valores padrão são usados.

Exemplo:

gcloud debug targets list --quiet

Como filtrar e formatar uma saída

Para criar um script com a CLI gcloud, é importante ter saída previsível. É aqui que as sinalizações --filter e --format ajudam. Eles garantem que, ao executar um comando usando a CLI gcloud, ele produz uma saída que atenda às suas especificações de formato (como json, yaml, csv e texto) e filtro (nomes de VM prefixados com "teste", ano de criação após 2015 etc.).

Se você quiser trabalhar em um tutorial interativo sobre como usar o filtro e formatar sinalizações, inicie o tutorial usando o seguinte botão:

Os exemplos a seguir mostram usos comuns de formatação e filtragem com comandos da CLI da gcloud:

Liste instâncias criadas na zona us-central1-a:

gcloud compute instances list --filter="zone:us-central1-a"

Lista no formato JSON os projetos em que os rótulos correspondem a valores específicos. Por exemplo, label.env é "test" e label.version é "alpha":

gcloud projects list --format="json" \
  --filter="labels.env=test AND labels.version=alpha"

Liste projetos com data e hora de criação especificadas no fuso horário local:

gcloud projects list \
  --format="table(name, project_id, createTime.date(tz=LOCAL))"

Liste projetos que foram criados após uma data específica no formato da tabela:

gcloud projects list \
  --format="table(projectNumber,projectId,createTime)" \
  --filter="createTime.date('%Y-%m-%d', Z)='2016-05-11'"

Observe que, no último exemplo, foi usada uma projeção na chave. O filtro é aplicado na chave createTime depois que a formatação de data é definida.

Liste uma tabela aninhada de cotas de uma região:

gcloud compute regions describe us-central1 \
  --format="table(quotas:format='table(metric,limit,usage)')"

Imprima uma lista nivelada de cotas globais no formato CSV:

gcloud compute project-info describe --flatten='quotas[]' \
  --format='csv(quotas.metric,quotas.limit,quotas.usage)'

Liste recursos de instância de computação com decorações e títulos de caixas, ordenadas por nome no formato da tabela:

gcloud compute instances list \
  --format='table[box,title=Instances](name:sort=1,zone:label=zone,status)'

Liste o endereço de e-mail do usuário autenticado do projeto:

gcloud info --format='value(config.account)'

Para mais exemplos envolvidos dos recursos de configuração de saída criados nas sinalizações filters, formats e projections da CLI gcloud, consulte esta postagem do blog sobre filtragem e formatação.

Práticas recomendadas

Se você quiser que um script ou outra automação execute ações condicionalmente com base na saída de um comando da CLI da gcloud, observe o seguinte:

• Conte com o status de saída do comando.

  O status de saída diferente de zero indica que ocorreu um erro e a saída pode estar incompleta, a menos que a documentação do comando faça observações diferentes. Por exemplo, um comando que cria vários recursos só pode criar alguns, listá-los na saída padrão e acabar saindo com um status diferente de zero. Como alternativa, é possível usar a propriedade show_structured_logs para analisar os registros de erro. Execute gcloud config para mais detalhes.

• Não dependa de mensagens impressas para erro padrão.

  O texto dessas mensagens pode mudar em versões futuras da CLI gcloud e interromper a automação.

• Não dependa da saída bruta de mensagens impressas para saída padrão.

  A saída padrão de qualquer comando pode mudar em uma versão futura. É possível minimizar o impacto dessas alterações usando a sinalização --format para formatar a saída com uma das seguintes opções: --format=json|yaml|csv|text|list, para especificar valores a serem retornados. Execute gcloud topic formats para mais opções.

  É possível modificar a saída padrão de --format usando projections. Para mais granularidade, use a sinalização --filter para retornar um subconjunto dos valores com base em uma expressão. Crie um script para esses valores retornados.

  Exemplos de formatação e resultados de filtragem podem ser encontrados na seção abaixo.

Scripts de exemplo

Com a funcionalidade de formato e filtro, é possível combinar comandos da CLI gcloud em um script para extrair facilmente informações incorporadas.

Liste as chaves de todas as contas de serviço dos seus projetos

Os exemplos de scripts a seguir listam as chaves associadas a todas as contas de serviço dos seus projetos por:

• Iteração nos seus projetos
• Para cada projeto, como receber as contas de serviço associadas

• Para cada conta de serviço, acessar as chaves associadas

Bash

#!/bin/bash
for project in  $(gcloud projects list --format="value(projectId)")
do
  echo "ProjectId:  $project"
  for robot in $(gcloud iam service-accounts list --project $project --format="value(email)")
   do
     echo "    -> Robot $robot"
     for key in $(gcloud iam service-accounts keys list --iam-account $robot --project $project --format="value(name.basename())")
        do
          echo "        $key"
     done
   done
done

Windows PowerShell

Ou como Windows PowerShell:

foreach ($project in gcloud projects list --format="value(projectId)")
{
  Write-Host "ProjectId: $project"
  foreach ($robot in  gcloud iam service-accounts list --project $project --format="value(email)")
  {
      Write-Host "    -> Robot $robot"
      foreach ($key in gcloud iam service-accounts keys list --iam-account $robot --project $project --format="value(name.basename())")
      {
        Write-Host "        $key"
      }
  }
}

Analisar saída para processamento

O exemplo a seguir demonstra a análise da saída para processamento. Em particular, o script de amostra grava as informações da conta de serviço em uma matriz e segrega os valores no campo serviceAccounts.scope() formatado em CSV com vários valores:

#!/bin/bash
for scopesInfo in $(
    gcloud compute instances list --filter=name:instance-1 \
        --format="csv[no-heading](name,id,serviceAccounts[].email.list(),
                      serviceAccounts[].scopes[].map().list(separator=;))")
do
      IFS=',' read -r -a scopesInfoArray<<< "$scopesInfo"
      NAME="${scopesInfoArray[0]}"
      ID="${scopesInfoArray[1]}"
      EMAIL="${scopesInfoArray[2]}"
      SCOPES_LIST="${scopesInfoArray[3]}"

      echo "NAME: $NAME, ID: $ID, EMAIL: $EMAIL"
      echo ""
      IFS=';' read -r -a scopeListArray<<< "$SCOPES_LIST"
      for SCOPE in  "${scopeListArray[@]}"
      do
        echo "  SCOPE: $SCOPE"
      done
done