Glances Cloud 插件详解：基于 OpenStack 元数据服务识别云主机实例信息

• 指标监控
• 监控大盘
• CLI
• 告警
• MCP 服务

导读

本文围绕 docs/aoa/cloud.rst 讲解的cloud 插件展开：当你的主机运行在 OpenStack（含 Amazon EC2 兼容 API 的云平台）上时，Glances 可以通过标准的 OpenStack 元数据服务（metadata service）自动获取云平台、实例 ID、实例类型、实例名称与可用区等信息，并显示在 TUI 界面中。读完本文，你将掌握该插件的启用方式、配置项含义、底层采集原理（两个异步线程与字段映射关系）以及实际运行的前提条件与排查要点。

一、插件功能概述

cloud 插件的目的非常单一且明确：识别宿主机所在的数据中心/云平台环境，并把实例的元信息呈现出来。官方文档的描述为：

This plugin displays information about the cloud provider if your host is running on OpenStack.

也就是说，它不是通用云监控插件，而是专门面向OpenStack及其EC2 兼容 API的场景。从 插件源码 的模块注释可以确认其支持的云 API 范围：

• ThreadOpenStack：标准（Vanilla）OpenStack 元数据服务；
• ThreadOpenStackEC2：兼容 Amazon EC2 元数据服务的 OpenStack 环境。

该插件默认处于禁用状态，需要显式启用后才会启动采集线程。

二、工作原理：OpenStack 元数据服务

OpenStack Nova 为实例提供了一套实例内的元数据服务（metadata service），虚拟机可以通过一个保留的链路本地地址访问：

• IPv4：169.254.169.254
• IPv6：fe80::a9fe:a9fe

cloud 插件正是基于这一机制，在实例内部发起 HTTP 请求来读取平台下发的元数据，无需任何云平台账号或认证信息。官方文档将这一入口称为 "standard OpenStack metadata service"。

从源码看，插件定义了两套 API 地址与字段映射（glances/plugins/cloud/init.py）：

最终汇总的 stats 是一个字典，包含五个键：

