Comandos comuns da gcloud compute

Veja a seguir os exemplos de tarefas comuns ao trabalhar com instâncias. Para mais informações sobre como trabalhar com instâncias, consulte Instâncias de máquina virtual.

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 definirá a zona 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 create, são definidas como valores padrão. Acesse a ajuda do comando create para ver os valores padrão:

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, o seguinte comando retorna todas as instâncias cujos nomes começam com "my-".

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

Para mais informações sobre como listar e filtrar recursos, consulte Como buscar recursos.

Para retornar detalhes sobre uma instância, use o comando instances describe. Por exemplo, o seguinte comando retorna informações sobre "my-instance".

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

O comando anterior retorna os resultados no formato YAML. 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-se a instâncias

Use gcloud compute para se conectar às 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

Por padrão, os comandos gcloud compute ssh e gcloud compute scp 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 você já tiver uma chave privada que pretende usar ou se quiser utilizar diferentes chaves privadas com projetos variados.

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.
  • configurar o disco para não ser 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:

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 recursos de ajuda disponíveis, consulte a documentação de referência de gcloud topic.