Ative o encerramento elegante numa instância do Compute Engine

Este documento explica como ativar o encerramento controlado numa instância do Compute Engine nova ou existente. Para saber mais sobre o encerramento controlado, consulte o artigo Vista geral do encerramento controlado.

Quando ativa o encerramento normal numa instância, pode dar ao respetivo SO convidado até uma hora para encerrar corretamente quando para ou elimina a instância. Isto ajuda a evitar uma potencial perda de dados ou sistemas de ficheiros danificados.

Antes de começar

  • Se ainda não o tiver feito, configure a autenticação. A autenticação valida a sua identidade para aceder a Google Cloud serviços e APIs. Para executar código ou exemplos a partir de um ambiente de desenvolvimento local, pode autenticar-se no Compute Engine selecionando uma das seguintes opções:

    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. Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando: 

      gcloud init

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

    2. Set a default region and zone.

    REST

    Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

      Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando: 

      gcloud init

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

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

Funções necessárias

Para receber as autorizações de que precisa para ativar o encerramento controlado numa instância de computação, peça ao seu administrador para lhe conceder a função IAM Administrador de instâncias do Compute (v1) (roles/compute.instanceAdmin.v1) no seu projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para ativar o encerramento controlado numa instância de computação. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para ativar o encerramento normal numa instância de computação:

  • Para criar instâncias:
    • compute.instances.create no projeto
    • Para usar uma imagem personalizada para criar a VM: compute.images.useReadOnly na imagem
    • Para usar um instantâneo para criar a VM: compute.snapshots.useReadOnly no instantâneo
    • Para usar um modelo de instância para criar a VM: compute.instanceTemplates.useReadOnly no modelo de instância
    • Para atribuir uma rede antiga à VM: compute.networks.use no projeto
    • Para especificar um endereço IP estático para a VM: compute.addresses.use no projeto
    • Para atribuir um endereço IP externo à VM quando usar uma rede antiga: compute.networks.useExternalIp no projeto
    • Para especificar uma sub-rede para a VM: compute.subnetworks.use no projeto ou na sub-rede escolhida
    • Para atribuir um endereço IP externo à VM quando usar uma rede VPC: compute.subnetworks.useExternalIp no projeto ou na sub-rede escolhida
    • Para definir os metadados da instância de VM para a VM: compute.instances.setMetadata no projeto
    • Para definir etiquetas para a VM: compute.instances.setTags na VM
    • Para definir etiquetas para a VM: compute.instances.setLabels na VM
    • Para definir uma conta de serviço para a VM usar: compute.instances.setServiceAccount na VM
    • Para criar um novo disco para a VM: compute.disks.create no projeto
    • Para anexar um disco existente no modo de leitura ou leitura/escrita: compute.disks.use no disco
    • Para anexar um disco existente no modo de leitura: compute.disks.useReadOnly no disco
  • Para criar um modelo de instância: compute.instanceTemplates.create no projeto
  • Para ativar o encerramento controlado numa instância existente: compute.instances.update na instância

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Ative o encerramento elegante

Para ativar o encerramento controlado numa instância de computação, use um dos seguintes métodos:

Ative o encerramento elegante numa instância existente

Pode ativar o encerramento controlado numa instância de computação existente sem a parar nem reiniciar. O período de encerramento normal predefinido é de 10 minutos, mas pode especificar um período de encerramento personalizado entre um segundo e uma hora.

Para ativar o encerramento controlado numa instância existente, selecione uma das seguintes opções:

Consola

  1. Na Google Cloud consola, aceda à página Instâncias de VM.

    Aceder às instâncias de VM

  2. Na coluna Nome, clique no nome da instância na qual quer ativar o encerramento elegante.

    É apresentada a página de detalhes da instância.

  3. Clique em Editar.

  4. Na secção Gestão, faça o seguinte:

    1. Selecione a caixa de verificação Encerrar a VM normalmente.

    2. Opcional: para especificar um período de encerramento normal personalizado, especifique uma duração no campo Duração máxima.

  5. Clique em Guardar.

gcloud

Para ativar o encerramento normal numa instância existente, use o comando gcloud beta compute instances update com a flag --graceful-shutdown:

gcloud beta compute instances update INSTANCE_NAME \
    --graceful-shutdown \
    --zone=ZONE

Substitua o seguinte:

  • INSTANCE_NAME: o nome da instância.

  • ZONE: a zona onde a instância está localizada.

