模板

最佳实践指南的这一部分重点介绍模板。

`templates/` 的结构

templates/ 目录应按以下结构组织

如果模板文件生成 YAML 输出，则应使用扩展名 .yaml。扩展名 .tpl 可用于生成无格式内容的模板文件。
模板文件名应使用破折号表示法 (my-example-configmap.yaml)，而不是驼峰式命名法。
每个资源定义应放在其自己的模板文件中。
模板文件名应在名称中反映资源类型。例如 foo-pod.yaml、bar-svc.yaml

定义的模板名称

定义的模板（在 {{ define }} 指令内创建的模板）是全局可访问的。这意味着图表及其所有子图表都可以访问使用 {{ define }} 创建的所有模板。

因此，所有定义的模板名称都应使用命名空间。

正确

{{- define "nginx.fullname" }}
{{/* ... */}}
{{ end -}}

错误

{{- define "fullname" -}}
{{/* ... */}}
{{ end -}}

强烈建议通过 helm create 命令创建新图表，因为模板名称将根据此最佳实践自动定义。

格式化模板

模板应使用两个空格缩进（永远不要使用制表符）。

模板指令在左花括号后和右花括号前应留有空格

正确

{{ .foo }}
{{ print "foo" }}
{{- print "bar" -}}

错误

{{.foo}}
{{print "foo"}}
{{-print "bar"-}}

模板应尽可能地去除空白

foo:
  {{- range .Values.items }}
  {{ . }}
  {{ end -}}

块（如控制结构）可以缩进以指示模板代码的流程。

{{ if $foo -}}
  {{- with .Bar }}Hello{{ end -}}
{{- end -}}

但是，由于 YAML 是一种以空白为导向的语言，因此代码缩进通常无法遵循该约定。

生成的模板中的空白

最好将生成的模板中的空白量保持在最低限度。特别是，不应该出现多个空行彼此相邻。但偶尔出现空行（特别是在逻辑部分之间）是可以的。

这是最好的

apiVersion: batch/v1
kind: Job
metadata:
  name: example
  labels:
    first: first
    second: second

这是可以的

apiVersion: batch/v1
kind: Job

metadata:
  name: example

  labels:
    first: first
    second: second

但应避免这种情况

apiVersion: batch/v1
kind: Job

metadata:
  name: example





  labels:
    first: first

    second: second

注释（YAML 注释与模板注释）

YAML 和 Helm 模板都有注释标记。

YAML 注释

# This is a comment
type: sprocket

模板注释

{{- /*
This is a comment.
*/}}
type: frobnitz

在记录模板的功能（例如解释定义的模板）时，应使用模板注释

{{- /*
mychart.shortname provides a 6 char truncated version of the release name.
*/}}
{{ define "mychart.shortname" -}}
{{ .Release.Name | trunc 6 }}
{{- end -}}

在模板内部，YAML 注释可用于在调试期间 Helm 用户需要（可能）看到注释时使用。

# This may cause problems if the value is more than 100Gi
memory: {{ .Values.maxMem | quote }}

上面的注释在用户运行 helm install --debug 时可见，而 {{- /* */}} 部分中指定的注释则不可见。

注意：在包含 Helm 值的模板部分添加 # YAML 注释，这些值可能被某些模板函数需要。

例如，如果在上面的示例中引入了 required 函数，而 maxMem 未设置，则 # YAML 注释将引入渲染错误。

正确：helm template 不会渲染此块

{{- /*
# This may cause problems if the value is more than 100Gi
memory: {{ required "maxMem must be set" .Values.maxMem | quote }}
*/ -}}

错误：helm template 返回 Error: execution error at (templates/test.yaml:2:13): maxMem must be set

# This may cause problems if the value is more than 100Gi
# memory: {{ required .Values.maxMem "maxMem must be set" | quote }}

查看调试模板以获取有关 YAML 注释如何保持原样的另一种示例。

在模板和模板输出中使用 JSON

YAML 是 JSON 的超集。在某些情况下，使用 JSON 语法可能比其他 YAML 表示更具可读性。

例如，此 YAML 更接近表达列表的正常 YAML 方法

arguments:
  - "--dirname"
  - "/foo"

但当折叠成 JSON 列表样式时，它更容易阅读

arguments: ["--dirname", "/foo"]

使用 JSON 以提高可读性是好的。但是，JSON 语法不应用于表示更复杂的结构。

当处理嵌入在 YAML 中的纯 JSON（如 init 容器配置）时，当然可以使用 JSON 格式。

模板

templates/ 的结构