Definir a política de manutenção do host para uma instância de computação

Este documento explica como definir a política de manutenção do host para uma instância do Compute Engine e determinar o comportamento dela durante eventos do host. Para saber mais sobre as políticas de manutenção do host, consulte Política de manutenção do host.

Uma política de manutenção do host determina como a instância responde quando o host em que ela está sendo executada precisa de manutenção ou encontra um erro. Configurar a política de manutenção do host para uma instância ajuda a fazer o seguinte:

  • Minimizar o tempo de inatividade.

  • Evite a perda de dados.

Limitações

Para as políticas de manutenção do host, as seguintes limitações se aplicam:

  • As instâncias de máquina virtual que usam tipos de máquina E2 só podem migrar em tempo real durante eventos de manutenção do host, a menos que sejam VMs do Spot ou VMs preemptivas.

  • As instâncias a seguir só podem ser interrompidas durante eventos de manutenção do host:

  • As VMs Spot e preemptivas não podem ser reiniciadas automaticamente após erros do host ou paradas programadas.

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

    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. After installing the Google Cloud CLI, initialize it by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    2. Set a default region and zone.

      3. REST

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

        After installing the Google Cloud CLI, initialize it by running the following command: 

        gcloud init

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

Funções exigidas

Para receber as permissões necessárias para definir a política de manutenção do host para uma instância de computação, peça ao administrador para conceder a você o papel do IAM de Administrador da instância do Compute (v1) (roles/compute.instanceAdmin.v1) no 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 definir a política de manutenção do host para 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 permissões a seguir são necessárias para definir a política de manutenção do host para uma instância de computação:

  • Para criar uma instância:
    • 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 atualizar a política de manutenção do host de uma instância: compute.instances.setScheduling na instância

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

Propriedades de manutenção do host disponíveis

É possível personalizar o comportamento da instância de computação durante a manutenção programada ou eventos inesperados do host. A menos que você especifique o contrário, o Compute Engine usa as configurações padrão ao criar uma instância , instâncias em massa ou um modelo de instância.

É possível configurar as seguintes propriedades de manutenção do host:

  • Comportamento de manutenção (onHostMaintenance): o que acontece com a instância durante um evento de manutenção no host que pode causar a reinicialização da instância. É possível definir essa propriedade como um dos seguintes valores:

    • Migrar: o Compute Engine migra automaticamente sua instância para outro host. Essa é a configuração padrão para todos os tipos de instâncias, exceto VMs spot e preemptivas.

    • Encerrar: o Compute Engine interrompe a instância. Essa é a configuração padrão para VMs spot ou VMs preemptivas, e é a única configuração com suporte para instâncias Z3, bare metal e instâncias com GPUs ou TPUs anexadas.

  • Reinício automático (automaticRestart): indica se a instância é reiniciada quando falha ou se o Compute Engine a interrompe para uma parada programada, como um evento de manutenção. É possível definir essa propriedade como um dos seguintes valores:

    • Ativado: o Compute Engine reinicia a instância automaticamente. Essa é a configuração padrão para todos os tipos de instâncias, exceto VMs spot e VMs preemptivas. Especifique essa configuração da seguinte maneira:

      • No console do Google Cloud, no painel Advanced, na lista Automatic restart, selecione On (recommended).

      • Para a CLI do Google Cloud, use a flag --restart-on-failure.

      • Para REST, defina o campo automaticRestart como true.

    • Desativado: o Compute Engine não reinicia a instância. Essa é a configuração padrão para VMs spot ou preemptivas. Especifique essa configuração da seguinte maneira:

      • No console do Google Cloud, no painel Advanced, na lista Automatic restart, selecione Off.

      • Para a CLI gcloud, use a flag --no-restart-on-failure.

      • Para REST, defina o campo automaticRestart como false.

  • Tempo limite de recuperação de dados do SSD local (localSsdRecoveryTimeout): essa configuração se aplica apenas a instâncias com discos SSD locais anexados. Ele determina quanto tempo o Compute Engine aguarda para recuperar dados dos discos SSD locais após erros do host. Por padrão, essa propriedade não é definida. É possível definir essa propriedade como uma das seguintes opções:

    • Não definido: o Compute Engine usa o tempo de espera padrão:

      • Para VMs Z3, 6 horas

      • Para todos os outros tipos de instâncias, 1 hora

    • Um número inteiro de 0 a 168: o número de horas a aguardar. Definir essa propriedade como 0 significa que o Compute Engine não recupera dados do SSD local e reinicia a instância imediatamente.

  • Tempo limite de erro do host (hostErrorTimeoutSeconds): essa propriedade determina quanto tempo o Compute Engine aguarda para reiniciar uma instância que não responde. É necessário configurar essa configuração antes que a instância pare de responder. Use um tempo limite longo o suficiente para que uma instância se recupere de uma falha de resposta. É possível definir essa propriedade como um dos seguintes valores:

    • Não definido: o Compute Engine aguarda até 330 segundos (5 minutos e 30 segundos). Essa é a configuração padrão para qualquer tipo de instância.

    • Um número inteiro de 90 a 330: o tempo de espera em segundos, em incrementos de 30 segundos.

