Como configurar metadados com estado em MIGs

Os metadados da instância são úteis para definir propriedades e se comunicar com os aplicativos por meio do servidor de metadados. Por exemplo, é possível usar metadados para configurar a identidade da instância da máquina virtual (VM), as variáveis de ambiente, as informações sobre a arquitetura de cluster ou o intervalo de dados pelo qual uma VM é responsável.

Ao configurar metadados com estado em um grupo de instâncias gerenciadas (MIG), você garante que os metadados específicos da instância sejam preservados na recuperação automática, atualização e recriação de eventos da instância gerenciada.

Configure metadados com estado individualmente para instâncias de VM em um MIG definindo-os na configuração por instância e aplicando a configuração. É possível definir uma configuração por instância na criação da instância ou em instâncias gerenciadas atuais. Depois que a configuração por instância é aplicada, o MIG armazena metadados com estado no campo estado preservado da configuração (preservedStateFromConfig) de uma instância gerenciada.

Antes de começar

Consulte quando usar MIGs com estado e como funcionam os MIGs com estado.
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 da seguinte maneira.

Select the tab for how you plan to use the samples on this page:
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.

Limitações

Um MIG com metadados com estado tem as seguintes limitações:

Um MIG com configuração com estado (um MIG com estado) tem as seguintes limitações:

Não é possível usar o escalonamento automático se o MIG tiver uma configuração com estado.
Se você quiser usar atualizações graduais automatizadas, defina o método de substituição como RECREATE.
Para MIGs regionais com estado, é necessário desativar a redistribuição proativa (defina o tipo de redistribuição como NONE) para evitar a exclusão de instâncias com estado causadas pela redistribuição automática entre zonas.
Se você usar uma configuração de todas as instâncias para substituir as propriedades do modelo de instância, não será possível especificar essas propriedades em nenhuma configuração por instância e ao mesmo tempo na configuração de todas as instâncias do grupo.
Quando você exclui permanentemente uma instância, seja manualmente ou por redimensionamento, o MIG não preserva os metadados com estado da instância.

Como configurar metadados com estado na criação da instância

Defina metadados com estado ao criar instâncias manualmente em um MIG. Isso é útil para migrar um aplicativo com estado em VMs independentes para um MIG com estado, e ao criar instâncias com estado.

Ao criar manualmente uma instância em um MIG e fornecer metadados com estado, o MIG realiza as seguintes tarefas:

Cria uma instância gerenciada a partir do modelo de instância usando o nome da instância fornecido.
Cria uma configuração por instância com os metadados com estado fornecidos e define esses metadados na instância.
Armazena os metadados com estado no estado preservado da configuração (preservedStateFromConfig) da instância gerenciada associada.

gcloud

Para criar uma instância gerenciada com um nome personalizado e definir metadados com estado nessa VM, use o comando gcloud compute instance-groups managed create-instance com a flag --stateful-metadata.

gcloud compute instance-groups managed create-instance NAME \
  --instance INSTANCE_NAME \
  --stateful-metadata KEY=VALUE[,KEY=VALUE,...]

Substitua:

NAME: o nome do MIG em que uma instância será criada.
INSTANCE_NAME: o nome da instância que será criada.
KEY e VALUE: pares de chave-valor de metadados com estado a serem definidos individualmente para as instâncias, além dos metadados definidos no modelo de instância.
- Os valores de chave aqui definidos têm prioridade sobre quaisquer valores de chave divergentes do modelo de instância.

Exemplo

É necessário implantar um cluster de nós (example-cluster) que possa operar em um dos dois modos: active ou standby. Defina o modo individualmente para cada VM em um cluster usando metadados, por exemplo: mode:active. Também é possível configurar a otimização da geração de registros para cada nó com uma chave de metadados logging, que pode ser definida como basic ou elaborate. O aplicativo no nó é configurado usando valores dos metadados da instância.

Para criar um nó ativo (node-12) com geração de registros otimizada, é preciso executar o seguinte comando:

