GoCD Helm Chart 版本演进全解析：从 stable/gocd 的 CHANGELOG 看 Kubernetes CI/CD 实践-平芜编程栈

【免费下载链接】charts

⚠️(OBSOLETE) Curated applications for Kubernetes

项目地址：https://gitcode.com/gh_mirrors/chart/charts

导读

本文以仓库中 stable/gocd/CHANGELOG.md 为骨架，完整梳理 GoCD Helm Chart 从 1.0.0 到 1.32.0 的功能演进史，并结合 stable/gocd/values.yaml、stable/gocd/README.md 及 templates 下的 Kubernetes 模板源码，讲解 GoCD Server 与 Agent 在 Kubernetes 上的部署、预配置、持久化、RBAC、Ingress/TLS 等关键配置。读完本文，你将掌握这个 Chart 的版本迭代脉络、各版本引入的配置参数含义，以及如何在实际集群中安装、配置和排障。

一、Chart 总览与版本坐标系

stable/gocd/Chart.yaml 记录了该 Chart 的最终状态：

Chart 版本：1.32.0
App 版本（GoCD 版本）：20.8.0
状态：deprecated: true，即该 Chart 已废弃，官方推荐迁移到 GoCD 官方的gocd/gocdHelm Chart（通过helm repo add gocd https://gocd.github.io/helm-chart使用）
类型：CI/CD 持续交付服务器，支持持续集成、持续交付、持续部署与持续测试

从 CHANGELOG 的版本演进可以看出两条清晰的迭代主线：

GoCD 应用版本持续升级：从 18.3 → 20.8.0，几乎每个版本都会 Bump 一次 GoCD 版本（如 1.0.6 到 18.3、1.24.0 到 20.2.0、1.32.0 到 20.8.0）；
Kubernetes 兼容性与功能增强：API 版本升级（Deployment/RBAC/Ingress）、生命周期钩子、持久化、SSH 密钥、Sidecar、Init 容器、特权模式等能力逐步加入。

二、版本演进主线：按主题归类的关键变更

2.1 GoCD 版本升级时间线

CHANGELOG 中记录的主要 GoCD 版本升级节点如下：

Chart 版本	GoCD 版本	说明
1.0.6	18.3	早期版本
1.0.9	18.6	应用版本升级
1.1.3	18.7 同 tag	使用`gocd-agent-docker-dind`镜像，tag 与 GoCD 版本保持一致
1.2.0	18.7.0	应用版本升级
1.4.0	18.8.0	更新 Kubernetes elastic agent 插件到 1.0.2，更新安装后脚本（18.8.0 起通过 API 创建的 pipeline 默认已是未暂停状态）
1.5.0	18.10.0	应用版本升级
1.5.7	18.11.0	应用版本升级
1.5.11	18.12.0	应用版本升级
1.7.0	19.2.0	应用版本升级
1.9.0	19.3.0	Bump k8s elastic agent 插件到最新
1.10.0	19.4.0	应用版本升级
1.11.0	19.5.0	应用版本升级
1.14.0	19.6.0	应用版本升级；新增安全约束选项；删除`goServerSystemProperties`/`goAgentSystemProperties`，改用`goServerJvmOpts`/`goAgentJvmOpts`
1.15.0	19.7.0	应用版本升级
1.16.0	19.8.0 周边	更新 Pipeline Config API 版本，任务改用 getting-started repo 的脚本
1.18.0	19.9.0	应用版本升级
1.19.0	19.10.0	应用版本升级；预配置脚本改用最新 GoCD API；k8s elastic agent 插件升级到 v3.4.0
1.20.0	19.11.0	应用版本升级
1.21.0	19.12.0	应用版本升级
1.22.0	20.1.0	应用版本升级
1.23.0	20.2.0	应用版本升级
1.26.0	20.3.0	应用版本升级
1.28.0	20.5.0	应用版本升级
1.29.0	20.6.0	应用版本升级
1.30.0	20.7.0	应用版本升级
1.32.0	20.8.0	最后一个版本