stats = { 'id': # 项目 ID / AMI ID 'name': # 实例名称 / 实例 ID 'type': # 角色 / 实例类型 'region': # 可用区 'platform' # 'OpenStack' 或 'Amazon EC2' }

源码中甚至保留了一段仅供本机测试用的示例（glances/plugins/cloud/init.py）：

stats = {'id': 'ami-id', 'name': 'My VM', 'type': 'Gold', 'region': 'France', 'platform': 'OpenStack'}

三、启用与配置

3.1 命令行启用

由于插件默认禁用，官方文档明确要求通过--enable-plugin cloud选项启用：

glances --enable-plugin cloud

--enable-plugin（别名--enable-plugins/--enable）是 Glances 全局插件开关，定义于 glances/main.py，支持逗号分隔的插件列表。与之配套的还有--disable-plugin（别名--disable-plugins/--disable），支持all关键字（glances/main.py），例如只保留 cloud 插件：

glances --disable-plugin all --enable-plugin cloud

3.2 配置文件配置

Glances 的默认配置文件 conf/glances.conf 中包含完整的[cloud]小节（conf/glances.conf）：

[cloud] # This plugin is disabled by default disable=True # Refresh rate for this plugin (in seconds). Default is the global refresh rate. # Cloud metadata API calls are slow. refresh=120

两个配置项的含义：

• disable=True：默认关闭插件（这与文档"disable by default"的描述一致）；
• refresh=120：该插件独立的刷新周期（秒），不跟随全局刷新率。配置注释明确说明原因——云元数据 API 调用较慢，因此把刷新间隔拉长到 120 秒，避免频繁发起元数据请求。

从源码看，插件的启停判定最终由插件基类 glances/plugins/plugin/model.py 的is_enabled()/is_disabled()完成：它优先读取disable_cloud参数（配置文件disable=True会映射到该参数），否则回退到enable_cloud（由--enable-plugin设置），返回d is False作为最终判定结果。也就是说，配置文件与命令行开关是同一套判定逻辑的两种入口。

3.3 依赖要求

cloud 插件依赖 Pythonrequests库（glances/plugins/cloud/init.py）。若环境中缺少requests，插件会打印告警日志 "Missing Python Lib (...), Cloud plugin is disabled"，并自动禁用自身，且采集线程会立即停止（glances/plugins/cloud/init.py）。因此启用前请确认依赖已安装。

四、TUI 界面输出格式

当插件启用、且成功从元数据服务取回数据时，TUI 界面会显示一行云平台信息。输出逻辑位于 glances/plugins/cloud/init.py 的msg_curse()：

• 第一段以标题样式（TITLE）显示platform，即OpenStack或Amazon EC2；
• 第二段显示{type} instance {name} ({region})。

对应的渲染模板为：

msg = self.stats.get('platform', 'Unknown') # 例：OpenStack msg = ' {} instance {} ({})'.format( self.stats.get('type', 'Unknown'), # 例：Gold / m1.small self.stats.get('name', 'Unknown'), # 例：My VM / i-xxxx self.stats.get('region', 'Unknown'), # 例：France / us-east-1a )

有两个值得注意的细节：

1. 无数据时不显示：若 stats 为空或插件被禁用，msg_curse()直接返回空（glances/plugins/cloud/init.py）；
2. 信息不完整时不显示：若拿不到platform或name，同样不渲染，避免输出 "Unknown" 噪声——这是针对 issue #2485 的显式处理（glances/plugins/cloud/init.py）。

因此在实际 TUI 中，只有数据完整可用时你才会看到 cloud 那一行。

五、源码级实现解析：两个采集线程

cloud 插件最核心的实现特点是用两个后台线程异步抓取元数据，避免阻塞 Glances 主循环。

5.1 线程生命周期

在 CloudPlugin.init中，只有is_enabled()判定插件已启用时，才会创建并启动两个线程：

if self.is_enabled(): self.OPENSTACK = ThreadOpenStack() self.OPENSTACKEC2 = ThreadOpenStackEC2() self.OPENSTACK.start() self.OPENSTACKEC2.start()

插件退出时，exit() 会依次调用两个线程的stop()，通过线程内部的threading.Event安全收尾。

5.2 采集流程与回退逻辑

update()的更新策略（glances/plugins/cloud/init.py）是：

stats = self.OPENSTACK.stats if not stats: stats = self.OPENSTACKEC2.stats

即优先使用标准 OpenStack 元数据，若为空（说明当前环境不是 Vanilla OpenStack），则回退到 EC2 兼容 API。

5.3 字段抓取与超时

ThreadOpenStack.run()（glances/plugins/cloud/init.py）按OPENSTACK_API_METADATA定义的字段逐条发起请求：

r = requests.get(r_url, timeout=3)

• 超时设为3 秒，代码注释解释为"本地请求，3 秒超时足够"（glances/plugins/cloud/init.py）；
• 任一请求失败（异常或非 OK 状态）都会break，此时不会写入platform字段，整个 stats 保持为空，从而触发上面的 EC2 回退；
• 只有当四个字段全部成功获取（循环正常走完else分支）时，才设置platform = 'OpenStack'（glances/plugins/cloud/init.py）。

这种"全部成功才认定平台"的设计保证了不会把残缺数据当成有效结果。ThreadOpenStackEC2继承自ThreadOpenStack，仅覆盖平台名、API 地址和字段映射三处常量（glances/plugins/cloud/init.py）。

六、适用前提与限制

基于文档与源码，使用 cloud 插件需要满足以下前提，缺一不可：

1. 运行在 OpenStack 云上（含提供 EC2 兼容元数据服务的环境）。在物理机、普通虚拟机或非 OpenStack 云（如仅提供 AWS 原生元数据的场景需另行确认兼容性）上，插件不会取到数据；
2. 实例能访问链路本地地址169.254.169.254。若云网络策略屏蔽了该地址，采集会因超时失败，插件静默无输出；
3. Python 环境已安装requests，否则插件直接禁用；
4. 显式启用插件：通过--enable-plugin cloud或修改配置文件的disable=False。

几点限制说明：

• 该插件默认禁用、不参与默认输出，需要按上文方式手动开启；
• 刷新周期独立为 120 秒，修改refresh值可调整元数据请求频率（不建议设得过低，元数据 API 调用较慢）；
• 从仓库结构看，tests 目录中暂未见针对 cloud 插件的独立测试文件，功能验证主要依赖真实 OpenStack 环境下的运行表现，本地调试时可参考源码中注释掉的示例 stats 字典进行模拟。

七、快速排障清单

当 TUI 中看不到 cloud 信息时，可按以下顺序排查：

结语

cloud 插件是 Glances 众多插件中定位最聚焦的一个：它只做一件事——通过 OpenStack 标准元数据服务识别宿主机云环境，并把平台、实例类型、名称与可用区以一行信息呈现。其"双线程异步采集 + 全字段成功才认定平台 + EC2 自动回退"的实现方式，既保证了不阻塞主界面，也保证了数据的可靠性。结合 docs/aoa/cloud.rst 的文档说明、插件源码 与 默认配置，你可以快速在 OpenStack 云主机上启用并验证该功能。

• 指标监控
• 监控大盘
• CLI
• 告警
• MCP 服务