Documentation survey

Helm

HelmはKubernetesのためのパッケージ管理ツールです。HelmチャートはKubernetes YAMLマニフェストドキュメントのためのテンプレート構文を提供します。Helmを使用すると、開発者やクラスター管理者は静的なマニフェストを使用する代わりに、チャートとして知られる設定可能なテンプレートを作成できます。独自のチャートカタログを作成する方法については、https://helm.sh/docs/intro/quickstart/のドキュメントを参照してください。

K3sはHelmをサポートするために特別な設定を必要としません。クラスターアクセスのドキュメントに従って、kubeconfigパスを正しく設定していることを確認してください。

K3sには、HelmChartカスタムリソース定義（CRD）を使用してHelmチャートのインストール、アップグレード/再構成、およびアンインストールを管理するHelmコントローラーが含まれています。自動デプロイAddOnマニフェストと組み合わせることで、ディスク上に1つのファイルを作成するだけでクラスターにHelmチャートを自動的にインストールできます。

Helmコントローラーの使用

HelmChartカスタムリソースは、通常helmコマンドラインツールに渡すほとんどのオプションをキャプチャします。

HelmChartフィールド定義

nameフィールドはHelmチャートの命名規則に従う必要があります, in addition to Kubernetes rules for object names and IDs。詳細については、https://helm.sh/docs/chart_best_practices/conventions/#chart-names[Helmベストプラクティスドキュメント]を参照してください。
フィールド デフォルト 説明 Helm引数/フラグの同等

metadata.name

Helmチャート名

NAME

spec.chart

リポジトリ内のHelmチャート名、またはチャートアーカイブ（.tgz）への完全なHTTPS URL

CHART

spec.chartContent

Base64エンコードされたチャートアーカイブ.tgz - spec.chartを上書き

CHART

spec.targetNamespace

default

Helmチャートのターゲットネームスペース

--namespace

spec.createNamespace

false

ターゲットネームスペースが存在しない場合に作成

--create-namespace

spec.version

リポジトリからインストールする場合のHelmチャートバージョン

--version

spec.repo

HelmチャートリポジトリURL

--repo

spec.repoCA

HTTPS対応サーバーの証明書をこのCAバンドルを使用して検証します。1つ以上のPEMエンコードされたCA証明書を含む文字列である必要があります。

--ca-file

spec.repoCAConfigMap

Helmが信頼するCA証明書を含むConfigMapへの参照。repoCAと一緒に、または代わりに使用できます。

--ca-file

spec.plainHTTP

false

Use insecure HTTP connections for the chart download.

--plain-http

spec.insecureSkipTLSVerify

false

Skip TLS certificate checks for the chart download.

--insecure-skip-tls-verify

spec.helmVersion

v3

Helm version to use. Only v3 is currently supported.

spec.bootstrap

False

このチャートがクラスターをブートストラップするために必要な場合（クラウドコントローラーマネージャーなど）にTrueに設定

spec.jobImage

Helmチャートをインストールする際に使用するイメージを指定します。例：rancher/klipper-helm:v0.3.0。

spec.podSecurityContext

Custom v1.PodSecurityContext for the Helm job pod

spec.securityContext

Custom v1.SecurityContext for the Helm job pod’s containers

spec.backOffLimit

1000

ジョブが失敗と見なされる前に再試行する回数を指定します。

spec.timeout

300s

Helm操作のタイムアウト、https://pkg.go.dev/time#ParseDuration[duration string]（300s、10m、1hなど）として指定

--timeout

spec.failurePolicy

reinstall

Helm操作が中止され、オペレーターによる手動介入が必要な場合にabortに設定

spec.authSecret

チャートリポジトリの基本認証資格情報を保持するkubernetes.io/basic-authタイプのSecretへの参照。

spec.authPassCredentials

false

すべてのドメインに基本認証資格情報を渡します。

--pass-credentials

spec.dockerRegistrySecret

チャートリポジトリとして機能するOCIベースのレジストリのDocker認証資格情報を保持するkubernetes.io/dockerconfigjsonタイプのSecretへの参照。

spec.set

シンプルなデフォルトチャート値を上書きします。これらはvaluesContent経由で設定されたオプションよりも優先されます。

--set / --set-string

spec.valuesContent

YAMLファイルの内容を介して複雑なデフォルトチャート値を上書き

--values

spec.valuesSecrets

Override complex Chart values via references to external Secrets

--values

/var/lib/rancher/k3s/server/static/に配置されたコンテンツは、クラスター内からKubernetes APIServerを介して匿名でアクセスできます。このURLは、spec.chartフィールドで特別な変数%{KUBERNETES_API}%を使用してテンプレート化できます。例えば、パッケージ化されたTraefikコンポーネントは、https://%{KUBERNETES_API}%/static/charts/traefik-VERSION.tgzからチャートをロードします。

Chart values are used in the following order, from least to greatest precedence:

  1. Chart default values

  2. HelmChart spec.valuesContent

  3. HelmChart spec.valuesSecrets in listed order of secret name and keys

  4. HelmChartConfig spec.valuesContent

  5. HelmChartConfig spec.valuesSecrets in listed order of secret name and keys

  6. HelmChart spec.set

以下は、BitnamiチャートリポジトリからApacheをデプロイし、いくつかのデフォルトチャート値を上書きする例です。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-----

Chart Values from Secrets

Chart values can be read from externally-managed Secrets, instead of storing the values in the spec.set or spec.valuesContent fields. This should be done when passing confidential information such as credentials in to Charts that do not support referring to existing Secrets via the existingSecret pattern.

As with other Secrets (spec.authSecret and spec.dockerRegistrySecret), Secrets referenced in spec.valuesSecrets must be in the same namespace as the HelmChart.

Each listed valuesSecrets entry has the following fields:

Field Description

name

The name of the Secret. Required.

keys

List of keys to read values from, values are used in the listed order. Required.

ignoreUpdates

Mark this Secret as optional, and do not update the chart if the Secret changes. Optional, defaults to false.

  • If ignoreUpdates is set to false or unspecified, the Secret and all listed keys must exist. Any change to a referenced values Secret will cause the chart to be updated with new values.

  • If ignoreUpdates is set to true, the Secret is used if it exists when the Chart is created, or updated due to any other change to related resources. Changes to the Secret will not cause the chart to be updated.

An example of deploying a helm chart using an existing Secret with two keys:

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 Field Definitions

Field Description

metadata.name

Helm Chart name - must match the HelmChart resource name.

spec.valuesContent

Override complex default Chart values via YAML file content.

spec.valuesSecrets

Override complect default Chart values via external Secrets.

spec.failurePolicy

Set to abort which case the Helm operation is aborted, pending manual intervention by the operator.

HelmChartのspec.set値は、HelmChartおよびHelmChartConfigのspec.valuesContentand spec.valuesSecrets settings, as described above。

例えば、パッケージ化されたTraefikのインバウンド設定をカスタマイズするには、/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