Harness Delegate 部署与配置指南：Kubernetes 环境下的 CI/CD 代理实践

1. 先搞清楚 Harness Agent 到底解决什么实际问题Harness Agent 不是一个独立的新技术而是 Harness 持续交付平台中的一个核心执行组件。如果你在搜索“Harness Agent 入门”大概率是遇到了这几个场景公司开始用 Harness 做 CI/CD你需要部署 Agent或者你在本地想搭建一个完整的 Harness 环境来学习再或者你发现 Jenkins 等传统工具在复杂流水线、多云部署和 GitOps 实践中有些力不从心想看看 Harness 这类现代平台是怎么做的。它的核心价值非常直接把你在 Harness SaaS 控制台Harness Manager上定义的流水线、部署、安全扫描等任务安全、可靠地在你指定的环境比如你自己的服务器、Kubernetes 集群、甚至虚拟机中执行起来。你可以把它理解为一个“远程执行器”或“工作节点”。没有 Agent你的任务定义就只是一张图纸有了 Agent图纸才能变成实际的建筑。所以这篇文章不是讲一个泛泛的“Agent”概念而是聚焦于Harness Platform 中的 Delegates代理这是 Harness 官方对 Agent 的称呼。搞清楚这一点能让你少走很多弯路因为很多混淆都源于把“Agent”当成了一个通用工具而没意识到它是 Harness 特定架构的一部分。对于刚接触的人最该关心的不是它有多少高级功能而是三个最实际的问题它怎么装在什么系统上需要什么前置条件装完怎么通如何验证它和 Harness SaaS 平台连接成功了通了之后怎么用最基本的流水线任务是怎么下发过来并执行的下面我们就从零开始把这三点彻底拆清楚。1.1 Harness 架构中的 Delegate 是什么角色在深入操作前花两分钟理解架构能避免后续很多困惑。Harness 采用了一种中心-边缘的模型Harness Manager (中心)这是你通过浏览器访问的 SaaS 控制台app.harness.io。在这里你定义一切项目、服务、环境、流水线、机密、云提供商连接等等。Harness Delegate (边缘/代理)这是一个轻量级的软件包你需要把它安装在你自己的基础设施中比如你的数据中心、公有云 VM 或 Kubernetes 集群里。它负责执行 Manager 下发的任务。它们之间通过出站Outbound连接通信这意味着Delegate 主动去连接 Harness 的云端服务而不是 Harness 主动连接你的内部网络。这种设计有两个巨大好处安全性你不需要在防火墙上为 Harness 开放任何入站端口Delegate 通过安全的、认证过的通道“打电话回家”。网络穿透Delegate 可以部署在防火墙后、私有子网甚至隔离的网络区域只要它能访问互联网和需要部署的目标资源如你的 K8s 集群、云 API即可。Delegate 不是单体的你可以根据需要在不同环境开发、测试、生产、不同区域美东、欧中或不同集群中部署多个 Delegate形成 Delegate 组Delegate Group实现任务的负载均衡和隔离。1.2 为什么你需要关心 Delegate 的版本和类型输入材料里提到了“2026最新版”这是一个需要谨慎对待的说法。Harness Delegate 的更新非常频繁几乎每周都有新版本。盲目追求“最新”可能引入不稳定性尤其是在生产环境。更务实的做法是与你使用的 Harness SaaS 平台版本保持兼容。通常Harness 后台会提示推荐或必需的 Delegate 版本。在安装时你会通过一个包含特定版本号的 Docker 镜像或 Kubernetes YAML 文件来部署。Delegate 主要有两种安装类型选择哪种取决于你的目标环境Docker 容器最适合在单台 Linux 虚拟机或服务器上快速启动。简单但高可用性需要你自己维护例如通过进程监控或编排工具。Kubernetes 集群这是生产环境的推荐方式。通过一个 YAML 文件部署为 Kubernetes 的StatefulSet或Deployment天然具备高可用、自愈和扩缩容能力。对于绝大多数学习和初期生产场景Kubernetes 部署方式是首选也是官方文档最侧重的。接下来的实操我们也将以 Kubernetes 方式为主线。2. 动手之前准备好你的 Kubernetes 环境在运行任何安装命令之前准备工作决定了成功率。很多人卡住不是因为 Delegate 复杂而是基础环境没配好。2.1 集群环境检查清单你需要一个可以操作的 Kubernetes 集群。可以是本地的 Minikube、Kind、K3s也可以是云上的 EKS、GKE、AKS。无论哪种请按顺序检查以下项目kubectl 配置与权限# 确认当前上下文指向正确的集群 kubectl config current-context # 测试基本命令权限 kubectl get nodes kubectl get pods -n default如果这些命令能成功执行说明你的kubectl已正确配置并拥有足够权限。务必在安装 Delegate 的命名空间Namespace里拥有cluster-admin或等效的创建StatefulSet、ServiceAccount、ClusterRoleBinding等资源的权限。集群资源要求CPU/内存一个 Delegate Pod 的默认请求Request大约是 0.5 核 CPU 和 1Gi 内存。对于学习和测试集群有 2 核 4Gi 可供调度就足够。生产环境根据任务并发量调整。存储Delegate 需要挂载一个空目录emptyDir来存放临时数据和工作日志不需要持久化卷PVC。确保节点有可用磁盘空间。网络Pod 需要能访问互联网出站以连接app.harness.io和拉取公共容器镜像如docker.iogcr.io。镜像拉取关键 Delegate 镜像通常托管在公共仓库如docker.io/harness/delegate。确保你的集群节点有权限拉取。如果处在内网或受限环境你可能需要先将镜像同步到私有仓库并修改部署 YAML 中的镜像地址。2.2 从 Harness 平台获取唯一的安装令牌这是连接 Delegate 和 Harness Manager 的“钥匙”每个 Harness 账号或项目都是唯一的。绝对不要使用从网上随便找到的 YAML 文件里的旧令牌。获取步骤登录你的 Harness SaaS 控制台 (app.harness.io)。进入“项目设置”Project Setup-“Delegates”。点击“ Delegate”按钮。在安装向导中选择“Kubernetes”作为部署平台。系统会生成一段完整的 YAML 配置。其中最关键的一行是环境变量- name: ACCOUNT_ID value: your_account_id - name: MANAGER_HOST_AND_PORT value: https://app.harness.io - name: DELEGATE_TOKEN value: your_unique_delegate_token_here # 这是密钥这个DELEGATE_TOKEN就是你的安装令牌。整个 YAML 文件已经预配置了你的账户信息、Delegate 名称和令牌。重要经验把这个 YAML 文件下载或复制保存到本地例如harness-delegate.yaml。你之后的所有安装都基于这个文件。如果令牌泄露或需要轮换可以在平台上使旧令牌失效并生成新的。3. 核心实操在 Kubernetes 中部署并验证 Delegate拿到 YAML 文件后我们进入部署环节。这个过程看似简单但验证步骤才是关键。3.1 执行部署命令与初始状态检查假设你保存的 YAML 文件名为harness-delegate.yaml。创建命名空间可选但推荐 为 Delegate 创建一个独立的命名空间便于资源管理。kubectl create namespace harness-delegate在应用 YAML 前确保kubectl上下文切换到这个命名空间或者修改 YAML 中所有的namespace: harness-delegate。应用 YAML 部署kubectl apply -f harness-delegate.yaml这条命令会创建一系列资源ServiceAccount、ClusterRoleBinding、Secret存放令牌、StatefulSet等。观察 Pod 启动状态kubectl get pods -n harness-delegate -w使用-w参数可以实时观察状态变化。正常情况下你会看到 Pod 经历ContainerCreating-Running。整个过程可能需要 1-3 分钟因为要拉取镜像并启动容器。检查 Pod 详情和日志 当 Pod 状态变为Running后立即查看其日志这是判断连接是否成功的第一步。# 获取 Pod 名称 kubectl get pods -n harness-delegate # 查看日志关注开头部分 kubectl logs -f delegate-pod-name -n harness-delegate成功的关键日志行寻找类似“Delegate started”或“Heartbeat sent”的信息。更明确的标志是看到 Delegate 向 Harness 发送心跳成功的日志。3.2 在 Harness 控制台验证连接状态Pod 在跑不代表万事大吉必须在 Harness Manager 上确认连接。回到 Harness 控制台的“Delegates”页面。你应该能看到一个新 Delegate 出现在列表中。它的状态会从“等待中”Waiting for connectivity逐渐变为“已连接”Connected并且“上次心跳时间”Last Heartbeat是几秒或几分钟前。点击这个 Delegate 的名字可以进入详情页看到它的容量、已分配任务、系统信息等。只有在这里看到状态为“已连接”Connected才证明 Delegate 部署真正成功。如果一直显示“等待中”或“未连接”就需要回到上一步的 Pod 日志中排查问题。3.3 运行第一个测试任务验证连接后最直接的测试是让这个 Delegate 执行一个简单任务。在 Harness 控制台创建一个新的“流水线”Pipeline或使用已有的。添加一个“阶段”Stage类型选择“构建”Build或“部署”Deploy。在该阶段内添加一个“步骤”Step选择最简单的“Shell 脚本”Shell Script。在 Shell 脚本步骤的配置中你会看到一个“Delegate 选择器”Delegate Selector的选项。这里可以选择你刚部署的 Delegate 所在的组默认组名通常在 YAML 的DELEGATE_NAME环境变量中体现。在脚本框中输入echo “Hello from Harness Delegate on $(hostname)”。运行这个流水线。如果配置正确该任务会被调度到你指定的 Delegate 上执行。你可以在流水线执行详情中看到日志输出里面会包含 Delegate Pod 的主机名。同时在 Delegate 的详情页“任务”Tasks列表里也会出现这个已完成的任务。走到这一步你的 Harness Agent (Delegate) 从安装到运行第一个任务的完整通路就彻底打通了。4. 从“能用”到“用好”配置、排查与进阶理解让 Delegate 跑起来只是第一步。要让它稳定、高效地工作还需要理解一些关键配置和常见问题。4.1 关键配置项解析与调优建议部署 YAML 中有几个环境变量值得特别关注环境变量默认/示例值作用与调优建议DELEGATE_NAMEmy-k8s-delegateDelegate 名称用于在控制台标识。命名要有意义如prod-us-east-1-delegate。DELEGATE_TYPEKUBERNETES部署类型通常自动设置勿改。DELEGATE_NAMESPACEharness-delegatePod 所在的命名空间。确保与kubectl apply时指定的命名空间一致。INIT_SCRIPT(空)重要Delegate 启动前执行的 Shell 脚本。可用于安装特定工具如helm,kubectl特定版本、配置代理或导入证书。JAVA_OPTS-Xmx4gJVM 堆内存设置。如果任务需要更多内存如处理大型构建可以适当增加例如-Xmx8g。需同步调整 Pod 的 memory request/limit。HELM3_PATH,KUBECTL_PATH/opt/harness-delegate/...内置工具路径。通常使用默认值除非你通过INIT_SCRIPT安装了自定义版本。PROXY_*系列变量(空)如果你的网络需要通过代理访问外网需要配置PROXY_HOST,PROXY_PORT,PROXY_SCHEME,PROXY_USER,PROXY_PASSWORD等。LOG_STREAMING_SERVICE_URL(自动)日志流服务地址通常无需修改除非是自托管 Harness 平台。经验建议INIT_SCRIPT是神器如果你需要 Delegate 具备某些特定能力比如访问私有 Git 仓库的 SSH 密钥、特定版本的terraform不要尝试去修改 Delegate 镜像而是通过INIT_SCRIPT在启动时安装和配置。脚本内容会保存在一个ConfigMap中。资源限制务必为 Delegate 的 Pod 设置合适的resources.limits特别是内存防止单个任务耗尽资源影响其他任务或 Delegate 本身。高可用生产环境至少部署2 个或以上的 Delegate 副本通过修改 YAML 中StatefulSet的replicas并分布在不同节点上。Harness 会自动在可用的 Delegate 间进行任务负载均衡。4.2 常见问题与系统化排查路径当 Delegate 出现问题时不要盲目重装。按照以下顺序排查能快速定位大多数问题。问题现象Delegate 状态为“未连接”Disconnected或“等待中”。第一步查 Pod 状态和事件kubectl describe pod delegate-pod-name -n harness-delegate关注Events部分是否是镜像拉取失败ErrImagePull、调度失败FailedScheduling可能资源不足、容器启动错误第二步查 Pod 日志kubectl logs delegate-pod-name -n harness-delegate如果日志很少或没有可能是 Pod 根本没启动成功回到第一步。如果日志显示连接失败检查网络。Pod 能否访问app.harness.io或你的私有 Manager 地址是否需要配置代理如果日志显示令牌无效检查DELEGATE_TOKEN环境变量是否与平台生成的一致。令牌是否在平台上被意外撤销第三步检查集群网络策略如果使用了 KubernetesNetworkPolicy确保 Delegate Pod 所在的命名空间允许出站流量到互联网。问题现象任务在 Delegate 上执行失败但 Delegate 本身是连接的。第一步看任务执行日志在 Harness 流水线执行详情中查看失败步骤的日志。错误信息通常会直接指出原因如“命令未找到”、“权限被拒绝”、“连接超时”。第二步检查 Delegate 的工具链任务是否需要kubectl、helm、docker等工具这些工具是否已通过INIT_SCRIPT正确安装并位于PATH中可以在 Delegate 的INIT_SCRIPT里加上which kubectl这样的命令来验证。第三步检查 Delegate 到目标资源的权限这是最常见的问题之一。例如任务是要部署应用到另一个 K8s 集群。Delegate Pod 的ServiceAccount只有它所在集群的权限。你需要要么在 Delegate 上配置目标集群的 kubeconfig通过INIT_SCRIPT注入。要么在 Harness 中配置一个“云提供商”Cloud Provider连接使用该连接的任务Harness 会动态地将凭据注入到 Delegate 的执行环境中。问题现象任务排队时间长执行慢。检查 Delegate 负载在 Delegate 详情页查看“容量”和“已使用容量”。如果持续高负载考虑增加 Delegate 副本数或升级 Delegate 的资源配置。检查任务选择器确保你的流水线步骤正确选择了有处理能力的 Delegate 组。如果选择器太宽泛或太严格可能导致任务被错误地调度到繁忙或无法处理的 Delegate 上。4.3 理解 Delegate 与 CI/CD 流程的集成Delegate 是执行的基石但它的价值在与 Harness 其他概念集成时才完全体现与“连接器”Connectors配合当你配置一个 Git 连接器、Docker 仓库连接器或 K8s 集群连接器时Harness 会使用指定的 Delegate 去测试连接。这意味着 Delegate 必须能访问这些外部系统。与“机密”Secrets配合Harness 的加密机密可以在运行时注入到 Delegate 的执行环境中供脚本或工具使用避免了在脚本中硬编码密码。与“基础设施定义”Infrastructure Definition配合在部署阶段你需要指定目标环境如一个 K8s 命名空间。Harness 会使用被选中的 Delegate并应用相应的连接器凭据在该目标上执行kubectl apply等操作。一个核心心法Delegate 是“执行者”它在哪里任务就在哪里执行它有什么权限和工具任务就能用什么权限和工具。规划 Delegate 的部署位置和权限本质上就是在规划你的 CI/CD 流水线的执行边界和能力范围。5. 生产环境部署的考量与最佳实践如果你计划将 Harness Delegate 用于生产以下几个方面的考量至关重要。5.1 安全性加固最小权限原则为 Delegate 的ServiceAccount绑定最小必要的 KubernetesClusterRole。如果 Delegate 只需要在特定命名空间内操作就使用Role和RoleBinding而非ClusterRoleBinding。令牌管理定期轮换DELEGATE_TOKEN。在 Harness 平台上使旧令牌失效然后使用新令牌重新部署 Delegate采用蓝绿部署方式先启动新 Delegate再停用旧的。镜像安全从可信源Harness 官方容器仓库拉取镜像并定期更新到稳定版本。可以考虑使用私有镜像仓库并设置镜像拉取策略imagePullPolicy: Always或IfNotPresent。网络隔离将 Delegate 部署在专门的服务子网或命名空间中通过网络策略限制其不必要的网络访问。5.2 可靠性与可观测性多副本与反亲和性至少部署 2 个副本并通过podAntiAffinity配置确保它们分布在不同的物理节点上避免单点故障。# 在 StatefulSet spec.template.spec 中添加示例 affinity: podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchLabels: harness.io/name: my-delegate-group topologyKey: kubernetes.io/hostname资源监控为 Delegate 命名空间配置 Prometheus 监控和告警关注 Pod 重启次数、CPU/内存使用率、网络错误率等。日志聚合确保 Delegate Pod 的日志被集群的日志收集系统如 Fluentd、Fluent Bit采集并发送到中心化的日志平台如 Elasticsearch、Loki以便排查历史问题。5.3 维护与升级版本升级Harness 平台升级后可能会要求 Delegate 升级到兼容版本。升级流程通常是在平台生成新版本的 Delegate YAML采用滚动更新或蓝绿部署的方式替换旧版本。务必先在测试环境验证。日常健康检查除了 Harness 平台的心跳监控可以在集群内为 Delegate Pod 配置livenessProbe和readinessProbe使其能更好地与 Kubernetes 的生命周期管理集成。清理旧任务Delegate 会缓存一些任务数据。虽然 Harness 会管理大部分清理工作但在磁盘空间紧张的环境中可以定期检查 Delegate 工作目录的体积。部署和维护 Harness Delegate 是一个持续的过程。开始时专注于让它连通并执行简单任务随着使用的深入再逐步引入高可用、安全加固和监控。它的稳定性直接决定了你整个 CI/CD 流水线的可靠性值得投入时间将其配置妥当。