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是一个云原生的软件交付控制平面，核心定位是统一编排、统一管控、统一可观测，覆盖软件交付的全生命周期：

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%：

三、边界划分的核心原则与决策模型

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实现的差异，帮助大家快速判断：

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
其中：

• 当S < 6 S < 6S<6：优先用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 决策流程图