Como escrever scripts de comandos da ferramenta gcloud

Além de executar comandos da ferramenta de linha de comando gcloud na linha de comando, é possível executá-los usando scripts ou outras automações, por exemplo, ao usar o Jenkins para fins de automação das tarefas do Google Cloud.

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

Para ver um guia passo a passo de como criar scripts básicos usando a ferramenta gcloud, consulte este guia de introdução à automatização de tarefas do Google Cloud.

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 ferramenta gcloud em uma instância de máquina virtual do Compute Engine em que todos os usuários têm 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".

Acessar 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, 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.

Desativar prompts

Alguns comandos da ferramenta gcloud são interativos e solicitam que os usuários confirmem uma operação ou solicitem outra entrada 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 dos comandos da ferramenta 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.

Por exemplo:

    gcloud debug targets list --quiet

Como filtrar e formatar uma saída

Para criar um script com a ferramenta gcloud, é importante ter uma saída previsível. É aqui que as sinalizações --filter e --format ajudam. Eles garantem que, quando você executar um comando usando a ferramenta gcloud, ele produza uma saída que cumpra o formato (como json, yaml, csv e texto) e o filtro (nomes de VM prefixados). com especificações de "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 ferramenta 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:label=zone,status)'

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

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

Exemplos mais envolvidos da saída configurando recursos criados na ferramenta filters, formats e projections da ferramenta gcloud As sinalizações do 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 ferramenta 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 ferramenta 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

Usando a funcionalidade de formato e filtro, você pode combinar comandos da ferramenta gcloud em um script para extrair facilmente informações incorporadas.

Se você listar todas as chaves associadas a todas as contas de serviço dos seus projetos, precisará iterar todos os seus projetos e, para cada projeto, receber todas as contas de serviço associadas a eles. Para cada conta de serviço, consiga 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