最近在帮团队搭建持续交付流水线时发现很多同学对 Harness 平台中的Agent组件理解不深配置起来总是磕磕绊绊要么连接不上要么权限不对网上资料又多是零散的官方文档翻译缺乏一个从零到一的完整闭环教程。本文将以Harness Delegate (Agent)为核心手把手带你完成从概念理解、环境准备、安装部署、到实战集成和深度排错的完整流程。无论你是刚接触 DevOps 的新手还是希望将 Harness 集成到现有企业环境中的架构师都能从本文中找到可直接复用的代码、配置和避坑指南。1. 背景与核心概念为什么需要 Harness Agent在深入实操之前我们必须先搞清楚几个核心问题Harness Agent 是什么它解决了什么痛点以及它在整个 Harness 平台中扮演什么角色1.1 什么是 Harness Delegate (Agent)你可以把Harness Delegate通常被简称为 Agent理解为一个安装在你的目标环境如你的 Kubernetes 集群、虚拟机或物理机中的“轻量级工作器”。它的核心职责是代表 Harness 平台在你的私有或隔离环境中执行任务。为什么需要它因为你的代码仓库如 GitLab、构建环境如 Jenkins 从节点、制品库如 Nexus、云环境如 AWS/Azure以及生产 Kubernetes 集群通常都位于企业防火墙之后或私有网络中。Harness 的 SaaS 控制台位于公网无法直接访问这些内部资源。此时Delegate 就成为了一个安全的“桥梁”或“信使”。核心工作流程Harness SaaS 平台将需要执行的任务如“从 Git 拉取代码”、“在 K8s 中部署应用”、“执行一个 Shell 脚本”放入一个队列。安装在你环境中的 Delegate 持续轮询这个队列领取属于它的任务。Delegate 在本地环境中执行该任务例如使用本地的kubectl连接集群。任务执行完毕后Delegate 将结果和日志回传给 Harness SaaS 平台。1.2 Harness Agent 的核心价值与场景安全隔离你的密钥、凭证、kubeconfig 等敏感信息永远不需要离开你的网络边界。Delegate 在本地使用这些凭证执行操作只将非敏感的日志和结果上报。网络穿透完美解决了 SaaS 控制台与内网资源无法直连的问题。环境适配你可以在不同的环境中安装不同的 Delegate如开发、测试、生产每个 Delegate 天然具备其所在环境的网络位置和上下文Harness 平台可以精准地将任务路由到对应的 Delegate。扩展性与负载均衡你可以在一个环境中安装多个相同的 Delegate它们会自动组成集群实现任务的高可用和负载均衡。常见应用场景持续集成 (CI)在自建的构建机VM/Bare Metal上运行构建、测试任务。持续交付 (CD)在目标 Kubernetes 集群或虚拟机环境中执行部署、回滚操作。云成本管理 (CCM)收集 AWS、Azure、GCP 等云环境的账单数据。特性标志 (FF)评估用户上下文决定是否开启某个特性。安全测试 (STO)在隔离环境中运行安全扫描工具。1.3 Harness Agent 与相关概念辨析Harness Agent 与 Jenkins Agent思想类似都是“主从”架构中的“从节点”。但 Harness Delegate 更轻量通常是一个容器或 Pod且与平台集成更紧密能自动发现和处理多种类型的任务CI/CD/CCM等。Harness 与 Agent 的关系Harness 是统一的 SaaS 平台提供 UI 和编排引擎Agent (Delegate) 是平台伸入用户环境中的“手”和“眼”。没有 AgentHarness 就无法操作你的内部资源。Delegate 与 Runner在一些其他 CI/CD 工具中可能有类似概念如 GitLab Runner。本质都是执行器但具体实现、通信协议和管理方式不同。理解了这些我们就知道安装和配置Harness Delegate是使用 Harness 平台几乎所有高级功能的前置必备步骤。2. 环境准备与安装规划在开始安装之前充分的规划能避免后续大量返工。本节将详细说明环境要求和安装策略。2.1 系统与环境要求Harness Delegate 非常灵活支持多种安装方式。你需要根据你的目标环境选择一种。安装方式推荐环境核心要求特点Kubernetes拥有 Kubernetes 集群K8s 1.19, ~2核CPU4GB内存10GB存储最推荐。以 Pod 形式运行易于管理、升级和扩展。Docker单台 Linux 虚拟机/物理机Docker 20.10, ~2核CPU4GB内存适合非 K8s 环境简单快捷。Helm ChartKubernetes 集群需 HelmHelm 3.2, K8s 1.19提供了更灵活的配置选项适合生产级定制。Linux 二进制无容器环境的 Linux 主机Systemd, ~2核CPU4GB内存最传统的安装方式适合高度受限的环境。通用要求网络出口Delegate 需要能访问 Harness SaaS 端点通常是*.harness.io,*.app.harness.io。请确保防火墙允许 HTTPS (443) 出口流量。如果环境需要代理Delegate 也支持配置。资源一个 Delegate 容器/Pod 建议分配至少2核 CPU和4GB 内存。对于执行大型构建或部署的任务需要酌情增加。标签 (Tags)在安装时或安装后可以为 Delegate 打上标签如env:prod,cloud:aws,purpose:cd。这是后续在 Harness 平台中选择由哪个 Delegate 执行任务的关键依据。2.2 安装策略一个还是多个如何选择单一通用 Delegate在小型团队或测试环境中可以在一个核心 Kubernetes 集群或虚拟机上安装一个 Delegate用它来处理所有环境Dev/Stage/Prod的任务。不推荐用于生产因为存在单点故障且任务隔离性差。按环境隔离推荐为开发、测试、生产环境分别安装独立的 Delegate并打上对应的标签如env:dev,env:prod。这样在 Harness 中创建“基础设施”时可以指定只有带有env:prod标签的 Delegate 才能访问生产集群安全又清晰。按功能隔离可以安装专门的 Delegate 用于 CI 构建打标签purpose:ci另一个用于 CD 部署打标签purpose:cd。高可用模式在同一个环境如生产 K8s 集群中安装2个或以上具有相同标签的 Delegate。Harness 会自动将它们组成集群实现负载均衡和故障转移。如果一个 Delegate 离线任务会自动被其他健康的 Delegate 接管。本文后续将以最常用的 Kubernetes (Docker-in-Docker) 和 Docker 安装方式为例进行详细演示。Helm 安装方式类似但提供了更多 Values 配置。3. 实战安装Kubernetes 篇我们将在一个已有的 Kubernetes 集群中安装 Harness Delegate。这是目前最主流和推荐的方式。3.1 获取唯一的 Delegate 令牌Delegate 需要凭据才能向 Harness 平台注册。这个凭据就是一个“令牌”。登录你的 Harness 平台。进入项目设置 (Project Setup)-Delegates。点击 New Delegate。选择Kubernetes作为安装类型。在出现的页面中Harness 会生成一个唯一的安装命令。其中包含了一个重要的环境变量DELEGATE_TOKEN。请妥善保管这个令牌值。它通常看起来像一串字母数字混合的字符串。3.2 准备 Kubernetes 安装清单Harness 提供了现成的 YAML 清单。在安装向导中你可以下载harness-delegate.yaml文件。让我们分析一下这个文件的核心部分# harness-delegate.yaml (关键部分摘录) apiVersion: v1 kind: Namespace metadata: name: harness-delegate-ng --- apiVersion: apps/v1 kind: Deployment metadata: name: harness-delegate namespace: harness-delegate-ng spec: replicas: 1 # 生产环境建议至少 2 以实现高可用 selector: matchLabels: harness.io/name: harness-delegate template: metadata: labels: harness.io/name: harness-delegate spec: containers: - image: harness/delegate:23.07.81507 # 版本号请使用向导中提供的最新版 imagePullPolicy: Always name: harness-delegate resources: limits: cpu: 2 memory: 4Gi requests: cpu: 1 memory: 2Gi env: - name: DELEGATE_TOKEN value: YOUR_UNIQUE_DELEGATE_TOKEN_HERE # -- 替换为你的令牌 - name: ACCOUNT_ID value: YOUR_HARNESS_ACCOUNT_ID - name: MANAGER_HOST_AND_PORT value: https://app.harness.io - name: DEPLOY_MODE value: KUBERNETES - name: DELEGATE_NAME value: my-k8s-delegate # -- 给你的Delegate起个名字 - name: DELEGATE_TYPE value: KUBERNETES - name: DELEGATE_TAGS value: env:dev,k8s # -- 打上标签多个用逗号分隔 - name: INIT_SCRIPT value: # 可以在此处填入初始化脚本 - name: HELM3_PATH value: /usr/local/bin/helm - name: KUBECTL_PATH value: /usr/local/bin/kubectl # ... 可能还有其他环境变量 securityContext: allowPrivilegeEscalation: false runAsUser: 65534 serviceAccountName: harness-delegate-sa --- # 还会包含相应的 ServiceAccount, Role, RoleBinding 等资源定义用于授权。关键配置解释DELEGATE_TOKEN:必须替换为你从平台获取的真实令牌。ACCOUNT_ID: 你的 Harness 账户 ID通常在安装命令中也已提供。DELEGATE_NAME: 在 Harness 平台上显示的名称具有唯一性。DELEGATE_TAGS:极其重要用于标识和选择此 Delegate。例如env:dev, cloud:aws, region:us-east-1。INIT_SCRIPT: 可以在 Delegate Pod 启动前执行自定义脚本例如安装特定工具。HELM3_PATH和KUBECTL_PATH: Delegate 镜像内已包含这些工具确保路径正确以便执行部署任务。3.3 执行安装并验证替换令牌用文本编辑器打开下载的harness-delegate.yaml找到DELEGATE_TOKEN环境变量将其值替换为你自己的令牌。可选自定义根据需要修改DELEGATE_NAME,DELEGATE_TAGS,replicas(高可用) 等。应用清单kubectl apply -f harness-delegate.yaml查看状态# 查看 Pod 是否运行 kubectl get pods -n harness-delegate-ng # 预期输出类似 # NAME READY STATUS RESTARTS AGE # harness-delegate-5dfc6f8d76-2xqjr 1/1 Running 0 2m # 查看 Delegate 日志 kubectl logs -f deployment/harness-delegate -n harness-delegate-ng在日志中你应看到Delegate started和Heartbeat sent等成功信息。平台验证等待1-2分钟后刷新 Harness 平台的Delegates页面。你应该能看到一个名为my-k8s-delegate或你指定的名字的 Delegate状态为Connected绿色勾选图标。点击它可以看到详细信息包括其 IP、标签和版本。恭喜你的第一个 Harness Kubernetes Delegate 已安装成功。4. 实战安装Docker 篇如果你的目标环境是单台 Linux 主机虚拟机或物理机Docker 安装是最快捷的方式。4.1 获取 Docker 安装命令与 K8s 安装类似在 Harness 平台的 Delegate 创建向导中选择Docker作为安装类型。平台会生成一条完整的docker run命令。4.2 解析与执行 Docker 命令生成的命令格式大致如下docker run --cpus2 --memory4g \ -e DELEGATE_NAMEdocker-delegate \ -e DELEGATE_TYPEDOCKER \ -e DELEGATE_TOKENYOUR_UNIQUE_DELEGATE_TOKEN_HERE \ -e ACCOUNT_IDYOUR_ACCOUNT_ID \ -e MANAGER_HOST_AND_PORThttps://app.harness.io \ -e DEPLOY_MODEKUBERNETES \ -e DELEGATE_TAGSenv:dev,docker \ -e LOG_STREAMING_SERVICE_URLhttps://app.harness.io/log-service/ \ -v /var/run/docker.sock:/var/run/docker.sock \ harness/delegate:23.07.81507关键参数解释--cpus和--memory限制容器资源。-e DELEGATE_TOKEN同样需要替换为你的令牌。-e DELEGATE_TAGS定义标签。-v /var/run/docker.sock:/var/run/docker.sock这是关键的一步。它将宿主机的 Docker 守护进程套接字挂载到容器内使得 Delegate 容器能够在宿主机上启动新的容器DinD - Docker in Docker。这是执行需要 Docker 的 CI 步骤如构建镜像所必需的。harness/delegate:23.07.81507Delegate 镜像请使用向导中提供的最新版本。安全注意挂载 Docker 套接字 (/var/run/docker.sock) 意味着该容器获得了宿主机的 root 权限。请确保只在受信任的环境中使用此方式并考虑使用非 root 用户运行 Docker 守护进程等安全加固措施。4.3 运行与验证复制完整的docker run命令到你的 Linux 主机终端。确保命令中的DELEGATE_TOKEN和ACCOUNT_ID是正确的。执行命令。使用docker ps查看容器是否运行。使用docker logs -f container_id查看日志确认连接成功。在 Harness 平台验证 Delegate 状态为Connected。5. 核心配置与集成实战Delegate 安装成功只是第一步。接下来我们要在 Harness 平台中使用它。5.1 在管道中使用 Delegate选择器 (Selectors)在 Harness 中创建 CI 流水线步骤或 CD 阶段时最关键的一步是指定“在哪个 Delegate 上运行”。在流水线步骤中当你添加一个“运行”步骤如“运行测试”、“构建并推送镜像”时在步骤配置的“高级”部分会有一个Delegate Selector的输入框。输入标签在此框中输入你在安装 Delegate 时设置的DELEGATE_TAGS中的一个或多个。例如输入env:dev。Harness 会自动选择所有带有env:dev标签的、状态为健康的 Delegate 来执行该步骤。选择策略如果有多个匹配的 DelegateHarness 会使用轮询策略分配任务。示例场景你有一个env:prod的 Delegate 运行在生产 K8s 集群一个env:dev的 Delegate 运行在开发集群。当部署生产流水线时在部署阶段的“Kubernetes 应用部署”步骤中将 Delegate Selector 设置为env:prod就能确保部署动作是由位于生产集群内部的 Delegate 执行的安全且网络通畅。5.2 为 Delegate 安装自定义工具Delegate 基础镜像包含常用工具kubectl, helm, git, docker-cli 等。但如果你需要特定版本的工具或额外的软件如jq,mvn,go,aws-cli有两种方法方法一使用 INIT_SCRIPT 环境变量推荐在 Delegate 的 YAML 或 Docker 命令中设置INIT_SCRIPT环境变量。该脚本会在 Delegate 进程启动前执行。env: - name: INIT_SCRIPT value: | apt-get update apt-get install -y jq python3-pip pip3 install awscli curl -LO https://dl.k8s.io/release/v1.27.0/bin/linux/amd64/kubectl install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl注意这会增加 Delegate 的启动时间。方法二构建自定义 Delegate 镜像对于更复杂或固定的工具集可以基于官方harness/delegate镜像创建 DockerfileFROM harness/delegate:23.07.81507 USER root RUN apt-get update apt-get install -y maven USER harness然后构建并推送镜像到你的私有仓库在安装时使用你的自定义镜像。5.3 配置网络代理如果 Delegate 所在环境需要通过代理服务器访问互联网需要配置代理变量。 在 Delegate 的 YAML 清单或 Docker 命令中添加以下环境变量env: - name: PROXY_HOST value: your.proxy.server - name: PROXY_PORT value: 3128 - name: PROXY_SCHEME value: http # 如果代理需要认证 - name: PROXY_USER value: username - name: PROXY_PASSWORD value: password6. 常见问题与深度排错指南即使按照步骤操作你也可能会遇到问题。以下是高频问题及排查思路。6.1 Delegate 状态为 “Disconnected” (未连接)这是最常见的问题。问题现象可能原因排查步骤与解决方案安装后一直未连接1. 网络不通。2.DELEGATE_TOKEN或ACCOUNT_ID错误。3. 防火墙/安全组阻止。4. 代理配置错误。1.查日志kubectl logs delegate-pod或docker logs container-id。看是否有Failed to connect或认证错误。2.测网络在 Delegate 所在主机执行curl -v https://app.harness.io或telnet app.harness.io 443。3.核验令牌去 Harness 平台 Delegate 页面点击“Connectivity Status”或“Troubleshoot”重新获取令牌并确认ACCOUNT_ID。4.检查代理如果使用代理确认PROXY_*环境变量正确无误。运行一段时间后断开1. 资源不足CPU/内存。2. 网络临时波动。3. Delegate Pod 被重启或驱逐。1.查资源kubectl describe pod delegate-pod看是否有OOMKilled或CPUThrottling事件。适当增加resources.limits。2.查事件kubectl get events -n harness-delegate-ng。3.高可用安装多个相同标签的 Delegate一个挂掉不影响任务执行。6.2 任务执行失败“No eligible delegates could be found”在流水线运行时步骤报此错误。问题现象可能原因排查步骤与解决方案步骤失败日志显示找不到 Delegate1. 步骤的 Delegate Selector 标签没有匹配的 Delegate。2. 匹配的 Delegate 状态不是 “Connected”。3. Delegate 资源耗尽无法接受新任务。1.核对标签检查失败步骤的 “Delegate Selector” 设置。去 Delegate 列表页面查看你期望的 Delegate 的 “Tags” 列是否完全匹配大小写敏感。2.检查状态确认匹配的 Delegate 是绿色 “Connected” 状态。3.查看队列在 Delegate 详情页查看是否有任务积压。重启不健康的 Delegate。6.3 Docker 方式安装后无法执行 Docker 命令在 CI 步骤中运行docker build失败。问题现象可能原因排查步骤与解决方案docker: command not found或Cannot connect to the Docker daemon1. Docker 套接字未挂载或路径错误。2. Delegate 容器内用户无权访问套接字。1.检查命令确认docker run命令中包含-v /var/run/docker.sock:/var/run/docker.sock。2.检查权限进入 Delegate 容器docker exec -it container_id sh运行ls -la /var/run/docker.sock。文件所属组应为docker。可能需要将harness用户Delegate 进程用户加入docker组但这通常在镜像内已处理。最稳妥的方式是使用privileged: true不推荐或调整宿主机 Docker 套接字权限。6.4 如何查看 Delegate 的详细日志和指标日志K8s:kubectl logs -f deployment/harness-delegate -n harness-delegate-ngDocker:docker logs -f container_idHarness 平台在 Delegate 详情页面有 “Logs” 标签页可以查看平台收集的日志。资源监控K8s:kubectl top pod -n harness-delegate-ng平台Delegate 详情页显示了 CPU/内存使用率的粗略情况。对于细粒度监控需集成集群的监控系统如 Prometheus。6.5 如何升级或重启 DelegateKubernetes升级修改 Deployment 中的镜像版本号如harness/delegate:23.08.xxxxx然后执行kubectl apply -f harness-delegate.yaml。K8s 会滚动更新 Pod。重启kubectl rollout restart deployment/harness-delegate -n harness-delegate-ngDocker停止旧容器docker stop container_id删除旧容器docker rm container_id用新令牌或新镜像重新运行docker run命令。7. 最佳实践与工程建议遵循以下实践能让你的 Harness Delegate 部署更稳健、安全、高效。标签策略标准化制定团队统一的标签命名规范例如env:dev|stage|prod,cloud:aws|azure|gcp,cluster:cluster-a,purpose:ci|cd|monitoring。在 Harness 的“基础设施”定义中清晰指定 Delegate Selector实现环境隔离。资源请求与限制始终在 K8s Deployment 或 Docker 命令中设置resources.requests和resources.limits。避免 Delegate 因资源竞争被驱逐或影响宿主机。监控实际使用量根据任务负载调整。一个处理复杂部署的 Delegate 可能需要更多内存。高可用部署对于生产环境至少部署 2 个具有相同标签的 Delegate 实例K8s 中设置replicas: 2。将它们调度到不同的 K8s 节点上使用podAntiAffinity防止节点故障导致全部中断。安全加固令牌管理Delegate 令牌是敏感信息。避免在代码仓库中明文存储 YAML 文件。使用 K8s Secrets 或 Helm values 加密管理。最小权限Delegate 的 K8s ServiceAccount 或宿主机上的 Docker 权限应遵循最小权限原则。例如CD Delegate 可能只需要在特定命名空间有部署权限而非集群管理员权限。镜像来源只从官方渠道获取 Delegate 镜像并定期更新以获取安全补丁。网络与代理如果企业网络策略严格可以预先在防火墙开放 Harness SaaS 所需的域名和端口列表。对于无法直连公网的环境Harness 也提供Air-Gapped离线安装模式需要提前下载所有依赖镜像和文件具体请参考官方文档。维护与监控将 Delegate 的版本更新纳入常规的运维流程。为 Delegate 所在的 K8s 命名空间或主机设置基础监控CPU、内存、磁盘、网络。关注 Harness 平台上的 Delegate 连接状态和任务队列情况。Harness Delegate 是整个 Harness 自动化体系的基石它的稳定运行直接关系到 CI/CD 流水线的可靠性。通过本文从概念到实战从安装到排错的详细拆解你应该已经掌握了 Delegate 的核心要领。关键在于理解其“桥梁”定位善用“标签”进行精细化的任务路由并遵循“高可用”和“最小权限”的生产级部署原则。接下来你可以尝试在 Harness 中创建一个简单的“Shell Script”步骤并指定你刚安装的 Delegate 来执行亲眼见证任务从云端下发到本地执行的全过程这将彻底打通你对 Harness 自动化流程的认知。如果在实践中遇到新的问题多查看 Delegate 日志和平台提示大部分问题都能迎刃而解。