Bitnami KubeRay Helm Chart 版本演进全解析：从 0.1.0 到 1.4.x 的安全加固与功能迭代路线图

KubeRay 是基于 Kubernetes CRD 的 Ray 分布式计算集群管理算子，而 bitnami/kuberay 则是 Bitnami 将其容器化封装后发布的官方 Helm Chart。本文以该 Chart 的 CHANGELOG 为时间主线，逐版本还原从 2023 年 12 月首次发布（0.1.0）到 2025 年 8 月（1.4.29）的完整演进过程，并对照仓库中的 values.yaml、Chart.yaml 与模板源码，说明每一项变更对应的实际配置项与运行效果。读完本文，你将掌握 KubeRay Chart 的版本基线、安全默认值变迁、RBAC 与多命名空间模型、可观测性集成方式，以及升级时需要注意的破坏性变更。

一、版本基线与发布背景

当前仓库中 KubeRay Chart 的元数据可以在 Chart.yaml 中确认：

• Chart 版本：1.4.30（CHANGELOG 记录的最近一次发布为 1.4.29，2025-08-26）
• 应用版本：1.4.2（对应上游 KubeRay Operator / API Server 的版本号）
• API 版本：apiVersion: v2（Helm 3 专用 Chart）
• 关键依赖：common（Bitnami 通用模板库，版本 2.x.x，以 OCI 方式从 registry-1.docker.io/bitnamicharts 拉取）
• 内置镜像（见 Chart.yaml 的 annotations.images）：
  • kuberay-apiserver:1.4.2-debian-12-r2
  • kuberay-operator:1.4.2-debian-12-r2
  • ray:2.49.0-debian-12-r0

Chart 提供的三大组件在 values.yaml 中分别对应 operator、apiserver 与 cluster 三个配置段，并在模板目录中一一对应：templates/operator/、templates/apiserver/ 与 templates/cluster/（后者渲染 ray.io/v1 的 RayCluster CRD 对象，见 templates/cluster/raycluster.yaml）。三个 CRD（rayclusters、rayjobs、rayservices）被随 Chart 一并打包在 crds 目录下，由 Helm 在安装时自动注册。

部署前提（来自 README.md）为 Kubernetes 1.23+ 与 Helm 3.8.0+；一键安装命令为：

helm install my-release oci://registry-1.docker.io/bitnamicharts/kuberay

二、完整版本时间线：0.1.0 → 1.4.29

CHANGELOG 记录的全部发布节点如下（主版本与次版本用加粗标注，补丁版本合并列出）：

版本	日期	核心变更
0.1.0	2023-12-14	首次发布 Chart
0.1.1 – 0.1.6	2023-12 至 2024-01	更新组件镜像版本；修复 worker 中 podSecurityContext.enabled 判断
0.2.0	2024-01-16	强化 podSecurityContext 与 containerSecurityContext 的安全默认值
0.2.1	2024-01-18	更新组件版本
0.3.0	2024-01-22	将 ServiceAccount token 自动挂载移到 Pod 声明层级；更新 CRD 并添加 source header
0.3.1 – 0.3.4	2024-01 至 2024-02	为 OpenShift 兼容将 seLinuxOptions 置空；文档从 docs.bitnami.com 回迁 README
0.4.0	2024-02-06	默认启用 NetworkPolicy
0.4.1 – 0.4.2	2024-02	更新组件版本
0.5.0	2024-02-15	引入 resourcesPreset 资源预设支持
0.6.0 – 0.6.2	2024-02	统一版本号；更新组件版本
0.7.0	2024-02-29	为容器安全上下文补充 runAsGroup
0.8.0	2024-03-06	增加 OpenShift restricted-v2 SCC 的自动适配
0.8.1 – 0.8.2	2024-03	更新组件版本；修正缩进
1.0.0	2024-03-12	破坏性变更：全面提升安全默认值
1.0.1 – 1.0.4	2024-04 至 2024-05	资源预设注释修正；文档与版权调整；组件版本更新
1.1.0	2024-05-21	增加替换镜像时的告警提示（NOTES.txt）；引入 tag 与 changelog 支持
1.1.1 – 1.1.3	2024-05 至 2024-06	区分 liveness/readiness 探针；版本升级
1.2.0	2024-06-06	默认启用 PodDisruptionBudgets（PDB）
1.2.1 – 1.2.7	2024-06 至 2024-07	版本升级与 TAC 文案调整
1.2.8	2024-07-16	引入 global.defaultStorageClass 作为默认存储类
1.2.9 – 1.2.20	2024-07 至 2024-12	组件版本升级；补充 "Backup & Restore" 与 "Prometheus metrics" 文档
1.3.0	2024-12-10	增加非标准镜像检测（镜像校验）；NOTES.txt 增加 Bitnami Premium 提示
1.3.1 – 1.3.7	2025-01 至 2025-02	为 ClusterRole 补充 endpoints 资源的 list/watch 权限；版本升级
1.4.0	2025-02-20	使用新的 helper 检查 Kubernetes API 版本
1.4.1 – 1.4.10	2025-03 至 2025-05	更新 common 依赖并移除 k8s < 1.23 引用；ClusterRole 与上游对齐
1.4.11 – 1.4.18	2025-05 至 2025-06	修正 nodeAffinity 缩进；增加 crNamespacedRbacEnable RBAC 开关；持续更新依赖
1.4.19	2025-07-07	operator.metrics.serviceMonitor.honorLabels 与上游对齐（默认 true）
1.4.20 – 1.4.24	2025-07	依赖引用更新
1.4.25	2025-07-19	README 引入 BSI（Bitnami Secure Images）品牌与欢迎语
1.4.26	2025-08-07	NOTES 中更新 BSI 安全提示；依赖更新
1.4.27 – 1.4.29	2025-08	依赖引用更新

