Aplicar automaticamente as atualizações de configuração de VM em um MIG

---

Este documento descreve como aplicar automaticamente atualizações de configuração às instâncias de máquina virtual (VM) em um grupo de instâncias gerenciadas (MIG).

O Compute Engine mantém as VMs em um MIG com base nos componentes de configuração usados: modelo de instância, configuração opcional de todas as instâncias e configuração com estado opcional.

Sempre que você atualiza a configuração da VM de um MIG alterando esses componentes, o Compute Engine aplica automaticamente sua configuração atualizada a novas VMs adicionadas ao grupo.

Para aplicar uma configuração atualizada às VMs atuais, defina uma atualização automática, também conhecida como tipo de atualização proativa. O MIG lança automaticamente as atualizações de configuração para todas ou um subconjunto de VMs do grupo. É possível controlar a velocidade da implantação, o nível de interrupção do serviço e, usando uma atualização Canary, o número de instâncias que o MIG atualiza com a nova configuração. Depois de especificar a nova configuração, você não precisa fornecer mais entrada, e a atualização é concluída por conta própria.

Como alternativa, se você quiser aplicar seletivamente uma nova configuração apenas a novas instâncias ou a instâncias específicas em um MIG, consulte Aplicar seletivamente as atualizações de configuração de VM em um MIG. Para ajudar você a decidir, consulte Métodos para aplicar uma nova configuração a VMs atuais.

Antes de começar

• Se você estiver atualizando um MIG com estado, consulte Como aplicar, visualizar e remover configurações com estado em MIGs.
• 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. Install the Google Cloud CLI, then initialize it by running the following command:

     gcloud init

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
  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 gcloud CLI.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

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

Limitações

• Se você tiver um MIG com estado e quiser usar atualizações graduais automatizadas, será necessário manter os nomes das instâncias ao substituir instâncias, ou então definir o método de substituição como RECREATE de dados.

Início de uma atualização contínua básica

Uma atualização gradual básica é aplicada gradualmente a todas as instâncias em um MIG, até que todas tenham sido atualizadas na configuração pretendida mais recente. A atualização gradual ignora automaticamente as instâncias que já estão na configuração mais recente.

Você pode controlar vários aspectos de uma atualização gradual, como quantas instâncias podem ficar off-line para a atualização, quanto tempo esperar entre atualizações de instâncias, se o novo modelo afeta todas as instâncias ou apenas uma parte delas e assim por diante.

Veja a seguir algumas considerações durante uma atualização gradual:

• As atualizações são baseadas em intent. Quando você faz a solicitação de atualização inicial, a API Compute Engine retorna uma resposta bem-sucedida para confirmar que a solicitação é válida, mas isso não indica que a atualização foi bem-sucedida. Você precisa verificar o status do grupo para determinar se a atualização foi implantada.

• A API Instance Group Updater é uma API declarativa. Ela espera que uma solicitação especifique a configuração pós-atualização pretendida do grupo de instâncias gerenciadas, em vez de uma chamada de função explícita.

• As atualizações automáticas são compatíveis com até duas versões de modelo de instância no MIG. Isso significa que é possível especificar duas versões de modelo de instância diferentes para o grupo, o que é útil para executar atualizações canário.

Para iniciar uma atualização gradual básica com aplicação em todas as instâncias do grupo, siga as instruções abaixo.

Permissões exigidas para a tarefa

Para executar esta tarefa, é necessário ter as seguintes permissões:

• Para MIGs zonais, todas as permissões necessárias para chamar o método instanceGroupManagers.patch
• Para MIGs regionais, todas as permissões necessárias para chamar o método regionInstanceGroupManagers.patch

Console

1. No Console do Google Cloud, acesse a página Grupos de instâncias.

   Acesse grupo de instâncias

2. Selecione o MIG que você quer atualizar.

3. Clique em Atualizar VMs.

4. Em Novo modelo, clique na lista suspensa e selecione o novo modelo para atualizar. O tamanho de destino é definido automaticamente como 100%, indicando que todas as instâncias serão atualizadas.

5. Em Atualizar configuração, expanda o menu de seleção e selecione Automático como o Tipo de atualização. Mantenha os valores padrão das outras opções.

6. Clique em Atualizar VMs para iniciar a atualização.

gcloud

Use o comando rolling-action start-update.

gcloud compute instance-groups managed rolling-action start-update INSTANCE_GROUP_NAME \
    --version=template=INSTANCE_TEMPLATE_NAME
    [--zone=ZONE | --region=REGION]

Substitua:

• INSTANCE_GROUP_NAME: o nome do MIG.
• INSTANCE_TEMPLATE_NAME: o novo modelo de instância
• ZONE: para MIGs zonais, forneça a zona.
• REGION: para MIGs regionais, forneça a região

REST

Chame o método patch em um recurso MIG regional ou zonal.

Por exemplo, no caso de um MIG regional, a solicitação a seguir mostra a configuração mínima necessária para atualizar automaticamente 100% de instâncias para o novo modelo de instância.

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME

{
  "instanceTemplate": "global/instanceTemplates/NEW_TEMPLATE",
  "updatePolicy": {
    "type": "PROACTIVE"
   }
}

Depois de fazer uma solicitação, você pode monitorar a atualização para saber quando ela foi concluída.

Para configurações avançadas, inclua outras opções de atualização. Se você não especificar o contrário, as opções maxSurge e maxUnavailable usarão o padrão 1 multiplicado pelo número de zonas afetadas. Isso significa que apenas uma instância é colocada off-line em cada zona afetada e o MIG cria apenas uma instância adicional por zona durante a atualização.

Como configurar opções para a atualização

Para atualizações mais complexas, é possível configurar outras opções, conforme descrito nas seções a seguir.

Atualizar tipo

Os grupos de instâncias gerenciadas aceitam dois tipos de atualização:

• Atualizações automáticas ou proativas
• Atualizações seletivas ou oportunistas

Se você quiser aplicar as atualizações automaticamente, defina o tipo como proativo.

