Harness 教程 09：使用 CLI 与 YAML 编辑：国内网络环境落地版

一：教程定位

在前 8 篇教程中，我们已经完成了 Harness 平台入门、CI/CD 流水线、触发器、测试制品管理、Kubernetes 部署、变量参数化、审批定时触发，以及日志排查。

第 9 篇开始进入工程化管理阶段：如何把 Harness 配置从“界面点点点”升级为“YAML 化、版本化、可审查、可批量管理”。

很多团队刚开始使用 Harness 时，习惯在 UI 里创建 Pipeline、Connector、Service、Environment、Input Set。这种方式适合入门，但企业落地后会遇到问题：

谁改了 Pipeline？ 改了什么？ 什么时候改的？ 能不能回滚？ 能不能代码评审？ 能不能批量复制到多个项目？ 能不能统一检查命名规范？ 能不能像管理 Kubernetes YAML 一样管理 Harness 配置？

答案是：可以。

本篇围绕三个能力展开：

Harness YAML 编辑器 Harness CLI Git 版本管理 / GitOps 化配置管理

需要特别说明：Harness CLI 在不同版本中的命令结构可能会变化。官方当前推荐使用新版 hc CLI，旧版 harness 会逐步废弃。因此本文不会编造某个未确认的子命令，而是采用“官方确认能力 + 可执行脚本 + 版本自检 + UI/YAML/API 兜底”的方式，保证企业或个人都可以落地。

---

二：适合人群

本文适合：

具备基础命令行能力的 DevOps 工程师 习惯使用 Git 管理配置的工程师 希望把 Harness 配置纳入版本管理的团队 正在从 Jenkinsfile / GitLab CI YAML 迁移到 Harness 的团队 希望批量创建 Pipeline、Input Set、Connector 的平台工程师

建议已经具备：

熟悉 Git 基础操作 熟悉 YAML 基础语法 已经能创建 Harness Pipeline 已经创建过 GitLab / Harbor / Kubernetes Connector 已经理解 Pipeline、Stage、Step、Input Set、Environment

---

三：学习目标

完成本文后，你应该能够：

理解 Visual Editor 与 YAML Editor 的区别 在 Pipeline Studio 中切换到 YAML 模式 从 UI 中导出 Pipeline YAML 将 Pipeline YAML 保存到 Git 仓库 通过 Git 分支和 Merge Request 管理 Harness 配置变更 安装并配置 Harness CLI 使用 CLI 完成登录、版本检查、基础资源查询 编写 Harness 配置仓库结构 用 YAML 定义 Pipeline、Input Set、Trigger 等资源 使用脚本批量检查 YAML 文件 设计 CLI 批量创建资源的安全流程 理解国内网络环境下 CLI 使用的代理、证书和权限问题 避免把 Secret 明文提交到 Git

---

四：国内网络环境下的整体架构

本文推荐架构如下：

开发人员 / 平台工程师 ↓ 本地 IDE / VS Code / Cursor ↓ Harness YAML 配置仓库 ↓ Merge Request 审查 GitLab / Gitee ↓ 平台管理员合并 ↓ Harness CLI / Harness UI YAML Import / Harness API ↓ Harness SaaS ↓ Delegate ↓ GitLab / Harbor / Kubernetes

国内企业重点关注：

CLI 所在机器是否能访问 app.harness.io 企业代理是否需要配置 是否使用自签证书或企业根证书 API Token 是否有足够权限 YAML 配置仓库是否在内网 GitLab / Gitee Secret 是否只保存引用，不保存明文 生产配置是否必须经过 Merge Request 审批

---

五：Visual Editor 与 YAML Editor 的区别

1. Visual Editor

适合：

初学者入门 第一次创建 Pipeline 不熟悉 Harness 字段 需要界面引导选择 Connector、Service、Environment 快速演示

优点：

直观 不容易漏字段 适合第一次跑通 便于非平台工程师理解流程

缺点：

不利于版本管理 多人修改不容易审查 不适合批量复制 不方便统一规范

---

2. YAML Editor

适合：

企业工程化 Git 版本管理 代码审查 多项目复制 模板化 批量变更 审计追溯

优点：

可以提交到 Git 可以走 Merge Request 可以做静态检查 可以批量搜索替换 可以回滚历史版本 可以沉淀模板

缺点：

初学者容易写错缩进 字段较多 不同模块 YAML 结构需要熟悉 建议先通过 Visual Editor 生成，再整理为标准 YAML

---

六：推荐工作方式

建议采用“三步走”：

