在 MIG 中配置有状态元数据

实例元数据对于设置应用属性以及通过元数据服务器与应用进行通信非常有用。例如，您可以使用元数据来配置虚拟机 (VM) 实例的身份、环境变量、集群架构相关信息或虚拟机负责的数据范围。

通过在代管实例组 (MIG) 中配置有状态元数据，可确保特定于实例的元数据在代管实例自动修复、更新和重新创建事件中得以保留。

如需为 MIG 中的虚拟机实例单独配置有状态元数据，请在实例配置中设置该元数据并应用配置。您可以在创建实例时设置个别实例配置，也可以针对现有代管实例进行设置。应用实例配置后，MIG 会将有状态元数据存储在托管式实例的配置保留状态 (preservedStateFromConfig) 字段中。

准备工作

参阅何时使用有状态 MIG 以及有状态 MIG 的工作原理。
如果您尚未设置身份验证，请进行设置。身份验证是通过其进行身份验证以访问 Google Cloud 服务和 API 的过程。如需从本地开发环境运行代码或示例，您可以按如下方式向 Compute Engine 进行身份验证。

选择标签页以了解您打算如何使用本页面上的示例：
gcloud
1. 安装 Google Cloud CLI，然后通过运行以下命令初始化 Google Cloud CLI：
```
gcloud init
```
  注意：如果您之前安装了 gcloud CLI，请确保通过运行 gcloud components update 获得最新版本。
2. 设置默认区域和可用区。
Terraform

如需从本地开发环境使用本页面上的 Terraform 示例，请安装并初始化 gcloud CLI，然后使用用户凭据设置应用默认凭据。
1. 安装 Google Cloud CLI。
2. 如需初始化 gcloud CLI，请运行以下命令：
```
gcloud init
```
3. 为您的 Google 账号创建本地身份验证凭据：
```
gcloud auth application-default login
```
如需了解详情，请参阅为本地开发环境设置身份验证。
REST

如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭据。

限制

具有有状态元数据的 MIG 存在以下限制：

具有有状态配置的 MIG（有状态 MIG）具有以下限制：

如果您的 MIG 采用有状态配置，则您无法使用自动扩缩功能。
如果您要使用自动滚动更新，则必须将替换方法设置为 RECREATE。
对于有状态区域级 MIG，您必须停用主动式重新分布功能（将重新分布类型设置为 NONE），以防止通过自动跨可用区重新分布删除有状态实例。
如果您使用所有实例配置来替换实例模板属性，则无法在任何每个实例配置中指定这些属性，同时也无法在组的所有实例配置中指定这些属性。
当永久删除某实例（无论是手动删除还是调整大小）时，MIG 不会保留其有状态元数据。

在创建实例时设置有状态元数据

您可以在 MIG 中手动创建实例时设置有状态元数据。这种做法有助于将独立虚拟机上的有状态应用迁移到有状态 MIG 以及创建有状态实例。

如果您在 MIG 中手动创建实例并提供有状态元数据，MIG 会执行以下任务：

使用提供的实例名称通过实例模板创建代管实例。
使用提供的有状态元数据创建个别实例配置，并在实例上设置该元数据。
存储关联代管实例的配置 (preservedStateFromConfig) 中处于保留状态的有状态元数据。

gcloud

如需使用自定义名称创建代管实例并在该虚拟机上设置有状态元数据，请使用带有 --stateful-metadata 标志的 gcloud compute instance-groups managed create-instance 命令。

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

替换以下内容：

NAME：要在其中创建实例的 MIG 的名称
INSTANCE_NAME：要创建的实例的名称
KEY 和 VALUE：除了在实例模板中定义的元数据之外，还要为实例单独设置的有状态元数据键值对
- 您在此处设置的键值对优先于实例模板中任何冲突的键值对

示例

您需要部署一个可以 active 或 standby 模式运行的节点集群 example-cluster。您使用元数据为集群中的每个虚拟机单独设置模式，例如：mode:active。您还使用 logging 元数据键（可设置为 basic 或 elaborate）来为每个节点配置详细日志记录。节点上的应用使用实例元数据中的值进行配置。

如需创建具有详细日志记录的活跃节点 node-12，请运行以下命令：

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

该命令会在 example-cluster MIG 中创建一个虚拟机 node-12，并为新实例设置两个元数据键值对 mode:active 和 logging:elaborate。

