Ativar o desligamento suave em uma instância do Compute Engine

Neste documento, explicamos como ativar o desligamento normal em uma instância do Compute Engine nova ou atual. Para saber mais sobre o encerramento gradual, consulte Visão geral do encerramento gradual.

Ao ativar o encerramento normal em uma instância, você pode dar ao SO convidado até uma hora para ser encerrado normalmente quando a instância for interrompida ou excluída. Isso ajuda a evitar a perda de dados ou a corrupção de sistemas de arquivos.

Antes de começar

  • 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 Trusted Cloud by S3NS . Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-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 Trusted Cloud console to access Trusted Cloud by S3NS services and APIs, you don't need to set up authentication.

    gcloud

    1. Instale a Google Cloud CLI e faça login nela com sua identidade federada. Depois de fazer login, inicialize a Google Cloud CLI executando o seguinte comando: 

      gcloud init
    2. Set a default region and zone.

    REST

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

      Instale a Google Cloud CLI e faça login nela com sua identidade federada. Depois de fazer login, inicialize a Google Cloud CLI executando o seguinte comando: 

      gcloud init

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

Funções exigidas

Para receber as permissões necessárias para ativar o encerramento normal em uma instância de computação, peça ao administrador para conceder a você o papel do IAM de Administrador da instância da computação (v1) (roles/compute.instanceAdmin.v1) no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para ativar o desligamento normal em uma instância de computação. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para ativar o desligamento normal em uma 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
    • Usar um snapshot para criar a VM: compute.snapshots.useReadOnly no snapshot
    • Usar um modelo de instância para criar a VM: compute.instanceTemplates.useReadOnly no modelo de instância
    • Atribuir uma rede legada à VM: compute.networks.use no projeto
    • Especificar um endereço IP estático para a VM: compute.addresses.use no projeto
    • Atribuir um endereço IP externo à VM ao usar uma rede legada: compute.networks.useExternalIp no projeto
    • Especificar uma sub-rede para a VM: compute.subnetworks.use no projeto ou na sub-rede escolhida
    • Atribuir um endereço IP externo à VM ao usar uma rede VPC: compute.subnetworks.useExternalIp no projeto ou na sub-rede escolhida
    • Definir os metadados da instância de VM para a VM: compute.instances.setMetadata no projeto
    • Definir tags para a VM: compute.instances.setTags na VM
    • Definir rótulos para a VM: compute.instances.setLabels na VM
    • Definir uma conta de serviço para a VM usar: compute.instances.setServiceAccount na VM
    • Criar um disco para a VM: compute.disks.create no projeto
    • Anexar um disco atual no modo somente leitura ou de leitura e gravação: compute.disks.use no disco
    • Anexar um disco atual no modo somente leitura: compute.disks.useReadOnly no disco
  • Para criar um modelo de instância: compute.instanceTemplates.create no projeto
  • Para ativar o encerramento normal em uma instância atual: compute.instances.update na instância

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Ativar o desligamento normal

Para ativar o desligamento normal em uma instância de computação, use um dos seguintes métodos:

Ativar o desligamento normal em uma instância atual

É possível ativar o desligamento normal em uma instância de computação sem interrompê-la ou reiniciá-la. O período padrão de desligamento normal é de 10 minutos, mas é possível especificar um período personalizado entre um segundo e uma hora.

Para ativar o desligamento normal em uma instância, selecione uma das seguintes opções:

Console

  1. No Trusted Cloud console, acesse a página Instâncias de VM:

    Acessar instâncias de VM

  2. Na coluna Nome, clique no nome da instância em que você quer ativar o desligamento normal.

    A página de detalhes da instância é aberta.

  3. Clique em Editar.

  4. Na seção Gerenciamento, faça o seguinte:

    1. Marque a caixa de seleção Desligar a VM normalmente.

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

  5. Clique em Salvar.

gcloud

Para ativar o desligamento normal em uma instância atual, 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:

  • INSTANCE_NAME: o nome da instância.

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

Se quiser especificar um período de desligamento normal 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 desligamento. O valor precisa ser formatado como o número de horas, minutos ou segundos, seguido por h, m e s, respectivamente. Por exemplo, especifique 1h para uma hora ou 20m10s para 20 minutos e 10 segundos.

REST

  1. Crie um arquivo JSON vazio.

  2. Para conferir as propriedades de uma instância atual, faça uma solicitação GET para o método instances.get da versão Beta:

    GET https://compute.s3nsapis.fr/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME

    Substitua:

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

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

    • INSTANCE_NAME: o nome de uma instância.

  3. No arquivo JSON vazio que você criou nas etapas anteriores, faça o seguinte:

    1. Insira os detalhes da configuração da instância na saída da solicitação GET.

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

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

      Se quiser especificar um período de desligamento normal 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 desligamento normal. O valor precisa estar entre 1 e 3600, que é 3.600 segundos (uma hora).

  4. Para atualizar e reiniciar a instância, faça uma solicitação PUT ao método Beta instances.update. Na solicitação, faça o seguinte:

    • No URL da solicitação, inclua o parâmetro de consulta mostDisruptiveAllowedAction definido como RESTART.

    • No corpo da solicitação, inclua as propriedades da instância do arquivo JSON que você criou e atualizou nas etapas anteriores.

    A solicitação PUT para atualizar a instância é semelhante a esta:

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

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

