跨计算实例管理主机事件

本文档介绍了如何使用 Cluster Director 套件提供的主机维护功能。还介绍了如何对 Compute Engine 实例监控、规划和执行预定维护。如需管理对预留容量块的维护（无论计算实例是否在这些容量块上运行），请改为参阅跨预留管理主机事件。

主动管理实例上即将发生的维护主机事件，您可以最大限度地减少中断并保持最佳性能。

准备工作

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

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

REST

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

安装 Google Cloud CLI。安装完成后，运行以下命令来初始化 Google Cloud CLI：

gcloud init

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

所需的角色

如需获得管理整个计算实例中的宿主机维护事件所需的权限，请让您的管理员为您授予以下 IAM 角色：

针对项目的 Compute Admin (roles/compute.admin)
拥有对系统事件审核日志的只读权限：针对项目的 Logs Viewer (roles/logging.viewer)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含管理计算实例中的主机维护事件所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需跨计算实例管理主机维护事件，您需要具备以下权限：

查看实例的详细信息：针对项目的 compute.instances.get 权限

您也可以使用自定义角色或其他预定义角色来获取这些权限。

概览

如需优化计算实例的维护，请完成以下步骤：

了解并处理主机维护。了解实例的维护频率和行为（具体取决于其机器系列），并了解如何准备工作负载以处理主机维护。这些信息有助于您最大限度地减少中断并防止数据丢失。
设置通知提醒。创建基于日志的提醒，以便在安排、启动或完成实例维护时收到通知。此方法有助于您主动规划活动，避免意外停机。
跨实例管理维护。查看是否已为实例安排维护。如有需要，您可以跨实例手动启动维护。此流程有助于您提高工作负载对主机事件的应对能力，防止停机，并最大限度地提高应用的可用性。

了解并处理主机维护

在 Compute Engine 实例的生命周期内，运行实例的宿主机会经历多个主机事件。主机事件可以包括以下内容：

Compute Engine 基础架构的计划内维护。
在发生主机错误或收到主机故障报告后，为修复 Compute Engine 基础设施而进行的计划外紧急维护。

下表介绍了加速器优化机器类型的主机维护功能：

机器类型	维护频率	行为	计划性维护的高级通知	紧急维护的高级通知	按需维护	模拟维护
A4X Max 和 A4X	最短 90 天	终止并具有本地 SSD 数据持久性	90 天	如果您启用紧急通知，则为 7 天。否则，需要几小时。	是	否
A4	最短 90 天	终止并具有本地 SSD 数据持久性	90 天	如果您启用紧急通知，则为 7 天。否则，需要几小时。	是	否
A3 Ultra	最短 90 天	终止并具有本地 SSD 数据持久性	90 天	如果您启用紧急通知，则为 7 天。否则，需要几小时。	是	否
A3 Mega 和 A3 High（8 个 GPU）	最短 90 天	终止并具有本地 SSD 数据持久性	60 分钟	几小时	是	是

上表中所示的维护频率为近似值，并不保证准确。 Compute Engine 有时可能更频繁地执行维护。

为防止丢失数据或进度，请配置工作负载以处理主机维护。例如，在工作负载停止之前，使用以下方法保存临时数据和进度：

为计算实例设置通知提醒

您可以创建基于日志的提醒政策，以便在为实例安排、启动或完成维护事件时收到通知。

如需为实例的维护事件创建提醒，请完成以下步骤。针对要创建的每个提醒重复此过程。

在 Google Cloud 控制台中，前往 Logs Explorer 页面：
前往 Logs Explorer

如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。
点击显示查询切换开关以切换到开启位置。
在查询窗格中，构建以下查询之一。这些查询会过滤日志条目，以识别特定的维护事件。如果您想使用多个查询，请重复此过程，为每个查询创建唯一的提醒。
- 如需在安排实例维护时收到提醒，请执行以下操作：
```
protoPayload.methodName="compute.instances.upcomingMaintenance" severity>=DEFAULT
protoPayload.status.message =~ "scheduled"
```
- 如需在实例的维护窗口开启时收到提醒，请构建以下查询：
```
protoPayload.methodName="compute.instances.upcomingMaintenance" severity>=DEFAULT
protoPayload.status.message =~ "ongoing"
```
- 如需在实例维护开始时收到提醒，请构建以下查询：
```
protoPayload.methodName="compute.instance.terminateOnHostMaintenance" severity>=DEFAULT
```
- 如需在实例维护完成后收到提醒，请构建以下查询：
```
protoPayload.methodName="compute.instances.upcomingMaintenance" severity>=DEFAULT
protoPayload.status.message =~ "completed"
```
如需验证查询，请点击运行查询。如果查询有效，则查询结果窗格会显示与查询匹配的日志条目。
在查询结果工具栏中，点击操作列表，然后选择 创建日志提醒。系统会显示创建基于日志的提醒政策窗格。
在提醒详情部分中，执行以下操作：
1. 在提醒政策名称字段中，输入政策的名称。
2. 在政策严重级别列表中，选择警告（或更高的严重级别）。
3. 点击下一步。
在选择要包含在提醒中的日志部分中，点击下一步。
在设置通知频率和自动关闭时长部分中，指定以下内容：
1. 在通知间隔时间列表中，选择您希望接收通知的频率。
2. 在突发事件自动关闭时长列表中，选择 Cloud Logging 在多久后停止发送通知并自动关闭突发事件。
3. 点击下一步。
在应通知的人员部分中，为 Logging 指定通知渠道，以便向其发送通知。
点击保存。

