Helm~Charts【未完成】

Charts

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.
Charts are created as files laid out in a particular directory tree. They can be packaged into versioned archives to be deployed.
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.
This document explains the chart format, and provides basic guidance for building charts with Helm.

Charts

Helm使用一种称为chart的打包格式.一个chart是藐视一些相关kubernetes资源的文件的集合.一个单独的chart可以被用于不是一些简单的,例如memcached pod,也可以是复杂的,例如一整个web应用栈包括HTTP服务,数据库,缓存和其他.
chart被按照特定目录的布局来创建文件.他们被打包成带版本的存档.
如果你想不安装一个发布了的chart而只是下载下来查看文件,你可以使用helm pull chartrepo/chartname.
这份文档解释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:

wordpress/
  Chart.yaml          # A YAML file containing information about the chart
  LICENSE             # OPTIONAL: A plain text file containing the license for the chart
  README.md           # OPTIONAL: A human-readable README file
  values.yaml         # The default configuration values for this chart
  values.schema.json  # OPTIONAL: A JSON Schema for imposing a structure on the values.yaml file
  charts/             # A directory containing any charts upon which this chart depends.
  crds/               # Custom Resource Definitions
  templates/          # A directory of templates that, when combined with values,
                      # will generate valid Kubernetes manifest files.
  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.

chart文件结构

一个chart是一个文件里被组织的一些文件.这个文件夹的名字是chart的名字(没有版本信息).因此,一个描述WordPress的chart应该被存放在wordpress文件夹.
在这个文件夹里面,helm期望下面的结构

wordpress/
  Chart.yaml          # 一个包含chart信息的yaml文件
  LICENSE             # 可选:包含chart许可的普通文本
  README.md           # 可选:一个人类可读的README文件
  values.yaml         # 这个chart的默认配置值
  values.schema.json  # 可选:一个规定values.yaml结构的json格式
  charts/             # 一个包含任何这个chart依赖的chart的文件夹
  crds/               # 用户资源的定义
  templates/          # 一个模板文件夹,当带入值之后会生成kubernetes文件
  templates/NOTES.txt # 可选:包好简要使用说明的纯文本

The Chart.yaml File

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

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.

chart.yaml文件

一个chart需要一个Chart.yml文件,它有以下字段

apiVersion: chart api的版本 (必须有)
name: chart的名字(必须有)
version: 结构化语意的版本 (必须有)
kubeVersion:兼容的kubernetes的版本 (可选)
description: 这个项目的一句话描述 (可选)
type: 这个chart的类型 (可选)
keywords:
  - 这个项目的一组关键词 (可选)
home: 这个项目的URL (可选)
sources:
  - 这个项目的源代码URL列表 (可选)
dependencies: # chart所依赖的列表(可选)
  - name: chart的名字 (nginx)
    version: chart的版本 ("1.2.3")
    repository: (可选)仓库的URL ("https://example.com/charts") 或者别名 ("@repo-name")
    condition: (可选)一个yaml里的boolean值,用于启用/禁用chart (比如subchart1.enabled )
    tags: # (可选)
      - 对于对chart分组从而一起启用/禁用
    import-values: # (可选)
      - 引入值用于将父级字段的值映射进来,每一项可以是一个字符串或者是一对子/父列表项
    alias: (可选) 别名在多次添加同一个chart时非常有用
maintainers: # (可选)
  - name: 维护者的姓名(需要每一个维护者的姓名)
    email: 维护者的邮箱 (对于每一个维护者可选)
    url: 维护者的URL (对于每一个维护者可选)
icon:一个SVG或者PNG格式的图片用来做图标 (可选).
appVersion:它所包含的应用的版本 (可选). 不要求是结构化语言版本. 建议使用引号.
deprecated: 这个chart是否被废弃 (可选, boolean类型)
annotations:
  example: 以名字作为键的批注列表 (可选).

其他的字段会被忽略

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:

nginx-1.2.3.tgz

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.

chart和version字段

每个chart都必须有版本号,一个版本号必须遵循结构化语言版本规则.不同于传统的Helm,v2版本以及以后的Helm版本使用版本号作为发布标记.仓库里使用名字加版本作为唯一标识.
例如,一个版本设置为version:1.2.3nginx的chart会被命名为

nginx-1.2.3.tgz

更复杂的结构化语意名字也被支持,例如version: 1.2.3-alpha.1+ef365,但是系统不允许非结构化语意的名字.
注意:即使传统的Helm和部署管理器都非常依赖GitHub,Helm的v2及以后的版本不再要求GitHub或Git.所以根本不再使用Git的SHA作为版本.
Chart.yml里的version字段用于很多Helm工具中,包括命令行界面.当生成一个包时,helm package指令会使用它在Chart.yml里找到的版本号作为这个包名的令牌.系统假设chart包名的版本号与Chart.yml里的版本号一致.不满足这一点将会导致错误.

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).

apiVersion字段

对于Helm3而言至少要求apiVersion字段应该是v2.chart支持之前设置apiVersion为v1的helm版本,但是仍然被Helm2来安装.
将v1改为v2

• 一个定义依赖的dependances字段,对于v1的chart而言它们在requirements.yaml里(参见chart依赖)
• type字段,区分chart是应用还是库(参见chart类型)

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.

appVersion字段

注意appVersion和version字段没有关系.它是知名应用的版本的方式.例如Drupal的chart可能appVersion是"8.2.1"指明这个chart(默认)里的Drupal的版本时8.2.1.这个字段是一些信息,对于chart版本的计算没有影响.建议将版本用引号括起来.它强制yaml解析器将版本号作为一个字符串.不加引号将在某些情况导致解析问题.例如yaml将1.0作为浮点值,或者一个git提交的sha例如1234e10作为科学计数法.
从helm3.5.0之后,helm create默认会将appVersion放入引号.

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

>= 1.13.0 < 1.15.0

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.

kubeVersion字段

可选字段kubeVersion可以定义支持的kubernetes版本.当安装chart时Helm将检查版本限制并在kubernetes的版本不支持时失败.
版本限制通过空格分隔并如下方式比较

>= 1.13.0 < 1.15.0

它们也可以通过或操作符如下来合并

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

在这个例子中1.14.0没有包含,可能是因为指导有bug的版本从而阻止chart不能正常运行.
版本限制除了使用=,!=,>,<,>=,<=这些符号,下列缩记符号也被支持

• 划线表示闭区间,例如1.1 - 2.3.4等同于>=1.1 <=2.3.4
• 通配符x,X,*,例如1.2.x等同于>=1.2.0 <1.3.0
• 波浪号~(补丁版本被允许),例如~1.2.3等同于>=1.2.3 <1.3.0
• 插入符^(小版本变更允许),例如^1.2.3等同于>=1.2.3 <2.0.0

关于结构化版本的更多细节解释参见结构化版本

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

当管理chart仓库里的chart时,有事需要废弃一个chart.在Chart.yml里的可选字段deprecated可以用于标记一个chart是被废弃的.如果一个chart的最新版本被标记废弃了,那么这个chart整个就被废弃了.这个chart的名字后面就可以在发布一个没有标记废弃的新版本时重用.废弃chart的流程如下:

1. 更新chart的Chart.yaml文件标记chart被废弃了,挤掉这个版本
2. 发布一个新的chart版本到chart仓库
3. 从源代码仓库(例如git)里移除这个chart

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类型

type字段定义了chart的类型,有两种类型:应用和库.应用是默认的类型并且他是能被整个操作的标准chart.库类型chart提供了构建chart的工具或功能.一个库chart不同于一个应用chart因为它不能被安装并且通常不包含任何资源.
注意:一个应用chart可以当做库chart来使用.通过将类型设置为库即可.这个chart将会被当做库chart对待所以所有的工具和功能将保留但是所有资源对象不生效.

