Harness与Agent SDK的边界划分：最佳实践

Harness与Agent SDK的边界划分：最佳实践引言在云原生软件交付的下半场，企业面临的核心矛盾已经从「有没有工具链」变成了「能不能把工具链用出价值」。作为全球领先的软件交付平台（SDP），Harness凭借开箱即用的CI/CD、Feature Flag、混沌工程、合规治理等能力，已经成为数千家企业统一DevOps流程的首选。但几乎所有使用Harness的企业都会遇到同一个灵魂拷问：哪些功能应该直接用Harness原生能力实现，哪些需要用Agent SDK做自定义扩展？边界划分不清的团队往往会陷入两个极端：要么过度依赖自定义脚本/SDK，把Harness当成了一个单纯的任务调度器，浪费了平台原生的可观测、合规、回滚、灰度等核心能力，还带来了极高的维护成本；要么强行用原生功能适配高度定制化的业务场景，写了上百行难以维护的YAML脚本，升级兼容性差，还满足不了内部系统的集成需求。本文基于我过去5年参与10+头部企业Harness落地的实践经验，从核心概念、划分原则、决策模型、实战案例、最佳实践等多个维度，系统讲解Harness与Agent SDK的边界划分方法，帮助团队最大化Harness的价值，同时把自定义扩展的成本降到最低。一、核心概念解析1.1 Harness核心平台：统一的交付控制平面Harness是一个云原生的软件交付控制平面，核心定位是统一编排、统一管控、统一可观测，覆盖软件交付的全生命周期：模块核心能力CI容器化构建、缓存优化、测试左移、依赖管理CD多环境部署、灰度发布、自动回滚、多集群管理Feature Flag灰度放量、A/B测试、故障止血、用户分群Chaos Engineering故障注入、容错验证、高可用评估Governance合规校验、流程管控、审计日志、RBAC权限SRM服务可靠性管理、变更影响分析、故障根因定位Harness平台的核心优势是开箱即用、免维护、安全合规，所有能力都经过了大规模生产环境验证，每两周迭代一次新版本，自带全球级的SLA保障。1.2 Harness Agent SDK：自定义扩展的开发框架Harness Agent SDK是官方提供的、用于开发自定义执行逻辑的开发工具包，支持Python、Go、Java、JavaScript等主流语言，核心能力包括：自定义Pipeline步骤：扩展Harness原生不支持的执行逻辑自定义执行器：对接自研的构建、部署、测试系统自定义控制器：实现个性化的灰度、回滚、扩容策略数据源扩展：把内部系统的 metrics、日志、事件同步到Harness可观测平台策略扩展：对接自研的合规、审批、安全扫描系统Agent SDK的核心定位是Harness控制平面在用户侧的延伸，负责执行Harness原生不覆盖的、和企业内部系统深度耦合的定制化逻辑。1.3 容易混淆的概念：Delegate vs Agent SDK很多团队会把Harness Delegate和Agent SDK搞混，这里明确边界：Delegate是Harness官方提供的通用执行代理，部署在用户的K8s集群/VM/私有云环境中，负责执行Harness原生的所有步骤，不需要用户开发Agent SDK是自定义扩展的开发框架，可以独立部署，也可以作为Delegate的插件运行，用于实现用户的个性化逻辑二、问题背景与边界不清的痛点2.1 问题背景企业选择Harness的核心诉求是统一异构的工具链，但几乎所有中大型企业都有大量自研的内部系统，比如：自研的镜像安全扫描、代码审计系统自研的变更审批、合规审计平台自研的配置中心、服务注册发现系统自研的灰度发布、流量控制组件边缘设备、专有硬件的部署管控系统这些系统和Harness的集成需求，是Agent SDK存在的核心原因，但如何平衡「原生能力复用」和「自定义扩展」就成了核心问题。2.2 边界不清的典型痛点我们统计了30家落地Harness的企业，边界不清带来的问题占所有Harness运维问题的68%：痛点影响占比过度自定义：把原生已经支持的逻辑用SDK重写开发成本高、升级不兼容、无法享受平台新特性32%过度依赖原生：用自定义脚本实现复杂业务逻辑脚本难以维护、调试困难、故障率高28%权责错位：把敏感信息、状态持久化放在SDK侧密钥泄露、数据丢失、合规风险22%重复建设：不同团队开发相同的SDK扩展资源浪费、标准不统一18%比如某头部电商团队，一开始把K8s部署逻辑用SDK重写，结果Harness每次升级都要修改SDK代码适配，光维护这个SDK每年就投入了1.5个工程师的人力，后来切换回原生CD模块，维护成本直接降到了0.1个工程师，还获得了原生的灰度、回滚、可观测能力。三、边界划分的核心原则与决策模型3.1 核心划分原则我们总结了5条边界划分的黄金原则，只要遵循这些原则，90%的场景都可以快速判断：原则1：控制平面与数据平面分离Harness永远做控制平面：负责配置管理、流程编排、权限管控、状态存储、可观测、合规审计Agent SDK永远做数据平面：负责无状态的逻辑执行、内部系统对接、自定义动作触发，不存储任何状态、不管理任何配置、不保存任何敏感信息原则2：通用能力下沉到平台，定制能力扩展到SDK所有通用的、行业标准的能力，只要Harness原生支持，就一定要用原生实现所有企业独有的、和内部系统深度耦合的能力，用SDK扩展实现原则3：安全合规优先所有敏感信息（密钥、证书、账号）必须存在Harness Secret Manager中，SDK只能调用，不能存储所有审计日志必须上报到Harness平台，SDK不能本地存储日志所有权限管控必须用Harness RBAC实现，SDK不能自己做权限校验原则4：运维成本最优优先选择开发成本、维护成本、升级成本最低的方案自定义逻辑的迭代频率越高，越适合放在SDK实现（SDK支持独立升级，不依赖Harness平台版本）原则5：可观测性统一所有执行状态、metrics、错误日志必须上报到Harness平台，SDK不能自己做可视化所有告警、通知必须用Harness原生的通知能力实现，SDK不能自己发告警3.2 核心属性对比表我们从10个维度对比Harness原生实现和Agent SDK实现的差异，帮助大家快速判断：维度Harness原生实现Agent SDK实现开发成本几乎为0，配置即可中等，需要开发测试维护成本极低，Harness官方负责维护中等，用户自己维护升级兼容性100%兼容，Harness官方负责适配高，基于稳定API，版本兼容可控安全合规原生满足SOC2、PCI、等保要求中等，需要用户自己保证逻辑合规可观测性原生全链路可观测，免配置高，需要手动上报数据到平台定制化程度低，仅支持官方提供的配置项极高，完全自定义内部系统集成能力低，仅支持官方集成的SaaS服务极高，支持所有内部系统对接迭代效率低，依赖Harness官方迭代周期高，随时可以发版升级性能中等，需要和平台交互高，本地执行，支持高并发SLA保障99.99%，Harness官方提供中等，用户自己保证可用性3.3 边界决策数学模型对于边界模糊的场景，我们可以用加权评分模型来量化决策：S = w 1 ∗ C + w 2 ∗ I + w 3 ∗ S r + w 4 ∗ O + w 5 ∗ F S = w_1*C + w_2*I + w_3*S_r + w_4*O + w_5*FS=w1​∗C+w2​∗I+w3​∗Sr​+w4​∗O+w5​∗F其中：变量定义取值范围权重C CC定制化程度：需求偏离通用场景的程度0-10分，越高越定制0.3I II内部集成度：需要对接内部自研系统的程度0-10分，越高对接越多0.2S r S_rSr​安全合规要求：对数据安全、审计的要求0-10分，越高要求越严0.2O OO运维成本：方案的长期运维成本0-10分，越高成本越低0.15F FF迭代频率：需求的更新频率0-10分，越高迭代越快0.15决策规则：当S 6 S 6S6：优先用Harness原生实现，或者原生自定义脚本当S = 6 S = 6S=6：优先用Agent SDK实现模型示例某金融企业需求：实现自定义的镜像扫描步骤，需要对接自研的等保合规扫描系统，扫描结果要同步到内部审计平台，每个季度都会更新扫描规则。我们来打分：C CC：定制化程度8分（完全自研的扫描规则，没有通用标准）I II：内部集成度9分（需要对接自研扫描系统、审计系统）S r S_rSr​：安全合规要求9分（金融等保要求，所有操作必须留痕）O OO：运维成本6分（SDK只需要对接API，维护成本低）F FF：迭代频率7分（每个季度更新规则）计算总分：S = 0.3 ∗ 8 + 0.2 ∗ 9 + 0.2 ∗ 9 + 0.15 ∗ 6 + 0.15 ∗ 7 = 2.4 + 1.8 + 1.8 + 0.9 + 1.05 = 7.95 = 6 S = 0.3*8 + 0.2*9 + 0.2*9 + 0.15*6 + 0.15*7 = 2.4 + 1.8 + 1.8 + 0.9 + 1.05 = 7.95 =6S=0.3∗8+0.2∗9+0.2∗9+0.15∗6+0.15∗7=2.4+1.8+1.8+0.9+1.05=7.95=6，所以应该用Agent SDK实现。3.4 决策流程图是是否