如需在 Logs Explorer 中查看维护事件通知示例，请参阅 Compute Engine 文档中的维护通知示例。

跨计算实例管理维护

您可以执行以下一项或多项操作，查看和控制实例的维护：

如需查看实例即将进行的维护的状态和预定时间，请查看实例的维护状态。
如需立即对实例启动维护，而不是等待预定维护时间，请对实例手动启动维护。

查看计算实例的维护状态

您可以通过检查实例元数据中 upcomingMaintenance 字段的值，查看实例即将进行的维护的状态和预定时间。如果实例不包含 upcomingMaintenance 字段，则系统不会为该实例安排任何主机维护事件。如需详细了解 upcomingMaintenance 中的字段，请参阅 Compute Engine 文档中的维护状态定义。

此外，如果已为实例安排维护，则 upcomingGroupMaintenance 字段会包含 maintenanceReasons 字段。此字段用于说明为实例安排维护的原因，如下表所述：

维护类型	维护原因	计算实例状态
报告有故障的主机后的计划内维护	`FAILURE_GPU_CUSTOMER_REPORTED`	仅适用于在您报告为有故障的主机上运行的实例。
计划内维护（常规维护）	`PLANNED_UPDATE`：计划内基础设施维护 `PLANNED_NETWORK_UPDATE`：计划内网络维护	适用于正在运行、已停止或已暂停的实例。
计划外紧急维护	`FAILURE_DISK`：因挂接到实例的磁盘出现错误而安排的计划外维护。 `FAILURE_GPU`：因 GPU 相关错误而安排的计划外维护。 `FAILURE_GPU_TEMPERATURE`：因 GPU 达到高温后出现 GPU 相关错误而安排的计划外维护。 `FAILURE_GPU_XID`：在您因 GPU 相关错误收到 Xid 消息后安排的计划外维护。 `FAILURE_INFRA`：因基础设施出现错误而安排的计划外维护。 `FAILURE_INTERFACE`：因 NIC 出现错误而安排的计划外维护。 `FAILURE_MEMORY`：因实例的内存出现错误而安排的计划外维护。 `FAILURE_NETWORK`：因网络出现错误而安排的计划外维护。 `FAILURE_NVLINK`：因 NVLink 出现错误而安排的计划外维护。	仅适用于正在运行的实例。

如需查看实例中的 maintenanceReasons 字段，您必须使用 gcloud CLI 或 REST API。如需同时查看多个计算实例的维护状态，您必须使用 Google Cloud 控制台或 REST API。否则，请选择以下选项之一：

控制台

在 Google Cloud 控制台中，前往虚拟机实例页面。

转到虚拟机实例
在维护状态列中，Compute Engine 会显示实例的维护状态。如果您在虚拟机实例表中没有看到此列，请点击 view_column 列显示选项，选中维护状态复选框，然后点击确定。

gcloud

如需查看实例的维护状态，请使用 gcloud compute instances describe 命令，并将 --flatten=resourceStatus.upcomingMaintenance 标志设置为：

gcloud compute instances describe INSTANCE_NAME \
    --flatten=resourceStatus.upcomingMaintenance \
    --zone=ZONE

替换以下内容：

INSTANCE_NAME：实例名称。
ZONE：实例所在的可用区。

输出类似于以下内容之一：

如果为实例安排了主机维护事件，则输出类似于以下内容：

---
canReschedule: true
latestWindowStartTime: '2025-11-01T19:00:00Z'
maintenanceReasons:
- 'PLANNED_UPDATE'
- 'PLANNED_NETWORK_UPDATE'
maintenanceStatus: 'PENDING'
type: 'SCHEDULED'
windowEndTime: '2025-11-01T22:00:00Z'
windowStartTime: '2025-11-01T19:00:00Z'

如果没有为实例安排主机维护事件，则输出类似于以下内容：
```
---
null
```

REST

如需查看实例的维护状态，请发出以下 GET 请求之一。发出请求时，您必须添加 fields 查询参数，以便仅显示实例的名称、机器类型和即将进行的维护。您还必须添加 filter 查询参数，以仅按特定机器类型过滤实例。

如需查看所有可用区中的实例，请使用 instances.aggregatedList 方法。

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/aggregated/instances?fields=items.name,items.machineType,items.upcomingMaintenance&filter=machineType%3AMACHINE_TYPE

如需查看特定可用区中的实例，请使用 instances.list 方法。

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances?fields=items.name,items.machineType,items.upcomingMaintenance&filter=machineType%3AMACHINE_TYPE

替换以下内容：