从源码看，Server 与 Agent 的镜像 tag 默认跟随.Chart.AppVersion。在 templates/gocd-server-deployment.yaml 中，未显式指定server.image.tag时会使用gocd/gocd-server:v{{ .Chart.AppVersion }}；templates/gocd-agent-deployment.yaml 同理使用gocd/gocd-agent-alpine-3.9:v{{ .Chart.AppVersion }}。

2.2 Kubernetes 兼容性与 API 演进

1.12.0：更新 Deployment 和 RBAC 资源的 API 版本（apps/v1、rbac.authorization.k8s.io），当前模板中 Deployment 已使用apiVersion: apps/v1；
1.22.1：Ingress API 版本变更（当前模板为networking.k8s.io/v1beta1），并将 ingress host 用引号包裹（host: {{ $host | quote }}，见 templates/ingress.yaml）；
1.25.1：明确支持的 Kubernetes 版本更新为1.14+，与 README 的前置条件一致（Kubernetes 1.14+ 且启用 Beta API）；
1.5.12：移除所创建 ServiceAccount 的 namespace list 权限，收紧 RBAC 最小权限。

2.3 Ingress 与 TLS 的演进

1.0.7：支持 Ingress TLS；
1.1.0：支持 AWS ELB SSL（通过 ACM 证书，对应 values 中service.beta.kubernetes.io/aws-load-balancer-ssl-cert注解）；
1.6.6：若ingress.yaml中没有配置 host，则回退使用 default backend——这正是 templates/ingress.yaml 中{{- else }}分支的backend:段；
1.24.0：更新文档说明 TLS 变更，并移除 8154 https 端口的使用。这是 GoCD 20.2.0 之后的重要变化：GoCD 不再自带 SSL 处理，需要由反向代理（Apache、NGINX 等）承担 TLS 终止；
1.22.1：Ingress 版本 API 变更 + host 加引号。

2.4 生命周期钩子与容器扩展能力

CHANGELOG 显示这一家族能力是逐步累积的，全部可以在 templates/gocd-server-deployment.yaml 与 templates/gocd-agent-deployment.yaml 的lifecycle段找到对应实现：

1.0.5：新增postStart钩子脚本用于预配置 GoCD Server（preconfigure_server.sh）；
1.6.0：支持指定 init containers 与 restart policy；
1.8.0：引入 server 与 agent 的preStop 钩子，用于清理与备份；
1.9.1：支持 Deployment 与 Pod 级 annotations（对应server.annotations.deployment/server.annotations.pod）；
1.19.2：GoCD agent 的 postStart 生命周期钩子（agent.postStart）；
1.19.3：GoCD server 的sidecar containers（server.sidecarContainers）；
1.19.1：支持在 server 与 agent pod 上指定tolerations。

2.5 预配置（Preconfigure）机制的演进

1.1.1：若 server 已配置（检测到已有配置），则不重复执行preconfigure_server 脚本；
1.5.5：即使禁用持久化，也挂载 ConfigMap 来预配置 server（issue #8579 的修复）；
1.5.10：允许覆盖 preconfigure 命令（server.preconfigureCommand）；
1.16.0：更新 Pipeline Config API 版本，使用 getting-started repo 的脚本来执行任务。

预配置逻辑的完整实现位于 templates/configmap.yaml，该 ConfigMap 在server.shouldPreconfigure=true时生成，包含preconfigure_server.sh脚本，主要做四件事：

循环探测http://localhost:8153/go/api/v1/health，等待 server 就绪；
检查/godata/logs/preconfigure_complete.log是否存在，存在则跳过（幂等）；
通过 GoCD API 创建cluster profile（k8-cluster-profile，plugin 为cd.go.contrib.elasticagent.kubernetes），配置go_server_url、kubernetes_cluster_url、namespace与从 ServiceAccount 读取的security_token；
创建elastic agent profile（demo-app，使用gocd/gocd-agent-docker-dind特权镜像）并创建示例 pipeline（getting_started_pipeline）。

脚本日志输出到/godata/logs/preconfigure.log，完成标记写入/godata/logs/preconfigure_complete.log。

