本文档采用自动化机器翻译技术翻译。 尽管我们力求提供准确的译文，但不对翻译内容的完整性、准确性或可靠性作出任何保证。 若出现任何内容不一致情况，请以原始 英文 版本为准，且原始英文版本为权威文本。

Helm

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

K3s不需要任何特殊配置即可支持Helm。只需确保您已根据集群访问文档正确设置kubeconfig路径。

K3s包括一个https://github.com/k3s-io/helm-controller/[Helm控制器]，它使用HelmChart自定义资源定义（CRD）管理Helm图表的安装、升级/重新配置和卸载。与自动部署的附加组件清单配合使用，在集群上安装Helm图表可以通过在磁盘上创建一个文件来实现自动化。

使用Helm控制器

HelmChart自定义资源捕获您通常会传递给`helm`命令行工具的大部分选项。

HelmChart字段定义

`name`字段应遵循Helm图表命名约定，以及Kubernetes对https://kubernetes.io/docs/concepts/overview/working-with-objects/names/[对象名称和ID]的规则。请参考https://helm.sh/docs/chart_best_practices/conventions/#chart-names[Helm最佳实践文档]以了解更多信息。
字段 默认值 说明 Helm参数/标志等效

metadata.name

Helm图表名称

名称

spec.chart

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

图表

spec.chartContent

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

图表

spec.targetNamespace

default

Helm图表目标命名空间

--namespace

spec.createNamespace

false

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

--create-namespace

spec.version

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

--version

spec.repo

Helm图表储存库URL

--repo

spec.repoCA

使用此 CA 包验证启用 HTTPS 的服务器的证书。应为包含一个或多个 PEM 编码 CA 证书的字符串。

--ca-file

spec.repoCAConfigMap

指向包含 Helm 信任的 CA 证书的 ConfigMap。可以与 repoCA 一起使用或替代

--ca-file

spec.plainHTTP

false

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

--plain-http

spec.insecureSkipTLSVerify

false

跳过图表下载的 TLS 证书检查。

--insecure-skip-tls-verify

spec.helmVersion

v3

要使用的 Helm 版本。目前仅支持 v3。

spec.bootstrap

False

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

spec.jobImage

指定安装Helm图表时使用的镜像。例如：rancher/klipper-helm:v0.3.0。

spec.podSecurityContext

Helm 作业 Pod 的自定义 v1.PodSecurityContext

spec.securityContext

Helm 作业 Pod 的容器的自定义 v1.SecurityContext

spec.backOffLimit

1000

指定在将作业视为失败之前的重试次数。

spec.timeout

300秒

Helm 操作的超时，作为 持续时间字符串（300s，10m，1h 等）

--timeout

spec.failurePolicy

重新安装

设置为 abort，此情况下 Helm 操作将被中止，等待操作员的手动干预。

spec.authSecret

引用类型为 kubernetes.io/basic-auth 的 Secret，持有图表储存库的基本身份验证凭据。

spec.authPassCredentials

false

将基本身份验证凭据传递给所有域。

--pass-credentials

spec.dockerRegistrySecret

引用类型为 kubernetes.io/dockerconfigjson 的 Secret，持有作为 Chart 储存库的 OCI 基础注册表的 Docker 身份验证凭据。

spec.set

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

--set / --set-string

spec.valuesContent

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

--values

spec.valuesSecrets

通过引用外部 Secrets 来覆盖复杂的 Chart 值。

--values

放置在 /var/lib/rancher/k3s/server/static/ 中的内容可以通过集群内的 Kubernetes APIServer 匿名访问。此 URL 可以在 spec.chart 字段中使用特殊变量 %{KUBERNETES_API}% 进行模板化。例如，打包的 Traefik 组件从 https://%{KUBERNETES_API}%/static/charts/traefik-VERSION.tgz 加载其图表。

