吉祥法师：Harness Delegate 安装全面指南

# 吉祥法师：Harness Delegate 安装全面指南

## 引言

Harness Delegate是Harness持续交付/集成平台中的一个轻量级工作进程，它安装在你自己的基础设施上，仅通过出站HTTP/HTTPS连接与Harness平台通信。这种架构设计使得Harness平台能够借助Delegate代表用户执行CI/CD任务，同时确保用户的机密信息不会离开自己的网络安全边界。本文将深入探讨Delegate的安装选项、配置方法、自定义工具集成以及故障排除策略，为你在实际项目中实施Harness Delegate提供全面的技术参考。

## Delegate安装选项概览

Harness Delegate支持多种安装方式，以适应不同的企业基础设施需求。主要包括：Helm Chart、Terraform Helm Provider、Kubernetes Manifest以及Docker容器方式。选择哪种安装方式取决于你的基础设施管理策略和运维流程。Helm方式适合已经在使用Kubernetes且偏好声明式配置的环境；Terraform方法则更适合已经采用基础设施即代码(IaC)实践的团队；Docker方式则提供了最大的灵活性和快速部署能力。

安装Delegate前，你需要准备两个关键凭证：Delegate Token和Harness账户ID。Delegate Token用于Delegate与Harness平台之间的身份验证，而账户ID则标识你的Harness组织。这两个参数在任何安装方式中都是必需的输入。

## 创建Delegate Token与账户信息准备

### 创建新Delegate Token

要创建一个新的Delegate Token，首先登录Harness平台，依次选择"Account Settings"，然后进入"Account Resources"页面。在页面中找到"Delegates"选项并点击进入Delegates列表页面。切换至"Tokens"标签页，点击"+ New Token"按钮创建新令牌。在弹出的对话框中，输入一个有意义的令牌名称(例如"firstdeltoken")，然后点击"Apply"生成令牌。生成后务必点击"Copy"按钮复制并妥善保存该令牌，因为在后续的安装步骤中需要将其作为输入参数提供，Delegate将使用这个令牌与Harness平台进行认证。

### 获取Harness账户ID

Harness账户ID出现在每个Harness URL中。例如，在URL https://app.harness.io/ng/#/account/6_vVHzo9Qeu9fXvj-AcQCb/settings/overview 中，`6_vVHzo9Qeu9fXvj-AcQCb`就是账户ID。当你通过Harness UI安装Delegate时，这些依赖信息会被自动预填，简化了操作流程。但对于命令行安装方式，你需要手动提供这些参数，因此在开始安装前务必确认已正确获取了账户ID和Delegate Token等信息。

## 在不同平台上安装Delegate

### Kubernetes集群上的Helm Chart安装

Helm Chart方式是目前最受推荐的Kubernetes Delegate安装方法。首先，需要确保本地环境已安装Helm v3。安装过程从添加Harness的Helm仓库开始：

```bash
helm repo add harness-delegate https://app.harness.io/storage/harness-download/delegate-helm-chart/
helm repo update
helm search repo harness-delegate
```

这一系列命令将Helm仓库添加到本地注册表，并搜索可用的Delegate图表。实际安装命令如下：

```bash
helm upgrade -i firstk8sdel --namespace harness-delegate-ng --create-namespace \
  harness-delegate/harness-delegate-ng \
  -f values.yaml \
  --set delegateName=firstk8sdel \
  --set accountId=PUT_YOUR_HARNESS_ACCOUNTID_HERE \
  --set delegateToken=PUT_YOUR_DELEGATE_TOKEN_HERE \
  --set managerEndpoint=PUT_YOUR_MANAGER_HOST_AND_PORT_HERE \
  --set delegateDockerImage=harness/delegate:yy.mm.verno \
  --set replicas=1 \
  --set upgrader.enabled=true
```

这个命令使用默认的values.yaml文件，创建名为firstk8sdel的Delegate。若想进行持久化配置修改，可以先下载values.yaml文件并做相应更新，再使用`-f`参数指定修改后的文件。

对于在气隙（air-gapped）环境中安装Harness Self-Managed Enterprise Edition的情况，需要在添加Helm仓库时传入证书：

```bash
helm repo add harness-delegate --ca-file <.PEM_FILE_PATH> 
```

### 使用Terraform进行安装

Terraform提供了将Delegate管理纳入基础设施即代码工作流的理想方案。Harness提供了官方的Terraform模块，该模块利用标准的Terraform Helm provider将Helm图表安装到Kubernetes集群中。创建一个main.tf文件，内容如下：

```hcl
module "delegate" {
  source = "harness/harness-delegate/kubernetes"
  version = "0.1.8"
  account_id = "PUT_YOUR_HARNESS_ACCOUNTID_HERE"
  delegate_token = "PUT_YOUR_DELEGATE_TOKEN_HERE"
  delegate_name = "firstk8sdel"
  namespace = "harness-delegate-ng"
  manager_endpoint = "PUT_YOUR_MANAGER_HOST_AND_PORT_HERE"
  delegate_image = "harness/delegate:yy.mm.verno"
  replicas = 1
  upgrader_enabled = false
  
  # 额外的可选值可以传递给Helm图表
  values = yamlencode({
    javaOpts: "-Xms64M"
  })
}

provider "helm" {
  kubernetes {
    config_path = "~/.kube/config"
  }
}
```