2.6 Agent 能力与弹性插件

1.3.2：支持 privileged 模式（为 DinD，Docker-in-Docker 所需），对应 templates/gocd-agent-deployment.yaml 中的securityContext.privileged: {{ .Values.agent.privileged }}；
1.5.1：使用 Kubernetes elastic agent 插件 v2.0.0；
1.5.9：支持配置 agent 的 service account；
1.6.2：弃用agent.env.agentAutoRegisterEnvironemnts（拼写错误），改用agent.env.agentAutoRegisterEnvironments。模板中保留了兼容逻辑（见 templates/gocd-agent-deployment.yaml），优先读取新属性，缺失时回退旧属性；
1.8.0：agent 镜像更新为gocd-agent-alpine-3.9（values.yaml 中agent.image.repository的默认值即为此）；
1.13.0：GoCD docker registry artifact 插件从 v1.0.1-92 升级到 v1.1.0-104（values.yaml 默认的GOCD_PLUGIN_INSTALL_docker-registry-artifact-plugin环境变量即安装此插件）；
1.18.1：kubernetes 插件升级到 v3.2.0。

2.7 持久化与卷能力

1.3.0：支持 server 与 agent 使用SSH keys（通过 Kubernetes Secret 挂载到/home/go/.ssh）；
1.4.3：为 server 与 agents 增加 extra volumes 与 extra volumeMounts；
1.5.8：不启用持久化时也能使用 extra volume mounts（修复回归的 1.6.3 也与此相关）；
1.26.1：更新~/.ssh目录中文件的权限（默认 256，即 0400）。

2.8 其他值得注意的变更

1.3.3：agent 支持 hostAliases（1.3.1 起 server 已支持）；
1.4.2：新增agent.env.extraEnvVars；
1.5.2：修复 agent kube resources 拼写错误；
1.5.3：server 与 agent 支持 affinity 设置，并修复 agent deployment 的无效 nodeSelector 引用；
1.5.6：新增 deployment strategy 值（agent.deployStrategy）；
1.6.0：init containers 与 restart policy；
1.14.0：支持指定 server 与 agent pod 的安全约束（securityContext），并将 JVM 参数属性改名；
1.20.1：更新 OWNERS 列表；
1.31.0：弃用 GoCD Helm Chart，最终版 1.32.0 将 GoCD 升到 20.8.0。

三、Server 与 Agent 核心配置参数详解

3.1 GoCD Server 配置

默认值详见 stable/gocd/values.yaml，关键参数如下：

参数	说明	默认值
`server.enabled`	是否部署 GoCD Server；设为`false`可实现 Agent Only 部署	`true`
`server.shouldPreconfigure`	是否预配置默认 elastic agent profile 与 Kubernetes 插件设置	`true`
`server.preconfigureCommand`	自定义预配置命令，列表类型	`["/bin/bash", "/preconfigure_server.sh"]`
`server.preStop`	server 停止前执行的清理/备份命令	`nil`
`server.image.repository`/`tag`	Server 镜像与 tag	`gocd/gocd-server`/ 默认`.Chart.appVersion`
`server.env.goServerJvmOpts`	Server JVM 参数，如`-Xmx4096mb -Dfoo=bar`，注入环境变量`GOCD_SERVER_JVM_OPTS`	`nil`
`server.env.extraEnvVars`	额外环境变量，常用于安装插件（见下文）	默认含两个插件
`server.service.type`	Service 类型	`NodePort`
`server.service.httpPort`	HTTP 端口	`8153`
`server.ingress.enabled`/`hosts`/`tls`	Ingress 开关、主机记录与 TLS 配置	`true`/`nil`/`[]`
`server.healthCheck.*`	健康检查：initialDelaySeconds=90、periodSeconds=15、failureThreshold=10	—
`server.securityContext.*`	runAsUser=1000、runAsGroup=0、fsGroup=0	—
`server.security.ssh.*`	SSH 密钥挂载开关、secret 名称（`gocd-server-ssh`）与权限	`false`/`gocd-server-ssh`/ 256
`server.sidecarContainers`	与 Server 并跑的 sidecar 容器	`[]`
`server.persistence.*`	持久化配置，见下文	—