Como alternativa, se uma atualização automatizada é potencialmente muito disruptiva, é possível executar uma atualização oportunista. O MIG aplica uma atualização oportunista apenas quando você a inicia manualmente nas instâncias selecionadas ou quando novas instâncias são criadas. Novas instâncias podem ser criadas quando você ou outro serviço, como um autoescalador, redimensiona o MIG. O Compute Engine não inicia as solicitações ativamente para aplicar as atualizações.

Para mais informações sobre atualizações automatizadas versus seletivas, consulte Métodos para aplicar uma nova configuração a VMs atuais.

Máximo de sobretensão

Use a opção maxSurge para configurar quantas instâncias novas o MIG pode criar acima do targetSize durante uma atualização automatizada. Por exemplo, se você definir maxSurge como 5, o MIG usará o novo modelo de instância para criar até cinco novas instâncias acima do tamanho de destino. Se um valor maior de maxSurge for definido, a atualização será acelerada ao custo de mais instâncias, que serão cobradas de acordo com a tabela de preçosdo Compute Engine. Preços do

Especifique um número fixo ou, se o grupo tiver dez ou mais instâncias, uma porcentagem. Se você definir uma porcentagem, o Updater arredondará o número de instâncias para cima, se necessário.

Se você não definir o valor de maxSurge, o padrão será usado. Para MIGs zonais, o padrão para maxSurge é 1. Para MIGs regionais, o padrão é o número de zonas associadas ao grupo, por padrão 3.

maxSurge apenas funcionará se você tiver cota ou recursos suficientes para atender aos recursos extras.

Se a atualização não exigir a substituição de VMs, essa opção será ignorada. É possível forçar que as VMs sejam substituídas durante uma atualização definindo a opção de ação mínima.

Máximo indisponível

Use a opção maxUnavailable para configurar quantas instâncias não estão disponíveis a qualquer momento durante uma atualização automatizada. Por exemplo, se você definir maxUnavailable como 5, apenas cinco instâncias de cada vez serão colocadas off-line para atualização. Utilize essa opção para controlar o nível de interrupção da atualização para o serviço e a velocidade da implantação da atualização.

Esse número também inclui todas as instâncias que não estão disponíveis por outros motivos. Por exemplo, se o grupo estiver em processo de redimensionamento, as instâncias que ainda estiverem no meio da etapa de criação talvez não estejam disponíveis. Essas instâncias contam para o número maxUnavailable.

Especifique um número fixo ou, se o grupo tiver 10 ou mais instâncias, uma porcentagem. Se você definir uma porcentagem, o Updater arredondará o número de instâncias para baixo, se necessário.

Se você não quiser que nenhuma máquina fique disponível durante uma atualização, defina o valor maxUnavailable como 0 e o valor maxSurge como maior que 0. Com essas configurações, o Compute Engine removerá cada máquina antiga somente depois que a nova máquina substituta for criada e executada.

Se você não definir o valor de maxUnavailable, o padrão será usado. Para MIGs zonais, o padrão é 1. Para MIGs regionais, o padrão é o número de zonas associadas ao grupo, por padrão 3.

Observação: se você definir as propriedades maxSurge e maxUnavailable e ambas forem resolvidas como 0, o Updater definirá automaticamente maxUnavailable=1 para garantir que a atualização sempre possa prosseguir.

Tempo de espera mínimo

Observação: minReadySec está disponível somente na API Compute Engine Beta e pode ter o uso suspenso em uma versão futura.

Use a opção minReadySec para especificar quanto tempo aguardar antes de considerar uma instância nova ou reiniciada como atualizada. Use essa opção para controlar a taxa em que a atualização automatizada é implantada. O timer é iniciado quando ocorrem as duas condições a seguir:

• o status da instância é RUNNING;
• a verificação de integridade retorna HEALTHY, quando ativada.

Para que a verificação de integridade retorne o status "integra", o Updater aguarda as seguintes condições:

1. aguarda até o período especificado pelo valor de autohealingPolicies.initialDelaySec do MIG para que a verificação de integridade retorne como HEALTHY;
2. aguarda, na sequência, o período especificado por minReadySec.

Se a verificação de integridade não retornar HEALTHY no initialDelaySec, o Updater declarará a instância de VM como não íntegra e possivelmente interromperá a atualização. Enquanto a instância de VM aguarda a confirmação durante os períodos initialDelaySec e minReadySec, a currentAction da instância é VERIFYING. No entanto, o status da instância de VM subjacente permanece como RUNNING.

Se não houver verificações de integridade para o grupo, o timer será iniciado quando o status da instância for RUNNING.

O valor máximo do campo minReadySec é de 3.600 segundos (1 hora).

O diagrama a seguir mostra como o tamanho de destino, o máximo de sobretensão, o máximo de sobretensão e as opções de tempo de espera mínimo afetam as instâncias. Para mais informações sobre o tamanho de destino, consulte Atualizações Canary.

Ação mínima

Use a opção de ação mínima para minimizar o máximo de interrupções ou aplicar uma ação mais disruptiva do que o estritamente necessário. Por exemplo, o Compute Engine não precisa reiniciar uma VM para alterar os metadados. No entanto, se seu aplicativo ler metadados de instância somente quando uma VM for reiniciada, será possível definir a ação mínima como para coletar as alterações de metadados.

Se a atualização exigir uma ação mais disruptiva do que a definida por essa sinalização, o Compute Engine executará a ação necessária para executar a atualização. Por exemplo, se você especificar uma reinicialização como a ação mínima, o Updater tentará reiniciar as instâncias para aplicar a atualização. No entanto, se você estiver alterando o SO, o que não pode ser feito reiniciando a instância, o Updater substituirá as instâncias no grupo por novas instâncias de VM.

Para mais informações, incluindo opções válidas, consulte Como controlar o nível de interrupção durante uma atualização gradual.

Ação mais disruptiva disponível

Use a opção de ação mais disruptiva para evitar atualizações se ela exigir mais interrupção do que você consegue sustentar. Se não for possível concluir uma atualização devido a essa configuração, a atualização falhará, e suas VMs manterão a configuração anterior.

Para mais informações, consulte Como controlar o nível de interrupção durante uma atualização gradual.

Método de substituição

