Helm使用自定义Chart模板来部署k8s应用

Helm Chart概述

Helm最核心的就是模板，即模板化的K8S manifests文件。

它本质上就是一个Go的template模板。Helm在Go template模板的基础上，还会增加很多东西。如一些自定义的元数据信息、扩展的库以及一些类似于编程形式的工作流，例如条件语句、管道等等。这些东西都会使得我们的模板变得更加丰富。

helm 项目提供了命令行工具 helm 来进行部署包的管理，并且支持接入 chart 仓库，如果你用过 linux 各大发行版的源，或者 docker 的镜像仓库，相信可以迅速 Get 到这种方案理念。目前官方的中央仓库为 artifacthub。

构建一个Helm Chart

使用helm create可以创建一个初始 chart，文件结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
# helm create mychart
Creating mychart
# tree mychart/
mychart/
├── charts
├── Chart.yaml
├── templates
│   ├── deployment.yaml
│   ├── _helpers.tpl
│   ├── ingress.yaml
│   ├── NOTES.txt
│   └── service.yaml
└── values.yaml

目录讲解：

  • Chart.yaml：用于描述这个Chart的基本信息，包括名称、版本、维护者、依赖（即子chart）等。
  • values.yaml ：用于存储Templates目录中模板文件中用到变量的值。
  • Templates： 目录里面存放所有yaml模板文件。
  • charts：目录里存放这个chart依赖的所有子chart。
  • NOTES.txt ：用于介绍Chart帮助信息，helm install部署后展示给用户。例如：如何使用这个 Chart、列出缺省的设置等。
  • _helpers.tpl：放置模板助手的地方，可以在整个chart中重复使用

创建Chart后，接下来就是将其部署：

1
2
3
4
helm install web mychart/

# 也可以打包推送的charts仓库共享别人使用。
helm package mychart/

Chart模板配置

创建一个nginx模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# rm -rf mychart/templates/*
# cat > mychart/templates/deployment.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.20
        name: nginx
EOF

实际上，这已经是一个可安装的Chart包了，通过 helm install命令来进行安装：

1
# helm install web mychart

但这样部署，其实与直接apply没什么两样。
然后使用如下命令可以看到实际的模板被渲染过后的资源文件：

1
# helm get manifest web

可以看到，这与刚开始写的内容是一样的，包括名字、镜像等，我们希望能在一个地方统一定义这些会经常变换的字段，这就需要用到Chart的模板了。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# cat > mychart/templates/deployment.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.20
        name: nginx
EOF

这个deployment就是一个Go template的模板，这里定义的Release模板对象属于Helm内置的一种对象，是从values文件中读取出来的。这样一来，我们可以将需要变化的地方都定义变量。

再执行helm install chart 可以看到现在生成的名称变成了web-deployment，证明已经生效了。也可以使用命令helm get manifest查看最终生成的文件内容。

调试

Helm也提供了--dry-run --debug调试参数，帮助你验证模板正确性。在执行helm install时候带上这两个参数就可以把对应的values值和渲染的资源清单打印出来，而不会真正的去部署一个release。

比如我们来调试上面创建的 chart 包：

1
# helm install web2 --dry-run /root/mychart

内置对象

刚刚我们使用 {{.Release.Name}}将 release 的名称插入到模板中。这里的 Release 就是 Helm 的内置对象，下面是一些常用的内置对象：

内置值详解
Release.Namerelease 名称
Release.Timerelease 的时间
Release.Namespacerelease 的 namespace（如果清单未覆盖）
Release.Servicereleaqse 服务的名称
Release.Revision此 release 的修订版本号，从1开始累加
Release.IsUpgrade如果当前操作是升级或回滚，则将其设置为 true。
Release.IsInstall如果当前操作是安装，则设置为 true。

有了模板，我们怎么把我们的配置融入进去呢？用的就是这个values文件。这两部分内容其实就是chart的核心功能。

Values

Values对象是为Chart模板提供值，这个对象的值有4个来源：

  • chart 包中的 values.yaml 文件

  • 父 chart 包的 values.yaml 文件

  • 通过 helm install 或者 helm upgrade 的 -f或者 --values参数传入的自定义的 yaml 文件

  • 通过 --set 参数传入的值

chart 的 values.yaml 提供的值可以被用户提供的 values 文件覆盖，而该文件同样可以被 --set提供的参数所覆盖。

