huawei-cloud-cce-kubernetes-event-analyzer

华为云 CCE Kubernetes 事件分析器

概述

查询并分析华为云 CCE 集群中的 Kubernetes 事件，以识别警告、重复故障模式、受影响的资源，以及有用的诊断交接信息。此技能通过 kubectl 查看当前事件，通过 LTS 查看历史事件。

架构：python3 scripts/huawei-cloud.py 分发器 -> 通过外部 kubeconfig 使用 kubectl，或通过 kubectl cce 查询当前事件 / 通过 kubectl cce 发现 LogConfig，并通过 hcloud LTS ListLogs 查询历史事件 -> 筛选与分组 -> 诊断交接。

执行方式：仅调用捆绑的分发器。请勿使用原始 Python Kubernetes SDK 调用、直接 Kubernetes API 调用或临时云命令查询 Kubernetes 事件。huawei_get_cce_events 实现会在内部调用 kubectl：优先访问外部 kubeconfig，然后回退到 kubectl cce 插件。

相关技能：

• huawei-cloud-kubectl-cce-installer - 安装访问集群所需的 kubectl 和 kubectl-cce 插件
• huawei-cloud-cce-metric-analyzer - CCE 和云资源指标

功能：

• 查询整个集群或某个命名空间中的当前 Kubernetes 事件
• 通过外部 kubectl kubeconfig 访问或 kubectl cce 读取事件
• 在明确的时间范围内从 LTS 查询历史事件记录
• 按类型、原因、命名空间、资源和时间戳筛选并分组事件
• 检查事件中引用的受支持资源的当前状态
• 无需再次请求云服务，即可在本地分析提供的当前或历史事件结果
• 识别重复的警告模式，并将证据交接给诊断技能

典型用例：

• “列出此 CCE 集群的 Warning 事件”
• “查找命名空间 default 中重复出现的 FailedScheduling 事件”
• “从 LTS 查询历史 ImagePullBackOff 事件”
• “分析事故期间出现最多的 Kubernetes 事件原因”

先决条件

1. 运行时依赖项

• Python 3.8+，用于运行分发器和处理结果
• hcloud（KooCLI），用于查找集群和生成临时外部 kubeconfig
• kubectl，用于读取当前事件
• 当集群没有可用的外部终端节点时，需要 kubectl-cce；请参阅 kubectl-cce.md
• hcloud LTS 命令支持，以及 Cloud Native Log Collection 插件（log-agent）和 default-event Event-to-LTS LogConfig。huawei_query_k8s_events_from_lts 通过 kubectl cce 读取 logconfigs.logging.openvessel.io，然后使用配置的 LTS ID 调用 hcloud LTS ListLogs。

2. 凭据配置

• 外部 kubeconfig 访问的 hcloud 凭据优先级：显式工具参数 > 本地 hcloud 配置文件 > 环境变量。
• kubectl cce 回退方式需要通过显式工具参数或环境变量提供 AK/SK 和目标集群的 project_id；插件无法复用经过加密的 hcloud 配置文件凭据。如果 project_id 可用，实现会将其显式传递给 kubectl cce --project-id <project-id>。
• LTS 查询需要有效的华为云凭据和已授权的项目。

安全规则：

• 切勿打印、持久化或硬编码 AK/SK、安全令牌、kubeconfig 内容或临时客户端凭据。
• 请勿使用 echo $HUAWEI_AK 或 echo $HUAWEI_SK 检查凭据。
• 外部 kubeconfig 访问优先使用本地 hcloud 配置文件。
• 使用遵循最小权限原则的 IAM 身份和只读 Kubernetes RBAC 权限。

可选环境变量回退方式：

export HUAWEI_AK=<your-ak>
export HUAWEI_SK=<your-sk>
export HUAWEI_REGION=cn-north-4
export HUAWEI_PROJECT_ID=<project-id>
export HUAWEI_SECURITY_TOKEN=<security-token>

3. IAM 权限要求

权限	用途
cce:cluster:get	检查集群外部端点是否可用
cce:cluster:createCert	生成用于外部 kubectl 访问的临时 kubeconfig
lts:logs:search	查询 LTS 中的历史 Event 记录

有效的 Kubernetes 身份还需要对目标命名空间或集群中的 Events 具有只读的 get 和 list 权限。

权限不足时的处理方式：

1. 报告失败的操作和所需权限。
2. 请用户授予缺失的 IAM 或 Kubernetes RBAC 权限。
3. 在用户确认权限已就绪之前，不要重试。

核心命令

所有命令都使用捆绑的分发器：

python3 scripts/huawei-cloud.py <tool-name> key=value key=value

KooCLI 命令格式标准

用户调用分发器，而不是直接使用 hcloud 命令。对于当前 Event 查询，分发器仅在适当时于内部使用 hcloud 检查 CCE 集群并生成临时外部 kubeconfig。

python3 scripts/huawei-cloud.py huawei_get_cce_events \
  region=cn-north-4 cluster_id=<cluster-id>

遵循以下规则：