Definir a política de manutenção do host para uma instância

Por padrão, as instâncias de computação usam as configurações padrão para a política de manutenção do host. Para personalizar essas configurações, use um dos seguintes métodos:

Definir a política para uma instância

Antes de mudar a política de manutenção do host de uma instância, verifique o seguinte:

  • Não é possível mudar o comportamento de manutenção (onHostMaintenance) dos seguintes tipos de instâncias:

  • Não é possível configurar VMs do Spot ou VMs preemptivas para reiniciar automaticamente após erros do host ou paradas programadas.

Para mudar o tempo limite de recuperação de dados do SSD local em uma instância com discos SSD locais conectados, use a CLI gcloud ou a API REST. Caso contrário, selecione uma das seguintes opções:

Console

  1. No console do Google Cloud, acesse a página Instâncias de VMs.

    Acessar instâncias de VM

  2. Na coluna Nome, clique no nome da instância que você quer atualizar. Uma página com os detalhes da instância vai aparecer.

  3. Clique em Editar. Uma página que permite editar as propriedades de instância é exibida.

  4. Na seção Gerenciamento, é possível realizar uma ou mais das seguintes ações:

    • Para mudar o comportamento durante eventos de manutenção, selecione outra opção na lista Na manutenção do host.

    • Para mudar o período de tempo limite antes de reiniciar uma instância que não responde, selecione outra opção na lista Tempo limite de erro do host.

    • Para mudar a reinicialização da instância após erros do host ou paradas programadas, selecione outra opção na lista Reinicialização automática.

  5. Clique em Salvar.

gcloud

Para mudar a política de manutenção do host em uma instância atual, use o comando gcloud compute instances set-scheduling com uma ou mais das seguintes flags:

  • Para mudar o comportamento de manutenção do host, inclua a flag --maintenance-policy.

  • Para mudar o comportamento de reinicialização automática, siga um destes procedimentos:

    • Para reiniciar a instância automaticamente, inclua a flag --restart-on-failure.

    • Para impedir que a instância seja reiniciada automaticamente, inclua a flag --no-restart-on-failure.

  • Para mudar o tempo limite de recuperação de dados do SSD local se a instância tiver discos SSD locais conectados, inclua a flag --local-ssd-recovery-timeout.

  • Para mudar o tempo limite de erro do host, inclua a flag --host-error-timeout-seconds.

Por exemplo, para mudar o comportamento de manutenção do host, reinicie automaticamente a instância após erros do host ou paradas programadas, mude o tempo limite de recuperação de dados do SSD local e mude o tempo limite de erro do host, execute o seguinte comando:

gcloud compute instances set-scheduling INSTANCE_NAME \
    --host-error-timeout-seconds=ERROR_DETECTION_TIMEOUT \
    --local-ssd-recovery-timeout=LOCAL_SSD_RECOVERY_TIMEOUT \
    --maintenance-policy=MAINTENANCE_POLICY \
    --restart-on-failure \
    --zone=ZONE

Substitua:

  • INSTANCE_NAME: o nome da instância.

  • ERROR_DETECTION_TIMEOUT: o número de segundos antes que o Compute Engine reinicie uma instância que não responde. O valor precisa estar entre 90 (90 segundos) e 330 (330 segundos ou 5 minutos e 30 segundos). Somente incrementos de 30 segundos são permitidos.

  • MAINTENANCE_POLICY: o comportamento de manutenção da instância. O valor pode ser TERMINATE ou MIGRATE.

  • LOCAL_SSD_RECOVERY_TIMEOUT: o número de horas usadas na recuperação de dados dos discos SSD locais anexados. O valor precisa estar entre 0 (0 horas) e 168 (168 horas ou 7 dias). Definir esse campo como 0 significa que o Compute Engine não recupera dados do SSD local.

  • ZONE: a zona em que a instância existe.

REST

Para mudar a política de manutenção do host em uma instância, faça uma solicitação POST para o método instances.setScheduling. No corpo da solicitação, inclua um ou mais dos seguintes campos:

  • Para mudar o comportamento de manutenção do host, inclua o campo onHostMaintenance.

  • Para mudar o comportamento de reinicialização automática, siga um destes procedimentos:

    • Para reiniciar a instância automaticamente, inclua o campo automaticRestart.

    • Para impedir que a instância seja reiniciada automaticamente, inclua o campo automaticRestart.

  • Para mudar o tempo limite de recuperação de dados do SSD local se a instância tiver discos SSD locais conectados, inclua o campo localSsdRecoveryTimeout.

  • Para mudar o tempo limite de erro do host, inclua o campo hostErrorTimeoutSeconds.

Por exemplo, para mudar o comportamento de manutenção do host, reinicie automaticamente a instância após erros do host ou paradas programadas, mude o tempo limite de recuperação de dados do SSD local e altere o tempo limite de erro do host. Faça uma solicitação da seguinte maneira:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/setScheduling

{
  "automaticRestart": AUTOMATIC_RESTART,
  "hostErrorTimeoutSeconds": ERROR_DETECTION_TIMEOUT,
  "localSsdRecoveryTimeout": LOCAL_SSD_RECOVERY_TIMEOUT,
  "onHostMaintenance": "MAINTENANCE_POLICY"
}

Substitua:

  • PROJECT_ID: o ID do projeto em que a instância existe.

  • ZONE: a zona em que a instância existe.

  • INSTANCE_NAME: o nome da instância.

  • AUTOMATIC_RESTART: o comportamento de reinicialização automática da instância se ela falhar ou se o Compute Engine a interromper para uma parada programada. Especifique um dos seguintes valores:

    • Para permitir que o Compute Engine reinicie sua instância automaticamente: true

    • Para evitar reinicializações automáticas: false

  • ERROR_DETECTION_TIMEOUT: o número de segundos antes de reiniciar uma instância que não responde. O valor precisa estar entre 90 (90 segundos) e 330 (330 segundos ou 5 minutos e 30 segundos). Somente incrementos de 30 segundos são permitidos.

  • LOCAL_SSD_RECOVERY_TIMEOUT: o número de horas usadas na recuperação de dados dos discos SSD locais anexados. O valor precisa estar entre 0 (0 horas) e 168 (168 horas ou 7 dias). Definir esse campo como 0 significa que o Compute Engine não recupera dados do SSD local.

  • MAINTENANCE_POLICY: o comportamento de manutenção da instância. O valor pode ser TERMINATE ou MIGRATE.

Definir a política ao criar uma instância

É possível definir a política de manutenção do host de uma instância de computação durante a criação.

Para definir o tempo limite de recuperação de dados do SSD local ao criar uma instância com discos SSD locais anexados, use a gcloud CLI ou a API REST. Caso contrário, selecione uma das seguintes opções:

Console

  1. No console do Google Cloud, acesse a página Criar uma instância.

    Acesse "Criar uma instância"

  2. No campo Nome, insira um nome para a instância.

  3. Nos campos Região e Zona, especifique em qual região e zona criar a instância.

  4. Especifique o tipo de máquina para a instância.

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

  6. Na seção Modelo de provisionamento, abra Configurações avançadas do modelo de provisionamento de VM e faça uma ou mais das seguintes ações:

    • Para definir o comportamento durante os eventos de manutenção, na lista Na manutenção do host, selecione uma das seguintes opções:

      • Para migrar a instância durante eventos de manutenção do host, selecione Migrar instância da VM (recomendado).

      • Para interromper a instância durante eventos de manutenção do host, selecione Encerrar instância da VM.

    • Para definir o período de tempo limite antes de reiniciar uma instância que não responde, na lista Tempo limite de erro do host, selecione uma das seguintes opções:

      • Para não especificar um tempo limite de erro do host, selecione Não especificado (padrão).

      • Para especificar um tempo limite de erro do host, selecione uma das opções disponíveis, até 5 minutos e 30 segundos.

    • Para definir se a instância será reiniciada se falhar ou for interrompida, na lista Reinicialização automática, selecione uma das seguintes opções:

      • Para reiniciar automaticamente a instância após erros de host ou paradas programadas, selecione Ativar (recomendado).

      • Para impedir que a instância seja reiniciada automaticamente após erros do host ou paradas programadas, selecione Desativado.

  7. Clique em Criar.

gcloud

Para definir a política de manutenção do host de uma instância durante a criação, use o comando gcloud compute instances create com uma ou mais das seguintes flags:

  • Para definir o comportamento de manutenção do host, inclua a flag --maintenance-policy.

  • Para definir o comportamento de reinicialização automática, faça o seguinte:

    • Para reiniciar a instância automaticamente, inclua a flag --restart-on-failure.

    • Para impedir que a instância seja reiniciada automaticamente, inclua a flag --no-restart-on-failure.

  • Para definir um tempo limite de recuperação de dados do SSD local se a instância tiver discos SSD locais anexados, inclua a flag --local-ssd-recovery-timeout.

  • Para definir um tempo limite de erro do host, inclua a flag --host-error-timeout-seconds.

Por exemplo, para definir o comportamento de manutenção do host, reinicie automaticamente a instância após erros do host ou paradas programadas, defina um tempo limite de recuperação de dados do SSD local e um tempo limite de erro do host, executando o seguinte comando:

gcloud compute instances create INSTANCE_NAME \
    --host-error-timeout-seconds=ERROR_DETECTION_TIMEOUT \
    --local-ssd-recovery-timeout=LOCAL_SSD_RECOVERY_TIMEOUT \
    --machine-type=MACHINE_TYPE \
    --maintenance-policy=MAINTENANCE_POLICY \
    --restart-on-failure \
    --zone=ZONE

Substitua:

  • INSTANCE_NAME: o nome da instância.

  • ERROR_DETECTION_TIMEOUT: o número de segundos antes de reiniciar uma instância que não responde. O valor precisa estar entre 90 (90 segundos) e 330 (330 segundos ou 5 minutos e 30 segundos). Somente incrementos de 30 segundos são permitidos.

  • LOCAL_SSD_RECOVERY_TIMEOUT: o número de horas usadas na recuperação de dados dos discos SSD locais anexados. O valor precisa estar entre 0 (0 horas) e 168 (168 horas ou 7 dias). Definir esse campo como 0 significa que o Compute Engine não recupera dados do SSD local.

  • MACHINE_TYPE: o tipo de máquina a ser usado.

  • MAINTENANCE_POLICY: o comportamento de manutenção da instância. O valor pode ser TERMINATE ou MIGRATE. Se você estiver criando uma VM spot, uma VM preemptiva ou uma instância que não ofereça suporte à migração em tempo real, só poderá usar TERMINATE.

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

REST

Para definir a política de manutenção do host de uma instância durante a criação, faça uma solicitação POST para o método instances.insert. No corpo da solicitação, inclua um ou mais dos seguintes campos no campo scheduling:

  • Para definir o comportamento de manutenção do host, inclua o campo onHostMaintenance.

  • Para definir o comportamento de reinicialização automática, faça o seguinte:

    • Para reiniciar a instância automaticamente, inclua o campo automaticRestart.

    • Para impedir que a instância seja reiniciada automaticamente, inclua o campo automaticRestart.

  • Para definir um tempo limite de recuperação de dados do SSD local se a instância tiver discos SSD locais conectados, inclua o campo localSsdRecoveryTimeout.

  • Para definir um tempo limite de erro do host, inclua o campo hostErrorTimeoutSeconds.

Por exemplo, para definir o comportamento de manutenção do host, reinicie automaticamente a instância após erros do host ou paradas programadas, defina um tempo limite de recuperação de dados do SSD local e defina um tempo limite de erro do host. Faça uma solicitação da seguinte maneira:

POST https://compute.googleapis.com/compute/v1/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": {
    "automaticRestart": AUTOMATIC_RESTART,
    "hostErrorTimeoutSeconds": ERROR_DETECTION_TIMEOUT,
    "localSsdRecoveryTimeout": LOCAL_SSD_RECOVERY_TIMEOUT,
    "onHostMaintenance": "MAINTENANCE_POLICY"
  }
}

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 a ser usado.

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

  • AUTOMATIC_RESTART: o comportamento de reinicialização automática da instância se ela falhar ou se o Compute Engine a interromper para uma parada programada. Especifique um dos seguintes valores:

    • Para permitir que o Compute Engine reinicie sua instância automaticamente: true

    • Para evitar reinicializações automáticas: false

  • ERROR_DETECTION_TIMEOUT: o número de segundos antes de reiniciar uma instância que não responde. O valor precisa estar entre 90 (90 segundos) e 330 (330 segundos ou 5 minutos e 30 segundos). Somente incrementos de 30 segundos são permitidos.

  • LOCAL_SSD_RECOVERY_TIMEOUT: o número de horas usadas na recuperação de dados dos discos SSD locais anexados. O valor precisa estar entre 0 (0 horas) e 168 (168 horas ou 7 dias). Definir esse campo como 0 significa que o Compute Engine não recupera dados do SSD local.

  • MAINTENANCE_POLICY: o comportamento de manutenção da instância. O valor pode ser TERMINATE ou MIGRATE. Se você estiver criando uma VM spot ou uma instância que não ofereça suporte à migração em tempo real, só será possível usar TERMINATE.

Para mais informações sobre como criar uma instância, consulte Criar e iniciar uma instância do Compute Engine.

Definir a política ao criar instâncias em massa

Para definir a política de manutenção do host ao criar instâncias em massa, selecione uma das seguintes opções:

gcloud

Para definir a política de manutenção do host ao criar instâncias em massa, use o comando gcloud compute instances bulk create com uma ou mais das seguintes flags:

  • Para definir o comportamento de manutenção do host, inclua a flag --maintenance-policy.

  • Para definir o comportamento de reinicialização automática, faça o seguinte:

    • Para reiniciar a instância automaticamente, inclua a flag --restart-on-failure.

    • Para impedir que a instância seja reiniciada automaticamente, inclua a flag --no-restart-on-failure.

  • Para definir um tempo limite de recuperação de dados do SSD local se a instância tiver discos SSD locais anexados, inclua a flag --local-ssd-recovery-timeout.

  • Para definir um tempo limite de erro do host, inclua a flag --host-error-timeout-seconds.

Por exemplo, para definir o comportamento de manutenção do host, reinicie automaticamente a instância após erros do host ou paradas programadas, defina um tempo limite de recuperação de dados do SSD local e defina um tempo limite de erro do host. Para isso, execute o comando a seguir. O exemplo a seguir também cria instâncias em uma única zona e especifica um padrão de nome para elas:

gcloud compute instances bulk create \
    --count=COUNT \
    --host-error-timeout-seconds=ERROR_DETECTION_TIMEOUT \
    --local-ssd-recovery-timeout=LOCAL_SSD_RECOVERY_TIMEOUT \
    --machine-type=MACHINE_TYPE \
    --maintenance-policy=MAINTENANCE_POLICY \
    --name-pattern=NAME_PATTERN \
    --restart-on-failure \
    --zone=ZONE

Substitua:

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

  • ERROR_DETECTION_TIMEOUT: o número de segundos antes de reiniciar uma instância que não responde. O valor precisa estar entre 90 (90 segundos) e 330 (330 segundos ou 5 minutos e 30 segundos). Somente incrementos de 30 segundos são permitidos.

  • LOCAL_SSD_RECOVERY_TIMEOUT: o número de horas usadas na recuperação de dados dos discos SSD locais anexados. O valor precisa estar entre 0 (0 horas) e 168 (168 horas ou 7 dias). Definir esse campo como 0 significa que o Compute Engine não recupera dados do SSD local.

  • MACHINE_TYPE: o tipo de máquina a ser usado.

  • MAINTENANCE_POLICY: o comportamento de manutenção das instâncias. O valor pode ser TERMINATE ou MIGRATE. Se você estiver criando VMs Spot, VMs preemptivas ou instâncias que não oferecem suporte à migração em tempo real, só poderá usar TERMINATE.

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

  • ZONE: a zona em que as instâncias serão criadas.

REST

Para definir a política de manutenção do host ao criar instâncias em massa, faça uma solicitação POST para o método instances.bulkInsert. No corpo da solicitação, inclua um ou mais dos seguintes campos no campo scheduling:

  • Para definir o comportamento de manutenção do host, inclua o campo onHostMaintenance.

  • Para definir o comportamento de reinicialização automática, faça o seguinte:

    • Para reiniciar a instância automaticamente, inclua o campo automaticRestart.

    • Para impedir que a instância seja reiniciada automaticamente, inclua o campo automaticRestart.

  • Para definir um tempo limite de recuperação de dados do SSD local se a instância tiver discos SSD locais conectados, inclua o campo localSsdRecoveryTimeout.

  • Para definir um tempo limite de erro do host, inclua o campo hostErrorTimeoutSeconds.

Por exemplo, para definir o comportamento de manutenção do host, reinicie automaticamente a instância após erros do host ou paradas programadas, defina um tempo limite de recuperação de dados do SSD local e defina um tempo limite de erro do host. Faça uma solicitação da seguinte maneira. O exemplo a seguir também cria instâncias em uma única zona e especifica um padrão de nome para elas:

POST https://compute.googleapis.com/compute/v1/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": {
      "automaticRestart": AUTOMATIC_RESTART,
      "hostErrorTimeoutSeconds": ERROR_DETECTION_TIMEOUT,
      "localSsdRecoveryTimeout": LOCAL_SSD_RECOVERY_TIMEOUT,
      "onHostMaintenance": "MAINTENANCE_POLICY"
    }
  }
}

Substitua:

  • PROJECT_ID: o ID do projeto em que as instâncias serão criadas.

  • ZONE: a zona em que as instâncias serão criadas.

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

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

  • MACHINE_TYPE: o tipo de máquina a ser usado.

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

  • AUTOMATIC_RESTART: o comportamento de reinicialização automática da instância se ela falhar ou se o Compute Engine a interromper para uma parada programada. Especifique um dos seguintes valores:

    • Para permitir que o Compute Engine reinicie sua instância automaticamente: true

    • Para evitar reinicializações automáticas: false

  • ERROR_DETECTION_TIMEOUT: o número de segundos antes de reiniciar uma instância que não responde. O valor precisa estar entre 90 (90 segundos) e 330 (330 segundos ou 5 minutos e 30 segundos). Somente incrementos de 30 segundos são permitidos.

  • LOCAL_SSD_RECOVERY_TIMEOUT: o número de horas usadas na recuperação de dados dos discos SSD locais anexados. O valor precisa estar entre 0 (0 horas) e 168 (168 horas ou 7 dias). Definir esse campo como 0 significa que o Compute Engine não recupera dados do SSD local.

  • MAINTENANCE_POLICY: o comportamento de manutenção das instâncias. O valor pode ser TERMINATE ou MIGRATE. Se você estiver criando VMs Spot, VMs preemptivas ou instâncias que não oferecem suporte à migração em tempo real, só poderá usar TERMINATE.

Para mais informações sobre a criação de instâncias em massa, consulte Criar VMs em massa.

Definir a política ao criar um modelo de instância

É possível definir a política de manutenção do host ao criar um modelo de instância. Todas as instâncias de computação criadas com o modelo herdam a política de manutenção do host especificada no modelo.

Para definir o tempo limite de recuperação de dados do SSD local ao criar um modelo de instância que especifique discos SSD locais, use a CLI gcloud ou a API REST. Caso contrário, selecione uma das seguintes opções:

Console

  1. No Console do Google 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 modelo de instância é exibida.

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

  4. Na seção Local, selecione uma das seguintes opções:

    • Para criar um modelo de instância regional, selecione Regional (recomendado) e escolha a região em que o modelo será criado.

    • Para criar um modelo de instância global, selecione Global.

  5. Na seção Configuração da máquina, especifique o tipo de máquina para o modelo de instância.

  6. Na seção Modelo de provisionamento, abra Configurações avançadas do modelo de provisionamento de VM e faça uma ou mais das seguintes ações:

    • Para mudar o comportamento durante os eventos de manutenção, na lista Na manutenção do host, selecione uma das seguintes opções:

      • Para migrar a instância durante eventos de manutenção do host, selecione Migrar instância da VM (recomendado).

      • Para interromper a instância durante eventos de manutenção do host, selecione Encerrar instância da VM.

    • Para mudar o período de tempo limite antes de reiniciar uma instância que não responde, na lista Tempo limite de erro do host, selecione uma das seguintes opções:

      • Para não especificar um tempo limite de erro do host, selecione Não especificado (padrão).

      • Para especificar um tempo limite de erro do host, selecione uma das opções disponíveis, até 5 minutos e 30 segundos.

    • Para mudar se a instância será reiniciada se falhar ou for interrompida, na lista Reinicialização automática, selecione uma das seguintes opções:

      • Para reiniciar automaticamente a instância após erros de host ou paradas programadas, selecione Ativar (recomendado).

      • Para impedir que a instância seja reiniciada automaticamente após erros do host ou paradas programadas, selecione Desativado.

  7. Clique em Criar.

gcloud

Para definir a política de manutenção do host ao criar um modelo de instância, use o comando gcloud compute instance-templates create com uma ou mais das seguintes flags:

  • Para definir o comportamento de manutenção do host, inclua o campo onHostMaintenance.

  • Para definir o comportamento de reinicialização automática, faça o seguinte:

    • Para reiniciar a instância automaticamente, inclua o campo automaticRestart.

    • Para impedir que a instância seja reiniciada automaticamente, inclua o campo automaticRestart.

  • Para definir um tempo limite de recuperação de dados do SSD local se a instância tiver discos SSD locais conectados, inclua o campo localSsdRecoveryTimeout.

  • Para definir um tempo limite de erro do host, inclua o campo hostErrorTimeoutSeconds.

Por exemplo, para definir o comportamento de manutenção do host, reinicie automaticamente a instância após erros do host ou paradas programadas, defina um tempo limite de recuperação de dados do SSD local e defina um tempo limite de erro do host. Para isso, execute o comando a seguir. O exemplo a seguir também cria um modelo de instância regional. Para criar um modelo de instância global, use o mesmo comando sem a flag --instance-template-region.

gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
    --host-error-timeout-seconds=ERROR_DETECTION_TIMEOUT \
    --instance-template-region=REGION \
    --local-ssd-recovery-timeout=LOCAL_SSD_RECOVERY_TIMEOUT \
    --machine-type=MACHINE_TYPE \
    --maintenance-policy=MAINTENANCE_POLICY \
    --restart-on-failure

Substitua:

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

  • ERROR_DETECTION_TIMEOUT: o número de segundos antes de reiniciar uma instância que não responde. O valor precisa estar entre 90 (90 segundos) e 330 (330 segundos ou 5 minutos e 30 segundos). Somente incrementos de 30 segundos são permitidos.

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

  • LOCAL_SSD_RECOVERY_TIMEOUT: o número de horas usadas na recuperação de dados dos discos SSD locais anexados. O valor precisa estar entre 0 (0 horas) e 168 (168 horas ou 7 dias). Definir esse campo como 0 significa que o Compute Engine não recupera dados do SSD local.

  • MACHINE_TYPE: o tipo de máquina a ser usado.

  • MAINTENANCE_POLICY: o comportamento de manutenção das instâncias. O valor pode ser TERMINATE ou MIGRATE. Se você estiver especificando uma VM do Spot, uma VM preemptiva ou um tipo de instância que não ofereça suporte à migração em tempo real no modelo de instância, só será possível usar TERMINATE.

REST

Para definir a política de manutenção do host ao criar um modelo de instância, faça uma solicitação POST para um dos seguintes métodos:

No corpo da solicitação, inclua um ou mais dos seguintes campos no campo scheduling:

  • Para definir o comportamento de manutenção do host, inclua o campo onHostMaintenance.

  • Para definir o comportamento de reinicialização automática, faça o seguinte:

    • Para reiniciar a instância automaticamente, inclua o campo automaticRestart.

    • Para impedir que a instância seja reiniciada automaticamente, inclua o campo automaticRestart.

  • Para definir um tempo limite de recuperação de dados do SSD local se a instância tiver discos SSD locais conectados, inclua o campo localSsdRecoveryTimeout.

  • Para definir um tempo limite de erro do host, inclua o campo hostErrorTimeoutSeconds.

Por exemplo, para definir o comportamento de manutenção do host, reinicie automaticamente a instância após erros do host ou paradas programadas, defina um tempo limite de recuperação de dados do SSD local e defina um tempo limite de erro do host. Faça uma solicitação da seguinte maneira. O exemplo a seguir também cria um modelo de instância regional.

POST https://compute.googleapis.com/compute/v1/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": {
      "automaticRestart": AUTOMATIC_RESTART,
      "hostErrorTimeoutSeconds": ERROR_DETECTION_TIMEOUT,
      "localSsdRecoveryTimeout": LOCAL_SSD_RECOVERY_TIMEOUT,
      "onHostMaintenance": "MAINTENANCE_POLICY"
    }
  }
}

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. 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 a ser usado.

  • AUTOMATIC_RESTART: o comportamento de reinicialização automática da instância se ela falhar ou se o Compute Engine a interromper para uma parada programada. Especifique um dos seguintes valores:

    • Para permitir que o Compute Engine reinicie sua instância automaticamente: true

    • Para evitar reinicializações automáticas: false

  • ERROR_DETECTION_TIMEOUT: o número de segundos antes de reiniciar uma instância que não responde. O valor precisa estar entre 90 (90 segundos) e 330 (330 segundos ou 5 minutos e 30 segundos). Somente incrementos de 30 segundos são permitidos.

  • LOCAL_SSD_RECOVERY_TIMEOUT: o número de horas usadas na recuperação de dados dos discos SSD locais anexados. O valor precisa estar entre 0 (0 horas) e 168 (168 horas ou 7 dias). Definir esse campo como 0 significa que o Compute Engine não recupera dados do SSD local.

  • MAINTENANCE_POLICY: o comportamento de manutenção das instâncias. O valor pode ser TERMINATE ou MIGRATE. Se você estiver especificando uma VM do Spot, uma VM preemptiva ou um tipo de instância que não ofereça suporte à migração em tempo real no modelo de instância, só será possível usar TERMINATE.

Para mais informações sobre como criar um modelo de instância, consulte Criar modelos de instância.

Conferir a política de manutenção do host de uma instância

Para conferir a política de manutenção do host de uma instância, acesse os detalhes dela.

Ao conferir os detalhes da instância usando a CLI gcloud ou a API REST, só é possível visualizar os campos localSsdRecoveryTimeout e hostErrorTimeoutSeconds se eles foram especificados ao criar ou atualizar a instância.

Para conferir o tempo limite de recuperação de dados do SSD local em uma instância com discos SSD locais conectados, use a CLI gcloud ou a API REST. Caso contrário, selecione uma das seguintes opções:

Console

  1. No console do Google Cloud, acesse a página Instâncias de VMs.

    Acessar instâncias de VM

  2. Na coluna Nome, clique na instância que você quer consultar. Uma página com os detalhes da instância aparece.

  3. Na guia Detalhes, na seção Gerenciamento, na seção Políticas de disponibilidade, você pode conferir o seguinte:

    • No campo On host maintenance, é possível conferir os eventos de comportamento de manutenção do host da instância.

    • No campo Tempo limite de erro do host, é possível conferir o tempo que a instância aguarda antes de reiniciar ou parar depois de detectar que ela não está respondendo. Se o valor não estiver definido (—), o tempo de espera padrão será de 5 minutos e 30 segundos.

    • No campo Reinício automático, é possível saber se a instância é reiniciada automaticamente após uma falha ou se o Compute Engine a interrompe para uma parada programada.

gcloud

Para conferir a política de manutenção do host de uma instância, use o comando gcloud compute instances describe com a flag --flatten definida como scheduling:

 gcloud compute instances describe INSTANCE_NAME \
    --flatten=scheduling \
    --zone=ZONE

Substitua:

  • INSTANCE_NAME: o nome da instância.

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

O resultado será assim:

---
scheduling:
  automaticRestart: true
  hostErrorTimeoutSeconds: 120
  localSsdRecoveryTimeout:
    nanos: 0
    seconds: '10800'
  onHostMaintenance: MIGRATE
  preemptible: false
  provisioningModel: STANDARD

REST

Para conferir a política de manutenção do host de uma instância, faça uma solicitação GET para o método instances.get. No URL da solicitação, inclua o parâmetro de consulta fields e defina-o como scheduling:

  GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?fields=scheduling

Substitua:

  • PROJECT_ID: o projeto em que a instância existe.

  • ZONE: a zona em que a instância existe.

  • INSTANCE_NAME: o nome da instância.

O resultado será assim:

{
  "scheduling": {
    "onHostMaintenance": "MIGRATE",
    "automaticRestart": true,
    "preemptible": false,
    "provisioningModel": "STANDARD",
    "localSsdRecoveryTimeout": {
      "seconds": "10800",
      "nanos": 0
    }
  }
}

A seguir