从时间线可以清晰看到两条主线：依赖引用（Update dependency references）持续占据绝大多数补丁版本，说明该 Chart 的发布节奏与上游容器镜像（operator / apiserver / ray）版本强绑定；功能演进集中在 0.x → 1.0.0 的早期阶段，此后再无破坏性大版本，进入以安全对齐与依赖维护为主的稳定期。

三、安全默认值演进：0.2.0 到 1.0.0 的加固路线

CHANGELOG 中 0.x 阶段的几乎所有功能性提交都围绕“安全加固”展开，这正是 1.0.0 被标记为破坏性变更（feat!: :lock: :boom:）的原因。

3.1 容器与 Pod 安全上下文（0.2.0、0.7.0）

• 0.2.0 强化了 podSecurityContext 与 containerSecurityContext 的“essential（最小必要）字段”。
• 0.7.0 补充 runAsGroup，使 UID/GID 不再依赖平台默认。

这些默认值至今仍保留在 values.yaml 中，并且 operator、apiserver、cluster.head、cluster.worker.common 四段配置完全一致，例如：

containerSecurityContext:
  enabled: true
  runAsUser: 1001
  runAsGroup: 1001
  runAsNonRoot: true
  privileged: false
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false
  capabilities:
    drop: ["ALL"]
  seccompProfile:
    type: "RuntimeDefault"

对应地，Pod 级安全上下文设置 fsGroup: 1001、fsGroupChangePolicy: Always。这套默认值意味着：以非 root 用户（1001）运行、只读根文件系统、丢弃全部 Linux capabilities、禁止提权并施加 RuntimeDefault seccomp 约束——任何依赖特权容器能力的自定义脚本都可能被破坏，这也是 1.0.0 升级说明中特别提示的原因。

3.2 NetworkPolicy 默认开启（0.4.0）

0.4.0 将 NetworkPolicy 设为默认创建。在 values.yaml 中，operator.networkPolicy 与 apiserver.networkPolicy 均默认 enabled: true，且预置了 kube-apiserver 常用端口列表：

networkPolicy:
  enabled: true
  kubeAPIServerPorts: [443, 6443, 8443]
  allowExternal: true
  allowExternalEgress: true

kubeAPIServerPorts 用于限定到 apiserver 的出口端口，README 中建议按集群实际设置收敛以提升安全性；allowExternal 为 false 时，只有携带正确 server 标签的 Pod 才能访问监听端口。

3.3 OpenShift 兼容（0.3.1、0.8.0、1.0.0）

• 0.3.1 将 seLinuxOptions 置为 null 以适配 OpenShift；
• 0.8.0 引入对 OpenShift restricted-v2 SCC 的自动适配；
• 1.0.0 将 global.compatibility.openshift.adaptSecurityContext 的默认值从 disabled 改为 auto。

