Helm

Helm是Kubernetes的首选软件包管理工具。Helm图表为Kubernetes YAML清单文档提供模板语法。使用 Helm，我们可以创建可配置的部署，而不仅仅是使用静态文件。有关创建您自己的部署目录的更多信息，请查看 https://helm.sh/docs/intro/quickstart/. 中的文档。

RKE2 不需要任何特殊配置即可与 Helm 命令行工具一起使用。请确保您已根据关于 集群访问 的部分正确设置 kubeconfig。RKE2 确实包含一些额外功能，使得使用 rancher/helm-release CRD 部署传统 Kubernetes 资源清单和 Helm Charts 更加容易。

自动部署清单和 Helm Charts

在 /var/lib/rancher/rke2/server/manifests 中找到的任何 Kubernetes 清单将在启动时以及磁盘中文件更改时，以类似于 kubectl apply 的方式自动部署到 RKE2。从此目录中删除文件不会从集群中删除相应的资源。

以这种方式部署的清单作为 AddOn 自定义资源进行管理，可以通过运行 kubectl get addon -A 来查看。默认情况下，您会发现 CoreDNS、Nginx-Ingress 和 Metrics Server 等打包组件的 AddOns。AddOns 由部署控制器自动创建，并根据清单目录中的文件名命名。

也可以将 Helm charts 作为 AddOns 部署。RKE2 包含一个 Helm Controller，它使用 HelmChart 自定义资源定义 (CRD) 管理 Helm charts。

文件命名要求

清单目录中每个文件的`AddOn`文件名是根据文件的基本名称生成的。 确保清单目录中的所有文件（或任何子目录中的文件）具有唯一的名称，并遵循 Kubernetes 对象命名限制。还应注意不要与默认 RKE2 打包组件使用的名称冲突，即使这些组件被禁用。

以下是一个错误示例，如果文件名包含下划线，将会报告该错误：

`Failed to process config: failed to process /var/lib/rancher/rke2/server/manifests/example_manifest.yaml:
   Addon.k3s.cattle.io "example_manifest" is invalid: metadata.name: Invalid value: "example_manifest":
   a lowercase RFC 1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character (e.g. 'example.com', regex used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')`

禁用 AddOns

上述列出的打包组件的 AddOns，以及放置在清单目录中的任何额外清单的 AddOns，可以使用 --disable 标志。被禁用的 AddOns 会从集群中主动卸载，并且源文件会从清单目录中删除。

例如，要禁用在新集群上安装 CoreDNS，或要卸载它并从现有集群中去除清单，您可以在配置文件中使用 disable: rke2-coredns 启动 RKE2。可以在嵌套列表中禁用多个项目。

# /etc/rancher/rke2/config.yaml
disable:
  - rke2-coredns
  - rke2-metrics-server

使用 Helm CRD

HelmChart资源定义捕获您通常会传递给`helm`命令行工具的大部分选项。以下是如何从默认图表储存库部署 Grafana 的示例，覆盖一些默认的图表值。请注意，HelmChart资源本身位于 `kube-system`名称空间，但图表的资源将被部署到 `monitoring`名称空间。

RKE2 also supports passing arguments directly to the helm-controller process with helm-controller-arg. This is useful when you want to tune controller behavior globally.

For example, to customize the CPU and memory resources allocated to Helm job pods:

# /etc/rancher/rke2/config.yaml
helm-controller-arg:
  - 'job-resources={"requests": {"cpu": "0.2", "memory": "64M"}, "limits": {"cpu": "1", "memory": "256M"}}'

You can specify helm-controller-arg multiple times in CLI form, or as a YAML list in the configuration file.

Version Gate

The helm-controller-arg flag is available since the RKE2 July 2026 releases: v1.36.3+rke2r1, v1.35.7+rke2r1, v1.34.10+rke2r1, v1.33.13+rke2r2

 
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: grafana
  namespace: kube-system
spec:
  chart: stable/grafana
  targetNamespace: monitoring
  set:
    adminPassword: "NotVerySafePassword"
  valuesContent: |-
    image:
      tag: master
    env:
      GF_EXPLORE_ENABLED: true
    adminUser: admin
    sidecar:
      datasources:
        enabled: true

