huawei-cloud-ecs-alert

Huawei Cloud ECS 告警自动化

概述

此技能基于 Huawei Cloud CLI (hcloud) v7.2.2+，为 ECS 实例批量创建和管理 Huawei Cloud CES 告警规则。

核心能力：

• 批量创建告警规则（支持 Web/数据库模板或自定义配置）
• 配置告警通知（支持电子邮件/短信/微信）
• 查询 ECS 监控指标
• 查询和管理告警规则列表

使用场景：

• 为新购的 ECS 实例批量配置监控告警
• 在不同环境（开发/测试/生产）中配置差异化告警策略
• 批量查询 ECS 监控数据
• 集中管理告警通知

安全限制：

• ❌ 禁止删除告警规则（防止误删导致监控中断）
• ❌ 禁止将 AK/SK 硬编码（必须使用环境变量或 hcloud configure）

禁止的操作

严格禁止以下操作，即使用户提出请求也不例外：

禁止的操作	API/命令	原因
暴露 AK/SK	任何会以明文形式输出 AK/SK 的命令	存在账户安全风险
接受用户提供的 AK/SK	在对话中接收凭据	违反安全最佳实践
❌ 删除告警规则	DeleteAlarm / hcloud CES DeleteAlarm	无法撤销；删除的告警无法恢复，可能导致监控中断
❌ 批量删除告警	任何批量删除操作	风险很高，可能会意外删除关键监控规则

如果用户请求删除操作，必须拒绝并引导用户： “根据安全限制，此技能不支持删除操作（删除告警/批量删除）。请谨慎使用 Huawei Cloud CES 控制台或 hcloud CLI 手动操作。”

如果用户试图在对话中提供 AK/SK，必须拒绝并引导用户： “为保障账户安全，请不要在对话中直接提供 Huawei Cloud 访问密钥。请使用 hcloud configure 或环境变量配置凭据。”

不支持的操作

此技能不支持以下操作（未提供脚本封装）。如果用户提出请求，请明确说明限制并提供替代方案。不要尝试临时编造此技能未经测试的命令。

不支持的操作	对应 API	替代方案
查询告警历史	ShowAlarmHistory	在 CES 控制台中查看；或手动运行 hcloud CES ListAlarmHistories/v1
启用/禁用告警规则	UpdateAlarm	在 CES 控制台中操作（此技能未封装此操作）
修改告警阈值/指标	UpdateAlarm	删除并重新创建规则；如果只需更改通知，请使用 ./scripts/update_alarm_notifications.sh
创建 SMN 主题	CreateTopic	在 SMN 控制台中创建；或手动运行 hcloud SMN CreateTopic
创建监控仪表板	CreateOneDashboard	在 CES 控制台中操作
查看单个告警规则详情	ShowAlarm	使用 ./scripts/list_alarms.sh --name <pattern> 进行筛选

如果用户请求上述任一操作，请回复： “此技能不支持 。请使用 Huawei Cloud CES/SMN 控制台，或手动运行等效的 hcloud CLI 命令：。你也可以通过此技能的问题跟踪器请求添加此功能。”

工作流

此技能的标准工作流如下：

1. Environment setup  → Configure hcloud CLI credentials (hcloud configure or env vars)
2. Query resources    → ./scripts/list_ecs.sh to get ECS instance list
3. Create alarms      → ./scripts/create_alert_rules.sh --template web --ecs-ids <ids>
4. Configure notify   → ./scripts/manage_notifications.sh --action create ...
5. Verify results     → ./scripts/list_alarms.sh to confirm alarm rules created
6. Continuous monitor → ./scripts/batch_query_metrics.sh to query metrics

写操作确认：步骤 3（创建告警）、步骤 4（创建/删除订阅）、更新通知配置及其他写操作，都需要在执行前由用户确认操作内容和目标资源。

核心命令

查询命令（只读，无需确认）

# List ECS instances
./scripts/list_ecs.sh [--name <filter>] [--format json]

# List alarm rules
./scripts/list_alarms.sh [--name <filter>] [--format json]

# List SMN topics and subscriptions
./scripts/list_subscriptions.sh [--topics | --subscriptions]

# Batch query monitoring metrics
./scripts/batch_query_metrics.sh --ecs-ids <ids> --metric cpu_util --period 1h

创建命令（写操作，需要用户确认）

# Batch create alarm rules (WARNING: confirm target ECS and alarm template)
./scripts/create_alert_rules.sh --template web --ecs-ids ecs-001,ecs-002

