Kubernetes - 实战：Helm（语法说明）

内置对象

前面提到过可以在模板中使用 {{ .Release.Name }} 获取 release 的名称，Release 是模板中可以访问的几个顶级对象之一：

Release：该对象描述了 release 本身的相关信息
Release.Name：release 名称
Release.Namespace：release 安装到的命名空间
Release.IsUpgrade：如果当前操作是升级或回滚，是为 true
Release.IsInstall：如果当前操作是否是安装，是为 true
Release.Revision：release 的 revision 版本号，在安装时为1，每次升级或回滚都会+1
Release.Service：渲染当前模板的服务，在 Helm 上，实际上该值始终为 Helm
Values：从 values.yaml 文件和用户提供的 values 文件传递到模板的 Values 值
Chart：获取 Chart.yaml 文件的内容，该文件中的任何数据都可以访问
Files：可以访问 chart 中的所有非特殊文件，虽然无法使用它来访问模板文件，但是可以来访问 chart 中的其他文件。
Files.Get：用于根据名称获取文件（比如 .Files.Get config.ini）
Files.GetBytes：用于以 bytes 数组而不是字符串的形式来获取文件内容的函数
Files.Glob：用于返回名称于给定的 shell glob 模式匹配的文件列表
Files.Lines：可以逐行读取文件的函数，对于遍历文件中的每行内容很有用
Files.AsSecrets：将文件内容以 Base64 编码的字符串返回的函数
Files.AsConfig：将文件正文作为 YAML 字典返回的函数
Capabilities：获取有关 Kubernetes 集群的信息的对象
Capabilities.APIVersions：支持的版本集合
Capabilities.APIVersions.Has $version：判断一个版本（比如 batch/v1）或资源（比如 apps/v1/Deployment）是否可用
Capabilities.Kube.Version：Kubernetes 的版本
Capabilities.Kube：是 Kubernetes 版本的缩写
Capabilities.Kube.Major：Kubernetes 主版本
Capabilities.Kube.Minor：Kubernetes 的次版本
Template：当前正在执行的模板的相关信息
Name：当前模板的命名空间文件路径（比如 mychart/templates/mytemplate.yaml）
BasePath：当前 chart 的模板目录的命名空间路径（比如 mychart/templates）

更多具体用法可以参考官方文档：

https://helm.sh/zh/docs/howto/charts_tips_and_tricks/

函数和管道

通过Values 获取到的数据不一定就是需要的，可能需要经过一定的处理之后才能正常的使用。此时就需要使用到函数。

Helm 有60多种可用的函数，其中一些是由 Go 模板语言本身定义的，其他大多数都是 Sprig 模板库提供的，一般常用的也就是 Spig 模板库的函数。

同时，模板语言有一个强大的功能就是 管道（Pipeline），它可以将一系列模板命令链接在一起，一起对外提供服务，换句话说，管道能让我们一次使用多个函数。

为了方便测试验证，创建一个新的 helm chart 包，然后清理掉没用的文件：

