Explains the chart format, and provides basic guidance for building charts with Helm.

Helm uses a packaging format called charts. A chart is a collection of files that describe a related set of Kubernetes resources. A single chart might be used to deploy something simple, like a memcached pod, or something complex, like a full web app stack with HTTP servers, databases, caches, and so on.

helm使用被称为charts的打包格式。一个char是一组文件的集合，该集合用于描述一组相关联的k8s资源。单一的chart可以被用于部署一些简单的应用，例如memcached pod 或一些更复杂的东西，例如完整的网页app栈，包含http服务器，数据库，缓存等等。

Charts are created as files laid out in a particular directory tree. They can be packaged into versioned archives to be deployed.

chart有自己特定的目录结构。可以被打包进按版本的压缩包中来进行部署。

If you want to download and look at the files for a published chart, without installing it, you can do so with helm pull chartrepo/chartname.

如果向下载和查看已发布的chart包中的文件，而不是安装它，可以使用helm pull chartreoi/chartname指令

This document explains the chart format, and provides basic guidance for building charts with Helm.

本文解释了chart 的基本格式，并提供了使用Helm构建chart的基本指导。

The Chart File Structure

A chart is organized as a collection of files inside of a directory. The directory name is the name of the chart (without versioning information). Thus, a chart describing WordPress would be stored in a wordpress/ directory.

Inside of this directory, Helm will expect a structure that matches this:

chart被组织为一个文件夹内的文件集合。文件夹的名字是char的名字(不含版本信息)。因此，一个用于描述Wordpree的char包应该被存储于wordpress/文件夹下

在此目录下，helm 使用以下结构

  1. wordpress/
  2.   Chart.yaml          # A YAML file containing information about the chart
  3.   LICENSE             # OPTIONAL: A plain text file containing the license for the chart
  4.   README.md           # OPTIONAL: A human-readable README file
  5.   values.yaml         # The default configuration values for this chart
  6.   values.schema.json  # OPTIONAL: A JSON Schema for imposing a structure on the values.yaml file
  7.   charts/             # A directory containing any charts upon which this chart depends.
  8.   crds/               # Custom Resource Definitions
  9.   templates/          # A directory of templates that, when combined with values,
  10.                       # will generate valid Kubernetes manifest files.
  11.   templates/NOTES.txt # OPTIONAL: A plain text file containing short usage notes

Helm reserves use of the charts/, crds/, and templates/ directories, and of the listed file names. Other files will be left as they are.

helm 保留charts/,crds/以及template/目录以及上列列出的文件名称，其他文件则没有要求

The Chart.yaml File

The Chart.yaml file is required for a chart. It contains the following fields:

每个chart都需要有一个Chart.yaml的文件，它包含以下字段

apiVersion: The chart API version (required)
name: The name of the chart (required)
version: A SemVer 2 version (required)
kubeVersion: A SemVer range of compatible Kubernetes versions (optional)
description: A single-sentence description of this project (optional)
type: The type of the chart (optional)
keywords:
  - A list of keywords about this project (optional)
home: The URL of this projects home page (optional)
sources:
  - A list of URLs to source code for this project (optional)
dependencies: # A list of the chart requirements (optional)
  - name: The name of the chart (nginx)
    version: The version of the chart ("1.2.3")
    repository: (optional) The repository URL ("https://example.com/charts") or alias ("@repo-name")
    condition: (optional) A yaml path that resolves to a boolean, used for enabling/disabling charts (e.g. subchart1.enabled )
    tags: # (optional)
      - Tags can be used to group charts for enabling/disabling together
    import-values: # (optional)
      - ImportValues holds the mapping of source values to parent key to be imported. Each item can be a string or pair of child/parent sublist items.
        alias: (optional) Alias to be used for the chart. Useful when you have to add the same chart multiple times
maintainers: # (optional)
  - name: The maintainers name (required for each maintainer)
    email: The maintainers email (optional for each maintainer)
    url: A URL for the maintainer (optional for each maintainer)
icon: A URL to an SVG or PNG image to be used as an icon (optional).
appVersion: The version of the app that this contains (optional). Needn't be SemVer. Quotes recommended.
deprecated: Whether this chart is deprecated (optional, boolean)
annotations:
  example: A list of annotations keyed by name (optional).

Other fields will be silently ignored.

Charts and Versioning

Every chart must have a version number. A version must follow the SemVer 2 standard. Unlike Helm Classic, Helm v2 and later uses version numbers as release markers. Packages in repositories are identified by name plus version.

For example, an nginx chart whose version field is set to version: 1.2.3 will be named:

More complex SemVer 2 names are also supported, such as version: 1.2.3-alpha.1+ef365. But non-SemVer names are explicitly disallowed by the system.

