helm-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Helm Chart Style Guide

Helm Chart 风格指南

This skill provides standardized conventions for authoring and maintaining Helm charts, with a focus on:

Global registry override using
```
.Values.global.image.registry
```
Clear, minimal templating
Consistent
```
image:
```
blocks for all containers

本技能为Helm Chart的编写与维护提供标准化规范，重点包括：

使用
```
.Values.global.image.registry
```
实现全局镜像仓库覆盖
清晰、简洁的模板编写
为所有容器保持一致的
```
image:
```
块格式

When to Use

适用场景

Activate this skill when:

Creating new Helm charts
Reviewing or modifying existing Helm charts
Configuring image registries for air-gapped environments
Setting up multi-chart deployments with Helmfile

在以下场景激活本技能：

新建Helm Chart时
评审或修改现有Helm Chart时
为离线环境配置镜像仓库时
使用Helmfile搭建多Chart部署时

Image Configuration Best Practices

镜像配置最佳实践

All charts must support the top-level configuration for global image settings.

yaml

global:
  image:
    registry: registry.mycompany.com

This enables centralized control of image sources across all dependencies and microservices.

所有Chart必须支持全局镜像设置的顶层配置。

yaml

global:
  image:
    registry: registry.mycompany.com

这能实现对所有依赖项和微服务的镜像源集中管控。

Consistent Image Blocks

一致的镜像块格式

All charts should follow a consistent

image:

block for every containerized application.

Fields should be templated for

registry

repository

tag

pullPolicy

, and

pullSecrets

for all containers.

Every chart must define all image values with reasonable defaults in

values.yaml

yaml

prometheus:
  image:
    registry: docker.io
    repository: prom/prometheus
    tag: v2.52.0
    pullPolicy: IfNotPresent

所有Chart应为每个容器化应用遵循一致的

image:

块格式。

所有容器的

registry

、

repository

、

tag

、

pullPolicy

和

pullSecrets

字段都应使用模板渲染。

每个Chart必须在

values.yaml

中为所有镜像字段定义合理的默认值：

yaml

prometheus:
  image:
    registry: docker.io
    repository: prom/prometheus
    tag: v2.52.0
    pullPolicy: IfNotPresent

Templating Pattern for Registry Override

镜像仓库覆盖的模板模式

Use a registry value at the top of the template. This pattern ensures ability to use internal registries (e.g.,

registry.mycompany.com

) for air-gapped environments or mirrored image sources:

gotmpl

{{- $registry := .Values.prometheus.image.registry | default .Values.global.image.registry | default "docker.io" -}}
image:
  registry: {{ $registry }}
  repository: {{ .Values.prometheus.image.repository }}
  tag: {{ .Values.prometheus.image.tag }}
  pullPolicy: {{ .Values.prometheus.image.pullPolicy }}

在模板顶部定义仓库变量。该模式确保能够为离线环境或镜像源使用内部仓库（例如

registry.mycompany.com

）：

gotmpl

{{- $registry := .Values.prometheus.image.registry | default .Values.global.image.registry | default "docker.io" -}}
image:
  registry: {{ $registry }}
  repository: {{ .Values.prometheus.image.repository }}
  tag: {{ .Values.prometheus.image.tag }}
  pullPolicy: {{ .Values.prometheus.image.pullPolicy }}

Templating Conventions

模板编写规范

Template only when necessary. Keep templates readable and manageable by avoiding over-templating.

Template:

Labels
Annotations
Resource requests and limits for CPU and memory for each container
Service port numbers and names

Avoid Templating:

Most values already present in
```
values.yaml
```
unless dynamically constructed

仅在必要时使用模板。避免过度模板化，保持模板的可读性和可维护性。

需要模板化的内容：

标签
注解
每个容器的CPU和内存资源请求与限制
服务端口号与名称

应避免模板化的内容：

```
values.yaml
```
中已存在的大部分值，除非需要动态构建

Linting & Validation

代码检查与验证

Run
```
helm lint
```
before commits
Use
```
helm template
```
for rendering checks
Ensure
```
values.yaml
```
and
```
Chart.yaml
```
are fully in sync with templated expectations

提交代码前运行
```
helm lint
```
使用
```
helm template
```
进行渲染检查
确保
```
values.yaml
```
和
```
Chart.yaml
```
与模板预期完全同步

Automated Chart Testing with ct

使用ct实现Chart自动化测试

Use the chart-testing tool (

ct

) to automate linting, installation, and upgrade checks for charts.

使用chart-testing工具（

ct

）自动完成Chart的代码检查、安装和升级测试。