然后依次执行`terraform init`初始化并下载相关providers，`terraform plan`预览将要进行的更改，最后通过`terraform apply`实际安装Delegate。Terraform会自动处理Delegate的安装过程，并输出安装结果。

### Kubernetes Manifest文件安装

如果团队偏好直接使用Kubernetes资源定义，可以通过Manifest方式部署。首先下载官方提供的YAML模板：

```bash
curl -LO https://raw.githubusercontent.com/harness/delegate-kubernetes-manifest/main/harness-delegate.yaml
```

然后打开该文件，替换其中的占位变量：PUT_YOUR_DELEGATE_NAME_HERE、PUT_YOUR_HARNESS_ACCOUNTID_HERE和PUT_YOUR_DELEGATE_TOKEN_HERE，以及PUT_YOUR_MANAGER_HOST_AND_PORT_HERE。其中Manager Endpoint对于SaaS账户来说，可以在Account Overview页面找到对应的Harness Cluster Location信息。编辑完变量后，通过`kubectl apply -f harness-delegate.yaml`命令应用该Manifest文件。

### Docker方式安装

Docker安装方式提供了最灵活轻量的部署选项。前提条件是在宿主机上安装Docker运行时。安装Delegate前，同样需要在Harness平台中操作，只是这里应该选择Docker选项而非Kubernetes选项。通过UI操作流程获取docker run命令：

```bash
docker run --cpus=1 --memory=2g \
  -e DELEGATE_NAME=docker-delegate \
  -e NEXT_GEN="true" \
  -e DELEGATE_TYPE="DOCKER" \
  -e ACCOUNT_ID=YOUR_HARNESS_ACCOUNTID_HERE \
  -e DELEGATE_TOKEN=YOUR_DELEGATE_TOKEN \
  -e DELEGATE_TAGS="" \
  -e MANAGER_HOST_AND_PORT=YOUR_MANAGER_HOST_AND_PORT \
  harness/delegate:yy.mm.verno
```

该命令中需要用实际值替换账户ID、Delegate Token和Manager Endpoint。值得注意的是，docker run命令默认不要求选择Delegate Token，但你可以按需在命令中替换Token环境变量。

Docker安装特别适合快速测试和小规模环境部署，也便于在本地进行功能验证。

## 配置自定义角色

在部署Kubernetes Delegate时，你可以选择使用自定义角色来提供不同的权限级别。Harness支持以下角色类型：cluster-admin、cluster-viewer、namespace-admin以及自定义集群角色。如果要使用自定义集群角色，需要修改Delegate的YAML文件，在roleRef字段中添加自定义角色引用：

```yaml
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
  name: harness-delegate-cluster-admin
subjects:
- kind: ServiceAccount
  name: default
  namespace: harness-delegate-ng
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io
```

修改后，请保存YAML文件并重新应用，以确保Delegate获取所需的权限。

## 安装验证与连接测试

完成Delegate安装后，需要在Harness平台中进行连通性验证。在Delegate安装界面上，点击"Continue"按钮，系统会执行健康检查。当所有健康检查通过后，新Delegate就会出现在可用状态列表中，可以用于后续的构建和部署任务。

要进行验证，可以回到Delegate列表页面查看状态。正常情况下，Delegate应该在几分钟内从"Pending"状态变为"Connected"状态。在Harness管道中，可以通过Delegate选择器将特定任务路由到这个新安装的Delegate上执行。

## 自定义Delegate镜像与第三方工具安装

### 理解默认Delegate与最小化Delegate

Harness默认提供的Delegate镜像(标志为yy.mm.verno)预装了一系列第三方自定义二进制文件，包括Kubernetes、Helm等常用工具，这些工具能帮助Delegate直接执行CI/CD相关任务。但预装工具也可能带来安全漏洞风险，因此Harness同时提供最小化Delegate镜像(标志为yy.mm.verno.minimal)，该镜像不包含任何预装的第三方工具，具备最小化攻击面和最少安全漏洞的特点，并会大幅度降低资源消耗和部署足迹。

用户在选择Delegate部署类型时，需要权衡预装工具的便利性带来的快速上手体验与最小镜像占用的安全优势之间的平衡。在关注安全性和供应链合规性的生产环境中，官方推荐使用最小化Delegate镜像并搭载必要的初始化脚本。

### 通过INIT_SCRIPT安装工具

INIT_SCRIPT方式是修改Delegate环境的主要途径之一。这种方式允许在Delegate容器实例上安装附加客户端工具，而不改变Delegate镜像本身。首先下载Delegate的YAML文件，找到INIT_SCRIPT环境变量配置部分，将需要执行的命令添加进去。例如下面的代码片段演示了如何安装AWS CLI：

```yaml
- name: INIT_SCRIPT
  value: |
    microdnf install -y zip unzip
    curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
    unzip awscliv2.zip
    ./aws/install
```