NOTE: Whereas Helm Classic and Deployment Manager were both very GitHub oriented when it came to charts, Helm v2 and later does not rely upon or require GitHub or even Git. Consequently, it does not use Git SHAs for versioning at all.

The version field inside of the Chart.yaml is used by many of the Helm tools, including the CLI. When generating a package, the helm package command will use the version that it finds in the Chart.yaml as a token in the package name. The system assumes that the version number in the chart package name matches the version number in the Chart.yaml. Failure to meet this assumption will cause an error.

The apiVersion Field

The apiVersion field should be v2 for Helm charts that require at least Helm 3. Charts supporting previous Helm versions have an apiVersion set to v1 and are still installable by Helm 3.

Changes from v1 to v2:

  • A dependencies field defining chart dependencies, which were located in a separate requirements.yaml file for v1 charts (see Chart Dependencies).
  • The type field, discriminating application and library charts (see Chart Types).

The appVersion Field

Note that the appVersion field is not related to the version field. It is a way of specifying the version of the application. For example, the drupal chart may have an appVersion: "8.2.1", indicating that the version of Drupal included in the chart (by default) is 8.2.1. This field is informational, and has no impact on chart version calculations. Wrapping the version in quotes is highly recommended. It forces the YAML parser to treat the version number as a string. Leaving it unquoted can lead to parsing issues in some cases. For example, YAML interprets 1.0 as a floating point value, and a git commit SHA like 1234e10 as scientific notation.

As of Helm v3.5.0, helm create wraps the default appVersion field in quotes.

The kubeVersion Field

The optional kubeVersion field can define semver constraints on supported Kubernetes versions. Helm will validate the version constraints when installing the chart and fail if the cluster runs an unsupported Kubernetes version.

Version constraints may comprise space separated AND comparisons such as

which themselves can be combined with the OR || operator like in the following example

>= 1.13.0 < 1.14.0 || >= 1.14.1 < 1.15.0

In this example the version 1.14.0 is excluded, which can make sense if a bug in certain versions is known to prevent the chart from running properly.

Apart from version constrains employing operators = != > < >= <= the following shorthand notations are supported

  • hyphen ranges for closed intervals, where 1.1 - 2.3.4 is equivalent to >= 1.1 <= 2.3.4.
  • wildcards x, X and *, where 1.2.x is equivalent to >= 1.2.0 < 1.3.0.
  • tilde ranges (patch version changes allowed), where ~1.2.3 is equivalent to >= 1.2.3 < 1.3.0.
  • caret ranges (minor version changes allowed), where ^1.2.3 is equivalent to >= 1.2.3 < 2.0.0.

For a detailed explanation of supported semver constraints see Masterminds/semver.

Deprecating Charts

When managing charts in a Chart Repository, it is sometimes necessary to deprecate a chart. The optional deprecated field in Chart.yaml can be used to mark a chart as deprecated. If the latest version of a chart in the repository is marked as deprecated, then the chart as a whole is considered to be deprecated. The chart name can be later reused by publishing a newer version that is not marked as deprecated. The workflow for deprecating charts is:

  1. Update chart’s Chart.yaml to mark the chart as deprecated, bumping the version
  2. Release the new chart version in the Chart Repository
  3. Remove the chart from the source repository (e.g. git)

Chart Types

The type field defines the type of chart. There are two types: application and library. Application is the default type and it is the standard chart which can be operated on fully. The library chart provides utilities or functions for the chart builder. A library chart differs from an application chart because it is not installable and usually doesn’t contain any resource objects.

Note: An application chart can be used as a library chart. This is enabled by setting the type to library. The chart will then be rendered as a library chart where all utilities and functions can be leveraged. All resource objects of the chart will not be rendered.

Chart LICENSE, README and NOTES

Charts can also contain files that describe the installation, configuration, usage and license of a chart.

chart中也包含安装、配置、使用说明、许可证等文件

A LICENSE is a plain text file containing the license for the chart. The chart can contain a license as it may have programming logic in the templates and would therefore not be configuration only. There can also be separate license(s) for the application installed by the chart, if required.

A README for a chart should be formatted in Markdown (README.md), and should generally contain:

  • A description of the application or service the chart provides
  • Any prerequisites or requirements to run the chart
  • Descriptions of options in values.yaml and default values
  • Any other information that may be relevant to the installation or configuration of the chart