helm create chartdemo
echo > chartdemo/values.yaml 
rm -rf chartdemo/templates/*

创建测试数据：

# chartdemo/values.yaml
name: dylan
age: 18
sports:
  - basketball
  - volleball
  - soccerball
language:
  - name: chinese
    years: 18
  - name: english
    years: 2

创建ConfigMap：

# chartdemo/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-ConfigMap
data:
  default 函数，设置默认值
  DefaultFunc1: {{ .Values.name | default "abc" }}
  DefaultFunc2: {{ .Values.app | default "abc" }}
  upper 函数，转换成大写
  UpperFunc: {{ .Values.name | default "abc" | upper }}
  quote 函数，加引号
  QuoteFunc: {{ .Values.name | quote }}
  repeat 函数，重复数据
  RepeatFunc: {{ .Values.name | repeat 5 }}

此时可以测试安装，查看输出是否正确：

helm install --generate-name --dry-run chartdemo/

想要使用更多函数，可以查看文档：

https://masterminds.github.io/sprig/

另外需要注意的是：在模板中，运算符（eq、ne、lt、gt、and、or 等等）均实现为函数，在管道中，运算符可以用括号 () 进行分割。

流程控制

Helm 的模板语言提供了以下一些流程控制：

if/ else 条件语句
with 指定一个作用域范围
range 提供类似于 for each 这样的循环样式

除此之外，还提供了一些声明和使用命名模板的操作：

define 在模板内部声明一个新的命名模板
template 导入一个命名模板
block 声明了一种特殊的可填充模板区域

if/ else 语法模板：

{{ if PIPELINE }}
  todo
{{ else if PIPELINE }}
  todo
{{ else }}
  todo
{{ end }}

这里判断内容是管道，而不是一个 values 值。因为控制结构可以执行整个管道，而不仅仅是判断值。如果值为以下内容则为 false：

布尔 false
数字零
一个空字符串
nil（empty 或者 null）
一个空集合（map、slice、tuple、dict、array）

在其他条件下，条件都为真。

测试示例：

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-ConfigMap
data:
  {{- if eq .Values.name "dylan" }}
  name: {{ .Values.name }}
  {{- else if eq .Values.name "abc" }}
  name: "abc"
  {{- else }}
  name: "no"
  {{- end }}

为了方便阅读，每行都单独另起一行，这会导致一个问题，最终生成的数据前面后面都会有一个空行。为了解决这个问题，在每个流程控制函数前面都加了 -，这个方法可以去掉空行。

with 语法模板：

{{ with PIPELINE }}
  限制范围
{{ end }}

用于控制变量的作用域，然后重新用 . 调用就表示对当前作用域的引用。

测试示例：

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-ConfigMap
data:
  {{- with .Values }}
  {{ .name }}
  {{ .age }}
  {{- end }}

range 语法模板：

{{ range PIPELINE }}
  循环
{{ end }}

Helm 得模板语言中，迭代集合得方法是使用 range 运算符。

测试示例：

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-ConfigMap
data:
  sports: |-
  {{- range .Values.sports }}
    - {{ . | title }}
  {{- end }}

还可以直接循环给出的数据：

sizes: |-
  {{- range tuple "small" "medium" "large" }}
    - {{ . }}
  {{- end }}

变量

在模板中，变量的使用频率较低，但可以用他们来简化代码，以及更好地使用 with 和 range。

在前面使用 with 的时候，如果在内部使用 Release 或者其它外部的值得时候是会出错的。原因很简单，他不知道在 with 下面是用的作用域里面的值还是外部的值。为了解决这个问题，就需要使用变量来进行改进。

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-ConfigMap
data:
  {{- $releaseName := .Release.Name }}
  {{- with .Values }}
  releaseName: {{ $releaseName }}
  name: {{ .name }}
  {{- end }}

定义变量的方法有点类似 Golang 中的定义方法，只是需要一个 $ 符号前缀。

同样在range 循环中也可以用这个特性：

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-ConfigMap
data: |-
  数组遍历
  {{- range $index, $value := .Values.sports }}
  {{ $index }}:{{ $value }} 
  {{- end }}
  对象遍历
  {{- range $index, $data := .Values.language }}
  {{- range $k, $v := $data }}
  {{ $k }}: {{ $v }}
  {{- end }}
  {{- end }}

命令模板

之前都是操作的一个模板，有些复杂的需求可能需要操作多个模板文件。可以通过在一个文件中定义命名模板，然后在其他地方使用它们。

当使用命名模板时需要注意：

模板名称是全局的，如果声明两个相同名称的模板，则会使用最后被加载的模板。
由于子 chart 中的模板是与顶级模板一起编译的，所以需要谨慎命名。

一种流行的命名约定是在每个定义的模板前添加 chart 名称：{{ define "chartdemo.labels" }}，通过使用特定的 chart 名作为前缀，可以避免由于两个不同的 chart 实现了相同名称的模板而引起的冲突。

Helm 的模板语言允许创建命名的嵌入式模板，可以在其他位置进行访问。但是需要注意以下命名约定：

templates/ 中的大多数文件都被视为 Kubernetes 资源清单文件（NOTES.txt 除外）
以 _ 开头命名的文件也不会被当做 Kubernetes 资源清单文件
下划线开头的文件不会被当做资源清单之外，还可以被其他 chart 模板调用

_开头的这些文件其实就是 Helm 中的 partials 文件，所以我们完全可以将命名模板定义在这些 partials 文件中，默认就是 _helpers.tpl 文件。

通过define 创建命名模板：

{{ define "MY.NAME" }}
  模板内容区域
{{ end }}

示例：

# chartdemo/templates/configmap.yaml
{{ define "chartdemo.labels" }}
labels:
  app: nginx
  author: {{ .Values.name }}
{{ end }}
apiVersion: v1
kind: ConfigMap
metadata:
  name: myapp
  {{- template "chartdemo.labels" -}}
data:
  key: value

可以直接在资源清单中定义，并通过 template 调用它。

不过一般来说，Helm 中约定将这些模板统一放到一个 partials 文件中，通常就是 _helpers.tpl 文件中。

此时模板中没有使用到 values 或者预定义的数据，如果使用了，会出现获取不到值的情况。原因在于作用域的问题，想要解决这个问题也很简单，只需要在使用 template 调用的时候将其传过去即可。

{{ template "chartdemo.labels" . }}

因为后面的 . 将当期作用域传递过去，所以能在模板中使用 values 等值。

特别注意，在有些时候使用 template 的时候，如 ConfigMap 的 data 数据中。由于 template 只是一个动作，而不是一个函数，所以无法将模板调用的输出传递给其他函数，只是内联插入，所以不能继续用其它函数来对它进行格式调整，那么此时就可能出现 YAML 格式错误的问题。

为了解决这个问题，引入了 include 导入模板的方式，该方式就可以利用函数进行二次调整格式，比如：

{{ include "chartdemo.labels" . | indent 2 }}

在数据前面空两个格，实现数据 YAML 格式的合法性。通常在使用中也是推荐使用 include 而不是 template。

访问文件

有时候需要导入一个不是模板的文件并注入其内容，此时就需要用到 .Files。

Helm 提供了一个 .Files 对象对文件的访问，但在使用之前需要注意：

可以在 Helm chart 中添加额外的文件，但这些文件也会被打包，由于 Kubernetes 对象的存储限制，Charts 必须小于 1M
由于一些安全原因，通过 .Files 对象无法访问某些文件
无法访问 templates/ 下面的文件
无法访问使用 .helmignore 排除的文件
Chart 不会保留 UNIX 模式的信息，所以，当使用 .Files 对象时，文件级别的权限不会对文件的可用性产生影响。

使用示例 1：读取三个文件

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-ConfigMap
data:
  {{- $files := .Files }}
  {{- range tuple "f1.conf" "f2.conf" "f3.conf" }}
  {{ . }}: |-
    {{ $files.Get . }}
  {{- end }}

结果：

apiVersion: v1
kind: ConfigMap
metadata:
  name: mychart-1576046462-ConfigMap
data:
  f1.conf: |-
    message = 1

  f2.conf: |-
    message = 2

  f3.conf: |-
    message = 3

ConfigMap 和 Secret 类型的数据：

apiVersion: v1
kind: ConfigMap
metadata:
  name: configmap-demo
data:
{{ (.Files.Glob "foo/*").AsConfig | indent 2 }}
---
apiVersion: v1
kind: Secret
metadata:
  name: secret-demo
type: Opaque
data:
{{ (.Files.Glob "bar/*").AsSecrets | indent 2 }}

base64 编码示例：

apiVersion: v1
kind: Secret
metadata:
  name: {{ .Release.Name }}-secret
type: Opaque
data:
  token: |-
    {{ .Files.Get "f1.config" | b64enc }}

逐行读取文件示例：

data:
  some-file.txt: {{ range .Files.Lines "foo/bar.txt" }}
    {{ . }}{{ end }}

NOTES.txt

在chart 安装或者升级结束时，Helm 可以为用户打印出一些有用的信息，使用模板也可以自定义这些信息。

要将安装说明添加到 chart 中，只需要创建一个 templates/NOTES.txt 文件，该文件纯文本的，但是可以像模板一样进行处理，并具有所有常规模板的功能和可用对象。

示例：

Thank you for installing {{ .Chart.Name }}.

Your release is named {{ .Release.Name }}.

To learn more about the release, try:

  $ helm status {{ .Release.Name }}
  $ helm get {{ .Release.Name }}

用这种方式可以向用户提供一个有关如何使用其新安装的 chart 的详细信息，强烈建议创建 NOTES.txt 文件，虽然这不是必须的。

子 Chart

上面的操作都是针对于一个 Chart 进行的，某些复杂的操作可能还需要一些依赖项目，也就是子 Chart，也叫 subcharts。

了解子Chart 之前，需要了解子 chart 相关的一些信息：

子 chart 是独立的，这意味着子 chart 不能显示依赖其父 chart
所以子 chart 无法访问其父级的值
父 chart 可以覆盖子 chart 的值
Helm 中有可以被所有 charts 访问的全局值的概念

比如上面的 chartdemo 项目，可以去该项目下创建子 Chart：

cd chartdemo/charts/
helm create subchartdemo
echo > subchartdemo/values.yaml 
rm -rf subchartdemo/templates/*

此时可以在 subchartdemo 的 values.yaml 文件中添加值：

name: subchart

通过父Chart 的 values 覆盖子 Chart 中的值：

subchartdemo:
  name: overvalue

subchartdemo 中所有的值都会被传递给子 Chart subchartdemo 中进行覆盖。

同时也可以通过 global 定义全局 value，这样父子都可以拿来直接使用。

父级chart 和子 chart 也可以共享模板，任何 chart 中已定义的块都可以用于其他 chart。

Chart Hook

Helm 也提供了一种 Hook 机制，可以允许 chart 开发人员在 release 生命周期的某些时间点进行干预。比如，可以使用 hook 来进行下面的操作：

在加载任何 charts 之前，在安装的时候加载 ConfigMap 或者 Secret
在安装新的 chart 之前，执行一个 Job 来备份数据库，然后在升级后执行第二个 Job 还原数据
在删除 release 之前运行一个 Job，以在删除 release 之前适当地取消相关服务

Hooks 的工作方式类似于普通的模板，但是他们具有特殊的注解，这些注解使 Helm 可以用不同的方式来使用他们。

在Helm 中定义了如下一些可供使用的 Hooks：

预安装 pre-install：在模板渲染后，kubernetes 创建任何资源之前执行
安装后 post-install：在所有 kubernetes 资源安装到集群后执行
预删除 pre-delete：在从 kubernetes 删除任何资源之前执行删除请求
删除后 post-delete：删除所有 release 的资源后执行
升级前 pre-upgrade：在模板渲染后，但在任何资源升级之前执行
升级后 post-upgrade：在所有资源升级后执行
预回滚 pre-rollback：在模板渲染后，在任何资源回滚之前执行
回滚后 post-rollback：在修改所有资源后执行回滚请求
测试 test：在调用 Helm test 子命令的时候执行

Hooks 就是 Kubernetes 资源清单文件，在元数据部分带有一些特殊的注解，因为他们是模板文件，所以你可以使用普通模板所有的功能，包括读取 .Values、.Release 和 .Template。

apiVersion: batch/v1
kind: Job
metadata:
  name: "{{ .Release.Name }}"
  labels:
    app.kubernetes.io/managed-by: {{ .Release.Service | quote }}
    app.kubernetes.io/instance: {{ .Release.Name | quote }}
    app.kubernetes.io/version: {{ .Chart.AppVersion }}
    helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
  annotations:
    因为添加了这个 hook，所以这个资源被定义为了 hook
    如果没有这行，则当前这个 Job 会被当成 release 的一部分内容。
    "helm.sh/hook": post-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    metadata:
      name: "{{ .Release.Name }}"
      labels:
        app.kubernetes.io/managed-by: {{ .Release.Service | quote }}
        app.kubernetes.io/instance: {{ .Release.Name | quote }}
        helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
    spec:
      restartPolicy: Never
      containers:
      - name: post-install-job
        image: "busybox:latest"
        command: ["/bin/sleep","{{ default "10" .Values.sleepyTime }}"]

同时也可以属于多个 Hook：

annotations:
  "helm.sh/hook": post-install,post-upgrade

hook 权重可以是正数也可以是负数，但是必须用字符串表示，当 Helm 开始执行特定种类的 hooks 的时候，它将以升序的方式对这些 hooks 进行排序。

同时，还可以定义确定何时删除相应 hook 资源的策略，hook 删除策略可以使用下面的注解进行定义：

annotations:
  "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded

可以选择一个或多个已定义的注解：

before-hook-creation：运行一个新的 hook 之前删除前面的资源（默认）
hook-succeeded：hook 成功执行后删除资源
hook-failed：hook 如果执行失败则删除资源

18、Kubernetes - 实战：Helm（语法说明）

内置对象

函数和管道

流程控制

变量

命令模板

访问文件

NOTES.txt

子 Chart

Chart Hook