当前该参数的取值语义在 values.yaml 中注释明确：auto（检测到 OpenShift 集群时自动应用）、force（始终适配）、disabled（不做适配）。适配行为是移除 runAsUser、runAsGroup、fsGroup，交由平台分配默认 ID。

3.4 镜像校验与安全提示（1.1.0、1.3.0、1.4.25/1.4.26）

• 1.1.0 在 NOTES.txt 中加入“替换原始镜像”的告警；
• 1.3.0 引入非标准镜像检测（Detect non-standard images），即安装时的镜像校验能力；
• 1.4.25/1.4.26 系列将品牌与安全提示切换为 BSI（Bitnami Secure Images）。

镜像校验由 global.security.allowInsecureImages 控制（默认 false，见 values.yaml）。README 的 Upgrading 一节明确指出：升级到 1.3.0 后如需跳过镜像校验，必须显式设置：

global:
  security:
    allowInsecureImages: true

四、资源预设与调度能力（0.5.0）

0.5.0 引入的 resourcesPreset 是 Bitnami 系列 Chart 的通用机制，底层实现在 bitnami/common 子 Chart 的资源模板中（common 模板）。本 Chart 为不同组件设置了不同预设默认值（values.yaml）：

组件	预设键	默认值
operator	operator.resourcesPreset	nano
apiserver	apiserver.resourcesPreset	nano
Ray head	cluster.head.resourcesPreset	large
Ray worker	cluster.worker.common.resourcesPreset	small

预设的合法取值为 none, nano, micro, small, medium, large, xlarge, 2xlarge。README 明确提示：生产环境应使用 resources 显式声明 requests/limits，而非依赖 resourcesPreset（预设只保证在官方测试套件中能跑通的最小规模）。例如为 operator 显式设置资源：

operator:
  resources:
    requests:
      cpu: 2
      memory: 512Mi
    limits:
      cpu: 3
      memory: 1024Mi

resources 一旦设置即忽略 resourcesPreset，这是升级到 1.0.0 时最容易察觉的变化之一——resourcesPreset 默认值从 none 调整为最小可用规格。

五、可用性与扩展性：PDB、存储类与多命名空间

5.1 PodDisruptionBudget（1.2.0）

1.2.0 为 operator 与 apiserver 默认启用 PDB。在 values.yaml 中两段配置对称：

pdb:
  create: true
  minAvailable: ""
  maxUnavailable: ""

模板 templates/operator/pdb.yaml 与 templates/apiserver/pdb.yaml 负责渲染。minAvailable 与 maxUnavailable 两者至少设置其一（可填数字或百分比），默认均为空字符串，此时 PDB 仅创建骨架对象，需由用户补充约束。

5.2 全局默认存储类（1.2.8）

1.2.8 引入 global.defaultStorageClass 作为全局默认 StorageClass（旧键 global.storageClass 被标记为 DEPRECATED，见 values.yaml）。对 KubeRay 而言，该参数用于为 Ray head/worker 的持久卷提供默认存储类。

5.3 多命名空间监控与 RBAC 开关（1.3.3、1.4.9、1.4.10、1.4.17）

KubeRay Operator 默认跨命名空间工作（operator.watchAllNamespaces: true）。这一系列提交逐步打磨了与之配套的 RBAC：

• 1.3.3：为 ClusterRole 增加 endpoints 资源的 list/watch 权限，解决跨命名空间下 Operator 无法观测 endpoints 的问题；
• 1.4.9：match upstream clusterrole，将 RBAC 规则与上游 KubeRay 官方对齐；
• 1.4.10：更新 common 依赖并移除 Kubernetes < 1.23 的兼容引用；
• 1.4.17：新增 operator.crNamespacedRbacEnable 开关——当 operator.watchAllNamespaces 设为 false 时，控制是否仍创建集群级 RBAC 资源（默认 true，见 values.yaml）。

RBAC 的实际渲染逻辑在 templates/operator/clusterroles.yaml 中可以看到清晰的开关链：仅当 operator.enabled && operator.rbac.create && operator.watchAllNamespaces 三者同时为真时才生成 ClusterRole，规则覆盖 batch/jobs、coordination.k8s.io/leases、events、endpoints 等资源。当 watchAllNamespaces=false 时，Chart 转而通过 operator.role.yaml / operator.rolebinding.yaml 渲染命名空间级 RBAC。

六、Prometheus 指标与可观测性（1.2.20、1.4.19）

