Como executar scripts de desligamento

Crie e execute scripts de desligamento que executem comandos antes que uma instância seja encerrada ou reiniciada. Isso é útil quando você conta com scripts automatizados para iniciar e encerrar instâncias para que elas tenham tempo de limpar ou fazer tarefas, como exportar registros ou fazer a sincronização com outros sistemas.

Os scripts de desligamento são úteis principalmente para instâncias em um grupo de instâncias gerenciadas com um escalonador automático. Se o escalonador automático encerra uma instância no grupo, o script de desligamento é executado antes de a instância parar e o script de desligamento executa todas as ações que você definir. O script é executado durante o período de desligamento limitado antes da interrupção da instância. Por exemplo, o script de desligamento pode copiar dados processados no Cloud Storage ou fazer backup de todos os registros.

As funções dos scripts de desligamento são similares às dos scripts de inicialização. Grande parte da documentação dos scripts de inicialização também se aplica aos scripts de desligamento.

Antes de começar

Permissões exigidas para a tarefa

Para executar esta tarefa, é preciso ter as permissões a seguir:

  • Todas as permissões necessárias para criar uma instância
  • compute.instances.setMetadata na instância

Especificações

Limitações

Existem algumas limitações a serem observadas ao usar scripts de desligamento:

  • Os scripts de desligamento têm um tempo limitado para concluir a execução antes que a instância seja interrompida:
    • Instâncias sob demanda: 90 segundos depois que você parar ou excluir uma instância
    • Instâncias preemptivas: 30 segundos depois da instância preemptiva
  • O Compute Engine só executa scripts de desligamento com base no melhor esforço. Em casos raros, o Compute Engine não pode garantir que o script de desligamento seja concluído.
  • Para instâncias do Linux, só é possível usar scripts de desligamento com a versão de imagem v20141007 ou posterior. Para instâncias do Windows Server, só é possível usar scripts de desligamento com a imagem v20150310 ou posterior.

Invocação de script de desligamento

Os scripts de desligamento são acionados por determinados eventos da Interface de energia e configuração avançada (ACPI, na sigla em inglês), como reinicializações ou encerramentos. Há muitas maneiras de reiniciar ou encerrar uma instância, mas apenas algumas ações acionam a execução do script de desligamento. Esse script é executado como parte das seguintes ações:

O script de desligamento não será executado se a instância for redefinida usando instances().reset.

Um script de desligamento pode ser de qualquer tipo de arquivo. Quando há um script de desligamento, o Compute Engine:

  1. copia o script para um arquivo local na instância;
  2. define as permissões no arquivo para torná-lo executável;
  3. executa o arquivo quando a instância é encerrada.

Por exemplo, é possível fornecer um script Python em vez de um script bash. Lembre-se de que o Compute Engine executa o script na íntegra, independentemente do tipo.

Para executar um script que não é bash, adicione uma linha shebang na parte superior do arquivo para permitir que o sistema operacional saiba qual intérprete usar. Por exemplo, para um script Python, adicione uma linha shebang como:

#!/usr/bin/python

Tempo de execução do script de desligamento

Antes de uma instância ser encerrada ou reiniciada, a execução do script de desligamento precisa ocorrer dentro um período de tempo limitado. Durante esse período, o Compute Engine tenta executar o script de desligamento. Se o script demora mais tempo para ser concluído, a instância termina automaticamente e todas as tarefas em execução são encerradas. Se você desligar ou reiniciar uma instância fazendo uma solicitação ao sistema operacional convidado com o comando sudo shutdown, o limite não será aplicado.

A duração do período de desligamento é diferente, dependendo do tipo de instância. Instâncias preemptivas têm um período de desligamento mais curto do que instâncias normais. Para mais informações sobre os limites de tempo de desligamento em cada tipo de instância, consulte Período de desligamento.

Em geral, é necessário que a conclusão da execução do script de desligamento ocorra dentro do período de desligamento para que o sistema operacional tenha tempo de concluir o processo de desligamento e liberar buffers para o disco.

Usar um script de desligamento local

Um script de desligamento local é um script que reside no computador local. Transfira um script de desligamento local como um arquivo ou fornecendo o conteúdo diretamente ao Compute Engine.