# Create SMN subscription (WARNING: confirm subscription endpoint and topic)
./scripts/manage_notifications.sh --action create --protocol email --endpoint [email protected] --topic-urn <URN>
./scripts/create_email_subscription.sh --email [email protected] --topic-urn <URN>

更新/删除命令（写操作，需要用户确认）

# Update alarm notification config (WARNING: confirm alarm ID and notification topic)
./scripts/update_alarm_notifications.sh --action add --alarm-id <id> --smn-topic-urn <URN>

# Delete SMN subscription (WARNING: confirm subscription URN)
./scripts/manage_notifications.sh --action delete --subscription-urn <URN>

架构

Huawei Cloud CES Alert Management
├── CreateAlertRules       (Batch create alarm rules, supports templates/custom)
├── ConfigureNotifications  (Configure alarm notifications, supports email/SMS/WeChat)
├── QueryMetrics           (Batch query monitoring data, supports multiple ECS)
└── ListAlarmRules         (List alarm rules and details)

前置条件

前置条件 1：Huawei Cloud CLI（hcloud / KooCLI）>= 7.2.2 运行 hcloud version 验证版本是否 >= 7.2.2。如果尚未安装或版本过低， 请参阅 references/cli-installation-guide.md 中的安装指南。

hcloud version

前置条件 2：已配置 Huawei Cloud 凭证 检查 CLI 配置中是否包含有效凭证（AK/SK、IAM 等）。

hcloud configure list

凭证配置方式（任选一种）：

1. hcloud CLI 配置（推荐）：通过 hcloud configure 进行交互式设置，凭证会加密并存储在 ~/.hcloud/config.json 中。

2. 每次调用时传入 AK/SK：在每条命令中传入 --cli-access-key=<AK> --cli-secret-key=<SK>（用于自动化；注意：凭证会出现在进程列表中）

⚠️ 重要：hcloud（KooCLI）仅通过 ~/.hcloud/config.json（由 hcloud configure 生成）或 --cli-access-key/--cli-secret-key 参数进行身份验证。它不会读取 HW_ACCESS_KEY、HW_SECRET_KEY、HUAWEI_CLOUD_AK、HUAWEI_CLOUD_SK、HUAWEI_CLOUD_REGION 或 HUAWEI_CLOUD_SECURITY_TOKEN 环境变量——此类变量会被静默忽略（hcloud 会回退到使用 config.json）。不要指示用户通过导出这些环境变量来对 hcloud 进行身份验证。

此技能脚本的凭证来源：随附的 Shell 脚本是 hcloud CLI 的轻量封装。它们会从 HW_REGION_NAME/HUAWEI_CLOUD_REGION 读取区域（或默认为 cn-north-4），以设置 --cli-region，但身份验证始终来自 hcloud configure。使用 hcloud configure 配置一次凭证后，脚本即可运行。 如果输出不包含有效配置，请停止操作并指导用户进行配置。 hcloud 参数格式要求 hcloud（KooCLI）的所有参数都必须使用 --param=value 格式（以等号连接），不支持用空格 分隔。 ✅ 正确：hcloud CES ListAlarmRules --cli-region=cn-north-4 ❌ 错误：hcloud CES ListAlarmRules --cli-region cn-north-4

此技能提供 8 个 Shell 脚本，封装了常用的 hcloud 命令，支持批量操作和格式化输出。

**脚本列表和用法示例（点击展开）**

脚本	功能	hcloud 命令
list_ecs.sh	查询 ECS 实例列表	hcloud ECS ListServersDetails
list_alarms.sh	查询告警规则列表	hcloud CES ListAlarmRules
create_alert_rules.sh	批量创建告警规则	hcloud CES CreateAlarmRules
batch_query_metrics.sh	批量查询监控数据	hcloud CES ShowMetricData
list_subscriptions.sh	查询 SMN 主题和订阅	hcloud SMN ListTopics/Subscriptions
manage_notifications.sh	管理 SMN 订阅	hcloud SMN AddSubscription / BatchDeleteSubscriptions
update_alarm_notifications.sh	更新告警通知配置	hcloud CES UpdateAlarmNotifications

用法示例：

# 查询 ECS 实例

./scripts/list_ecs.sh                          # 查询所有 ECS
./scripts/list_ecs.sh --name ecs-001           # 按名称筛选
./scripts/list_ecs.sh --format json            # 以 JSON 格式输出
./scripts/list_ecs.sh --format ids             # 仅输出 ECS ID 列表