Terraform

如需使用自定义名称创建托管式实例并在该虚拟机上设置有状态元数据，请使用 google_compute_per_instance_config 资源。

以下示例使用可用区级 MIG。如果您还没有可用区级 MIG，请创建一个可用区级 MIG，并将虚拟机限制在单个可用区。

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"
    }
  }
}

如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。

REST

如需在 MIG 中创建一个或多个具有自定义虚拟机名称的代管实例，并在这些虚拟机上单独设置有状态元数据，请使用 instanceGroupManagers.createInstances 方法。对于区域级 MIG，请使用 regionInstanceGroupManagers.createInstances 方法。

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

替换以下内容：

PROJECT_ID：请求的项目 ID。
ZONE：MIG 所在的区域（适用于区域级 MIG）
- 对于地区级 MIG，将 zones/ZONE 替换为 regions/REGION 并指定 MIG 所在的地区
NAME：要在其中创建实例的 MIG 的名称
INSTANCE_NAME：要创建的实例的名称
KEY 和 VALUE：除了在实例模板中定义的元数据之外，还要为实例单独设置的有状态元数据键值对
- 您在此处设置的键值对优先于实例模板中任何冲突的键值对

示例

如需创建具有详细日志记录的活跃节点 node-12，请执行以下方法：

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"
        }
      }
    }
  ]
}

该方法会在 example-cluster MIG 中创建一个虚拟机 node-12，并为新实例设置两个元数据键值对 mode:active 和 logging:elaborate。

为现有虚拟机实例单独设置、修改和移除有状态元数据

如需设置、修改或移除 MIG 中现有实例的有状态元数据，请在关联的个别实例配置中设置该元数据，然后更新该实例以应用配置。

gcloud

如需为 MIG 中的虚拟机实例单独配置有状态元数据，请在关联的个别实例配置中设置或移除有状态元数据。如果您同时将配置应用于实例 (--update-instance)，则可以选择是保持实例运行、重启实例还是重新创建实例。如果您未应用配置 (--no-update-instance)，则在重新创建或更新实例之前，您的更改不会生效。

如果给定实例不存在个别实例配置，请使用带有以下标志之一的 gcloud compute instance-groups managed instance-configs create 命令：

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]

如果指定实例已存在个别实例配置，请搭配以下标志使用 gcloud compute instance-groups managed instance-configs update 命令：

--stateful-metadata 标志（用于设置或修改元数据）或
--remove-stateful-metadata 标志（用于移除特定于实例的有状态元数据）。

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]

替换以下内容：

NAME：代管实例组的名称。
INSTANCE_NAME：要为其配置有状态元数据的实例的名称。
KEY=VALUE：除了在实例模板中定义的元数据之外，还要为实例单独设置的有状态元数据键值对。您在此处设置的键值对优先于实例模板中任何冲突的键值对。
KEY：要从个别实例配置中移除的实例特定有状态元数据键。
- 如果实例模板未定义键的值，则在应用更改时，键值对会从实例中完全移除。
- 如果实例模板定义了键的值，则在应用更改时，系统将在实例上设置实例模板中的值。
MINIMAL_ACTION：在将个别实例配置更新应用于实例时，至少执行指定的操作。只有在使用 --update-instance 标志时才能设置 MINIMAL_ACTION。该值必须为以下项之一：
- none：不执行任何操作。
- refresh：应用可在不停止实例的情况下应用的更新。
- restart：停止实例，然后重新启动。
- replace：重新创建实例。
如果省略此项，则使用更新所需的中断性最低的操作。

示例

您有一个节点集群 example-cluster，该集群可以 active 或 standby 模式运行。您使用元数据为集群中的每个虚拟机单独设置模式，例如：mode:active。您还使用 logging 元数据键（可设置为 basic 或 elaborate）来为每个节点配置详细日志记录。每个节点上的应用都使用实例元数据中的值。

实例模板定义了 mode:active 和 logging:basic 元数据，以用作所有实例的默认值。您已在集群内 node-12 虚拟机的个别实例配置中设置了 logging:elaborate。现在，您希望将 node-12 切换到备用模式，并将此虚拟机的日志记录切换到 basic 模式。

如需将 node-12 实例切换到备用模式并将其日志记录切换到基本模式，请运行以下命令：

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