Installing ct

安装ct

Install

ct

(chart-testing) locally:

brew install helm/chart-testing/ct

在本地安装

ct

（chart-testing）：

brew install helm/chart-testing/ct

or via Docker:

或通过Docker安装：

docker pull quay.io/helmpack/chart-testing

undefined

undefined

Using ct

使用ct

ct lint --config charts/your-chart/ct.yaml
ct install --config charts/your-chart/ct.yaml

Typical workflow:

Lint all charts:
```
ct lint --all
```
Install and test charts:
```
ct install --all
```
Test only changed charts:
```
ct lint --charts charts/your-chart
```

ct lint --config charts/your-chart/ct.yaml
ct install --config charts/your-chart/ct.yaml

典型工作流：

检查所有Chart：
```
ct lint --all
```
安装并测试所有Chart：
```
ct install --all
```
仅测试变更的Chart：
```
ct lint --charts charts/your-chart
```

Best Practices

最佳实践

Always run
```
ct lint
```
and
```
ct install
```
before submitting a PR
Ensure
```
ct.yaml
```
is up to date with chart locations and test settings
Integrate
```
ct
```
into CI pipelines for automated validation
Address all errors and warnings before merging

提交PR前务必运行
```
ct lint
```
和
```
ct install
```
确保
```
ct.yaml
```
与Chart位置和测试设置保持同步
将
```
ct
```
集成到CI流水线中实现自动验证
合并前解决所有错误和警告

Helmfile Multi-Chart Management

使用Helmfile管理多Chart

Helmfile enables declarative management of multiple Helm charts and environments.

Helmfile支持对多个Helm Chart和环境进行声明式管理。

Installing Helmfile

安装Helmfile

brew install helmfile

brew install helmfile

or via Docker:

或通过Docker安装：

docker run --rm -v $PWD:/apps -w /apps ghcr.io/helmfile/helmfile:latest helmfile --help

undefined

undefined

Using Helmfile

使用Helmfile

Define releases and environments in
```
helmfile.yaml
```
or
```
helmfile.d/*.yaml
```
Use
```
values:
```
blocks to layer configuration and support overrides per environment
Run
```
helmfile lint
```
to validate all releases and values
Apply changes with
```
helmfile apply
```
(dry-run with
```
--dry-run
```
first)
Sync state with
```
helmfile sync
```
to ensure all releases match the desired state

在
```
helmfile.yaml
```
或
```
helmfile.d/*.yaml
```
中定义发布和环境
使用
```
values:
```
块分层配置，支持按环境覆盖配置
运行
```
helmfile lint
```
验证所有发布和配置值
使用
```
helmfile apply
```
应用变更（先使用
```
--dry-run
```
进行试运行）
使用
```
helmfile sync
```
同步状态，确保所有发布与预期状态一致

Helmfile Best Practices

Helmfile最佳实践

Keep environment-specific values in separate files (e.g.,
```
values-prod.yaml
```
,
```
values-dev.yaml
```
)
Use
```
secrets:
```
for sensitive values, leveraging helm-secrets if needed
Prefer referencing charts by version for reproducibility
Use
```
helmfile diff
```
before applying changes to preview impact
Document all environments and overrides clearly
Validate with
```
helmfile lint
```
and test deployments in CI where possible

将环境特定的配置值保存在单独文件中（例如
```
values-prod.yaml
```
、
```
values-dev.yaml
```
）
使用
```
secrets:
```
存储敏感值，必要时借助helm-secrets
优先通过版本引用Chart以保证可复现性
应用变更前使用
```
helmfile diff
```
预览影响
清晰记录所有环境和覆盖配置
尽可能在CI中使用
```
helmfile lint
```
验证并测试部署

Naming Conventions

命名规范

Chart names must be lower case letters and numbers. Words may be separated with dashes (-).

Neither uppercase letters nor underscores can be used in chart names. Dots should not be used in chart names.

YAML files should be indented using two spaces (and never tabs).

Chart名称必须为小写字母和数字，单词间可使用短横线（-）分隔。

Chart名称中不得使用大写字母或下划线，也不应使用点号。

YAML文件应使用两个空格缩进（绝对不能使用制表符）。

CRDs

CRD相关规范

When working with Custom Resource Definitions (CRDs):

There is a declaration of a CRD (YAML file with
```
kind: CustomResourceDefinition
```
)
There are resources that use the CRD (resources with the CRD's
```
apiVersion
```
and
```
kind
```
)

For a CRD, the declaration must be registered before any resources of that CRD's kind(s) can be used.

With Helm 3, use the special

