gcloud compute

Com a ferramenta de linha de comando gcloud compute, é possível gerenciar facilmente os recursos do Google Compute Engine em um formato mais amigável do que com a Compute Engine API.

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

Se ainda não ativou o Google Compute Engine, siga as etapas de inscrição. Também recomendamos rever os Guias de primeiros passos.

Instalar o gcloud compute

Para instalar o gcloud compute, faça a instalação do Google Cloud SDK.

Configurar o gcloud computing

O Google Compute Engine usa o OAuth2 para autenticar e autorizar o acesso. Antes de usar o gcloud compute, autorize o Cloud SDK para acessar seu projeto e conseguir um token de autenticação.

Para usar a ferramenta de linha de comando gcloud pela primeira vez, o gcloud usa automaticamente a configuração default. Para a maioria dos casos, a configuração default é suficiente.

  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 Cloud SDK não puder abrir um navegador (por exemplo, você está trabalhando em uma máquina remota), a saída abaixo será exibida. Ou então, se estiver trabalhando em uma máquina local e o navegador não carregar automaticamente o URL, use novamente o comando gcloud init 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. Para trabalhar em uma máquina remota ou usar uma sinalização --console-only, copie e cole o código retornado na linha de comando após 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, o gcloud solicita um projeto padrão para essa configuração. Selecione um código do projeto na lista.

    Após definir essa propriedade, todos os comandos gcloud compute usarão o código do projeto padrão, a menos que você os modifique com a sinalização --project ou defina a variável de ambiente CLOUDSDK_CORE_PROJECT. Se você não definir um projeto padrão ou variável de ambiente, será necessário incluir uma sinalização --project em cada comando gcloud compute executado.

Ao executar o gcloud pela primeira vez, ele também define uma zona e região padrão com base na zona padrão e nas chaves da região nos metadados do seu projeto. 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). Para configurar uma zona e região padrão, o gcloud pode inferir essa informação sem exigir que você a forneça em cada solicitação. Sempre é possível alterar ou modificar manualmente essas configurações padrão.

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

Como usar configurações

O gcloud usa o conceito configurations para gerenciar suas credenciais para diferentes contas. Cada configuração contém a conta de e-mail a ser autenticada e as configurações específicas, como o código do projeto padrão, a configuração de zona padrão e assim por diante. O gcloud já vem automaticamente instalado com uma configuração default. Essa é a configuração cujas credenciais serão usadas para autenticação nos serviços do Google Cloud Platform.

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

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

Definir propriedades padrão

Atualmente, quando você cria um projeto e usa o gcloud pela primeira vez, o Compute Engine escolhe uma zona e região padrão com base nas informações dos metadados do projeto e define essa propriedade como a configuração default. Essas propriedades padrão podem ser vistas nas informações de metadados sobre o projeto:

gcloud compute project-info describe

Procure as seguintes chaves de metadados:

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

Se essas propriedades não são alteradas nem modificadas, o gcloud as fornece automaticamente para todas as solicitações do gcloud que você fizer. Para alterar ou modificar essas propriedades, 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 a zona e a região padrão. Por exemplo:

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

A ferramenta de linha de comando gcloud utiliza as novas alterações da zona e região padrão após você executar novamente o comando gcloud init. Depois de atualizar os metadados padrão, execute o gcloud init para reinicializar a configuração default.

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

Escolha manualmente uma zona ou região diferente sem atualizar o servidor de metadados, configurando essas propriedades localmente no cliente gcloud.

Primeiro, certifique-se de estar usando a configuração que 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 remover totalmente a propriedade padrão fará com que o gcloud solicite uma zona ou região para cada comando que você executar.

Definir valores padrão em variáveis de ambiente

Configure variáveis de ambiente que fornecem valores aos comandos do gcloud compute. Essas variáveis modificam as propriedades padrão configuradas com os comandos gcloud config, mas não as sinalizações explícitas, como --zone ou --region.

Linux/Mac OS X
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 estes 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

Modifique as variáveis de ambiente incluindo as sinalizações --zone ou --region específicas junto com os comandos.

Definir valores em cada solicitação

Para modificar as propriedades padrão, inclua as sinalizações --zone ou --region específicas em 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 as propriedades padrão na seguinte ordem para cada configuração:

  • Se você fornecer uma sinalização explícita --zone ou --region ou --project, ela modificará todas as outras configurações para essa única solicitação.
  • Quando as propriedades da zona e da região padrão são definidas apenas no servidor de metadados, a ferramenta de linha de comando gcloud configura o cliente gcloud local para essas propriedades ao executar o 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 do 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, o gcloud vai deduzir a zona escolhida com base nas propriedades padrão.

