O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Executar scripts de desligamento

Linux Windows

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.

Pré-requisitos

Para executar scripts armazenados em metadados em uma instância de VM, o ambiente de convidado precisa estar instalado e em execução.

O ambiente de convidado inclui o agente de convidado (por exemplo, google-guest-agent no Linux), que lê o conteúdo ou o URL do script nos metadados da instância e inicia a execução.
Todas as imagens públicas do Compute Engine vêm com o ambiente de convidado pré-instalado.
Se você criar uma imagem personalizada, será necessário instalar manualmente o ambiente de convidado do Google para garantir que os scripts de metadados e outros recursos do Google Cloud funcionem corretamente.

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. Com isso, você confirma 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 selecionando uma das seguintes opções:
Selecione a guia para como planeja usar as amostras nesta página:
Console

Quando você usa o console do Google Cloud para acessar os serviços e as APIs do Google Cloud , não é necessário configurar a autenticação.
gcloud
1. Instale a CLI do Google Cloud. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando:
  gcloud init
  Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.
  
  Observação:se você já instalou a CLI gcloud, verifique se tem a versão mais recente executando gcloud components update.
Defina uma região e uma zona padrão.

Terraform

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

Instale a CLI do Google Cloud.
Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.
Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:
```
gcloud auth application-default login
```
Não é necessário fazer isso se você estiver usando o Cloud Shell.

Se um erro de autenticação for retornado e você estiver usando um provedor de identidade externo (IdP), confirme se você fez login na CLI gcloud com sua identidade federada.

Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

REST

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

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Saiba mais em 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

As seções a seguir descrevem as especificações dos scripts de encerramento.

Limitações

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

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 quando a instância é encerrada após qualquer um dos seguintes eventos:

Faça o seguinte:
- Interrompa ou reinicie a instância no SO convidado.
- Interrompa ou exclua a instância.
O Compute Engine interrompe uma instância como parte de uma operação programada de interrupção ou exclusão.
O Compute Engine interrompe uma VM spot ou uma instância preemptiva como parte do processo de preempção.

Um script de desligamento pode ser de qualquer tipo de arquivo. Se houver um script de encerramento presente na instância, o Compute Engine vai fazer o seguinte:

Copia o script para um arquivo local na instância.
Define permissões no arquivo para tornar o script executável.
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

Os scripts de encerramento começam a ser executados quando o Compute Engine define o estado da instância como STOPPING. Os scripts precisam ser concluídos antes que a instância seja totalmente interrompida, que é quando o estado dela muda para TERMINATED. O tempo que a instância leva para atingir o estado TERMINATED varia de acordo com o tipo de instância.

Se os scripts demorarem mais do que o tempo necessário para a instância ser interrompida, o Compute Engine vai interromper os scripts à força, o que pode levar à perda de dados ou a tarefas incompletas. Para evitar isso, interrompa a instância no SO convidado. Essa abordagem mantém o estado da instância como STOPPING até que os scripts de encerramento terminem de ser executados.

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

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-13"
    }
  }
  network_interface {
    # A default network is created for all Google Cloud projects
    network = "default"
    access_config {
    }
  }
}

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

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:

Acesse a página Criar uma instância.

Acesse "Criar uma instância"
Especifique os detalhes da VM.
Expanda a seção Opções avançadas.
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.
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.

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-13"
    }
  }
  network_interface {
    # A default network is created for all Google Cloud projects
    network = "default"
    access_config {
    }
  }
}

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

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 usadas com um script de desligamento local, usando as mesmas instruções descritas anteriormente neste documento.

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.

Executar um script de encerramento durante um encerramento completo

Por padrão, se uma instância de computação tiver o encerramento completo ativado, todos os scripts de encerramento configurados nas chaves de metadados serão executados após o término do encerramento completo.

Para executar comandos durante um encerramento completo, use um script de observador personalizado que consulta continuamente o servidor de metadados em segundo plano, conforme mostrado nesta seção. Para dar aos scripts tempo suficiente para serem concluídos e evitar possíveis perdas de dados ou tarefas incompletas, recomendamos que você modifique os scripts de desligamento movendo a lógica para esse script de observador.

Para executar um script de encerramento durante um encerramento completo, selecione uma das seguintes opções com base no SO convidado usado pela instância de computação:

Linux

Conecte-se à instância de computação, caso ainda não tenha feito isso.