Por padrão, quando você atualiza um MIG proativamente, o grupo exclui as instâncias de VM e as troca por novas com novos nomes. Se você precisar preservar os nomes das instâncias de VM, use a opção replacementMethod.

Preservar nomes de instâncias existentes pode ser útil se você tiver aplicativos ou sistemas que dependem do uso de nomes de instância específicos. Por exemplo, alguns aplicativos, como o Memcached, dependem de nomes de instância porque não têm um serviço de descoberta; como resultado, sempre que um nome de instância é alterado, o aplicativo perde a conexão com essa VM específica.

Para preservar nomes de instâncias, defina o método de substituição como RECREATE em vez de SUBSTITUTE se você atualizar o MIG com a CLI gcloud ou a API Compute Engine. Como alternativa, se você atualizar o MIG no Console do Cloud, marque a caixa de seleção Manter nomes das instâncias ao substituir instâncias.

Os valores replacementMethod válidos são:

• SUBSTITUTE (padrão). Substitui as instâncias de VM mais rapidamente durante as atualizações porque novas VMs são criadas antes que as antigas sejam encerradas. No entanto, os nomes das instâncias não são preservados porque os nomes ainda estão sendo usados pelas instâncias antigas.

• RECREATE. Preserva os nomes de instâncias por meio de uma atualização. O Compute Engine libera o nome da instância quando a VM antiga é encerrada. Em seguida, o Compute Engine cria uma nova instância usando esse mesmo nome. Para usar este modo, defina maxSurge para 0.

Observação: se você definir o método de substituição como RECREATE, o nome da instância será preservado. No entanto, o ID da instância e o carimbo de data/hora da criação podem mudar. Para confirmar se a operação RECREATE criou uma nova instância quando o carimbo de data/hora de criação da instância não foi alterado, verifique o carimbo de data/hora de criação do disco de inicialização anexado a essa instância.

Para mais informações, consulte como preservar nomes de instâncias.

Outros exemplos de atualização

Veja a seguir alguns exemplos de linha de comando com opções de configuração comuns.

Executar uma atualização gradual de todas as instâncias de VM, mas criar até cinco novas instâncias de cada vez acima do tamanho de destino

gcloud compute instance-groups managed rolling-action start-update INSTANCE_GROUP_NAME \
    --version=template=NEW_TEMPLATE \
    --max-surge=5 \
    [--zone=ZONE | --region=REGION]

Executar uma atualização gradual com no máximo três máquinas indisponíveis e um tempo de espera mínimo de três minutos antes de marcar uma nova instância como disponível

gcloud beta compute instance-groups managed rolling-action start-update INSTANCE_GROUP_NAME \
    --version=template=NEW_TEMPLATE \
    --min-ready=3m \
    --max-unavailable=3 \
    [--zone=ZONE | --region=REGION]

Executar uma atualização gradual de todas as instâncias de VM, mas criar até 10% de novas instâncias de cada vez acima do tamanho de destino

Por exemplo, se você tiver 1.000 instâncias e executar o comando a seguir, o Updater criará até 100 instâncias antes de começar a remover aquelas que executam o modelo anterior.

gcloud compute instance-groups managed rolling-action start-update INSTANCE_GROUP_NAME \
    --version=template=NEW_TEMPLATE \
    --max-surge=10% \
    [--zone=ZONE | --region=REGION]

Atualizações Canary

Uma atualização canário é aplicada a um subconjunto de instâncias no grupo. Com uma atualização canário, é possível testar novos recursos ou upgrades em um subconjunto aleatório de instâncias, em vez de implantar uma atualização potencialmente disruptiva em todas as instâncias. Se uma atualização não está indo bem, você só precisa reverter o subconjunto de instâncias, minimizando a interrupção para os usuários.

Uma atualização canário é igual a uma atualização gradual padrão, exceto pelo número de instâncias que precisam ser atualizadas que é menor que o tamanho total do grupo. Assim como uma atualização gradual padrão, é possível configurar outras opções (em inglês) para controlar o nível de interrupção no serviço.

Como iniciar uma atualização canário

Para iniciar uma atualização canário, especifique até duas versões do modelo de instância, normalmente um novo modelo para canário e outro atual para o restante. Por exemplo, é possível especificar que 20% das instâncias sejam criadas com base em NEW_INSTANCE_TEMPLATE, enquanto o restante das instâncias continuará em execução no OLD_INSTANCE_TEMPLATE. Não é possível especificar mais de dois modelos de instância por vez. O NEW_INSTANCE_TEMPLATE pode ser um modelo de instância regional da mesma região do seu MIG ou um modelo de instância global.

Sempre especifique um tamanho de destino (targetSize) para a versão canary. Não será possível iniciar uma atualização canário se você omitir o tamanho de destino da versão canário. Por exemplo, se você especificou que 10% das instâncias devem ser usadas para atualização canário, os 90% restantes não são alterados e usam o modelo de instância atual.

Permissões exigidas para a tarefa

Para executar esta tarefa, é necessário ter as seguintes permissões:

• Para MIGs zonais, todas as permissões necessárias para chamar o método instanceGroupManagers.patch
• Para MIGs regionais, todas as permissões necessárias para chamar o método regionInstanceGroupManagers.patch

Console

1. No Console do Google Cloud, acesse a página Grupos de instâncias.

   Acesse grupo de instâncias

2. Selecione o grupo de instâncias gerenciadas que você quer atualizar.
3. Clique em Atualizar VMs.
4. Clique em Adicionar um segundo modelo e escolha o novo modelo de instância para o teste canário.
5. Em Tamanho do destino, insira a porcentagem ou o número fixo de instâncias que você quer usar para fazer o teste canário do novo modelo de instância.
6. Se você quiser, poderá configurar outras opções de atualização.
7. Clique em Atualizar VMs para iniciar a atualização.

gcloud

Use o comando rolling-action start-update. Forneça o modelo atual e o novo para expressar explicitamente quantas instâncias devem usar cada modelo:

gcloud compute instance-groups managed rolling-action start-update INSTANCE_GROUP_NAME \
    --version=template=CURRENT_INSTANCE_TEMPLATE_NAME \
    --canary-version=template=NEW_TEMPLATE,target-size=SIZE \
    [--zone=ZONE | --region=REGION]

Substitua:

• INSTANCE_GROUP_NAME: o nome do grupo de instâncias.
• CURRENT_INSTANCE_TEMPLATE_NAME: o modelo de instância que o grupo de instâncias está executando.
• NEW_TEMPLATE: o novo modelo em que você quer fazer a atualização canário;
• SIZE: o número ou a porcentagem de instâncias às quais você quer aplicar esta atualização. Aplique a propriedade target-size ao modelo --canary-version. Somente será possível definir uma porcentagem se o grupo tiver dez ou mais instâncias.
• ZONE: para MIGs zonais, forneça a zona.
• REGION: para MIGs regionais, forneça a região.

Por exemplo, o comando a seguir executa uma atualização canário que implanta example-template-B em 10% das instâncias no grupo:

gcloud compute instance-groups managed rolling-action start-update example-mig \
    --version=template=example-template-A \
    --canary-version=template=example-template-B,target-size=10%

REST

Chame o método patch em um recurso MIG regional ou zonal. No corpo da solicitação, inclua os modelos de instância que já existem e os novos que você quer fazer a atualização canário. Por exemplo:

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME

{
 "versions": [
  {
   "instanceTemplate": "global/instanceTemplates/NEW_TEMPLATE",
   "targetSize": {
    "[percent|fixed]": NUMBER|PERCENTAGE # Use `fixed` for a specific number of instances
   }
  },
  {
   "instanceTemplate": "global/instanceTemplates/CURRENT_INSTANCE_TEMPLATE_NAME"
  }
 ]
}

Substitua:

• NEW_TEMPLATE: o nome do novo modelo em que você quer fazer a atualização canário.
• NUMBER|PERCENTAGE: o número fixo ou a porcentagem de instâncias para fazer essa atualização canário. Somente será possível definir uma porcentagem se o grupo tiver dez ou mais instâncias. Caso contrário, forneça um número fixo.
• CURRENT_INSTANCE_TEMPLATE_NAME: o nome do modelo de instância atual que o grupo está executando.

Para mais opções, consulte Como configurar opções para a atualização.

Depois de fazer uma solicitação, você pode monitorar a atualização para saber quando ela foi concluída.

Como avançar uma atualização canário

Depois de executar uma atualização canário, decida se quer confirmar a atualização como 100% do MIG ou revertê-la.

Console

1. No Console do Google Cloud, acesse a página Grupos de instâncias.

   Acesse grupo de instâncias

2. Selecione o grupo de instâncias gerenciadas que você quer atualizar.
3. Clique em Atualizar VMs.
4. Em Novo modelo, atualize o tamanho de destino do modelo canário como 100% para implementar o modelo em todas as instâncias. Se preferir, substitua o modelo principal pelo modelo canário e remova o segundo campo.
5. Clique em Atualizar VMs para iniciar a atualização.

gcloud

Se você quer confirmar a atualização canário, avance-a emitindo outrocomandorolling-action start-update mas defina somente a sinalização version e omitir a sinalização --canary-version.

gcloud compute instance-groups managed rolling-action start-update INSTANCE_GROUP_NAME \
    --version=template=NEW_TEMPLATE \
    [--zone=ZONE | --region=REGION]

REST

Chame o método patch em um recurso MIG regional ou zonal. No corpo da solicitação, especifique o novo modelo de instância como version e omita o modelo anterior. Omita a especificação do tamanho de destino para lançar a atualização em 100% das instâncias. Por exemplo:

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME

{
"versions": [
   {
   "instanceTemplate": "global/instanceTemplates/NEW_TEMPLATE" # New instance template
   }
 ]
}

Como monitorar as atualizações

Uma atualização pode levar algum tempo para ser concluída para todas as instâncias afetadas após o início de uma nova configuração. É possível monitorar o progresso de uma atualização verificando o seguinte:

• Para verificar se todas as VMs atingiram a versão do modelo de destino, visualize o status do grupo.
• Para verificar se VMs específicas atingiram a versão do modelo de destino, consulte as ações atuais nas instâncias.
• Para MIGs com estado, consulte também Como verificar se as configurações por instância foram aplicadas.

Status do grupo

No nível do grupo, o Compute Engine preenche um campo somente leitura denominado status, que contém uma sinalização versionTarget.isReached e uma sinalização isStable. Use a CLI gcloud ou REST para acessar essas flags. Também é possível usar o Console do Cloud para ver o número atual e planejado das instâncias que estão sendo atualizadas.

Permissões exigidas para a tarefa

Para executar esta tarefa, é necessário ter as seguintes permissões:

• compute.instanceGroupManagers.get no MIG

Console

Para monitorar a atualização gradual de um grupo, acesse a página de detalhes do grupo.

1. No Console do Google Cloud, acesse a página Grupos de instâncias.

   Acesse grupo de instâncias

2. Selecione o grupo de instâncias gerenciadas que você quer monitorar. Na página de visão geral do grupo, aparece o modelo que cada instância usa.
3. Para ver os detalhes, clique na guia Detalhes.
4. Em Modelo de instância, é possível ver o número atual e de destino de instâncias para cada modelo, bem como os parâmetros de atualização.

gcloud

Use o comando describe.

gcloud compute instance-groups managed describe INSTANCE_GROUP_NAME \
    [--zone=ZONE | --region=REGION]

É possível também usar o comando gcloud compute instance-groups managed wait-until (em inglês) com a sinalização --version-target-reached para aguardar que status.versionTarget.isReached seja definido como true no grupo:

gcloud compute instance-groups managed wait-until INSTANCE_GROUP_NAME \
    --version-target-reached \
    [--zone=ZONE | --region=REGION]

REST

Chame o método get em um recurso MIG regional ou zonal.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME/get

Como verificar se um lançamento de atualização foi concluído

Verifique se o lançamento de uma atualização está completo verificando o valor do campo status.versionTarget.isReached do MIG:

• status.versionTarget.isReached definido como true indica que todas as instâncias de VM foram ou estão sendo criadas usando a versão de destino.

• status.versionTarget.isReached definido como false indica que pelo menos uma VM ainda não está usando a versão de destino. Ou, no caso de uma atualização canário, false indica que o número de VMs que usam uma versão de destino não corresponde ao tamanho de destino.

Observação: para confirmar se o lançamento da atualização foi concluído e se todas as instâncias de VM no grupo estão em execução e íntegras, verifique as sinalizações status.isStable e status.versionTarget.isReached.

Como verificar se o grupo de instâncias gerenciadas é estável

Verifique se todas as instâncias em um grupo de instâncias gerenciadas estão em execução e íntegras verificando o valor do campo status.isStable do grupo.

status.isStable definido como false indica que as alterações estão ativas, pendentes ou que o próprio MIG está sendo modificado.

status.isStable definido como true indica o seguinte:

• Nenhuma das instâncias no MIG está passando por qualquer tipo de alteração, e o currentAction de todas as instâncias é NONE.
• Nenhuma alteração pendente para instâncias no MIG.
• O MIG não está sendo modificado.

A estabilidade de um MIG depende de vários fatores porque ele pode ser modificado de várias maneiras. Por exemplo:

• Você faz uma solicitação para lançar um novo modelo de instância.
• Você faz uma solicitação para criar, excluir, redimensionar ou atualizar instâncias no MIG.
• Um escalonador automático solicita o redimensionamento do MIG.
• Um recurso de recuperação automática está substituindo uma ou mais instâncias não íntegras do MIG.
• Em um MIG regional, algumas das instâncias estão sendo redistribuídas.

Assim que todas as ações forem concluídas, status.isStable será definido como true novamente para esse MIG.

Ações atuais nas instâncias

Use a CLI do Google Cloud ou a REST para ver detalhes sobre as instâncias em um grupo gerenciado de instâncias. Isso inclui o status da instância e as ações atuais que o grupo está executando nas instâncias.

Permissões exigidas para a tarefa

Para executar esta tarefa, é necessário ter as seguintes permissões:

• compute.instanceGroupManagers.get no grupo
• compute.instanceGroupManagers.list no grupo

gcloud

Todas as instâncias gerenciadas

Para verificar o status e as ações atuais em todas as instâncias no grupo, use o comando list-instances.

gcloud compute instance-groups managed list-instances INSTANCE_GROUP_NAME \
    [--zone=ZONE | --region=REGION]

O comando retorna uma lista de instâncias no grupo, incluindo o status, as ações atuais e outros detalhes.

NAME               ZONE           STATUS   HEALTH_STATE  ACTION  INSTANCE_TEMPLATE  VERSION_NAME  LAST_ERROR
vm-instances-9pk4  us-central1-f                          CREATING  my-new-template
vm-instances-h2r1  us-central1-f  STOPPING                DELETING  my-old-template
vm-instances-j1h8  us-central1-f  RUNNING                 NONE      my-old-template
vm-instances-ngod  us-central1-f  RUNNING                 NONE      my-old-template

A coluna HEALTH_STATE aparece vazia, a menos que você tenha configurado a verificação de integridade.

Uma instância gerenciada específica

Para verificar o status e a ação atual de uma instância específica no grupo, use o comando describe-instance.

gcloud compute instance-groups managed describe-instance INSTANCE_GROUP_NAME \
    --instance INSTANCE_NAME \
    [--zone=ZONE | --region=REGION]

O comando retorna detalhes sobre a instância, incluindo o status da instância, a ação atual e, para MIGs com estado, o estado preservado:

currentAction: NONE
id: '6789072894767812345'
instance: https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/instances/example-mig-hz41
instanceStatus: RUNNING
name: example-mig-hz41
preservedStateFromConfig:
  metadata:
    example-key: example-value
preservedStateFromPolicy:
  disks:
    persistent-disk-0:
      autoDelete: NEVER
      mode: READ_WRITE
      source: https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/disks/example-mig-hz41
version:
  instanceTemplate: https://www.googleapis.com/compute/v1/projects/example-project/global/instanceTemplates/example-template

REST

Chame o método listManagedInstances em um recurso MIG regional ou zonal. Por exemplo, para ver detalhes sobre as instâncias em um recurso de MIG zonal, faça a seguinte solicitação:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/INSTANCE_GROUP_NAME/listManagedInstances

A chamada retorna uma lista de instâncias para o MIG, incluindo instanceStatus e currentAction de cada instância.

{
 "managedInstances": [
  {
   "instance": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-f/instances/vm-instances-prvp",
   "id": "5317605642920955957",
   "instanceStatus": "RUNNING",
   "instanceTemplate": "https://www.googleapis.com/compute/v1/projects/example-project/global/instanceTemplates/example-template",
   "currentAction": "REFRESHING"
  },
  {
   "instance": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-f/instances/vm-instances-pz5j",
   "currentAction": "DELETING"
  },
  {
   "instance": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-f/instances/vm-instances-w2t5",
   "id": "2800161036826218547",
   "instanceStatus": "RUNNING",
   "instanceTemplate": "https://www.googleapis.com/compute/v1/projects/example-project/global/instanceTemplates/example-template",
   "currentAction": "REFRESHING"
  }
 ]
}

Para ver uma lista de valores válidos do campo instanceStatus, consulte Ciclo de vida da instância da VM.

Se uma instância estiver passando por algum tipo de alteração, o grupo gerenciado de instâncias definirá o campo currentAction da instância como uma das ações a seguir para ajudar você a acompanhar o andamento da alteração. Caso contrário, o campo currentAction será definido como NONE.

Os valores possíveis de currentAction são:

• ABANDONING. A instância está sendo removida do MIG.
• CREATING: a instância está em processo de criação;
• CREATING_WITHOUT_RETRIES. A instância está sendo criada sem novas tentativas. Se a instância não for criada na primeira tentativa, o MIG não tentará substituí-la novamente.
• DELETING: a instância está em processo de exclusão;
• RECREATING: a instância está sendo substituída;
• REFRESHING: a instância está sendo removida e adicionada novamente à lista de pools de destino atuais (essa lista pode corresponder ou não aos pools de destino atuais);
• RESTARTING: a instância está em processo de reinicialização por meio dos métodos stop e start;
• RESUMING: A instância está em processo de ser retomada após ser suspensa.
• STARTING: A instância está em processo de inicialização após ser interrompida.
• STOPPING: a instância está sendo interrompida.
• SUSPENDING: a instância está sendo suspensa.
• VERIFYING: a instância foi criada e está em processo de verificação;
• NONE: nenhuma ação está sendo executada na instância.

Observação: o campo pendingActions se tornou obsoleto e precisa ser removido. Entre em contato com [e-mail] para deixar um feedback se sua carga de trabalho depende deste campo.

Como reverter uma atualização

Não há comando explícito para reverter uma atualização para uma versão anterior, mas se você decidir reverter uma atualização (uma atualização totalmente consolidada ou Canary), poderá fazer uma nova solicitação de atualização e passar o modelo de instância para o que você quer reverter.

gcloud

Por exemplo, o seguinte comando da CLI gcloud reverte uma atualização o mais rápido possível. Substitua OLD_INSTANCE_TEMPLATE pelo nome do modelo de instância ao qual você quer reverter.

gcloud compute instance-groups managed rolling-action start-update INSTANCE_GROUP_NAME \
    --version=template=OLD_INSTANCE_TEMPLATE_NAME \
    --max-unavailable=100% \
    [--zone=ZONE | --region=REGION]

REST

Chame o método patch em um recurso MIG regional ou zonal.

No corpo da solicitação, especifique o modelo de instância anterior como uma version:

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME

{
  "updatePolicy":
  {
    "maxUnavailable":
    {
      "percent": 100
    }
  },
  "versions": [
    {
      "instanceTemplate": "global/instanceTemplates/OLD_INSTANCE_TEMPLATE_NAME" # Old instance template
    }
  ]
}

Para um MIG regional com menos de 10 instâncias, use um valor fixo de maxUnavailable e defina o valor como o número de instâncias no grupo.

O Updater trata uma solicitação de reversão da mesma maneira que uma solicitação de atualização regular, para que você possa especificar outras opções de atualização.

Cuidado: para atualizações canário, recomendamos reverter totalmente as atualizações canário antes de tentar uma nova versão canário. Não há como escolher seletivamente quais instâncias são atualizadas com base no modelo de instância, e a realização de outra atualização canário sobre uma atualização existente pode causar consequências inesperadas. Recomendamos reverter totalmente uma atualização canário primeiro e reiniciar o processo de canário novamente desde o início.

Como parar uma atualização

Não há nenhum método ou comando explícito para interromper uma atualização. Altere uma atualização de proativa para oportunista e, se o grupo de não estiver sendo redimensionado por outros serviços, como o autoescalador, a alteração para oportunista interromperá a atualização de maneira efetiva.

Para alterar uma atualização de proativa para oportunista usando a CLI gcloud, execute o seguinte comando:

gcloud compute instance-groups managed rolling-action stop-proactive-update INSTANCE_GROUP_NAME \
    [--zone=ZONE | --region=REGION]

Para interromper a atualização completamente após convertê-la de proativa em oportunista, siga estas etapas:

1. Faça uma solicitação para determinar quantas instâncias foram atualizadas:

   gcloud compute instance-groups managed list-instances INSTANCE_GROUP_NAME \
      [--zone=ZONE | --region=REGION]

   A CLI gcloud retorna uma resposta que inclui uma lista de instâncias no grupo e os status atuais delas:

   NAME               ZONE           STATUS   HEALTH_STATE  ACTION    INSTANCE_TEMPLATE  VERSION_NAME  LAST_ERROR
   vm-instances-9pk4  us-central1-f  RUNNING  HEALTHY       NONE      example-new-template
   vm-instances-j1h8  us-central1-f  RUNNING  HEALTHY       NONE      example-old-template
   vm-instances-ngod  us-central1-f  STAGING  UNKNOWN       CREATING  example-new-template
   

   Neste exemplo, duas instâncias já foram atualizadas.

2. Em seguida, faça uma solicitação para executar uma nova atualização, mas transmita o número de instâncias que já foram atualizadas como o tamanho de destino:

   gcloud compute instance-groups managed rolling-action start-update INSTANCE_GROUP_NAME \
      --version template=OLD_INSTANCE_TEMPLATE_NAME \
      --canary-version template=NEW_INSTANCE_TEMPLATE_NAME,target-size=2 \
      [--zone=ZONE | --region=REGION]

   Para o Updater, esta atualização parece completa, por isso nenhuma outra instância é atualizada, interrompendo efetivamente a atualização.

Como controlar a velocidade de uma atualização gradual

Por padrão, quando você faz uma solicitação de atualização, o Updater realiza a atualização o mais rápido possível. Caso não tenha certeza se quer aplicar uma atualização integralmente ou se estiver apenas testando as alterações, controle a velocidade da atualização usando os métodos a seguir.

1. Inicie uma atualização canário em vez de uma atualização completa.
2. Defina um valor minReadySec alto. Isso faz com que o Updater aguarde esse número de segundos antes de considerar a atualização da instância concluída e avançar para a próxima.
3. Ative a verificação de integridade para fazer com que o Updater aguarde a inicialização do aplicativo e informe um sinal de integridade antes de considerar a atualização da instância concluída e avançar para a próxima.
4. Defina valores maxUnavailable e maxSurge baixos. Isso garante que somente um número mínimo de instâncias seja atualizado de cada vez.
5. Atualização seletiva de instâncias em um MIG em vez de usar uma atualização automatizada.

Também é possível usar uma combinação desses métodos para controlar a taxa de atualização.

Como controlar o nível de interrupção durante uma atualização gradual

Dependendo da natureza da atualização, ela pode interferir no estado do ciclo de vida de uma instância. Por exemplo, a alteração do disco de inicialização de uma instância requer a substituição da instância. Controle o nível de interrupção durante uma atualização seletiva definindo as seguintes opções:

• Ação mínima: use esta opção para minimizar ao máximo a interrupção ou aplicar uma ação mais disruptiva do que o necessário.

  • Para limitar o máximo de interrupções possível, defina a ação mínima como REFRESH. Se a atualização exigir uma ação mais disruptiva, o Compute Engine executará a ação necessária para executá-la.
  • Para aplicar uma ação mais disruptiva do que o estritamente necessário, defina a ação mínima como RESTART ou REPLACE. Por exemplo, o Compute Engine não precisa reiniciar uma VM para alterar os metadados. Mas se seu aplicativo ler metadados de instância somente quando uma VM for reiniciada, será possível definir a ação mínima como RESTART para coletar as alterações de metadados.

• Ação permitida mais disruptiva: use esta opção para impedir uma atualização se ela exigir mais interferência do que você consegue sustentar. Se a atualização exigir uma ação mais disruptiva do que a definida por essa sinalização, a solicitação de atualização falhará. Por exemplo, se você definir RESTART como a ação mais disruptiva permitida, haverá falha na tentativa de atualizar a imagem do disco de inicialização, já que essa atualização exige a substituição da instância, uma ação mais disruptiva do que a reinicialização.

Ambas as opções aceitam os seguintes valores:

Valor	Descrição	Que propriedades da instância podem ser atualizadas?
REFRESH	Não pare a instância.	Discos adicionais, metadados de instância, rótulos, tags
RESTART	Pare a instância e inicie-a novamente.	Discos extras, metadados de instância, rótulos, tipo de máquina
REPLACE	(padrão). Substitua a instância de acordo com a opção do método de substituição.	Todas as propriedades da instância armazenadas no modelo da instância ou na configuração por instância

A ação mais disruptiva permitida não pode ser menos disruptiva que a ação mínima.

Quando você lança atualizações automaticamente, os seguintes padrões se aplicam:

• A ação mínima padrão é REPLACE. Se você quiser evitar interrupções não intencionais, defina a ação mínima para ser menos disruptiva.
• A REPLACEmost-disruptive-allowed-action padrão é Se não for possível tolerar essa interrupção, defina a ação mais disruptiva permitida para ser menos disruptiva.

É possível alterar o comportamento padrão usando a API do Compute Engine para definir os campos updatePolicy.minimalAction e updatePolicy.mostDisruptiveAllowedAction em seu recurso MIG, por exemplo, chamando o método regionInstanceGroupManagers.patch de dados. Como alternativa, é possível selecionar as Ações com permissão para atualizar VMs específicas ao atualizar seu MIG no Console do Cloud. Para visualizar as configurações atuais, consulte Como receber as propriedades de um MIG.

A atualização falhará se exigir uma ação mais disruptiva do que o permitido. Caso isso aconteça, tente a atualização novamente com uma ação mais disruptiva permitida ou atualize seletivamente a instância. O Compute Engine executa a validação de melhor esforço para ver se as instâncias podem ser atualizadas com o limite de interrupção especificado. No entanto, devido a alterações simultâneas no sistema, a situação pode mudar após o início da atualização. Se uma operação em uma instância específica falhar, liste erros de instância para ver o erro.

Como realizar uma substituição ou reinicialização gradual

Uma reinicialização gradual interrompe e reinicia todas as instâncias, enquanto uma substituição gradual substitui as instâncias de acordo com a opção do método de substituição. Uma reinicialização ou substituição gradual não altera mais nada no grupo, incluindo o modelo da instância.

Há vários motivos para realizar uma reinicialização gradual ou uma substituição gradual. Por exemplo, convém reiniciar ou substituir suas instâncias de VM de vez em quando por um dos seguintes motivos:

• limpar vazamentos de memória;
• reiniciar seu aplicativo para que ele possa ser executado a partir de uma máquina renovada;
• aplicar uma substituição periódica como prática recomendada para testar as VMs;
• atualizar a imagem do sistema operacional da VM ou executar novamente os scripts de inicialização para atualizar o software.

Use o console do Google Cloud, a CLI do Google Cloud ou o REST para executar uma reinicialização ou substituição.

Console

1. No Console do Google Cloud, acesse a página Grupos de instâncias.

   Acesse grupo de instâncias

2. Selecione o grupo de instâncias gerenciadas que tem as VMs que você quer reiniciar ou substituir.
3. Clique em Reiniciar/substituir VMs.
4. Em Operação, selecione Reiniciar ou Substituir.
   • Se você selecionar Reiniciar, alterne os parâmetros a seguir:
     • Máximo de instâncias indisponíveis
     • Tempo de espera mínimo
   • Se você selecionar Substituir, faça o seguinte:
     1. Escolha se você quer manter os nomes das instâncias ao substituir instâncias.
     2. Alterne os seguintes parâmetros:
        • Instâncias extras temporárias
        • Máximo de instâncias indisponíveis
        • Tempo de espera mínimo
5. Para iniciar a operação, clique em Reiniciar VMs ou Substituir VMs.

gcloud

Use o comando restart ou comando replace.

O seguinte comando substitui todas as instâncias no MIG, uma por vez:

gcloud compute instance-groups managed rolling-action replace INSTANCE_GROUP_NAME

O comando a seguir reinicia cada instância, uma de cada vez:

gcloud compute instance-groups managed rolling-action restart INSTANCE_GROUP_NAME

É possível personalizar ainda mais cada um desses comandos com as mesmas opções disponíveis para as atualizações. Por exemplo, maxSurge e maxUnavailable.

REST

Chame o método patch em um recurso MIG regional ou zonal.

No campo updatePolicy.minimalAction, especifique RESTART ou REPLACE. No campo versions.instanceTemplate, especifique o modelo atual.

Para acionar a ação, você também precisa atualizar o campo versions.name, por exemplo, anexando-o com um carimbo de data/hora. Mais tarde, é possível listar as VMs do MIG e inspecionar o campo versions.name de cada VM para determinar quais VMs foram substituídas ou reiniciadas.

Por exemplo, para um MIG zonal, a solicitação a seguir mostra a configuração mínima necessária para reiniciar automaticamente todas as instâncias.

PATCH https://compute.googleapis.com/compute/v1/projects/example-project/zones/ZONE/instanceGroupManagers/INSTANCE_GROUP_NAME