Outras configurações de instâncias obrigatórias, como tipo de máquina e imagem, quando não especificadas no comando "criar", são definidas como valores padrão. Acesse a ajuda do create command para ver os valores padrão:

gcloud compute instances create --help

Listar instâncias

Há diversas maneiras de listar instâncias usando o comando instances list. Crie uma saída tabular legível com o seguinte comando:

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 --regexp my-.*

Para mais informações sobre como trabalhar com a sinalização --regexp e usar expressões regulares, 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. Use a sinalização --format para alterar a forma como os resultados são exibidos. Para mais exemplos de como receber e listar recursos, inclusive instâncias, consulte Como buscar recursos.

Conectar a instâncias

O gcloud compute facilita a conexão com instâncias. Os comandos gcloud compute ssh e gcloud compute scp fornecem wrappers em torno do SSH e SCP, que são responsáveis pela a autenticação e associação do nome da instância ao 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 é 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 particular localizado no "~/.ssh/google_compute_engine". Se não quiser usar esse arquivo de chave, especifique uma localização diferente com a sinalização --ssh-key-file para utilizar outro arquivo de chave. Por exemplo, se já tiver uma chave privada que pretende usar, ou se quiser utilizar diferentes chaves privadas com diferentes projetos.

Como usar diretamente programas baseados em SSH

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

gcloud compute config-ssh

Veja o 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

Especifique um arquivo de configuração SSH alternativo, por usuário, usando a sinalização --ssh-config-file.

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

Depois de atualizar os arquivos de configuração SSH com o comando config-ssh, use qualquer programa baseado em SSH para acessar as 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 mais detalhes sobre como trabalhar com metadados, consulte Como armazenar e recuperar metadados.

Como adicionar e remover metadados de instância

Configure metadados de instância com o gcloud compute quando criar uma instância usando o comando create ou com uma instância existente, usando os comandos add-metadata e remove-metadata. Os metadados são especificados como pares de chave-valor separados com um sinal de igual ("=") usando a sinalização --metadata. Os metadados também podem ser lidos a partir 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 existente 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, após adicionar e remover metadados em uma instância existente, 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 existentes ou adicionar novos metadados, 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 existente, o valor da chave será atualizado com o novo valor.

Para as imagens que tenham ferramentas do Google 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 executado quando a instância é iniciada. Para um conteúdo de script mais longo, use a sinalização --metadata-from-file para transmitir um caminho para um arquivo que contenha o conteúdo do script.
  • startup-script-url: indica que um script na localização publicamente acessível especificada é executado quando a instância é iniciada.

Por exemplo, para criar uma instância denominada "my-instance" na zona "us-central1-a", com conteúdo de 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 log do sistema (/var/log/syslog), será exibido o resultado do script de inicialização.

Com uma instância existente denominada "my-instance", é possível adicionar o seguinte script de inicialização a partir 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

Nesse exemplo, o script de inicialização é executado no momento em que a instância é reinicializada, por exemplo, ao utilizar 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 existente, o valor da chave será atualizado com o novo valor.

Para ver os metadados existentes em nível de projeto, use o comando project-info describe:

gcloud compute project-info describe

O seguinte comando 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

Observe que a chave startup-script é reservada e significa que o conteúdo do arquivo local especificado deve ser executado quando as instâncias iniciarem.

Para remover os dois metadados que 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 é considerado em relação à cota de disco permanente e incorre em 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:

  • Usar a sinalização --keep-disks do comando instances delete.
  • Configurar o disco para não ser excluído automaticamente. Após criar uma instância e, a qualquer momento, antes de excluir as 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.

Como listar operações

Operações são um registro de alterações nos recursos do Google Compute Engine. Para receber 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, use as sinalizações --global, --zones e --regions para refinar os resultados. O comando a seguir retorna apenas as operações nas zonas "us-central1-a" e "us-central1-b":

gcloud compute operations list --zones us-central1-a,us-central1-b

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

Como acessar páginas de ajuda

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

gcloud compute --help
gcloud compute instances --help
gcloud compute instances create --help

A ajuda rápida pode ser recebida usando a sinalização -h em vez da sinalização --help. Reveja toda a ajuda abrangente em Referência do Cloud SDK.

Para ajuda abrangente especificamente com comandos para configurar a ferramenta gcloud, execute:

gcloud topic TOPIC

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

Próximas etapas

É isso! Agora comece a usar a ferramenta gcloud compute. Estas são algumas ideias para ajudá-lo a dar os primeiros passos:

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Documentação do Compute Engine