gcloud compute instance-groups managed create-instance example-cluster \
  --instance node-12 \
  --stateful-metadata mode=active,logging=elaborate

O comando cria uma VM (node-12) no MIG example-cluster e define dois pares de chave-valor de metadados, mode:active e logging:elaborate, para a nova instância.

Terraform

Para criar uma instância gerenciada com um nome personalizado e definir metadados com estado nessa VM, use o recurso google_compute_per_instance_config.

O exemplo a seguir usa um MIG zonal. Se você ainda não tiver um MIG zonal, crie um MIG zonal com VMs restritas a uma única zona.

resource "google_compute_per_instance_config" "default" {
  instance_group_manager = google_compute_instance_group_manager.default.name
  zone                   = google_compute_instance_group_manager.default.zone
  name                   = "node-12"
  preserved_state {
    metadata = {
      mode    = "active"
      logging = "elaborate"
    }
  }
}

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

REST

Para criar uma ou várias instâncias gerenciadas em um MIG com nomes de VM e definir metadados com estado individualmente nessas VMs, use o método instanceGroupManagers.createInstances (em inglês). Para um MIG regional, use o método regionInstanceGroupManagers.createInstances (em inglês).

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/createInstances
{
  "perInstanceConfigs": [
    {
      "name": "INSTANCE_NAME",
      "preservedState" : {
        "metadata": {
          "KEY" : "VALUE",
          ...
        }
      }
    },
    ...
  ]
}

Substitua:

PROJECT_ID: o ID do projeto para a solicitação.
ZONE: a zona onde o MIG está localizado, aplicável a um MIG zonal.
- Substitua zones/ZONE por regions/REGION e especifique a região do MIG se ele for regional.
NAME: o nome do MIG em que uma instância será criada.
INSTANCE_NAME: o nome da instância que será criada.
KEY e VALUE: pares de chave-valor de metadados com estado a serem definidos individualmente para as instâncias, além dos metadados definidos no modelo de instância.
- Os valores de chave aqui definidos têm prioridade sobre quaisquer valores de chave divergentes do modelo de instância.

Exemplo

Para criar um nó ativo (node-12) com geração de registros otimizada, execute este método:

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/createInstances

{
  "instance": [
    {
      "name": "node-12",
      "preservedState" : {
        "metadata": {
          "mode":"active",
          "logging":"elaborate"
        }
      }
    }
  ]
}

O método cria uma VM (node-12) no MIG example-cluster e define dois pares de chave-valor de metadados, mode:active e logging:elaborate, para a nova instância.

Como configurar, modificar e remover metadados com estado individualmente para instâncias de VM existentes

Defina, modifique ou remova metadados com estado de uma instância atual em um MIG ao defini-los em uma configuração por instância associada e, em seguida, aplicando a configuração ao atualizar a instância.

gcloud

Para configurar metadados com estado individualmente para uma instância de VM em um MIG, defina ou remova metadados com estado na configuração por instância associada. Se, ao mesmo tempo, você aplicar a configuração à instância (--update-instance), será possível optar por manter a instância em execução, reiniciá-la ou recriá-la. Se a configuração (--no-update-instance) não for aplicada, as alterações não entrarão em vigor até que a instância seja recriada ou atualizada.

Se não houver uma configuração por instância para uma determinada instância, use o comando gcloud compute instance-groups managed instance-configs create com uma das seguintes sinalizações:

gcloud compute instance-groups managed instance-configs create NAME \
  --instance INSTANCE_NAME \
  --stateful-metadata KEY=VALUE[,KEY=VALUE,...] \
  [--no-update-instance | --update-instance] \
  [--instance-update-minimal-action MINIMAL_ACTION]

Se já houver uma configuração por instância para uma determinada instância, use o comando gcloud compute instance-groups managed instance-configs update com:

a sinalização --stateful-metadata para definir ou modificar metadados; ou
a sinalização --remove-stateful-metadata para remover metadados com estado específicos da instância.