• 使用 key=value 参数，并为包含空格或特殊 shell 字符的值加引号。
• 不要打印或持久化凭据、安全令牌或临时 kubeconfig 文件。
• 对于集群范围的查询，使用准确的 cluster_id 值。
• LTS 查询必须限定时间范围，同时提供 start_time 和 end_time。

1. 当前 Kubernetes Events

# Query Warning Events (default)
python3 scripts/huawei-cloud.py huawei_get_cce_events \
  region=cn-north-4 cluster_id=<cluster-id>

# Query Events in a namespace
python3 scripts/huawei-cloud.py huawei_get_cce_events \
  region=cn-north-4 cluster_id=<cluster-id> namespace=default

# Limit returned Event records
python3 scripts/huawei-cloud.py huawei_get_cce_events \
  region=cn-north-4 cluster_id=<cluster-id> limit=100

# Query all Event types only when explicitly needed
python3 scripts/huawei-cloud.py huawei_get_cce_events \
  region=cn-north-4 cluster_id=<cluster-id> event_type=all limit=100

默认情况下，工具使用 Kubernetes API 服务器端字段选择器，仅返回 Warning Events。它会先使用外部端点和临时 kubeconfig；随后回退到 kubectl cce。对于大型集群，完整的 Event 历史记录可能非常庞大；只有在用户明确通过 event_type=all 请求后，才查询所有类型。

2. 来自 LTS 的历史 Events

# Query an explicit historical window
python3 scripts/huawei-cloud.py huawei_query_k8s_events_from_lts \
  region=cn-north-4 cluster_id=<cluster-id> \
  start_time="2026-05-30 06:00:00" \
  end_time="2026-05-30 08:00:00"

# Query with an LTS keyword filter
python3 scripts/huawei-cloud.py huawei_query_k8s_events_from_lts \
  region=cn-north-4 cluster_id=<cluster-id> \
  start_time="2026-05-30 00:00:00" \
  end_time="2026-05-30 23:59:59" \
  keywords=FailedScheduling

LTS 时间格式为 UTC YYYY-MM-DD HH:MM:SS；工具始终将输入值解释为 UTC，而非主机的本地时区。集群必须安装并运行正常的 Cloud Native Log Collection 插件（log-agent），且配置 default-event Event-to-LTS LogConfig。工具使用 kubectl cce --cluster-id <cluster-id> --region <region> get logconfigs.logging.openvessel.io -A -o json，选择 default-event，并读取 outputDetail.LTS.ltsGroupID 和 ltsStreamID。LTS 查询默认使用 event_type=Warning，并将 Warning 用作服务器端关键词筛选条件。对于大型集群，只有在用户确认后，才通过 event_type=all 请求完整的 Event 历史记录；此操作会移除类型关键词筛选条件。LTS 筛选采用关键词匹配，而非结构化字段选择器。

3. 查询和分析 Event 结果

未提供 events 时，工具默认查询并分析当前集群 Events。对于跨度超过一小时的历史请求，请使用带时间范围限制的 LTS。提供 start_time 或 end_time 会自动选择 LTS；也可以显式设置 event_source=lts。传入 events 数组（或包含该数组的完整响应对象）时，将保留离线分析行为。

# Query and analyze current Events
python3 scripts/huawei-cloud.py huawei_analyze_cce_events \
  region=cn-north-4 cluster_id=<cluster-id>

# Query and analyze historical LTS Events
python3 scripts/huawei-cloud.py huawei_analyze_cce_events \
  region=cn-north-4 cluster_id=<cluster-id> event_source=lts \
  start_time="2026-05-30 06:00:00" end_time="2026-05-30 08:00:00"

# Analyze supplied Events without a cloud query
python3 scripts/huawei-cloud.py huawei_analyze_cce_events \
  events='[{"type":"Warning","reason":"FailedScheduling","namespace":"default","count":3}]' \
  max_groups=10

风险级别

此技能为只读。它不会更改云资源、Kubernetes 资源、LTS 配置或本地集群访问配置。

级别	含义	执行指南
R3	只读 Event 查询或本地 Event 分析	可自动运行

工具	操作类型	风险级别	说明
huawei_get_cce_events	查询	R3	通过 kubectl 查询当前集群或命名空间中的 Events
huawei_query_k8s_events_from_lts	查询	R3	查询来自已配置 LTS 收集的数据中的历史 Event 记录
huawei_analyze_cce_events	查询和分析	R3	根据需要查询当前 Events 或 LTS Events，然后按类型、原因、命名空间和资源进行汇总

参数参考

常用参数

参数	必填/可选	说明	默认值
region	必填	华为云区域	HUAWEI_REGION
cluster_id	必填	精确的 CCE 集群 ID	N/A
ak	可选	为支持该参数的访问方式显式指定 AK	配置文件/环境回退
sk	可选	为支持该参数的访问方式显式指定 SK	配置文件/环境回退
project_id	kubectl cce 必填；其他情况可选	目标集群的华为云项目 ID	通过 hcloud 配置文件/IAM/环境变量回退，用于外部 kubeconfig 访问