Execute um script de observador ou configure-o para ser executado na inicialização, como o seguinte. Adicione sua lógica de encerramento específica onde indicado:

#!/bin/bash

# --------------------------------------------------------
# Script for graceful shutdown based on the metadata value
# --------------------------------------------------------
#
# This script monitors the metadata key `shutdown-status` and
# waits for its value to change to `PENDING_STOP`. After the script
# runs a series of user-defined commands, it runs `sudo shutdown -h now`
# to signal to Compute Engine that the shutdown process is
# complete.
#
# To run this script, you must have passwordless sudo privileges.

METADATA_URL="http://metadata.google.internal/computeMetadata/v1/instance/attributes/shutdown-status"
LAST_ETAG="0"

echo "Starting shutdown status watcher"

while true; do
  # Wait for the metadata value to change.
  # The metadata server blocks the request until a change occurs or a timeout is reached.
  RESPONSE=$(curl -H "Metadata-Flavor: Google" -s -i "${METADATA_URL}?wait_for_change=true&last_etag=${LAST_ETAG}")
  CURL_EXIT_STATUS=$?

  if [[ ${CURL_EXIT_STATUS} -ne 0 ]]; then
    echo "Error: curl command failed with exit status ${CURL_EXIT_STATUS}. Retrying in 5 seconds..."
    sleep 5
    continue
  fi

  # Strip carriage returns (\r) immediately to prevent CRLF line endings from corrupting string comparisons
  RESPONSE=$(echo "$RESPONSE" | tr -d '\r')

  # Extract the HTTP status code from the first line of the response
  HTTP_STATUS=$(echo "$RESPONSE" | head -n 1 | awk '{print $2}')

  if [[ "${HTTP_STATUS}" -eq 200 ]]; then
    # Read the new etag value to re-subscribe on the next poll.
    NEW_ETAG=$(echo "$RESPONSE" | grep -i "^ETag:" | awk '{print $2}')
    if [[ -n "${NEW_ETAG}" ]]; then
      LAST_ETAG="${NEW_ETAG}"
    fi

    # Extract the value of the shutdown status from the last line of the response body.
    SHUTDOWN_STATUS=$(echo "$RESPONSE" | tail -n 1)

    echo "Metadata changed. New ETag: ${LAST_ETAG}, shutdown-status: '${SHUTDOWN_STATUS}'"

    if [[ "${SHUTDOWN_STATUS}" == "PENDING_STOP" ]]; then
      echo "Shutdown signal 'PENDING_STOP' received. Exiting watcher loop."
      break
    fi
  elif [[ "${HTTP_STATUS}" -eq 503 ]]; then
    # 503 Service Unavailable: wait_for_change timed out with no change. Sleep and loop again.
    echo "Service temporarily unavailable or request timed out. Retrying in 2 seconds..."
    sleep 2
    continue
  else
    # Unexpected HTTP status
    echo "Warning: Unexpected HTTP status ${HTTP_STATUS}. Retrying in 5 seconds..."
    sleep 5
  fi
done

# --------------------------------------------------------
# Graceful shutdown commands section
# --------------------------------------------------------
echo "Watcher loop exited. Starting graceful shutdown procedures..."

# --- ADD YOUR GRACEFUL SHUTDOWN COMMANDS HERE ---

echo "Graceful shutdown commands executed."

# --------------------------------------------------------
# Signal OS to stop
# --------------------------------------------------------
echo "Shutting down the guest OS to turn off the compute instance..."
sudo shutdown -h now

Windows

Se ainda não tiver feito isso, conecte-se à instância de computação usando um dos seguintes métodos:

Execute um script de observador ou configure-o para ser executado na inicialização, como o seguinte. Adicione sua lógica de encerramento específica onde indicado:

<#
.SYNOPSIS
pre-shutdown-script.ps1
#>

# --------------------------------------------------------
# Script for graceful shutdown based on the metadata value
# --------------------------------------------------------
#
# This script monitors the metadata key `shutdown-status` and
# waits for its value to change to `PENDING_STOP`. After the script
# runs a series of user-defined commands, it runs `Stop-Computer -Force`
# to signal to Compute Engine that the shutdown process is
# complete.

$METADATA_URL = "http://metadata.google.internal/computeMetadata/v1/instance/attributes/shutdown-status"
$LAST_ETAG = "0"