crds

directory in your chart to hold your CRDs. These CRDs are not templated, but will be installed by default when running

helm install

. If the CRD already exists, it will be skipped with a warning. Use

--skip-crds

flag to skip CRD installation.

Note: There is no support for upgrading or deleting CRDs using Helm.

处理自定义资源定义（CRD）时：

需要声明CRD（包含
```
kind: CustomResourceDefinition
```
的YAML文件）
存在使用该CRD的资源（使用CRD的
```
apiVersion
```
和
```
kind
```
的资源）

对于CRD，必须先注册声明，然后才能使用该CRD类型的任何资源。

在Helm 3中，可使用Chart中的特殊

crds

目录存放CRD。这些CRD不会被模板化，但运行

helm install

时会默认安装。如果CRD已存在，会跳过安装并发出警告。使用

--skip-crds

标志可跳过CRD安装。

注意： Helm不支持升级或删除CRD。

Standard Labels

标准标签

The following labels are recommended for Helm charts:

Name	Status	Description
`app.kubernetes.io/name`	REC	App name, usually `{{ template "name" . }}`
`helm.sh/chart`	REC	Chart name and version: `{{ .Chart.Name }}-{{ .Chart.Version \| replace "+" "_" }}`
`app.kubernetes.io/managed-by`	REC	Always set to `{{ .Release.Service }}`
`app.kubernetes.io/instance`	REC	Set to `{{ .Release.Name }}`
`app.kubernetes.io/version`	OPT	App version: `{{ .Chart.AppVersion }}`
`app.kubernetes.io/component`	OPT	Component role, e.g., `frontend`
`app.kubernetes.io/part-of`	OPT	Top-level application when multiple charts work together

An item of metadata should be a label if:

It is used by Kubernetes to identify this resource
It is useful for operators to query the system

If an item of metadata is not used for querying, it should be set as an annotation instead.

推荐为Helm Chart使用以下标签：

名称	状态	描述
`app.kubernetes.io/name`	推荐	应用名称，通常为 `{{ template "name" . }}`
`helm.sh/chart`	推荐	Chart名称和版本： `{{ .Chart.Name }}-{{ .Chart.Version \| replace "+" "_" }}`
`app.kubernetes.io/managed-by`	推荐	始终设置为 `{{ .Release.Service }}`
`app.kubernetes.io/instance`	推荐	设置为 `{{ .Release.Name }}`
`app.kubernetes.io/version`	可选	应用版本： `{{ .Chart.AppVersion }}`
`app.kubernetes.io/component`	可选	组件角色，例如 `frontend`
`app.kubernetes.io/part-of`	可选	多Chart协作时的顶层应用名称

满足以下条件的元数据项应设为标签：

被Kubernetes用于识别该资源
便于运维人员查询系统

如果元数据项不用于查询，应设为注解。

Images

镜像规范

A container image should use a fixed tag or the SHA of the image. Never use

latest

head

canary

, or other "floating" tags.

容器镜像应使用固定标签或镜像SHA值，绝不能使用

latest

、

head

、

canary

或其他“浮动”标签。

Pods

Pod规范

All PodTemplate sections should specify a selector:

yaml

selector:
  matchLabels:
    app.kubernetes.io/name: MyName
template:
  metadata:
    labels:
      app.kubernetes.io/name: MyName

This makes the relationship between the set and the pod explicit and prevents breaking changes when labels change.

所有PodTemplate部分必须指定选择器：

yaml

selector:
  matchLabels:
    app.kubernetes.io/name: MyName
template:
  metadata:
    labels:
      app.kubernetes.io/name: MyName

这能明确集合与Pod之间的关系，防止标签变更时出现破坏性变化。

RBAC Configuration

RBAC配置规范

RBAC and ServiceAccount configuration should happen under separate keys:

yaml

rbac:
  # Specifies whether RBAC resources should be created
  create: true

serviceAccount:
  # Specifies whether a ServiceAccount should be created
  create: true
  # The name of the ServiceAccount to use
  # If not set and create is true, a name is generated using the fullname template
  name:

For complex charts with multiple ServiceAccounts:

yaml

someComponent:
  serviceAccount:
    create: true
    name:
anotherComponent:
  serviceAccount:
    create: true
    name:

rbac.create

should default to

true

. Users who wish to manage RBAC access controls themselves can set this to

false

RBAC和ServiceAccount配置应放在独立的配置项中：

yaml

rbac:
  # 指定是否创建RBAC资源
  create: true