Opcionalmente, para especificar um período de encerramento normalizado personalizado, inclua a flag --graceful-shutdown-max-duration:

gcloud beta compute instances update INSTANCE_NAME \
    --graceful-shutdown \
    --graceful-shutdown-max-duration=MAX_DURATION \
    --zone=ZONE

Substitua MAX_DURATION por uma duração para o período de encerramento. O valor tem de estar formatado como o número de horas, minutos ou segundos, seguido de h, m e s, respetivamente. Por exemplo, especifique 1h durante uma hora ou 20m10s durante 20 minutos e 10 segundos.

REST

  1. Crie um ficheiro JSON vazio.

  2. Para ver as propriedades de uma instância existente, faça um pedido GET ao método beta instances.get:

    GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME

    Substitua o seguinte:

    • PROJECT_ID: o ID do projeto onde a instância está localizada.

    • ZONE: a zona onde a instância está localizada.

    • INSTANCE_NAME: o nome de uma instância existente.

  3. No ficheiro JSON vazio que criou nos passos anteriores, faça o seguinte:

    1. Introduza os detalhes da configuração da instância a partir do resultado do pedido GET.

    2. No campo scheduling, adicione o campo gracefulShutdown da seguinte forma:

      {
  ...
  "scheduling": {
    ...
    "gracefulShutdown": {
      "enabled": true
    }
  },
  ...
}

      Opcionalmente, para especificar um período de encerramento normalizado personalizado, inclua o campo maxDuration:

      {
  ...
  "scheduling": {
    ...
    "gracefulShutdown": {
      ...
      "enabled": true,
      "maxDuration": {
        "seconds": "MAX_DURATION"
      }
    }
  },
  ...
}

      Substitua MAX_DURATION por uma duração em segundos para o período de encerramento gradual. O valor tem de estar compreendido entre 1 e 3600, que corresponde a 3600 segundos (uma hora).

  4. Para atualizar a instância e reiniciá-la, faça um pedido PUT ao método instances.update beta. Na solicitação, faça o seguinte:

    • No URL do pedido, inclua o parâmetro de consulta mostDisruptiveAllowedAction definido como RESTART.

    • No corpo do pedido, inclua as propriedades da instância do ficheiro JSON que criou e atualizou nos passos anteriores.

    O pedido PUT para atualizar a instância é semelhante ao seguinte:

    PUT https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?mostDisruptiveAllowedAction=RESTART

{
  ...
  "scheduling": {
    ...
    "gracefulShutdown": {
      "enabled": true
    }
  },
  ...
}

Para mais informações sobre a atualização das propriedades de uma instância, consulte o artigo Atualize as propriedades da instância.

Ative o encerramento correto durante a criação de uma instância

Quando cria uma instância de computação com o encerramento elegante ativado, o período de encerramento predefinido é de 10 minutos. Opcionalmente, pode especificar um período de encerramento personalizado entre um segundo e uma hora.

Para criar uma instância com o encerramento elegante ativado, selecione uma das seguintes opções:

Consola

  1. Na Google Cloud consola, aceda à página Instâncias de VM.

    Aceder às instâncias de VM

  2. Clique em Criar instância.

    É apresentada a página Criar uma instância.

  3. Especifique um Nome para a instância.

  4. Especifique a Região e a Zona nas quais criar a instância.

  5. Especifique um tipo de máquina para a instância.

  6. No menu de navegação, clique em Avançadas.

  7. Expanda a secção Definições avançadas do modelo de aprovisionamento de VMs e, em seguida, faça o seguinte:

    1. Selecione a caixa de verificação Encerrar a VM normalmente.

    2. Opcional: para especificar um período de encerramento normal personalizado, especifique uma duração no campo Duração máxima.

  8. Clique em Criar.

gcloud

Para criar uma instância com o encerramento elegante ativado, use o comando gcloud beta compute instances create com a flag --graceful-shutdown:

gcloud beta compute instances create INSTANCE_NAME \
    --graceful-shutdown \
    --machine-type=MACHINE_TYPE \
    --zone=ZONE

Substitua o seguinte:

  • INSTANCE_NAME: o nome da instância.

  • MACHINE_TYPE: o tipo de máquina a usar para a instância.

  • ZONE: a zona na qual criar a instância.

Opcionalmente, para especificar um período de encerramento normalizado personalizado, inclua a flag --graceful-shutdown-max-duration:

gcloud beta compute instances create INSTANCE_NAME \
    --graceful-shutdown \
    --graceful-shutdown-max-duration=MAX_DURATION \
    --machine-type=MACHINE_TYPE \
    --zone=ZONE

