OneUptime Kubernetes 监控完全指南集群健康、指标告警与预置模板实战【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime 的 Kubernetes 监控器通过 OpenTelemetryOTLP从集群摄取指标对节点、Pod、工作负载与控制平面组件进行健康与性能评估并在指标越界时自动触发告警与事件。本指南将带你走通安装 Kubernetes Agent → 创建监控器 → 配置资源范围与指标查询 → 设置告警条件 → 使用预置模板的完整链路并深入源码级细节指标目录、聚合语义、按序列分组告警让你能直接在生产集群上落地一套可运行的 Kubernetes 观测与告警方案。监控能力总览Kubernetes 监控器利用集群自身上报的指标为基础设施提供深度可观测性你可以据此实现监控集群Cluster、命名空间Namespace、工作负载Workload、节点Node与 Pod五个层级的健康状态追踪各资源维度的CPU、内存、磁盘与网络使用情况检测Pod 崩溃crash、重启restart与调度失败scheduling failure监控Deployment 副本可用性对控制平面问题etcd、API Server、Scheduler发出告警追踪资源的requests 与 limits配置及使用饱和度。这些能力由仓库中的一套完整实现支撑监控器配置模型定义于 MonitorStepKubernetesMonitor.ts可查询的指标清单定义于 KubernetesMetricCatalog.ts执行逻辑则位于 Workers 的 MonitorTelemetryMonitor.ts 中。前置条件安装 Kubernetes AgentKubernetes 监控器本身不发起任何探测它消费的是 OneUptime Kubernetes Agent 采集并上报的数据。因此在使用前必须先在目标集群安装 Agent。Agent 负责采集集群的指标metrics、事件events、Pod 日志pod logs默认还通过eBPF 捕获应用链路与 HTTP RED 指标并经由 OTLP 上报 OneUptime——这意味着无需为每个应用改动代码或接入 SDK即可看到服务级流量视图。此外CPU 持续火焰图eBPF profiler可作为可选项通过--set profiling.enabledtrue开启。快速安装命令Helm 单命令安装helm repo add oneuptime https://helm-chart.oneuptime.com helm repo update helm install oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent \ --create-namespace \ --set oneuptime.urlhttps://oneuptime.com \ --set oneuptime.apiKeyYOUR_API_KEY \ --set clusterNameA_UNIQUE_NAME_FOR_THIS_CLUSTER安装后几分钟内集群就会出现在 OneUptime 中。参数含义参数说明oneuptime.urlOneUptime 实例地址自托管为你的域名oneuptime.apiKey项目 API KeySettings API Keys 获取clusterName集群唯一名称将作为 OTel 资源属性k8s.cluster.name写入clusterName不只是标签。在数据库模型 KubernetesCluster.ts 中clusterIdentifier字段明确注释为 sourced from the k8s.cluster.name OTel resource attribute并作为该模型的唯一标识参与集群身份折叠——两个未设置 clusterName 的集群会被静默合并成一个资产因此该值必须唯一且稳定。按集群类型选择 preset不同 Kubernetes 发行版对hostPath卷挂载的限制不同。Helm Chart 用一个顶层选项preset屏蔽掉这些差异详见 kubernetes-agent/values.yamlpreset适用场景日志采集方式说明standard默认自建集群、EKS on EC2、GKE Standard、AKS、minikube、kind、k3sDaemonSet 通过 hostPath 读取/var/log/pods开销最低这些平台均允许 hostPathgke-autopilotGKE AutopilotKubernetes API tailerDeploymentAutopilot 禁用 hostPathchart 会套用通过其 Pod Security Standards 的加固安全上下文eks-fargateEKS FargateKubernetes API tailerDeployment同gke-autopilotFargate 同时限制 hostPath 与 DaemonSet不确定时保持preset不设置即可得到standard默认值。若安装因 Pod Security 策略报出hostPath相关错误切换为gke-autopilotEKS Fargate 用eks-fargate重新安装# GKE Autopilot helm install oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent --create-namespace \ --set oneuptime.urlhttps://oneuptime.com \ --set oneuptime.apiKeyYOUR_API_KEY \ --set clusterNameprod-gke-autopilot \ --set presetgke-autopilot另外Agent 支持按命名空间过滤namespaceFilters.rules含include/exclude动作与podLogs、ebpfDiscovery、metrics、traces四种作用域以及采集侧遥测过滤filters.logs等可在数据离开节点前就裁剪采集量。控制平面指标etcd、API Server、Scheduler需要额外开启controlPlane.enabled托管集群EKS/GKE/AKS通常不暴露这些端点——详见下文告警模板部分的说明。创建 Kubernetes 监控器在 OneUptime 面板中按以下步骤创建进入Monitors监控器页面点击Create Monitor创建监控器选择Kubernetes作为监控器类型选择要监控的集群与资源范围scope配置资源过滤器与指标查询按需配置监控条件criteria。创建出的监控器本质是一个MonitorStep对象其data.kubernetesMonitor字段保存全部 Kubernetes 配置见 KubernetesAlertTemplates.ts 中的buildKubernetesMonitorStep结构由MonitorStepKubernetesMonitor接口定义clusterIdentifier、resourceScope、resourceFilters、metricViewConfig查询 公式与rollingTime。配置选项详解集群Cluster选择要监控的 Kubernetes 集群。集群必须通过 OpenTelemetry 与 OneUptime 完成集成即安装 Agent。集群记录由 KubernetesCluster.ts 建模关键字段包括clusterIdentifier来自k8s.cluster.name、providerEKS/GKE/AKS/self-managed、otelCollectorStatusAgent 连接状态默认disconnected、nodeCount/podCount/namespaceCount以及lastSeenAt最近一次收到指标的时间。Agent 首次上报时集群会被自动发现也可手动登记。资源范围Resource Scope选择监控的粒度层级范围说明Cluster监控整个集群Namespace监控指定命名空间内的资源Workload监控指定的 deployment、statefulset、daemonset、job 或 cronjobNode监控指定集群节点Pod监控指定 Pod在源码中该枚举定义于 MonitorStepKubernetesMonitor.tsKubernetesResourceScope同时也是 KubernetesMetricCatalog.ts 中每条指标defaultResourceScope的取值依据——选择指标时 UI 会结合默认范围给出合理提示。资源过滤器Resource Filters在选定范围内进一步收窄监控对象过滤器说明适用范围NamespaceKubernetes 命名空间Namespace、Workload、PodWorkload Typedeployment、statefulset、daemonset、job、cronjobWorkloadWorkload Name工作负载名称WorkloadNode Name节点名称NodePod NamePod 名称Pod对应数据结构为KubernetesResourceFiltersnamespace、workloadType、workloadName、nodeName、podName这些过滤器会被 Worker 端拼进 ClickHouse 查询谓词。指标查询与公式配置一条或多条待评估的指标查询。每条查询包含Metric name指标名——要查询的 Kubernetes 指标Aggregation聚合方式——窗口内如何聚合指标值Filters过滤器——基于属性attributes的附加过滤。此外还可以创建公式formulas用数学表达式组合多条指标查询。公式在metricViewConfig.formulaConfigs中定义例如比率监控器(numerator / denominator) * 100就是通过公式实现的见 KubernetesAlertTemplates.ts 的buildKubernetesRatioMonitorConfig默认公式为(${numeratorAlias} / ${denominatorAlias}) * 100。高级用法包括自定义公式节点磁盘使用率模板使用(used_disk / (used_disk avail_disk)) * 100与df命令报告的 Use% 一致。滚动时间窗口Rolling Time Window选择指标评估的时间窗口可选值Past 1 MinutePast 5 MinutesPast 10 MinutesPast 15 MinutesPast 30 MinutesPast 60 Minutes在 Worker 端窗口决定了查询的数据范围rollingTime字段默认Past1Minute在告警条件端配合持续命中All Values聚合时窗口本身就成了故障持续多久才告警的旋钮——例如 Deployment 副本不匹配模板特意使用 15 分钟窗口以避开正常滚动更新期间的瞬时副本缺口。常用 Kubernetes 指标目录以下是 OneUptime 内置指标目录KubernetesMetricCatalog.ts中按类别组织的核心指标。每条指标在源码中均带有metricName实际 OTel 指标名、默认聚合方式、默认资源范围与单位下表一并给出便于配置时参考。Pod 指标指标说明指标名源码默认聚合Pod CPU UsagePod 的 CPU 消耗k8s.pod.cpu.utilizationAveragePod Memory UsagePod 的内存消耗字节k8s.pod.memory.usageAveragePod Filesystem UsagePod 的磁盘使用字节k8s.pod.filesystem.usageAveragePod Network Receive/Transmit网络流量累计计数器双向k8s.pod.network.ioMaximumPod PhasePod 当前阶段Running、Pending、Failed 等k8s.pod.phaseMaximum需要特别注意的是Pod CPU Usage 的单位源码描述明确指出k8s.pod.cpu.utilization是cores 单位0.18 表示 0.18 个核而非 18%要用百分比需除以容器 CPU limitk8s.container.cpu_limit或节点可分配 CPUk8s.node.allocatable_cpu。Pod Phase是分类值而非数量k8s.pod.phase以数字编码1Pending2Running3Succeeded4Failed5Unknown绝不能求和gauge 每次抓取都会重新上报Sum 会得到 pods×scrapes应使用 Max 捕获最差相位或用 Min 配合 等于 1 捕获卡在 Pending 的 Pod。Node 指标指标说明指标名源码默认聚合Node CPU Usage节点 CPU 利用率k8s.node.cpu.utilizationAverageNode Memory Usage节点内存使用字节k8s.node.memory.usageAverageNode Filesystem Usage节点磁盘使用字节k8s.node.filesystem.usageAverageNode Disk I/O读写操作由文件系统指标派生—Node Ready Condition节点是否就绪k8s.node.condition_readyMinimumk8s.node.cpu.utilization同样是 cores 单位1.4 表示 1.4 核k8s.node.condition_ready取值 1就绪/ 0未就绪模板中使用 Min 聚合后与坏值做相等比较——这是源码注释明确推荐的Min 相等比较惯用法。此外目录中还有k8s.node.filesystem.available剩余字节下降才危险应使用 less than 阈值告警。Container 指标指标说明指标名源码默认聚合Container Restarts容器重启次数k8s.container.restartsMaximumContainer CPU/Memory Limits资源上限k8s.container.cpu_limit/k8s.container.memory_limitAverageContainer CPU/Memory Requests资源请求k8s.container.cpu_request/k8s.container.memory_requestAverageContainer Ready Status容器是否就绪k8s.container.readyMinimumWorkload 指标指标说明指标名源码默认聚合Deployment Available/Unavailable Replicas副本计数k8s.deployment.available_replicas/k8s.deployment.unavailable_replicasMin / MaxDaemonSet Misscheduled Nodes调度问题在不应运行的节点上运行k8s.daemonset.misscheduled_nodesMaximumStatefulSet Ready Replicas就绪副本计数k8s.statefulset.ready_replicasMinimumJob Active/Failed/Succeeded PodsJob 状态k8s.job.failed_pods/k8s.job.successful_pods等Maximum除文档列出的四类外指标目录还包含HPA 指标k8s.hpa.current_replicas、desired_replicas、max_replicas、min_replicas用于构建HPA 触及上限类告警以及 kubeletstats 直接上报的limit 饱和度指标k8s.pod.memory_limit_utilization、k8s.pod.cpu_limit_utilization默认开启见 configmap-daemonset.yaml 中kubeletstats.utilizationMetrics.enabled它们按Pod 使用量 ÷ 该 Pod 所有容器 limit 之和计算天然正确处理带 sidecar 的多容器 Pod。监控条件Criteria可用检查类型检查类型说明Metric Value评估配置的指标查询或公式的计算值聚合类型聚合说明Average时间窗口内的平均值Sum所有值求和Maximum Value窗口内最高值Minimum Value窗口内最低值All Values所有样本都必须匹配条件持续命中Any Value至少一个样本匹配即可聚合类型的选择直接影响告警语义例如k8s.pod.phase这类每次抓取重发的 gauge 必须用 Min/Max 而非 SumDeployment 副本缺口用 Max 取最坏一分钟跨接收器的比率指标用 Avg 才能在两个接收器抓取周期不一致时保持正确详见 KubernetesAlertTemplates.ts 中buildKubernetesRatioMonitorConfig的大段注释。过滤类型Greater Than、Less Than、Greater Than or Equal To、Less Than or Equal To、Equal To基线异常检测Anomaly Detection除了阈值比较还可以使用无阈值的基线异常检测表单会显示Sensitivity灵敏度与Baseline Window基线窗口两个参数将每个样本与上周同时段的基线进行比较异常偏高Anomalously High——值高于预期范围异常偏低Anomalously Low——值低于预期范围异常Anomalous——值朝任意方向偏离预期范围。需要留意的是在积累满配置的基线窗口历史数据之前异常条件不会产生告警监控器会处于Learning学习状态。预置告警模板OneUptime 为常见 Kubernetes 监控场景提供了开箱即用的告警模板选择后即自动生成对应的监控步骤与条件含健康/不健康条件、事件标题与描述。文档列出的 12 个模板如下模板说明阈值CrashLoopBackOff Detection容器重启计数 5 restartsPod Stuck in PendingPending 阶段 Pod 0 podsNode Not Ready节点就绪条件 0 (not ready)High Node CPU节点 CPU 利用率 90%High Node Memory节点内存利用率 85%Deployment Replica Mismatch副本不可用 0 replicasJob FailuresJob 中失败 Pod 0 failuresetcd No Leaderetcd 集群缺少 leader 0 (no leader)API Server Throttling丢弃的 API 请求 0 requestsScheduler BacklogScheduler 中待调度 Pod 0 podsHigh Node Disk Usage节点文件系统使用率 90%DaemonSet Unavailable错误调度的节点数 0 nodes源码中实际注册了17 个模板KubernetesAlertTemplates.ts 的getAllKubernetesAlertTemplates在文档表格之外还有 5 个进阶模板且部分模板的实现细节与表格中的简单描述差异较大值得展开Node Not Ready、High Node CPU/Memory/Disk、Deployment Replica Mismatch、Job Failures、DaemonSet Unavailable均为**按对象分组group by**的监控器例如 Node Not Ready 按resource.k8s.node.name分组一个不健康节点产生一条独立事件而不是整个集群合并成一条否则第二个故障节点会被第一条事件的去重吞掉。分组键使用 ClickHouse 中带resource.前缀的属性名resource.k8s.node.name而非k8s.node.name因为 OTel 资源属性在入库时被统一加了该前缀见 MonitorTelemetryMonitor.ts 的查询构建逻辑与模板源码注释。High Node CPU / Memory实际是比率监控器k8s.node.cpu.usage ÷ k8s.node.allocatable_cpu × 100两者均为 cores/bytes才是真正的百分比而非直接比较k8s.node.cpu.utilization——因为后者是名字带 utilization 的 cores gauge。API Server Throttling实际监控apiserver_current_inflight_requests并发在途请求 gauge按request_kind分系列阈值 200而非表格中的 0 requests200 恰好是 API Server--max-mutating-requests-inflight的默认上限gauge 饱和在限制处而不会超过因此用才能命中。需要开启controlPlane.enabled并把controlPlane.apiServer.endpoints指向 collector 实际可达的 API Server 地址chart 默认的 localhost:6443 是 collector 自身的回环地址什么都抓不到。etcd No Leader、Scheduler Backlog同样需要controlPlane.enabled且托管集群EKS/GKE/AKS不暴露这些 metrics 端点在这些集群上此类监控器永远不会收到数据点源码描述中已明确提示。源码新增的 5 个模板覆盖自动伸缩器背后的资源不足链路HPA Saturated at Max Replicascurrent_replicas ÷ max_replicas × 100 90Critical、Pod Memory Saturating Container Limit与Pod CPU Saturating Container Limit读 kubeletstats 自带的k8s.pod.*_limit_utilization 90%以及High Node CPU/Memory Request Commitment节点上容器 requests 之和 ÷ allocatable 90%。这些模板由 KubernetesAlertTemplates.ts 的buildKubernetesMonitorConfig/buildKubernetesRatioMonitorConfig生成并被Common/Tests/Types/Monitor/KubernetesAlertTemplates.test.ts等测试覆盖验证。底层执行原理Kubernetes 监控器的评估不依赖外部探针而是由 Worker 定时查询 ClickHouse 中已入库的 OTel 指标完成。核心入口是 MonitorTelemetryMonitor.ts 中的monitorKubernetes函数第 1497 行起读取监控步骤的kubernetesMonitor配置滚动窗口、查询配置、集群标识符、资源过滤器按clusterIdentifier与resourceFilters拼装 ClickHouse 查询谓词对每条queryConfigs执行指标查询并用formulaConfigs计算公式结果若配置了groupByAttributeKeys则按序列per-series分组评估——每个分组如每个 Pod、每个节点独立判断条件、独立产生事件collectPerSeriesMatches这正是200 个 Pod 的集群里每个不健康 Pod 各产生一条事件的机制。一个值得注意的工程细节buildKubernetesRatioMonitorConfig中两路查询通过序列指纹fingerprint连接因此只有两侧都确定携带的属性才能作为分组键——例如k8s.node.name在 k8s_cluster 侧只能靠 best-effort 的k8sattributesprocessor 补充在跨接收器比率中作为分组键可能导致查询永远连接不上、监控器静默停止告警。配置自定义比率监控器时应严格遵循此约束。实践建议小结务必设置唯一的clusterName它是集群身份k8s.cluster.name的组成部分缺失会导致多集群数据合并区分cores 指标与百分比指标k8s.pod.cpu.utilization等是 cores 计数做百分比告警请使用usage ÷ allocatable型比率模板对k8s.pod.phase、k8s.node.condition_ready等分类 gauge 使用 Min/Max 聚合绝不求和对 Pod/Node/Workload 级指标按对象分组group by让每个故障对象拥有独立事件避免去重掩盖多故障场景控制平面模板etcd、API Server、Scheduler仅在自建集群且开启controlPlane.enabled时可用使用基线异常检测时请耐心等待**基线窗口积累完成后Learning 状态结束**再评估告警是否合理。相关深入阅读Agent 完整安装与高级配置见 kubernetes-agent 文档Helm 全部可调参数见 kubernetes-agent/values.yaml集群数据模型见 KubernetesCluster.ts指标目录与告警模板源码见 KubernetesMetricCatalog.ts 与 KubernetesAlertTemplates.ts。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考