Telegraf Kubernetes Input Plugin 完整指南基于 Kubelet API 采集 Pod 与容器指标【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf本指南以 plugins/inputs/kubernetes/README.md 为核心系统讲解 Telegraf 的 Kubernetes 输入插件它如何通过 Kubelet API 采集节点、Pod、容器、卷与网络的资源指标如何以 DaemonSet 形式部署在每个节点上以及如何配置认证、标签过滤、TLS 与两种运行模式单节点直连与集群发现。读完本文你将能独立完成该插件的配置、部署含 RBAC 权限规划与高基数指标治理并理解其底层数据流与源码实现。该插件自 Telegraf v1.1.0 起可用仓库元数据标注⭐ v1.1.0、️ containers、 支持所有平台通过 plugins/inputs/all 注册为inputs.kubernetes。插件定位与工作前提Kubernetes 输入插件用于采集某个 Kubernetes 实例中正在运行的 Pod 与容器的指标数据来源是每个节点上的Kubelet API而不是 Kubernetes API Server 的聚合监控端点。在部署上有两个硬性前提该插件必须作为DaemonSet的一部分在 Kubernetes 集群内运行Telegraf 必须运行在集群中的每一个节点上。因此配置时应当让插件只与本机localhost运行的 Kubelet 通信而不是跨节点访问。从源码看插件在Gather阶段会根据url是否为空切换两种采集模式见 kubernetes.gourl非空直接对指定地址发起采集单节点模式url为空调用getNodeURLs通过集群内配置发现全部节点然后并发sync.WaitGroup goroutine对每个节点的 Kubelet 发起采集集群模式。两种模式最终都会调用gatherSummary向 Kubelet 请求/stats/summary与/pods两个端点kubernetes.go。[!CRITICAL] 该插件会产出高基数high cardinality数据若不加控制会给数据库带来高负载。请务必通过 metric filtering 过滤产出的指标或配置数据库以避免基数爆炸。配置详解完整配置示例与插件内置的 sample.conf 完全一致# Read metrics from the kubernetes kubelet api [[inputs.kubernetes]] ## URL for the kubelet, if empty read metrics from all nodes in the cluster url http://127.0.0.1:10255 ## Use bearer token for authorization. # bearer_token /var/run/secrets/kubernetes.io/serviceaccount/token ## Kubernetes Node Metric Name ## The default Kubernetes node metric name (kubernetes_node) is the same ## for the kubernetes and kube_inventory plugins. To avoid conflicts, set this ## option to a different value. # node_metric_name kubernetes_node ## Pod labels to be added as tags. An empty array for both include and ## exclude will include all labels. # label_include [] # label_exclude [*] ## Set response_timeout (default 5 seconds) # response_timeout 5s ## Optional TLS Config # tls_ca /path/to/cafile # tls_cert /path/to/certfile # tls_key /path/to/keyfile ## Use TLS but skip chain host verification # insecure_skip_verify false各配置项的作用与源码依据如下配置结构定义见 kubernetes.go配置项类型默认行为说明urlstring空Kubelet 的访问地址。留空表示通过 Kubernetes API 发现集群中所有节点并对每个节点 10250 端口发起 HTTPS 采集显式设置如http://127.0.0.1:10255则只与本机 Kubelet 通信bearer_tokenstring默认使用/var/run/secrets/kubernetes.io/serviceaccount/token用于授权的 Bearer Token 文件路径。Init阶段若未显式设置会填充该默认 ServiceAccount 路径kubernetes.gonode_metric_namestringkubernetes_node节点指标的名称。默认名称与kube_inventory插件相同两者同时启用时会产生指标冲突应改为不同值。源码中buildNodeMetrics使用该名称作为 measurementkubernetes.golabel_include[]string空需要转为标签tag的 Pod labels 白名单。与label_exclude均为空数组时包含全部 labelslabel_exclude[]string[*]排除为标签的 Pod labels 黑名单。插件默认值即为[*]即默认不导入任何 Pod labelkubernetes.goresponse_timeoutduration5 秒请求 Kubelet 的超时时间。源码中当未设置或小于 1 秒时自动回退到 5 秒kubernetes.gotls_ca/tls_cert/tls_keystring—可选 TLS 配置用于与启用 HTTPS 的 Kubelet如 10250 端口建立双向/单向 TLS 连接insecure_skip_verifyboolfalse跳过证书链与主机名校验。注意当url留空集群模式时Init会强制将其置为truekubernetes.go因为集群模式下是逐个发现节点地址动态发起 HTTPS 请求全局配置选项所有插件都支持额外的全局与插件级配置用于修改指标、标签和字段、创建别名、调整插件执行顺序等详见 docs/CONFIGURATION.md#plugins。获取宿主机 IPHost IPKubelet 默认地址是本机但在 DaemonSet 环境下有时需要宿主机Node的 IP。可以借助 KubernetesDownward API配合如下命令获取curl -s $API_URL/api/v1/namespaces/$POD_NAMESPACE/pods/$HOSTNAME \ --header Authorization: Bearer $TOKEN \ --insecure | jq -r .status.hostIP说明$POD_NAMESPACE通过 Downward API 注入到环境变量$HOSTNAME即 Pod 主机名由 Kubernetes API 设置为节点名$TOKEN为访问 Kubernetes API 所需的 Bearer Token请求结果中.status.hostIP即为当前 Pod 所在宿主机的 IP可据此推导本机 Kubelet 地址。完整的 Bearer Token 生成方式可参考 Kubernetes 官方文档中不借助kubectl proxy访问集群 API的章节。以 DaemonSet 部署作为 DaemonSet 部署时Telegraf 会确保集群每个节点恰好运行一个副本这正是该插件的运行前提。社区常见的做法是参考 Monitoring Kubernetes Architecture 一文中关于 InfluxData 监控 Kubernetes 的架构设计并可以直接使用 Telegraf、InfluxDB、Chronograf、Kapacitor 等对应的 Helm Chart 快速搭建一整套监控栈Telegraf DaemonSet 时序存储 可视化 告警。RBAC 权限规划RBAC 需求完全取决于url是否设置这一点在 kubernetes.go 的getNodeURLs中有直接体现集群模式url留空插件通过rest.InClusterConfig()读取集群内配置实例化 Kubernetes 客户端后执行Nodes().List()发现全部节点再为每个节点拼接https://node-address:10250作为采集地址。因此需要具备以下权限的ClusterRoleapiGroupscoreresourcesnodesverbslist、get同时需要创建对应的 ClusterRoleBinding 将该角色绑定到 Telegraf 的 ServiceAccount。Kubernetes RBAC 对象的创建方法参见 Kubernetes 官方 RBAC 文档。另外两个实现细节值得注意节点地址选取上getNodeAddress优先使用InternalIP仅在不存在内网地址时才回退到第一个外部地址kubernetes.go若某节点无法解析出地址插件会记录一条Unable to node addresses for Node ...的警告并跳过该节点。单节点模式url显式设置例如url http://127.0.0.1:10255插件只与本机 Kubelet API 通信不使用 Kubernetes API Server因此不需要任何 Kubernetes RBAC 权限。指标清单插件从 Kubelet 的/stats/summary聚合摘要数据中解析出四类用户指标外加从/pods端点补充的 Pod 元数据labels、容器镜像最终产出以下 measurement字段映射逻辑见 kubernetes_metrics.go 与 kubernetes.go。kubernetes_node节点级资源使用指标。tagsnode_namefieldscpu_usage_nanocorescpu_usage_core_nanosecondsmemory_available_bytesmemory_usage_bytesmemory_working_set_bytesmemory_rss_bytesmemory_page_faultsmemory_major_page_faultsnetwork_rx_bytesnetwork_rx_errorsnetwork_tx_bytesnetwork_tx_errorsfs_available_bytesfs_capacity_bytesfs_used_bytesruntime_image_fs_available_bytesruntime_image_fs_capacity_bytesruntime_image_fs_used_bytes该指标名称默认与kube_inventory插件输出的kubernetes_node冲突见 kube_inventory.go 的nodeMeasurement常量两者同时采集时务必通过node_metric_name区分。kubernetes_pod_container容器级资源使用指标包含根文件系统与日志文件系统占用。tagscontainer_namenamespacenode_namepod_name以及image、version从容器镜像名中解析和经过过滤的 Pod labelsfieldscpu_usage_nanocorescpu_usage_core_nanosecondsmemory_usage_bytesmemory_working_set_bytesmemory_rss_bytesmemory_page_faultsmemory_major_page_faultsrootfs_available_bytesrootfs_capacity_bytesrootfs_used_byteslogsfs_available_byteslogsfs_capacity_byteslogsfs_used_bytes实现细节buildPodMetrics会先把/pods返回的 Pod 信息与/stats/summary的 Pod 按metadata.namemetadata.namespace关联从而获得每个容器的镜像名并拆出image与version两个 tag例如镜像myapp:1.2.3会得到version1.2.3然后通过labelFilter把允许的 Pod labels 附加为 tagskubernetes.go。kubernetes_pod_volumePod 卷的磁盘占用。tagsvolume_namenamespacenode_namepod_namefieldsavailable_bytescapacity_bytesused_byteskubernetes_pod_networkPod 网络收发统计。tagsnamespacenode_namepod_namefieldsrx_bytesrx_errorstx_bytestx_errors附kubernetes_system_containerREADME 的示例输出中还出现了kubernetes_system_container系统容器如kubelet、bar等。虽然它不在 README 的正式指标清单中但源码中的buildSystemContainerMetrics会为summaryMetrics.Node.SystemContainers中的每个系统容器输出该 measurement包含cpu_usage_nanocores、cpu_usage_core_nanoseconds、memory_usage_bytes、memory_working_set_bytes、memory_rss_bytes、memory_page_faults、memory_major_page_faults、rootfs_*、logsfs_*等字段tags 为node_name与container_namekubernetes.go。数据采集流程与底层实现结合源码一次完整的采集周期如下Gather判断url非空则直接采集为空则通过InClusterConfigNodes().List()发现节点并并发采集kubernetes.go。对每个目标节点调用gatherSummary请求GET baseURL/stats/summary解析为summaryMetrics结构节点 CPU/内存/网络/文件系统/运行时镜像文件系统 Pod 列表请求GET baseURL/pods解析为 Pod 元数据labels、容器镜像列表依次调用buildSystemContainerMetrics、buildNodeMetrics、buildPodMetrics生成指标kubernetes.go。HTTP 请求细节loadJSON每次请求读取bearer_token指向的文件内容去空格后放入Authorization: Bearer token请求头携带Accept: application/json响应状态非 200 时报错响应体通过 JSON 解码到对应结构体kubernetes.go。测试用例 kubernetes_test.go 使用httptest模拟 Kubelet 的/stats/summary与/pods端点验证了kubernetes_system_container、kubernetes_node、kubernetes_pod_container含运行中与已停止 Pod、kubernetes_pod_volume、kubernetes_pod_network五类指标及其 tag/field 的准确性同时也验证了label_include对 Pod labels 的过滤效果例如测试中将excludelabel 排除在外。高基数治理建议由于容器名、Pod 名、命名空间、卷名、镜像版本以及导入的 Pod labels 都会成为 tag一个规模稍大的集群就会产生海量时间序列。结合 docs/CONFIGURATION.md#metric-filtering 中的过滤机制建议用label_include/label_exclude严格控制导入的 Pod labels默认的label_exclude [*]已是最安全的起点在插件上使用tagdrop/tagpass按namespace、node_name等维度收敛指标集用namepass/namedrop只保留真正需要的 measurement如仅保留kubernetes_node与kubernetes_pod_container关注高变化的 tag 值如不断重建的 Pod 名、滚动更新的镜像版本必要时在写入数据库前进行聚合降采样。示例输出以下是 README 给出的真实输出样例行内时间戳为纳秒kubernetes_node kubernetes_pod_container,container_namedeis-controller,namespacedeis,node_nameip-10-0-0-0.ec2.internal,pod_namedeis-controller-3058870187-xazsr cpu_usage_core_nanoseconds2432835i,cpu_usage_nanocores0i,logsfs_available_bytes121128271872i,logsfs_capacity_bytes153567944704i,logsfs_used_bytes20787200i,memory_major_page_faults0i,memory_page_faults175i,memory_rss_bytes0i,memory_usage_bytes0i,memory_working_set_bytes0i,rootfs_available_bytes121128271872i,rootfs_capacity_bytes153567944704i,rootfs_used_bytes1110016i 1476477530000000000 kubernetes_pod_network,namespacedeis,node_nameip-10-0-0-0.ec2.internal,pod_namedeis-controller-3058870187-xazsr rx_bytes120671099i,rx_errors0i,tx_bytes102451983i,tx_errors0i 1476477530000000000 kubernetes_pod_volume,volume_namedefault-token-f7wts,namespacedefault,node_nameip-172-17-0-1.internal,pod_namestorage-7 available_bytes8415240192i,capacity_bytes8415252480i,used_bytes12288i 1546910783000000000 kubernetes_system_container参考文件插件文档plugins/inputs/kubernetes/README.md插件入口与采集逻辑plugins/inputs/kubernetes/kubernetes.gosummary/pod 响应结构定义plugins/inputs/kubernetes/kubernetes_metrics.go、plugins/inputs/kubernetes/kubernetes_pods.go内置配置示例plugins/inputs/kubernetes/sample.conf测试用例含模拟 Kubelet 响应plugins/inputs/kubernetes/kubernetes_test.go指标过滤说明docs/CONFIGURATION.md#metric-filtering插件注册目录plugins/inputs/all【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
