Como executar scripts de desligamento

Crie e execute scripts de desligamento que executam comandos antes que uma instância de máquina virtual (VM) seja interrompida 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 VMs em um grupo gerenciado de instâncias com um escalonador automático. Se o escalonador automático encerra uma VM no grupo, o script de desligamento é executado antes de a VM ser interrompida e o script de desligamento executa todas as ações definidas por você. 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 de scripts de inicialização também se aplica aos scripts de desligamento.

Para tarefas de desligamento e reinicialização, as VMs sempre executam scripts de desligamento da seguinte maneira:

  • Para VMs do Linux, usando o usuário root.
  • Para VMs do Windows, usando a conta System.

Antes de começar

  • Saiba mais sobre scripts de inicialização.
  • Entenda o que é o servidor de metadados.
  • Configure a autenticação, caso ainda não tenha feito isso. A autenticação é o processo de verificação da sua identidade para acesso a serviços e APIs do Google Cloud. Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine da seguinte maneira.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

      3. Terraform

      Para usar os exemplos do Terraform nesta página em um ambiente de desenvolvimento local, instale e inicialize a gcloud CLI e, em seguida, configure o Application Default Credentials com suas credenciais de usuário.

      1. Install the Google Cloud CLI.

      2. To initialize the gcloud CLI, run the following command: 

        gcloud init

      3. If you're using a local shell, then create local authentication credentials for your user account: 

        gcloud auth application-default login

        You don't need to do this if you're using Cloud Shell.

      Confira mais informações em Set up authentication for a local development environment.

      REST

      Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.

        Install the Google Cloud CLI, then initialize it by running the following command: 

        gcloud init

      Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.

Permissões exigidas para a tarefa

Para executar esta tarefa, é preciso ter a permissão 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.
  • No Windows, a Política de Grupo Local é usada para iniciar o script de desligamento.
    • O pacote de instalação define a configuração da Política de Grupo Local Computer Configuration/Windows Setting/Scripts (Startup/Shutdown) para iniciar o script após o encerramento do sistema.

Invocação de script de desligamento

Os scripts de desligamento são acionados por determinados eventos da Interface avançada de energia e configuração (ACPI, na sigla em inglês), como reinicializações ou encerramentos. Há muitas maneiras de reiniciar ou interromper 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:

  • Quando uma instância é desligada devido a uma solicitação instances.delete ou instances.stop à API.
  • Quando o Compute Engine interrompe uma instância preemptiva como parte do processo preemptivo.
  • Quando uma instância é desligada devido a uma solicitação ao sistema convidado, como sudo shutdown ou sudo reboot.
  • Ao desligar uma instância manualmente usando o console do Google Cloud ou a ferramenta gcloud compute.

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 é interrompida.

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 a conclusão do script demorar mais do que o período limitado, a instância será interrompida automaticamente e todas as tarefas em execução serã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.

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. Exemplo:

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

Terraform

Para especificar um script de encerramento diretamente, use o recurso google_compute_instance com o caminho para o script de encerramento nos metadados.

compute/run_shutdown_scripts/main.tf 
resource "google_compute_instance" "shutdown_content_from_file" {
  name         = "instance-name-shutdown-content-from-file"
  machine_type = "f1-micro"
  zone         = "us-central1-c"
  metadata = {
    # Shuts down Apache server
    shutdown-script = file("${path.module}/shutdown-script.sh")
  }
  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-11"
    }
  }
  network_interface {
    # A default network is created for all Google Cloud projects
    network = "default"
    access_config {
    }
  }
}

Fornecer conteúdo do script desligamento diretamente

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

Console

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

  1. Acesse a página Criar uma instância.

    Acesse "Criar uma instância"

  2. Especifique os detalhes da VM.

  3. Expanda a seção Opções avançadas.

  4. Expanda Gerenciamento e faça o seguinte:

    1. Na seção Metadados, clique em Adicionar item.
    2. No campo Chave, insira shutdown-script para a chave de metadados.
    3. No campo Valor, adicione o conteúdo do script de desligamento.

  5. Continue com o processo de criação da VM.

gcloud

Com a CLI do Google Cloud, 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"

Terraform

Para especificar um script de encerramento diretamente, use o recurso google_compute_instance com o script de encerramento nos metadados.

compute/run_shutdown_scripts/main.tf 
resource "google_compute_instance" "default" {
  name         = "instance-name-shutdown-content-directly"
  machine_type = "f1-micro"
  zone         = "us-central1-c"
  metadata = {
    # Shuts down Apache server
    shutdown-script = "#! /bin/bash /etc/init.d/apache2 stop"
  }
  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-11"
    }
  }
  network_interface {
    # A default network is created for all Google Cloud projects
    network = "default"
    access_config {
    }
  }
}

REST

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 passando 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 desligamento 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 CLI do Google Cloud, é 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.

Como visualizar a saída de um script de desligamento

Linux

É possível visualizar a saída em um script de desligamento do Linux seguindo um destes procedimentos:

Windows

Visualize a saída de um script de desligamento do Windows Server usando qualquer um dos seguintes itens e verificando eventos GCEMetadataScripts: