Como atualizar grupos de instâncias gerenciadas

Nesta página, descrevemos como fazer atualizações nos grupos de instâncias gerenciadas. Para saber mais sobre os grupos de instâncias gerenciadas, leia a documentação sobre Grupos de instâncias.

Um grupo de instâncias gerenciadas contém uma ou mais instâncias da máquina virtual que são controladas com o uso de um modelo de instância. Para atualizar instâncias em um grupo de instâncias gerenciadas, você pode fazer solicitações de atualização para o grupo como um todo usando o recurso Managed Instance Group Updater.

O Managed Instance Group Updater permite que você implante facilmente novas versões do software nas instâncias nos seus grupos de instâncias gerenciadas, enquanto controla a velocidade de implantação, o nível de interrupção do seu serviço e o escopo da atualização. O Updater oferece duas vantagens principais:

  • O lançamento de uma atualização acontece automaticamente de acordo com suas especificações, sem a necessidade de entrada adicional do usuário após a solicitação inicial.
  • É possível executar implementações parciais que permitem testes canário.

Ao permitir que o novo software seja implantado dentro de um grupo de instâncias gerenciadas existente, não é necessário reconfigurar o grupo de instâncias ou reconectar o balanceamento de carga, o escalonamento automático ou a autocorreção a cada vez que a nova versão do software é lançada. Sem o Updater, as novas versões de software precisam ser implantadas com a criação de um novo grupo de instâncias gerenciadas com uma nova versão de software, exigindo configuração adicional a cada vez, ou por meio de uma recriação manual, iniciada pelo usuário, instância por instância. As duas abordagens requerem etapas manuais significativas ao longo do processo.

Antes de começar

Como iniciar uma atualização contínua básica

Uma atualização contínua é aplicada gradualmente a todas as instâncias de um grupo de instâncias até que todas tenham sido atualizadas. Você pode controlar vários aspectos de uma atualização contínua, como quantas instâncias podem ficar off-line para a atualização, quanto tempo esperar entre atualizações de instâncias, se a atualização afeta todas as instâncias ou apenas uma parte delas e assim por diante.

Aqui estão algumas observações para ter em mente durante uma atualização contínua:

  • As atualizações são baseadas em intenções. Quando você faz a solicitação de atualização inicial, a API retorna uma resposta bem-sucedida para confirmar se a solicitação foi válida. No entanto, isso não indica que a atualização foi concluída. Você precisa verificar o status do grupo de instâncias gerenciadas para determinar se a atualização foi implantada.

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

  • O recurso Updater é compatível com até duas versões de modelo de instância no grupo de instâncias gerenciadas. Isso significa que é possível especificar duas versões de modelo de instância diferentes para o grupo de instâncias gerenciadas, o que é útil para executar atualizações canário.

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

Console

  1. Acesse a página "Grupos de instâncias" no Console do GCP.

    Acessar a página "Grupos de instâncias"

  2. Selecione o grupo de instâncias a ser atualizado.
  3. Na parte superior da página, clique em Atualização gradual.
  4. Em Modelo, abra o menu suspenso e selecione o novo modelo de atualização.
  5. Para o tamanho de destino, insira 100% para atualizar todas as instâncias.
  6. Opcionalmente, é possível alternar as opções de configuração, como se a atualização é proativa (o grupo substitui instâncias ativamente) ou oportunista (o grupo não substitui as instâncias ativamente, mas aplica a atualização quando elas são substituídas por outros meios). Também é possível fornecer as opções máximo de sobretensão, máximo de opções indisponíveis e tempo de espera mínimo.
  7. Clique em Atualizar para iniciar a atualização.

gcloud

Usando a ferramenta gcloud, execute o comando rolling-action start-update:

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

em que:

  • [INSTANCE_GROUP] é o nome do grupo de instâncias a ser atualizado.
  • [INSTANCE_TEMPLATE] é o novo modelo de instância para atualizar o grupo de instâncias;
  • é necessário fornecer uma [ZONE] ou [REGION] para esse grupo de instâncias. Se o grupo de instâncias for do tipo zonal, forneça a zona. Se for regional, forneça a região.

API

Na API, faça uma solicitação PATCH para o seguinte URL:

https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[MANAGED_INSTANCE_GROUP_NAME]

Se o grupo de instâncias for um grupo regional de instâncias gerenciadas, substitua zones/[ZONE] por regions/[REGION].

A payload da solicitação contém:

Veja a seguir a configuração mínima necessária para iniciar uma atualização na API. Se você não especificar o contrário, as propriedades maxSurge e maxUnavailable serão definidas como 1, o que significa que o Updater deixará apenas uma instância indisponível a qualquer momento e só criará uma instância adicional acima do tamanho de destino do grupo de instâncias durante a atualização. A solicitação atualizará 100% das instâncias para o novo modelo de instância.

Por exemplo:

{
  "instanceTemplate": "global/instanceTemplates/example-template",
  "updatePolicy": {
    "type": "proactive"
   }
 }

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

Configuração de opções para a atualização

No caso de atualizações mais complexas, é possível configurar mais opções para uma solicitação de atualização específica. Essas opções estão descritas abaixo.

Máximo de sobretensão

Defina a propriedade maxSurge para permitir que o Updater crie temporariamente novas instâncias acima do targetSize durante a atualização. Por exemplo, se você definir maxSurge como 5, o grupo de instâncias gerenciadas criará até cinco novas instâncias acima do tamanho de destino com o novo modelo de instância. A definição de um valor maxSurge maior acelera a atualização e tem o custo de instâncias extras, que são faturadas de acordo com a tabela de preços do Compute Engine. Se você não definir o valor maxSurge, o valor padrão de uma instância de máximo de sobretensão é usado.

Essa opção é reconhecida somente quando configurada com a ação mínima REPLACE, mas não é compatível com a configuração de ação RESTART. Você pode especificar um número fixo, ou especificar uma porcentagem se o grupo de instâncias gerenciadas tiver dez instâncias ou mais. Se você definir uma porcentagem, o Updater arredondará para cima o número de instâncias, se necessário.

maxSurge só funcionará se você tiver cotas ou recursos suficientes para comportar os recursos adicionais.

Máximo indisponível

Defina a configuração maxUnavailable de modo que somente um certo número de instâncias fique indisponível a qualquer momento durante a atualização. Por exemplo, se definir maxUnavailable como 5, apenas cinco instâncias ficarão off-line para atualização de cada vez. Utilize esse parâmetro para controlar o quanto a atualização é disruptiva para o serviço e controlar a taxa na qual a atualização é implantada.

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 de instâncias estiver em processo de redimensionamento, as instâncias que ainda estão na etapa de criação talvez não estejam disponíveis. Elas são computadas no número maxUnavailable. Você pode especificar um número fixo, ou especificar uma porcentagem se o grupo de instâncias gerenciadas tiver dez instâncias ou mais. Se você definir uma porcentagem, o Updater arredondará para baixo o número de instâncias se necessário.

O valor padrão de maxUnavailable em um grupo de instâncias gerenciadas por zona é 1. Em um grupo de instâncias gerenciadas por região, o padrão é [NUMBER_OF_ZONES]. [NUMBER_OF_ZONES] é o número de zonas selecionadas. Por padrão, 3.

Tempo de espera mínimo

Defina minReadySeconds para especificar a quantidade de tempo a aguardar antes de considerar uma instância recém-criada ou reiniciada como atualizada. Use esse recurso para controlar a taxa em que a atualização é implantada. O timer é iniciado quando as duas condições a seguir são satisfeitas:

Para que a verificação de integridade retorne o status "healthy", o Updater:

  1. aguardará o período especificado por autohealingPolicies.initialDelaySec para que a verificação de integridade retorne HEALTHY;
  2. aguardará o período especificado por minReadySeconds.

Se a verificação de integridade não retornar HEALTHY dentro de 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 estiver esperando a verificação durante os períodos initialDelaySec e minReadySeconds, ela ficará no estado verifying pelo grupo de instâncias gerenciadas. No entanto, o status da instância de VM subjacente permanecerá como RUNNING.

Se não houver verificações de integridade para o grupo de instâncias, o timer será iniciado quando o status da instância for RUNNING. O valor máximo para a propriedade minReadySeconds é 3.600 segundos (1 hora).

Ação mínima

Defina a propriedade que controla a ação mínima executada pelo Updater para atualizar as instâncias no grupo. Por exemplo, se você definir REPLACE como a ação mínima, todas as instâncias afetadas serão excluídas e substituídas por uma nova instância, seja ou não necessário.

A definição de uma ação mínima garante que o Updater executará pelo menos essa ação. No entanto, se o Updater determinar que a ação mínima especificada não é suficiente para realizar a atualização, ele poderá executar uma ação mais disruptiva. Por exemplo, se você definir RESTART como a ação mínima, o Updater tentará reiniciar instâncias para aplicar a atualização. No entanto, se a atualização requer uma ação mais disruptiva, o Updater a executará. Por exemplo, não é possível alterar o sistema operacional de uma instância reiniciando-a. Portanto, o Updater substituirá as instâncias no grupo de instâncias por novas instâncias de VM.

As ações aplicáveis são REPLACE ou RESTART:

  • RESTART: reinicia a instância, executando uma solicitação stop e start. A solicitação de atualização será forçada a executar REPLACE se ela exigir que a instância seja substituída para aderir às alterações. Por exemplo, alterar a imagem pode exigir que a instância seja excluída e substituída.

  • REPLACE: exclui a instância atual e cria uma nova com base no modelo de destino. O Updater cria uma nova instância com todas as novas propriedades, como novos endereços IP internos e externos.

O diagrama a seguir visualiza como essas opções afetam as instâncias.

Diagrama explicando como as diferentes opções do Updater afetam a solicitação

Exemplos de atualização adicionais

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

Executar uma atualização contínua de todas as instâncias de máquina virtual, mas criar até cinco novas instâncias acima do tamanho de destino de cada vez

gcloud beta 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 contínua 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]]

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

Executar uma atualização contínua de todas as instâncias da máquina virtual, mas criar até 10% de novas instâncias acima do tamanho de destino de cada vez

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

Como iniciar uma atualização canário

O recurso Instance Group Updater permite a realização de atualizações canário, para que você possa testar as atualizações em um subconjunto aleatório de instâncias antes de se comprometer totalmente com a atualização.

Uma atualização canário é aplicada a um número parcial de instâncias no grupo. As atualizações canário permitem testar novos recursos ou atualizações em um subconjunto 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 um pequeno número de instâncias, minimizando a interrupção para os usuários. Do ponto de vista do servidor, uma atualização canário é idêntica a uma atualização contínua padrão, exceto pelo fato de o número de instâncias que devem ser atualizadas ser menor que o tamanho total do grupo de instâncias. Como uma atualização contínua padrão, uma atualização canário é perigosa para as instâncias afetadas. Ou seja, as instâncias afetadas são excluídas e substituídas por novas instâncias de VM durante a atualização.

Para iniciar uma atualização canário, faça o seguinte:

  • Especifique até duas versões do modelo de instância, normalmente um novo modelo para canário e outro atual para o restante das instâncias. Por exemplo, é possível especificar que 20% das instâncias sejam criadas com base em new-instance-template, enquanto o restante delas continuará a ser executada em old-instance-template. Não é possível especificar mais de dois modelos de instância de cada vez.

  • Sempre especifique um tamanho de destino (targetSize) para a versão canário. Não é 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 precisam ser usadas para o teste canário, os 90% restantes permanecerão intactos e usarão o modelo atual.

Console

  1. Acesse a página "Grupos de instâncias" no Console do GCP.

    Acessar a página "Grupos de instâncias"

  2. Selecione o grupo de instâncias a ser atualizado.
  3. Na parte superior da página, clique em Atualização contínua.
  4. Clique em Adicionar 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. Opcionalmente, é possível alternar as opções de configuração, como se a atualização é proativa (o grupo exclui e substitui instâncias ativamente) ou oportunista (o grupo não substitui as instâncias ativamente, mas aplica a atualização quando elas são criadas por outros meios). Também é possível fornecer as opções máximo de sobretensão, máximo de opções indisponíveis e tempo de espera mínimo.
  7. Clique em Atualizar para iniciar a atualização.

gcloud

Usando a ferramenta de linha de comando gcloud, forneça o modelo atual e o modelo novo para expressar explicitamente quantas instâncias cada modelo deve usar:

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

em que:

  • [CURRENT_TEMPLATE] é o modelo atual que o grupo de instâncias está executando;
  • [NEW_TEMPLATE] é o novo modelo no qual você quer fazer a atualização canário;
  • [SIZE] é o número ou a porcentagem de instâncias em que você quer aplicar essa atualização. Aplique a propriedade target-size ao modelo --canary-version. Só será possível definir uma porcentagem se o grupo tiver 10 instâncias ou mais;
  • é necessário fornecer uma [ZONE] ou [REGION] para esse grupo de instâncias. Se o grupo de instâncias for do tipo zonal, forneça a zona. Se for regional, forneça a região.

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

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

API

Na API, faça uma solicitação PATCH para o seguinte URI:

https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP_NAME]

A payload da solicitação deve conter o modelo de instância atual e o novo modelo de instância no qual você quer fazer a atualização canário. Por exemplo:

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

em que:

  • [NEW_TEMPLATE] é o nome do novo modelo no qual você quer fazer a atualização canário;
  • [NUMBER|PERCENTAGE] é o número fixo ou a porcentagem de instâncias para fazer o canário nessa atualização. Só será possível definir uma porcentagem se o grupo tiver 10 instâncias ou mais. Caso contrário, forneça um número fixo;
  • [CURRENT_TEMPLATE] é o nome do modelo atual que o grupo de instâncias está executando.

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

Depois de executar uma atualização canário, é possível decidir se você quer confirmar a atualização para 100% do grupo de instâncias ou revertê-la.

Console

  1. Acesse a página "Grupos de instâncias" no Console do GCP.

    Acessar a página "Grupos de instâncias"

  2. Selecione o grupo de instâncias a ser atualizado.
  3. Na parte superior da página, clique em Atualização gradual.
  4. Em 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 canário e defina o tamanho de destino como 100%. Em seguida, remova completamente o segundo campo de modelo.
  5. Clique em Atualizar para iniciar a atualização.

gcloud

Caso queira fazer o commit da atualização canário, implante-a fazendo a mesma solicitação de atualização, mas definindo apenas version e omitindo --canary-version. Com a ferramenta de linha de comando gcloud:

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

API

Na API, faça uma solicitação PATCH para o seguinte URI:

https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP_NAME]

No corpo de solicitação, especifique o novo modelo de instância como uma version e omita o modelo de instância antigo do corpo de solicitação. Omita a especificação do tamanho de destino para implantar a atualização em 100% das instâncias. Por exemplo, o corpo de solicitação ficaria assim:

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

Substitua [NEW_TEMPLATE] pelo nome do novo modelo de instância que você quer implantar.

Como iniciar uma atualização oportunista ou proativa

Por padrão, as atualizações feitas usando a ferramenta de linha de comando gcloud são proativas e as atualizações iniciadas na API são oportunistas.

Para as atualizações proativas, o Compute Engine programa ativamente ações para aplicar as atualizações solicitadas às instâncias, conforme necessário. Em muitos casos, isso geralmente significa excluir e recriar instâncias proativamente.

Como alternativa, você pode optar por realizar uma atualização oportunista, se uma atualização proativa for potencialmente muito disruptiva. Uma atualização oportunista é aplicada somente quando novas instâncias são criadas pelo grupo de instâncias gerenciadas. Isso normalmente acontece quando o grupo de instâncias gerenciadas é redimensionado por outro serviço, como um autoescalador, ou manualmente por um usuário. O Compute Engine não inicia ativamente solicitações para aplicar atualizações.

Em certos cenários, uma atualização oportunista é útil, porque instabilidade no sistema é algo que se deve evitar. Por exemplo, se você tiver uma atualização não crítica que pode ser aplicada conforme necessário e sem urgência, e tiver um grupo de instâncias gerenciadas cujo tamanho está sendo ativamente autoajustado, realize uma atualização oportunista para que o Compute Engine não desmonte ativamente as instâncias existentes para aplicar a atualização.

Para escolher se uma atualização é oportunista ou proativa, defina a propriedade como OPPORTUNISTIC ou PROACTIVE usando a ferramenta de linha de comando gcloud ou a API.

Console

  1. Acesse a página "Grupos de instâncias" no Console do GCP.

    Acessar a página "Grupos de instâncias"

  2. Selecione o grupo de instâncias a ser atualizado.
  3. Na parte superior da página, clique em Atualização gradual.
  4. Em Modelo, escolha um modelo para atualizar o grupo de instâncias e selecione um tamanho de destino para o modelo.
  5. Em Modo de atualização, escolha entre uma atualização oportunista ou proativa.
  6. Clique em Atualizar para iniciar a atualização.

gcloud

Com a ferramenta de linha de comando gcloud:

gcloud beta compute instance-groups managed rolling-action start-update [INSTANCE_GROUP_NAME] \
    --version template=[INSTANCE_TEMPLATE] \
    --type [opportunistic|proactive] [--zone [ZONE] | --region [REGION]]

API

Na payload da solicitação para iniciar uma atualização, inclua a propriedade type em updatePolicy:

{
"updatePolicy": {
  "type": "PROACTIVE" # Performs a proactive update
},
"versions": [{
  "instanceTemplate": "global/instanceTemplates/[NEW_TEMPLATE]",
  }]
}

em que [NEW_TEMPLATE] é o nome do novo modelo no qual você quer fazer a atualização canário. Caso queira uma atualização oportunista, substitua PROACTIVE por OPPORTUNISTIC.

Como realizar uma substituição ou reinicialização contínua

Como alternativa, você pode usar os comandos restart ou replace para executar uma reinicialização ou uma substituição contínua de instâncias de VM no grupo de instâncias gerenciadas. Da mesma forma que o comando start-update, especifique qualquer uma das opções de configuração para uma reinicialização ou substituição. Uma reinicialização ou substituição contínua não altera nada do grupo de instâncias, incluindo o modelo de instância. Ela simplesmente atualiza as instâncias no grupo usando o método escolhido.

Há vários motivos para realizar uma substituição contínua ou uma reinicialização contínua. Por exemplo, pode ser conveniente atualizar suas instâncias de VM de vez em quando para:

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

Para fazer uma substituição em que todas as instâncias são excluídas e substituídas por novas instâncias:

Console

  1. Acesse a página "Grupos de instâncias" no Console do GCP.

    Acessar a página "Grupos de instâncias"

  2. Selecione o grupo de instâncias a ser atualizado.
  3. Na parte superior da página, clique em Reinicialização/substituição contínua.
  4. Escolha se instâncias serão reiniciadas ou substituídas. A reinicialização executa os métodos stop e start nas instâncias, enquanto a substituição exclui e cria instâncias ativamente.
  5. Também é possível alternar as opções de configuração como máximo de sobretensão, máximo de opções indisponíveis e tempo de espera mínimo.
  6. Clique no botão Reiniciar ou Substituir para iniciar a atualização.

gcloud

gcloud beta compute instance-groups managed rolling-action replace [INSTANCE_GROUP]

Esse comando substitui todas as instâncias nos grupos de instâncias gerenciadas, uma por vez. Se uma substituição for muito disruptiva, você pode especificar uma reinicialização contínua, que reinicia todas as instâncias sem excluir nenhuma delas.

gcloud beta compute instance-groups managed rolling-action restart [INSTANCE_GROUP]

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

API

Na API, faça uma solicitação PATCH para o grupo e defina uma updatePolicy proativa com minimalAction definido como RESTART ou REPLACE de acordo com a opção de fazer uma substituição contínua, em que cada instância é excluída e substituída por uma nova instância, ou uma reinicialização contínua, em que cada instância é interrompida e reiniciada. Tanto no caso de RESTART quanto de REPLACE, sempre é necessário fornecer um versions.instanceTemplate e uma propriedade versions.name (por exemplo, v2) para acionar a ação.

Uma substituição contínua tem a seguinte aparência:

PATCH https://www.googleapis.com/compute/beta/projects/myproject/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP_NAME]

{
 "updatePolicy": {
  "minimalAction": "REPLACE",
  "type": "PROACTIVE"
 },
 "versions": [
  {
   "instanceTemplate": "global/instanceTemplates/example-template",
   "name": "v2"
  }
 ]
}

Para uma reinicialização contínua:

PATCH https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP_NAME]

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

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

Realizar uma reinicialização contínua de todas as máquinas virtuais, duas de cada vez

Esse comando reinicia todas as máquinas virtuais no grupo de instâncias, duas de cada vez. Observe que nenhum modelo de instância novo é especificado.

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

Reinicialização contínua de todas as VMs o mais rapidamente possível

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

Substituição contínua de todas as VMs o mais rapidamente possível

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

Como atualizar um grupo regional de instâncias gerenciadas

Um grupo regional de instâncias gerenciadas contém instâncias de máquinas virtuais espalhadas por várias zonas dentro de uma região, em oposição aos grupos zonais de instâncias gerenciadas, que contêm apenas instâncias em uma zona. Os grupos regionais de instâncias gerenciadas permitem distribuir instâncias em mais de uma zona para melhorar a disponibilidade do aplicativo e permitir casos extremos em que uma zona falha ou todo um grupo de instâncias deixa de responder.

A atualização de um grupo regional de instâncias gerenciadas usando o recurso Instance Group Updater é semelhante a uma atualização em um grupo zonal de instâncias gerenciadas, com algumas exceções descritas a seguir. Ao iniciar uma atualização em um grupo regional de instâncias, as instâncias sempre serão atualizadas pelo Updater de modo proporcional e uniforme em cada zona. Não é possível escolher instâncias específicas em zonas específicas para serem atualizadas primeiro, nem atualizar instâncias em apenas uma zona.

Diferenças entre a atualização de um grupo regional de instâncias gerenciadas e um zonal

Antes de iniciar uma atualização para um grupo regional de instâncias gerenciadas, esteja ciente de que há vários itens que se comportam de maneira diferente dos grupos zonais de instâncias gerenciadas.

  • Os parâmetros de atualização padrão em grupos de instâncias gerenciadas por região são maxUnavailable=[NUMBER_OF_ZONES] e maxSurge=[NUMBER_OF_ZONES]. [NUMBER_OF_ZONES] é o número de zonas selecionadas. Por padrão, 3.

  • Se você usa números fixos ao especificar uma atualização, eles precisam ser zero ou igual ou maior que o número de zonas associadas ao grupo de instâncias gerenciadas por região. Por exemplo, se o grupo for distribuído em três zonas, não é possível definir maxSurge como 1 ou 2 porque o Updater precisa criar uma instância extra em cada uma 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 grupo regional de instâncias gerenciadas e distribuído uniformemente. Por exemplo, se você especificar maxSurge=10, o Updater dividirá 10 pelo número de zonas da região e criará novas instâncias com base nesse número. Se o número de instâncias não for dividido uniformemente em zonas, o Updater adicionará as instâncias adicionais a uma zona aleatória. Assim, para dez instâncias em três zonas, duas das zonas receberão três instâncias e uma zona receberá quatro instâncias. A mesma lógica é aplicada aos parâmetros maxUnavailable e targetSize para atualizações canário.

Uma porcentagem só pode ser especificada se o grupo de instâncias gerenciadas contém 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á distribuir as instâncias uniformemente entre as zonas. O restante será arredondado para mais ou para menos em cada zona, mas a diferença total não será maior que uma instância de VM por grupo. Por exemplo, em um grupo de instâncias gerenciadas com dez instâncias e uma porcentagem de tamanho de destino de 25%, a atualização será implementada em duas a três instâncias de VM.

  • Se você especificar uma porcentagem para opções de atualização como maxSurge e maxUnavailable, ela será arredondada independentemente por zona. As mesmas regras que se aplicam à atualização de grupos de instâncias gerenciadas por zona se aplicam nesse caso.

Como monitorar atualizações graduais

Depois de iniciar uma atualização contínua, pode levar algum tempo para o término da atualização. Você pode monitorar o estado da atualização por meio da obtenção de uma lista de instâncias que fazem parte do grupo de instâncias gerenciadas. A API Compute Engine retorna o status da instância juntamente com uma lista de instâncias.

Console

Para monitorar a atualização contínua de um grupo, acesse a página de detalhes do grupo de instâncias específico.

  1. Acesse a página "Grupos de instâncias" no Console do GCP.

    Acessar a página "Grupos de instâncias"

  2. Selecione o grupo de instâncias a ser atualizado. A página de visão geral do grupo de instâncias mostra o modelo que cada instância usa.
  3. Para ver os detalhes, clique na guia Detalhes.

A página Detalhes mostra o número atual e de destino de instâncias sendo atualizadas para cada modelo de instância e também exibe os parâmetros de atualização.

gcloud

gcloud beta compute instance-groups managed list-instances [INSTANCE_GROUP_NAME] [--filter="zone:([ZONE])" | --filter="region:([REGION])"]

gcloud retorna uma resposta com uma lista de instâncias no grupo de instâncias e os respectivos status. Por exemplo:

NAME               ZONE           STATUS   ACTION    INSTANCE_TEMPLATE  LAST_ERROR
vm-instances-9pk4  us-central1-f           CREATING  my-new-template
vm-instances-h2r1  us-central1-f           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

API

Na API, faça uma solicitação POST para o seguinte URI:

POST https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP_NAME]/listManagedInstances

Se o grupo de instâncias for um grupo regional de instâncias gerenciadas, substitua zones/[ZONE] por regions/[REGION].

A API retorna uma lista de instâncias para o grupo e os respectivos status e ação atual.

{
 "managedInstances": [
  {
   "instance": "https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/zones/[ZONE]/instances/vm-instances-j701",
   "id": "4251656203855893170",
   "instanceStatus": "RUNNING",
   "instanceTemplate": "https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/global/instanceTemplates/[INSTANCE_TEMPLATE_NAME]",
   "currentAction": "REFRESHING"
  },
  {
   "instance": "https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/zones/[ZONE]/instances/vm-instances-prvp",
   "id": "5317605642920955957",
   "instanceStatus": "RUNNING",
   "instanceTemplate": "https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/global/instanceTemplates/[INSTANCE_TEMPLATE_NAME]",
   "currentAction": "REFRESHING"
  },
  {
   "instance": "https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/zones/[ZONE]/instances/vm-instances-pz5j",
   "currentAction": "DELETING"
  },
  {
   "instance": "https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/zones/[ZONE]/instances/vm-instances-w2t5",
   "id": "2800161036826218547",
   "instanceStatus": "RUNNING",
   "instanceTemplate": "https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/global/instanceTemplates/[INSTANCE_TEMPLATE_NAME]",
   "currentAction": "REFRESHING"
  }
 ]
}

Status do grupo e ações pendentes e atuais

Para cada instância em um grupo de instâncias gerenciado, o status atual da instância é descrito pelo campo instanceStatus. Se a instância estiver passando por algum tipo de alteração, o campo currentAction também será preenchido para você acompanhar o status das atualizações. Quando a instância for atualizada com êxito, o campo instanceStatus refletirá o estado atual da instância. Para ver uma lista de campos instanceStatus válidos, consulte a documentação referente a Como verificar o status de instâncias.

Se uma instância estiver passando por algum tipo de alteração, o campo currentAction será preenchido com um dos status a seguir. Caso contrário, o campo currentAction será NONE.

Possíveis valores de currentAction:

  • ABANDONING: a instância está sendo removida do grupo de instâncias gerenciadas.
  • CREATING: a instância está em processo de criação.
  • CREATING_WITHOUT_RETRIES: a instância está sendo criada sem novas tentativas. Se ocorrer uma falha na primeira tentativa, o grupo de instâncias gerenciadas não tentará substituí-la novamente.
  • DELETING: a instância está em processo de exclusão.
  • RECREATING: a instância foi excluída e está sendo substituída.
  • REFRESHING: a instância está sendo removida e adicionada novamente à lista de pools de destino atuais. Essa lista pode ser a mesma dos pools de destino atuais ou diferente.
  • RESTARTING: a instância está em processo de reinicialização com o uso dos métodos stop e start.
  • VERIFYING: a instância foi criada e está em processo de verificação.

No nível do grupo de instâncias gerenciadas, o Compute Engine preenche um campo chamado pendingActions, que descreve o número de instâncias que aguardam uma ação específica. Por exemplo, o campo pendingActions pode retornar uma contagem de pendingActions que especifique:

CREATING: 3
DELETING: 3
RECREATING: 2
RESTARTING: 1

Isso indica que há três instâncias pendentes de exclusão, duas que serão substituídas, uma que será reiniciada e três que serão criadas.

Como reverter uma atualização

Não há um comando explícito para reverter uma atualização para uma versão anterior. Porém, se decidir que quer reverter uma atualização, seja ela totalmente comprometida ou canário, faça uma nova solicitação de atualização e passe o modelo de instância para o qual você quer reverter.

Por exemplo, o seguinte comando reverte uma atualização o mais rápido possível:

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

Substitua [OLD_INSTANCE_TEMPLATE] pelo nome do modelo de instância antigo para o qual você quer reverter.

Na API, faça uma solicitação PATCH para o seguinte URI:

https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP_NAME]

Se o grupo de instâncias for um grupo regional de instâncias gerenciadas, substitua zones/[ZONE] por regions/[REGION].

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

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

O serviço Instance Group Updater trata isso como uma solicitação de atualização regular para que todas as opções de atualização descritas neste documento possam ser especificadas com a solicitação.

Controle da velocidade de uma atualização

Por padrão, quando você faz uma solicitação de atualização, o serviço realiza a atualização o mais rápido possível. Se você não tem certeza se pretende aplicar uma atualização totalmente ou se está testando as alterações de maneira não muito clara, poderá aplicar a atualização mais lentamente com os seguintes métodos:

  1. Inicie uma atualização canário em vez de uma atualização completa.
  2. Defina um valor grande para minReadySeconds. Isso faz com que o serviço aguarde esse número de segundos antes de considerar que a instância foi atualizada e continuar para a próxima.
  3. Defina um valor baixo para maxUnavailable e maxSurge. Isso garante que somente um número mínimo de instâncias seja atualizado de cada vez.

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

Interrupção de uma atualização

Não há nenhum método ou comando explícito para interromper uma atualização. Você pode alterar uma atualização de proativa para oportunista. Se o grupo de instâncias gerenciadas não estiver sendo redimensionado por outros serviços, como o autoescalador, a alteração para oportunista efetivamente "interromperá" a atualização.

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

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

Se você decidir que quer interromper completamente a atualização após convertê-la de proativa para oportunista, poderá interrompê-la usando estas etapas:

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

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

    A ferramenta gcloud retorna uma resposta com uma lista de instâncias no grupo de instâncias e os status atuais delas:

    NAME               ZONE           STATUS   ACTION    INSTANCE_TEMPLATE  LAST_ERROR
    vm-instances-9pk4  us-central1-f  RUNNING  NONE      my-new-template
    vm-instances-j1h8  us-central1-f  RUNNING  NONE      my-new-template
    vm-instances-ngod  us-central1-f  RUNNING  NONE      my-old-template
    

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

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

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

    Para o serviço Updater, essa atualização aparece como "concluída", por isso nenhuma outra instância é atualizada, o que interrompe efetivamente a atualização.

Relação entre versões e propriedades instanceTemplate para um grupo de instâncias gerenciadas

Os campos versions e instanceTemplate de nível superior se sobrepõem em funcionalidade porque os dois campos permitem especificar qual modelo de instância o grupo de instâncias gerenciadas usará para criar novas instâncias. A diferença entre o campo instanceTemplate de nível superior e o campo versions é que o novo campo versions permite que o usuário especifique uma configuração avançada de dois modelos (canário).

Para manter a compatibilidade com versões anteriores, os grupos de instâncias gerenciadas continuarão a aceitar a configuração do campo instanceTemplate de nível superior, mesmo sendo recomendado alternar para o uso apenas do campo versions, já que sua funcionalidade é um superconjunto do campo instanceTemplate. O uso dos dois campos ao mesmo tempo pode levar a ambiguidade e confusão.

Se você especificar os dois campos, instanceTemplate e versions, ao chamar o método update() ou patch(), três situações podem ocorrer:

  • Você define ambos os campos para o mesmo valor.

    Essa é uma solicitação válida. Nesse caso, ela não cria ambiguidade e o novo modelo de instância é aplicado ao grupo de instâncias gerenciadas.

    Por exemplo, na solicitação a seguir, os campos instanceTemplate de nível superior e versions especificam o mesmo modelo de instância, que é diferente do modelo existente atualmente. O grupo de instâncias gerenciadas será atualizado para o novo modelo de instância.

    {
     "instanceTemplate": "global/instanceTemplates/new-template",
     "versions": [
      {
       "instanceTemplate": "global/instanceTemplates/new-template"
      }
     ],
     "updatePolicy": {
       "type": "PROACTIVE"
     }
    }
    
  • Você define os dois campos não correspondentes, mas apenas um valor é diferente do modelo de instância atual no grupo de instâncias gerenciadas.

    Essa é uma solicitação válida. O campo diferente da configuração atual é tomado como o valor pretendido. Por exemplo, você chama o método get(), altera um dos dois campos e, em seguida, chama update(), com apenas um campo alterado.

    {
     "instanceTemplate": "global/instanceTemplates/current-template",
     "versions": [
      {
       "instanceTemplate": "global/instanceTemplates/new-template"
      }
     ],
     "updatePolicy": {
       "type": "PROACTIVE"
     }
    }
    
  • Você define os dois campos, mas eles não são correspondentes, têm valores diferentes e são distintos do modelo de instância atual no grupo de instâncias gerenciadas.

    Essa configuração é inválida e retornará um erro por falta de intenção clara.

    {
     "instanceTemplate": "global/instanceTemplates/new-template",
     "versions": [
      {
       "instanceTemplate": "global/instanceTemplates/a-different-new-template"
      }
     ],
     "updatePolicy": {
       "type": "PROACTIVE"
     }
    }
    

Os campos versions e instanceTemplate e o método get()

Se você especificar apenas um modelo de instância, seja por meio do campo instanceTemplate de nível superior, do campo versions ou de ambos, o método get() retornará os dois campos na resposta. Isso faz com que o novo campo versions seja compatível com versões anteriores. Enquanto você especificar um único modelo de instância em cada um desses campos, não haverá alteração no que get() retorna no campo instanceTemplate.

Se o campo versions tiver dois modelos de instância especificados, o método get() retornará um campo instanceTemplate de nível superior vazio. Não há como expressar uma configuração canário de dois modelos de instância sem ambiguidade em um campo instanceTemplate de nível superior, portanto o campo não é usado durante uma atualização canário.

O campo versions e o método setInstanceTemplate()

Para manter a compatibilidade reversa, o método setInstanceTemplate() se comporta como da maneira anterior, permitindo alterar o modelo usado pelo grupo de instâncias gerenciadas para criar novas instâncias. Ao chamar esse método, o campo versions será substituído pelo modelo de instância especificado pelo método setInstanceTemplate().

Além disso, o método definirá updatePolicy para OPPORTUNISTIC. Isso evita que o grupo de instâncias gerenciadas implante ativamente um modelo de instância que não estava especificado explicitamente no campo versions.

Feedback e dúvidas

Dúvidas e feedback são bem-vindos. Envie suas perguntas para cloud-updater-feedback@google.com.

A seguir

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Documentação do Compute Engine