制作 Helm Chart todo
文件结构
参考官方文档 Charts - Helm Docs.
官方文档中对于文件结构的介绍
wordpress/
Chart.yaml # A YAML file containing information about the chart
LICENSE # OPTIONAL: A plain text file containing the license for the chart
README.md # OPTIONAL: A human-readable README file
values.yaml # The default configuration values for this chart
values.schema.json # OPTIONAL: A JSON Schema for imposing a structure on the values.yaml file
charts/ # A directory containing any charts upon which this chart depends.
crds/ # Custom Resource Definitions
templates/ # A directory of templates that, when combined with values,
# will generate valid Kubernetes manifest files.
templates/NOTES.txt # OPTIONAL: A plain text file containing short usage notescharts/包含子图表 (所依赖的本地 Chart), 详见下文 依赖管理.templates/包含 Kubernetes YAML 模板文件.values.yaml包含默认的配置值, 这些值将被模板使用.Chart.yaml包含 Chart 的元数据 (例如版本, 描述, 依赖等).
# Chart.yaml
apiVersion: v2
name: my-chart
description: A Helm chart for my application
version: 1.0.0# values.yaml
replicaCount: 1
image:
repository: my-app
tag: latest# 在模板中引用 values.yaml 中的值
replicaCount: {{ .Values.replicaCount }}
image:
repository: {{ .Values.image.repository }}
tag: {{ .Values.image.tag }}常用命令
# 新建 chart
helm create [chart]
# 检查当前 chart, 获取修改建议
helm lint [chart]
# 显示某个 chart 的信息
helm show [sub-command] [chart]
# 例如查看 chart 的默认 values
helm show values [chart]
# 提供 name 作为 release 的名称, 并以此渲染出结果
helm template [name] [chart]依赖管理
主 Chart 根目录的 Chart.yaml 文件中的 dependencies 字段用于声明对 Chart 的依赖关系.
这种依赖关系可以确保在部署主 Chart 之前, 所有依赖的 Chart 已被安装.
# Chart.yaml
dependencies:
- name: mysql
version: 5.7.14
repository: https://charts.bitnami.com/bitnami
- name: redis
version: 10.0.1
repository: https://charts.bitnami.com/bitnami通过使用 dependencies 字段, 我们可以将 Helm Chart 拆分为更小更易管理的部分.
这使得复用和分发 Helm Charts 变得更加方便, 维护成本更低.
相关命令:
helm dep build [path] # 将 Chart.yaml 中声明的依赖下载至 ./charts 路径下
helm dep update [path] # 更新 Chart.lock 文件, 其中记录了确切的依赖版本
helm dep list [path] # 列出所依赖 Chart说明文档
提供清晰和详细的文档, 解释 Chart 的用途, 配置选项和如何使用.
可以使用 README.md 文件或者使用 Helm 提供的 NOTES.txt 来添加提示信息.
NOTES.txt 文件是 Helm Chart 中的一种特殊文件, 用于提供与安装的 Chart 相关的提示和说明.
当用户使用 Helm 安装 Chart 时, NOTES.txt 文件的内容将被打印到命令行终端.
一般来说可以包含: 配置说明, 后续步骤, 故障排除信息.
版本控制
是否建议将 helm chart 单独作为 git 工程? (ChatGPT)
是的，将 Helm Chart 单独作为一个独立的 Git 仓库是一种良好的实践。这种做法带来了一些好处：
可重用性： 将 Helm Chart 独立存储在一个 Git 仓库中使得它可以轻松地被其他项目所重用。其他项目只需要引用该 Git 仓库，就可以方便地使用和部署这个 Helm Chart。
版本控制： Helm Charts 随时间可能会有多个版本，通过将其放在独立的 Git 仓库中，你可以更方便地进行版本控制。这有助于跟踪 Chart 的演变和变更历史。
可分发性： 将 Helm Chart 存储在独立的 Git 仓库中，使得它可以轻松地被分发和分享给其他团队成员、项目或者社区。其他人只需克隆仓库或者在 Helm 安装时引用仓库的 URL。
持续集成和持续部署（CI/CD）： 独立的 Git 仓库为 Helm Chart 的 CI/CD 流程提供了更好的支持。你可以在仓库中配置 CI/CD 流程，以确保 Chart 在不同环境中的自动构建、测试和部署。
文档和说明： 独立的 Git 仓库允许你在仓库中添加文档、说明和示例，以帮助其他开发人员更好地理解和使用 Helm Chart。
考虑到这些好处，将 Helm Chart 作为独立的 Git 仓库通常是一种推荐的做法。这使得 Helm Chart 更易于管理、维护和分享。
.gitignore 模板
# Ignore system and editor files
*.iml
*.swp
*~
# Ignore macOS specific files
.DS_Store
.AppleDouble
.LSOverride
# Ignore Windows specific files
Thumbs.db
ehthumbs.db
# Ignore Helm plugin specific files
helm-plugin-cache/
# Ignore Helm-specific files and directories
charts/
*.tgz
*.prov
*.orig
*.bak
*.tmpWARNING
应谨慎处理敏感信息, 如密码和密钥. 不要硬编码这些敏感信息.
而应提供安全的配置选项, 并使用 k8s 的 Secret 对象来存储.
测试框架 todo
helm test
模板语法 todo
Schema todo
Subchart
路径结构
main-chart
├─ values.yaml
├─ templates
│ ├─ _helpers.tpl
│ ├─ service.yaml
│ ├─ NOTES.txt
│ └─ deployment.yaml
├─ charts
│ └─ my-subchart
│ ├─ templates
│ │ ├─ _helpers.tpl
│ │ ├─ deployment.yaml
│ │ └─ configmap.yaml
│ ├─ charts
│ └─ Chart.yaml
├─ Chart.yaml
└─ Chart.lockValue Context
values 处于不同的 context 中.
例如在主 Chart 的 values.yaml 中做了如下定义:
# ./values.yaml
my-subchart:
property: ""那么在 subchart 中应该这么使用:
# ./charts/my-subchart/templates/deployment.yaml
property: {{ .Values.property }}
property: {{ .Values.my-subchart.property }} 若希望让主 chart 和 subchart 能以相同的路径访问 values, 可以使用 global values.
注意事项
- subchart 中不要包含 NOTES.txt (因为不会被打印出来).
- .tpl 文件与主 Chart 共享, 相互都可以用对方的 .tpl 文件.
- subchart 会在主 Chart 被
helm package .的时候一同被打包. helm install的时候, subchart 不会显示为单独的 release.- 需要在主 Chart 的 Chart.yaml 声明 dependencies:
# Chart.yaml
dependencies:
# Subchart 应该在主 Chart 中被列出
- name: my-subchart
# 版本范围必须写明
version: ">= 0.1.0"
# **不应该** 设置 repository 字段
# repository:最佳实践
参考 6 Tips to Writing a Great Helm Chart - Sven Hans Knecht.
Don't Change Well-Known API Spec
Generate the schema.json
Generate Documentation
Set Sane Default Values
Allow for API Version Overrides
Write Unit Tests
Write Good Release Notes
Always allow for standard customizations
Helm Docs
helm-docs 用于根据注释自动生成文档.
准确地讲, 是将写在 values.yaml 的注释, 转换成 markdown 文件.
为了确保所有项目参与者都能执行 helm-docs 的命令, 不建议本地安装其命令行工具.
建议借助 docker 来执行. 例如先创建如下的 compose.yaml 文件:
# compose.yaml
services:
helm-docs:
image: jnorwood/helm-docs
volumes:
- .:/helm-docs/:ro
- ./README.md:/helm-docs/README.md之后就可以通过此命令生成文档:
docker compose run --rm helm-docs应想办法确保文档始终与源文件同步.
为此可以通过 在 CI/CD 中创建 Commit.
Chart 笔记
空白字符裁剪
Helm 通过 "与两个大括号链接的短横线" 裁剪 空白字符.
这里所说的 空白字符 包括: 空格 换行符 Tab.
{{- # 裁剪左侧的空白字符.
-}} # 裁剪右侧的空白字符例如在使用 toYaml 函数时, 就经常需要处理左侧空格:
# 这一行文本左侧可以是任意缩进.
# 只要模板被渲染成最终的 yaml 文件,
# 左侧的缩进总会是 4 个空格.
{{- include "my-chart.labels" . | nindent 4 }}必须赋值的字段
可以在条件判断中使用 fail:
{{- if xxx -}}
{{- fail "xxx" -}}
{{- end -}}也可以使用 required 函数, 在缺失必要的值时报错:
value: {{ required "A valid .Values.who entry required!" .Values.who }}是否使用双引号
YAML 的隐式类型转换有些时候比较反直觉, 例如 foo: false 与 foo: "false" 不同,
比较大的整数例如 foo: 12345678 在某些情况下, 可能会被科学计数法表示.
因此在实践中的建议是:
- 字符串类型都使用双引号包裹.
- 比较小的数字 (例如网络端口), 不使用 双引号.
- 针对数字也可以使用字符串赋值, 之后通过 helm 的某个函数来转换成数字.
# 对于字符串类型的字段, 赋值时应尽量使用双引号
name: {{ .Values.myName | quote }}
# 对于类似于网络端口这种字段, **不要** 使用双引号
port: {{ .Values.port }}
# values.yaml 中使用字符串类型, 在模板中使用时转换为整数
number: {{ int .Values.number }}CRD 的注意事项
Helm 对 CRD (Custom Resource Definition) 是支持的, 但有一些需要注意的地方.
- Helm 可以安装 CRD, 但 不能 将其更新或删除.
- 在 Helm Chart 中编写 CRD 时 不支持 模板语法 (写在
crds/路径下). - 无法使用
--dry-run选项 (但可以考虑用helm template命令作为替代).