Substitua MAX_DURATION por uma duração para o período de encerramento elegante. O valor tem de ser formatado como o número de horas, minutos ou segundos, seguido de h, m e s, respetivamente. Por exemplo, especifique 1h para uma hora ou 20m10s para 20 minutos e 10 segundos.

REST

Para criar uma instância com o encerramento elegante ativado, faça um POST pedido ao método beta.instances.insert. No corpo do pedido, inclua o campo gracefulShutdown:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances

{
  "name": "INSTANCE_NAME",
  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
  "disks": [
    {
      "boot": true,
      "initializeParams": {
        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
      }
    }
  ],
  "networkInterfaces": [
    {
      "network": "global/networks/default"
    }
  ],
  "scheduling": {
    "gracefulShutdown": {
      "enabled": true
    }
  }
}

Substitua o seguinte:

  • PROJECT_ID: o ID do projeto no qual criar a instância.

  • ZONE: a zona na qual criar a instância.

  • INSTANCE_NAME: o nome da instância.

  • MACHINE_TYPE: o tipo de máquina da instância.

  • IMAGE_PROJECT: o projeto de imagem que contém a imagem, por exemplo, debian-cloud. Para mais informações sobre os projetos de imagens suportados, consulte o artigo Imagens públicas.

  • IMAGE: especifique uma das seguintes opções:

    • Uma versão específica da imagem do SO, por exemplo, debian-12-bookworm-v20240617.

    • Uma família de imagens, que tem de estar formatada como family/IMAGE_FAMILY. Esta formatação especifica a imagem do SO mais recente e não descontinuada. Por exemplo, se especificar family/debian-12, é usada a versão mais recente na família de imagens do Debian 12. Para mais informações sobre a utilização de famílias de imagens, consulte o artigo Práticas recomendadas para famílias de imagens.

Opcionalmente, para especificar um período de encerramento normal personalizado, inclua o campo maxDuration no corpo do pedido:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances

{
  "name": "INSTANCE_NAME",
  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
  "disks": [
    {
      "boot": true,
      "initializeParams": {
        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
      }
    }
  ],
  "networkInterfaces": [
    {
      "network": "global/networks/default"
    }
  ],
  "scheduling": {
    "gracefulShutdown": {
      "enabled": true,
      "maxDuration": {
        "seconds": "MAX_DURATION"
      }
    }
  }
}

Substitua MAX_DURATION por uma duração em segundos para o período de encerramento gradual. O valor tem de estar compreendido entre 1 e 3600, que é 3600 segundos (uma hora).

Para mais opções de configuração ao criar uma instância, consulte o artigo Crie e inicie uma instância do Compute Engine.

Ative o encerramento elegante durante a criação de instâncias em massa

Quando cria instâncias de computação em massa com o encerramento elegante ativado, o período de encerramento predefinido é de 10 minutos. Opcionalmente, pode especificar um período de encerramento personalizado entre um segundo e uma hora.

Para criar instâncias em massa com o encerramento elegante ativado, selecione uma das seguintes opções:

gcloud

Para criar instâncias em massa com o encerramento simples ativado, use o comando gcloud beta compute instances bulk create com a flag --graceful-shutdown.

Por exemplo, para criar instâncias em massa numa única zona e especificar um padrão de nome para as instâncias, execute o seguinte comando:

gcloud beta compute instances bulk create \
    --count=COUNT \
    --graceful-shutdown \
    --machine-type=MACHINE_TYPE \
    --name-pattern="NAME_PATTERN" \
    --zone=ZONE

