fluxcd/helm-controller

helm-controller 技术文档

概述

helm-controller 是 Flux（CNCF 毕业项目）的核心组件，专为 Kubernetes 集群设计，专注于 Helm Chart 发布生命周期的自动化管理。作为 Flux 生态的关键组件，它通过声明式 API 和 GitOps 流程，实现 Helm Release 的部署、升级、回滚及删除等全生命周期操作，是在 Kubernetes 中践行 GitOps 理念时管理 Helm 资源的核心工具。

核心功能

• 声明式 Helm Release 管理：通过自定义资源 HelmRelease 声明 Helm Chart 发布配置，支持版本固定、values 覆盖等精细控制。
• 自动化触发机制：与 source-controller 集成，可基于 Git 仓库变更或 Helm Repository 索引更新自动触发 Release 同步。
• 生命周期保障：提供自动重试、失败回滚、健康检查等机制，确保 Release 状态与期望一致。
• 状态可视化：通过 status 字段暴露 Release 部署状态、历史版本、错误信息等关键指标，便于监控与调试。

使用场景

• GitOps 驱动的 Helm 部署：在 Flux 管理的 Kubernetes 集群中，通过 Git 仓库声明 HelmRelease，实现 Chart 发布的可审计与自动化。
• 多环境一致性管理：通过同一套 Git 配置管理开发、测试、生产环境的 Helm Release，确保环境配置一致性。
• 大规模集群的 Release 治理：集中管理成百上千个 Helm Release，通过自动化减少人工操作风险，提升运维效率。

使用方法

前置条件

• Kubernetes 集群（版本 ≥ 1.24）
• Flux 已安装（helm-controller 随 Flux 一同部署，无需单独安装）

安装 Flux（含 helm-controller）

通过 Flux 官方引导命令安装 Flux 组件（默认包含 helm-controller）：

bash
flux bootstrap github \
  --owner=<你的 GitHub 用户名> \
  --repository=<你的 Git 仓库名> \
  --branch=main \
  --path=./clusters/my-cluster \
  --personal

部署示例：管理 Nginx Ingress Controller

1. 定义 Helm 仓库源

创建 HelmRepository 资源，指定 Nginx Ingress Controller Chart 所在仓库：

yaml
# ingress-nginx-repo.yaml
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
  name: ingress-nginx
  namespace: flux-system
spec:
  interval: 1h
  url: https://kubernetes.github.io/ingress-nginx

2. 定义 HelmRelease 资源

创建 HelmRelease 资源，声明 Nginx Ingress Controller 的发布配置：

yaml
# ingress-nginx-release.yaml
apiVersion: helm.toolkit.fluxcd.io/v2beta2
kind: HelmRelease
metadata:
  name: ingress-nginx
  namespace: default
spec:
  interval: 5m  # 每 5 分钟检查一次更新
  chart:
    spec:
      chart: ingress-nginx
      version: "4.8.3"  # Chart 版本
      sourceRef:
        kind: HelmRepository
        name: ingress-nginx
        namespace: flux-system
  install:
    createNamespace: true  # 自动创建目标命名空间
  values:  # 覆盖 Chart 默认 values
    controller:
      replicaCount: 2
      service:
        type: LoadBalancer

3. 应用配置至集群

将上述 YAML 文件提交至 Flux 监控的 Git 仓库，或直接通过 kubectl 应用：

bash
kubectl apply -f ingress-nginx-repo.yaml
kubectl apply -f ingress-nginx-release.yaml

验证部署状态

检查 HelmRelease 状态：

bash
kubectl get helmrelease ingress-nginx -n default -o wide

查看详细事件与状态：

bash
kubectl describe helmrelease ingress-nginx -n default

配置参数

HelmRelease 核心配置参数说明：

• spec.chart.spec.version：指定 Helm Chart 版本，支持语义化版本约束（如 ^4.8.0）。
• spec.values：覆盖 Chart 默认 values，支持引用 ConfigMap/Secret 中的配置。
• spec.install.strategy：安装策略，可选 RollingUpdate（默认）或 Recreate。
• spec.upgrade.preserveValues：升级时是否保留现有 values，避免被 Chart 默认值覆盖。
• spec.rollback.enabled：是否启用自动回滚（默认 false，需手动开启）。

更多配置细节请参考 https://fluxcd.io/flux/components/helm/helmrelease/。