1.2.20 为 README 补充了 "Prometheus metrics" 章节。当前 Chart 的指标采集支持两条路径（对应 values.yaml 中 operator.metrics 与 apiserver.metrics 两个对称配置段）：

1. 原生注解采集：设置 *.metrics.enabled=true 后，Service 会自动附加 prometheus.io/scrape: "true" 与 prometheus.io/port 注解，供标准 Prometheus 按注解自动抓取；
2. Prometheus Operator ServiceMonitor：设置 *.metrics.serviceMonitor.enabled=true（并同时开启 *.metrics.enabled），Chart 渲染 ServiceMonitor 模板。若集群未安装 Prometheus Operator CRD，安装会报错：

no matches for kind "ServiceMonitor" in version "monitoring.coreos.com/v1"

此时需先安装 kube-prometheus 或 prometheus Chart 以提供 CRD 与采集端。

1.4.19 是本主题在 1.4.x 阶段最重要的变更：将 operator.metrics.serviceMonitor.honorLabels 与上游对齐，从默认 false 调整为 true（见 values.yaml 中 operator.metrics.serviceMonitor.honorLabels: true；apiserver 段则保持 false）。honorLabels 决定指标标签与目标标签冲突时以谁为准，直接影响 Prometheus 中的标签语义，因此该提交在变更说明中特别注明“keep in sync with upstream”。

此外 1.2.20 同期补充的 "Backup & Restore" 章节建议使用 Velero 备份持久卷并在新部署中挂载，这是对有状态 Ray 集群数据迁移的官方建议路径。

七、细节修复与工程化沉淀

补丁版本中除依赖更新外，还沉淀了一批值得关注的工程修正：

• 1.4.0：改用统一的 helper 检测 Kubernetes API 版本，替代原先分散在模板中的 Capabilities 判断，降低多版本兼容维护成本；
• 1.4.12：修复 nodeAffinity 元素的缩进错误（fix(kuberay): wrong indentation in nodeAffinity element），此类 YAML 缩进问题会直接导致渲染出的 affinity 结构不合法，属于典型的“小改动、大影响”；
• 0.3.0：将 ServiceAccount token 自动挂载从 ServiceAccount 对象声明迁移到 Pod 声明层级，配合 automountServiceAccountToken 参数实现按 Pod 粒度控制（operator/apiserver 默认 true，head/worker 默认 false，见 values.yaml）；
• 1.1.1：为同一组件配置不同的 liveness 与 readiness 探针，替代原先共用一套探针的做法；
• 1.1.0 / 1.3.0 的工程化配套：为 CI 引入 tag 与 changelog 自动生成支持（Add tag and changelog support），这正是当前 CHANGELOG 能够逐版本可追溯的基础设施来源。

八、升级注意事项总结

结合 CHANGELOG 与 README.md 的 Upgrading 章节，从旧版本升级时需要重点核对以下两点：

升级到 1.3.0（镜像校验）：Chart 引入镜像校验，若使用自定义镜像或私有镜像源，需设置 global.security.allowInsecureImages: true 才能继续安装。

升级到 1.0.0（安全默认值）：两个默认值变化可能破坏既有部署的自定义逻辑：

• resourcesPreset 从 none 变为各组件的最小可用规格（operator/apiserver 为 nano，head 为 large，worker 为 small），容器会因此获得实际的资源 requests/limits；
• global.compatibility.openshift.adaptSecurityContext 从 disabled 变为 auto。

若部署依赖旧的宽松默认值，需在升级前将上述参数显式改回旧值。

九、结语

回顾 bitnami/kuberay 的整个 CHANGELOG，可以提炼出该 Chart 的演进规律：早期版本集中补齐安全上下文、NetworkPolicy、OpenShift 兼容、资源预设与 PDB 等生产级特性，1.0.0 以破坏性变更收束安全默认值；此后进入依赖同步与上游对齐的稳定维护期（CRD 对齐、ClusterRole 对齐、honorLabels 对齐、BSI 品牌切换）。对于使用者而言，理解这条演进路径的意义在于：任何旧版本的自定义 values 在升级前都应重新对照 values.yaml 与 README.md 校验安全默认值、RBAC 开关与资源预设的变化，再结合 Chart.yaml 确认镜像基线，即可安全完成从 0.x 到 1.4.x 的平滑迁移。