Substitua o seguinte:

  • COUNT: o número de instâncias a criar.

  • MACHINE_TYPE: o tipo de máquina para as instâncias.

  • NAME_PATTERN: o padrão de nome para as instâncias. Para substituir uma sequência de números num nome de instância, use uma sequência de carateres de cardinal (#). Por exemplo, usar instance-# para o padrão de nome gera instâncias com nomes que começam por instance-1, instance-2 e continuam até ao número de instâncias especificado por COUNT.

  • ZONE: a zona na qual criar instâncias em massa.

Opcionalmente, para especificar um período de encerramento normalizado personalizado, inclua a flag --graceful-shutdown-max-duration:

gcloud beta compute instances bulk create \
    --count=COUNT \
    --graceful-shutdown \
    --graceful-shutdown-max-duration=MAX_DURATION \
    --machine-type=MACHINE_TYPE \
    --name-pattern="NAME_PATTERN" \
    --zone=ZONE

Substitua MAX_DURATION por uma duração para o período de encerramento elegante. O valor tem de ser formatado como o número de horas, minutos ou segundos, seguido de h, m e s, respetivamente. Por exemplo, especifique 1h para uma hora ou 20m10s para 20 minutos e 10 segundos.

REST

Para criar instâncias em massa com o encerramento controlado ativado, faça um pedido ao método beta instances.bulkInsert.POST No corpo do pedido, inclua o campo gracefulShutdown.

Por exemplo, para criar instâncias em massa numa única zona e especificar um padrão de nome para as instâncias, faça um pedido POST da seguinte forma:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/bulkInsert

{
  "count": COUNT,
  "namePattern": "NAME_PATTERN",
  "instanceProperties": {
    "machineType": "MACHINE_TYPE",
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
        }
      }
    ],
    "networkInterfaces": [
      {
        "network": "global/networks/default"
      }
    ],
    "scheduling": {
      "gracefulShutdown": {
        "enabled": true
      }
    }
  }
}

Substitua o seguinte:

  • PROJECT_ID: o ID do projeto no qual criar instâncias em massa.

  • ZONE: a zona na qual criar instâncias em massa.

  • COUNT: o número de instâncias a criar.

  • NAME_PATTERN: o padrão de nome para as instâncias. Para substituir uma sequência de números num nome de instância, use uma sequência de carateres de cardinal (#). Por exemplo, usar instance-# para o padrão de nome gera instâncias com nomes que começam por instance-1, instance-2 e continuam até ao número de instâncias especificado por COUNT.

  • MACHINE_TYPE: o tipo de máquina para as instâncias.

  • IMAGE_PROJECT: o projeto de imagem que contém a imagem, por exemplo, debian-cloud. Para mais informações sobre os projetos de imagens suportados, consulte o artigo Imagens públicas.

  • IMAGE: especifique uma das seguintes opções:

    • Uma versão específica da imagem do SO, por exemplo, debian-12-bookworm-v20240617.

    • Uma família de imagens, que tem de estar formatada como family/IMAGE_FAMILY. Esta formatação especifica a imagem do SO mais recente e não descontinuada. Por exemplo, se especificar family/debian-12, é usada a versão mais recente na família de imagens do Debian 12. Para mais informações sobre a utilização de famílias de imagens, consulte o artigo Práticas recomendadas para famílias de imagens.

  • ZONE: a zona na qual criar instâncias em massa.

Opcionalmente, para especificar um período de encerramento normal personalizado, inclua o campo maxDuration no corpo do pedido:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/bulkInsert

{
  "count": COUNT,
  "namePattern": "NAME_PATTERN",
  "instanceProperties": {
    "machineType": "MACHINE_TYPE",
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
        }
      }
    ],
    "networkInterfaces": [
      {
        "network": "global/networks/default"
      }
    ],
    "scheduling": {
      "gracefulShutdown": {
        "enabled": true,
        "maxDuration": {
          "seconds": "MAX_DURATION"
        }
      }
    }
  }
}

Substitua MAX_DURATION por uma duração em segundos para o período de encerramento gradual. O valor tem de estar compreendido entre 1 e 3600, que é 3600 segundos (uma hora).

Para ver mais opções de configuração quando cria instâncias em massa, consulte o artigo Crie VMs em massa.

Ative o encerramento elegante durante a criação de um modelo de instância

Quando cria um modelo de instância com o encerramento elegante ativado, o período de encerramento predefinido é de 10 minutos. Opcionalmente, pode especificar um período de encerramento personalizado entre um segundo e uma hora.

Todas as instâncias de computação criadas com o modelo de instância têm o encerramento normal ativado.

Para criar um modelo de instância com o encerramento elegante ativado, selecione uma das seguintes opções:

Consola

  1. Na Google Cloud consola, aceda à página Modelos de instâncias.

    Aceda a Modelos de instâncias

  2. Clique em Criar modelo de instância.

    É apresentada a página Criar um modelo de instância.

  3. No campo Nome, introduza um nome para o modelo de instância.

  4. Selecione a Localização da seguinte forma:

    • Para reduzir a dependência entre regiões através da criação de um modelo de instância regional, faça o seguinte:

      1. Escolha Regional, se ainda não estiver selecionado.

      2. No campo Região, selecione a região na qual criar o modelo de instância.

    • Caso contrário, para usar o modelo de instância em várias regiões, escolha Global.

  5. Na secção Configuração da máquina, especifique um tipo de máquina.

  6. Expanda a secção Definições avançadas do modelo de aprovisionamento de VMs e, em seguida, faça o seguinte:

    1. Selecione a caixa de verificação Encerrar a VM normalmente.

    2. Opcional: para especificar um período de encerramento normal personalizado, especifique uma duração no campo Duração máxima.

  7. Clique em Criar.

