KubeEye 集群巡检完全指南KubeSphere 扩展的安装、规则开发与报告获取【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphereKubeEye 是面向 KubeSphere 的 Kubernetes 集群巡检工具通过 OPA/Rego 策略、PromQL 查询、文件完整性校验、内核参数校验与 systemd 健康检查等手段全面检测工作负载、节点、配置与组件中存在的隐患。本文以 KubeSphere 仓库中的 KubeEye 技能文档为骨架结合仓库内 skills/kubeeye/rules/ 目录下的 17 个真实示例规则与 skills/kubeeye/scripts/ 下的自动化脚本源码系统讲解 KubeEye 的架构原理、InstallPlan 式安装、九类巡检规则编写、巡检计划参数调优、邮件告警配置以及报告导出读完即可在 KubeSphere 集群中落地一套可持续运行的集群巡检体系。KubeEye 是什么KubeSphere 的集群巡检扩展KubeEye 以 KubeSphere 扩展Extension的形式交付核心使命是持续发现集群中的隐患而非故障工作负载是否缺少就绪探针、容器是否以特权模式运行、节点内核参数是否符合推荐值、关键配置文件是否被篡改、systemd 服务是否存活、文件系统是否即将写满等。它不需要侵入业务 Pod而是通过一套声明式的巡检规则InspectRule 调度计划InspectPlan驱动 Kubernetes Job 执行检查最终将结果落盘到自定义资源CRD中供查看或下载。典型使用场景包括在 KubeSphere 中安装与配置 KubeEye 集群巡检扩展编写集群巡检规则OPA、PromQL、文件检查、内核参数、systemd 等九类配置周期性或一次性巡检任务查看与下载集群巡检报告HTML / XLSX。架构解析从扩展安装到巡检执行的数据流扩展安装流程KubeEye 遵循 KubeSphere 扩展的标准安装链路从发布到部署共四个阶段kspublish (push extension to KubeSphere) | v Extension available in KubeSphere marketplace | v kubectl apply -f installplan.yaml | v KubeEye deployed (3 components)即先通过kspublish将扩展发布到 KubeSphere 应用商店随后以kubectl apply方式提交 InstallPlanKubeSphere 扩展控制器会完成 KubeEye 三个组件的实际部署。运行时架构部署完成后KubeEye 在 KubeSphere 扩展命名空间extension-kubeeye内运行三个核心组件┌─────────────────────────────────────────────────────────────┐ │ KubeSphere Extension │ │ │ │ ┌─────────────────────┐ ┌─────────────────────────────┐ │ │ │ kubeeye-apiserver │ │ kubeeye-controller-manager │ │ │ │ (Gin REST API) │ │ (4 CRD Controllers) │ │ │ │ Port 9090 │ │ │ │ │ └──────────┬──────────┘ └──────────────┬──────────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ CRDs │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │ │ │ │ │InspectRule│ │InspectPlan│ │InspectTask│ │Inspect │ │ │ │ │ │ │ │ │ │ │ │Result │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ kubeeye-job (K8s Jobs) │ │ │ │ OPA ├─ PromQL ├─ FileChange ├─ Sysctl ├─ Systemd │ │ │ │ NodeInfo ├─ FileFilter ├─ ServiceConnect ├─ Cmd │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘说明图中Cmd指代customCommand规则类型。kubeeye-apiserver基于 Gin 提供 REST API端口 9090kubeeye-controller-manager运行 4 个 CRD 控制器InspectRule / InspectPlan / InspectTask / InspectResult实际巡检逻辑由动态创建的kubeeye-job容器执行。CRD 概览四个自定义资源全部为集群级Cluster ScopeAPI 版本统一为kubeeye.kubesphere.io/v1alpha2CRDAPI 版本作用域用途InspectRulekubeeye.kubesphere.io/v1alpha2Cluster定义巡检规则OPA、PromQL、文件检查等InspectPlankubeeye.kubesphere.io/v1alpha2Cluster调度巡检执行cron 或一次性InspectTaskkubeeye.kubesphere.io/v1alpha2Cluster追踪单次巡检执行由 InspectPlan 创建InspectResultkubeeye.kubesphere.io/v1alpha2Cluster存储巡检结果由 InspectTask 填充CRD 数据流一次巡检的完整生命周期如下User creates InspectRule ──────┐ ├── InspectPlan references InspectRules User creates InspectPlan ──────┘ | | (cron trigger or manual) v InspectTask created by InspectPlanReconciler | InspectTaskReconciler: 1. Fetches referenced InspectRules 2. Merges rules per type 3. Creates K8s Jobs (kubeeye-job) 4. Jobs execute rule checks 5. Results accumulated | v InspectResult populated with findings | v User views results via: - kubectl get inspectresult - API: HTML report / XLSX download关键环节在InspectTaskReconciler它拉取 InspectPlan 引用的所有 InspectRule按规则类型合并例如将所有 OPA 规则归并为一份 Rego 策略、所有 PromQL 规则归并为一份查询列表再创建kubeeye-job类型的 Kubernetes Job 执行检查最后把各规则类型的发现findings聚合写入 InspectResult。部署前置检查确认扩展可用性与安装状态在安装之前先确认 KubeEye 扩展是否已发布到当前 KubeSpherekubectl get extensionversions | grep kubeeye预期输出形如kubeeye-{version}例如kubeeye-1.0.1。如果没有输出说明扩展尚未发布到 KubeSphere需要先完成发布本文假设kspublish已可用。再确认 KubeEye 是否已经安装kubectl get installplans.kubesphere.io kubeeye --ignore-not-found如果 InstallPlan 已存在说明 KubeEye 已安装后续可以走升级流程——只需在 InstallPlan 中选择更新的版本。安装 KubeEye版本检测与 InstallPlan 生成KubeEye 以 KubeSphere 扩展形式安装。仓库提供了自动化脚本 skills/kubeeye/scripts/generate-installplan.sh 来生成合法 InstallPlan。注意以下./scripts/路径默认在skills/kubeeye/目录下执行若在其他目录运行请相应调整路径。Step 1检测并选择版本ALL_VERSIONS$(kubectl get extensionversions.kubesphere.io \ -l kubesphere.io/extension-refkubeeye \ -o jsonpath{range .items[*]}{.spec.version}{\n}{end} | sort -V) LATEST_STABLE$(echo $ALL_VERSIONS | tail -1) echo Available versions: echo $ALL_VERSIONS echo echo Latest stable: $LATEST_STABLE该命令以kubesphere.io/extension-refkubeeye为标签选择器过滤出 KubeEye 的所有扩展版本sort -V按语义化版本号排序tail -1得到最新稳定版。选定版本后将其记为SELECTED_VERSION。Step 2生成并应用 InstallPlan./scripts/generate-installplan.sh $SELECTED_VERSION从脚本源码 generate-installplan.sh 可以看出它生成了如下结构的 InstallPlan 并写入/tmp/kubeeye-installplan.yamlapiVersion: kubesphere.io/v1alpha1 kind: InstallPlan metadata: name: kubeeye spec: extension: name: kubeeye version: ${SELECTED_VERSION} enabled: true upgradeStrategy: Manual随后脚本会先执行kubectl apply --dry-runserver做服务端校验通过后打印 apply 命令。手动应用即可完成安装kubectl apply -f /tmp/kubeeye-installplan.yaml安装状态检查安装过程中可询问用户是否需要检查状态需要时运行./scripts/check-status.sh poll仓库提供的 check-status.sh 支持两种模式核心逻辑围绕 InstallPlan 的.status.state字段用途命令单次快照./scripts/check-status.sh quick等待安装完成5 分钟超时./scripts/check-status.sh poll状态判定逻辑全部Installed→ ✓ 成功打印extension-kubeeye命名空间下的 Pod 列表任一Failed→ ✗ 打印完整 InstallPlan YAML 以便排查超时300 秒→ ⚠ 打印当前状态进行中→ 每 10 秒输出一次进度。quick模式还会额外输出 InstallPlan 的状态条件.status.conditions[-1].reason/.message与extension-kubeeye命名空间下的 Pod 详情适合快速定位卡在哪一步。快速开始导入规则并创建巡检计划Step 1导入示例规则kubectl apply -f rules/该命令将本技能 rules/ 目录下捆绑的全部示例 InspectRule 一次性应用到集群。规则文件覆盖 OPADeployment、Pod、Node、Job、CronJob、DaemonSet、StatefulSet、Event、PodState、NodeStatsSummary、PromQL、FileChange、FileFilter、NodeInfo、Sysctl、Systemd、ServiceConnect 等类型。注意如果使用 PromQL 规则导入前务必在 kubeeye_promql_inspect.yaml 中设置正确的prometheus.endpoint仓库示例默认指向http://prometheus-k8s.kubesphere-monitoring-system.svc.cluster.local:9090即 KubeSphere 监控栈内的 Prometheus。Step 2创建巡检计划 InspectPlan./scripts/generate-plan.sh从脚本源码 generate-plan.sh 看它会动态读取集群中已有的全部 InspectRule 名称生成引用所有规则的 InspectPlan 并直接kubectl apply -f -apiVersion: kubeeye.kubesphere.io/v1alpha2 kind: InspectPlan metadata: name: inspectplan spec: schedule: * */12 * * ? maxTasks: 10 suspend: false timeout: 30m ruleNames: - name: rule-1 - name: rule-2 ...示例计划每 12 小时巡检一次Cron 表达式* */12 * * ?保留最近 10 次结果maxTasks: 10单次巡检超时 30 分钟。若集群中尚无 InspectRule脚本会提示先执行kubectl apply -f rules/并退出。Step 3监控巡检任务 InspectTaskInspectPlan 应用后控制器会自动创建对应的 InspectTask# Watch task status kubectl get inspecttask -w # Describe a task kubectl describe inspecttask {task-name}-w持续观察任务状态流转describe可查看任务引用的规则列表、调度来源与执行进度。Step 4查看巡检结果 InspectResultInspectTask 完成后会生成 InspectResult# List results kubectl get inspectresult # View result details kubectl get inspectresult {result-name} -o yaml下载 HTML 报告与 XLSX 报告需要先拿到kubeeye-apiserver的服务地址# 获取 apiserver 服务地址 kubectl get svc -n extension-kubeeye kubeeye-apiserver \ -o custom-columnsCLUSTER-IP:.spec.clusterIP,PORT:.spec.ports[*].port # Download HTML report curl http://{svc-ip}:9090/kapis/kubeeye.kubesphere.io/v1alpha2/inspectresults/{result-name}?typehtml -o report.html # Download XLSX report curl http://{svc-ip}:9090/kapis/kubeeye.kubesphere.io/v1alpha2/inspectresults/{result-name}/download -o report.xlsx两个 API 均位于 kubeeye-apiserverGin REST API端口 9090下?typehtml返回网页版报告/download返回 Excel 报表。浏览器查看报告如需在浏览器中直接打开报告可将 apiserver 以 NodePort 方式暴露kubectl -n extension-kubeeye expose deploy kubeeye-apiserver --port9090 --typeNodePort --nameke-apiserver-node-port # http://{node-address}:{node-port}/kapis/kubeeye.kubesphere.io/v1alpha2/inspectresults/{result-name}?typehtmlInspectRule 规则开发九类巡检规则详解InspectRulekubeeye.kubesphere.io/v1alpha2是定义巡检逻辑的核心资源。一个规则文件可以在spec下同时组合多种规则类型如opas、promQL、sysctl并存灵活度极高。OPA 规则opasOPA 规则使用 Rego 策略语言通过input.kind与input.apiVersion指定目标资源类型。Rego 子包package约定inspect.kubeeye—— 标准 K8s 资源Deployment、Pod、Node、ConfigMap 等inspect.kubeeye.nodeStatsSummary—— 节点 stats summary通过input.pods[*]访问带ephemeral-storage的 Pod 数据。示例一Deployment 镜像拉取策略检查spec: opas: - name: imagePullPolicyRule rule: |- package inspect.kubeeye import rego.v1 deny contains msg if { input.kind Deployment input.apiVersion apps/v1 container : input.spec.template.spec.containers[_] container.imagePullPolicy ! IfNotPresent msg : { Name: input.metadata.name, Namespace: input.metadata.namespace, Type: input.kind, Message: ImagePullPolicyNotIfNotPresent, Reason: sprintf(imagePullPolicy is %v, should be IfNotPresent, [container.imagePullPolicy]), Level: WARNING } }示例二Node 临时存储ephemeral-storage检查spec: opas: - name: CheckEphemeralStorage rule: |- package inspect.kubeeye.nodeStatsSummary import rego.v1 threshold : 5 * 1024 * 1024 * 1024 deny contains msg if { pod : input.pods[_] bytes : pod[ephemeral-storage].usedBytes bytes threshold msg : { Name: pod.podRef.name, Namespace: pod.podRef.namespace, Type: Pod, Level: danger, Message: sprintf(ephemeral-storage usage %.2f GB exceeds 5 GB, [bytes / 1073741824]), Reason: ephemeral-storage exceeds threshold } }消息结构约定无论哪种 OPA 规则deny集合中的msg对象都遵循统一的五字段结构——Name、Namespace、Type、Message规则标识、Reason人类可读的原因描述、LevelWARNING/DANGER/CRITICAL等严重级别。仓库内置的 kubeeye_opa_deployment_inspect.yaml 是绝佳的参考范本一个文件内组合了 14 条 Deployment 巡检规则可直接照搬复用镜像与探针imagePullPolicyRuleForDeployment要求IfNotPresent、readinessProbeRuleForDeployment/livenessProbeRuleForDeployment必须配置就绪/存活探针且跳过kubeeye-system命名空间、LivenessProbeTimeRuleForDeployment对kubesphere-*与kube-system命名空间探针总超时initialDelaySeconds failureThreshold * periodSeconds不得超过 180 秒资源配额cpuRequestsRuleForDeployment/cpuLimitsRuleForDeployment/memoryRequestsRuleForDeployment/memoryLimitsRuleForDeployment容器必须声明 CPU/内存 requests 与 limits安全加固高危hostPathRuleForDeploymenthostPath 卷必须只读DANGER、privilegedRuleForDeployment禁止特权容器DANGER、insecureCapabilitiesRuleForDeployment禁止 CHOWN、DAC_OVERRIDE、NET_RAW 等 12 种不安全 capabilitiesCRITICAL、highRiskCapabilitiesRuleForDeployment禁止 NET_ADMIN、SYS_ADMIN、ALLDANGER主机命名空间高危hostPortRuleForDeploymentCRITICAL、hostPIDRuleForDeployment/hostNetworkRuleForDeployment/hostIPCRuleForDeployment均为CRITICAL。这套规则展示了一个重要设计同一资源类型可以在一个 InspectRule 中堆叠多条 OPA 子规则控制器会按类型合并后统一执行严重级别从 WARNING 到 CRITICAL 分层告警。PromQL 规则promQLPromQL 规则直接对 Prometheus 执行即时查询命中即产生告警spec: prometheus: endpoint: http://prometheus-k8s.monitoring.svc.cluster.local:9090 promQL: - name: NodeMemory desc: Node memory usage 30% rule: (1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100 30 rawDataEnabled: truespec.prometheus.endpointPrometheus 服务地址KubeSphere 监控栈内通常为http://prometheus-k8s.kubesphere-monitoring-system.svc.cluster.local:9090可选的basicToken/bearerToken用于访问受认证保护的 Prometheus见仓库示例中的注释spec.promQL[].rulePromQL 表达式返回非空结果即视为发现rawDataEnabled是否将原始指标数据一并写入结果。仓库的 kubeeye_promql_inspect.yaml 提供了 12 条生产级 PromQL 巡检规则覆盖磁盘空间NodeFilesystemSpaceFillingUp预测 24 小时内写满、NodeFilesystemAlmostOutOfSpace剩余不足 5%、inode 耗尽NodeFilesystemFilesFillingUp、时钟偏移NodeClockSkewDetected、Pod 崩溃循环KubePodCrashLooping、Pod 长期未就绪KubePodNotReady、命名空间配额将满KubeQuotaAlmostFull、CPU/内存超卖KubeCPUOvercommit/KubeMemoryOvercommit、K8s 组件版本不一致KubeVersionMismatch以及 API Server 客户端错误KubeClientErrors。这些规则大量使用predict_linear、max_over_time等 PromQL 函数是编写监控型巡检规则的极佳素材。文件变更检查规则fileChange对节点上的文件做完整性基线比对文件内容发生变化即告警常用于检测关键配置被篡改spec: fileChange: - name: kubelet-config path: /var/lib/kubelet/config.yaml level: warning仓库示例 kubeeye_filechange_inspect.yaml 正是监控 kubelet 核心配置文件/var/lib/kubelet/config.yaml。内核参数规则sysctl校验节点内核参数是否满足期望值格式为参数名 期望值spec: sysctl: - name: net.ipv4.ip_forward rule: net.ipv4.ip_forward 1 level: warning仓库的 kubeeye_sysctlrule_inspect.yaml 提供了 28 项 KubeSphere 环境推荐的内核参数基线覆盖网络转发net.ipv4.ip_forward、bridge-nf 系列、NodePort 端口保留net.ipv4.ip_local_reserved_ports 30000-32767、内存与文件系统vm.max_map_count 262144、vm.swappiness 0、vm.overcommit_memory 1、inotify 限额fs.inotify.max_user_instances/max_user_watches 524288、TCP 栈优化net.core.somaxconn、net.ipv4.tcp_max_syn_backlog等以及 ARP 防护rp_filter、arp_accept。直接导入即可获得一份完整的节点内核健康基线。systemd 服务规则systemd校验节点上 systemd 服务的运行状态格式为服务名 期望状态spec: systemd: - name: kubelet rule: kubelet active level: warning仓库示例 kubeeye_systemd_inspect.yaml 检查docker、etcd、kubelet三个关键服务必须处于active状态。节点信息规则nodeInfo基于节点指标做阈值判断支持的resourcesType有cpu、memory、filesystem、inode、load。spec: nodeInfo: - name: CpuUsage rule: cpu 20 resourcesType: cpu desc: CPU usage 20% level: warning仓库示例 kubeeye_nodeInfo_inspect.yaml 分别以 20% 为阈值检查 CPU、内存与文件系统使用率注意该示例未显式声明level将采用默认级别。文件内容过滤规则fileFilter按正则规则扫描指定文件内容匹配即产生告警用于在日志中检索错误特征spec: fileFilter: - name: systemLog path: /var/log/syslog rule: error level: warning仓库示例 kubeeye_filterrule_inspect.yaml 在/var/log/syslog中匹配error关键字。服务连通性规则serviceConnect验证工作空间下服务之间的网络连通性spec: serviceConnect: - workspace: system-workspace level: warning仓库示例 kubeeye_services_connect_inspect.yaml 对system-workspace内的服务执行连通性探测。自定义命令规则customCommand在节点上执行任意 Shell 命令并用正则匹配输出命中即告警spec: customCommand: - name: check-disk command: df -h / | tail -1 rule: .*5[0-9]% level: warning该示例检查根分区磁盘使用率是否达到 50% 以上rule为正则表达式。这正是运行时架构图中Cmd所指的规则类型适合 OPA/PromQL 无法覆盖的自定义巡检场景。组件排除componentExclude在spec.componentExclude中列出要跳过的组件格式命名空间/资源名避免误报或重复检查spec: componentExclude: - kube-system/kube-dnsInspectPlan 参数详解InspectPlan 定义巡检的执行策略核心参数如下参数类型说明schedulestringCron 表达式如*/30 * * * ?。移除该字段即为一次性巡检suspendbool暂停周期性巡检timeoutstring单次巡检超时时间默认10mruleNamesarrayInspectRule 名称列表。每条规则支持nodeName/nodeSelector限定目标节点maxTasksint最多保留的历史任务/结果数超出后清理旧结果oncetimestamp在指定时间执行一次性巡检clusterNamearray多集群巡检目标适用于 KubeSphere 多集群环境典型组合固定周期巡检 设置timeout防止 Job 卡死 通过maxTasks控制结果留存 通过ruleNames[].nodeSelector只巡检指定节点。若要临时停止周期性巡检但保留计划将suspend: true即可若需要现在立刻跑一次则删除schedule字段创建一次性计划。运维与通知日志查看与邮件告警查看组件日志kubectl logs -n extension-kubeeye -l control-planecontroller-manager --tail100 kubectl logs -n extension-kubeeye -l appkubeeye-apiserver --tail100controller-manager 日志用于排查巡检任务调度问题apiserver 日志用于排查报告下载与 API 访问问题。配置邮件通知KubeEye 支持将巡检结果通过邮件推送。首先创建存放邮箱凭据的 SecretapiVersion: v1 kind: Secret metadata: name: message-secret namespace: extension-kubeeye type: Opaque stringData: username: your-emailexample.com password: your-password然后更新 ConfigMapkubeeye-config开启邮件通知并配置 SMTPdata: config: |- job: autoDelTime: 30 backLimit: 5 image: kubespheredev/kubeeye-job:v1.0.6 imagePullPolicy: Always resources: limits: cpu: 2000m memory: 512Mi requests: cpu: 50m memory: 256Mi message: enable: true email: address: smtp.example.com port: 25 fo: senderexample.com to: - recipientexample.com secretKey: message-secret配置要点job段控制 kubeeye-job 的镜像与资源规格autoDelTime为结果自动清理天数、backLimit为 Job 失败重试上限生产环境可按集群规模调整 CPU/内存 requests/limitsmessage.enable总开关设为true开启通知emailaddress/port为 SMTP 服务器地址与端口fo为发件人to为收件人列表secretKey引用上述message-secret。卸载 KubeEye⚠卸载前务必与用户确认。先做存在性检查if ! kubectl get installplans.kubesphere.io kubeeye --ignore-not-found /dev/null; then echo KubeEye is not installed. exit 0 fi与用户确认后删除 InstallPlankubectl delete installplans.kubesphere.io kubeeye --ignore-not-found最后运行验证脚本确认清理完成./scripts/verify-uninstall.sh从 verify-uninstall.sh 源码看成功标准有两条InstallPlan 已删除extension-kubeeye命名空间下不再有 Pod 残留轮询最长 300 秒每 10 秒检查一次。排障指南组件 Pod 无法启动kubectl describe po -n extension-kubeeye重点关注镜像拉取失败、资源不足Pending、CrashLoopBackOff 等事件。巡检不执行kubectl get inspectplan kubectl get inspectrule kubectl describe inspectplan inspectplan依次确认InspectPlan 是否存在且未suspend、引用的 InspectRule 是否已创建、计划的schedule是否合法。注意generate-plan.sh生成的计划名默认为inspectplan。有任务但无结果kubectl get inspecttask kubectl get inspectresult kubectl get endpoints -n extension-kubeeye kubeeye-apiserver若 InspectTask 存在但 InspectResult 未生成问题多出在 kubeeye-job 执行阶段可结合 controller-manager 日志排查若结果已生成但下载失败检查 apiserver 的 Endpoints 是否有可用后端。结语把巡检变成集群的例行体检KubeEye 的价值在于把检查集群有没有问题从一次性人工操作转化为可声明、可调度、可追溯的持续机制用 InspectRule 沉淀巡检经验仓库 rules/ 下的 17 个示例规则覆盖 OPA、PromQL、Sysctl 等全部九类检查几乎可以开箱即用用 InspectPlan 定义巡检节奏用 InspectTask/InspectResult 追踪每次执行并产出 HTML / XLSX 报告再通过邮件把异常推送给人。配合generate-installplan.sh、generate-plan.sh、check-status.sh、verify-uninstall.sh四个脚本从安装、巡检、运维到卸载的全生命周期均可自动化闭环非常适合作为 KubeSphere 生产集群的常态化健康保障手段。【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考