Para mais informações sobre como atualizar as propriedades de uma instância, consulte Atualizar propriedades da instância.

Ativar o desligamento normal ao criar uma instância

Quando você cria uma instância de computação com o desligamento automático ativado, o período de desligamento padrão é de 10 minutos. Se quiser, especifique um período de desligamento personalizado entre um segundo e uma hora.

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

Console

  1. No Trusted Cloud console, acesse a página Instâncias de VM:

    Acessar instâncias de VM

  2. Clique em Criar instância.

    A página Criar uma instância será aberta.

  3. Especifique um Nome para a instância.

  4. Especifique a Região e a Zona em que a instância será criada.

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

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

  7. Expanda a seção Configurações avançadas do modelo de provisionamento de VM e faça o seguinte:

    1. Marque a caixa de seleção Desligar a VM normalmente.

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

  8. Clique em Criar.

gcloud

Para criar uma instância com o desligamento normal 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:

  • INSTANCE_NAME: o nome da instância.

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

  • ZONE: a zona em que a instância será criada.

Se quiser especificar um período de desligamento normal 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 desligamento normal. O valor precisa ser formatado como o número de horas, minutos ou segundos, seguido por h, m e s, respectivamente. Por exemplo, especifique 1h para uma hora ou 20m10s para 20 minutos e 10 segundos.

REST

Para criar uma instância com o desligamento normal ativado, faça uma solicitação POST para o método beta.instances.insert. No corpo da solicitação, inclua o campo gracefulShutdown:

POST https://compute.s3nsapis.fr/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:

  • PROJECT_ID: o ID do projeto em que a instância será criada.

  • ZONE: a zona em que a instância será criada.

  • 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 imagem com suporte, consulte Imagens públicas.

  • IMAGE: especifique uma destas opções:

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

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

Opcionalmente, para especificar um período de desligamento normal personalizado, inclua o campo maxDuration no corpo da solicitação:

POST https://compute.s3nsapis.fr/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 desligamento normal. O valor precisa estar entre 1 e 3600, que é 3.600 segundos (uma hora).

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

Ativar o desligamento normal ao criar um modelo de instância

Quando você cria um modelo de instância com o encerramento automático ativado, o período de encerramento padrão é de 10 minutos. Se quiser, especifique um período de desligamento personalizado entre um segundo e uma hora.

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

Para criar um modelo de instância com o desligamento normal ativado, selecione uma das opções a seguir:

Console

  1. No console Trusted Cloud , acesse a página Modelos de instância.

    Acesse "Modelos de instância"

  2. Clique em Criar modelo de instância.

    A página Criar um modelo de instância é aberta.

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

  4. Selecione o Local da seguinte forma:

    • Para reduzir a dependência entre regiões criando 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 em que o modelo de instância será criado.

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

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

  6. Expanda a seção Configurações avançadas do modelo de provisionamento de VM e faça o seguinte:

    1. Marque a caixa de seleção Desligar a VM normalmente.

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

  7. Clique em Criar.

gcloud

Para criar um modelo de instância com o desligamento normal 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 desligamento normal 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:

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

  • REGION: a região em que o modelo de instância será criado.

  • MACHINE_TYPE: o tipo de máquina das instâncias criadas usando o modelo de instância.

Se quiser especificar um período de desligamento normal 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 desligamento. O valor precisa ser formatado como o número de horas, minutos ou segundos, seguido por h, m e s, respectivamente. Por exemplo, especifique 1h para uma hora ou 20m10s para 20 minutos e 10 segundos.

REST

Para criar um modelo de instância com o desligamento normal ativado, faça uma solicitação POST para um dos seguintes métodos:

Por exemplo, para criar um modelo de instância regional com o desligamento normal ativado, faça uma solicitação POST da seguinte maneira:

POST https://compute.s3nsapis.fr/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:

  • PROJECT_ID: o ID do projeto em que o modelo de instância será criado.

  • REGION: a região em que o modelo de instância será criado.

  • 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 imagem com suporte, consulte Imagens públicas.

  • IMAGE: especifique uma destas opções:

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

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

  • MACHINE_TYPE: o tipo de máquina das instâncias criadas usando o modelo de instância.

Opcionalmente, para especificar um período de desligamento normal personalizado, inclua o campo maxDuration no corpo da solicitação.

POST https://compute.s3nsapis.fr/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 desligamento. O valor precisa estar entre 1 e 3600, que é 3.600 segundos (uma hora).

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

A seguir