Chart 值的使用顺序，从最低到最高优先级：

  1. Chart 默认值

  2. HelmChart spec.valuesContent

  3. 按 Secret 名称和键的列出顺序的 HelmChart spec.valuesSecrets

  4. HelmChartConfig spec.valuesContent

  5. 按 Secret 名称和键的列出顺序的 HelmChartConfig spec.valuesSecrets

  6. HelmChart spec.set

以下是如何从 Bitnami Chart 储存库部署 Apache 的示例，覆盖一些默认的 Chart 值。请注意，HelmChart 资源本身位于 kube-system 命名空间，但图表的资源将被部署到 web 命名空间，该命名空间在同一清单中创建。如果您希望将 HelmChart 资源与其部署的资源分开，这可能会很有用。

apiVersion: v1
kind: Namespace
metadata:
  name: web
---
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: apache
  namespace: kube-system
spec:
  repo: https://charts.bitnami.com/bitnami
  chart: apache
  targetNamespace: web
  valuesContent: |-
    service:
      type: ClusterIP
    ingress:
      enabled: true
      hostname: www.example.com
    metrics:
      enabled: true

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

apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  namespace: kube-system
  name: example-app
spec:
  targetNamespace: example-namespace
  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-----

来自 Secrets 的 Chart 值

Chart 值可以从外部管理的 Secrets 中读取，而不是将值存储在 spec.set 或 spec.valuesContent 字段中。在将机密信息（例如凭据）传递给不支持通过 existingSecret 模式引用现有 Secrets 的 Charts 时，应执行此操作。

与其他 Secrets (spec.authSecret 和 spec.dockerRegistrySecret) 一样，在 spec.valuesSecrets 中引用的 Secrets 必须与 HelmChart 在同一命名空间中。

每个列出的 valuesSecrets 条目具有以下字段：

字段 说明

name

Secret 的名称。必需。

密钥

要读取值的键列表，值按列出顺序使用。必需。

ignoreUpdates

将此 Secret 标记为可选，如果 Secret 更改，则不更新图表。可选，默认为 false。

  • 如果 ignoreUpdates 设置为 false 或未指定，则 Secret 和所有列出的键必须存在。对引用的值 Secret 的任何更改将导致图表更新为新值。

  • 如果 ignoreUpdates 设置为 true，则在创建图表时，如果 Secret 存在，则使用该 Secret，或者由于与相关资源的其他更改而更新。对 Secret 的更改不会导致图表更新。

使用具有两个键的现有 Secret 部署 Helm图表的示例：

apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  namespace: kube-system
  name: example-app
spec:
  targetNamespace: example-namespace
  createNamespace: true
  version: v1.2.3
  chart: example-app
  repo: https://repo.example.com
  valuesContent: |-
    image:
      tag: v1.2.2
  valuesSecrets:
    - name: example-app-custom-values
      ignoreUpdates: false
      keys:
        - someValues
        - moreValues
---
apiVersion: v1
kind: Secret
metadata:
  namespace: kube-system
  name: example-app-custom-values
stringData:
  moreValues: |-
    database:
      address: db.example.com
      username: user
      password: pass
  someValues: |-
    adminUser:
      create: true
      username: admin
      password: secret

使用 HelmChartConfig 自定义打包组件

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

HelmChartConfig 字段定义

字段 说明

metadata.name

Helm Chart 名称 - 必须与 HelmChart 资源名称匹配。

spec.valuesContent

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

spec.valuesSecrets

通过外部 Secrets 覆盖复杂的默认 Chart 值。

spec.failurePolicy

设置为 abort，此情况下 Helm 操作将被中止，等待操作员的手动干预。

HelmChart spec.set 值覆盖 HelmChart 和 HelmChartConfig spec.valuesContent 和 spec.valuesSecrets 设置，如上所述。

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

apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: traefik
  namespace: kube-system
spec:
  valuesContent: |-
    image:
      repository: docker.io/library/traefik
      tag: 3.3.5
    ports:
      web:
        forwardedHeaders:
          trustedIPs:
            - 10.0.0.0/8