当前事件查询参数

工具	必填	可选
huawei_get_cce_events	region、cluster_id	namespace、event_type（默认为 Warning，也可为 Normal 或 all）、limit、ak、sk、project_id（kubectl cce 必填）、security_token

历史事件查询参数

工具	必填	可选
huawei_query_k8s_events_from_lts	region、cluster_id、start_time、end_time、project_id	event_type（默认为 Warning，也可为 Normal 或 all）、keywords（需要 event_type=all）、ak、sk

事件分析参数

工具	必填	可选
huawei_analyze_cce_events	events，或 region + cluster_id	event_source（默认为 current，也可为 lts）、start_time/end_time（lts 必填）、namespace、event_type、keywords、limit、max_groups（1-100，默认为 10）、check_resource_status（存在 region 和 cluster_id 时默认为 true）、ak、sk、project_id、security_token

输出格式

所有公开响应字段、Event 记录字段和资源状态均在 output-schema.md 中定义。该参考文档是输出约定的唯一事实来源。

工作流

1. 确定 region、精确的 cluster_id、可选的命名空间和事故时间范围。
2. 使用 huawei_get_cce_events 检查当前 Event。
3. 对于超过一小时的历史 Event 时间范围，或需要精确的 LTS 时间范围或关键字筛选时，使用 huawei_query_k8s_events_from_lts。
4. 将返回的 events 传递给 huawei_analyze_cce_events，以汇总原因、命名空间、资源和重复模式。
5. 将证据移交给相关的 Pod、Workload、Node、Storage 或 Network 诊断技能。

有关模式识别和时间范围分析的指导，请参阅 workflow.md。

验证

先运行当前 Event 查询：

python3 scripts/huawei-cloud.py huawei_get_cce_events \
  region=cn-north-4 cluster_id=<cluster-id> limit=10

启用默认的 Event-to-LTS 收集后，验证有界的历史查询：

python3 scripts/huawei-cloud.py huawei_query_k8s_events_from_lts \
  region=cn-north-4 cluster_id=<cluster-id> \
  start_time="2026-05-30 06:00:00" \
  end_time="2026-05-30 07:00:00"

验证当前 Event 响应中包含 access_method，并且 LTS 响应标明默认的 LTS 组和流。验证过程中不要创建或更改日志配置。

最佳实践

1. 从警告开始 - 详细检查前先筛选 type == "Warning"。
2. 按原因分组 - 重复出现的原因比单条记录更快揭示系统性问题。
3. 使用精确的集群 ID - 不要根据集群名称推断集群。
4. 限制 LTS 时间范围 - 使用能回答问题的最短事故时间范围。
5. 使用 LTS 查询历史记录 - Kubernetes 当前 Event 的保留时间有限。
6. 移交而非修复 - 此技能仅提供证据。

注意事项

• 没有活动警告并不能证明集群健康；如果可以，检查历史 LTS Event，以了解近期发生或已恢复的事故。
• Event-to-LTS 路径依赖运行正常且已启用默认 Event 收集的 log-agent 插件。
• 如果受众不需要了解敏感的生产工作负载、Pod 和节点标识符，应在 Event 摘要中对其脱敏。
• 不要通过此技能修改 Kubernetes、CCE 日志、LTS 或云资源。

故障排查

症状	可能原因	处理方法
外部 kubeconfig 访问失败	没有外部端点、配置文件无效或缺少 CCE 权限	验证 cce:cluster:get 和 cce:cluster:createCert；随后工具会尝试 kubectl cce
kubectl cce 回退失败	缺少插件或插件凭据不可用	按照 kubectl-cce.md 安装/配置插件
LTS 查询未找到默认 Event 流	未启用默认 Event 收集，或尚未完成预配	通过 log-agent 插件启用默认 Event 收集，然后重试
LTS 查询未返回记录	时间范围、关键词、保留期或 Event 收集不匹配	缩小或修正时间范围，并验证默认 LTS 组和流
当前 Event 过多	集群查询范围过广	默认查询 Warning；提供 namespace 和更小的 limit，以便在数据源处进一步减少数据
权限被拒绝	缺少 IAM 或 Kubernetes RBAC 权限	授予报告中所列的最小权限，然后重试

限制

• 此技能仅提供文档中说明的两个只读 Event 工具。
• 当前 Event 查询仅支持在服务端按命名空间和 Event 类型（Warning、Normal 或 all）筛选。
• 历史查询要求在事件发生前启用默认的 Event-to-LTS 收集；此技能无法恢复未收集的历史记录。
• 此技能无法创建、修改或删除 LTS 流、Kubernetes 资源或 CCE 资源。
• 此技能不会自动为用户选择集群、命名空间、事件筛选条件或诊断/修复操作。

参考资料

文档	用途
工作流	Event 查询顺序、分组、模式和时间范围分析
风险规则	只读边界、脱敏和移交约束
输出架构	查询、分析和 Event 记录字段
kubectl-cce	kubectl-cce 安装、凭据和访问回退
验收标准	当前、历史以及组合查询与分析流程的预期结果