这里我们来重新编辑 mychart/values.yaml 文件，将默认的值全部清空，然后添加一个副本数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 编辑values文件
# cat > mychart/values.yaml <<EOF 
replicas: 3
image: "nginx"
imageTag: "1.20"
EOF
# 修改deployment 文件
# cat > mychart/templates/deployment.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-deployment
spec:
  replicas: {{ .Values.replicas }}
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: {{ .Values.image }}:{{ .Values.imageTag }}
        name: nginx
EOF

查看渲染结果：

1
2
# helm install --dry-run web mychart
# helm install --set imageTag=1.24 web24 --dry-run mychart

注意：这里就会发现--set的优先级要比values文件中的要高。

values 文件也可以包含结构化内容，例如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# cat > mychart/values.yaml <<EOF
replicas: 3
image: "nginx"
imageTag: "1.20"
label:
  project: dev
  app: nginx
EOF

# cat > mychart/templates/deployment.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-deployment 
spec:
  replicas: {{ .Values.replicas }} 
  selector:
    matchLabels:
      project: {{ .Values.label.project }}
      app: {{ .Values.label.app }}
  template:
    metadata:
      labels:
        project: {{ .Values.label.project }}
        app: {{ .Values.label.app }}
    spec:
      containers:
      - image: {{ .Values.image }}:{{ .Values.imageTag }} 
        name: nginx
EOF

查看渲染结果：

1
# helm install --dry-run web mychart

管道与函数

前面讲的模块，其实就是将值传给模板引擎进行渲染，模板引擎还支持对拿到数据进行二次处理。

  1. 例如从.Values中读取的值变成字符串，可以使用quote函数实现：
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    # cat > mychart/templates/deployment.yaml <<EOF
    apiVersion: apps/v1
    kind: Deployment
    metadata:
    name: {{ .Release.Name }}-deployment 
    spec:
    replicas: {{ .Values.replicas }} 
    selector:
        matchLabels:
        project: {{ .Values.label.project }}
        app: {{ quote .Values.label.app }}
    template:
        metadata:
        labels:
            project: {{ .Values.label.project }}
            app: {{ .Values.label.app }}
        spec:
        containers:
        - image: {{ .Values.image }}:{{ .Values.imageTag }} 
            name: nginx
    EOF
    # helm install --dry-run web mychart
            project: ms
            app: "nginx"
    quote .Values.label.app 将后面的值作为参数传递给quote函数。

模板函数调用语法为：functionName arg1 arg2…

  1. 另外还会经常使用一个default函数，该函数允许在模板中指定默认值，以防止该值被忽略掉。例如忘记定义，执行helm install会因为缺少字段无法创建资源，这时就可以定义一个默认值。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    # cat > mychart/values.yaml <<EOF
    replicas: 3
    image: "nginx"
    imageTag: "1.20"
    label:
    project: dev
    app: nginx
    EOF

    # cat > mychart/templates/deployment.yaml <<EOF
    apiVersion: apps/v1
    kind: Deployment
    metadata:
    name: {{ .Release.Name }}-deployment 
    spec:
    replicas: {{ .Values.replicas }} 
    selector:
        matchLabels:
        project: {{ .Values.label.project }}
        app: {{ quote .Values.label.app }}
    template:
        metadata:
        labels:
            project: {{ .Values.label.project }}
            app: {{ .Values.label.app }}
        spec:
        containers:
        - image: {{ .Values.image }}:{{ .Values.imageTag }} 
          name: {{ .Values.name | default "def-nginx" }}
    EOF

查看渲染结果：

1
# helm install --dry-run web mychart

其他函数

  • 缩进：{{ .Values.resources | indent 12 }}
  • 大写：{{ upper .Values.resources }}
  • 首字母大写：{{ title .Values.resources }}
  • 循环：{{ .Values.resources | repeat 5 }}

比较函数

函数含义
eq如果 arg1 == arg2 返回 真
ne如果 arg1 != arg2 返回 真
lt如果 arg1 < arg2 返回 真
le如果 arg1 <= arg2 返回 真
gt如果 arg1 > arg2 返回 真
ge如果 arg1 >= arg2 返回 真

流程控制

流程控制是为模板提供了一种能力，满足更复杂的数据逻辑处理。

Helm模板语言提供以下流程控制语句：

  • if/else 条件块
  • with 指定范围
  • range 循环块

条件判断-if

if/else块是用于在模板中有条件地包含文本块的方法，条件块的基本结构如下：

1
2
3
4
5
6
7
{{ if PIPELINE }}
  # Do something
{{ else if OTHER PIPELINE }}
  # Do something else
{{ else }}
  # Default case
{{ end }}

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
# cat > mychart/values.yaml <<EOF
replicas: 3
image: "nginx"
imageTag: "1.20"
label:
  project: dev
  app: nginx