该命令将执行以下操作：

在与 example-cluster MIG 中的虚拟机 node-12 相关联的个别实例配置中设置 mode:standby 元数据。
从 node-12 实例的个别实例配置中移除 logging:elaborate 元数据。
将个别实例配置更改应用于 node-12 虚拟机：
- 根据配置设置 mode:standby 元数据。
- 从实例模板设置 logging:basic 元数据，因为 logging 键的值不再由个别实例配置定义。
默认情况下，更改会立即应用于虚拟机，因为省略了 --no-update-instance 标志。
虚拟机在更新期间会保持运行状态，因为省略了 --instance-update-minimal-action 标志，并且系统默认为更新选择了中断性最低的操作（在本例中为 refresh）。

REST

如需为 MIG 中的现有虚拟机实例单独配置有状态元数据，请在关联的个别实例配置中设置或移除该元数据。然后更新实例以应用配置。

如果指定实例尚不存在个别实例配置，请将 instanceGroupManagers.updatePerInstanceConfigs 方法与有状态元数据结合使用：

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"
    },
    ...
  ]
}

如果指定实例已存在个别实例配置，请使用 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"
    },
    ...
  ]
}

替换以下内容：

PROJECT_ID：请求的项目 ID。
ZONE：MIG 所在的区域（适用于区域级 MIG）。
- 对于地区级 MIG，将 zones/ZONE 替换为 regions/REGION 并指定 MIG 所在的地区。
NAME：MIG 的名称。
INSTANCE_NAME：要为其配置有状态元数据的虚拟机的名称。
KEY 和 VALUE：除了在实例模板中定义的任何元数据之外，还要为实例单独设置的有状态元数据键值对。
- 为实例模板中已存在的键定义的有状态元数据值将替换实例模板中的值。
- 来自实例模板的其他元数据条目不会受影响且仍然可用。
- 提供 null 作为值会从个别实例配置中移除键。
FINGERPRINT（可选）：指定配置的指纹（如果已存在）。用于乐观锁定。

updatePerInstanceConfigs 和 patchPerInstanceConfigs 方法会更新指定个别实例配置，但不会将配置更新应用于关联的虚拟机实例。更改会在您更新或重新创建实例时应用于虚拟机。如需将更改应用于虚拟机，您可以手动应用更新或以主动模式或寻机模式使用更新程序。

示例

实例模板定义了 mode:active 和 logging:basic 元数据，以用作所有实例的默认值。您已在集群内 node-12 虚拟机的个别实例配置中设置了 logging:elaborate。现在，您希望将 node-12 切换到备用模式，并将此实例的日志记录切换到 basic 模式。

如需将 node-12 虚拟机切换到备用模式并将其日志记录切换到基本模式，请使用 patchPerInstanceConfigs 方法修补关联的个别实例配置：

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
        }
      }
    }
  ]
}

该方法将执行以下操作：

在与 example-cluster MIG 中的虚拟机 node-12 关联的个别实例配置中设置 mode:standby 元数据。
从个别实例配置中移除 logging:elaborate 元数据，因为提供的值为 null。

配置更新尚未应用于 node-12 虚拟机实例。如果您下次重新创建或更新实例，或者您使用主动自动更新，则系统会应用配置更新。

如需将实例配置更新应用于 node-12 虚拟机实例，请为该实例调用 instanceGroupManagers.applyUpdatesToInstances 方法：

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"
}

该方法会将更新后的个别实例配置应用于 node-12 虚拟机：

根据个别实例配置设置 mode:standby 元数据。
从实例模板设置 logging:basic 元数据，因为 logging 键的值不再由个别实例配置定义。
虚拟机会在更新期间保持运行状态，因为 minimalAction 设置为 NONE，这允许 MIG 使用更新所需的中断性最低的操作。实例元数据更新需要执行 REFRESH 操作，这不会中断正在运行的实例。

反馈

我们希望了解有关有状态 MIG 的用例、挑战和反馈。请发送至 mig-discuss@google.com，与我们的团队分享您的反馈。

后续步骤

详细了解如何存储和检索实例元数据。
为 MIG 中的虚拟机配置有状态 Persistent Disk。
了解如何应用、查看和移除有状态配置。
详细了解 MIG 以及如何使用代管式实例。