第一步：Visual Editor 跑通功能 第二步：切换 YAML Editor 导出配置 第三步：把 YAML 提交到 Git，后续通过 Git 管理

不要一开始就完全手写 YAML。更稳妥的方式是：

UI 创建成功 复制 YAML 提交 Git 在 Git 中做小步修改 用 Harness YAML Editor 校验 再导入或更新

---

七：在 Harness 中切换 YAML 编辑器

进入：

Project → Pipelines → 选择 Pipeline → Pipeline Studio

右上角切换：

Visual YAML

在 YAML 模式中可以：

查看完整 Pipeline YAML 复制 YAML 修改字段 查看语法错误 使用自动补全 查找替换

常用技巧：

Cmd/Ctrl + Space：自动补全 Cmd/Ctrl + F：查找替换 F1：命令面板

当 YAML 不合法时，编辑器会提示 Invalid。此时不要强行保存，应先根据提示修复缩进、字段名或缺失项。

---

八：Harness YAML 配置仓库结构

建议创建一个专门仓库：

harness-platform-config/ ├── README.md ├── docs/ │ ├── naming-convention.md │ ├── review-checklist.md │ └── troubleshooting.md ├── orgs/ │ └── devops-lab/ │ └── projects/ │ └── harness-demo/ │ ├── pipelines/ │ │ ├── nodejs-ci.yaml │ │ ├── nodejs-k8s-deploy.yaml │ │ └── nodejs-prod-release.yaml │ ├── inputsets/ │ │ ├── dev.yaml │ │ ├── test.yaml │ │ ├── pre.yaml │ │ └── prod.yaml │ ├── triggers/ │ │ ├── gitlab-main-push.yaml │ │ └── gitlab-mr-ci.yaml │ ├── connectors/ │ │ ├── gitlab-company.yaml │ │ ├── harbor-company.yaml │ │ └── k8s-dev-cluster.yaml │ ├── services/ │ │ └── harness-demo-app.yaml │ └── environments/ │ ├── dev.yaml │ ├── test.yaml │ ├── pre.yaml │ └── prod.yaml ├── scripts/ │ ├── install-hc.sh │ ├── validate-yaml.sh │ ├── check-sensitive-info.sh │ ├── list-cli-capabilities.sh │ ├── apply-one.sh │ └── apply-all.sh └── Makefile

说明：

pipelines：保存 Pipeline YAML inputsets：保存 Input Set YAML triggers：保存 Trigger YAML connectors：保存 Connector YAML services：保存 Service YAML environments：保存 Environment YAML scripts：保存本地校验、批量导入、批量检查脚本 docs：保存团队规范

企业建议：

一个业务项目一个目录 公共模板放到 templates 目录 生产环境配置单独保护 所有 YAML 变更必须走 Merge Request

---

九：命名规范

建议统一命名：

Org Identifier: devops_lab

Project Identifier: harness_demo

Pipeline Identifier: nodejs_k8s_deploy nodejs_prod_release

Connector Identifier: gitlab_company harbor_company k8s_dev_cluster

Input Set Identifier: dev test pre prod

Environment Identifier: dev test pre prod

不要使用：

中文 identifier 空格 中横线 点号 特殊字符

推荐使用：

小写字母 数字 下划线

原因：

表达式引用更稳定 脚本处理更简单 Git 搜索更方便 跨平台兼容更好

---

十：示例 Pipeline YAML

orgs/devops-lab/projects/harness-demo/pipelines/nodejs-k8s-deploy.yaml

pipeline:
  name: nodejs-k8s-deploy
  identifier: nodejs_k8s_deploy
  projectIdentifier: harness_demo
  orgIdentifier: devops_lab
  tags:
    app: nodejs
    network: china
    managed_by: git
  variables:
    - name: app_name
      type: String
      value: harness-demo-app
    - name: image_repository
      type: String
      value: harbor.company.com/devops/harness-demo-app
    - name: image_tag
      type: String
      value: <+input>
    - name: namespace
      type: String
      value: <+input>
  stages:
    - stage:
        name: Deploy
        identifier: deploy
        type: Deployment
        spec:
          deploymentType: Kubernetes
          service:
            serviceRef: harness_demo_app
          environment:
            environmentRef: <+input>
            deployToAll: false
            infrastructureDefinitions:
              - identifier: <+input>
          execution:
            steps:
              - step:
                  name: K8s Rolling Deploy
                  identifier: k8s_rolling_deploy
                  type: K8sRollingDeploy
                  timeout: 10m
                  spec:
                    skipDryRun: false
              - step:
                  name: Verify Deployment
                  identifier: verify_deployment
                  type: ShellScript
                  timeout: 5m
                  spec:
                    shell: Bash
                    source:
                      type: Inline
                      spec:
                        script: |
                          set -e
                          export KUBECONFIG=${HARNESS_KUBE_CONFIG_PATH}

                          APP_NAME="<+pipeline.variables.app_name>"
                          NAMESPACE="<+pipeline.variables.namespace>"

                          kubectl rollout status deployment/${APP_NAME} -n ${NAMESPACE} --timeout=180s
                          kubectl get pods -n ${NAMESPACE} -l app=${APP_NAME} -o wide