模板中健康检查探针指向http://{containerPort}/go/api/v1/health（liveness 与 readiness 共用，见 gocd-server-deployment.yaml），因此 Server 的启动时间决定了initialDelaySeconds需要偏大（默认 90 秒）。

3.2 插件安装：GOCD_PLUGIN_INSTALL 机制

README 的 "Adding plugins" 章节与 CHANGELOG 1.18.2（"Add information about adding plugins"）对应。插件通过环境变量安装，环境变量名必须以GOCD_PLUGIN_INSTALL_为前缀：

server: env: extraEnvVars: - name: GOCD_PLUGIN_INSTALL_email-notifier value: https://github.com/gocd-contrib/email-notifier/releases/download/v0.3-68-exp/email-notifier-0.3-68.jar

values.yaml 默认已安装两个插件（values.yaml 第 123-127 行）：

GOCD_PLUGIN_INSTALL_kubernetes-elastic-agents→ kubernetes-elastic-agent-3.4.0-196.jar
GOCD_PLUGIN_INSTALL_docker-registry-artifact-plugin→ docker-registry-artifact-plugin-1.1.0-104.jar

对已运行的 GoCD Server 添加插件，会触发新 Server pod 的创建并完成插件安装。

3.3 GoCD Agent 配置

Agent 默认replicaCount=0（不启动静态 Agent，推荐使用弹性 Agent），关键参数见 values.yaml 第 228-407 行：

参数	说明	默认值
`agent.replicaCount`	静态 Agent 副本数	`0`
`agent.image.repository`	Agent 镜像	`gocd/gocd-agent-alpine-3.9`
`agent.env.goServerUrl`	Server URL；为空时模板自动生成`http://{release}-gocd-server:8153/go`	`nil`
`agent.env.agentAutoRegisterKey`/`Resources`/`Environments`/`Hostname`	Agent 自动注册的 key、资源、环境与主机名	`nil`
`agent.env.goAgentJvmOpts`	Agent JVM 参数（环境变量`GOCD_AGENT_JVM_OPTS`）	`nil`
`agent.env.goAgentBootstrapperArgs`	Agent Bootstrapper 参数，可配置端到端传输安全（TLS）	`nil`
`agent.privileged`	特权模式，DinD Agent 需要	`false`
`agent.healthCheck.enabled`	健康检查开关，默认关闭；开启后探针指向`/health/v1/isConnectedToServer:8152`	`false`
`agent.deployStrategy`	Deployment 滚动更新策略	`{}`
`agent.postStart`/`agent.preStop`	Agent 启动后/停止前钩子命令	`nil`
`agent.securityContext.`/`agent.security.ssh.`	同 Server	—
`agent.serviceAccount.reuseTopLevelServiceAccount`/`name`	Agent 专属 ServiceAccount 配置	`false`/`nil`

四、持久化：动态供给、静态卷与现有 PVC

4.1 动态卷供给（默认）

Chart 默认支持动态卷供给（依赖底层云平台的默认 StorageClass）。注意默认供给器的 reclaim policy 多为delete，PVC 被删除时数据也会一并删除。默认值：

Server：server.persistence.enabled=true，accessMode=ReadWriteOnce，size=2Gi
Agent：agent.persistence.enabled=false，size=1Gi

Server PVC 通过三个 subPath 挂载（见 gocd-server-deployment.yaml）：

godata→/godata（配置、数据库、插件目录）
homego→/home/go
scripts→/docker-entrypoint.d（自定义启动脚本）

4.2 静态卷与现有 PVC

要绑定静态 PV，将storageClass设为-以禁用动态供给，并用pvSelector选择正确的卷；
使用已有 PVC：先创建 PV 与 PVC，再安装：

helm install --name gocd-app --set server.persistence.existingClaim=PVC_NAME stable/gocd

4.3 额外卷挂载

可在persistence.extraVolumes/extraVolumeMounts中挂载 Secret、ConfigMap 等。例如挂载 GitHub 私钥 Secret：

