标签: Kubernetes

  • 深入 Prometheus OOM 雪崩排查:动态 Label 滥用引发的高基数风暴与 TSDB WAL 夯死实战

    某次生产核心监控集群突然全线熔断,Prometheus 节点 Load Average 飙升至 100+,Pod 陷入持续的 OOMKilled 死亡循环。排查确认,业务研发在一项 HTTP 统计指标中错误注入了 trace_iduser_id 作为 Label,导致时间序列(Time Series)基数瞬间暴增千万级别。最终通过介入 metric_relabel_configs 强制丢弃高基数 Label,并物理清理内存映射的 Head 块与臃肿的 WAL(Write-Ahead Log)才得以恢复。

    结论先放在这里:监控指标(Metrics)绝对不是日志(Logs),把无边界的动态变量作为 Label 写入 Prometheus,是对 TSDB 存储引擎最无知的谋杀。

    案发现场:失控的 OOM 与堵死的 IO

    排查过程中,告警通道首先报出 Prometheus target 掉线,紧接着是 Kubernetes 节点资源耗尽告警。登录宿主机,dmesg 日志非常直白:

    [52143.123456] prometheus invoked oom-killer: gfp_mask=0x100cca(GFP_HIGHUSER_MOVABLE), order=0, oom_score_adj=-998
    [52143.123458] Memory cgroup out of memory: Killed process 10245 (prometheus) total-vm:42949672960kB, anon-rss:34359738368kB, file-rss:0kB, shmem-rss:0kB
    

    32GB 内存的 Pod 被硬生生撑爆。由于 Pod 重启策略为 Always,Prometheus 尝试重新启动,但在恢复 WAL 阶段再次卡死,磁盘 IOPS 被打满,日志停留在:

    level=info ts=... caller=head.go:760 component=tsdb msg="Replaying WAL, this may take a while"
    level=info ts=... caller=head.go:812 component=tsdb msg="WAL segment loaded" segment=1023 maxSegment=1045
    

    重放速度极慢,且内存水位在重放过程中成级数增长,最终在启动完成前再次 OOM。这属于典型的高基数(High Cardinality)雪崩

    罪魁祸首:TSDB 的倒排索引与高基数之殇

    在处理这种无法启动的僵尸实例时,直接查 PromQL 是行不通的。直接把挂载的 PV 临时挂给一个 Debug 容器,掏出 promtool 对 TSDB 数据目录进行离线分析:

    promtool tsdb analyze /prometheus/data/
    

    输出结果直接锁定了元凶:

    Block ID: ...
    ...
    Label names with highest number of values:
    1. trace_id: 12045678
    2. user_id: 8543210
    ...
    Metrics with highest number of series:
    1. http_requests_total: 12045678
    

    一个原本只有几十个 endpoint 和 method 组合的 http_requests_total 指标,因为加上了 trace_id,硬生生裂变出了 1200 万个时间序列。

    为什么加个 Label 能把 32G 内存干爆?这要从 Prometheus TSDB 的底层机制说起:

    Prometheus TSDB 的设计前提是 Label 的组合是有限且收敛的。当前正在写入的数据存放在内存中的 Head Block,Head Block 默认保留最多 3 小时的数据。为了实现快速的多维查询,TSDB 维护了倒排索引(Inverted Index)。 每一条唯一的 Label 组合(例如 http_requests_total{method="GET", trace_id="abc"})都会被当作一个全新的 Series。

    1. 内存放大:在 Head 块中,每个活跃的 Series 都会占用几百字节到几 KB 不等的内存(包括结构体、索引缓存、Chunk 引用等)。一千万个 Series,光是基础的结构体开销就能轻易吃掉十几 GB 内存。

    2. WAL 风暴:每次出现一个新的 Series,TSDB 必须在 WAL 中写入一条 Series Record 以保证宕机不丢失。高基数意味着海量的新 Series 不断产生,WAL 写入量呈指数级上升,直接将磁盘 IO 打到饱和。

    3. Compaction 瘫痪:当 Head 块数据落盘生成持久化 Block 时,后台的 Compaction 机制需要对成千万的 Series 进行合并和索引重构,这会耗尽 CPU,并导致 Compaction 积压。

    业务将 trace_id 塞进 Label,等于把 O(N) 复杂度的存储系统当成了 O(1) 的 Key-Value 库在用。

    止血与修复实战

    既然抓到了凶手,修复逻辑就是:阻断毒流量输入,清理已中毒的数据。

    第一步:通过 relabel 丢弃高基数 Label 在不改动业务代码(或业务还没来得及回滚)的情况下,运维必须在 Prometheus 抓取阶段直接阉割掉这个恶意的 Label。在 prometheus.yml 中修改对应 Job 的配置:

    scrape_configs:
      - job_name: 'business_app'
        # 注意:必须使用 metric_relabel_configs,这作用于抓取后、落盘前的阶段
        metric_relabel_configs:
          - source_labels: [trace_id]
            regex: '.*'
            action: labeldrop
          - source_labels: [user_id]
            regex: '.*'
            action: labeldrop
    

    注:如果是客户端直接暴露了几千万行的 /metrics,那应用本身大概率也会因为构建 metrics 字符串而 OOM。此时需要业务立即回滚。

    第二步:处理无法启动的 TSDB 此时由于旧的脏数据还卡在 WAL 里,Prometheus 依然起不来。最粗暴有效的方法是放弃最近几小时的 Head 块数据(监控容忍短暂的断点,但不容忍系统不可用)。

    进入数据目录,直接清理 WAL 和 chunk_head:

    cd /prometheus/data/
    # 备份后删除(如果在乎现场的话)
    rm -rf wal/*
    rm -rf chunks_head/*
    

    清理后拉起 Prometheus,内存占用瞬间回落到正常的几 GB 水平,Load Average 恢复正常,集群起死回生。

    排查清单与同类问题速查

    1. 内存/OOM 快速定位
    2. 永远不要猜测,直接用 promtool tsdb analyze 分析本地数据块,查看 Metrics with highest number of series 排名。

    3. 区分 Relabel 阶段

    4. relabel_configs:作用于 Target 发现阶段,用于过滤抓取目标(改 IP、改端口、丢弃整个 Endpoint)。
    5. metric_relabel_configs:作用于抓取后、写入 TSDB 前,用于修改或过滤具体的 Metrics 和 Label(丢弃高基数 Label 必用)。

    6. 监控自身的监控

    7. 必须为 Prometheus 配置 prometheus_tsdb_head_seriesprometheus_target_scrapes_exceeded_sample_limit_total 的告警。当 Head 序列数突增时,能在 OOM 发生前拦截。

    8. 高基数需求替代方案

    9. 业务确实需要通过 Metrics 关联 TraceID 怎么办?使用 OpenMetrics 标准的 Exemplars。Exemplars 附着在具体的观测值上,不会被纳入倒排索引,不影响基数,完美解决 Metrics 到 Trace 的联动诉求。

    10. 防御性配置限制

    11. scrape_configs 中强制加上 sample_limitlabel_limitlabel_value_length_limit。宁可让超过阈值的抓取失败(报错 sample limit exceeded),也绝不让垃圾数据撑爆整个集群。
  • 深入 K8S CSI 挂载雪崩排查:Node 假死引发的 Multi-Attach 锁死与 VolumeAttachment 强制清理实战

    Node 假死时,StatefulSet 发生驱逐漂移,但底层块存储因旧节点未释放导致新节点挂载失败,陷入持续的 Multi-Attach error 死锁。本文直接给出破局方案:通过清理 VolumeAttachment 僵尸对象强制解除挂载锁,并基于 K8s 1.26+ 的 out-of-service 污点实现 Non-Graceful Node Shutdown 自愈,同时剖析 CSI external-attacher 的防脑裂流转机制。

    故障现场:Pod 永远停留在 ContainerCreating

    某次处理基础架构告警,某可用区交换机故障导致部分 K8s Worker 节点失联(状态变为 NotReady)。按照系统默认配置,大约 5 分钟后(pod-eviction-timeout),运行在故障节点上的 StatefulSet 实例被驱逐并在健康的 Node 上重新调度。

    但是,新创建的 Pod 一直卡在 ContainerCreating,通过 kubectl describe pod 查看 Events,满屏全是同一种报错:

    Warning  FailedAttachVolume  2m45s (x12 over 15m)  attachdetach-controller
    Multi-Attach error for volume "pvc-c93a8...": Volume is already exclusively attached to one node and can't be attached to another
    

    同时,底层存储 CSI Driver(以 Ceph RBD 为例,AWS EBS/阿里云云盘同理)的日志中疯狂输出:

    rpc error: code = FailedPrecondition desc = volume is published to another node
    

    很明显,新节点无法将云盘 attach 过来,因为 K8s 认为这块盘还挂载在那个“已经死掉”的旧节点上。

    为什么 CSI 驱动不会自动强制 Detach 假死节点的 Volume?

    这是排查此类问题时最常产生的疑问:既然节点已经 NotReady 且 Pod 被驱逐了,为什么 K8s 负责管理挂载的 AttachDetachController (ADC) 不直接把旧节点上的盘强制卸载(Force Detach)?

    答案是:为了绝对的数据安全(防脑裂)。

    在块存储(ReadWriteOnce 模式,通常格式化为 ext4/xfs)的场景下,如果旧节点只是网络断开(假死),而 CPU、内存和磁盘 IO 还在正常运行。如果此时 K8s 强制在 IaaS 层将这块云盘摘除并挂载给新节点,新节点的 Pod 开始写入数据,一旦旧节点网络恢复,其内核缓存中未刷盘的脏数据(Dirty Pages)会继续向磁盘 flush,立刻导致文件系统元数据损坏(Filesystem Corruption)。

    为了防御这种脑裂,CSI 引入了极其严谨的状态机。K8s 侧通过 VolumeAttachment CRD 来记录挂载状态,而非直接依赖底层云 API:

    # 查看集群中的挂载记录
    $ kubectl get volumeattachment -l "node.name=old-dead-node"
    NAME                                                                   ATTACHER                       PV           NODE            ATTACHED   AGE
    csi-24a9e4...   diskplugin.csi.alibabacloud.com   pvc-c93a...  old-dead-node   true       120d
    

    查看这个僵尸 VolumeAttachment 的详情:

    status:
      attached: true # 这里一日不变成 false,新节点的 attach 就一日不能发起
      attachmentMetadata:
        csi.storage.k8s.io/node-name: old-dead-node
    

    在旧节点恢复通信(或者被彻底销毁)之前,external-attacher Sidecar 无法确认原节点的 kubelet 是否已经安全 unmount 了文件系统,因此它绝对不会将 VolumeAttachmentattached 状态改为 false,挂载死锁由此产生。

    破局与自愈:如何安全介入清理死锁?

    方案一:手动暴力介入(适用于 K8s < 1.26)

    当明确知道旧节点已经物理宕机被彻底隔离(例如已经在云控制台强制关机),我们需要手动帮助 ADC 越过这道安全红线。

    1. 强制删除旧 Pod(如果它还处于 Terminating 状态): bash kubectl delete pod --grace-period=0 --force
    2. 强制删除旧节点残留的 VolumeAttachment: 找到对应 PV 的 VolumeAttachment 记录,直接干掉: bash kubectl delete volumeattachment csi-24a9e4...
    3. 此时,external-attacher 会监听到旧 Attachment 消失,ADC 终于允许为新节点创建新的 VolumeAttachment,挂载流程恢复,Pod 启动。

    方案二:Non-Graceful Node Shutdown (NGNS) 自动化(K8s 1.26+ 标准解法)

    手动干预违背了自动化的运维信条。K8s 1.26 正式 GA 了 Non-Graceful Node Shutdown 特性。

    当节点失联且你确认它无法恢复时(可以通过外部监控脚本或 Node 自动运维系统判定),不要去删 Pod,而是直接给这个死亡节点打上一个特定的污点:

    kubectl taint nodes old-dead-node node.kubernetes.io/out-of-service=nodeshutdown:NoExecute
    

    这个污点是内置控制器的“免死金牌”。一旦加上:

    1. Taint Manager 会立刻驱逐节点上的所有 Pod,无视普通的 finalizers。

    2. 最核心的是:AttachDetachController 看到这个污点后,会认为系统管理员已经做出了背书(节点已死),它将直接绕过 CSI 正常的优雅 Detach 流程,强制删除 VolumeAttachment 并通知云厂商底层解绑。

    存储拓扑感知(Topology Awareness)的隐藏陷阱

    在多可用区(Multi-AZ)架构下排查时,就算解决了 Multi-Attach,Pod 仍有可能一直处于 Pending,报错变成:

    1 node(s) had volume node affinity conflict.
    

    这是因为 K8s 原生集成了存储拓扑感知。CSI 驱动(例如 AWS EBS CSI Driver)在创建 PV 时,会在 PV 的 nodeAffinity 中注入可用区标签:

    # PV 的拓扑信息片段
    nodeAffinity:
      required:
        nodeSelectorTerms:
        - matchExpressions:
          - key: topology.ebs.csi.aws.com/zone
            operator: In
            values:
            - ap-southeast-1a
    

    如果旧节点在 AZ-A,而 K8s 调度器将 Pod 驱逐到了 AZ-B 的新节点上,此时跨可用区是无法挂载单 AZ 云盘的。

    防范机制:StorageClass 延迟绑定 必须确保 StorageClass 启用了 volumeBindingMode: WaitForFirstConsumer

    apiVersion: storage.k8s.io/v1
    kind: StorageClass
    metadata:
      name: ebs-sc
    provisioner: ebs.csi.aws.com
    volumeBindingMode: WaitForFirstConsumer
    allowedTopologies:
    - matchLabelExpressions:
      - key: topology.ebs.csi.aws.com/zone
        values:
        - ap-southeast-1a
        - ap-southeast-1b
    

    但对于已经创建且绑定到特定 AZ 的现存 PV,如果整个 AZ 挂了,K8s 层面无能为力。这就要求核心有状态服务(如 DB、消息队列)必须在应用层做高可用(如 Raft、多副本同步),不要指望底层块存储跨 AZ 漂移。

    常见问题

    Q1:如果不确认节点死透,直接强制删除 VolumeAttachment,具体会发生什么样的底层损坏? A:如果旧节点只是管理网断开,业务网和存储网还在工作。强删 VolumeAttachment 导致盘被挂载给新节点,此时旧节点的 ext4 的日志(Journaling)仍在向设备写入,新节点也在写入。这会造成 inode 树严重破坏,通常在 5 分钟内整个文件系统就会变成只读(Read-only file system),甚至引发内核 Panic。操作前必须确保 IaaS 层原节点已下电。

    Q2:为什么 NFS 或者 CephFS 这种网络文件系统不会发生 Multi-Attach 报错? A:NFS/CephFS 提供的是文件级访问,其 AccessMode 通常是 ReadWriteMany(RWX)。K8s 和底层存储本身就允许多个节点同时挂载(Mount)同一个共享目录,没有独占锁(Exclusive Lock)的概念,因此不受 external-attacher 单点绑定的限制。

    Q3:Local PV(本地盘)在节点宕机时,调度行为和 CSI 有什么不同? A:Local PV 与节点是强绑定的(通过严格的 NodeAffinity)。一旦本地磁盘所在的 Node 宕机,使用该 PV 的 Pod 无论如何都不会漂移到其他节点上,它会永远处于 Pending,直到原节点恢复。所以 Local PV 只能用于自身具备数据冗余复制能力的应用(如 Elasticsearch、TiKV)。

  • 深入 Jenkins 动态构建雪崩排查:Kubernetes 插件 QPS 限流引发的 JNLP 断连与 Pod 孤儿风暴实战

    Jenkins 动态 Agent 架构在处理高并发构建时极易触发系统雪崩。核心元凶通常是 kubernetes-plugin 默认极低的 Client-Go QPS 限制引发 API 节流与 Pod 调度积压,叠加 NAT 网关静默丢弃 JNLP 空闲连接导致断连风暴。破局的关键在于:切换 Agent 通信至 WebSocket 协议,利用底层 System Properties 强行拉高 K8S 客户端 QPS/Burst 阈值,并通过 JCasC 实施防御性的超时与重试固化配置。

    故障现场:几百个 Pipeline 瞬间卡死,Master 线程池耗尽

    某次在应对业务大版本集中发布时,Jenkins(版本 2.426.1 LTSkubernetes-plugin 版本 4136.v7233)出现突发性大面积卡顿。

    现场症状:

    1. 构建积压:超过 300 个 Pipeline 任务处于 pending 状态,卡在 Jenkins doesn’t have label XXX

    2. 僵尸 Pod 泛滥:K8S 集群中存在大量状态为 TerminatingRunning 但未在执行任务的 Jenkins-Agent Pod。

    3. Master 假死:Jenkins Web UI 响应极其缓慢,Load Average 飙升至 80+,JVM 老年代内存使用率长期处于 95% 以上,频繁触发 Full GC。

    通过 jstack 抓取 Jenkins Master 的线程快照,发现大量线程阻塞在 Kubernetes 客户端的 HTTP 请求调度上,同时伴随疯狂报错的系统日志:

    # 报错一:JNLP Ping 超时风暴
    WARNING: Ping thread for channel JNLP4-connect connection from 10.244.5.122:38912 failed.
    java.util.concurrent.TimeoutException: Ping started at 171xxxxxxx hasn't completed by 171xxxxxxx+240000
        at hudson.remoting.PingThread.ping(PingThread.java:132)
    
    # 报错二:Kubernetes Plugin API 限流
    WARNING: Failed to provision a new node. 
    io.fabric8.kubernetes.client.KubernetesClientException: too many requests (429)
        at io.fabric8.kubernetes.client.dsl.internal.OperationSupport.requestFailure(OperationSupport.java:694)
    

    为什么 Jenkins Master 会被 K8S 动态 Agent 拖垮?

    表象是 Jenkins 性能不足,底层其实是通信协议缺陷与默认配置短板在并发场景下的集中爆发。

    1. K8S 插件 Client-Go QPS 限流导致的调度饥饿

    Jenkins Kubernetes 插件底层依赖 fabric8io/kubernetes-client。在缺乏显式配置的情况下,该客户端继承了极低的默认流控阈值(早期版本 QPS=5,Burst=10)。 当瞬间涌入几百个动态 Agent 申请时,Jenkins 向 Kube-APIServer 发起大量的 Pod Create/Watch 请求。触发限流(HTTP 429)后,客户端会指数退避重试。这不仅导致 Pod 迟迟无法拉起,还会使 Master 端负责 Provisioning 的专属线程被长时间挂起,最终耗尽线程池资源,引发 Web UI 卡死。

    2. NAT 网关静默丢弃引发 JNLP 断连风暴

    传统的 JNLP 代理协议基于 TCP长连接(默认端口 50000)。在容器化部署中,Agent Pod 通常经过 NodePort、Ingress 或云厂商的 NAT 网关与 Master 通信。 许多 NAT 网关/防火墙对空闲 TCP 连接有严格的存活期限制(如 5 分钟或更短),若无数据传输会静默丢弃(Drop)连接,且不发送 RST。 Jenkins 默认的 PingThread 检测周期是 4 分钟。当构建任务处于长时间的纯本地编译(如 make -j16)且没有向 Master 输出日志时,TCP 连接会被 NAT 掐断。此时 Master 仍在等待 Ping 回应,直到超时报错终止构建。随后 Master 尝试销毁 Pod,但由于上述的 API 限流,Delete 请求失败,直接产生大量“孤儿 Pod”。

    3. Pipeline CPS 转换引发的 Master CPU 燃烧

    部分研发在 Pipeline 的共享库(Shared Library)中编写了复杂的 for/while 循环或对大体积 JSON 进行了反序列化,且未加 @NonCPS 注解。Jenkins Pipeline 的 Continuation Passing Style (CPS) 引擎会将这些逻辑转换成成百上千个小的状态机对象存储到 Heap 中。大量的状态变更叠加 Agent 断连引发的异常处理逻辑,导致 Master 的 CPU 被 GC 线程和 CPS 引擎彻底吃光。

    极客实战:防御性配置与底层调优

    拒绝修修补补,直接从网络协议、K8S 客户端参数和不可变基础设施层面彻底重构。

    调优 1:废弃 TCP JNLP,全面启用 WebSocket 通道

    WebSocket 基于 HTTP/HTTPS 进行协议升级,复用 80/443 端口。标准 L7 Ingress/LB 对 WebSocket 的保活支持远好于裸 TCP 端口,有效穿透各类严格的防火墙。

    需要在 Jenkins System 中开启 WebSocket 并在 K8S Agent 模板中强制指定。通过 JCasC (Jenkins Configuration as Code) 固化配置如下:

    jenkins:
      cloud:
        kubernetes:
          name: "kubernetes"
          serverUrl: "https://kubernetes.default"
          # 开启 WebSocket 连接
          webSocket: true
          containerCapStr: "200" # 限制最大并发 Pod 数,防止打爆集群
          templates:
            - name: "base-agent"
              label: "base-agent"
              nodeUsageMode: EXCLUSIVE
              containers:
                - name: "jnlp"
                  image: "jenkins/inbound-agent:3148.v532a_7e715ee3-1"
                  # JNLP 容器的防御性资源限制
                  resourceRequestCpu: "500m"
                  resourceLimitCpu: "1000m"
                  resourceRequestMemory: "512Mi"
                  resourceLimitMemory: "1024Mi"
    

    调优 2:暴力破解 K8S 客户端并发限制

    直接通过 JVM 启动参数(System Properties),向 Kubernetes 客户端注入高并发阈值配置,并缩短 JNLP 的 Ping 超时窗口以尽早发现死连接。

    在 Jenkins Master 的 Deployment/StatefulSet 中注入以下 JAVA_OPTS

    # 提升 fabric8 k8s client 并发上限 (根据 API Server 承载能力调整)
    -Dorg.csanchez.jenkins.plugins.kubernetes.clients.Qps=50
    -Dorg.csanchez.jenkins.plugins.kubernetes.clients.Burst=100
    
    # 优化 JNLP Ping 机制:2分钟 Ping 一次,超时时间设为 1 分钟 (默认 4 分钟太迟钝)
    -Dhudson.remoting.PingThread.pingIntervalSecs=120
    -Dhudson.remoting.PingThread.pingTimeoutSecs=60
    
    # 优化 GC:大内存下启用 G1GC 并开启字符串去重 (缓解 CPS 转换导致的字符串常量泛滥)
    -XX:+UseG1GC -XX:+UseStringDeduplication -Xms8g -Xmx8g
    

    调优 3:Pipeline 共享库死锁的防御拦截

    针对耗时的 JSON 解析和复杂的集合遍历,强制在共享库代码层面引入 @NonCPS 注解,将计算任务剥离出 Jenkins Master 的状态机保存机制,交由原生 JVM 栈执行:

    import groovy.json.JsonSlurper
    import com.cloudbees.groovy.cps.NonCPS
    
    // 错误示范:在 CPS 块中解析大 JSON,极易导致 Master OOM 或 CPU 100%
    // def parseJson(String text) { return new JsonSlurper().parseText(text) }
    
    // 正确实战:防御性声明,计算完毕后直接返回结果,不保留中间状态
    @NonCPS
    def parseJsonFast(String text) {
        def slurper = new JsonSlurper()
        return slurper.parseText(text)
    }
    

    常见问题 (FAQ)

    Q1:Pipeline 卡在 “Waiting for next available executor”,但 K8S 集群明明有充足的 CPU/Memory 资源? A: 检查 Jenkins Master 是否达到了 containerCap 上限(默认 100)。即使集群有资源,Jenkins Kubernetes 插件也会拒绝发起新的 Pod 创建请求。另外,确认 Agent 模板中的 label 是否与 Pipeline 中声明的一致,拼写错误会导致无限期等待。

    Q2:通过 JCasC 更新了共享库 (Shared Library) 的分支,为什么重新构建时没有立刻生效? A: Jenkins 针对 Shared Library 默认开启了基于 Workspace 的缓存机制。如果在短时间内连续触发构建,可能会复用上一次 clone 的旧版本代码。可以在共享库配置中勾选 Include @Library changes in job recent changes 或在 JCasC 中显式关闭库的深度缓存(调整 retriever 的 timeout 策略),同时确认 Jenkins 服务器本地时间与 Git 仓库时间没有出现钟摆漂移。

    Q3:Pipeline 运行中抛出 java.io.NotSerializableException: java.util.regex.Matcher 报错,如何排查? A: 这是极其典型的 CPS 污染问题。Jenkins Pipeline 遇到 shsleep 等步骤时,会将当前所有的局部变量序列化保存到磁盘。如果在上述步骤前定义了不可序列化的对象(如 Regex Matcher、Socket 连接、I/O 流),序列化就会崩溃。 解法: 将对 Matcher 的操作封装到一个使用 @NonCPS 修饰的函数中执行,或者在使用完该对象后立即将其设为 null,确保其在跨越 Node/Agent 边界或进入挂起状态前被抛弃。

  • 深入 K8S Operator 内存雪崩排查:全局缓存滥用引发的 Informer OOM 与按需过滤实战

    排查发现,大量 Operator OOMKilled 并非代码内存泄漏,而是直接 Watch corev1.Secret 等基础资源时,Controller-Runtime 默认拉取全集群数据并构建本地 Indexer 缓存引发的。解决核心是在 Manager 初始化时引入 cache.Options.ByObject(v0.15.0+),在 Reflector 建立 Watch Stream 侧实施 Label 过滤,阻断无关数据进入 DeltaFIFO,将内存从 4GB 压降至 50MB。

    案发现场:一次常规 Watch 引发的血案

    某次排查线上自研 DB Operator 时,发现该组件的 Pod 频繁重启,Exit Code 137,监控面板显示内存使用率呈标准的锯齿状(直奔 4GB Limit 后被内核 OOM Killer 击溃)。同时,集群 kube-apiserver 的 CPU 出现周期性异常飙升,网络出带宽被打满。

    直接拉取 Operator 的 pprof heap 剖析文件:

    go tool pprof -http=:8080 http://localhost:8081/debug/pprof/heap
    

    Top 资源消耗显示,90% 以上的内存被 client-go 的底层缓存结构吃掉:

    (pprof) top
    Showing nodes accounting for 3.6GB, 92% of 3.9GB total
    Dropped 120 nodes (cum <= 0.02GB)
          flat  flat%   sum%        cum   cum%
         2.1GB 53.84% 53.84%      2.1GB 53.84%  k8s.io/client-go/tools/cache.(*ThreadSafeStore).Add
         1.0GB 25.64% 79.48%      1.0GB 25.64%  k8s.io/apimachinery/pkg/apis/meta/v1/unstructured.(*Unstructured).DeepCopy
         0.5GB 12.82% 92.30%      3.6GB 92.30%  k8s.io/client-go/tools/cache.(*sharedIndexInformer).HandleDeltas
    

    检查业务代码,开发人员在 Setup 阶段写了如下逻辑,目的是为了监听 Operator 自身下发给 DB 实例的 Secret(用于 TLS 证书轮转):

    // 埋雷代码
    err = ctrl.NewControllerManagedBy(mgr).
        For(&dbv1.MyDatabase{}).
        Watches(&corev1.Secret{}, &handler.EnqueueRequestForOwner{
            OwnerType:    &dbv1.MyDatabase{},
            IsController: true,
        }).
        Complete(r)
    

    为什么一个简单的 Watch 会打爆整个 Indexer 缓存?

    很多新人对 Controller-Runtime 的 Cache 机制存在误解,以为在 Reconcile 里过滤或者用 EnqueueRequestForOwner 就能限制内存使用。这是典型的防御边界后置

    在 Controller-Runtime 的底层架构中,所有通过 Client 读取的操作(非直接指定 client.Reader)和 Watch 操作,都会由全局共享的 Cache 组件(Backed by Informer)接管。

    1. 无差别 LIST/WATCH: 当你调用 Watches(&corev1.Secret{}) 时,Manager 会检查对应的 Informer 是否启动。如果没有,它会创建一个针对 corev1.Secret 的全局 Informer。

    2. 全量同步: Reflector 会向 API Server 发送一个 不带任何过滤条件LIST /api/v1/secrets 请求。如果你的集群里有 10 万个 Secret(比如 Helm Release 的历史记录、各种 ServiceAccount Token),这 10 万个对象会被全量拉取。

    3. 入库 Indexer: 拉取到的数据经过 DeltaFIFO,最终塞进本地的 ThreadSafeStore(一个带有读写锁的 map)。

    4. 爆炸: Kubernetes 的 Secret 对象通常包含巨大的 Base64 payload(如证书、配置)。将 10 万个 Secret 全量缓存在 Operator 的进程内存中,不仅当场撑爆 4GB,还会导致 API Server 在建立 Watch stream 时耗尽缓冲区。

    EnqueueRequestForOwner 只是限制了事件入队 (WorkQueue) 的范围,并没有限制 Informer 缓存 (Cache) 的范围。内存早就被底层 map 吃干抹净了。

    破局:在 Watch Stream 侧实施按需过滤

    解决这个问题的关键在于:将过滤逻辑前置推送到 API Server 端

    sigs.k8s.io/controller-runtime v0.15.0 开始,Cache 配置选项被重新设计,我们可以利用 cache.Options.ByObject 为特定资源指定 LabelSelector 或 FieldSelector。这样,底层 Reflector 在构造 ListWatch 请求时,就会带上相应的查询参数。

    重构 Manager 初始化逻辑:

    import (
        "k8s.io/apimachinery/pkg/labels"
        "sigs.k8s.io/controller-runtime/pkg/cache"
        "sigs.k8s.io/controller-runtime/pkg/client"
        ctrl "sigs.k8s.io/controller-runtime"
    )
    
    func main() {
        // 1. 定义我们只关心带有特定 Label 的 Secret
        secretLabelSelector := labels.SelectorFromSet(labels.Set{
            "app.kubernetes.io/managed-by": "my-db-operator",
        })
    
        // 2. 配置 Cache 策略
        mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
            Scheme: scheme,
            Cache: cache.Options{
                ByObject: map[client.Object]cache.ByObject{
                    &corev1.Secret{}: {
                        Label: secretLabelSelector,
                        // 如果只需要监听特定 NS,也可以配合 FieldSelector
                        // Field: fields.SelectorFromSet(fields.Set{"metadata.namespace": "db-system"}),
                    },
                },
            },
        })
    
        if err != nil {
            setupLog.Error(err, "unable to start manager")
            os.Exit(1)
        }
        // ... 后续启动逻辑
    }
    

    修改后重启 Operator,API Server 侧接收到的请求变为: LIST /api/v1/secrets?labelSelector=app.kubernetes.io%2Fmanaged-by%3Dmy-db-operator

    仅拉取和缓存 Operator 真正管理的几十个 Secret,内存消耗瞬间从 4GB 暴跌至 50MB 左右,GC 压力释放,CPU 利用率趋于一条平滑的直线。

    常见问题 (FAQ)

    Q1:为了绕过缓存导致 OOM,我直接使用 mgr.GetAPIReader() 替代 mgr.GetClient() 来读取 Secret 可以吗? 不可以滥用 APIReader。APIReader 会直接穿透缓存向 API Server 发起实时查询。如果在高频的 Reconcile 循环中对基础资源使用 APIReader,会产生可怕的 Read QPS,极易触发 API Server 的流控(RateLimiting),甚至拖垮主节点 etcd。基础资源读取必须走缓存,关键在于“控缓存规模”而非“弃用缓存”。

    Q2:如果我需要监听多个特定 Namespace 下的资源,而不是依赖 Label,该怎么配置? 可以通过 cache.Options.DefaultNamespaces 来限制全局缓存的命名空间范围。如果你需要监听 ns-ans-b

    Cache: cache.Options{
        DefaultNamespaces: map[string]cache.Config{
            "ns-a": {},
            "ns-b": {},
        },
    }
    

    这在底层会实例化 MultiNamespacedCache,对每个指定 NS 启动独立的 Watcher。

    Q3:我在 Cache 中配置了 LabelSelector,这会影响 Garbage Collection (GC) 和 OwnerReference 的级联删除吗? 会产生直接影响。如果父对象 A 创建了子对象 B,且通过 cache.ByObject 过滤了子对象 B(比如子对象 B 没有打上对应的 Label),那么当 B 发生状态变化或被意外删除时,Operator 的 Informer 将无法收到事件,也就无法触发针对父对象 A 的 Reconcile,导致级联恢复机制失效。 最佳实践: 只要是你 Operator 创建并需要跟踪生命周期的附属资源,必须在创建时强行注入统一的管控 Label,并在 Manager Cache 配置中对齐该 Label。

  • 深入 Argo CD 配置漂移雪崩排查:全量 Reconcile 引发的 API Server 限流与 Repo Server OOM 实战

    某次管理 5000+ Application 的多集群 Argo CD (v2.8.4) 平台突发系统级雪崩,同步队列深度飙升至上万,Repo Server 陷入 OOM 死循环,直接导致底层管控 K8s API Server 出现大规模 429 限流拒绝服务。核心结论:默认 3 分钟的全局漂移检测机制(Reconcile)配合高并发的 Helm 渲染,会轻易击穿系统底线。通过实施 Controller 动态分片(Ring Sharding)、拉长调谐周期配合 Webhook 触发、以及全面启用 Server-Side Apply (SSA),我们最终将系统 Load 均值从 80+ 压回 2 以内。

    故障现场:队列拥塞与级联崩溃

    排查过程中,告警系统首先抛出的是应用同步延迟告警,紧接着是整个 CD 平台的 UI 瘫痪。登录管控集群节点,查看核心指标:

    # Application Reconcile 队列深度飙升
    sum(argocd_app_reconcile_queue_depth) > 5000
    
    # API Server 响应延迟 P99 打到了 15s 以上
    histogram_quantile(0.99, sum(rate(apiserver_request_duration_seconds_bucket[5m])) by (le)) > 15
    

    检查 argocd-application-controller 的日志,满屏的 gRPC 超时与限流报错:

    time="202X-XX-XXT10:14:22Z" level=error msg="Failed to reconcile application" application=prod-payment-svc error="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp: i/o timeout\""
    time="202X-XX-XXT10:14:25Z" level=warning msg="Waited for 2.142s due to client-side throttling, not priority and fairness, request: GET:https://10.96.0.1:443/apis/apps/v1/namespaces/default/deployments"
    

    同时,argocd-repo-server 频繁触发 OOMKilled 被 Kubelet 重启。整个系统陷入了“积压 -> 重试 -> 资源耗尽 -> 宕机重启 -> 进一步积压”的死亡螺旋。

    为什么配置漂移检测会演变成 API Server 拒绝服务?

    Argo CD 的核心架构设计中,状态对比(Diff)依赖两部分数据:

    1. Target State (Git/Helm): 由 repo-server 负责拉取仓库并执行 helm templatekustomize build 动态生成。

    2. Live State (K8s): 由 application-controller 维护的 Cluster Cache,它会针对纳管集群中的资源建立全量 Watch

    在 Kubernetes Operator 模式中,通常依靠事件驱动(Informer)来触发 Reconcile。但为了捕获不在 Kubernetes 内部触发的变更(如直接在 Git 仓库修改代码,或目标集群由于某种网络割接导致状态漂移),Argo CD 强制引入了定期轮询机制。

    关键配置在 argocd-cm 中的 timeout.reconciliation(默认 3 分钟)。 这意味着,每隔 3 分钟,Controller 会强制对所有 Application 发起一次全量调谐。

    当 Application 数量达到 5000 时,系统每秒需要处理 5000 / 180s ≈ 28 个应用的 Diff 计算。 问题出在 repo-server 的处理逻辑上。每次对比,repo-server 都要执行底层的 exec 系统调用来拉起 Helm/Kustomize 二进制进程渲染 Manifest。高频率的进程 Fork 加上并发拉取巨型 Chart 包,瞬间吃光了 repo-server 所在的 Node 内存,触发 OOM。

    更致命的是,随着 repo-server 宕机,Controller 内部的 Workqueue 开始大量积压。当 repo-server 重启恢复后,Controller 瞬间发起海量重试请求。同时,集群缓存(Cluster Cache)如果因为网络抖动断开连接,重建缓存时会对目标集群的 API Server 发起海量的 LIST 请求,直接打爆 API Server 的带宽和内存,导致客户端被 K8s API Server 的 APF (API Priority and Fairness) 机制无情限流(429)。

    破局与防御性性能调优实战

    为了彻底根治大规模 GitOps 场景下的雪崩问题,必须从请求入口、队列处理、资源隔离三个维度进行防御性改造。

    1. 斩断无效轮询:拉长周期与 Webhook 接管

    绝对不要在生产环境保持 3 分钟的全量 Reconcile。将定期漂移检测的周期拉长至 15 分钟甚至更久,日常同步全部交由 Git Webhook 触发。

    修改 argocd-cm ConfigMap:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: argocd-cm
      namespace: argocd
    data:
      # 将全量调谐周期拉长至 15 分钟
      timeout.reconciliation: 15m
    

    注:Webhook 接收到 Push 事件后,只会触发指定代码库关联的 Application 进行更新,直接将 O(N) 的全局扫描降维打击为 O(1) 的定向更新。

    2. 引入 Ring Sharding 动态分片

    单个 Controller 扛 5000 个应用是不现实的。在 Argo CD v2.8+ 中,官方支持了基于一致性哈希(Ring Hash)的 Controller 动态分片。相比于老版本按集群分片(可能导致单集群应用过多引发数据倾斜),Ring 算法能在应用级别均衡负载。

    argocd-cmd-params-cm 中开启分片并指定算法:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: argocd-cmd-params-cm
      namespace: argocd
    data:
      # 开启一致性哈希分片
      controller.sharding.algorithm: "ring"
    

    同时调整 StatefulSet 副本数:

    kubectl scale statefulset argocd-application-controller -n argocd --replicas=5
    

    这样 5000 个 App 会被平滑打散到 5 个 Controller 实例中,每个节点只负责 1000 个。

    3. 压制 Repo Server 的无序并发

    不能让 Controller 无脑压垮 Repo Server。必须对 repo-server 进行并发度限制,以时间换取系统稳定性。

    修改 argocd-cmd-params-cm

    data:
      # 限制单个 Repo Server 的最大并发解析数为 50 (默认不限制,极易 OOM)
      reposerver.parallelism.limit: "50"
      # 开启 Exec 进程复用限制
      reposerver.disable.tls: "true" 
    

    4. 启用 Server-Side Apply (SSA) 拯救巨型 CRD

    排查中发现,某些包含复杂 CRD(如 PrometheusRule 或 Istio VirtualService)的 Application 极易同步卡死。原因是 Argo CD 默认使用 Client-Side Apply,会将上次同步的状态塞进 K8s 资源的 kubectl.kubernetes.io/last-applied-configuration Annotation 中。当 CRD 极大时,直接突破 Annotation 262144 bytes 的大小限制,导致永远同步失败并反复重试。

    解决方案是强制启用 Server-Side Apply,将状态合并逻辑下沉到 K8s API Server 端处理。 在 Application 的 syncOptions 中开启:

    apiVersion: argoproj.io/v1alpha1
    kind: Application
    metadata:
      name: prometheus-rules
    spec:
      syncPolicy:
        syncOptions:
        - ServerSideApply=true
        - RespectIgnoreDifferences=true
    

    常见问题

    Q1:Application 一直处于 OutOfSync 状态,但仔细看代码根本没有变更,怎么排查? 通常是因为某些 Mutating Webhook(如 Istio 注入的 sidecar、Kyverno 修改的 default 字段)在资源创建后修改了 K8s 里的 Live State,导致 Git 里的配置和集群真实状态对不上。 解决办法:在 Application 配置中加入 ignoreDifferences,忽略这些由准入控制器自动注入的字段(例如 spec.replicas 或特定的 annotations)。

    Q2:配置了 GitLab Webhook,但为什么推代码后 Argo CD 还是等了很久才同步? Argo CD 的 Webhook 逻辑是:收到事件后,使内部缓存的该 Repo 的 Git commit sha 失效,并标记关联的 App 为需要 Reconcile。如果此时 Controller 的 Workqueue 仍然拥堵,或者你的 repo-server 拉取大仓库超时,依然会出现延迟。必须结合前面提到的 Controller 分片和并发调优才能彻底加速。

    Q3:多租户场景下,Argo CD UI 越用越卡,加载应用列表要 10 秒以上? 这是 Argo CD 经典的 RBAC 性能陷阱。每次请求 UI,API Server 都会通过 Casbin 引擎去全量校验该用户对所有 App 的权限。随着 App 数量增加,CPU 计算量呈指数上升。 解决办法:在 argocd-cmd-params-cm 中开启 RBAC 缓存 server.rbac.log.enforce.enable: "false"(视情况),并精简 argocd-rbac-cm 中的 policy 规则,尽量使用 group 授权,避免给单独用户绑定上千条单一应用的 ACL 规则。

  • 深入 Jenkins 动态 Agent 调度延迟:K8S Pod 启动风暴引发的 JNLP 连接超时与 Master 线程耗尽排查实战

    高并发 CI/CD 场景下,Jenkins K8S 动态 Agent 极易因 Pod 启动风暴引发雪崩。本文核心结论:当并发构建量突增时,基于传统的 TCP 50000 端口进行 JNLP 通信会导致大量半连接和路由超时;通过将 Remoting 协议切换为 WebSocket,并调优 fabric8 客户端并发数与 K8S Cloud 的 containerCap,可彻底根治 Agent 频繁掉线与 Master 线程耗尽问题。

    故障现场:Agent 陷入“创建-离线-销毁”的死循环

    某次核心业务线进行大版本多分支并发验证,短时间内触发了超过 300 个 Pipeline 构建任务。监控大盘显示,Jenkins Master(版本 2.426.3-lts)的 Load Average 瞬间飙升至 40+,大量构建任务处于 Pending 状态。

    观察 K8S 集群发现,Kubernetes Plugin 确实在疯狂下发 Pod 创建请求,但现象极为诡异:

    1. Pod 能够被 K8S 调度并启动,进入 Running 状态。

    2. Pod 内的 jnlp 容器存活约 100 秒后,打印 Terminated 异常并自动退出。

    3. Jenkins Master 认为 Agent 离线,再次向 K8S 申请新建 Pod。

    4. 整个集群陷入了毫无意义的资源消耗死循环,API Server QPS 异常突增。

    提取出错 Agent Pod 内 jnlp 容器的日志:

    INFO: Locating server among [http://jenkins-master.cicd.svc.cluster.local:8080/]
    INFO: Trying protocol: JNLP4-connect
    WARNING: Could not connect to jenkins-master.cicd.svc.cluster.local:50000
    java.net.ConnectException: Connection timed out (Connection timed out)
        at java.base/sun.nio.ch.Net.connect0(Native Method)
        at hudson.remoting.Engine.connect(Engine.java:544)
        at hudson.remoting.Engine.innerRun(Engine.java:375)
    

    深度追踪:为什么 K8S Agent 能够正常拉起,却始终无法完成 JNLP 注册?

    从日志来看,这是一个典型的网络连通性报错,但问题并没有那么表面。Jenkins 的 Master-Agent 架构依赖 Remoting 协议,其传统的握手流程如下:

    1. Agent 启动时,通过 HTTP(S) 请求 Master 的 TCP port API,获取 JNLP 加密凭证(Secret)和专用的 TCP 通信端口(默认 50000)。

    2. Agent 与 Master 的 50000 端口建立长连接,维持心跳并接收 Pipeline 执行指令。

    1. 传统 TCP 50000 端口的架构缺陷

    在 K8S 环境中,Master 通常隐藏在 Ingress 或 Service 之后。如果仅仅暴露 HTTP 8080 端口,而没有在 Ingress 上透传 50000 端口的 TCP 流(需配置 Ingress Nginx 的 tcp-services ConfigMap),Agent 在第二步就会直接被拒绝。

    即便 Service 层开放了 50000 端口,当数百个 Agent 同时发起 TCP 握手时,若底层网络 CNI 插件(如 Calico 或 Cilium)遇到 iptables/eBPF 规则更新延迟,也会导致 SYN 报文被 Drop,进而引发 Connection timed out

    2. Jenkins Master 线程池耗尽

    排查过程中,直接在 Jenkins Master 宿主机抓取 jstack,发现大量 Jetty HTTP 线程处于 BLOCKED 状态:

    "qtp12345678-100" prio=10 tid=0x00007f8a1c000000 nid=0x1a2b waiting for monitor entry [0x00007f8a11234000]
       java.lang.Thread.State: BLOCKED (on object monitor)
        at org.csanchez.jenkins.plugins.kubernetes.KubernetesCloud.provision(KubernetesCloud.java:650)
        - waiting to lock <0x00000007a1b2c3d0> (a java.lang.Object)
        at hudson.model.NodeProvisioner.update(NodeProvisioner.java:310)
    

    Kubernetes Plugin(版本 4136.vca_b_3203a_5103)底层使用 fabric8 K8S 客户端。默认情况下,fabric8 的 HTTP 客户端(OkHttp)对同一 Host 的并发连接数有严格限制。当并发创建 Pod 请求积压时,不仅阻塞了 Jenkins NodeProvisioner 的调度线程,更拖垮了 Master 响应 Agent HTTP JNLP 请求的能力,导致即使网络是通的,Agent 也因 Master 响应超时而注册失败。

    防御性架构重构与 JCasC 落地

    要从根本上解决高并发下的 Agent 调度雪崩,必须切断对独立 TCP 端口的依赖,并对 K8S Plugin 进行限流防爆。

    1. 抛弃独立 TCP 端口,全面启用 WebSocket

    Jenkins 2.222+ 已原生支持通过 WebSocket 传输 Remoting 协议。启用后,Agent 的通信将直接复用 HTTP(S) 的 8080/443 端口,无需额外配置 TCP 转发,完美穿透 Ingress 与负载均衡器,且极大降低了网络组件的连接跟踪(Conntrack)压力。

    2. JCasC (Jenkins Configuration as Code) 最佳实践

    通过 JCasC 固化 Kubernetes Cloud 的防御性配置。以下为排查后的标准配置片段,重点关注 webSocket 与容量控制参数:

    jenkins:
      clouds:
        - kubernetes:
            name: "k8s-cluster"
            serverUrl: "https://kubernetes.default"
            # 强制启用 WebSocket 复用 HTTP 端口
            webSocket: true 
            # Master 并发创建 Agent 的上限,避免 API Server 与 fabric8 线程池被击穿
            containerCapStr: "100" 
            # 连接超时与读取超时调优
            connectTimeout: 5
            readTimeout: 15
            templates:
              - name: "base-agent"
                namespace: "jenkins-agents"
                label: "k8s-agent"
                # 故障排查关键:任务失败后保留 Pod 10分钟,以便抓取现场日志
                podRetention: "OnFailure" 
                containers:
                  - name: "jnlp"
                    image: "jenkins/inbound-agent:3148.v532a_7e715ee3-1"
                    workingDir: "/home/jenkins/agent"
                    resourceRequestCpu: "500m"
                    resourceLimitCpu: "1000m"
                    resourceRequestMemory: "512Mi"
                    resourceLimitMemory: "1024Mi"
    

    3. JVM 与底层客户端参数调优

    为了防止 fabric8 客户端在极端并发下卡死,需要在 Jenkins Master 的启动参数(JAVA_OPTS)中注入以下调优指令,突破 OkHttp 的并发瓶颈:

    # 提升 Kubernetes Client 对单个后端(API Server)的并发连接数限制
    -Dkubernetes.client.maxConcurrentRequests=200
    -Dkubernetes.client.maxConcurrentRequestsPerHost=100
    # 禁用 Jenkins 旧版 Remoting 协议,减少安全面攻击和不必要的协议回退
    -Djenkins.slaves.JnlpSlaveAgentProtocol3.enabled=false
    -Djenkins.slaves.JnlpSlaveAgentProtocol4.enabled=true
    

    常见问题 (FAQ)

    Q1:Pipeline 执行时频繁报 NotSerializableException,如何解决? 这是由于 Jenkins 的 CPS(Continuation Passing Style)引擎在持久化 Pipeline 状态时,遇到了无法序列化的 Java 对象(如 java.util.regex.Matcher、数据库 Connection、或是非序列化的自定义类)。 解决: 永远不要在 nodestage 闭包跨越处传递这类对象;如果必须在代码块中使用复杂逻辑,请将该逻辑抽取为独立函数,并打上 @NonCPS 注解,让其在标准 JVM 堆栈中执行,而非被 CPS 引擎拦截。

    Q2:更新了 Jenkins Shared Library 的代码,但在已缓存的 Job 中不生效,必须重启 Jenkins 吗? 不需要。如果是隐式加载(Global Shared Libraries),Jenkins 默认会开启基于分支/标签的缓存。如果在 JCasC 中配置了 Library,务必检查 implicit: truedefaultVersion: "master" 的设置。如果是通过 @Library('[email protected]') _ 显式加载,建议采用基于 Git Tag 或 Commit Hash 的不可变版本号,而不是依赖分支名(如 master),以彻底规避 Classloader 缓存未刷新的问题。

    Q3:通过 JCasC 动态 Reload 配置时,会导致正在运行的 Pipeline 中断吗? 绝大多数配置(如 Views, Jobs 模板, Cloud 设置)的 Reload 是平滑的。但如果你在 JCasC 中修改了 securityRealm(安全域认证机制)或 authorizationStrategy,Jenkins 会销毁当前所有的安全上下文,这会直接导致正在执行的 Remoting Channel 被强行终止,引发 Agent 断联和任务报错。强规则: 绝对禁止在有核心业务构建运行时热重载安全相关配置。

  • Jenkins 生产环境雪崩排查实战:Groovy CPS 陷阱引发的 Metaspace 溢出与 K8S Agent 调度风暴

    结论先行:Jenkins Pipeline 复杂的 Groovy 闭包会导致 CPS(Continuation Passing Style)频繁进行 AST 转换,耗尽 Master Metaspace 触发 OOM。同时,K8S 插件在 Master 假死断连时产生的 Agent 创建风暴,会瞬间击穿 K8S API Server。本文通过重构 Shared Library 剥离 CPS 逻辑,并引入 JCasC 固化 K8S 动态 Agent 限流配置,彻底解决百级别并发构建下的系统雪崩问题。

    1. 故障现场:Master 假死与 K8S API Server 告警

    排查过程中接到告警,CI/CD 集群 P99 构建排队时间从平时的 5 秒飙升至 30 分钟以上。登录控制台发现 Jenkins UI 响应极其缓慢,部分页面直接 502。 联动监控大盘,发现了两个极度异常的指标:

    1. Jenkins Master JVMMetaspace 使用率在两小时内呈阶梯式上涨,直至 100% 触发 Full GC,单次 GC 停顿(STW)超过 12 秒。

    2. K8S 控制平面:API Server QPS 突增,尤其是针对 namespaces/jenkins/podsPOSTDELETE 请求,导致 API Server CPU 飙升,etcd 出现选主告警。

    进入 Jenkins Master 容器抓取现场:

    # 查看 JVM 内存状态
    jstat -gcutil $(pgrep java) 1000 5
      S0     S1     E      O      M     CCS    YGC     YGCT    FGC    FGCT    GCT   
      0.00 100.00  32.14  89.45  99.98  98.71  23412  145.312  425  312.411  457.723
    
    # 生成 Heap Dump 和 Thread Dump(保留案发现场)
    jcmd $(pgrep java) GC.heap_dump /tmp/jenkins_oom.hprof
    jcmd $(pgrep java) Thread.print > /tmp/jenkins_threads.txt
    

    日志中大量抛出 java.lang.OutOfMemoryError: Metaspace,同时伴随着 Kubernetes client: failed to create pod ... Read timeout。很明显,JVM 已经处于频繁 GC 的濒死状态。

    2. 为什么 Groovy CPS 机制会吃光 Master 的 Metaspace?

    把 Heap Dump 拖到 MAT(Memory Analyzer Tool)里分析,发现 ClassLoader 数量异常庞大,且绝大多数是由 com.cloudbees.groovy.cps.NonCPS 和 Pipeline 脚本动态生成的类。

    Jenkins Pipeline 的底层运行机制基于 CPS(Continuation Passing Style)。为了让 Pipeline 在 Jenkins Master 重启后还能从断点恢复继续执行,Jenkins 必须能够将当前执行的堆栈状态序列化到磁盘。 这就导致了一个致命陷阱:你在 Jenkinsfile 里写的每一行看似普通的 Groovy 代码,都会被 CPS 转换引擎解析重写为可以被序列化的 AST(抽象语法树)对象。

    在某次业务线提交的 Shared Library 中,发现了一段类似这样的代码:

    // 反面教材:在 CPS 方法中进行大量不可序列化对象的循环操作
    def processComplexJson(String jsonStr) {
        def jsonSlurper = new groovy.json.JsonSlurperClassic()
        def data = jsonSlurper.parseText(jsonStr)
        // 这里的 data 树结构非常复杂,且在循环中调用了 pipeline step
        data.items.each { item ->
            if (item.name.matches(".*-service-.*")) { // 正则 Matcher 不可序列化
                echo "Processing ${item.name}"       // 调用了 CPS 步骤
                // 复杂的处理逻辑...
            }
        }
    }
    

    原理解析

    1. JsonSlurper 解析出的复杂对象模型、java.util.regex.Matcher 等对象是不可序列化的。

    2. 当闭包 .each {} 内部混合调用了 Pipeline 原生 step(如 echo, sh)时,Jenkins 会尝试保存整个上下文。

    3. 每次执行构建,CPS 引擎为了处理这些无法直接解析的代码,会动态生成大量的匿名类加载到 Metaspace 中。由于这些类持有 Pipeline 的执行上下文(强引用),无法被 GC 快速回收。

    4. 并发一高,Metaspace 迅速被打爆。Master 发生长达十几秒的 STW。

    雪崩链条: Master STW -> JNLP Agent (运行在 K8S Pod 中) 的心跳超时 -> Jenkins 认为 Agent 已死,触发重连或重新分配 -> K8S Plugin 疯狂向 API Server 发起创建 Pod 请求 -> API Server 被打满 -> 旧 Agent 还在跑,新 Pod 不断创建 -> K8S 节点资源耗尽。

    3. 核心修复:Shared Library 与 K8S Agent 调优实践

    针对上述问题,我们从代码重构和配置加固两方面进行落地。当前环境为 Jenkins 2.414.3 LTS,Kubernetes Plugin 4136.v464303c7379d。

    3.1 剥离 CPS:使用 @NonCPS 与纯粹的 Java 类

    对于 Shared Library 中的数据处理逻辑,必须将纯粹的代码计算Pipeline 执行步骤隔离开。使用 @NonCPS 注解,让 Jenkins 跳过 AST 转换,按标准 JVM 字节码执行。

    import com.cloudbees.groovy.cps.NonCPS
    import groovy.json.JsonSlurperClassic
    
    // 1. 将耗时的、涉及不可序列化对象的纯计算逻辑标记为 @NonCPS
    @NonCPS
    List<String> getServicesToProcess(String jsonStr) {
        def services = []
        def jsonSlurper = new JsonSlurperClassic()
        def data = jsonSlurper.parseText(jsonStr)
    
        for (item in data.items) {
            if (item.name.matches(".*-service-.*")) {
                services.add(item.name)
            }
        }
        return services // 只返回可序列化的基本类型或标准集合
    }
    
    // 2. 在 Pipeline 步骤中通过标准 for 循环调用(不要用 .each 闭包混合 pipeline step)
    def call(String jsonStr) {
        List<String> targetServices = getServicesToProcess(jsonStr)
        for (int i = 0; i < targetServices.size(); i++) {
            def svc = targetServices[i]
            echo "Processing ${svc}"
            // 执行实际的 pipeline steps...
        }
    }
    

    3.2 阻断雪崩:JCasC 固化 K8S Agent 限流配置

    为了防止 Jenkins 在网络抖动或自身 GC 时向 K8S 发起 API DDOS 攻击,必须严格配置 K8S Plugin 的容量上限,并改用 WebSocket 代替 TCP JNLP 端口直连。 我们通过 JCasC (Jenkins Configuration as Code) 强制注入以下安全配置:

    jenkins:
      clouds:
        - kubernetes:
            name: "kubernetes"
            serverUrl: "https://kubernetes.default"
            namespace: "jenkins"
            jenkinsUrl: "http://jenkins-master.jenkins.svc.cluster.local:8080"
            # 【核心防御】开启 WebSocket,复用 HTTP 端口,避免 K8S LoadBalancer 断流导致心跳丢失
            webSocket: true 
            # 【核心防御】限制全局并发 Pod 数,保护 K8S API Server 和节点资源
            containerCapStr: "200"
            # 限制 API 请求超时时间
            readTimeout: 15
            connectTimeout: 5
            maxRequestsPerHostStr: "32"
            templates:
              - name: "base-maven"
                namespace: "jenkins"
                label: "maven-agent"
                # 限制单种模板的最大并发数
                instanceCapStr: "50" 
                containers:
                  - name: "jnlp"
                    image: "jenkins/inbound-agent:3148.v532a_7e715ee3-1"
                    workingDir: "/home/jenkins/agent"
                    resourceRequestCpu: "500m"
                    resourceLimitCpu: "2"
                    resourceRequestMemory: "1Gi"
                    resourceLimitMemory: "2Gi"
    

    同时,调整 Jenkins Master 启动参数,增大 Metaspace 并限制其无序扩张: JAVA_OPTS="-Xms8G -Xmx8G -XX:MetaspaceSize=512M -XX:MaxMetaspaceSize=1G -XX:+UseG1GC"

    应用上述修复后,P99 排队时间回落至 3 秒,Master 内存泄漏彻底消除,API Server 平稳运行。

    4. 常见问题 (FAQ)

    Q1: K8S 动态 Agent 频繁出现 JNLP connection timeout 或 offline,是什么原因? 通常有两个原因:一是中间的 Ingress/LoadBalancer 对长连接(默认 50000 TCP 端口)有 idle timeout 清理机制,导致静默断连;二是 Master 的 CPU 或内存被跑满,无法及时响应心跳。 建议解决: 启用 Kubernetes 插件的 webSocket: true 选项,让 Agent 通过 标准的 HTTP 8080 端口使用 WebSocket 与 Master 通讯,这样不仅穿透性好,还能复用 HTTP 的负载均衡和 KeepAlive 策略。

    Q2: 在动态 K8S Agent 中构建 Docker 镜像,推荐 DinD (Docker in Docker) 还是 Kaniko? 坚决抵制在 K8S 生产环境中大规模使用 DinD。DinD 需要开启 Pod 的 privileged: true 特权模式,这在任何有底线的运维体系中都是不被允许的,极易引发容器逃逸。 建议解决: 使用 Google 提供的 Kaniko。它完全在用户态执行,无需特权,直接通过解析 Dockerfile 在容器内层层构建镜像文件系统,最后 push 到 Harbor。

    Q3: 如何安全地在 JCasC YAML 中管理集群密码和 Secret? 禁止在 JCasC 的 yaml 文件里明文写 Token! 建议解决: 利用 Jenkins 的 Secret 机制结合 K8S 环境变量。在 JCasC 中使用 ${MY_SECRET} 占位符,然后在 Jenkins Master 的 Deployment 中通过 K8S Secret 挂载到环境变量。启动时 JCasC 会自动将其替换,实现配置与凭据解耦。

  • K8S API Server 被打挂的元凶:记一次 CRD Status 更新引发的 Reconcile 死循环惨案

    排查某个生产 K8S 集群异常时,发现 APIServer P99 延迟飙升至 4000ms 以上,etcd 磁盘 IOPS 直接打满。排查结论极度缺乏常识:业务团队新上线的一个 Operator 在 Reconcile 循环中毫无节制地更新 CRD 的 Status 字段(甚至注入了 time.Now()),且未配置任何 Event Filter。这导致了一个经典的死循环:更新 Status -> 触发 Update 事件 -> 进入 WorkQueue -> 再次 Reconcile -> 再次更新 Status。最终演变成针对 APIServer 的内网 DDoS,直接干碎了控制平面。

    这种低级失误在 Operator 开发中屡见不鲜。如果你连 K8S 声明式 API 的控制循环语义和 Informer 机制都没搞懂,就不要去碰 controller-runtime

    现场还原与指标雪崩

    近期监控系统疯狂报警,核心集群的 apiserver_request_duration_seconds_bucket 指标中,Mutating API 的 P99 延迟从平时的 15ms 暴涨到 4s。同时,etcd 节点的 etcd_disk_wal_fsync_duration_seconds 指标出现剧烈抖动,底层存储 IOPS 处于持续饱和状态。

    第一反应是控制平面被恶意击穿。拉取 APIServer 的审计日志和 QPS 监控(apiserver_request_total),发现某个特定资源 appconfigs.biz.example.comPUT / PATCH 请求 QPS 高达 8000+,且全集中在 /status 子资源上。

    随便抓一条 APIServer 的日志:

    I0814 10:23:45.123456       1 trace.go:205] Trace[12345678]: "Update /apis/biz.example.com/v1/namespaces/default/appconfigs/test-app/status" (started: 202x-xx-xx..., 3.5s)
    

    很明显,是新上的 Operator 出了严重 Bug。

    扒开烂代码:愚蠢的 Reconcile 逻辑

    把出问题 Operator 的代码拉下来,看一眼 Reconcile 函数和 Controller 的注册逻辑,简直是灾难现场。

    致命代码片段 1:无意义的动态 Status 更新

    func (r *AppConfigReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
        var instance bizv1.AppConfig
        if err := r.Get(ctx, req.NamespacedName, &instance); err != nil {
            return ctrl.Result{}, client.IgnoreNotFound(err)
        }
    
        // ... 执行一些实际的业务逻辑 ...
    
        // 灾难的根源:每次 Reconcile 都无脑更新时间戳
        instance.Status.LastReconciledTime = metav1.Now()
        instance.Status.Phase = "Running"
    
        if err := r.Status().Update(ctx, &instance); err != nil {
            return ctrl.Result{}, err
        }
    
        return ctrl.Result{}, nil
    }
    

    致命代码片段 2:毫无防备的 Watch 注册

    func (r *AppConfigReconciler) SetupWithManager(mgr ctrl.Manager) error {
        return ctrl.NewControllerManagedBy(mgr).
            For(&bizv1.AppConfig{}). // 没有任何 Predicate 过滤
            Complete(r)
    }
    

    底层原理解析:为什么会死循环?

    在 Kubernetes 的架构中,任何对 Object 的修改(无论是 Spec 还是 Status,甚至是 Annotations 的变动),都会导致该 Object 的 ResourceVersion 发生改变。

    当这段代码执行 r.Status().Update() 时,底层发生了什么?

    1. APIServer 接收到更新请求,持久化到 etcd,并生成一个新的 ResourceVersion

    2. Operator 内部的 Reflector 通过 List-Watch 机制感知到这个变更,将带有新 ResourceVersion 的对象推入 DeltaFIFO

    3. Informer 处理这个 Delta 事件,更新本地 Indexer 缓存,并触发 Update 事件回调。

    4. 由于 SetupWithManager 中没有配置任何过滤条件,这个 Update 事件被原封不动地转换成了一条针对该 NamespacedName 的 Reconcile Request,塞进 WorkQueue

    5. Worker 协程从队列中取出 Request,再次执行 Reconcile

    6. Reconcile 中又执行了 metav1.Now() 生成了全新的时间戳,再次发起 Update

    死循环正式确立。 Operator 的 CPU 飙升,APIServer 的连接池被耗尽,etcd 疯狂刷盘写 WAL,最终整个 K8S 控制平面的响应能力被拖垮。

    破局与防御性编程实践

    修复这个 Bug 只需要两步,但更重要的是建立防御性编程的思维。

    1. 引入 GenerationChangedPredicate 拦截无效事件SetupWithManager 中,必须明确告诉 Controller:我只关心 Spec 的变化,不关心 Status 的变化。Kubernetes 通过 metadata.generationmetadata.resourceVersion 来区分这一点。修改 Spec 会自增 generation,而仅修改 Status 只会改变 resourceVersion

    import "sigs.k8s.io/controller-runtime/pkg/predicate"
    
    func (r *AppConfigReconciler) SetupWithManager(mgr ctrl.Manager) error {
        return ctrl.NewControllerManagedBy(mgr).
            For(&bizv1.AppConfig{}, builder.WithPredicates(predicate.GenerationChangedPredicate{})).
            Complete(r)
    }
    

    注:如果你的 Controller 需要响应 Annotation 或 Label 的变化,不能简单使用 GenerationChangedPredicate,需要自定义 Predicate 逻辑。

    2. 状态对比,拒绝盲目 Update 不要在 Reconcile 中无脑塞 metav1.Now()。状态是用来反映资源当前真实情况的,不是用来做心跳上报的。在调用 Update 之前,必须做 DeepEqual 或者状态哈希校验,只有真正发生变化时才发起网络请求。

    // 好的实践:对比新老状态
    oldStatus := instance.Status.DeepCopy()
    
    // ... 计算新的 status ...
    instance.Status.Phase = "Running"
    // 取消无意义的 LastReconciledTime 更新
    
    if !reflect.DeepEqual(oldStatus, &instance.Status) {
        if err := r.Status().Update(ctx, &instance); err != nil {
            return ctrl.Result{}, err
        }
    }
    

    3. 利用 Client-Side Rate Limiter 兜底 哪怕业务逻辑写出了死循环,也绝不能把底层的 APIServer 打挂。在实例化 Manager 时,应当配置合理的限速器(RateLimiter),控制入队重试的指数退避频率和最大 QPS。

    排查清单:Operator Reconcile 性能与死循环速查

    1. APIServer QPS 异常突增定位: 优先检查 Prometheus apiserver_request_total 指标,按 resourceverb 分组,找出请求量异常的 CRD 和操作类型(通常是 UPDATE / PATCH status)。

    2. Controller 队列深度监控: 观察 workqueue_depthworkqueue_adds_total 指标。如果某个 Controller 的 adds_total 呈陡峭直线飙升,必然存在 Reconcile 死循环。

    3. 检查 Event Predicate 配置: 确认 SetupWithManager 是否使用了 GenerationChangedPredicate,或者是否在自定义的 Update Func 中过滤掉了 oldObj.ResourceVersion == newObj.ResourceVersion 的无效事件。

    4. 排查 Informer Cache 穿透: 绝对禁止在 Reconcile 中使用 r.Client.Get 获取对象后,直接在原对象指针上修改并绕过 Client 调用。如果强行修改 informer 缓存的对象而不提交到 APIServer,会导致本地缓存污染和不可预期的异常。始终对拿到的对象做 DeepCopy

    5. CRD Subresource 配置核对: 检查 CRD 的 YAML 定义中是否启用了 subresources: status。如果没有启用,对 Status 的更新会被当作对主对象的更新处理,极易引发锁冲突和额外的业务级混乱。

  • K8S 控制平面性能调优实战:如何拯救被 List-Watch 击穿的 etcd 集群

    大规模 K8S 集群中,90% 的控制平面雪崩源于野蛮的 List 请求击穿 APIServer 缓存并耗尽 etcd 磁盘 IO。本文通过配置 APF 阻断高频穿透请求,结合 etcd WAL 磁盘物理隔离与参数调优,彻底解决控制平面高延迟与假死问题。

    案发现场:慢如老牛的 APIServer 与崩溃的 etcd

    某次集群(K8S v1.26.5, etcd v3.5.7)规模扩容至 500+ Node、20000+ Pod 后,控制平面出现剧烈抖动。具体表现为:kubectl 响应极慢甚至经常 Timeout,新 Pod 处于 ContainerCreating 状态长达数分钟无法调度。

    直切要害,先看 APIServer 报错日志:

    W0824 10:12:35.123456       1 request.go:1085] Request takes too long: type=list, resource=pods, user=system:serviceaccount:monitoring:custom-operator...
    

    转头去拉 etcd 的日志,标准的重载现象:

    {"level":"warn","ts":"...","caller":"etcdserver/server.go:872","msg":"apply request took too long","took":"543.2ms","expected-duration":"100ms","prefix":"k8s.io/pods/..."}
    {"level":"warn","ts":"...","caller":"wal/wal.go:783","msg":"sync duration of file 485.4ms, expected duration is <10ms"}
    

    通过 PromQL 看一眼核心指标:

    # 查看 etcd WAL fsync 99线延迟
    histogram_quantile(0.99, rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m]))
    

    查询结果显示 fsync 99线延迟竟然飙到了 600ms 以上。正常基于 NVMe SSD 的集群,这个值不该超过 10ms。控制面板的瓶颈已经很清晰了:底层 etcd 的 IO 被彻底打爆,导致 Quorum 写入超时,上层 APIServer 出现堆积。

    为什么一个外围的 Operator 能轻易干碎底层 etcd?

    在排查过程中,通过开启 APIServer 的审计日志(Audit Log),发现元凶是某个业务团队自己写的 custom-operator。它每隔几秒钟就在全局范围内发起针对 Pod 和 ConfigMap 的全量 List 操作。

    这里必须讲一下 K8S APIServer 处理 List 请求的底层逻辑。很多人以为 APIServer 有本地 Cache,所有的读请求都不会对 etcd 造成压力。这是典型的只知其一不知其二。

    当客户端发起 List 请求时,决定是否命中 APIServer 缓存的关键在于 ResourceVersionLimit 参数:

    1. ResourceVersion="0":直接从 APIServer 本地 Cache 读取数据,对 etcd 无影响,速度最快。

    2. ResourceVersion="" (未设置):默认行为,要求保证强一致性(Quorum Read)。APIServer 必须穿透缓存,向 etcd 发起请求以获取最新数据。在数据量庞大的集群中,这种全量拉取不仅消耗 etcd CPU 和内存,还会挤占网络带宽。

    3. 未设置分页参数 (Limit / Continue):如果单次拉取的数据集达到数百 MB,APIServer 在反序列化时会造成巨大的 CPU 飙升和内存消耗(OOM 诱因)。

    当时的那个 custom-operator,用的是旧版 client-go,且写法极其粗暴,未走 Informer 机制(基于 Watch 维护本地 Cache),而是直接调用原生 Client 的 List 方法,并且未带任何缓存容忍参数。这就是典型的“一脚油门把 etcd 踹进火葬场”。

    调优实战:防穿透与底层 IO 隔离

    既然找到了问题,处理思路就很直接:上层限流,底层扩容 IO

    1. APIServer 侧:启用 APF(API Priority and Fairness)进行流控

    绝对不要指望业务开发能立刻改掉拉垮的代码,运维必须从架构层面自保。K8S 自带的 API 优先级和公平性(APF)就是用来防这类 DDoS 的。

    针对这个惹祸的 Operator,我们专门下发一个 FlowSchemaPriorityLevelConfiguration 来压制它的并发数:

    # 1. 定义并发等级:限制最多只能有 2 个并发,超出直接拒绝或排队
    apiVersion: flowcontrol.apiserver.k8s.io/v1beta3
    kind: PriorityLevelConfiguration
    metadata:
      name: limit-custom-operator
    spec:
      type: Limited
      limited:
        assuredConcurrencyShares: 5
        limitResponse:
          type: Reject # 超过限额直接拒绝,不排队,快速失败
    ---
    # 2. 匹配肇事的 ServiceAccount 规则
    apiVersion: flowcontrol.apiserver.k8s.io/v1beta3
    kind: FlowSchema
    metadata:
      name: restrict-custom-operator
    spec:
      priorityLevelConfiguration:
        name: limit-custom-operator
      matchingPrecedence: 100
      rules:
      - subjects:
        - kind: ServiceAccount
          serviceAccount:
            name: custom-operator
            namespace: monitoring
        resourceRules:
        - apiGroups: ["*"]
          resources: ["pods", "configmaps"]
          verbs: ["list"]
    

    应用该策略后,该 Operator 的高频穿透读被直接按死在 APIServer 层,返回 429 Too Many Requests,etcd 的负载曲线立刻呈断崖式下降。

    2. etcd 侧:WAL 与数据盘的物理隔离

    虽然拦住了异常流量,但 etcd fsync 延迟对磁盘波动的敏感度依然极高。默认情况下,etcd 的 WAL(预写日志)和 db 数据文件都在同一块盘上。 etcd 处理一次写请求的路径是:收到请求 -> Append WAL -> fsync 落盘 -> 应用到状态机 -> 返回。如果 fsync 慢,整个集群的写入就慢。

    在生产环境中,必须将 WAL 剥离到单独的极速盘(最好是基于 PCIe 的 NVMe SSD,不与其他任何 IO 混用)。

    操作步骤: 假设新的高性能盘挂载点为 /data/etcd-wal

    1. 停止 etcd 进程。

    2. 迁移原有的 WAL 目录: bash mv /var/lib/etcd/member/wal/* /data/etcd-wal/ rm -rf /var/lib/etcd/member/wal ln -s /data/etcd-wal /var/lib/etcd/member/wal

    3. 调整文件系统挂载参数。在 /etc/fstab 中,确保存储 etcd 数据的磁盘禁用 atime 记录,减少无用元数据更新: text /dev/nvme1n1 /data/etcd-wal ext4 defaults,noatime,nodiratime,barrier=0 0 0
    4. 启动 etcd。

    3. etcd 参数调优(缓解大对象写入)

    除了存储隔离,对于 v3.5 版本的 etcd,我们还需调整以下参数,提升其在高并发场景下的生命力:

    • --snapshot-count=10000:默认 100000 次修改才做一次快照。将其调低,减少每次构建快照的内存消耗和 IO 瞬时突增。

    • --quota-backend-bytes=8589934592:默认 2G,大集群极易触顶导致 alarm:NOSPACE,直接拉满到 8G(官方建议最大上限)。

    • 开启自动压缩:--auto-compaction-retention=1 / --auto-compaction-mode=periodic,每小时清理一次历史版本,防止库文件无限膨胀。

    常见问题

    Q: APF 配置把业务请求拦掉了,业务跑异常了怎么办? A: 运维的底线是保证控制平面的可用性,而不是为烂代码买单。如果是 List 被限流返回 429,业务应该在代码中实现退避重试(Exponential Backoff),最根本的解决方法是改写代码,使用 client-go 的 SharedInformerFactory,基于 List-Watch 机制消费本地内存数据,绝不允许将 APIServer 当作通用数据库高频乱查。

    Q: 为什么 etcd 报 NOSPACE,但我看了下磁盘空间还有很多剩余? A: 这是个经典的认知误区。etcd 的 NOSPACE 通常指的不是宿主机的磁盘满了,而是 etcd 的 DB 文件大小达到了 --quota-backend-bytes 设置的硬上限(默认 2GB)。解决办法:首先用 etcdctl compact 压缩历史版本,然后执行 etcdctl defrag 释放存储碎片,最后视情况修改启动参数提高 Quota 值。

    Q: APIServer 的参数配置里,--max-requests-inflight 和 APF 有什么区别? A: --max-requests-inflight(及其相关的 mutating 参数)是全局并发限制,属于一刀切的限流。一旦触发阈值,不论是关键的 Controller 还是无用的旁路脚本,都会被无差别丢弃。而 APF 是精细化流控,支持根据资源类型、User、Namespace 等对请求进行分类、排队和熔断。在较新的 K8S 版本中,APF 是更推荐且更核心的防灾手段。

  • Jenkins K8S 动态 Agent 疯狂重启劫难:被隐式降级击穿的 JNLP 通信防线

    某次排查过程中,核心业务线的 CI/CD 流水线彻底瘫痪,Jenkins 任务队列(Queue)积压突破 500。与此同时,底层 Kubernetes 集群告警群炸锅,API Server 出现严重的请求限流(Throttling),P99 延迟飙升至 3 秒以上。

    最终排查结论:架构团队在做 Jenkins 迁移与高可用改造时,仅配置了 Layer 7 的 Ingress 规则,却遗漏了 Jenkins Remoting 通信依赖的 Layer 4 TCP(50000)端口。导致 K8S 动态 Agent Pod 启动后无法与 Master 建立 JNLP 连接。Jenkins Kubernetes 插件因此陷入了致命的“申请 Pod -> Agent 注册超时 -> 销毁 Pod -> 无限重试”死循环,硬生生把集群 API Server 给打穿了。

    把 Jenkins 当成一个普通的无状态 Web 服务去搞云原生改造,而不去深究其底层 Master-Agent 的心跳与通信模型,这种粗暴的操作在生产环境中是极其致命的。

    案发现场:失控的调度器与死亡循环

    接到报障后,第一时间登录集群查看资源状态。终端里的现象令人窒息:

    $ kubectl get pods -n jenkins | grep jnlp-agent | wc -l
    842
    
    $ kubectl get pods -n jenkins | grep jnlp-agent | head -n 5
    jnlp-agent-8f73b-5x9qp   0/1     ContainerCreating   0          12s
    jnlp-agent-8f73b-9m2kx   1/1     Terminating         0          1m45s
    jnlp-agent-8f73b-p2v1l   0/1     ContainerCreating   0          8s
    jnlp-agent-8f73b-x8c4d   1/1     Terminating         0          1m45s
    

    数百个 Agent Pod 处于 ContainerCreatingTerminating 状态。再去查看 Jenkins Master 的系统日志,满屏都是类似下面的报错:

    INFO: Kubernetes pod jnlp-agent-8f73b-9m2kx started
    WARNING: Failed to connect to agent jnlp-agent-8f73b-9m2kx within 100 seconds. 
    INFO: Terminating node jnlp-agent-8f73b-9m2kx
    INFO: Queue task #4023 still pending, provisioning a new agent...
    

    转头查看其中一个 Agent Pod 的内部日志,终于抓到了真凶:

    INFO: Locating server among [https://jenkins.company.com/]
    WARNING: Failed to connect to https://jenkins.company.com/tcpSlaveAgentListener/: Connection refused
    java.net.ConnectException: Connection refused
        at sun.nio.ch.SocketChannelImpl.checkConnect(Native Method)
    ...
    INFO: Retrying in 10 seconds
    

    深度剖析:为什么缺少一个端口会导致雪崩?

    要理解这个故障,必须理清 Jenkins Kubernetes Plugin 的工作状态机。这绝不只是一个“网络不通”的简单 Bug,而是一个典型的分布式状态机不同步导致的雪崩。

    1. Remoting 协议的固执:Jenkins Master 与 Agent 之间的通信基于 Jenkins Remoting 协议,这是一个重度依赖序列化与长连接的 Java 二进制协议。默认情况下,Agent 启动后,会先通过 HTTP(S) 请求 Master 的主入口,获取 X-Jenkins-CLI-Port 或相关 TCP 端口信息(通常是 50000),随后尝试建立直连 TCP 通道。

    2. L7 Ingress 的拦截:改造期间,Jenkins Master 被放到了 Nginx Ingress 后端。Ingress 默认只处理 HTTP/HTTPS 协议(L7)。当 Agent 尝试向 jenkins.company.com:50000 建立 TCP 握手时,流量直接在网关层被丢弃或拒绝。

    3. 致命的机制错位(State Mismatch)

    4. K8S 视角:Pod 已经成功拉起,容器状态是 Running,K8S 认为任务完成。
    5. Jenkins 视角:向 K8S 发送了 Pod 创建请求,且等待 Agent 进程发起 JNLP 注册回调。
    6. 死循环触发:等待 100 秒后(默认超时时间),Jenkins Master 依然没收到 Agent 的 JNLP 注册心跳。它不仅不会认为是自己的网络配置问题,反而会固执地判定:“这个 Pod 死掉了,为了满足队列里等待的构建任务,我必须销毁它,并向 K8S 申请一个新的 Pod。”

    当并发构建任务达到 50 个,每个任务都在触发这种“申请 -> 等待 -> 销毁 -> 再申请”的循环时,K8S 的 kube-apiserver 就成了重灾区。大量的 POST /api/v1/namespaces/jenkins/podsDELETE 请求瞬间填满了 API Server 的队列,触发限流,进而影响整个集群内其他核心业务 Pod 的调度与扩缩容。

    解决方案与防御性配置

    针对此类问题,修复网络通信只是第一步,更重要的是在架构层面加上防御性兜底限制。

    1. 拥抱 WebSocket,抛弃底层 TCP 直连

    既然 L4 暴露配置繁琐且容易在各种负载均衡器上踩坑,最优雅的做法是直接让 JNLP 流量复用 HTTP(S) 的 L7 通道。从 Jenkins 2.217 开始,Remoting 已经原生支持 WebSocket。

    在 JCasC (Jenkins Configuration as Code) 的配置中,必须在 K8S Cloud 配置项里显式开启 webSocket: true

    jenkins:
      clouds:
        - kubernetes:
            name: "kubernetes"
            # 直接走集群内部 DNS 通信,绕过外部 Ingress,降低网络开销与故障点
            serverUrl: "https://kubernetes.default"
            namespace: "jenkins-agents"
            jenkinsUrl: "http://jenkins-master.jenkins.svc.cluster.local:8080"
            # 开启 WebSocket,彻底解决 TCP 50000 端口穿透问题
            webSocket: true
            # 【防御性编程核心】设置全局容量上限,哪怕死循环也不会打穿 API Server
            containerCapStr: "100" 
    

    2. 配置 Kubernetes Plugin 的防雪崩限制

    永远不要假设外部系统会乖乖按预期工作。必须给 Jenkins 向 K8S 索要资源的行为加上硬性枷锁:

    • containerCapStr: 限制整个 K8S Cloud 并发存活的 Agent 总数。

    • 在每个 podTemplate 级别设置 instanceCap:防止单一异常的 Pipeline 把所有集群资源耗尽。

    3. 剥离通信链路(Cluster Internal Routing)

    如果你只是在同一个 K8S 集群内部署 Jenkins Master 和调度 Agent,Agent 连接 Master 绝对不应该 绕一圈跑到外网 Ingress 再进来。不仅增加延迟,还多引入了一层网络设备的故障风险。 强制在 jenkinsUrl 中使用 K8S 内部的 FQDN:http://..svc.cluster.local:

    排查清单与同类问题速查

    如果你也遇到了 Jenkins Agent 疯狂重启或一直在 Pending/Terminating 之间横跳,请核对以下清单:

    1. 排查 JNLP 握手阻断:查看 Agent Pod 的日志。如果出现 Connection refusedConnection timed out,且指向 Master 的 50000 端口,立刻检查安全组、网络策略 (NetworkPolicy) 或 LoadBalancer 的 L4 暴露情况,或者直接开启 WebSocket。

    2. 检查 Jenkins Master URL 配置:如果 Manage Jenkins -> System -> Jenkins URL 配置错误,Agent 会拿到一个无法解析的地址。在 K8S 环境下,尽量在 Cloud 配置的 jenkinsUrl 中覆盖并强制指定 ClusterIP 或内部 DNS。

    3. 监控 ContainerCap 触顶情况:如果在 Jenkins 侧看到任务一直卡在 ‘Jenkins’ doesn’t have label ‘xxx’ 或者 Waiting for next available executor,但没有看到新 Pod 创建,检查系统日志确认是否触发了 containerCap 上限。

    4. 防御性兜底检查:确认有没有恶意的 Groovy 脚本在无限触发重试。检查 Pipeline 里的 retry() 块逻辑是否包含了环境构建阶段,避免因业务代码逻辑错误引发基础设施级别的 Ddos 攻击。