{
 "updatePolicy": {
  "minimalAction": "RESTART",
  "type": "PROACTIVE"
 },
 "versions": [
  {
   "instanceTemplate": "global/instanceTemplates/CURRENT_INSTANCE_TEMPLATE_NAME",
   "name": "v2-1705499403"
  }
 ]
}

Outros exemplos de substituição e reinicialização

Executar uma reinicialização gradual de todas as VMs, duas de cada vez

No comando a seguir, todas as VMs no grupo são reiniciadas, duas por vez. Observe que nenhum modelo de instância novo é especificado.

gcloud compute instance-groups managed rolling-action restart INSTANCE_GROUP_NAME \
    --max-unavailable=2 \
    [--zone=ZONE | --region=REGION]

Realizar uma reinicialização gradual de todas as VMs o mais rápido possível

gcloud compute instance-groups managed rolling-action restart INSTANCE_GROUP_NAME \
    --max-unavailable=100% \
    [--zone=ZONE | --region=REGION]

Executar uma substituição gradual de todas as VMs o mais rápido possível

gcloud compute instance-groups managed rolling-action replace INSTANCE_GROUP_NAME  \
    --max-unavailable=100% \
    [--zone=ZONE | --region=REGION]

Como preservar nomes de instância

Se for necessário manter os nomes das instâncias de VM em uma atualização, defina replacementMethod para RECREATE. Você também precisa definir maxUnavailable para ser maior que 0 e maxSurge como 0. Recriar instâncias em vez de substituí-las faz com que a atualização leve mais tempo para ser concluída, mas as instâncias atualizadas mantêm seus nomes.

Se você não especificar um método de substituição, o valor updatePolicy.replacementMethod atual do MIG será usado. Se ele não estiver definido, o valor padrão (substitute) será usado, substituindo as instâncias de VM por novas instâncias com nomes gerados aleatoriamente.

gcloud

Ao emitir um comando rolling-action, inclua a sinalização --replacement-method=recreate.

gcloud compute instance-groups managed rolling-action start-update INSTANCE_GROUP_NAME \
    --replacement-method=recreate \
    --version=template=NEW_TEMPLATE \
    --max-unavailable=5 \
    [--zone=ZONE | --region=REGION]

REST

Chame o método patch em um recurso MIG regional ou zonal. No corpo da solicitação, inclua o campo updatePolicy.replacementMethod:

PATCH /compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME
{
    "updatePolicy": {
        "type": "PROACTIVE",
        "maxUnavailable": { "fixed": 5 },
        "replacementMethod": "RECREATE"
    },
    "versions": [ {
        "instanceTemplate": "global/instanceTemplates/NEW_TEMPLATE"
    } ]
}

Depois de fazer uma solicitação, você pode monitorar a atualização para saber quando ela foi concluída.

Como atualizar um grupo regional de instâncias gerenciadas

Um MIG regional contém instâncias de VM espalhadas por várias zonas em uma região, em oposição a um MIG zonal, que contém apenas instâncias em uma zona. Os MIGs regionais permitem distribuir as instâncias por mais de uma zona para melhorar a disponibilidade do aplicativo e oferecer suporte a casos extremos em que uma zona falha ou um grupo inteiro de instâncias para de responder.

Executar uma atualização em um MIG regional é igual a uma atualização em um MIG zonal, com algumas exceções descritas abaixo. Quando você inicia uma atualização em um MIG regional, o Updater sempre atualiza as instâncias de modo proporcional e uniforme em cada zona. Não é possível escolher as instâncias em que as zonas são atualizadas primeiro nem atualizar as instâncias em apenas uma zona.

Diferenças entre a atualização de MIGs regionais e zonais

MIGs regionais têm os seguintes valores de atualização padrão:

• maxUnavailable=NUMBER_OF_ZONES
• maxSurge=NUMBER_OF_ZONES

NUMBER_OF_ZONES é o número de zonas associadas ao MIG regional. Por padrão, o número de zonas de um MIG regional é 3. Mas é possível selecionar um número diferente.

Se você usa números fixos ao especificar uma atualização, eles precisam ser 0 ou iguais ou maiores que o número de zonas associadas ao MIG regional. Por exemplo, se o grupo for distribuído em três zonas, não é possível definir maxSurge como 1 ou como 2, porque o Updater precisa criar uma instância extra em cada uma delas das três zonas.

Como usar um número fixo ou uma porcentagem nas solicitações de atualização

Se você especifica um número fixo em suas solicitações de atualização, esse número é dividido pelo número de zonas no MIG regional e distribuído uniformemente. Por exemplo, se você especificar maxSurge=10, o Updater dividirá dez pelo número de zonas na região e criará as instâncias com base nesse número. Se o número de instâncias não for dividido uniformemente entre as zonas, o Updater adicionará as instâncias restantes a uma zona aleatória. Portanto, para dez instâncias em três zonas, duas zonas recebem três instâncias e uma recebe quatro instâncias. A mesma lógica é aplicada aos parâmetros maxUnavailable e targetSize para atualizações canary.

Só será possível especificar uma porcentagem se o MIG contiver 10 ou mais instâncias de VM. As porcentagens são processadas de maneira um pouco diferente dependendo da situação:

• Se você especificar uma porcentagem de instâncias de VM em uma atualização canário, o Updater tentará distribuí-las uniformemente entre as zonas. O restante será arredondado para cima ou para baixo em cada zona, mas a diferença total não será mais do que uma instância de VM por grupo. Por exemplo, para um MIG com 10 instâncias e uma porcentagem de tamanho de destino de 25%, a atualização é implementada em duas a três instâncias de VM.

• Se você especificar uma porcentagem para as opções de atualização, como maxSurge e maxUnavailable, as porcentagens serão arredondadas de forma independente por zona.

A seguir

• Saiba mais sobre Como visualizar informações sobre MIGs e instâncias gerenciadas.
• Veja Como criar modelos de instâncias.
• Saiba como usar famílias de imagens e uma substituição gradual para atualizar a imagem do SO em todas as VMs em um MIG.