server: persistence: enabled: true extraVolumeMounts: - name: github-key mountPath: /etc/config/keys/ readOnly: true extraVolumes: - name: github-key secret: secretName: github-key defaultMode: 0744

注意：/home/go被多个 Agent 共享意味着缓存的包与其中的 Secret 也会被共享，多 Agent 共享目录时需评估安全影响（README "Persistence" 章节的明确提示）。

五、Init 容器：在启动前准备环境

CHANGELOG 1.6.0 引入 init containers，典型用途是在 Agent 启动前下载kubectl等工具：

agent: persistence: extraVolumes: - name: kubectl emptyDir: {} extraVolumeMounts: - name: kubectl mountPath: /usr/local/bin/kubectl subPath: kubectl initContainers: - name: download-kubectl image: "ellerbrock/alpine-bash-curl-ssl:latest" imagePullPolicy: "IfNotPresent" volumeMounts: - name: kubectl mountPath: /download workingDir: /download command: ["/bin/bash"] args: - "-c" - 'curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl && chmod +x ./kubectl'

init 容器耗时较长时，需相应调大server.healthCheck.initialDelaySeconds或agent.healthCheck.initialDelaySeconds。

六、RBAC 与 ServiceAccount：支撑 Kubernetes 弹性 Agent

弹性 Agent 插件需要在运行 Job 时按需拉起 Pod，因此需要相应 RBAC 权限（CHANGELOG 1.3.6 修复过 README 中的 role 配置说明）：

rbac.create=true（默认）时创建 cluster role，权限为：nodes（list, get）、events（list, watch）、namespace（list, get）、pods与pods/log（*）；
同时创建 cluster role binding 与 gocd service account；
若rbac.create=true且serviceAccount.create=false，则使用命名空间下的defaultservice account 做绑定；

若rbac.create=false，则需手动创建 cluster role binding：

kubectl create clusterrolebinding clusterRoleBinding \ --clusterrole=CLUSTER_ROLE_WITH_NECESSARY_PRIVILEGES \ --serviceaccount=NAMESPACED_SERVICE_ACCOUNT

也可复用已有角色：--set rbac.roleRef=ROLE_NAME。

Agent 的 ServiceAccount 有独立配置（对应 CHANGELOG 1.5.9）：

状态	效果
`reuseTopLevelServiceAccount=false`且`name`为空	使用`default`service account
`reuseTopLevelServiceAccount=false`且`name='agentSA'`	使用已存在的`agentSA`（需预先绑定适当角色）
`reuseTopLevelServiceAccount=true`	复用顶层 GoCD service account（即 Server 所用的账号）

模板中的实现位于 templates/_helpers.tpl：gocd.serviceAccountName决定 Server 的 SA，gocd.agentServiceAccountName决定 Agent 的 SA。

七、Ingress 与 TLS 实战

7.1 Ingress 工作原理

Ingress Controller 充当 GoCD Server 前的反向代理：

集群内 Agent：绕过 Ingress 直接访问 Service（http://{release}-gocd-server:8153/go）；
集群外 Agent：通过 Ingress 或 LoadBalancer 的 http(s) 端口连接 Server。

模板逻辑（templates/ingress.yaml）：

配置了server.ingress.hosts时生成rules，每个 host 指向 server service 的 8153 端口；
未配置 hosts 时退化为backend默认后端（CHANGELOG 1.6.6 的变更）；
配置了server.ingress.tls时输出 TLS 段。

配置示例：

server: ingress: enabled: true hosts: - ci.example.com annotations: kubernetes.io/ingress.class: nginx tls: - secretName: ci-example-tls hosts: - ci.example.com

常用注解（README Ingress 章节）包括ingress.kubernetes.io/force-ssl-redirect、kubernetes.io/ingress.allow-http（GCE，默认 true）、alb.ingress.kubernetes.io/backend-protocol（EKS）、networking.gke.io/managed-certificates（GCP）与alb.ingress.kubernetes.io/certificate-arn（AWS ACM）等。