gcloud compute instance-groups managed instance-configs update NAME \
  --instance INSTANCE_NAME \
  [--stateful-metadata KEY=VALUE[,KEY=VALUE,...]] \
  [--remove-stateful-metadata KEY[,KEY,...]] \
  [--no-update-instance | --update-instance] \
  [--instance-update-minimal-action MINIMAL_ACTION]

Substitua:

NAME: o nome do grupo de instâncias gerenciadas.
INSTANCE_NAME: o nome da instância em que os metadados com estado serão configurados.
KEY=VALUE: pares de chave-valor de metadados com estado a serem definidos individualmente para as instâncias, além dos metadados definidos no modelo da instância. Os valores de chave aqui definidos têm prioridade sobre quaisquer valores de chave divergentes do modelo de instância.
KEY: chaves de metadados com estado específicos da instância para remover da configuração por instância.
- Se um valor da chave não for definido pelo modelo de instância, o par de chave-valor será removido completamente da instância quando a alteração for aplicada.
- Se um valor da chave for definido pelo modelo de instância, o valor desse modelo será definido na instância quando a alteração for aplicada.
MINIMAL_ACTION: executa, pelo menos, a ação especificada ao aplicar a atualização da configuração por instância à instância. Uma MINIMAL_ACTION só pode ser definida quando a sinalização --update-instance for usada. O valor precisa ser um dos indicados abaixo:
- none: nenhuma ação.
- refresh: aplica as atualizações possíveis sem interromper a instância.
- restart: interrompa a instância e inicie-a novamente.
- replace: recrie a instância.
Se omitida, a ação menos interruptiva exigida pela atualização será usada.

Exemplo

Há um cluster de nós (example-cluster) que pode ser operado em um dos dois modos: active ou standby. Defina o modo individualmente para cada VM em um cluster usando metadados, por exemplo: mode:active. Também é possível configurar a otimização da geração de registros para cada nó com uma chave de metadados logging, que pode ser definida como basic ou elaborate. O aplicativo em cada nó consome os valores dos metadados da instância.

O modelo de instância define os metadados mode:active e logging:basic a serem usados como padrão para todas as instâncias. Você definiu logging:elaborate em uma configuração por instância para a VM node-12 no cluster. Agora, quer alternar node-12 para o modo de espera e alternar a geração de registros para basic para essa VM.

Para alternar a instância node-12 para o modo de espera e a geração de registros dela para o modo básico, execute o seguinte comando:

gcloud compute instance-groups managed instance-configs update example-cluster \
  --instance node-12 \
  --stateful-metadata mode=standby \
  --remove-stateful-metadata logging

O comando faz o seguinte:

Define os metadados mode:standby na configuração por instância associada à VM (node-12) no MIG example-cluster.
Remove os metadados logging:elaborate da configuração por instância da instância node-12.
Aplica a alteração da configuração por instância na VM node-12:
- Define os metadados mode:standby, de acordo com a configuração.
- Define os metadados logging:basic do modelo de instância porque o valor da chave logging não é mais definido pela configuração por instância.
Por padrão, a alteração é imediatamente aplicada à VM, porque a sinalização --no-update-instance é omitida.
A VM continua em execução durante a atualização, porque a sinalização --instance-update-minimal-action é omitida e a ação menos interruptiva é selecionada para a atualização por padrão, neste caso: refresh.

REST

Para configurar metadados com estado individualmente para instâncias de VM atuais em um MIG, defina ou remova os metadados na configuração por instância associada. Em seguida, atualize a instância para aplicar a configuração.

Se ainda não houver configurações por instância para as instâncias especificadas, use o método instanceGroupManagers.updatePerInstanceConfigs com metadados com estado:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/updatePerInstanceConfigs

{
  "perInstanceConfigs": [
    {
      "name": "INSTANCE_NAME",
      "preservedState" : {
        "metadata": {
          "KEY": "VALUE",
          ...
        }
      },
      "fingerprint: "FINGERPRINT"
    },
    ...
  ]
}