PROJECT_ID：您在其中创建了实例的项目的 ID。
ZONE：实例所在的可用区。
MACHINE_TYPE：您要用于过滤实例的机器类型。

如果为实例安排了主机维护事件，则该实例会包含 upcomingMaintenance 字段：

{
  "items": [
    {
      "name": "vm-01",
      "machineType": "https://www.googleapis.com/compute/v1/projects/example-project/zones/europe-west1-b/machineTypes/a3-ultragpu-8g",
      "resourceStatus": {
        "upcomingMaintenance": {
          "canReschedule": true,
          "latestWindowStartTime": "2024-11-01T19:00:00Z",
          "maintenanceStatus": "PENDING",
          "maintenanceReasons": [
            "PLANNED_UPDATE",
            "PLANNED_NETWORK_UPDATE"
          ],
          "type": "SCHEDULED",
          "windowEndTime": "2024-11-01T22:00:00Z",
          "windowStartTime": "2024-11-01T19:00:00Z"
        }
      }
    },
    ...
  ]
}

（可选）如需进一步缩小实例列表的范围，请将 filter 查询参数设置为其他过滤条件表达式。

元数据服务器

如需查看实例的维护状态，请执行以下操作：

连接到 Linux 或 Windows 实例（如果您尚未这样做）。

如需查看即将进行的维护安排，请查询 upcoming-maintenance 端点：

curl http://metadata.google.internal/computeMetadata/v1/instance/upcoming-maintenance?alt=json -H "Metadata-Flavor: Google"

如果为实例安排了主机维护事件，则输出类似于以下内容：

"Upcoming maintenance": {
  "can_reschedule": "true",
  "latest_window_start_time": "2024-12-01T19:00:01Z",
  "maintenance_reasons": [
    "PLANNED_UPDATE",
    "PLANNED_NETWORK_UPDATE"
  ],
  "maintenance_status": "PENDING",
  "type": "SCHEDULED",
  "window_end_time": "2024-12-01T21:00:01Z",
  "window_start_time": "2024-12-01T19:00:01Z"
}

如果没有安排主机维护事件，则输出类似于以下内容：

{ }

如需查看虚拟机的当前维护状态，请查询 maintenance-event 端点：
```
curl http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event -H "Metadata-Flavor: Google"
```
如需详细了解这些查询的输出，请参阅查看输出。

手动对计算实例启动维护

您可以对实例手动启动维护，而不是等待预定时间。

根据实例的维护状态，会发生以下情况：

维护状态	说明	看到的内容
已安排	Compute Engine 已为实例安排了维护。您可以在预定时间之前手动启动维护。	在 Google Cloud 控制台中，维护状态显示为已可以运行 - 将于 `DATE` 运行。在 gcloud CLI 或 REST API 中，Compute Engine 会将 `maintenanceStatus` 字段设置为 `PENDING`。
进行中	维护正在进行中。您无法重新安排。	在 Google Cloud 控制台中，维护状态显示为正在运行。在 gcloud CLI 或 REST API 中，Compute Engine 会将 `maintenanceStatus` 字段设置为 `ONGOING`。
已完成	维护已完成。Compute Engine 已从实例中移除所有维护通知。	在 Google Cloud 控制台中，维护状态显示为最新。在 gcloud CLI 或 REST API 中，Compute Engine 会将 `maintenanceStatus` 字段设置为 `COMPLETE`。

您可以同时或单独为多个实例手动启动维护。对于多个实例，请使用 Google Cloud 控制台或 gcloud CLI（后者适用于位于同一可用区中的实例）。对于单个实例，请选择以下任一选项：

控制台

在 Google Cloud 控制台中，前往虚拟机实例页面。

转到虚拟机实例
选择要启动维护的实例所在的行。
点击 运行维护。
点击运行维护进行确认。

gcloud

如需手动为同一可用区中的一个或多个实例启动维护，请使用 gcloud compute instances perform-maintenance 命令：

gcloud compute instances perform-maintenance INSTANCE_NAMES \
    --zone=ZONE

替换以下内容：

INSTANCE_NAMES：以空格分隔的实例名称列表，例如 vm-01 vm-02 vm-03。
ZONE：实例所在的可用区。

REST

如需对实例手动启动维护，请向 instances.performMaintenance 方法发出 POST 请求：

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/performMaintenance

替换以下内容：

PROJECT_ID：您在其中创建了实例的项目的 ID。
ZONE：实例所在的可用区。
INSTANCE_NAME：实例名称。

后续步骤

如需在主机事件后测试工作负载，请参阅基准比较方案。
如需详细了解如何监控虚拟机，请参阅监控虚拟机和 Slurm 集群。

跨计算实例管理主机事件 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

Console

gcloud

REST

所需的角色

所需权限

概览

了解并处理主机维护

为计算实例设置通知提醒

跨计算实例管理维护

查看计算实例的维护状态

控制台

gcloud

REST

元数据服务器

手动对计算实例启动维护

控制台

gcloud

REST

后续步骤

跨计算实例管理主机事件