gcloud compute

A ferramenta de linha de comando gcloud compute permite que você gerencie facilmente os recursos do Compute Engine em um formato mais amigável do que usando a API Compute Engine.

A ferramenta de linha de comando unificada gcloud faz parte do SDK do Cloud e inclui recursos, como preenchimento automático de instruções, atualização no local, ajuda extensiva em estilo de página de manual, formatos de saída legíveis por humanos e compatíveis com máquina e integração com o SDK do Cloud.

Se você nunca usou o Compute Engine, comece com um dos Guias de início rápido.

Instalar ou atualizar a gcloud compute

Configurar a gcloud compute

O Compute Engine usa o OAuth2 para autenticar e autorizar o acesso. Antes de usar gcloud compute, primeiro é necessário autorizar o SDK do Cloud a acessar o projeto no seu nome e adquirir um token de autenticação.

Se você estiver usando a ferramenta de linha de comando gcloud pela primeira vez, automaticamente gcloud usará a configuração default. Para a maioria dos casos, você só precisa da configuração default.

  1. Execute gcloud init para iniciar o processo de autenticação. Pressione Enter quando solicitado.

    O comando imprime um URL e tenta abrir uma janela do navegador para solicitar o acesso ao projeto. Se uma janela do navegador for aberta, será exibida a seguinte saída:

    gcloud init

    Welcome! This command will take you through the configuration of gcloud.

Your current configuration has been set to: [default]

...

To continue, you must login. Would you like to login (Y/n)?  y

Your browser has been opened to visit:

https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.co%2
Fauth%2Fappengine.admin+https%3A%2F%2...

    Se o SDK do Cloud detectar que um navegador não pode ser aberto (por exemplo, se você estiver trabalhando em uma máquina remota), será gerada a saída abaixo. Se você estiver trabalhando em uma máquina local e o navegador não carregar automaticamente o URL, tente o comando gcloud init novamente com a sinalização --console-only.

    gcloud init --console-only

    Copie o URL de autenticação e cole-o em um navegador. Em seguida, cole o código de verificação novamente no terminal.

    Go to the following link in your browser:

https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.co%2
Fauth%2Fappengine.admin+https%3A%2F%2...

Enter verification code:

  2. Conceda acesso.

    Na janela do navegador, revise as permissões do aplicativo e clique em Aceitar quando estiver pronto. Se você estiver trabalhando em uma máquina remota ou usar a sinalização --console-only, copie e cole o código retornado na linha de comando após a etapa Inserir código de verificação:. Caso contrário, o código será enviado automaticamente para a ferramenta de linha de comando.

  3. Escolha as credenciais para essa configuração.

    Depois de configurar suas credenciais, gcloud solicitará um projeto padrão para a configuração. Selecione um ID do projeto na lista.

    Depois de definir essa propriedade, todos os gcloud compute usarão o ID do projeto padrão, a não ser que você o substitua pela sinalização --project ou defina a variável de ambiente CLOUDSDK_CORE_PROJECT. Se você não definir um projeto ou variável de ambiente padrão, precisará incluir uma sinalização --project em cada comando gcloud compute que executar.

Defina uma zona ou região para trabalhar com os recursos que pertencem a uma zona ou região. Por exemplo, ao manipular uma instância de máquina virtual, é necessário especificar uma zona. Ao definir uma zona e uma região padrão, gcloud pode deduzir essas informações sem que você precise fornecê-las a cada solicitação. Sempre é possível substituir modificar ou alterar manualmente essas configurações padrão.

Para mais informações, leia Definir propriedades padrão.

Como usar configurações

gcloud usa o conceito de configurations para ajudar você a gerenciar suas credenciais de contas diferentes. Cada configuração contém a conta de e-mail usada para se autenticar e configurações específicas, como o ID do projeto padrão, a configuração de zona padrão e assim por diante. gcloud vem instalado automaticamente com uma configuração default. Essa é a configuração cujas credenciais serão usadas para autenticação nos serviços do Google Cloud.