gcloud

Para criar um modelo de instância com o encerramento elegante ativado, use o comando gcloud beta compute instance-templates create com a flag --graceful-shutdown.

Por exemplo, para criar um modelo de instância regional com o encerramento elegante ativado, execute o seguinte comando:

gcloud beta compute instance-templates create INSTANCE_TEMPLATE_NAME \
    --graceful-shutdown \
    --instance-template-region=REGION \
    --machine-type=MACHINE_TYPE

Substitua o seguinte:

  • INSTANCE_TEMPLATE_NAME: o nome do modelo de instância.

  • REGION: a região na qual criar o modelo de instância.

  • MACHINE_TYPE: o tipo de máquina para as instâncias criadas com o modelo de instância.

Opcionalmente, para especificar um período de encerramento normalizado personalizado, inclua a flag --graceful-shutdown-max-duration.

gcloud beta compute instance-templates create INSTANCE_TEMPLATE_NAME \
    --graceful-shutdown \
    --graceful-shutdown-max-duration=MAX_DURATION \
    --instance-template-region=REGION \
    --machine-type=MACHINE_TYPE

Substitua MAX_DURATION por uma duração para o período de encerramento. O valor tem de estar formatado como o número de horas, minutos ou segundos, seguido de h, m e s, respetivamente. Por exemplo, especifique 1h durante uma hora ou 20m10s durante 20 minutos e 10 segundos.

REST

Para criar um modelo de instância com o encerramento elegante ativado, faça um pedido POST a um dos seguintes métodos:

Por exemplo, para criar um modelo de instância regional com o encerramento elegante ativado, faça um pedido POST da seguinte forma:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceTemplates

{
  "name": "INSTANCE_TEMPLATE_NAME",
  "properties": {
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
        }
      }
    ],
    "machineType": "MACHINE_TYPE",
    "networkInterfaces": [
      {
        "network": "global/networks/default"
      }
    ],
    "scheduling": {
      "gracefulShutdown": {
        "enabled": true
      }
    }
  }
}

Substitua o seguinte:

  • PROJECT_ID: o ID do projeto onde criar o modelo de instância.

  • REGION: a região onde criar o modelo de instância.

  • INSTANCE_TEMPLATE_NAME: o nome do modelo de instância.

  • IMAGE_PROJECT: o projeto de imagem que contém a imagem, por exemplo, debian-cloud. Para mais informações sobre os projetos de imagens suportados, consulte o artigo Imagens públicas.

  • IMAGE: especifique uma das seguintes opções:

    • Uma versão específica da imagem do SO, por exemplo, debian-12-bookworm-v20240617.

    • Uma família de imagens, que tem de estar formatada como family/IMAGE_FAMILY. Esta formatação especifica a imagem do SO mais recente e não descontinuada. Por exemplo, se especificar family/debian-12, é usada a versão mais recente na família de imagens do Debian 12. Para mais informações sobre a utilização de famílias de imagens, consulte o artigo Práticas recomendadas para famílias de imagens.

  • MACHINE_TYPE: o tipo de máquina para as instâncias criadas com o modelo de instância.

Opcionalmente, para especificar um período de encerramento gradual personalizado, inclua o campo maxDuration no corpo do pedido.

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/instanceTemplates

{
  "name": "INSTANCE_TEMPLATE_NAME",
  "properties": {
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
        }
      }
    ],
    "machineType": "MACHINE_TYPE",
    "networkInterfaces": [
      {
        "network": "global/networks/default"
      }
    ],
    "scheduling": {
      "gracefulShutdown": {
        "enabled": true,
        "maxDuration": {
          "seconds": "MAX_DURATION"
        }
      }
    }
  }
}

Substitua MAX_DURATION por uma duração em segundos para o período de encerramento. O valor tem de estar compreendido entre 1 e 3600, que corresponde a 3600 segundos (uma hora).

Para mais opções de configuração ao criar um modelo de instância, consulte o artigo Crie modelos de instâncias.

O que se segue?