说明：

managed_by: git 表示该配置由 Git 管理 image_tag、namespace、environmentRef、infrastructureDefinitions 使用 Runtime Input 后续通过 Input Set 提供 dev/test/prod 差异参数

---

十一：示例 Input Set YAML

orgs/devops-lab/projects/harness-demo/inputsets/dev.yaml

inputSet:
  name: dev
  identifier: dev
  orgIdentifier: devops_lab
  projectIdentifier: harness_demo
  pipeline:
    identifier: nodejs_k8s_deploy
    variables:
      - name: image_tag
        type: String
        value: latest
      - name: namespace
        type: String
        value: dev
    stages:
      - stage:
          identifier: deploy
          type: Deployment
          spec:
            environment:
              environmentRef: dev
              infrastructureDefinitions:
                - identifier: dev_k8s

orgs/devops-lab/projects/harness-demo/inputsets/prod.yaml

inputSet:
  name: prod
  identifier: prod
  orgIdentifier: devops_lab
  projectIdentifier: harness_demo
  pipeline:
    identifier: nodejs_k8s_deploy
    variables:
      - name: image_tag
        type: String
        value: <+input>
      - name: namespace
        type: String
        value: prod
    stages:
      - stage:
          identifier: deploy
          type: Deployment
          spec:
            environment:
              environmentRef: prod
              infrastructureDefinitions:
                - identifier: prod_k8s

生产环境要求：

image_tag 不允许 latest 必须使用 v1.0.0、release-日期-流水号或 commit sha prod Input Set 的修改必须走审批

---

十二：示例 Trigger YAML

orgs/devops-lab/projects/harness-demo/triggers/gitlab-main-push.yaml

trigger:
  name: gitlab-main-push
  identifier: gitlab_main_push
  enabled: true
  description: main 分支 push 后触发测试环境部署
  orgIdentifier: devops_lab
  projectIdentifier: harness_demo
  pipelineIdentifier: nodejs_k8s_deploy
  source:
    type: Webhook
    spec:
      type: Gitlab
      spec:
        type: Push
        spec:
          connectorRef: gitlab_company
          autoAbortPreviousExecutions: true
          repoName: devops/harness-demo-app
          branchRegex: main
  inputSetRefs:
    - dev

注意：

Trigger YAML 字段可能随 Harness 版本或 UI 生成方式有差异 建议先在 UI 中创建 Trigger 再切换 YAML 复制保存 不要凭空手写不确定字段

---

十三：安装 Harness CLI

官方推荐新版 CLI 命令为：

hc

旧版：

harness

旧版未来会废弃，因此本文统一使用 hc。

安装脚本 scripts/install-hc.sh：

#!/usr/bin/env bash
set -e

echo "安装 Harness CLI hc"

curl https://raw.githubusercontent.com/harness/harness-cli/v2/install | sh

echo "检查版本"
hc version

echo "安装完成"

执行：

chmod +x scripts/install-hc.sh
./scripts/install-hc.sh

如果国内网络无法访问 GitHub raw 地址，有三种方案：

方案一：使用企业代理访问 GitHub raw 方案二：在可出网机器下载 hc 二进制后上传到内网 方案三：将 hc 二进制放入企业制品库或对象存储统一分发

代理示例：

export HTTPS_PROXY=http://proxy.company.com:3128
export HTTP_PROXY=http://proxy.company.com:3128

---

十四：配置 Harness CLI 登录

执行：

hc auth login

按提示输入：

URL: app.harness.io

API Token Key: Harness API Token

Account ID: Harness Account Identifier

Organization ID: devops_lab

Project ID: harness_demo

登录后验证：

hc version
hc --help

官方示例中还可以通过查询 Registry 验证连接：

hc registry list --org devops_lab --project harness_demo

注意：