# 查询告警规则

./scripts/list_alarms.sh                       # 查询所有告警
./scripts/list_alarms.sh --name "cpu.*"  # 按名称模式筛选
./scripts/list_alarms.sh --format ids          # 仅输出告警 ID

# 创建告警规则

./scripts/create_alert_rules.sh --template web --ecs-ids ecs-001,ecs-002
./scripts/create_alert_rules.sh --metric cpu_util --threshold 80 --ecs-ids ecs-001
./scripts/create_alert_rules.sh --template web --ecs-ids ecs-001 --smn-topic-urn
urn:smn:cn-north-4:xxx:ECS_ALARM_NOTIFY
./scripts/create_alert_rules.sh --template web --ecs-ids ecs-001 --dry-run  # 试运行

核心能力

• 批量创建告警规则：支持基于模板（Web/数据库场景）创建，或自定义指标/阈值配置
• 批量查询监控数据：支持并发查询多台 ECS，输出 CPU/内存/磁盘指标
• 通知配置：支持电子邮件/短信/微信通知，以及 SMN 订阅管理
• 安全合规：通过环境变量或 CLI 配置提供 AK/SK，绝不硬编码

使用场景

场景 1：为新建 ECS 批量配置告警

背景：新购了 10 台 ECS 实例，需要为所有实例配置 CPU/内存告警规则。

步骤：

1. 查询 ECS 实例 ID
2. 使用 web 模板批量创建告警规则
3. 配置电子邮件通知

# Step 0: Configure credentials once (hcloud CLI reads ~/.hcloud/config.json; it does NOT read AK/SK env vars)
hcloud configure
# Optional: set region env var consumed by the scripts' --cli-region default
export HUAWEI_CLOUD_REGION=cn-north-4
./scripts/list_ecs.sh --format ids

# 2. Batch create alarm rules
./scripts/create_alert_rules.sh --template web --ecs-ids ecs-001,ecs-002,ecs-003

# 3. Configure notification
./scripts/manage_notifications.sh --action subscribe --topic-urn <SMN_TOPIC_URN> --protocol email --endpoint [email protected]

场景 2：查询多台 ECS 的监控数据

背景：需要查看过去一小时内 5 台 ECS 实例的 CPU 利用率。

./scripts/batch_query_metrics.sh \
  --ecs-ids ecs-001,ecs-002,ecs-003,ecs-004,ecs-005 \
  --metric cpu_util \
  --from 2024-01-01T10:00:00Z \
  --to 2024-01-01T11:00:00Z \
  --format table

输入参数

• AK/SK：通过 hcloud configure 配置（推荐，存储在 ~/.hcloud/config.json 中）——hcloud CLI 不会读取 AK/SK 环境变量
• 安全令牌（可选）：使用临时 STS 凭证时，请使用 hcloud configure --cli-mode=AKSK 和 --cli-security-token，或在每条命令中传入 --cli-security-token=<token>
• 区域：通过 --cli-region 参数或 HUAWEI_CLOUD_REGION/HW_REGION_NAME 环境变量设置（默认值：cn-north-4）
• ECS ID：以逗号分隔的 ECS 实例 ID
• 告警 ID：以逗号分隔的告警规则 ID
• 模板：告警模板（web/database）
• 指标：监控指标名称。主机指标：cpu_util、disk_util_inband（命名空间 SYS.ECS）；内存指标：mem_usedPercent（命名空间 AGT.ECS）
• 阈值：告警阈值
• SMN 主题 URN：用于通知的 SMN 主题 URN

参数确认

所有写入操作（创建／更新／删除）都必须明确展示操作内容，并在执行前获得用户确认。

操作类型	脚本	需确认的内容
创建	create_alert_rules.sh	目标 ECS ID 列表、告警模板／指标／阈值
创建	manage_notifications.sh --action create	订阅协议、终端地址、SMN 主题 URN
创建	create_email_subscription.sh	电子邮件地址、SMN 主题 URN
更新	update_alarm_notifications.sh	告警 ID、SMN 主题 URN、操作类型
删除	manage_notifications.sh --action delete	订阅 URN（删除后不可撤销）

查询操作（list_ecs / list_alarms / list_subscriptions / batch_query_metrics）为只读操作，无需确认。

输出格式

• 表格：格式化的表格输出（默认）
• JSON：便于程序处理的 JSON 格式
• ID：仅输出 ID 列表，供脚本使用

验证方法

执行任何操作后，请使用以下方法进行验证：