Se já houver instâncias por instância para as instâncias especificadas, use o método instanceGroupManagers.patchPerInstanceConfigs

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/patchPerInstanceConfigs

{
  "perInstanceConfigs": [
    {
      "name": "INSTANCE_NAME",
      "preservedState" : {
        "metadata": {
          "KEY": "VALUE",
          ...
        }
      },
      "fingerprint: "FINGERPRINT"
    },
    ...
  ]
}

Substitua:

PROJECT_ID: o ID do projeto para a solicitação.
ZONE: a zona onde o MIG está localizado, aplicável a um MIG zonal.
- zones/ZONE por regions/REGION e especifique a região do MIG se ele for regional;
NAME: o nome do MIG.
INSTANCE_NAME: o nome da VM em que os metadados com estado serão configurados.
KEY e VALUE: pares de chave-valor de metadados com estado a serem definidos individualmente para as instâncias, além dos metadados definidos no modelo de instância.
- Os valores de metadados com estado definidos para as chaves que já existem no modelo de instância modificam os valores do modelo de instância.
- Outras entradas de metadados do modelo de instância permanecem inalteradas e disponíveis.
- Fornecer null como um valor remove a chave da configuração por instância.
FINGERPRINT: opcional. A impressão digital da configuração especificada, se já houver. Usada para bloqueio otimista.

Os métodos updatePerInstanceConfigs e patchPerInstanceConfigs atualizam as configurações por instância especificadas, mas não aplicam as atualizações às instâncias de VMs associadas. As alterações são aplicadas a uma VM quando a instância é atualizada ou recriada. Para aplicar as alterações à VM, é possível aplicar a atualização manualmente ou usar o Updater no modo proativo ou oportunista.

Exemplo

Para alternar a VM node-12 para o modo de espera e sua geração de registro para o modo básico, aplique o patch na configuração patchPerInstanceConfigs por instância associada:

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/patchPerInstanceConfigs

{
  "perInstanceConfigs": [
    {
      "name": "node-12",
      "preservedState" : {
        "metadata": {
          "mode": "standby",
          "logging": null
        }
      }
    }
  ]
}

O método faz o seguinte:

Define os metadados mode:standby na configuração por instância associada à VM (node-12) no MIG example-cluster.
Remove os metadados logging:elaborate da configuração por instância, já que o valor fornecido é null.

A atualização da configuração ainda não foi aplicada à instância de VM node-12. A atualização de configuração será aplicada na próxima vez que a instância for recriada ou atualizada, ou se a atualização automática proativa for utilizada.

Para aplicar a atualização da configuração por instância à instância de VM node-12, chame o método instanceGroupManagers.applyUpdatesToInstances para a instância:

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/applyUpdatesToInstances

{
  "instances": ["/zones/us-east1-c/instances/node-12"],
  "minimalAction": "NONE"
}

O método aplica a configuração por instância atualizada à VM node-12:

Define os metadados mode:standby, de acordo com a configuração por instância.
Define os metadados logging:basic do modelo de instância porque o valor da chave logging não é mais definido pela configuração por instância.
A VM continua em execução durante a atualização porque minimalAction está definida como NONE, o que permite que o MIG use a ação menos interruptiva necessária para a atualização. Uma atualização de metadados de instância requer a ação REFRESH, que não interrompe uma instância em execução.

Feedback

Queremos saber sobre seus casos de uso, desafios e feedback que envolvem os MIGs com estado. Compartilhe essas informações com nossa equipe em mig-discuss@google.com.

A seguir

Saiba mais sobre Como armazenar e recuperar metadados de instâncias.
Configuração de discos permanentes com estado das VMs em um MIG.
Saiba como aplicar, ver e remover uma configuração com estado.
Saiba mais sobre MIGs e como trabalhar com instâncias gerenciadas.