Visão geral da ferramenta de linha de comando gcloud

Esta página apresenta uma visão geral da ferramenta de linha de comando gcloud, os padrões de comando comuns e as peculiaridades dela.

O que é a ferramenta de linha de comando gcloud?

A interface da linha de comando do gcloud é uma ferramenta que fornece a CLI principal ao Google Cloud Platform. É possível usar essa ferramenta para realizar muitas tarefas de plataforma comuns pela linha de comando ou em scripts e outras automações.

Por exemplo, use a CLI da gcloud para criar e gerenciar:

  • instâncias de máquina virtual do Google Compute Engine e outros recursos
  • instâncias do Google Cloud SQL
  • clusters do Google Kubernetes Engine
  • clusters e jobs do Google Cloud Dataproc
  • zonas gerenciadas DNS e conjuntos de registros do Google Cloud
  • implantações do Google Cloud Deployment Manager

Também é possível usar a CLI da gcloud para implantar aplicativos do App Engine e executar outras tarefas. Leia a referência da CLI da gcloud para saber mais sobre os recursos dessa ferramenta.

A CLI da gcloud e o SDK do Cloud

A CLI do gcloud faz parte do SDK do Google Cloud. Faça o download e a instalação do SDK no sistema e inicialize-o antes de usar a ferramenta de linha de comando gcloud.

Por padrão, o SDK instala esses comandos da CLI da gcloud que estão apenas nos níveis de disponibilidade geral e visualização. Há outras funcionalidades disponíveis nos componentes do SDK chamados alpha e beta. Esses componentes permitem usar a CLI do gcloud para trabalhar com o Google Cloud Bigtable, o Google Cloud Dataflow e outras partes do Cloud Platform em versões anteriores à de disponibilidade geral.

As versões da CLI do gcloud têm o mesmo número de versão que o SDK. A versão atual do SDK é 245.0.0. Faça o download e a instalação de versões anteriores do SDK a partir do arquivo de downloads.

Como fazer o download da ferramenta de linha de comando gcloud

É possível fazer o download da versão mais recente do SDK do Cloud, que inclui a ferramenta de linha de comando gcloud, na página de download.

Níveis de versão

Os comandos da CLI da gcloud têm os seguintes níveis de versão:

Nível de versão Rótulo Descrição
Disponibilidade geral Nenhum Os comandos são considerados totalmente estáveis e disponíveis para uso da produção. São exibidos alertas para comandos que interrompem a funcionalidade atual e estão documentados nas notas da versão.
Beta beta Os comandos estão funcionalmente completos, mas ainda têm alguns problemas pendentes. Nesses comandos, as alterações importantes podem ser feitas sem aviso prévio.
Alfa alpha Os comandos estão na versão inicial e podem mudar sem aviso.
Visualização preview Os comandos podem ser instáveis e mudar sem aviso.

Quando o SDK é instalado, os componentes alpha e beta não são instalados por padrão. Instale-os separadamente usando o comando gcloud components install. Se você tentar executar um comando alfa ou beta e o componente correspondente não estiver instalado, a ferramenta de linha de comando gcloud solicitará a instalação.

Grupos de comandos

Em cada nível de versão, os comandos da CLI da gcloud são organizados em uma hierarquia aninhada de grupos de comando, cada um representando um produto ou recurso do Cloud Platform ou seus subgrupos funcionais.

Exemplo:

Grupo de comandos Descrição
gcloud compute Comandos relacionados ao Compute Engine em disponibilidade geral
gcloud compute instances Comandos relacionados a instâncias do Compute Engine em disponibilidade geral
gcloud beta compute Comandos relacionados ao Compute Engine em Beta
gcloud alpha app Comandos relacionados ao gerenciamento de implantações do App Engine em Alfa

Como executar comandos da CLI da gcloud

É possível executar comandos da CLI da gcloud a partir da linha de comando da mesma maneira que usa outras ferramentas de linha de comando. Também é possível executar comandos da CLI do gcloud a partir de scripts e outras automações. Por exemplo, ao usar o Jenkins para automatizar tarefas do Cloud Platform.