serviceAccount:
  # 指定是否创建ServiceAccount
  create: true
  # 要使用的ServiceAccount名称
  # 如果未设置且create为true，将使用fullname模板生成名称
  name:

对于包含多个ServiceAccount的复杂Chart：

yaml

someComponent:
  serviceAccount:
    create: true
    name:
anotherComponent:
  serviceAccount:
    create: true
    name:

rbac.create

应默认设为

true

，希望自行管理RBAC权限的用户可将其设为

false

。

ServiceAccount Helper Template

ServiceAccount辅助模板

yaml

{{/*
Create the name of the service account to use
*/}}
{{- define "mychart.serviceAccountName" -}}
{{- if .Values.serviceAccount.create -}}
    {{ default (include "mychart.fullname" .) .Values.serviceAccount.name }}
{{- else -}}
    {{ default "default" .Values.serviceAccount.name }}
{{- end -}}
{{- end -}}

yaml

{{/*
生成要使用的ServiceAccount名称
*/}}
{{- define "mychart.serviceAccountName" -}}
{{- if .Values.serviceAccount.create -}}
    {{ default (include "mychart.fullname" .) .Values.serviceAccount.name }}
{{- else -}}
    {{ default "default" .Values.serviceAccount.name }}
{{- end -}}
{{- end -}}

Templates Directory Structure

模板目录结构

The

templates/

directory should be structured as follows:

Template files should have the extension
```
.yaml
```
if they produce YAML output
The extension
```
.tpl
```
may be used for template files that produce no formatted content
Template file names should use dashed notation (
```
my-example-configmap.yaml
```
), not camelcase
Each resource definition should be in its own template file
Template file names should reflect the resource kind (e.g.,
```
foo-pod.yaml
```
,
```
bar-svc.yaml
```
)

templates/

目录应遵循以下结构：

生成YAML输出的模板文件应使用
```
.yaml
```
扩展名
不生成格式化内容的模板文件可使用
```
.tpl
```
扩展名
模板文件名应使用短横线命名法（
```
my-example-configmap.yaml
```
），而非驼峰命名
每个资源定义应放在单独的模板文件中
模板文件名应反映资源类型（例如
```
foo-pod.yaml
```
、
```
bar-svc.yaml
```
）

Defined Template Names

模板名称规范

All defined template names should be namespaced to avoid collisions with subcharts:

Correct:

yaml

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

Incorrect:

yaml

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

所有自定义模板名称应添加命名空间，避免与子Chart冲突：

正确示例：

yaml

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

错误示例：

yaml

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

Formatting Templates

模板格式规范

Templates should be indented using two spaces (never tabs).

Template directives should have whitespace after the opening braces and before the closing braces:

Correct:

text

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

Incorrect:

text

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

模板应使用两个空格缩进（绝不能使用制表符）。

模板指令的左大括号后和右大括号前应保留空格：

正确示例：

text

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

错误示例：

text

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

helm-best-practices

Original

Translation

Helm Chart Style Guide

Helm Chart 风格指南

When to Use

适用场景

Image Configuration Best Practices

镜像配置最佳实践

Consistent Image Blocks

一致的镜像块格式

Templating Pattern for Registry Override

镜像仓库覆盖的模板模式

Templating Conventions

模板编写规范

Linting & Validation

代码检查与验证

Automated Chart Testing with ct

使用ct实现Chart自动化测试

Installing ct

安装ct

or via Docker:

或通过Docker安装：

docker pull quay.io/helmpack/chart-testing

docker pull quay.io/helmpack/chart-testing

Using ct

使用ct

Best Practices

最佳实践

Helmfile Multi-Chart Management

使用Helmfile管理多Chart

Installing Helmfile

安装Helmfile

or via Docker:

或通过Docker安装：

docker run --rm -v $PWD:/apps -w /apps ghcr.io/helmfile/helmfile:latest helmfile --help

docker run --rm -v $PWD:/apps -w /apps ghcr.io/helmfile/helmfile:latest helmfile --help

Using Helmfile

使用Helmfile

Helmfile Best Practices

Helmfile最佳实践

Naming Conventions

命名规范

CRDs

CRD相关规范

Standard Labels

标准标签

Images

镜像规范

Pods

Pod规范

RBAC Configuration

RBAC配置规范

ServiceAccount Helper Template

ServiceAccount辅助模板

Templates Directory Structure

模板目录结构

Defined Template Names

模板名称规范

Formatting Templates

模板格式规范

Checklist for Chart Review

Chart评审检查清单

Structure

结构

Image Configuration

镜像配置

Labels & Selectors

标签与选择器

RBAC

RBAC配置

Validation

验证