从带有身份验证的私有储存库部署 Helm图表的示例：

apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  namespace: kube-system
  name: example-app
spec:
  targetNamespace: example-space
  createNamespace: true
  version: v1.2.3
  chart: example-app
  repo: https://secure-repo.example.com
  authSecret:
    name: example-repo-auth
  repoCAConfigMap:
    name: example-repo-ca
  valuesContent: |-
    image:
      tag: v1.2.2
---
apiVersion: v1
kind: Secret
metadata:
  namespace: kube-system
  name: example-repo-auth
type: kubernetes.io/basic-auth
stringData:
  username: user
  password: pass
---
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: kube-system
  name: example-repo-ca
data:
  ca.crt: |-
    -----BEGIN CERTIFICATE-----
    <YOUR CERTIFICATE>
    -----END CERTIFICATE-----

HelmChart字段定义

name 字段应遵循 Helm Chart 命名约定，并同时满足 Kubernetes 的 对象命名规则。更多信息请参见 Helm Best Practices 文档。
字段 默认值 说明 Helm参数/标志等效

metadata.name

Helm图表名称

名称

spec.chart

储存库中的Helm图表名称，或指向图表归档（.tgz）的完整HTTPS URL

图表

spec.targetNamespace

default

Helm图表目标命名空间

--namespace

spec.createNamespace

false

如果不存在，则创建目标命名空间

--create-namespace

spec.version

Helm图表版本（从储存库安装时）

--version

spec.repo

Helm图表储存库URL

--repo

spec.plainHTTP

false

使用不安全的 HTTP 连接下载 Chart。

--plain-http

spec.insecureSkipTLSVerify

false

跳过 Chart 下载时的 TLS 证书校验。

--insecure-skip-tls-verify

spec.helmVersion

v3

要使用的Helm版本（v2`或`v3）

spec.bootstrap

False

如果此图表需要启动集群（云控制器管理器等），则设置为 True。

spec.set

覆盖简单的默认 Chart 值。这些优先于通过 valuesContent 设置的选项。

--set / --set-string

spec.podSecurityContext

为 Helm Job Pod 自定义 v1.PodSecurityContext

spec.securityContext

为 Helm Job Pod 的容器自定义 v1.SecurityContext

spec.valuesContent

通过 YAML 文件内容覆盖复杂的默认 Chart 值。

--values

spec.valuesSecrets

通过引用外部 Secret 覆盖复杂 Chart 值

--values

spec.chartContent

Base64编码的图表归档.tgz - 覆盖spec.chart

图表

完整 API 请参见 自动生成的 API 文档。

对于复杂 Helm Chart（例如 Rancher）或升级期间的 CNI 插件，建议设置 failurePolicy: abort。默认的 reinstall 策略适用于一般应用，但对关键基础设施组件可能会造成破坏性影响。当 Helm 升级被中断且发布卡在 pending 状态时，默认策略会自动卸载并重新安装 Chart，可能导致网络中断或关键 CRD 被删除。将策略设置为 abort 可在失败后保留现场，便于人工排障并降低进一步影响。

使用 HelmChartConfig 自定义打包组件

为了允许覆盖作为 HelmCharts 部署的打包组件的值（例如 Canal、CoreDNS、Nginx-Ingress 等），RKE2 支持通过 HelmChartConfig 资源自定义部署。HelmChartConfig`资源必须与其对应的 HelmChart 的名称和名称空间匹配，并支持提供额外的 `valuesContent，该值作为附加值文件传递给 helm 命令。

HelmChart spec.set 值覆盖 HelmChart 和 HelmChartConfig spec.valuesContent 设置。

例如，要自定义打包的CoreDNS配置，您可以创建一个名为`/var/lib/rancher/rke2/server/manifests/rke2-coredns-config.yaml`的文件，并用以下内容填充它：

apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: rke2-coredns
  namespace: kube-system
spec:
  valuesContent: |-
    image:
      tag: v1.14.3-build20260506

您可以在 RKE2图表储存库中找到所有打包的Helm图表，包括它们的文档和默认值。