Propriedades

As propriedades da CLI da gcloud são configurações que afetam o comportamento da CLI da gcloud e de outras ferramentas do SDK do Cloud. Algumas dessas propriedades podem ser definidas por sinalizações globais ou de comando. Nesse caso, o valor definido pela sinalização tem precedência.

Encontre uma lista de propriedades disponíveis neste link.

Configurações

Uma configuração é um conjunto nomeado de propriedades da CLI da gcloud. Essencialmente, elas funcionam como um perfil.

Ao começar a usar o Cloud SDK, você trabalhará com uma única configuração chamada default e poderá definir propriedades com gcloud init ou gcloud config set. Essa configuração padrão única é adequada para a maioria dos casos de uso.

Se quiser trabalhar com vários projetos ou contas de autorização, você poderá definir várias configurações com gcloud config configurations create e alternar entre elas quando preciso.

Para uma descrição detalhada desses conceitos, consulte as explorações de configurações e seu gerenciamento.

Sinalizações globais

A CLI da gcloud fornece um conjunto de sinalizações da CLI da gcloud que controlam o comportamento dos comandos a cada invocação. As sinalizações substituem todos os valores configurados nas propriedades do SDK.

Sinalizações e argumentos posicionais

Tanto as sinalizações quanto os argumentos posicionais afetam a saída de um comando da CLI da gcloud, mas há uma diferença sutil entre os casos de uso de cada um. O argumento posicional é usado para definir uma entidade em que um comando opera. Já a sinalização é necessária para definir uma variação no comportamento de um comando.

Uso de stdout e stderr

A saída bem-sucedida dos comandos da CLI da gcloud é gravada em stdout. Todos os outros tipos de resposta, como solicitações, avisos e erros, são gravados em stderr. Observe que as gravações em stderr não são estáveis e não devem ser usadas novamente em scripts.

Para ver uma lista definitiva de diretrizes sobre o gerenciamento de saída, leia esta seção.

Solicitações de prompt ou confirmação

Para proteger você contra ações destrutivas não desejadas, a CLI da gcloud confirmará suas intenções antes de executar comandos como gcloud projects delete.

Você também verá uma solicitação de prompt quando criar uma instância de máquina virtual do Google Compute Engine. Para criar uma instância de teste, use gcloud compute instances create test-instance. Será necessário escolher uma zona para criar a instância.

Para desativar as solicitações, use a sinalização --quiet.

Observe que o texto dos prompts pode mudar e não deve ser usado em scripts.

Como suprimir solicitações, gravar no terminal e gerar registros

A sinalização --quiet (também, -q) para a CLI do gcloud desativa todos os prompts interativos ao executar os comandos da CLI do gcloud e é útil quando há scripts. Caso uma entrada seja necessária, os padrões serão usados. Se não houver um padrão, será exibido um erro.

Para suprimir a impressão da saída do comando para a saída e o erro padrão no terminal, use a sinalização --no-user-output-enabled.

Para ajustar o nível de detalhamento dos registros, use a sinalização --verbosity e defina o nível apropriado.

Como determinar a estrutura da saída

Por padrão, quando um comando da CLI da gcloud retorna uma lista de recursos, eles tem estilo formatado para a saída padrão. Para produzir resultados mais significativos, ajuste a saída com as sinalizações de formato, filtro e projeção.

Se você quiser definir apenas o formato de sua saída, use a sinalização --format para produzir uma versão tabulada ou simplificada da saída (para tela interativa) ou uma versão da saída legível por máquina (json, csv, yaml, value).

Se quiser formatar uma lista de chaves para selecionar valores de dados de recursos, use projections. Para refinar ainda mais a saída, definindo seus próprios critérios, use filter.

Se você quiser ver um tutorial interativo rápido para se familiarizar mais rapidamente com os recursos de filtro e formato, siga o link abaixo.

Abrir no Cloud Shell

A seguir