Scripts de desligamento podem executar quantas ações forem necessárias. No entanto, se você estiver transferindo o arquivo localmente, o script não poderá exceder o limite de 256 KB. Para usar um script que exceda o limite de tamanho, armazene o arquivo no Cloud Storage. Consulte Usar um script de desligamento do Cloud Storage para mais informações.

Fornecer um arquivo de script de desligamento

Um arquivo de script de desligamento local só pode ser transferido por meio da ferramenta de linha de comando gcloud.

Para transferir um arquivo de script de desligamento local, use a sinalização --metadata-from-file seguida por um par de chaves de metadados, shutdown-script=PATH/TO/FILE, em que PATH/TO/FILE é um caminho relativo para o script de desligamento. Por exemplo:

gcloud compute instances create example-instance \
    --metadata-from-file shutdown-script=examples/scripts/install.sh

Fornecer conteúdo do script desligamento diretamente

Como alternativa, transfira diretamente o conteúdo do script de desligamento.

Console

No Console do Cloud, especifique um script de desligamento diretamente usando a chave de metadados shutdown-script:

  1. No Console do Cloud, acesse a página Instâncias de VM.

    Acessar a página Instâncias de VM (em inglês)

  2. Clique em Criar instância.
  3. Na página Criar uma nova instância, preencha as propriedades da sua instância. Para opções avançadas de configuração, expanda a seção Gerenciamento, segurança, discos, rede, locatário único.
  4. Na seção Metadados, insira shutdown-script como a chave de metadados.
  5. Na caixa Valor, insira o conteúdo do script de desligamento.
  6. Clique em Criar para criar a instância.

gcloud

Com a ferramenta de linha de comando gcloud, use a sinalização --metadata para inserir o conteúdo do script de desligamento, seguido pelo par de chaves shutdown-script=CONTENTS, em que CONTENTS é o conteúdo do script de desligamento.

gcloud compute instances create example-instance --metadata shutdown-script="#! /bin/bash
> # Shuts down Apache server
> /etc/init.d/apache2 stop"

API

Na API, quando você criar uma instância, forneça um script de desligamento como parte da propriedade de metadados em sua solicitação. Use shutdown-script como chave de metadados:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances

{...
  "metadata": {
    "items": [
      {
       "key": "shutdown-script",
       "value": "#! /bin/bash\n\n# Shuts down Apache server\n/etc/init.d/apache2 stop"
      }
    ]
  }...
}

Inserir um script de desligamento em instâncias do Windows

Execute scripts de desligamento em instâncias do Windows usando as seguintes chaves de metadados específicas do Windows. Escolha entre as chaves especializadas listadas abaixo. Cada chave deve corresponder ao tipo de script que você quer executar.

É possível especificar vários scripts de desligamento transferindo chaves diferentes para a instância, mas cada chave só pode ser definida uma vez por máquina virtual.

As chaves a seguir podem ser utilizadas com um script de desligamento local, seguindo as mesmas instruções acima.

Scripts de desligamento cmd Scripts de desligamento bat Scripts de desligamento ps1
windows-shutdown-script-cmd windows-shutdown-script-bat windows-shutdown-script-ps1

Usar um script de desligamento do Cloud Storage

É possível armazenar e usar um script de desligamento do Cloud Storage. Siga as instruções da documentação Scripts de inicialização, mas substitua startup-script-url por shutdown-script-url.

Para instâncias do Windows, substitua windows-startup-script-url por windows-shutdown-script-url.

Aplicar um script de desligamento a instâncias em execução

Para adicionar um script de desligamento a uma instância em execução, siga as instruções da documentação Como aplicar um script de inicialização a instâncias em execução, mas substitua as chaves de metadados por uma das chaves a seguir:

  • shutdown-script: use essa chave para inserir diretamente o conteúdo do script de desligamento. Com a ferramenta de linha de comando gcloud, é possível inserir o caminho para um arquivo de script de desligamento usando a sinalização --metadata-from-file e a chave de metadados shutdown-script.
  • shutdown-script-url: use essa chave para inserir um URL do Cloud Storage para o arquivo de script de desligamento.