Como realizar o script de comandos da CLI da gcloud

Além de executar os comandos da CLI da gcloud a partir da linha de comando, também é possível executá-los a partir de scripts ou outras automações. Por exemplo, ao usar o Jenkins para orientar a automação das tarefas do Google Cloud Platform.

O SDK do Cloud vem com uma variedade de ferramentas, como filtragem, formatação e a sinalização --quiet, permitindo que você gerencie efetivamente a saída e automatize tarefas.

Princípios básicos de script com o SDK do Cloud

Se você quer um guia passo a passo sobre como criar scripts básicos com a ferramenta de linha de comando gcloud, consulte este guia para iniciantes sobre como automatizar tarefas do GCP.

autorização

Ao criar scripts com o SDK do Cloud, você precisará considerar métodos de autorização. O SDK do Cloud 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 do Cloud SDK:

    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. Também é o método de autorização recomendado se você estiver executando comandos da CLI da gcloud em uma instância de máquina virtual do Google Compute Engine em que todos os usuários tenham acesso ao root.

Para usar a autorização de conta de serviço, use uma conta de serviço atual ou crie uma nova no Console do Google Cloud Platform. Na coluna de opções da tabela de contas de serviço, crie e faça o download da chave privada associada como arquivo de chave formatado para JSON.

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

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

É possível usar o SSH em 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 do Cloud SDK, confira nosso guia completo.

Como 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. É possível desativar solicitações de comandos da CLI da gcloud definindo a propriedade disable_prompts na sua configuração para True ou usando as sinalizações --quiet ou -q globais. 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.

Por exemplo:

    gcloud debug targets list --quiet

Como filtrar e formatar uma saída

Para criar scripts com a ferramenta de linha de comando gcloud, é importante ter uma saída previsível. É nisso que as sinalizações --filter e --format ajudam. Eles garantem que, quando você executa um comando usando a ferramenta de linha de comando gcloud, produz saída que adere à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:

Abrir no Cloud Shell

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 à chave createTime após a definição de formatação de datas.

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:title=zone,status)'

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

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

Mais exemplos envolvidos dos recursos de configuração de saída incorporados nas sinalizações filters, formats e projections da CLI da gcloud podem ser encontradas nesta 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 da 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 maior 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, combine comandos da CLI do gcloud em um script para extrair facilmente informações integradas.

Para listar todas as chaves associadas a todas as contas de serviço do seu projeto, incremente todos os seus projetos e, para cada projeto, receba todas as contas de serviço associadas a ele. Para cada conta de serviço, receba todas as chaves. Isso pode ser realizado das seguintes formas:

Como um script 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

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"
      }
  }
}

Às vezes, você precisará analisar a saída para processamento. Por exemplo, seria útil gravar as informações da conta de serviço em uma matriz e separar os valores no campo serviceAccounts.scope() formatado em CSV com valores múltiplos. O script abaixo realiza essa ação:

#!/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