API Token 不要提交到 Git 不要写在脚本里 不要输出到日志 企业建议使用专用平台机器人账号

---

十五：CLI 国内网络注意事项

1. 代理

如果本地不能访问 Harness SaaS：

export HTTPS_PROXY=http://proxy.company.com:3128
export HTTP_PROXY=http://proxy.company.com:3128

如果还需要访问内网 GitLab / Harbor：

export NO_PROXY=localhost,127.0.0.1,.company.com,gitlab.company.com,harbor.company.com

2. 证书

如果企业代理或 Harness Self-Managed 使用自签证书，需要确认系统信任企业 CA。

macOS：

security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain company-ca.crt

Linux：

sudo cp company-ca.crt /usr/local/share/ca-certificates/company-ca.crt
sudo update-ca-certificates

3. Token 权限

CLI 使用的 API Token 建议具备：

读取 Project 读取和编辑 Pipeline 读取和编辑 Input Set 读取和编辑 Trigger 读取 Connector 必要时创建或更新 Service / Environment

生产环境不要给所有人管理员 Token。

---

十六：查看 CLI 当前支持哪些命令

由于 CLI 版本会持续演进，企业脚本不要假设所有资源都有同样的 create/apply 命令。

先执行：

hc --help

查看某类资源：

hc pipeline --help || true
hc input-set --help || true
hc trigger --help || true
hc connector --help || true
hc project --help || true

建议把支持的命令输出保存：

scripts/list-cli-capabilities.sh

#!/usr/bin/env bash
set -e

echo "===== hc version ====="
hc version || true

echo "===== hc help ====="
hc --help || true

for cmd in pipeline input-set trigger connector service environment project registry; do
  echo "===== hc ${cmd} --help ====="
  hc ${cmd} --help || true
done

执行：

chmod +x scripts/list-cli-capabilities.sh
./scripts/list-cli-capabilities.sh | tee cli-capabilities.txt

企业落地建议：

把 cli-capabilities.txt 提交到内部文档 明确当前版本支持哪些资源的创建、更新、查询 脚本中根据实际支持的命令实现批量管理 不使用未经验证的命令

---

十七：YAML 静态检查

在导入 Harness 前，先做本地检查。

安装工具：

brew install yamllint yq

Linux：

sudo apt-get install -y yamllint

scripts/validate-yaml.sh

#!/usr/bin/env bash
set -e

ROOT_DIR="${1:-orgs}"

echo "检查 YAML 格式：${ROOT_DIR}"

find "${ROOT_DIR}" \( -name "*.yaml" -o -name "*.yml" \) | while read -r file; do
  echo "检查：${file}"
  yamllint -d relaxed "${file}"
done

echo "YAML 格式检查完成"

执行：

chmod +x scripts/validate-yaml.sh
./scripts/validate-yaml.sh orgs

---

十八：敏感信息检查

不能把以下内容提交到 Git：

GitLab Token Harbor Robot Token Slack Webhook 企业微信 Webhook 数据库密码 云厂商 AK/SK 私钥 kubeconfig 明文

scripts/check-sensitive-info.sh

#!/usr/bin/env bash
set -e

ROOT_DIR="${1:-orgs}"

echo "检查敏感信息：${ROOT_DIR}"

PATTERNS=(
  "password:"
  "token:"
  "secret:"
  "PRIVATE KEY"
  "BEGIN RSA"
  "hooks.slack.com/services"
  "key_id"
  "access_key"
  "secret_key"
  "kubeconfig"
)

FOUND=0

for pattern in "${PATTERNS[@]}"; do
  echo "扫描关键字：${pattern}"
  if grep -Rni "${pattern}" "${ROOT_DIR}" || true; then
    FOUND=1
  fi
done

if [ "${FOUND}" -eq 1 ]; then
  echo "发现疑似敏感信息，请人工确认"
  exit 1
fi

echo "未发现明显敏感信息"

注意：

这个脚本可能有误报 误报比漏报更安全 正式环境建议接入 GitLab Secret Detection 或企业代码安全扫描

---

十九：通过 UI 导入 / 更新 YAML

对于初学者，最稳定方式是：

1. 在 Git 中修改 YAML
2. 复制 YAML 内容
3. 进入 Harness Pipeline Studio
4. 切换 YAML
5. 粘贴内容
6. 等待编辑器校验
7. 保存
8. 运行验证

这种方式虽然不是完全自动化，但最适合初学阶段。

适合：

第一次创建 Pipeline 学习 Harness YAML 结构 不确定 CLI 是否支持某个资源 需要 Harness YAML Editor 直接提示错误