Chart LICENSE, README and NOTE

Charts can also contain files that describe the installation, configuration, usage and license of a 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

When hubs and other user interfaces display details about a chart that detail is pulled from the content in the README.md file.
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.

LICENSE,README和NOTES文件

chart包含一些描述安装,配置,使用和许可的文件
LICENSE文件是包含这个chart许可证的普通文本.因为模板里不只是配置还有编码逻辑所以chart能包含一个许可.如果需要的话,也可以为chart安装的应用提供独立的许可.
一个chart的README文件应该是Markdown格式(README.md)并且一般应当包含一些内容

• chart提供的应用或服务的描述
• 运行chart的前置条件或依赖
• 对value.yaml及默认值的描述
• 安装或配置chart的任何其他相关信息

当仓库和其他用户界面展示chart的细节信息时将从README.md文件中获取内容.
chart同时还有一个简单的普通文本文件templates/NOTES.txt,他将在安装后被显示或者查看发布的状态的时候.这个文件也被当成模板来对待.并被用作显示使用信息,下一步或者任何其他发布的相关信息.例如,连接一个数据库或者登录一个web页面的指引.因为这个文件是运行helm install和helm status时输出到控制台,所以建议它只包含简短的信息并指向README来获取更多的细节

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.

chart依赖

在helm中,一个chart可以依赖任意数量的其他chart,这些依赖使用Chart.yml里dependancies字段动态链接或者带入charts/文件夹并被手工管理.

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 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:

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

使用dependencies字段管理依赖

当前chart依赖的chart定义为一个列表存放在dependencies字段

dependencies:
  - name: apache
    version: 1.2.3
    repository: https://example.com/charts
  - name: mysql
    version: 3.2.1
    repository: https://another.example.com/charts

• name字段是你想要的chart的名字
• version字段是你想要的chart的版本
• repository字段是chart仓库的完整URL.注意你必须使用helm repo add添加到本地仓库
• 你可以使用仓库的名字来代替URL

$ helm repo add fantastic-charts https://fantastic-charts.storage.googleapis.com

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

一旦你定义了依赖,你可以运行helm dependancy update来使用依赖文件为你下载所有指定的chart到==chart/==文件夹

$ 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

当时用helm dependancy update获取chart后,他将把这些chart用档案的形式存储在==charts/==文件夹.比如上面的例子,将会在chart文件夹里看到以下文件

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).

# 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.

dependancies中的alias字段

除了上面的字段,每个依赖项可以包含一个可选字段alias
对一个依赖的chart添加一个别名,可以把一个chart放入dependencies中使用别名作为新依赖的名字.
可以使用别名当需要使用其他的名字访问一个chart时

# 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

在上面的例子对于parentchart有三个依赖

subchart
new-subchart-1
new-subchart-2

手工方式完成可以通过复制/黏贴

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.

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.

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.

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:

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.

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)
Release.Namespace: The namespace the chart was released to.
Release.Service: The service that conducted the release.
Release.IsUpgrade: This is set to true if the current operation is an upgrade or rollback.
Release.IsInstall: This is set to true if the current operation is an install.
Chart: The contents of the Chart.yaml. Thus, the chart version is obtainable as Chart.Version and the maintainers are in 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 }}
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” }})
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.

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

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:

$ 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:

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

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.

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

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

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

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:

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.

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.

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

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.

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:

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.

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.

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

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:

{
“$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:

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:

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.

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.

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

Go templates
Extra template functions
The YAML format
JSON Schema
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.

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.

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 files cannot be templated. They must be plain YAML documents.

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.

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:

crontabs/
Chart.yaml
crds/
crontab.yaml
templates/
mycrontab.yaml
The crontab.yaml file must contain the CRD with no template directives:

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/.

Limitations on CRDs
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.

Using Helm to Manage Charts
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 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 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.