Para a maioria dos usuários, é suficiente usar a configuração default. Se você tiver casos de uso que exijam a alternância entre contas, é possível criar mais configurações.

Leia gcloud topic configurations para ver informações detalhadas sobre como usar configurações.

Definir propriedades padrão

O servidor de metadados contém informações de metadados sobre um projeto, como ID, nome etc. Consulte o servidor de metadados para acessar e usar essas informações.

Se você especificar região e zona padrão para o projeto, o Compute Engine definirá esses valores no servidor de metadados do projeto.

As regiões e zonas padrão são definidas usando os seguintes valores:

  • google-compute-default-zone
  • google-compute-default-region

Para ver suas configurações padrão de região e zona, execute o seguinte comando gcloud:

gcloud compute project-info describe --project [PROJECT_ID]

em que [PROJECT_ID] é o ID do projeto.

Procure as seguintes chaves e valores de metadados na resposta:

- key: google-compute-default-region
  value: ...
- key: google-compute-default-zone
  value: ..

Se os valores e as chaves google-compute-default-region e google-compute-default-zone estiverem ausentes na resposta, é porque não foi feita a definição de nenhuma zona padrão ou região.

  • Se nenhum padrão for definido, gcloud solicitará uma região e zona em cada solicitação.
  • Se um padrão for definido, gcloud usará automaticamente o valor padrão para todos as solicitações gcloud feitas, a não ser que você modifique as configurações padrão manualmente.

Para alterar, definir ou substituir as propriedades padrão, use os métodos abaixo.

Alterar sua zona e região padrão no servidor de metadados

Faça uma solicitação ao servidor de metadados para alterar as respectivas zona e região padrão. Exemplo:

gcloud compute project-info add-metadata \
    --metadata google-compute-default-region=europe-west1,google-compute-default-zone=europe-west1-b

Novas alterações de zona e região padrão serão detectadas pela ferramenta de linha de comando gcloud somente depois de você executar novamente o comando gcloud init. Depois de atualizar seus metadados padrão, execute gcloud init para reinicializar sua configuração default.

Definir a zona e a região padrão no seu cliente local

É possível escolher manualmente uma zona ou região diferente, sem atualizar o servidor de metadados. Basta definir essas propriedades localmente no seu cliente gcloud.

Primeiro, certifique-se de usar a configuração para que você pretende definir essas propriedades. Cada configuração tem suas próprias definições. Para alternar entre as configurações, execute:

gcloud config configurations activate CONFIGURATION_NAME

Depois, para definir uma propriedade de zona ou região no cliente, execute:

gcloud config set compute/zone ZONE

gcloud config set compute/region REGION

Para remover completamente uma propriedade padrão, use o comando unset.

gcloud config unset compute/zone

gcloud config unset compute/region

Observe que a remoção completa da propriedade padrão resultará na solicitação gcloud de uma zona ou região para cada comando executado.

Definir valores padrão em variáveis de ambiente

É possível definir variáveis de ambiente que forneçam valores para comandos gcloud compute. As variáveis de ambiente substituem as propriedades padrão definidas com os comandos gcloud config, mas não substituem as sinalizações explícitas, como --zone ou --region.

Linux/macOS
Use o comando export para definir as variáveis de zona e região.
$ export CLOUDSDK_COMPUTE_ZONE=ZONE
$ export CLOUDSDK_COMPUTE_REGION=REGION
Para tornar essas variáveis de ambiente permanentes, inclua esses comandos no arquivo ~/.bashrc e reinicie o terminal.
Windows
Use o comando set para definir as variáveis de zona e região.
C:\> set CLOUDSDK_COMPUTE_ZONE=ZONE
C:\> set CLOUDSDK_COMPUTE_REGION=REGION

É possível substituir as variáveis de ambiente por meio da inclusão de sinalizações específicas --zone ou --region com seus comandos.

Definir valores em cada solicitação

É possível substituir as propriedades padrão por meio da inclusão de sinalizações específicas --zone ou --region com cada um dos comandos. Exemplo:

gcloud compute instances create example-instance --zone us-central1-f