7.2 GoCD 20.2.0+ 的 TLS 变更

自 GoCD v20.2.0 起（CHANGELOG 1.24.0），GoCD 改变了 SSL 处理方式：不再自行提供 HTTPS 端口（8154 已移除），需要由支持 TLS 的反向代理（Apache、NGINX 等）终结 TLS。从 20.2.0 以下版本升级时，Agent 需要重新配置连接方式。因此 Ingress 承担了 HTTPS 终结的职责，配置 TLS 时需将 Secret 指向包含私钥与证书的 TLS Secret。

八、SSH 密钥挂载

为支持通过 SSH 访问代码仓库（CHANGELOG 1.3.0 引入），Secret 结构需完整容纳.ssh目录内容：

ssh-keygen -t rsa -b 4096 -C "user@example.com" -f gocd-server-ssh -P '' ssh-keyscan [host] > gocd_known_hosts kubectl create secret generic gocd-server-ssh \ --from-file=id_rsa=gocd-server-ssh \ --from-file=id_rsa.pub=gocd-server-ssh.pub \ --from-file=known_hosts=gocd_known_hosts

启用方式：server.security.ssh.enabled=true（Agent 同理为agent.security.ssh.enabled=true），Secret 以只读方式挂载到/home/go/.ssh，文件权限由defaultMode控制（默认 256，即 0400，对应 CHANGELOG 1.26.1 的权限修复）。

九、安装、预配置与排障

9.1 安装与卸载

# 添加仓库并安装 helm repo add stable https://kubernetes-charts.storage.googleapis.com helm install --name gocd-app --namespace gocd stable/gocd # 卸载 helm delete --purge gocd-app

前置条件：Kubernetes 1.14+（启用 Beta API）、底层支持 PV 供给、LoadBalancer 或 Ingress Controller；启动 Tiller 的 ServiceAccount 需有创建 role 的权限（minikube 使用--bootstrapper kubeadm，GKE 下可为 kube-system 的 default SA 创建 cluster-admin 绑定）。

9.2 预配置机制与幂等性

安装后 Server pod 通过postStart钩子执行预配置（templates/gocd-server-deployment.yaml），期间 Pod 处于ContainerCreating。预配置会：

等待 health 接口返回 200；
若检测到/godata/logs/preconfigure_complete.log（即已有配置），直接跳过——这正是 CHANGELOG 1.1.1 引入的幂等保护；
依次创建 cluster profile（k8-cluster-profile）、elastic agent profile（demo-app）、示例 pipeline（getting_started_pipeline）。

注意：若 Server 从已有持久卷启动（已存在配置），务必设置server.shouldPreconfigure=false，否则 API 调用会因安全配置而失败。

排障手段：

kubectl get pods --namespace gocd kubectl describe pods --namespace gocd # 关注 FailedPostStartHook 事件 helm status gocd-app

预配置日志位于/godata/logs/preconfigure.log。常见失败原因（README 明确指出）：

ServiceAccount token 权限不足，创建插件设置的 API 调用失败；
Server 以已配置且开启安全模式的既有配置启动，预配置 API 调用失败。

十、总结与迁移建议

从 1.0.0（由 incubator 移入 stable）到 1.32.0，GoCD Helm Chart 在四年左右的演进中沉淀了大量 Kubernetes 部署实践：预配置自动化、弹性 Agent 集成、DinD 特权模式、SSH 密钥管理、持久化多场景、RBAC 最小权限、Ingress/TLS 支持、生命周期钩子与 Sidecar/Init 容器扩展。其设计思路——"Server 单一实例 + 弹性 Agent 按需扩容"——至今仍是 GoCD on Kubernetes 的主流形态。

需要特别留意的是：该 Chart 已于 1.31.0 被官方标记为废弃（deprecated: true），1.32.0 为最终版本。新项目请直接使用 GoCD 官方 Helm Chart（helm repo add gocd https://gocd.github.io/helm-chart后使用gocd/gocd），本文梳理的版本演进与参数含义，可作为理解 GoCD 官方 Chart 及迁移配置时的重要参考。