Helm安装Longhorn时CRD未自动创建？

Question

在使用 Helm 安装 Longhorn 时，部分用户遇到 CRD（如 `LonghornVolume`、`LonghornNode` 等）未自动创建的问题，导致组件无法正常运行。该问题通常出现在 Helm 版本较旧或 Helm 安装过程中跳过了 `crds/` 目录的部署。Longhorn Chart 的 CRD 并非通过 Helm 模板自动安装，而是需手动应用或启用 `--include-crds` 参数。若未正确处理，控制器会因 CRD 缺失而报错，集群中也查找不到自定义资源定义。建议在安装时显式添加 `--create-namespace --include-crds` 参数，或预先手动应用 CRD 清单以确保注册成功。

Answer 1

1. 问题背景与现象描述

在使用 Helm 安装 Longhorn 存储系统时，部分用户反馈安装后控制器（Controller）无法正常运行，日志中频繁出现类似 no matches for kind "LonghornVolume" in version "longhorn.io/v1beta2" 的错误信息。进一步检查发现，Kubernetes 集群中并未注册 Longhorn 所需的自定义资源定义（CRD），例如 LonghornVolume、LonghornNode、LonghornEngine 等。

该问题通常出现在以下场景：

• Helm 版本低于 v3.3.0，不支持自动处理 CRD 目录；
• 执行 helm install 时未添加 --include-crds 参数；
• Chart 包结构中存在独立的 crds/ 目录，但 Helm 跳过了其部署流程。

2. 技术原理与 Helm CRD 处理机制

Helm 自 v3.2.0 起引入了对 CRD 的增强管理能力，并在 v3.3.0 正式支持通过 --include-crds 参数在安装时自动应用 crds/ 目录下的所有清单文件。然而，这一行为并非默认开启，必须显式声明。

Longhorn 的 Helm Chart 设计遵循此模式：其仓库中的 crds/ 目录包含所有必需的 CRD 定义，但这些文件不会被模板化注入到 templates/ 中，以避免升级时的不可变字段冲突。因此，若未正确加载 CRD，即使 Deployment 成功部署，控制器也无法识别自定义资源类型。

3. 常见排查路径与诊断方法

当遇到 Longhorn 组件异常时，应按如下顺序进行诊断：

1. 查看命名空间中 Pod 状态：kubectl get pods -n longhorn-system
2. 检查控制器日志：kubectl logs -n longhorn-system <longhorn-manager-pod>
3. 确认 CRD 是否存在：kubectl get crd | grep longhorn
4. 验证 Helm 版本：helm version
5. 检查 Helm 安装命令是否包含 --include-crds

检查项	预期结果	异常表现
kubectl get crd | grep longhorn	显示至少 10 个 Longhorn CRD	无输出或仅个别存在
helm list -n longhorn-system	显示已安装 release	release 存在但组件未就绪
Pod 日志关键词	failed to list *v1beta2.Longhorn*	大量资源类型未找到错误

4. 解决方案与最佳实践

为确保 Longhorn CRD 正确注册，推荐采用以下任一方式：

方案一：使用 --include-crds 参数安装

helm repo add longhorn https://charts.longhorn.io
helm repo update
helm install longhorn longhorn/longhorn \
  --namespace longhorn-system \
  --create-namespace \
  --include-crds

方案二：手动预先应用 CRD 清单

适用于 Helm 版本较旧或需要精细化控制部署流程的环境：

kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.5.0/chart/crds.yaml

或克隆仓库后本地应用：

git clone https://github.com/longhorn/longhorn.git
kubectl apply -f longhorn/chart/crds/

5. 自动化检测与 CI/CD 集成建议

在生产级部署中，建议将 CRD 检查纳入部署前校验流程。可通过脚本实现自动化验证：

#!/bin/bash
EXPECTED_CRDS=("longhornvolumes.longhorn.io" "longhornnodes.longhorn.io" "longhornengines.longhorn.io")
for crd in "${EXPECTED_CRDS[@]}"; do
  if ! kubectl get crd $crd > /dev/null 2>&1; then
    echo "CRD $crd not found. Please install CRDs first."
    exit 1
  fi
done
echo "All required CRDs are present."

此外，在 GitOps 流程中（如 ArgoCD 或 Flux），可将 CRD 应用作为前置 Helm 同步步骤，或启用 Helm 插件如 helm-crds 来分离管理。

6. 架构视角下的设计权衡分析

为何 Longhorn 不将 CRD 写入 templates/ 目录？原因在于 Kubernetes 对 CRD 的更新限制：某些字段（如 spec.preserveUnknownFields）一旦设置便不可变更，直接通过 Helm 管理会引发升级失败。因此社区普遍采用“外部管理 CRD”模式。

Mermaid 流程图展示了推荐的部署顺序：

graph TD
    A[开始部署] --> B{Helm 版本 ≥ v3.3.0?}
    B -- 是 --> C[执行 helm install --include-crds]
    B -- 否 --> D[手动 kubectl apply -f crds/]
    C --> E[等待 Pod 就绪]
    D --> E
    E --> F[验证 CRD 注册状态]
    F --> G[完成 Longhorn 初始化]