Essas sinalizações funcionam somente para o único comando que você usa. Elas não alteram suas configurações padrão, mas as modificam para essa solicitação.

Ordem de precedência para propriedades padrão

A ferramenta de linha de comando gcloud avalia propriedades padrão na seguinte ordem, para cada configuração:

  • Se você fornecer uma sinalização explícita --zone ou --region ou --project, todas as outras configurações da solicitação única serão substituídas.
  • Se as propriedades padrão de zona e região forem definidas somente no servidor de metadados, a ferramenta de linha de comando gcloud fará a configuração do cliente local da gcloud para essas propriedades quando você executar gcloud init. Para as solicitações subsequentes, a ferramenta solicitará a zona.
  • Se as propriedades da zona e região padrão forem definidas em ambos no servidor de metadados e no cliente local para essa configuração, a ferramenta usará as propriedades padrão no cliente local.
  • Se as propriedades de zona e região padrão forem definidas no servidor de metadados, no cliente local e nas variáveis de ambiente, a ferramenta usará as propriedades padrão nas variáveis de ambiente, independentemente da configuração usada por você.

Comandos comuns da gcloud compute

Abaixo estão exemplos de tarefas comuns ao trabalhar com instâncias. Para mais detalhes sobre como trabalhar com instâncias, consulte Instâncias.

Criar instâncias

Use o comando instances create para criar uma nova instância. Por exemplo, o comando a seguir cria uma instância denominada "my-instance" na zona "us-central1-a".

gcloud compute instances create my-instance

Se você omitir a sinalização --zone, a gcloud poderá inferir a zona pretendida com base nas suas propriedades padrão.

Outras configurações de instâncias obrigatórias, como tipo de máquina e imagem, quando não especificadas no comando de criação, são definidas como valores padrão. É possível ver os valores padrão ao exibir a ajuda para o comando create command:

gcloud compute instances create --help

Listar instâncias

Há várias maneiras de listar suas instâncias usando o comando instances list. Crie uma saída tabular legível com o comando a seguir:

gcloud compute instances list

Use expressões regulares para restringir a lista de instâncias retornadas pelo nome. Por exemplo, todas as instâncias que tenham nomes iniciados com "my-" são retornadas com o seguinte comando.

gcloud compute instances list --filter="name ~ ^my-.*"

Para mais informações sobre recursos de listagem e filtragem, consulte Como buscar recursos.

Para retornar detalhes sobre uma instância, use o comando instances describe. Por exemplo, informações sobre "my-instance" são retornadas com comando a seguir.

gcloud compute instances describe my-instance --zone us-central1-a

Os resultados no formato YAML são retornados com o comando anterior. Para alterar como os resultados são exibidos, use a sinalização --format. Para mais exemplos de como receber e listar recursos, inclusive instâncias, consulte Como buscar recursos.

Conectar a instâncias

gcloud compute facilita a conexão com suas instâncias. Os comandos gcloud compute ssh e gcloud compute scp fornecem wrappers em torno do SSH e do SCP, que tratam da autenticação e do mapeamento do nome da instância para o endereço IP.

Por exemplo, para ssh em "my-instance" na zona "us-central1-a", é possível usar:

gcloud compute ssh my-instance --zone us-central1-a

Para copiar o arquivo local "file-1" para "my-instance" na zona "us-central1-a", use:

gcloud compute scp ~/file-1 my-instance:~/remote-destination --zone us-central1-a

O comando scp também pode ser usado para copiar arquivos de uma instância para sua máquina local. Por exemplo, para criar uma cópia local de "file-1", que está na instância "my-instance", na zona "us-central1-a", use:

gcloud compute scp my-instance:~/file-1 ~/local-destination --zone us-central1-a

Os comandos gcloud compute ssh e gcloud compute scp, por padrão, usam o arquivo de chave privada localizado em "~/.ssh/google_compute_engine". Se não quiser usar esse arquivo de chave, defina outro especificando um local diferente com a sinalização --ssh-key-file. Por exemplo, se já tiver uma chave privada que pretenda usar ou se quiser utilizar diferentes chaves privadas com diferentes projetos.