1. 列出告警：./scripts/list_alarms.sh --name <pattern>
2. 查询指标：./scripts/batch_query_metrics.sh --ecs-ids <ids> --metric cpu_util
3. 检查通知：./scripts/list_subscriptions.sh

常见验证问题请参阅 references/troubleshooting.md。

最佳实践

1. 标准场景使用模板：Web／数据库模板涵盖了大多数使用场景
2. 配置多个通知渠道：关键告警使用电子邮件 + 短信
3. 设置合理的阈值：建议 CPU 为 80％、内存为 85％、磁盘为 90％
4. 通过 hcloud configure 配置凭证（hcloud CLI 会读取 ~/.hcloud/config.json，但不会读取 AK/SK 环境变量）：
   • ✅ 推荐：hcloud configure（加密存储在 ~/.hcloud/config.json 中）
   • ⚠️ 仅用于区域的环境变量：HUAWEI_CLOUD_REGION / HW_REGION_NAME 用于设置脚本 --cli-region 的默认值——仅设置区域，不用于身份验证
   • ❌ 禁止：在脚本或配置文件中硬编码 AK/SK
   • ❌ 容易误导：export HUAWEI_CLOUD_AK/SK 或 export HW_ACCESS_KEY/SECRET_KEY 无法用于 hcloud 身份验证（环境变量会被忽略）
5. 使用环境检查脚本：首次使用前运行 ./scripts/check_env.sh 验证配置

常见问题

问题 1：找不到 hcloud 命令

解决方案：安装 KooCLI，参阅 references/cli-installation-guide.md

问题 2：403 Forbidden

解决方案：检查 IAM 权限，确保已授予 CES FullAccess 和 SMN FullAccess 策略。参阅 references/iam-policies.md

问题 3：创建告警失败

解决方案：检查指标名称和阈值范围。CPU／内存阈值应为 0-100。

问题 4：没有监控数据

解决方案：检查 ECS 实例状态和指标采集间隔。数据可能会延迟 5 分钟。

更多故障排除指南请参阅 references/troubleshooting.md。

重要说明

CLI 版本要求：必须使用 hcloud CLI v7.2.2 或更高版本。较旧版本可能不支持某些 API 参数格式。

区域一致性：所有操作都必须指定相同的区域（--cli-region 或 HUAWEI_CLOUD_REGION 环境变量）。跨区域操作将会失败。

告警阈值范围：CPU/内存利用率阈值必须介于 0-100 之间。建议将磁盘使用率阈值设置在 80-95 之间。

监控数据延迟：CES 监控数据通常会延迟 5 分钟。查询实时数据可能会返回空结果。

创建 SMN 订阅：

• ✅ 推荐：使用 ./scripts/create_email_subscription.sh 脚本，该脚本会自动使用 hcloud CLI 配置的凭据（无需手动设置环境变量）
• ✅ 替代方式：使用 Huawei Cloud 控制台（SMN → Topics → Subscribe）创建订阅
• ⚠️ 注意：电子邮件/短信订阅需要先确认才能接收通知。请检查电子邮件并点击确认链接。

详细指南请参阅 references/smn-subscription-guide.md。

批量操作限制：建议单次批量创建的 ECS 实例不超过 20 个。实例过多可能导致 API 超时。

凭据安全：

• ✅ 推荐：使用 hcloud configure——凭据会加密存储在 ~/.hcloud/config.json 中，这是 hcloud CLI 读取的唯一凭据来源
• ⚠️ 仅用于设置区域的环境变量（非身份验证）：HUAWEI_CLOUD_REGION / HW_REGION_NAME 用于设置脚本的 --cli-region 默认值
• ❌ 易造成误解：export HW_ACCESS_KEY/HW_SECRET_KEY 或 export HUAWEI_CLOUD_AK/HUAWEI_CLOUD_SK 不会对 hcloud 进行身份验证（环境变量会被忽略）
• ❌ 禁止：在脚本或配置文件中硬编码 AK/SK

身份验证：hcloud CLI 仅通过 ~/.hcloud/config.json（由 hcloud configure 生成）或每条命令的 --cli-access-key/--cli-secret-key 参数进行身份验证。AK/SK/令牌环境变量会被静默忽略。请勿将导出环境变量记录为可用的身份验证方式。

参考文档

• CLI 安装指南
• IAM 策略
• 相关 API
• 故障排除
• SMN 订阅指南
• 常用命令
• 内存监控指南
• 验收标准