K8s Helm部署模板编写指南：快速掌握核心技巧
<p>Helm作为Kubernetes的包管理工具，通过模板化的方式简化了应用的部署流程。本文将深入探讨Helm模板的编写方法，涵盖常用语法、命令以及注意事项，帮助您快速掌握Helm模板的核心技巧。</p><h2 id="一helm模板基础">一、Helm模板基础</h2>
<p>Helm模板使用Go模板语言，结合Kubernetes YAML文件，生成最终的部署清单。一个典型的Helm模板文件结构如下：</p>
<pre><code>mychart/
├── Chart.yaml # 定义Chart的元数据（名称、版本、依赖等）
├── values.yaml # 存储默认配置值
├── templates/ # 存放所有Kubernetes资源模板文件
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── ingress.yaml
│ ├── _helpers.tpl # 定义可重用的命名模板
│ └── NOTES.txt # 安装后提示信息
├── charts/ # 存放子Chart或依赖Chart
└── .helmignore # 指定打包时忽略的文件
</code></pre>
<p><strong>核心概念</strong>：</p>
<ul>
<li><strong>Chart</strong>：一个Helm包，包含运行某个应用所需的所有Kubernetes资源定义。</li>
<li><strong>Release</strong>：在Kubernetes集群中运行的Chart的一个实例。同一个Chart可以安装多次，每次安装都会创建一个新的Release。</li>
<li><strong>Repository</strong>：用于存放和共享Chart的仓库。</li>
</ul>
<p>Helm的核心价值在于其能够将复杂的Kubernetes应用及其依赖关系打包成一个可版本化、可分享、可重复部署的单元。</p>
<h2 id="二常用模板语法详解">二、常用模板语法详解</h2>
<h3 id="1-变量与内置对象">1. 变量与内置对象</h3>
<p>Helm模板通过点（<code>.</code>）来访问上下文。常用的内置对象包括：</p>
<ul>
<li><code>.Values</code>：访问<code>values.yaml</code>文件或通过<code>--set</code>传入的值，这是模板参数化的核心。</li>
<li><code>.Release</code>：访问发布信息，如 <code>.Release.Name</code>（Release名称）、<code>.Release.Namespace</code>（命名空间）。</li>
<li><code>.Chart</code>：访问<code>Chart.yaml</code>文件中定义的元数据，如 <code>.Chart.Name</code>、<code>.Chart.Version</code>。</li>
<li><code>.Files</code>：访问Chart中的非模板文件。</li>
<li><code>.Capabilities</code>：访问Kubernetes集群的信息，如API版本。</li>
</ul>
<p>示例：</p>
<pre><code>apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ .Release.Name }}-{{ .Chart.Name }} # 生成唯一资源名
spec:
replicas: {{ .Values.replicaCount }}
template:
spec:
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
ports:
- containerPort: {{ .Values.service.port }}
</code></pre>
<h3 id="2-管道与函数">2. 管道与函数</h3>
<p>Helm提供了强大的管道（Pipeline）功能，允许将多个函数串联处理数据。它还内置了大量函数（包括Go模板函数和Sprig函数库）。</p>
<pre><code># 字符串处理：将Release名称转换为小写，并截断至63个字符
name: {{ .Release.Name | lower | trunc 63 }}
# 默认值设置：如果image.pullPolicy未定义，则使用"IfNotPresent"
imagePullPolicy: {{ .Values.image.pullPolicy | default "IfNotPresent" }}
# 缩进与YAML处理：包含命名模板并正确缩进2个空格
labels:
{{- include "mychart.labels" . | nindent 2 }}
# 类型转换：将字符串端口号转换为整数
port: {{ .Values.service.port | int }}
</code></pre>
<h3 id="3-控制流条件与循环">3. 控制流（条件与循环）</h3>
<p><strong>条件判断</strong>：使用<code>if/else</code>根据条件生成不同的配置。</p>
<pre><code>{{- if .Values.ingress.enabled }} # 注意 `-` 会去除前面的空白符
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: {{ .Release.Name }}-ingress
spec:
...
{{- end }} # 结束if语句
</code></pre>
<p><strong>循环遍历</strong>：使用<code>range</code>遍历列表或键值对。</p>
<pre><code># values.yaml中定义
env:
LOG_LEVEL: INFO
DATABASE_URL: postgresql://localhost/mydb
# templates/deployment.yaml中使用
env:
{{- range $key, $value := .Values.env }}
- name: {{ $key }}
value: {{ $value | quote }}
{{- end }}
</code></pre>
<h3 id="4-命名模板与局部模板">4. 命名模板与局部模板</h3>
<p>为了提高模板的复用性和可维护性，可以在 <code>_helpers.tpl</code>中定义命名模板。</p>
<pre><code># 在 _helpers.tpl 中定义
{{- define "mychart.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end -}}
{{- define "mychart.labels" -}}
app.kubernetes.io/name: {{ include "mychart.fullname" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end -}}
</code></pre>
<p>在模板文件中使用命名模板：</p>
<pre><code># 在 deployment.yaml 中使用
metadata:
name: {{ include "mychart.fullname" . }}
labels:
{{- include "mychart.labels" . | nindent 4 }} # 使用nindent保证缩进正确
</code></pre>
<h2 id="三helm常用命令大全实操核心">三、Helm常用命令大全（实操核心）</h2>
<p>为了方便查阅，以下将Helm常用命令按功能分类列出。</p>
<h3 id="1-仓库管理-helm-repo">1. 仓库管理 (<code>helm repo</code>)</h3>
<table>
<thead>
<tr>
<th>命令</th>
<th>说明</th>
<th>示例</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>helm repo add</code></td>
<td>添加仓库</td>
<td><code>helm repo add bitnami https://charts.bitnami.com/bitnami</code></td>
</tr>
<tr>
<td><code>helm repo list</code></td>
<td>列出已添加的仓库</td>
<td><code>helm repo list</code></td>
</tr>
<tr>
<td><code>helm repo update</code></td>
<td>更新仓库中的Chart索引</td>
<td><code>helm repo update</code></td>
</tr>
<tr>
<td><code>helm repo remove</code></td>
<td>移除仓库</td>
<td><code>helm repo remove bitnami</code></td>
</tr>
</tbody>
</table>
<h3 id="2-chart查询与检查-helm-searchshow">2. Chart查询与检查 (<code>helm search/show</code>)</h3>
<table>
<thead>
<tr>
<th>命令</th>
<th>说明</th>
<th>示例</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>helm search repo</code></td>
<td>从已添加仓库中搜索Chart</td>
<td><code>helm search repo nginx</code></td>
</tr>
<tr>
<td><code>helm search hub</code></td>
<td>从Artifact Hub中搜索Chart</td>
<td><code>helm search hub mysql</code></td>
</tr>
<tr>
<td><code>helm show chart</code></td>
<td>显示Chart的基本信息</td>
<td><code>helm show chart bitnami/nginx</code></td>
</tr>
<tr>
<td><code>helm show values</code></td>
<td><strong>显示Chart的默认可配置值（重要）</strong></td>
<td><code>helm show values bitnami/nginx > myvalues.yaml</code></td>
</tr>
<tr>
<td><code>helm show all</code></td>
<td>显示Chart的所有信息</td>
<td><code>helm show all bitnami/nginx</code></td>
</tr>
</tbody>
</table>
<h3 id="3-chart安装与管理-helm-installlistupgrade">3. Chart安装与管理 (<code>helm install/list/upgrade...</code>)</h3>
<table>
<thead>
<tr>
<th>命令</th>
<th>说明</th>
<th>示例</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>helm install</code></td>
<td>安装Chart</td>
<td><code>helm install my-release ./mychart</code></td>
</tr>
<tr>
<td><code>helm list</code></td>
<td>列出已安装的Release</td>
<td><code>helm list -n <namespace></code></td>
</tr>
<tr>
<td><code>helm upgrade</code></td>
<td>升级Release</td>
<td><code>helm upgrade my-release ./mychart -f new-values.yaml</code></td>
</tr>
<tr>
<td><code>helm history</code></td>
<td>查看Release的修订历史</td>
<td><code>helm history my-release</code></td>
</tr>
<tr>
<td><code>helm rollback</code></td>
<td>回滚Release到指定版本</td>
<td><code>helm rollback my-release 1</code></td>
</tr>
<tr>
<td><code>helm uninstall</code></td>
<td>卸载Release</td>
<td><code>helm uninstall my-release</code></td>
</tr>
</tbody>
</table>
<h3 id="4-chart开发与调试-helm-createlinttemplate">4. Chart开发与调试 (<code>helm create/lint/template...</code>)</h3>
<table>
<thead>
<tr>
<th>命令</th>
<th>说明</th>
<th>示例</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>helm create</code></td>
<td>创建新的Chart骨架</td>
<td><code>helm create mychart</code></td>
</tr>
<tr>
<td><code>helm lint</code></td>
<td>检查Chart的语法和格式是否正确</td>
<td><code>helm lint ./mychart</code></td>
</tr>
<tr>
<td><code>helm template</code></td>
<td>本地渲染模板，查看生成的K8s资源清单</td>
<td><code>helm template my-release ./mychart</code></td>
</tr>
<tr>
<td><code>helm get manifest</code></td>
<td>获取已安装Release生成的资源清单</td>
<td><code>helm get manifest my-release</code></td>
</tr>
</tbody>
</table>
<h3 id="5-chart打包与分发-helm-packagedependency">5. Chart打包与分发 (<code>helm package/dependency...</code>)</h3>
<table>
<thead>
<tr>
<th>命令</th>
<th>说明</th>
<th>示例</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>helm package</code></td>
<td>将Chart目录打包成<code>.tgz</code>压缩文件</td>
<td><code>helm package ./mychart</code></td>
</tr>
<tr>
<td><code>helm dependency update</code></td>
<td>根据<code>Chart.yaml</code>更新依赖包到<code>charts/</code>目录</td>
<td><code>helm dependency update ./mychart</code></td>
</tr>
<tr>
<td><code>helm pull</code></td>
<td>从仓库拉取（下载）Chart</td>
<td><code>helm pull bitnami/nginx --untar</code></td>
</tr>
</tbody>
</table>
<h3 id="6-调试与预安装极其重要">6. 调试与预安装（极其重要）</h3>
<p>在实际安装之前，强烈建议使用以下命令进行调试和预览：</p>
<pre><code># 1. 语法检查
helm lint ./mychart
# 2. 模拟安装并渲染模板，检查生成的YAML是否正确
# --dry-run 模拟安装，不真正创建资源
# --debug 显示渲染的详细信息
helm install my-release ./mychart --dry-run --debug
# 3. 或者使用 `helm template` 仅渲染模板
helm template my-release ./mychart
</code></pre>
<h2 id="四最佳实践与注意事项">四、最佳实践与注意事项</h2>
<ol>
<li>
<p><strong>模板命名规范</strong>：模板文件名应使用小写字母和连字符，如<code>my-awesome-chart</code>。命名模板（在<code>_helpers.tpl</code>中）使用点分隔的命名空间，如<code>mychart.labels</code>。</p>
</li>
<li>
<p><strong>缩进处理</strong>：使用<code>nindent</code>函数可以智能处理包含模板片段后的缩进问题。</p>
<pre><code># 正确示例：使用 nindent
metadata:
labels:
{{- include "mychart.labels" . | nindent 4 }} # 包含内容会被缩进4个空格
# 错误示例：缩进可能不一致
metadata:
labels:
{{- include "mychart.labels" . }}
</code></pre>
</li>
<li>
<p><strong>值文件管理</strong>： 使用<code>values.yaml</code>作为默认配置。 为不同环境（如开发、测试、生产）创建不同的values文件（<code>values-dev.yaml</code>, <code>values-prod.yaml</code>）。 使用<code>-f</code>选项指定自定义values文件来覆盖默认值：<code>helm install -f values-prod.yaml ...</code>。 使用<code>--set</code>快速覆盖单个值（适用于临时调试）：<code>helm upgrade ... --set image.tag=latest</code>。</p>
</li>
<li>
<p><strong>依赖管理</strong>：在<code>Chart.yaml</code>中声明依赖，并使用<code>helm dependency update</code>来下载依赖。</p>
<pre><code># Chart.yaml
dependencies:
- name: mysql
version: "8.5.0"
repository: "https://charts.bitnami.com/bitnami"
</code></pre>
</li>
<li>
<p><strong>安全注意事项</strong>： <strong>避免在values.yaml中直接存储敏感信息</strong>（如密码、密钥）。应使用Kubernetes Secrets管理敏感数据，在模板中通过<code>.Values.secretName</code>引用，或在安装时通过外部方式（如HashiCorp Vault）注入。 定期更新所依赖的Chart版本，以获取安全补丁和新功能。</p>
</li>
</ol>
<h2 id="五实战案例调试与故障排查">五、实战案例：调试与故障排查</h2>
<p>即使遵循了最佳实践，编写模板时也难免出错。Helm提供了有效的调试工具。</p>
<ol>
<li>
<p><strong>使用 <code>--dry-run --debug</code></strong>：这是部署前最关键的检查步骤。它可以让你看到模板渲染后的最终YAML内容，而无需真正安装到集群。</p>
<pre><code>helm install my-app ./my-chart --dry-run --debug
</code></pre>
<p>这个命令会输出所有将被创建的Kubernetes资源清单，仔细检查以确保其符合预期，如资源名称、镜像标签、环境变量等是否正确注入。</p>
</li>
<li>
<p><strong>常见错误与排查</strong>： <strong>模板渲染错误</strong>：通常是模板语法错误或引用了不存在的变量。使用<code>helm lint</code>和<code>helm template --debug</code>定位问题。 <strong>依赖冲突</strong>：使用<code>helm dependency list</code>和<code>helm dependency update</code>确保依赖一致。 <strong>资源创建失败</strong>：检查<code>helm get manifest <release-name></code>输出的YAML是否正确，并使用<code>kubectl describe</code>和<code>kubectl get events</code>查看Kubernetes的具体报错信息。</p>
</li>
</ol>
<h2 id="六总结">六、总结</h2>
<p>Helm模板通过强大的模板引擎和丰富的功能，极大地简化了Kubernetes应用的部署和管理。掌握模板语法、合理组织文件结构、遵循最佳实践，可以编写出既灵活又可维护的Helm Chart。</p>
<p>本指南从基础概念到常用命令，再到最佳实践和调试技巧，提供了较为全面的概述。建议从创建一个简单的Chart开始，逐步尝试更复杂的模板功能，结合<code>--dry-run --debug</code>命令不断验证。随着实践的深入，你会越发体会到Helm在管理复杂应用部署时的巨大价值。</p>
</div>
<div id="MySignature" role="contentinfo">
<p>本文来自博客园，作者：dashery，转载请注明原文链接：https://www.cnblogs.com/ydswin/p/19327845</p><br><br>
来源：https://www.cnblogs.com/ydswin/p/19327845
頁:
[1]