企业工程化后，可以逐步切换到 CLI/API/Terraform Provider 自动化。

---

二十：通过 CLI 批量管理资源的落地策略

由于 CLI 版本和资源子命令会演进，本文提供一种安全落地策略：

第一层：用 hc auth login、hc --help、hc version 做身份和能力检查 第二层：用脚本读取 YAML 文件列表 第三层：对当前 hc 已支持的资源使用 CLI 创建或更新 第四层：对 CLI 未覆盖或不稳定的资源，回退到 Harness UI YAML Import 或官方 API 第五层：所有操作前必须通过 Merge Request 审查

不要写死未经验证的命令，例如：

hc apply -f xxx.yaml hc pipeline apply xxx.yaml

除非你已经在当前 CLI 版本中通过 hc --help 确认该命令存在。

---

二十一：批量处理脚本框架

scripts/apply-one.sh

#!/usr/bin/env bash
set -e

FILE="${1:?YAML file is required}"

echo "准备处理文件：${FILE}"

if [ ! -f "${FILE}" ]; then
  echo "文件不存在：${FILE}"
  exit 1
fi

echo "先做 YAML 格式检查"
yamllint -d relaxed "${FILE}"

echo "识别资源类型"

if grep -q "^pipeline:" "${FILE}"; then
  RESOURCE_TYPE="pipeline"
elif grep -q "^inputSet:" "${FILE}"; then
  RESOURCE_TYPE="inputset"
elif grep -q "^trigger:" "${FILE}"; then
  RESOURCE_TYPE="trigger"
elif grep -q "^connector:" "${FILE}"; then
  RESOURCE_TYPE="connector"
else
  RESOURCE_TYPE="unknown"
fi

echo "资源类型：${RESOURCE_TYPE}"

echo "检查当前 hc 是否支持该资源命令"
hc --help >/dev/null

case "${RESOURCE_TYPE}" in
  pipeline)
    echo "这是 Pipeline YAML"
    echo "请使用当前 hc 版本中已确认的 pipeline create/update 命令，或回到 UI YAML Editor 导入"
    ;;
  inputset)
    echo "这是 Input Set YAML"
    echo "请使用当前 hc 版本中已确认的 input-set create/update 命令，或回到 UI 导入"
    ;;
  trigger)
    echo "这是 Trigger YAML"
    echo "建议优先在 UI 创建并导出 YAML，因为 Trigger 字段随 SCM 类型差异较大"
    ;;
  connector)
    echo "这是 Connector YAML"
    echo "Connector 通常引用 Secret，不要在 YAML 中写明文密码"
    ;;
  *)
    echo "无法识别资源类型，请人工处理"
    exit 1
    ;;
esac

echo "处理完成：${FILE}"

这个脚本不是为了“假装自动导入”，而是为了建立企业流程：

识别资源类型 先校验 再决定使用 CLI、UI 或 API 避免盲目批量写入生产配置

---

二十二：批量扫描所有 YAML

scripts/apply-all.sh

#!/usr/bin/env bash
set -e

ROOT_DIR="${1:-orgs}"

echo "批量处理目录：${ROOT_DIR}"

./scripts/validate-yaml.sh "${ROOT_DIR}"
./scripts/check-sensitive-info.sh "${ROOT_DIR}"

find "${ROOT_DIR}" \( -name "*.yaml" -o -name "*.yml" \) | sort | while read -r file; do
  echo "================================"
  echo "处理：${file}"
  ./scripts/apply-one.sh "${file}"
done

echo "批量处理完成"

执行：