Como usar diretamente programas baseados em SSH

Se preferir usar diretamente ssh e scp, gcloud compute gere um arquivo de configuração SSH contendo aliases de host para suas instâncias com a configuração de autenticação. Para fazer isso, execute:

gcloud compute config-ssh

Aqui está um exemplo de um alias adicionado ao arquivo de configuração SSH (~/.ssh/config):

Host my-instance.us-central1-a.myproject
HostName 107.178.220.224
IdentityFile ~/.ssh/google_compute_engine
UserKnownHostsFile=/dev/null
CheckHostIP=no
StrictHostKeyChecking=no

É possível especificar um arquivo de configuração SSH alternativo, por usuário, usando a sinalização --ssh-config-file.

Sempre que você adicionar ou remover uma instância, execute o comando config-ssh novamente.

Depois de atualizar os arquivos de configuração SSH com o comando config-ssh, é possível usar qualquer programa baseado em SSH para acessar suas instâncias. Por exemplo, para a instância chamada "my-instance", na zona "us-central1-a", no projeto denominado "myproject", use o cliente ssh do OpenSSH da seguinte maneira:

$ ssh my-instance.us-central1-a.myproject

Para fazer uma cópia local do arquivo "file-1" na instância, use o cliente scp da seguinte maneira:

$ scp my-instance.us-central1-a.myproject:~/file-1 .

Como trabalhar com metadados

É possível definir metadados personalizados para uma instância ou projeto fora dos metadados definidos pelo servidor. Isso é útil para transmitir valores arbitrários ao projeto ou instância que podem ser consultados pelo seu código na instância. Esta seção apresenta algumas operações comuns de metadados. Para saber mais informações sobre como trabalhar com metadados, consulte Armazenamento e recuperação de metadados.

Como adicionar e remover metadados de instância

É possível configurar metadados de instância com gcloud compute ao criar uma instância usando o create ou com uma instância atual, usando os comandos add-metadata e remove-metadata. Metadados são especificados como pares chave/valor separados por um sinal de igual ("=") usando a sinalização --metadata. Os metadados também podem ser lidos de um arquivo local usando a sinalização --metadata-from-file.

Por exemplo, para adicionar as teclas de metadados personalizadas "role", "unique-id" e "build-num" a uma instância atual chamada "my-instance" na zona "us-central1-a", use:

gcloud compute instances add-metadata my-instance \
    --zone us-central1-a \
    --metadata role=worker unique-id=1234 build-num=4.32

Para remover as chaves de metadados personalizadas "role" e "unique-id", use:

gcloud compute instances remove-metadata my-instance \
    --zone us-central1-a \
    --keys role unique-id

Para ver as mudanças depois de adicionar e remover metadados em uma instância atual, execute:

gcloud compute instances describe my-instance --zone us-central1-a

...
metadata:
  fingerprint: eU448B6JGQw=
  items:
  - key: build-num
    value: '4.32'
  kind: compute#metadata
...

Para alterar os metadados atuais ou adicionar novos, use o comando add-metadata. As atualizações de metadados de instância são aditivas. Isso significa que só é preciso especificar as chaves de metadados a serem adicionadas ou alteradas. Se você especificar uma chave atual, o valor da chave será atualizado com o novo valor.

Para as imagens que tenham ferramentas do Compute Engine instaladas, há duas chaves de metadados reservadas para a funcionalidade de script de inicialização:

  • startup-script: indica o conteúdo do script que é executado quando a instância é iniciada. Para um conteúdo de script mais longo, use a sinalização --metadata-from-file para transferir um caminho para um arquivo em que está o conteúdo do script.
  • startup-script-url: indica que um script no local especificado publicamente acessível é executado quando a instância é iniciada.

Por exemplo, para criar uma instância chamada "my-instance" na zona "us-central1-a", com o conteúdo do script de inicialização especificado com a sinalização --metadata, use:

gcloud compute instances create my-instance --zone us-central1-a \
    --metadata startup-script="echo 'hello world'"

Se você inserir SSH em "my-instance" e verificar o registro do sistema (/var/log/syslog), será exibido o resultado do script de inicialização.