EOF

# cat > mychart/templates/deployment.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-deployment 
spec:
  replicas: {{ .Values.replicas }} 
  selector:
    matchLabels:
      {{ if eq .Values.label.project "dev" }}
      project: 1234
      {{ else }}
      project: 5678
      {{ end }}
      app: {{ .Values.label.app }}
  template:
    metadata:
      labels:
        {{ if eq .Values.label.project "dev" }}
        project: 1234
        {{ else }}
        project: 5678
        {{ end }}
        app: {{ .Values.label.app }}
    spec:
      containers:
      - image: {{ .Values.image }}:{{ .Values.imageTag }} 
        name: nginx
EOF

在上面条件语句使用了eq运算符判断是否相等，除此之外，还支持ne、 lt、 gt、 and、 or等运算符。
通过模板引擎来渲染一下，会得到如下结果：

1
2
3
4
5
6
7
# helm install --dry-run web mychart
...
      labels:
        
        project: 1234
        
        app: nginx

可以看到渲染出来会有多余的空行，这是因为当模板引擎运行时，会将控制指令删除，所有之前占的位置也就空白了，需要使用{{- if …}}… {{- else }} 的方式消除此空行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
cat > mychart/templates/deployment.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-deployment 
spec:
  replicas: {{ .Values.replicas }} 
  selector:
    matchLabels:
      {{- if eq .Values.label.project "dev" }}
      project: 1234
      {{- else }}
      project: 5678
      {{ end }}
      app: {{ .Values.label.app }}
  template:
    metadata:
      labels:
        {{ if eq .Values.label.project "dev" }}
        project: 1234
        {{ else }}
        project: 5678
        {{ end }}
        app: {{ .Values.label.app }}
    spec:
      containers:
      - image: {{ .Values.image }}:{{ .Values.imageTag }} 
        name: nginx
EOF

注意：如果{{ if eq .Values.label.project “dev” -}}那就表示删除了双方的换行符。

查看效果，现在是不是没有多余的空格了。

1
2
3
4
5
# helm install --dry-run web mychart
...
      labels:
        project: 1234
        app: nginx

条件判断就是判断条件是否为真，如果值为以下几种情况则为false：

  • 一个布尔类型的 假

  • 一个数字 零

  • 一个 空的字符串

  • 一个 nil（空或 null）

  • 一个空的集合（ map、 slice、 tuple、 dict、 array）

除了上面的这些情况外，其他所有条件都为 真。

例如，判断一个空的数组

1
2
3
4
5
6
7
8
# cat values.yaml 
resources: {}
  # limits:
  #   cpu: 100m
  #   memory: 128Mi
  # requests:
  #   cpu: 100m
  #   memory: 128Mi
1
2
3
4
5
6
7
8
9
10
# cat templates/deploymemt.yaml
...
    spec:
      containers:
      - image: nginx:1.21
        name: nginx
        {{- if .Values.resources }}
        resources:
{{ toYaml .Values.resources | indent 10 }}
        {{- end }}

例如，判断一个布尔值

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# cat >> mychart/values.yaml <<EOF
service:
  type: ClusterIP
  port: 80

ingress:
  enabled: true 
  host: example.boysec.cn
EOF

# cat > mychart/templates/ingress.yaml  <<EOF 
{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ .Release.Name }}-ingress
spec:
  rules:
  - host: {{ .Values.ingress.host }}
    http:
      paths:
      - path: /
        backend:
          serviceName: {{ .Release.Name }}
          servicePort: {{ .Values.service.port }}
{{ end }}
 EOF

控制变量作用域-with

with ：控制变量作用域。

还记得之前我们的 {{.Release.xxx}}或者 {{.Values.xxx}}吗？其中的 .就是表示对当前范围的引用， .Values就是告诉模板在当前范围中查找 Values对象的值。而 with语句就可以来控制变量的作用域范围，其语法和一个简单的 if语句比较类似：

1
2
3
{{ with PIPELINE }}
  #  restricted scope
{{ end }}

with语句可以允许将当前范围 .设置为特定的对象，比如我们前面一直使用的 .Values.label，我们可以使用 with来将 .范围指向 .Values.label：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# cat mychart/values.yaml 
...
replicas: 3
label:
  project: ms
  app: nginx

# cat > mychart/templates/deployment.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      {{- with .Values.nodeSelector }}
      nodeSelector:
        team: {{ .team }}
        gpu: {{ .gpu }}
      {{- end }}
      containers:
      - image: nginx:1.16
        name: nginx