README文件应使用Markdown进行编写，并包含以下内容：

  1. 对此chart所提供的应用/服务的描述
  2. 运行此chart 的必备条件
  3. 对`values.yaml文件选项和默认值的描述
  4. 和chart的安装、配置相关的其他信息

When hubs and other user interfaces display details about a chart that detail is pulled from the content in the README.md file.

当hub或其他用户接口展示chart的具体信息时，会从README.md中拉取消息。

The chart can also contain a short plain text templates/NOTES.txt file that will be printed out after installation, and when viewing the status of a release. This file is evaluated as a template, and can be used to display usage notes, next steps, or any other information relevant to a release of the chart. For example, instructions could be provided for connecting to a database, or accessing a web UI. Since this file is printed to STDOUT when running helm install or helm status, it is recommended to keep the content brief and point to the README for greater detail.

chart 中也可以包含一个templates/NOTE.txt文件，该文件会在安装完成后进行打印，显示发行状 态。这个文件被视作一个模版(template)，可用于显示用法、注意事项、下一步的动作或其他和此发行版本相关的信息

Chart Dependencies

In Helm, one chart may depend on any number of other charts. These dependencies can be dynamically linked using the dependencies field in Chart.yaml or brought in to the charts/ directory and managed manually.

在helm中，说和chart可以依赖于任意数量的其他chart。这些依赖可以通过Chart.yaml文件中的dependencies字段进行动态连接

Managing Dependencies with the dependencies field

The charts required by the current chart are defined as a list in the dependencies field.

dependencies:
  - name: apache
    version: 1.2.3
    repository: https://example.com/charts
  - name: mysql
    version: 3.2.1
    repository: https://another.example.com/charts
  • The name field is the name of the chart you want.
  • The version field is the version of the chart you want.
  • The repository field is the full URL to the chart repository. Note that you must also use helm repo add to add that repo locally.
  • You might use the name of the repo instead of URL
$ helm repo add fantastic-charts https://fantastic-charts.storage.googleapis.com

dependencies:
  - name: awesomeness
    version: 1.0.0
    repository: "@fantastic-charts"

Once you have defined dependencies, you can run helm dependency update and it will use your dependency file to download all the specified charts into your charts/ directory for you.

当定义完毕所需要的依赖后，运行helm dependency update命令，之后依赖文件就会自动下载到你的charts文件夹中。

$ helm dep up foochart
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "local" chart repository
...Successfully got an update from the "stable" chart repository
...Successfully got an update from the "example" chart repository
...Successfully got an update from the "another" chart repository
Update Complete. Happy Helming!
Saving 2 charts
Downloading apache from repo https://example.com/charts
Downloading mysql from repo https://another.example.com/charts

When helm dependency update retrieves charts, it will store them as chart archives in the charts/ directory. So for the example above, one would expect to see the following files in the charts directory:

当helm dependency update检索到相应的chart，它会将其以chart归档文件的形式存储在charts/目录中。因此，在上例中，用户可以在charts目录下看到以下内容。

charts/
  apache-1.2.3.tgz
  mysql-3.2.1.tgz

Alias field in dependencies

In addition to the other fields above, each requirements entry may contain the optional field alias.

Adding an alias for a dependency chart would put a chart in dependencies using alias as name of new dependency.

One can use alias in cases where they need to access a chart with other name(s).

除了以上字段意外，每个需求项也可以包含一个alias字段。为依赖的chart包添加一个别名，会使用别名作为新依赖chart的名称

在需要时候其他名称访问依赖chart包时，可以使用alias字段。

# parentchart/Chart.yaml

dependencies:
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    alias: new-subchart-1
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    alias: new-subchart-2
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0

In the above example we will get 3 dependencies in all for parentchart:

subchart
new-subchart-1
new-subchart-2

The manual way of achieving this is by copy/pasting the same chart in the charts/ directory multiple times with different names.

Tags and Condition fields in dependencies

In addition to the other fields above, each requirements entry may contain the optional fields tags and condition.

All charts are loaded by default. If tags or condition fields are present, they will be evaluated and used to control loading for the chart(s) they are applied to.

Condition - The condition field holds one or more YAML paths (delimited by commas). If this path exists in the top parent’s values and resolves to a boolean value, the chart will be enabled or disabled based on that boolean value. Only the first valid path found in the list is evaluated and if no paths exist then the condition has no effect.

Tags - The tags field is a YAML list of labels to associate with this chart. In the top parent’s values, all charts with tags can be enabled or disabled by specifying the tag and a boolean value.

# parentchart/Chart.yaml

dependencies:
  - name: subchart1
    repository: http://localhost:10191
    version: 0.1.0
    condition: subchart1.enabled, global.subchart1.enabled
    tags:
      - front-end
      - subchart1
  - name: subchart2
    repository: http://localhost:10191
    version: 0.1.0
    condition: subchart2.enabled,global.subchart2.enabled
    tags:
      - back-end
      - subchart2

# parentchart/values.yaml

subchart1:
  enabled: true
tags:
  front-end: false
  back-end: true

In the above example all charts with the tag front-end would be disabled but since the subchart1.enabled path evaluates to ‘true’ in the parent’s values, the condition will override the front-end tag and subchart1 will be enabled.

Since subchart2 is tagged with back-end and that tag evaluates to true, subchart2 will be enabled. Also note that although subchart2 has a condition specified, there is no corresponding path and value in the parent’s values so that condition has no effect.

Using the CLI with Tags and Conditions

The --set parameter can be used as usual to alter tag and condition values.

helm install --set tags.front-end=true --set subchart2.enabled=false

Tags and Condition Resolution
  • Conditions (when set in values) always override tags. The first condition path that exists wins and subsequent ones for that chart are ignored.
  • Tags are evaluated as ‘if any of the chart’s tags are true then enable the chart’.
  • Tags and conditions values must be set in the top parent’s values.
  • The tags: key in values must be a top level key. Globals and nested tags: tables are not currently supported.

Importing Child Values via dependencies

In some cases it is desirable to allow a child chart’s values to propagate to the parent chart and be shared as common defaults. An additional benefit of using the exports format is that it will enable future tooling to introspect user-settable values.

The keys containing the values to be imported can be specified in the parent chart’s dependencies in the field import-values using a YAML list. Each item in the list is a key which is imported from the child chart’s exports field.

To import values not contained in the exports key, use the child-parent format. Examples of both formats are described below.

Using the exports format

If a child chart’s values.yaml file contains an exports field at the root, its contents may be imported directly into the parent’s values by specifying the keys to import as in the example below:

# parent's Chart.yaml file

dependencies:
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    import-values:
      - data

# child's values.yaml file

exports:
  data:
    myint: 99

Since we are specifying the key data in our import list, Helm looks in the exports field of the child chart for data key and imports its contents.

The final parent values would contain our exported field:

# parent's values

myint: 99

Please note the parent key data is not contained in the parent’s final values. If you need to specify the parent key, use the ‘child-parent’ format.

Using the child-parent format

To access values that are not contained in the exports key of the child chart’s values, you will need to specify the source key of the values to be imported (child) and the destination path in the parent chart’s values (parent).

The import-values in the example below instructs Helm to take any values found at child: path and copy them to the parent’s values at the path specified in parent:

# parent's Chart.yaml file

dependencies:
  - name: subchart1
    repository: http://localhost:10191
    version: 0.1.0
    ...
    import-values:
      - child: default.data
        parent: myimports

In the above example, values found at default.data in the subchart1’s values will be imported to the myimports key in the parent chart’s values as detailed below:

# parent's values.yaml file

myimports:
  myint: 0
  mybool: false
  mystring: "helm rocks!"

# subchart1's values.yaml file

default:
  data:
    myint: 999
    mybool: true

The parent chart’s resulting values would be:

# parent's final values

myimports:
  myint: 999
  mybool: true
  mystring: "helm rocks!"

The parent’s final values now contains the myint and mybool fields imported from subchart1.

Managing Dependencies manually via the charts/ directory

If more control over dependencies is desired, these dependencies can be expressed explicitly by copying the dependency charts into the charts/ directory.

A dependency can be either a chart archive (foo-1.2.3.tgz) or an unpacked chart directory. But its name cannot start with _ or .. Such files are ignored by the chart loader.

For example, if the WordPress chart depends on the Apache chart, the Apache chart (of the correct version) is supplied in the WordPress chart’s charts/ directory:

wordpress:
  Chart.yaml
  # ...
  charts/
    apache/
      Chart.yaml
      # ...
    mysql/
      Chart.yaml
      # ...

The example above shows how the WordPress chart expresses its dependency on Apache and MySQL by including those charts inside of its charts/ directory.

TIP: To drop a dependency into your charts/ directory, use the helm pull command

Operational aspects of using dependencies

The above sections explain how to specify chart dependencies, but how does this affect chart installation using helm install and helm upgrade?

Suppose that a chart named “A” creates the following Kubernetes objects

  • namespace “A-Namespace”
  • statefulset “A-StatefulSet”
  • service “A-Service”

Furthermore, A is dependent on chart B that creates objects

  • namespace “B-Namespace”
  • replicaset “B-ReplicaSet”
  • service “B-Service”

After installation/upgrade of chart A a single Helm release is created/modified. The release will create/update all of the above Kubernetes objects in the following order:

  • A-Namespace
  • B-Namespace
  • A-Service
  • B-Service
  • B-ReplicaSet
  • A-StatefulSet

This is because when Helm installs/upgrades charts, the Kubernetes objects from the charts and all its dependencies are

  • aggregated into a single set; then
  • sorted by type followed by name; and then
  • created/updated in that order.

Hence a single release is created with all the objects for the chart and its dependencies.

The install order of Kubernetes types is given by the enumeration InstallOrder in kind_sorter.go (see the Helm source file).

Templates and Values 模版和值

Helm Chart templates are written in the Go template language, with the addition of 50 or so add-on template functions from the Sprig library and a few other specialized functions.

helm chart模版是按照go 模版语言编写的。并从Spring库和其他一些来源添加了50多个额外的函数。

All template files are stored in a chart’s templates/ folder. When Helm renders the charts, it will pass every file in that directory through the template engine.

所有的模版文件都被存储于chart的templates/目录下。当helm渲染chart时，他会将该目录下的所有文件传递到模版引擎中。

Values for the templates are supplied two ways:

  • Chart developers may supply a file called values.yaml inside of a chart. This file can contain default values.
  • Chart users may supply a YAML file that contains values. This can be provided on the command line with helm install.

When a user supplies custom values, these values will override the values in the chart’s values.yaml file.

模版文件通过两种方式来获取实际的值：

  1. 开发者在chart中提供一个名为values.yaml的文件，该文件可包含默认值
  2. 用户可以提供一个包含了值的yaml文件，该文件通过helm install命令传入

当用户提供了自定义的值时，这些值会覆盖掉chart中values.yaml文件中的值

Template Files 模版文件

Template files follow the standard conventions for writing Go templates (see the text/template Go package documentation for details). An example template file might look something like this:

模版文件遵循go模版的标准。模版文件样例如下：

apiVersion: v1
kind: ReplicationController
metadata:
  name: deis-database
  namespace: deis
  labels:
    app.kubernetes.io/managed-by: deis
spec:
  replicas: 1
  selector:
    app.kubernetes.io/name: deis-database
  template:
    metadata:
      labels:
        app.kubernetes.io/name: deis-database
    spec:
      serviceAccount: deis-database
      containers:
        - name: deis-database
          image: {{ .Values.imageRegistry }}/postgres:{{ .Values.dockerTag }}
          imagePullPolicy: {{ .Values.pullPolicy }}
          ports:
            - containerPort: 5432
          env:
            - name: DATABASE_STORAGE
              value: {{ default "minio" .Values.storage }}

The above example, based loosely on https://github.com/deis/charts, is a template for a Kubernetes replication controller. It can use the following four template values (usually defined in a values.yaml file):

  • imageRegistry: The source registry for the Docker image.
  • dockerTag: The tag for the docker image.
  • pullPolicy: The Kubernetes pull policy.
  • storage: The storage backend, whose default is set to "minio"

All of these values are defined by the template author. Helm does not require or dictate parameters.

To see many working charts, check out the CNCF Artifact Hub.

Predefined Values 预定义值

Values that are supplied via a values.yaml file (or via the --set flag) are accessible from the .Values object in a template. But there are other pre-defined pieces of data you can access in your templates.

通过valies.yaml文件( 或通过--set)定义的值，在模版文件中可通过.Values进行访问。

但在模版文件中还有其他可以预定义的数据。

The following values are pre-defined, are available to every template, and cannot be overridden. As with all values, the names are case sensitive.

下列值是预定义的，每个模版都可以访问并且无法被覆盖。和所有值一样，其名字是大小写敏感的。

  • Release.Name: The name of the release (not the chart) 版本名称(不是Chart的名称)

  • Release.Namespace: The namespace the chart was released to. 发布的Chart的命名空间

  • Release.Service: The service that conducted the release.组织版本的服务

  • Release.IsUpgrade: This is set to true if the current operation is an upgrade or rollback.当前的操作是升级还是回滚，设置为true

  • Release.IsInstall: This is set to true if the current operation is an install.如果当前的操作是安装，则设置为true

  • Chart: The contents of the Chart.yaml. Thus, the chart version is obtainable as Chart.Version and the maintainers are in Chart.Maintainers. Chart.yaml中的内容。因此Chart.Version以及Chart.Maintainers都可以获取

  • Files: A map-like object containing all non-special files in the chart. This will not give you access to templates, but will give you access to additional files that are present (unless they are excluded using .helmignore). Files can be accessed using {{ index .Files "file.name" }} or using the {{.Files.Get name }} function. You can also access the contents of the file as []byte using {{ .Files.GetBytes }}

chart中的包含了非特殊文件的类图对象。这将不允许您访问模板， 但是可以访问现有的其他文件（除非被.helmignore排除在外）。 使用{{ index .Files "file.name" }}可以访问文件或者使用{{.Files.Get name }}功能。 您也可以使用{{ .Files.GetBytes }}作为[]byte方位文件内容。

  • Capabilities: A map-like object that contains information about the versions of Kubernetes ({{ .Capabilities.KubeVersion }}) and the supported Kubernetes API versions ({{ .Capabilities.APIVersions.Has "batch/v1" }})

包含了Kubernetes版本信息的类图对象。({{ .Capabilities.KubeVersion }}) 和支持的Kubernetes API 版本({{ .Capabilities.APIVersions.Has "batch/v1" }})

NOTE: Any unknown Chart.yaml fields will be dropped. They will not be accessible inside of the Chart object. Thus, Chart.yaml cannot be used to pass arbitrarily structured data into the template. The values file can be used for that, though.

注意：任何未知的Chart.yaml字段都会被抛弃。在Chart对象内都不访问。因此，Chart.yaml不能被用于向模版中传递任意类型的数据结构。value文件可用于此方法。

Values files 值文件

Considering the template in the previous section, a values.yaml file that supplies the necessary values would look like this:

参考之前章节中的模版，values.yaml文件可提供以下必要值

imageRegistry: "quay.io/deis"
dockerTag: "latest"
pullPolicy: "Always"
storage: "s3"

A values file is formatted in YAML. A chart may include a default values.yaml file. The Helm install command allows a user to override values by supplying additional YAML values:

value文件使用yaml格式。chart会包含一个默认的values.yaml文件。helm安装命令允许用户通过提供额外的yaml value来覆盖掉这个value

$ helm install --generate-name --values=myvals.yaml wordpress

When values are passed in this way, they will be merged into the default values file. For example, consider a myvals.yaml file that looks like this:

当通过这种方法传递值的时，相应的值会合并到默认value文件中，例如，使用如下所示的myvals.yaml文件

storage : "gcs"

When this is merged with the values.yaml in the chart, the resulting generated content will be:

在这个值在chart中被合并到value.yaml中时，会产生如下结果：

imageRegistry: "quay.io/deis"
dockerTag: "latest"
pullPolicy: "Always"
storage: "gcs"

Note that only the last field was overridden.

需要注意的是只有最后一个字段会被覆盖

NOTE: The default values file included inside of a chart must be named values.yaml. But files specified on the command line can be named anything.

注意： 在Chart包中默认的value文件必须以value.yaml文件命名；在命令行中传入的文件则没有限制

NOTE: If the --set flag is used on helm install or helm upgrade, those values are simply converted to YAML on the client side.

注意: 如果在使用helm install或helm upgrade时使用了--set标志，这些值会在客户端被转换成yaml

NOTE: If any required entries in the values file exist, they can be declared as required in the chart template by using the ‘required’ function

注意：如果values文件存在任何必需的条目，他们会在chart模版中使用required函数声明为必须的

Any of these values are then accessible inside of templates using the .Values object:

在模版中使用.Values对象，就可以任意访问这些值了

apiVersion: v1
kind: ReplicationController
metadata:
  name: deis-database
  namespace: deis
  labels:
    app.kubernetes.io/managed-by: deis
spec:
  replicas: 1
  selector:
    app.kubernetes.io/name: deis-database
  template:
    metadata:
      labels:
        app.kubernetes.io/name: deis-database
    spec:
      serviceAccount: deis-database
      containers:
        - name: deis-database
          image: {{ .Values.imageRegistry }}/postgres:{{ .Values.dockerTag }}
          imagePullPolicy: {{ .Values.pullPolicy }}
          ports:
            - containerPort: 5432
          env:
            - name: DATABASE_STORAGE
              value: {{ default "minio" .Values.storage }}

Scope, Dependencies, and Values 范围,依赖和值

Values files can declare values for the top-level chart, as well as for any of the charts that are included in that chart’s charts/ directory. Or, to phrase it differently, a values file can supply values to the chart as well as to any of its dependencies. For example, the demonstration WordPress chart above has both mysql and apache as dependencies. The values file could supply values to all of these components:

Value文件可以为最高层次的chart提供值，也可以为所有charts/下包含的chart提供值。换句话说，value文件可以为chart及其所有的依赖提供值信息。例如，wordpress chart的例子中包含mysql和apache作为依赖。则value文件可以为所有组件提供值。

title: "My WordPress Site" # Sent to the WordPress template

mysql:
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  port: 8080 # Passed to Apache

Charts at a higher level have access to all of the variables defined beneath. So the WordPress chart can access the MySQL password as .Values.mysql.password. But lower level charts cannot access things in parent charts, so MySQL will not be able to access the title property. Nor, for that matter, can it access apache.port.

最高层的chart可以访问下面定义的所有变量。因此，WordPress chart可以访问MYSQL密码，.Values.mysql.password,但低层次的chart无法访问上层的数据，所以MySQL无法访问title属性。同样也无法访问apache.port

Values are namespaced, but namespaces are pruned. So for the WordPress chart, it can access the MySQL password field as .Values.mysql.password. But for the MySQL chart, the scope of the values has been reduced and the namespace prefix removed, so it will see the password field simply as .Values.password.

values属于特定的命名空间，但是命名空间被删减了。因此对于Wordpress chart，其可以用.Values.mysql.password来访问mysql的密码字段。但是对于mysql chart来说，值的范围被缩减了且命名空间前缀被移除了，因此，它把密码字段简单的看作.Values.passworcd

Global Values 全局值

As of 2.0.0-Alpha.2, Helm supports special “global” value. Consider this modified version of the previous example:

从2.0.0-Alpha.2开始，helm支持特殊的global值。

title: "My WordPress Site" # Sent to the WordPress template

global:
  app: MyWordPress

mysql:
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  port: 8080 # Passed to Apache

The above adds a global section with the value app: MyWordPress. This value is available to all charts as .Values.global.app.

上面添加了global章节，其包含一个app: MyWordPress值。所有的chart都可以使用.Values.global.app来访问这个值

For example, the mysql templates may access app as {{ .Values.global.app}}, and so can the apache chart. Effectively, the values file above is regenerated like this

例如,mysql模版可以通过{{.Values.global.app}}来访问app的值，apachechart也是一样。

实际上，上面的values文件会重塑成这样

title: "My WordPress Site" # Sent to the WordPress template

global:
  app: MyWordPress

mysql:
  global:
    app: MyWordPress
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  global:
    app: MyWordPress
  port: 8080 # Passed to Apache

This provides a way of sharing one top-level variable with all subcharts, which is useful for things like setting metadata properties like labels.

这提供了一种和所有的子chart共享顶级变量的方式，这在设置metadata中的labels时会很有效

If a subchart declares a global variable, that global will be passed downward (to the subchart’s subcharts), but not upward to the parent chart. There is no way for a subchart to influence the values of the parent chart.

如果一个子chart声明了一个全局变量，则该变量会向下传递，但不会向上传递到上层chart中。子chart无法影响到上层chart的值

Also, global variables of parent charts take precedence over the global variables from subcharts.

并且上层Chart的全局变量优先于子chart中的全局变量

Schema Files 模式文件

Sometimes, a chart maintainer might want to define a structure on their values. This can be done by defining a schema in the values.schema.json file. A schema is represented as a JSON Schema. It might look something like this:

有时，chart的维护者希望基于values定义一个结构。这可以通过在values.schema,json定义一个模式来实现。模式使用json格式

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "properties": {
    "image": {
      "description": "Container Image",
      "properties": {
        "repo": {
          "type": "string"
        },
        "tag": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": {
      "description": "Service name",
      "type": "string"
    },
    "port": {
      "description": "Port",
      "minimum": 0,
      "type": "integer"
    },
    "protocol": {
      "type": "string"
    }
  },
  "required": [
    "protocol",
    "port"
  ],
  "title": "Values",
  "type": "object"
}

This schema will be applied to the values to validate it. Validation occurs when any of the following commands are invoked:

这个架构会应用Value并验证它。以下命令都会触发校验

  • helm install
  • helm upgrade
  • helm lint
  • helm template

An example of a values.yaml file that meets the requirements of this schema might look something like this:

一个符合此架构要求的values.yaml文件实例如下

name: frontend
protocol: https
port: 443

Note that the schema is applied to the final .Values object, and not just to the values.yaml file. This means that the following yaml file is valid, given that the chart is installed with the appropriate --set option shown below.

注意，此模式应用与最终的.Value对象，不仅是values.yaml文件。这就以为着以下yaml文件是有效的，给定的chart时用下面的显示的适当的—set选项安装的。

name: frontend
protocol: https

helm install --set port=443

Furthermore, the final .Values object is checked against all subchart schemas. This means that restrictions on a subchart can’t be circumvented by a parent chart. This also works backwards - if a subchart has a requirement that is not met in the subchart’s values.yaml file, the parent chart must satisfy those restrictions in order to be valid.

此外，最终的.Values对象会按照所有子chart的模式进行检查。这就以为着上层chart无法规则掉子Chart的限制。这也是逆向的-如果子Chart的values.yaml文件无法满足要求 ，上层chart必须满足这些限制才能生效。

References

When it comes to writing templates, values, and schema files, there are several standard references that will help you out.

编写模版，values，以及模式文件时，以下参考标准会有很大帮助

Custom Resource Definitions (CRDs)

Kubernetes provides a mechanism for declaring new types of Kubernetes objects. Using CustomResourceDefinitions (CRDs), Kubernetes developers can declare custom resource types.

k8s提供了一种声明k8s新类型对象的机制。通过使用CRDD,k8s开发者可以声明自定义资源类型

In Helm 3, CRDs are treated as a special kind of object. They are installed before the rest of the chart, and are subject to some limitations.

在helm3中，crd被当作一种特殊的对象来处理。CRD会在chart其他对象之前进行安装，被受到一些限制

CRD YAML files should be placed in the crds/ directory inside of a chart. Multiple CRDs (separated by YAML start and end markers) may be placed in the same file. Helm will attempt to load all of the files in the CRD directory into Kubernetes.

CRD yaml文件应该被放置在crds/目录下。多个Crd可以在一个文件中，helm会尝试将crd目录下的所有文件加载到k8s中。

CRD files cannot be templated. They must be plain YAML documents.

CRD文件无法被模板化，必须是普通的yaml文件

When Helm installs a new chart, it will upload the CRDs, pause until the CRDs are made available by the API server, and then start the template engine, render the rest of the chart, and upload it to Kubernetes. Because of this ordering, CRD information is available in the .Capabilities object in Helm templates, and Helm templates may create new instances of objects that were declared in CRDs.

当helm安装一个新的chart时，会上传CRD并阻塞，直到api应用完毕，该CRD可以访问，之后才启动模版引擎，渲染剩下的chart,将其上传到k8s。由于这种顺序性，crd信息可以在helm模版的.Capabilities对象获取到，helm模版会创建一个CRD中声明的新的对象的实例

For example, if your chart had a CRD for CronTab in the crds/ directory, you may create instances of the CronTab kind in the templates/ directory:

例如，如果在crds/包含一个CronTab的CRD文件，则可以在templates/目录下为其创建一个实例

crontabs/
  Chart.yaml
  crds/
    crontab.yaml
  templates/
    mycrontab.yaml

The crontab.yaml file must contain the CRD with no template directives:

crontab.yaml文件不能使用模版指令

kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com
spec:
  group: stable.example.com
  versions:
    - name: v1
      served: true
      storage: true
  scope: Namespaced
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab

Then the template mycrontab.yaml may create a new CronTab (using templates as usual):

然后模版可以为其创建一个实例

apiVersion: stable.example.com
kind: CronTab
metadata:
  name: {{ .Values.name }}
spec:
   # ...

Helm will make sure that the CronTab kind has been installed and is available from the Kubernetes API server before it proceeds installing the things in templates/.

helm会在安装模版文件之前确认对应资源安装成功并且k8s api可用。

Limitations on CRDs CRD限制

Unlike most objects in Kubernetes, CRDs are installed globally. For that reason, Helm takes a very cautious approach in managing CRDs. CRDs are subject to the following limitations:

  • CRDs are never reinstalled. If Helm determines that the CRDs in the crds/ directory are already present (regardless of version), Helm will not attempt to install or upgrade.
  • CRDs are never installed on upgrade or rollback. Helm will only create CRDs on installation operations.
  • CRDs are never deleted. Deleting a CRD automatically deletes all of the CRD’s contents across all namespaces in the cluster. Consequently, Helm will not delete CRDs.

Operators who want to upgrade or delete CRDs are encouraged to do this manually and with great care.

和k8s中的其他队列不同，crd是全局安装的。因为这个原因，helm在管理Crd时很谨慎。CRD对象受以下限制：

  1. CRD不会重复安装。如果helm检测到crd已经安装了，则不会尝试安装或更新
  2. CRD不会在升级或回滚时安装。helm只会在安装时创建CRD
  3. CRD不会被删除，自动删除CRD会删除集群中所有命名空间中的所有CRD内容，因此helm不会删除CRD

CRD需要操作员手动进行删除和更新

Using Helm to Manage Charts 使用helm管理chart

The helm tool has several commands for working with charts.

It can create a new chart for you:

$ helm create mychart
Created mychart/

Once you have edited a chart, helm can package it into a chart archive for you:

$ helm package mychart
Archived mychart-0.1.-.tgz

You can also use helm to help you find issues with your chart’s formatting or information:

可以使用helm来检查charts的格式或信息的问题

$ helm lint mychart
No issues found

Chart Repositories

A chart repository is an HTTP server that houses one or more packaged charts. While helm can be used to manage local chart directories, when it comes to sharing charts, the preferred mechanism is a chart repository.

Any HTTP server that can serve YAML files and tar files and can answer GET requests can be used as a repository server. The Helm team has tested some servers, including Google Cloud Storage with website mode enabled, and S3 with website mode enabled.

A repository is characterized primarily by the presence of a special file called index.yaml that has a list of all of the packages supplied by the repository, together with metadata that allows retrieving and verifying those packages.

On the client side, repositories are managed with the helm repo commands. However, Helm does not provide tools for uploading charts to remote repository servers. This is because doing so would add substantial requirements to an implementing server, and thus raise the barrier for setting up a repository.

Chart Starter Packs

The helm create command takes an optional --starter option that lets you specify a “starter chart”.

Starters are just regular charts, but are located in $XDG_DATA_HOME/helm/starters. As a chart developer, you may author charts that are specifically designed to be used as starters. Such charts should be designed with the following considerations in mind:

  • The Chart.yaml will be overwritten by the generator.
  • Users will expect to modify such a chart’s contents, so documentation should indicate how users can do so.
  • All occurrences of <CHARTNAME> will be replaced with the specified chart name so that starter charts can be used as templates.

Currently the only way to add a chart to $XDG_DATA_HOME/helm/starters is to manually copy it there. In your chart’s documentation, you may want to explain that process.