chmod +x scripts/*.sh
./scripts/apply-all.sh orgs

---

二十三：Makefile

Makefile

ROOT_DIR ?= orgs

.PHONY: validate
validate:
	./scripts/validate-yaml.sh $(ROOT_DIR)

.PHONY: secrets-check
secrets-check:
	./scripts/check-sensitive-info.sh $(ROOT_DIR)

.PHONY: cli-capabilities
cli-capabilities:
	./scripts/list-cli-capabilities.sh

.PHONY: plan
plan: validate secrets-check
	@echo "YAML 校验和敏感信息检查通过"

.PHONY: apply-all
apply-all: validate secrets-check
	./scripts/apply-all.sh $(ROOT_DIR)

使用：

make plan
make cli-capabilities
make apply-all

---

二十四：通过 GitOps 管理 Harness 配置

这里的 GitOps 不是指 Harness GitOps Agent 部署 Kubernetes，而是指：

Harness 自身配置通过 Git 管理 所有变更都走 Git 提交 所有修改都走 Merge Request 合并后由平台管理员应用到 Harness

推荐流程：

1. 平台工程师从 UI 导出 Pipeline YAML
2. 提交到 harness-platform-config 仓库
3. 新建分支修改配置
4. 提交 Merge Request
5. 自动运行 yamllint 和敏感信息扫描
6. 平台负责人 Review
7. 合并到 main
8. 由管理员执行 make apply-all 或在 UI 中导入
9. 运行 Pipeline 验证

分支命名建议：

fea-harness-pipeline-param fix-prod-inputset-approval chore-update-harbor-connector

提交信息建议：

feat: add nodejs prod release pipeline fix: update prod inputset image tag rule chore: add yaml validation script

---

二十五：GitLab CI 校验 Harness YAML

在配置仓库中添加 .gitlab-ci.yml：

stages:
  - validate

validate_harness_yaml:
  stage: validate
  image: harbor.company.com/platform/yaml-tools:1.0.0
  script:
    - ./scripts/validate-yaml.sh orgs
    - ./scripts/check-sensitive-info.sh orgs
  only:
    - merge_requests
    - main

如果没有 yaml-tools 镜像，可以先制作：

FROM alpine:3.20

RUN apk add --no-cache bash grep curl python3 py3-pip
RUN pip3 install --break-system-packages yamllint

WORKDIR /workspace

构建：

docker build -t harbor.company.com/platform/yaml-tools:1.0.0 .
docker push harbor.company.com/platform/yaml-tools:1.0.0

国内环境建议：

CI 校验镜像放 Harbor 不要依赖 DockerHub pip 源可以改为国内镜像或企业 PyPI 私服

---

二十六：Pipeline YAML 审查清单

Merge Request 审查时，至少检查：

Pipeline identifier 是否符合规范 orgIdentifier / projectIdentifier 是否正确 是否使用了生产环境 Connector 是否跳过了审批 是否关闭了 Dry Run 是否使用 latest 部署生产 是否把 Secret 明文写入 YAML 是否修改了 prod Input Set 是否修改了生产命名空间 是否修改了审批人组 是否修改了 failure strategy

生产配置修改必须特别关注：

prod environment prod infrastructure prod input set prod approval prod connector prod secrets reference

---

二十七：生产配置保护规则

GitLab 中建议配置：

main 分支保护 prod 目录 Code Owner prod Input Set 修改必须 2 人 Review 禁止普通开发直接合并 禁止 Force Push 启用 Secret Detection 启用 MR 审批规则

目录示例：

orgs/devops-lab/projects/harness-demo/inputsets/prod.yaml orgs/devops-lab/projects/harness-demo/environments/prod.yaml orgs/devops-lab/projects/harness-demo/pipelines/nodejs-prod-release.yaml

CODEOWNERS 示例：

/orgs/devops-lab/projects/harness-demo/inputsets/prod.yaml @devops-admins @release-managers /orgs/devops-lab/projects/harness-demo/environments/prod.yaml @devops-admins /orgs/devops-lab/projects/harness-demo/pipelines/prod.yaml @devops-admins @release-managers

---

二十八：CLI 批量创建资源的练习设计

本篇练习目标是：用 CLI 和脚本批量处理 Harness YAML 配置。

因为不同 CLI 版本支持的命令可能不同，所以练习分为两级。

练习 A：基础 CLI 验证

执行：

hc version
hc auth login
hc --help
hc registry list --org devops_lab --project harness_demo

验收：

hc 可以正常执行 认证成功 能够查询到项目内资源

练习 B：批量检查 YAML

执行：

make plan

验收：

YAML 语法检查通过 敏感信息检查通过 没有明文 Token 没有 Webhook URL 没有 kubeconfig

练习 C：识别资源类型

执行：

./scripts/apply-one.sh orgs/devops-lab/projects/harness-demo/pipelines/nodejs-k8s-deploy.yaml
./scripts/apply-one.sh orgs/devops-lab/projects/harness-demo/inputsets/dev.yaml

验收：

脚本能识别 pipeline 脚本能识别 inputset 脚本能提示后续应用方式

练习 D：根据当前 CLI 支持能力完善 apply-one.sh

执行：

./scripts/list-cli-capabilities.sh

根据输出确认是否支持：

pipeline create/update input-set create/update trigger create/update connector create/update

如果当前 CLI 支持，就在 apply-one.sh 中补充对应命令。

如果当前 CLI 不支持，就采用：

UI YAML 导入 Harness API Terraform Provider

作为替代方案。

---

二十九：为什么不直接硬写所有 CLI 命令？

企业落地一定要避免“复制网上过期命令”。

原因：

Harness CLI 正在从旧版 harness 迁移到新版 hc 不同版本命令可能不同 不同账号模块启用情况不同 部分资源字段会随 Harness 版本变化 Trigger / Connector 字段差异较大

更安全的方式：

以官方 hc --help 为准 以 Harness UI 生成 YAML 为准 以当前账号实际功能为准 先在测试 Project 验证 再推广到生产 Project

这也是本文强调“不随意编造”的原因。

---

三十：YAML 导入失败常见问题

1. Identifier 重复

错误现象：

identifier already exists

原因：

创建资源时 identifier 已存在

处理：

改为 update 或修改 identifier 或先删除旧资源

---

2. orgIdentifier / projectIdentifier 错误

错误现象：

Project not found Organization not found

处理：

检查 orgIdentifier 检查 projectIdentifier 确认当前 API Token 有该项目权限

---

3. Connector 引用不存在

错误现象：

connectorRef not found

处理：

先创建 Connector 确认 connector identifier 正确 确认当前 Project 可以访问该 Connector

---

4. Secret 引用不存在

错误现象：

secret not found

处理：

先在 Harness 创建 Secret YAML 中只引用 Secret Identifier 不要提交 Secret 明文

---

5. YAML 缩进错误

错误现象：

Invalid YAML mapping values are not allowed did not find expected key

处理：

用 yamllint 检查 使用 2 空格缩进 不要混用 Tab 复杂脚本使用 | 块

---

6. Runtime Input 没有对应 Input Set

错误现象：

运行 Pipeline 时仍要求填写参数

原因：

Input Set 没覆盖所有 <+input>

处理：

更新 Input Set 或者把固定值写回 Pipeline

---

三十一：国内网络常见问题

1. 安装 hc 失败

原因：

无法访问 raw.githubusercontent.com 公司代理未配置 DNS 解析失败

解决：

配置 HTTPS_PROXY 使用可出网机器下载 将 hc 二进制放入内部制品库

---

2. hc auth login 失败

原因：

API Token 错误 Account ID 错误 代理拦截 证书不受信任 URL 写错

排查：

curl -I https://app.harness.io
hc --help
hc version

---

3. CLI 可以登录但操作失败

原因：

API Token 权限不足 Org / Project 不匹配 资源 identifier 写错 账号没有启用对应模块

解决：

检查 RBAC 检查 Token 所属用户 检查 Organization / Project 使用最小测试资源验证

---

4. GitLab CI 中使用 CLI 失败

原因：

CI Runner 不能访问 Harness SaaS 未配置 API Token Token 被日志暴露 容器镜像没有 hc

解决：

制作内部 hc 工具镜像 Token 放 GitLab CI Variables 设置 masked / protected 配置企业代理

---

三十二：制作企业内部 hc 工具镜像

为了让 GitLab CI 或内部流水线使用 hc，建议制作内部镜像。

Dockerfile.hc

FROM alpine:3.20

RUN apk add --no-cache bash curl ca-certificates git grep yq

RUN curl https://raw.githubusercontent.com/harness/harness-cli/v2/install | sh || true

RUN if [ -f ./hc ]; then mv ./hc /usr/local/bin/hc; fi && \
    chmod +x /usr/local/bin/hc || true

WORKDIR /workspace

CMD ["bash"]

构建：

docker build -f Dockerfile.hc -t harbor.company.com/platform/harness-cli:1.0.0 .
docker push harbor.company.com/platform/harness-cli:1.0.0

如果不能在 Dockerfile 中访问 GitHub raw：

先下载 hc 二进制 放到构建上下文 COPY hc /usr/local/bin/hc

离线版：

FROM alpine:3.20

RUN apk add --no-cache bash curl ca-certificates git grep yq

COPY hc /usr/local/bin/hc
RUN chmod +x /usr/local/bin/hc

WORKDIR /workspace

CMD ["bash"]

---

三十三：GitLab CI 中运行校验

.gitlab-ci.yml

stages:
  - validate
  - plan

variables:
  ROOT_DIR: orgs

validate_harness_config:
  stage: validate
  image: harbor.company.com/platform/harness-cli:1.0.0
  script:
    - ./scripts/validate-yaml.sh ${ROOT_DIR}
    - ./scripts/check-sensitive-info.sh ${ROOT_DIR}
  only:
    - merge_requests
    - main

show_cli_capabilities:
  stage: plan
  image: harbor.company.com/platform/harness-cli:1.0.0
  script:
    - hc version
    - hc --help
    - ./scripts/list-cli-capabilities.sh
  only:
    - main

注意：

不要在普通 MR 中直接 apply 到生产 Harness 先 validate 合并 main 后由平台管理员执行 apply

---

三十四：企业落地推荐流程

推荐流程：

开发或平台工程师修改 YAML ↓ 提交 feature 分支 ↓ 创建 Merge Request ↓ GitLab CI 运行 YAML 校验和敏感信息扫描 ↓ 平台负责人 Review ↓ 合并 main ↓ 管理员执行 make apply-all 或 UI/API 导入 ↓ Harness 中验证 Pipeline ↓ 记录变更

生产配置变更推荐：

必须关联变更单 必须 2 人 Review 必须验证测试环境 必须记录回滚方案 必须保留旧版本 YAML

---

三十五：企业最佳实践

1. 先 UI 生成，再 YAML 管理

不要纯手写复杂 Pipeline。

推荐：

UI 跑通 YAML 导出 Git 管理 小步修改 MR 审查

2. Harness 配置仓库独立管理

不要把所有 Harness 配置散落在各业务仓库。

推荐：

harness-platform-config

业务仓库只保存应用代码、Dockerfile、K8s Manifest。

3. Secret 只存引用

正确：

passwordRef: harbor_robot_token

错误：

password: "真实密码"

4. 生产配置受保护

必须保护：

prod input set prod pipeline prod environment prod connector prod approval

5. CLI 命令以版本为准

任何批量脚本中都要先做：

hc version
hc --help

不要复制未经验证的 CLI 命令。

6. YAML 必须走校验

最少检查：

YAML 语法 敏感信息 identifier 命名 prod latest approval_required connectorRef secretRef

---

三十六：练习 1：导出 Pipeline YAML

目标：

从 Harness UI 导出一条已有 Pipeline YAML，提交到 Git。

步骤：

1. 打开 Pipeline Studio
2. 切换 YAML
3. 复制 YAML
4. 保存到 pipelines/nodejs-k8s-deploy.yaml
5. git add / commit / push

验收：

Git 仓库中存在 Pipeline YAML YAML 中没有明文 Secret 可以通过 yamllint

---

三十七：练习 2：安装并登录 hc CLI

目标：

完成 hc 安装、登录和基础查询。

步骤：

curl https://raw.githubusercontent.com/harness/harness-cli/v2/install | sh
hc version
hc auth login
hc --help

验收：

hc version 正常 hc auth login 成功 hc --help 可以显示命令

---

三十八：练习 3：批量检查 YAML

目标：

使用脚本批量校验 Harness YAML。

步骤：

make plan

验收：

YAML 校验通过 敏感信息扫描通过 发现问题时 GitLab CI 失败

---

三十九：练习 4：批量创建资源前的能力探测

目标：

通过 hc --help 确认当前 CLI 支持哪些资源命令。

步骤：

./scripts/list-cli-capabilities.sh | tee cli-capabilities.txt

验收：

能看到当前 CLI 版本 能看到可用命令 能确定 pipeline/inputset/trigger/connector 是否支持 CLI 方式管理

---

四十：练习 5：使用 GitOps 流程修改 Input Set

目标：

把 dev 副本数从 1 改成 2，并通过 MR 审查。

步骤：

git checkout -b fea-update-dev-inputset

修改：

replicas: 2

提交：

git add orgs/devops-lab/projects/harness-demo/inputsets/dev.yaml
git commit -m "feat: update dev inputset replicas"
git push origin fea-update-dev-inputset

创建 Merge Request。

验收：

MR 中能看到 YAML 差异 CI 校验通过 合并后由管理员应用到 Harness 运行 dev Input Set 后副本数变为 2

---

四十一：验收标准

完成本文后，应达到：

已理解 Visual Editor 与 YAML Editor 的区别 已能在 Harness 中切换 YAML 编辑器 已能导出 Pipeline YAML 已能将 Harness YAML 提交到 Git 已安装 hc CLI 已完成 hc auth login 已能使用 hc --help 查看命令 已能设计 Harness 配置仓库结构 已能编写 Pipeline / Input Set / Trigger YAML 已能进行 YAML 格式校验 已能进行敏感信息扫描 已理解 CLI 版本差异与命令确认方式 已能设计批量创建资源的安全流程 已能通过 GitLab MR 管理 Harness 配置变更