No caso de uma instância atual chamada "my-instance", é possível adicionar o seguinte script de inicialização de um arquivo local usando a sinalização --metadata-from-file:

gcloud compute instances add-metadata my-instance \
    --metadata-from-file startup-script=/local/path/to/script/startup

Neste exemplo, o script de inicialização é executado quando a instância é reinicializada, por exemplo, quando você usa gcloud compute instances reset.

Como adicionar e remover metadados do projeto

Os metadados do projeto são acessados por todas as instâncias em um projeto. Por padrão, um projeto tem metadados reservados de projeto. Também é possível adicionar e remover metadados personalizados do projeto. Assim como os metadados de instâncias, as atualizações de metadados do projeto são aditivas. Isso significa que só é preciso especificar as chaves de metadados a serem adicionadas ou alteradas. Se você especificar uma chave atual, o valor da chave será atualizado com o novo valor.

Para ver os metadados atuais no nível do projeto, use o comando project-info describe:

gcloud compute project-info describe

O comando a seguir adiciona dois metadados do projeto inteiro.

gcloud compute project-info add-metadata \
    --metadata-from-file startup-script=/local/path/to/script
    --metadata startup-id=1234

Lembre-se de que a chave startup-script é reservada, o conteúdo do arquivo local especificado deve ser executado no início das instâncias.

Para remover os dois metadados que você acabou de adicionar, use:

gcloud compute project-info remove-metadata --keys startup-script startup-id

Como excluir instâncias

Para excluir a instância chamada "my-instance", na zona "us-central1-a", use o comando instances delete:

gcloud compute instances delete my-instance --zone us-central1-a

Quando você cria uma instância, um disco permanente também é criado. Esse disco entra na cota de disco permanente e está sujeito a taxas mensais. O comando instances delete para excluir uma instância, por padrão remove o disco permanente associado à instância. Para modificar tal comportamento, é possível:

  • Use a sinalização --keep-disks do comando instances delete.
  • Configure o disco para que não seja excluído automaticamente. Depois de criar uma instância e a qualquer momento antes de excluir instâncias, use o comando instances set-disk-auto-delete para preservar o disco permanente. Observe que a sinalização --delete-disks do comando instances delete excluirá os discos, independentemente da configuração de exclusão automática.

Para mais informações, consulte Como configurar o estado de remoção automática de um disco permanente.

Listar operações

Operações são um registro das alterações nos recursos do Compute Engine. Para ver uma lista de todas as operações em um projeto, use o comando operations list:

gcloud compute operations list

As operações têm escopos que podem ser usados para restringir as operações retornadas em uma solicitação de lista. Por exemplo, é possível usar as sinalizações --global, --zones e --regions para refinar resultados. O comando a seguir retorna apenas as operações nas zonas us-central1-a e us-central1-b:

gcloud compute operations list --filter="zone:(us-central1-a us-central1-b)"

Para mais exemplos de como receber e listar recursos, inclusive de operações, consulte Como buscar recursos.

Como acessar páginas de ajuda

Use os comandos a seguir para saber como acessar diferentes tipos de ajuda, desde a ajuda geral sobre o comando gcloud compute até a ajuda específica sobre um grupo de recursos (instances) ou um comando (create). A ajuda abrangente para todos os recursos e comandos segue esse padrão:

gcloud compute --help

gcloud compute instances --help

gcloud compute instances create --help

É possível receber ajuda rápida usando a sinalização -h em vez da sinalização --help. Revise toda a ajuda abrangente em Referência do SDK do Cloud.

Para receber ajuda abrangente relativa aos comandos específicos de configuração da ferramenta gcloud, execute:

gcloud topic TOPIC

Em que TOPIC é o tópico aplicável que você quer ajuda. Para ver uma lista de tópicos que têm ajuda disponível, consulte a documentação de referência de gcloud topic.

A seguir

É isso aí. Você agora pode começar a usar a ferramenta gcloud compute. Estas são algumas ideias para ajudá-lo a dar os primeiros passos: