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

Neste documento, explicamos 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, consulte Política de manutenção do host.

Uma política de manutenção do host define 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 você a:

  • Diminuir o tempo de inatividade.

  • Evitar a perda de dados.

Limitações

Para 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 fazer migração em tempo real durante eventos de manutenção do host, a menos que sejam VMs spot ou preemptivas.

  • As seguintes instâncias 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 interrupções programadas.

Antes de começar

  • 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ódigo ou exemplos em um ambiente de desenvolvimento local, faça a autenticação no Compute Engine com um destes métodos:

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

      gcloud init

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

    2. Set a default region and zone.

    REST

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

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

      gcloud init

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

    Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Papéis necessários

Para receber as permissões necessárias para definir a política de manutenção do host em uma instância de computação, peça ao admin 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 em uma instância de computação. Para acessar as permissões exatas necessárias, abra 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 em uma instância de computação:

  • Criar uma instância:
    • compute.instances.create no projeto
    • Usar uma imagem personalizada para criar a VM: compute.images.useReadOnly na imagem
    • Utilizar 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 da 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
  • Criar um modelo de instância: compute.instanceTemplates.create no projeto
  • Atualizar a política de manutenção do host em 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

Você pode personalizar o comportamento da sua 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 vai usar as configurações padrão ao criar uma instância, várias instâncias ou um modelo de instância. Instância ou modelo de instância do

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

  • Comportamento de manutenção (onHostMaintenance): o que acontece com sua 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 uma das seguintes opções:

    • Migração: o Compute Engine faz a migração em tempo real da 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 preemptivas e a única configuração compatível com instâncias Z3 com mais de 18 TiB de SSD Titanium anexado, instâncias bare metal e instâncias com GPUs ou TPUs anexadas.

  • Reinicialização automática (automaticRestart): se a instância será reiniciada em caso de falha ou se o Compute Engine vai pausá-la para uma interrupção programada, como um evento de manutenção. É possível definir essa propriedade como uma das seguintes opções:

    • 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 preemptivas. Você especifica essa configuração da seguinte maneira:

      • Para o console do Google Cloud , no painel Avançado da lista Reinicialização automática, selecione Ativado (recomendado).

      • 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. Você especifica essa configuração da seguinte maneira:

      • Para o console do Google Cloud , no painel Avançado da lista Reinicialização automática, selecione Desativado.

      • Para a gcloud CLI, 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. Ela determina quanto tempo o Compute Engine aguarda para recuperar dados dos seus discos SSD locais após erros do host. Por padrão, essa propriedade não é definida. Você pode defini-la 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. Se você definir essa propriedade como 0, o Compute Engine não vai recuperar os dados do SSD local, reiniciando 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. Configure essa opção antes que a instância pare de responder. Use um tempo limite longo o suficiente para que uma instância se recupere de um estado sem resposta. É possível definir essa propriedade como uma das seguintes opções:

    • 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 em uma instância

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

Definir a política em uma instância atual

Antes de mudar a política de manutenção do host em uma instância, confirme 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 spot ou preemptivas para reinicialização automática após erros do host ou interrupções programadas.

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

Console

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

    Acessar "Instâncias de VM"

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

  3. Clique em Editar. Uma página para modificar as propriedades da instância vai aparecer.

  4. Na seção Gerenciamento, é possível realizar pelo menos uma destas ações:

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

    • Se quiser alterar o tempo limite antes de reiniciar uma instância que não responde, escolha outra opção na lista Tempo limite de erro do host.

    • Para definir se a instância será reiniciada ou não após erros do host ou interrupções 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, use o comando gcloud compute instances set-scheduling com pelo menos uma destas flags:

  • Se quiser alterar o comportamento da manutenção do host, inclua a flag --maintenance-policy.

  • Para mudar o comportamento de reinicialização automática, siga uma destas opções:

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

    • Se quiser evitar a reinicialização automática da instância, adicione 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 anexados, inclua a flag --local-ssd-recovery-timeout.

  • Se quiser alterar o tempo limite de erro do host, adicione a flag --host-error-timeout-seconds.

Por exemplo, para mudar o comportamento de manutenção do host, reiniciar automaticamente a instância após erros do host ou interrupções programadas, alterar o tempo limite de recuperação de dados do SSD local e modificar 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 de o Compute Engine 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). São permitidos apenas incrementos de 30 segundos.

  • 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). Se você definir esse campo como 0, o Compute Engine não vai recuperar dados do SSD local.

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

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 pelo menos dos seguintes campos:

  • Se quiser alterar o comportamento da manutenção do host, inclua o campo onHostMaintenance.

  • Para mudar o comportamento de reinicialização automática, siga uma destas opções:

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

    • Se quiser evitar a reinicialização automática da instância, adicione o campo automaticRestart.

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

  • Se quiser alterar o tempo limite de erro do host, adicione o campo hostErrorTimeoutSeconds.

Por exemplo, para mudar o comportamento de manutenção do host, reiniciar automaticamente a instância após erros do host ou interrupções programadas, alterar o tempo limite de recuperação de dados do SSD local e modificar o tempo limite de erro do host, envie uma solicitação da seguinte forma:

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 está.

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

  • 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 pausá-la para uma interrupção programada. Especifique um dos seguintes valores:

    • Para autorizar o Compute Engine a reiniciar 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). São permitidos apenas incrementos de 30 segundos.

  • 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). Se você definir esse campo como 0, o Compute Engine não vai recuperar 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 em uma instância de computação ao criá-la.

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 destas opções:

Console

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

    Acessar "Criar uma instância"

  2. No campo Nome, dê 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. Defina o tipo de máquina da 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 realize pelo menos uma destas ações:

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

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

      • Se quiser interromper a instância durante esses eventos, escolha Encerrar instância da VM.

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

      • Se não quiser determinar um tempo limite de erro do host, selecione Não especificado (padrão).

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

    • Para definir se a instância será reiniciada em caso de falha ou interrupção, na lista Reinicialização automática, selecione uma destas opções:

      • Se quiser reiniciar automaticamente a instância após erros do host ou interrupções programadas, escolha Ativar (recomendado).

      • Para evitar a reinicialização automática da instância após erros do host ou interrupções programadas, selecione Desativado.

  7. Clique em Criar.

gcloud

Para definir a política de manutenção do host em uma instância durante a criação, use o comando gcloud compute instances create com pelo menos uma destas flags:

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

  • Se quiser definir o comportamento de reinicialização automática, siga uma destas opções:

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

    • Se quiser evitar a reinicialização automática da instância, adicione 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.

  • Se quiser definir um tempo limite de erro do host, adicione a flag --host-error-timeout-seconds.

Por exemplo, para definir o comportamento de manutenção do host, reiniciar automaticamente a instância após erros do host ou interrupções programadas, definir um tempo limite de recuperação de dados do SSD local e escolher um tempo limite de erro do host, execute 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). São permitidos apenas incrementos de 30 segundos.

  • 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). Se você definir esse campo como 0, o Compute Engine não vai recuperar dados do SSD local.

  • MACHINE_TYPE: o tipo de máquina que 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 é compatível com a migração em tempo real, só será possível usar TERMINATE.

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

REST

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

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

  • Se quiser definir o comportamento de reinicialização automática, siga uma destas opções:

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

    • Se quiser evitar a reinicialização automática da instância, adicione o campo automaticRestart.

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

  • Se quiser definir um tempo limite de erro do host, adicione o campo hostErrorTimeoutSeconds.

Por exemplo, para definir o comportamento de manutenção do host, reiniciar automaticamente a instância após erros do host ou interrupções programadas, definir um tempo limite de recuperação de dados do SSD local e escolher um tempo limite de erro do host, envie uma solicitação da seguinte forma:

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 que será usado.

  • IMAGE_PROJECT: o projeto que contém a imagem, como debian-cloud. Para mais detalhes sobre os projetos de imagem disponíveis, consulte Imagens públicas.

  • IMAGE: especifique uma destas opções:

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

    • Uma família de imagens, que precisa ter o formato family/IMAGE_FAMILY. Ela 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 detalhes, 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 pausá-la para uma interrupção programada. Especifique um dos seguintes valores:

    • Para autorizar o Compute Engine a reiniciar 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). São permitidos apenas incrementos de 30 segundos.

  • 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). Se você definir esse campo como 0, o Compute Engine não vai recuperar 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 é compatível com a migração em tempo real, só será possível usar TERMINATE.

Saiba como criar uma instância em Criar e iniciar uma instância do Compute Engine.

Definir a política ao criar várias instâncias

Para definir a política de manutenção do host ao criar várias instâncias, selecione uma destas opções:

gcloud

Para definir a política de manutenção do host ao criar várias instâncias, use o comando gcloud compute instances bulk create com pelo menos uma destas flags:

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

  • Se quiser definir o comportamento de reinicialização automática, siga uma destas opções:

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

    • Se quiser evitar a reinicialização automática da instância, adicione 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.

  • Se quiser definir um tempo limite de erro do host, adicione a flag --host-error-timeout-seconds.

Por exemplo, para definir o comportamento de manutenção do host, reiniciar automaticamente a instância após erros do host ou interrupções programadas, definir um tempo limite de recuperação de dados do SSD local e escolher um tempo limite de erro do host, execute o comando abaixo. 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 que serão 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). São permitidos apenas incrementos de 30 segundos.

  • 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). Se você definir esse campo como 0, o Compute Engine não vai recuperar dados do SSD local.

  • MACHINE_TYPE: o tipo de máquina que 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 são compatíveis com a migração em tempo real, só será possível 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-# no 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 várias instâncias, envie uma solicitação POST para o método instances.bulkInsert. No corpo da solicitação, inclua pelo menos um dos seguintes campos no campo scheduling:

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

  • Se quiser definir o comportamento de reinicialização automática, siga uma destas opções:

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

    • Se quiser evitar a reinicialização automática da instância, adicione o campo automaticRestart.

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

  • Se quiser definir um tempo limite de erro do host, adicione o campo hostErrorTimeoutSeconds.

Por exemplo, para definir o comportamento de manutenção do host, reiniciar automaticamente a instância após erros do host ou interrupções programadas, definir um tempo limite de recuperação de dados do SSD local e escolher um tempo limite de erro do host, envie uma solicitação da forma especificada abaixo. 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 que serão 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-# no 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 que será usado.

  • IMAGE_PROJECT: o projeto que contém a imagem, como debian-cloud. Para mais detalhes sobre os projetos de imagem disponíveis, consulte Imagens públicas.

  • IMAGE: especifique uma destas opções:

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

    • Uma família de imagens, que precisa ter o formato family/IMAGE_FAMILY. Ela 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 detalhes, 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 pausá-la para uma interrupção programada. Especifique um dos seguintes valores:

    • Para autorizar o Compute Engine a reiniciar 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). São permitidos apenas incrementos de 30 segundos.

  • 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). Se você definir esse campo como 0, o Compute Engine não vai recuperar 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 são compatíveis com a migração em tempo real, só será possível usar TERMINATE.

Para mais detalhes, 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 usando 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 especifica discos SSD locais, use a gcloud CLI ou a API REST. Caso contrário, selecione uma destas opções:

Console

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

    Acessar "Modelos de instância"

  2. Clique em Criar modelo de instância para abrir essa página.

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

  4. Na seção Local, escolha uma destas opções:

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

    • 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 realize pelo menos uma destas ações:

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

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

      • Se quiser interromper a instância durante esses eventos, escolha Encerrar instância da VM.

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

      • Se não quiser determinar um tempo limite de erro do host, selecione Não especificado (padrão).

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

    • Para mudar se a instância será reiniciada em caso de falha ou interrupção, na lista Reinicialização automática, selecione uma destas opções:

      • Se quiser reiniciar automaticamente a instância após erros do host ou interrupções programadas, escolha Ativar (recomendado).

      • Para evitar a reinicialização automática da instância após erros do host ou interrupções 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 pelo menos uma destas flags:

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

  • Se quiser definir o comportamento de reinicialização automática, siga uma destas opções:

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

    • Se quiser evitar a reinicialização automática da instância, adicione o campo automaticRestart.

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

  • Se quiser definir um tempo limite de erro do host, adicione o campo hostErrorTimeoutSeconds.

Por exemplo, para definir o comportamento de manutenção do host, reiniciar automaticamente a instância após erros do host ou interrupções programadas, definir um tempo limite de recuperação de dados do SSD local e escolher um tempo limite de erro do host, execute o comando abaixo. O exemplo a seguir também cria um modelo de instância regional. Para criar um modelo desses, 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). São permitidos apenas incrementos de 30 segundos.

  • 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). Se você definir esse campo como 0, o Compute Engine não vai recuperar dados do SSD local.

  • MACHINE_TYPE: o tipo de máquina que 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 spot, uma VM preemptiva ou um tipo de instância que não é compatível com a 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, envie uma solicitação POST para um dos seguintes métodos:

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

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

  • Se quiser definir o comportamento de reinicialização automática, siga uma destas opções:

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

    • Se quiser evitar a reinicialização automática da instância, adicione o campo automaticRestart.

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

  • Se quiser definir um tempo limite de erro do host, adicione o campo hostErrorTimeoutSeconds.

Por exemplo, para definir o comportamento de manutenção do host, reiniciar automaticamente a instância após erros do host ou interrupções programadas, definir um tempo limite de recuperação de dados do SSD local e escolher um tempo limite de erro do host, envie uma solicitação da forma especificada abaixo. 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 que contém a imagem, como debian-cloud. Para mais detalhes sobre os projetos de imagem disponíveis, consulte Imagens públicas.

  • IMAGE: especifique uma destas opções:

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

    • Uma família de imagens, que precisa ter o formato family/IMAGE_FAMILY. Ela 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 detalhes, consulte Práticas recomendadas para famílias de imagens.

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

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

    • Para autorizar o Compute Engine a reiniciar 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). São permitidos apenas incrementos de 30 segundos.

  • 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). Se você definir esse campo como 0, o Compute Engine não vai recuperar 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 spot, uma VM preemptiva ou um tipo de instância que não é compatível com a migração em tempo real no modelo de instância, só será possível usar TERMINATE.

Para mais detalhes, consulte Criar modelos de instância.

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

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

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

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

Console

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

    Acessar "Instâncias de VM"

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

  3. Na guia Detalhes > Gerenciamento, > Políticas de disponibilidade, você pode conferir o seguinte:

    • No campo Na manutenção do host, aparecem os eventos de comportamento de manutenção do host da instância.

    • No campo Tempo limite de erro do host, é possível ver o tempo que a instância aguarda até a reinicialização ou interrupção após 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 Reinicialização automática, é possível conferir se a instância é reiniciada automaticamente após uma falha ou se o Compute Engine a pausa para uma interrupção programada.

gcloud

Para ver a política de manutenção do host em 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á.

O resultado será assim:

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

REST

Para ver a política de manutenção do host em uma instância, envie 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 está.

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

  • 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