Write-Host "Starting shutdown status watcher"

while ($true) {
    $Response = $null
    $HTTP_STATUS = 0

    # Wait for the metadata value to change.
    # The metadata server blocks the request until a change occurs or a timeout is reached.
    try {
        $Response = Invoke-WebRequest `
            -Headers @{"Metadata-Flavor" = "Google"} `
            -Uri "${METADATA_URL}?wait_for_change=true&last_etag=${LAST_ETAG}" `
            -TimeoutSec 320 `
            -ErrorAction Stop

        if ($null -ne $Response) {
            $HTTP_STATUS = [int]$Response.StatusCode
        }
    } catch {
        # Invoke-WebRequest throws an error for non-2xx status codes or connection failures.
        $Exception = $_.Exception
        if ($null -ne $Exception -and $null -ne $Exception.Response) {
            $HTTP_STATUS = [int]$Exception.Response.StatusCode
        } else {
            $HTTP_STATUS = 0
        }
    }

    if ($HTTP_STATUS -eq 0) {
        Write-Host "Error: Request failed. Retrying in 5 seconds..."
        Start-Sleep -Seconds 5
        continue
    }

    if ($HTTP_STATUS -eq 200) {
        # Read the new etag value to re-subscribe on the next poll.
        $NEW_ETAG = $Response.Headers["ETag"]
        if ($null -ne $NEW_ETAG) {
            $LAST_ETAG = $NEW_ETAG
        }

        # Extract the value of the shutdown status from the response body.
        $SHUTDOWN_STATUS = $Response.Content.Trim()

        Write-Host "Metadata changed. New ETag: ${LAST_ETAG}, shutdown-status: '${SHUTDOWN_STATUS}'"

        if ($SHUTDOWN_STATUS -eq "PENDING_STOP") {
            Write-Host "Shutdown signal 'PENDING_STOP' received. Exiting watcher loop."
            break
        }
    } elseif ($HTTP_STATUS -eq 503) {
        # 503 Service Unavailable: wait_for_change timed out with no change. Sleep and loop again.
        Write-Host "Service temporarily unavailable or request timed out. Retrying in 2 seconds..."
        Start-Sleep -Seconds 2
        continue
    } else {
        # Unexpected HTTP status
        Write-Host "Warning: Unexpected HTTP status ${HTTP_STATUS}. Retrying in 5 seconds..."
        Start-Sleep -Seconds 5
    }
}

# --------------------------------------------------------
# Graceful shutdown commands section
# --------------------------------------------------------
Write-Host "Watcher loop exited. Starting graceful shutdown procedures..."

# --- ADD YOUR GRACEFUL SHUTDOWN COMMANDS HERE ---

Write-Host "Graceful shutdown commands executed."

# --------------------------------------------------------
# Signal OS to Halt
# --------------------------------------------------------
Write-Host "Shutting down the guest OS to turn off the compute instance..."
Stop-Computer -Force

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:

Conectando-se à instância e executando o comando a seguir:
```
sudo journalctl -u google-shutdown-scripts.service
```
Como visualizar a saída pela porta serial 1 no console do Google Cloud e verificar se há eventos google_metadata_script_runner.
IAP Desktop em uma estação de trabalho do Windows. Para mais informações, consulte o repositório GoogleCloudPlatform/iap-desktop no GitHub.

Windows

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

Porta serial 1 no console do Google Cloud . Para mais informações, consulte Como visualizar a saída da porta serial.
Registro do aplicativo do Visualizador de eventos do Windows.
IAP Desktop em uma estação de trabalho do Windows. Para mais informações, consulte o repositório GoogleCloudPlatform/iap-desktop no GitHub.

Executar scripts de desligamento Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Pré-requisitos

Antes de começar

Console

gcloud

Terraform

REST

Permissões exigidas para a tarefa

Especificações

Limitações

Invocação de script de desligamento

Tempo de execução do script de desligamento

Usar um script de desligamento local

Fornecer um arquivo de script de desligamento

gcloud

Terraform

Fornecer conteúdo do script desligamento diretamente

Console

gcloud

Terraform

REST

Inserir um script de desligamento em instâncias do Windows

Usar um script de desligamento do Cloud Storage

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

Executar um script de encerramento durante um encerramento completo

Linux

Windows

Como visualizar a saída de um script de desligamento

Linux

Windows

Executar scripts de desligamento