类似地，可以通过修改此脚本安装kubectl、Terraform或Helm3等工具。如安装kubectl：

```yaml
- name: INIT_SCRIPT
  value: |
    curl -L0 https://dl.k8s.io/release/v1.24.3/bin/linux/amd64/kubectl -o kubectl
    chmod +x ./kubectl
    mv kubectl /opt/harness-delegate/custom-client-tools/kubectl
```

甚至可以将多个工具的安装脚本一次性全部放入INIT_SCRIPT，在Delegate启动时执行批量安装。

对于Helm Chart部署类型，需要在values.yaml文件中添加initScript配置来实现相同目的。

### 构建自定义Delegate镜像

当你的工具集合已经固定，并且希望将标准化工具版本固化到镜像中时，建议基于Harness的最小化Delegate镜像构建自定义Delegate镜像。这种方法需要创建一个新的Dockerfile，从Harness提供的基础镜像出发，将所需的第三方工具和SDKs在镜像构建阶段安装进去。此方式提供了更快的启动速度，减少了运行时初始化开销，并确保所有Delegate实例拥有一致且可预知的软件环境。

### 添加Harness必需SDKs

无论采用哪种自定义方式，都必须确保Delegate安装有Harness执行任务所需的核心SDK集合。这些SDK版本的选用需参考官方认证的兼容版本列表，并且必须与所需执行的部署类型相匹配。例如，若涉及Private Cloud Foundry(PCF)部署任务，还需要额外安装PCF CLI 7及以上版本，并确保使用受官方认证的特定版本构建。

### 使用自定义工具进行验证

为了确认为Delegate添加的工具可以正常工作，可以创建一条包含Shell Script步骤的测试管道进行验证。在此步骤中，添加一个简单命令检查工具版本，如`git --version`或`aws --version`。执行完成后，可在运行日志中查看输出结果，以确认工具是否已正确安装并可用。

## 故障排查与问题解决

Delegate安装过程中可能遇到各种问题，需要系统地排查解决方案。以下列出了常见问题及对应的排查步骤。

对于Helm安装问题，首先验证Helm是否正确安装并检查版本：运行`helm version`。若收到"Error: rendered manifests contain a resource that already exists..."错误，则需先删除已存在的命名空间，然后重试Helm升级命令。部署后还应检查Delegate在Kubernetes集群上的状态：`kubectl describe pods -n `。如果Pod未能启动，需检查Delegate的日志：`kubectl logs -f  -n `。对于Pod处于CrashLoopBackOff状态的情况，常见原因是分配给集群的计算资源(CPU和内存)不足，需要检查并增加相应资源分配。

对于Terraform安装问题，首先应验证Terraform已正确安装并处于可用状态，可以运行`terraform -version`进行确认。该方式的技术细节与Helm方式相似，因为Terraform也是通过Helm Provider将Delegate部署到集群中。

对于Docker安装问题，使用`docker container ls -a`命令检查Delegate容器的运行状态。如果容器未在运行，使用`docker container logs  -f`命令来查看详细的日志输出。若容器运行异常，可以依次使用`docker container stop `和`docker container start `命令重启容器。同时需要确保并发容器分配了足够的CPU和内存资源。要删除旧容器，使用`docker container rm [container id]`命令完成清理。

Harness平台的Delegate安装向导提供了交互式的故障排查指导。对于无法自动验证的情况，可以遵循向导中提供的解决步骤操作。如果问题持续存在，还可以在反馈表单中描述，以便结合人工支持的响应快速定位并解决问题。

## 永久存储配置（Ephemeral Storage）

Delegate的Helm Chart支持临时存储的配置，这对于在Pod生命周期内管理临时磁盘空间比较关键。配置通过定义自定义卷来进行，适用于多种云平台厂商，只需根据实际环境调整对应的存储类即可。创建values.yaml文件并添加如下配置：

```yaml
custom_mounts:
- mountPath: "/scratch"
  name: scratch-volume
custom_volumes:
- name: scratch-volume
  ephemeral:
    volumeClaimTemplate:
      metadata:
        labels:
          type: 
      spec:
        accessModes: ["ReadWriteOnce"]
        storageClassName: ""
        resources:
          requests:
            storage: 
```

在应用此配置前，确保集群中存在合适的StorageClass，或者根据文档说明创建自定义StorageClass对象。然后通过`-f values.yaml`参数将配置应用到Helm安装命令中。

重要提醒：临时存储会随Pod终止而自动删除，新Pod启动时会创建全新卷，这种机制确保存储的临时性以及与Pod生命周期的紧密绑定。

## 结论

Harness Delegate是连接Harness平台和用户基础设施的桥梁，它的灵活安装方式和可定制能力让你能够更好地控制CI/CD流水线的安全性、性能和可靠性。通过本文档中的各种选项和最佳实践，你可以根据自身组织的技术栈和运维需求选择合适的安装策略，并通过自定义第三方工具和镜像构建一套针对性较强且运行稳定的CI/CD基础设施。为了保证系统安全稳定，建议你持续关注Harness官方文档和发布说明，以确保Delegate保持受支持的版本，并根据实际需求的变化定期审查和更新部署配置。