EOF

优化后：

1
2
3
4
5

{{- with .Values.nodeSelector }}
nodeSelector:
  {{- toYaml . | nindent 8 }}
{{- end }}

上面增加了一个 xxx的一个块，这样的话就可以在当前的块里面直接引用 .team和 .gpu了。

with是一个循环构造。使用**.Values.nodeSelector中**的值：将其转换为Yaml。

toYaml之后的点是循环中**.Values.nodeSelector**的当前值

数组-range

在 Helm 模板语言中，使用 range关键字来进行循环操作。

我们在 values.yaml文件中添加上一个变量列表：

1
2
3
4
5
# cat values.yaml 
test:
  - 1
  - 2
  - 3

循环打印该列表：

1
2
3
4
5
6
7
8
9
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}
data:
  test: |
  {{- range .Values.test }}
    {{ . }}
  {{- end }}

循环内部我们使用的是一个 .，这是因为当前的作用域就在当前循环内，这个 .引用的当前读取的元素。

变量

接下来学习一个语言中基本的概念：变量，在模板中，使用变量的场合不多，但我们将看到如何使用它来简化代码，并更好地利用with和range。

问题1：获取列表键值

1
2
3
4
5
6
7
8
9
10
11
12
# cat ../values.yaml
env:
  NAME: "gateway"
  JAVA_OPTS: "-Xmx1G"
  
# cat deployment.yaml 
...
		env:
		{{- range $k, $v := .Values.env }}
           - name: {{ $k }}
             value: {{ $v | quote }}
        {{- end }}

结果如下：

    env:
       - name: JAVA_OPTS
         value: "-Xmx1G"
       - name: NAME
         value: "gateway"

上面在 range循环中使用 $key和 $value两个变量来接收后面列表循环的键和值。

问题2：with中不能使用内置对象

with语句块内不能再 .Release.Name对象，否则报错。

我们可以将该对象赋值给一个变量可以来解决这个问题：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-deployment
spec:
  replicas: {{ .Values.replicas }}
  template:
    metadata:
      labels:
        project: {{ .Values.label.project }}
        app: {{ quote .Values.label.app }}
      {{- with .Values.label }}
        project: {{ .project }}
        app: {{ .app }}
        release: {{ .Release.Name }}
      {{- end }}

上面会出错。

1
2
3
4
5
6
7
8
{{- $releaseName := .Release.Name -}}
{{- with .Values.label }}
  project: {{ .project }}
  app: {{ .app }}
  release: {{ $releaseName }}
  # 或者可以使用$符号,引入全局命名空间
  release: {{ $.Release.Name }}
{{- end }}

可以看到在 with语句上面增加了一句 {{-$releaseName:=.Release.Name-}}，其中 $releaseName就是后面的对象的一个引用变量，它的形式就是 $name，赋值操作使用 :=，这样 with语句块内部的 $releaseName变量仍然指向的是 .Release.Name

命名模板

命名模板：使用define定义，template引入，在templates目录中默认下划线_开头的文件为公共模板(_helpers.tpl)

1
2
3
4
5
6
7
8
9
10
11
# cat _helpers.tpl
{{- define "demo.fullname" -}}
{{- .Chart.Name -}}-{{ .Release.Name }}
{{- end -}}

# cat deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ template "demo.fullname" . }}
...

template指令是将一个模板包含在另一个模板中的方法。但是，template函数不能用于Go模板管道。为了解决该问题，增加include功能。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# cat _helpers.tpl
{{- define "demo.labels" -}}
app: {{ template "demo.fullname" . }}
chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
release: "{{ .Release.Name }}"
{{- end -}}

# cat deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "demo.fullname" . }}
  labels:
    {{- include "demo.labels" . | nindent 4 }}
...

上面包含一个名为 demo.labels 的模板，然后将值 . 传递给模板，最后将该模板的输出传递给 nindent 函数。

Helm Chart升级、回滚和删除

发布新版本的chart时，或者当您要更改发布的配置时，可以使用该helm upgrade 命令。

1
2
# helm upgrade --set imageTag=1.20 web mychart
# helm upgrade -f values.yaml web mychart

如果在发布后没有达到预期的效果，则可以使用helm rollback 回滚到之前的版本。

例如将应用回滚到第一个版本：

1
# helm rollback web 2

卸载发行版，请使用以下helm delete命令：

1
2
# helm delete web
# helm uninstall web

查看历史版本配置信息

1
# helm get --revision 1 web