gcloud compute

A ferramenta de linha de comando gcloud permite gerenciar os recursos do Compute Engine usando o grupo de comandos gcloud compute. gcloud compute é uma alternativa ao uso da 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 da linha de comando e formatos de saída legíveis por humanos e compatíveis com máquina, além da integração com o SDK do Cloud.

Se você nunca usou o Compute Engine, confira o Guia de início rápido do Linux ou o Guia de início rápido do Windows.

Antes de começar

  • Se você quiser executar gcloud compute em um prompt de comando, instale, atualize e inicialize o SDK do Cloud.
  • Se você não tiver um prompt de comando disponível, tente usar gcloud compute no Cloud Shell. O Cloud Shell é instalado, atualizado e inicializado automaticamente com o SDK do Cloud mais recente.

Propriedades padrão

O servidor de metadados contém informações de metadados sobre um projeto, como ID, nome etc. Use a ferramenta de linha de comando gcloud para consultar o servidor de metadados para receber e usar as informações sobre o projeto.

Ver as propriedades padrão

Para ver quais são suas propriedades padrão, execute o comando a seguir usando a ferramenta de linha de comando gcloud. Substitua PROJECT_ID pelo ID do projeto.

gcloud compute project-info describe --project PROJECT_ID

Ver a região e a zona padrão

Para ver quais são suas configurações de região e zona padrão, execute os comandos a seguir:

gcloud config get-value compute/zone
gcloud config get-value compute/region

Se as respostas google-compute-default-region ou google-compute-default-zone forem (unset), isso significará que nenhuma zona ou região padrão foi definida.

  • Se nenhum padrão for definido, a ferramenta gcloud solicitará uma região e zona com cada solicitação.

  • Se um padrão for definido, a ferramenta gcloud usará automaticamente o valor padrão para todas as solicitações da ferramenta 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

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

Defina regiões e zonas padrão usando:

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

Por 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 estar usando a configuração que pretende definir essas propriedades. Cada configuração tem as próprias configurações. Para alternar entre elas, execute o seguinte comando:

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 remover totalmente a propriedade padrão fará com que a ferramenta gcloud solicite uma zona ou região para cada comando que você executar.

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 projeto, zona e região. 
export CLOUDSDK_CORE_PROJECT=PROJECT
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 projeto, zona e região. 
C:\> set CLOUDSDK_CORE_PROJECT=PROJECT
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. Por 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, --region ou --project, todas as outras configurações da solicitação serão substituídas pela sinalização.
  • 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 gcloud solicitará a zona.
  • Se as propriedades de zona e região padrão forem definidas tanto no servidor de metadados quanto no cliente local para essa configuração, a ferramenta gcloud 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 gcloud usará as propriedades padrão nas variáveis de ambiente, independentemente da configuração usada por você.

Como usar as configurações

gcloud topic configurations é um recurso avançado que pode ser usado para influenciar o comportamento da ferramenta gcloud. Para a maioria dos usuários, o uso das configurações padrão é suficiente.

As configurações podem ser úteis para usuários que:

  • trabalhem com vários projetos. É possível criar uma configuração separada para cada projeto;
  • usem várias contas. Por exemplo, uma conta de usuário e uma conta de serviço;
  • executem várias tarefas independentes (trabalham em um aplicativo do App Engine em um projeto, administram um cluster do Compute Engine na zona us-central-1a, gerenciam as configurações de rede para a região asia-east-1 etc.).

Para gerenciar suas configurações, consulte gcloud config configurations.

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 ferramenta 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.

Como se 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 todo o conteúdo de ajuda abrangente em Referência do SDK do Cloud.

Para ver informações detalhadas sobre os comandos específicos de configuração da ferramenta gcloud, execute:

<pre class="devsite-click-to-copy>gcloud topic <var>TOPIC</var></pre>

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