Kubernetes Helm Chart 模板語法完整教學：從基本結構到進階控制流程

前言

Helm Chart 是 Kubernetes 中最主流的套件管理方式，透過模板化機制可以靈活地設定和部署應用程式。本文將完整介紹 Helm Chart 的目錄結構與模板語法，幫助你從零開始掌握 Helm Chart 的編寫技巧。

Helm Chart 基本結構

目錄說明

helm create mychart

mychart/
├── charts                   # 依賴的 Chart 目錄（子 Chart）
├── Chart.yaml               # Chart 的元資料檔案
├── templates                # 模板檔案目錄
│   ├── deployment.yaml        # Deployment 物件模板
│   ├── _helpers.tpl           # 輔助模板，定義可重用片段
│   ├── hpa.yaml               # HPA 物件模板
│   ├── ingress.yaml           # Ingress 物件模板
│   ├── NOTES.txt              # Chart 使用說明
│   ├── serviceaccount.yaml    # SA 物件模板
│   ├── service.yaml           # Service 物件模板
│   └── tests/
│       └── test-connection.yaml
└── values.yaml              # 預設配置檔

Chart.yaml 範例

apiVersion: v2
name: mychart
version: 0.1.0
description: xxx
appVersion: "1.0"

values.yaml 範例

values.yaml 定義了模板中使用的變數值，在模板中透過 {{ .Values.replicaCount }} 等方式引用：

replicaCount: 1
image:
  repository: nginx
  tag: "1.19"
  pullPolicy: IfNotPresent
service:
  type: ClusterIP
  port: 80

模板語法詳解

模板指令與註釋

{{ }} 中的內容是模板指令
轉義方法：{{` {{ 非模板資料 }} `}}
values.yaml 用 # 註釋；templates/ 下用 {{/* xxx */}} 註釋

內建物件

Release 物件：描述 Release 實例本身

Release.Name                # Release 名稱
Release.Namespace           # Release 命名空間
Release.Revision            # 修訂版本號，從 1 開始
Release.IsUpgrade           # 是否為升級或回滾
Release.IsInstall           # 是否為安裝

Values 物件：四個來源（優先順序由低到高）

子 Chart 的 values.yaml
父 Chart 的 values.yaml
-f 或 --values 指定的 YAML 檔案
--set 指定的鍵值對

Capabilities 物件：存取 Kubernetes 資訊

{{ .Capabilities.KubeVersion }}
{{ .Capabilities.APIVersions.Has "batch/v1" }}

常用模板函式

quote / squote   # 加雙引號 / 單引號
upper / lower    # 大寫 / 小寫
default "xxx"    # 預設值
indent N         # 縮排 N 個空格
nindent N        # 換行 + 縮排 N 個空格
toYaml           # 轉為 YAML 格式
b64enc / b64dec  # BASE64 編碼 / 解碼
tpl              # 渲染模板指令

管道（Pipeline）

k8s: {{ .Values.course.k8s | quote }}

控制結構

if / else 條件

{{- if eq .Values.xxx "參數" }}
xxxx
{{- else if xxxx }}
yyyy
{{- else }}
zzzz
{{- end }}

with 指定範圍

{{- with .Values.course }}
k8s: {{ .k8s | upper | quote }}
python: {{ .python | repeat 3 | quote }}
{{- end }}

range 迴圈

方式一：鍵值對迭代

# values.yaml
env:
  enable: true
  items:
    name1: value1
    name2: value2

# templates/deployment.yaml
{{- if .Values.env.enable }}
env:
{{- range $name, $value := .Values.env.items }}
- name: {{ $name }}
  value: {{ $value | quote }}
{{- end }}
{{- end }}

方式二：列表迭代

# values.yaml
env:
- name: xxx1
  value: xxx1
- name: xxx2
  value: xxx2

# templates/deployment.yaml
env:
{{- range .Values.env }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

命名模板

通常在 _helpers.tpl 中定義，以 _ 開頭的檔案不會被識別為資源清單。

define 宣告

{{/* 產生基本的 labels 標籤 */}}
{{- define "mychart.labels" }}
  labels:
    generator: helm
    date: {{ now | htmlDate }}
{{- end }}

template vs include

template：動作，無法使用管道，無縮排控制
include：函式，可搭配管道和 indent 控制縮排

{{- include "mychart.labels" . | indent 2 }}

錨點（Anchor）

# 定義錨點
anchors:
  pod_template: &pod_template
    apiVersion: v1
    kind: Pod
    metadata:
      labels:
        app: demo

# 引用錨點
apiVersion: v1
kind: Pod
metadata:
  name: demo_pod
  <<: *pod_template

總結

Helm Chart 模板語法涵蓋了內建物件、函式、管道、控制結構和命名模板等核心概念。熟練掌握這些語法後，你就能靈活地編寫和維護 Helm Chart，大幅提升 Kubernetes 應用的部署效率。建議搭配 helm template 指令進行本地渲染測試，在部署前先驗證模板輸出是否正確。

前言