@ -144,113 +144,6 @@ Charts must not assume that they can perform file system operations to load anot
### Generators and Templates
The contents inside of the `templates/` directory may contain directives that can be processed by an external processor. Such a processor may read these files and generate new content.
A generator reads through the files in `templates/` and looks for special file headers that indicate what generation tool needs to be run (if any) on a file. One such implementation of a generation tool is a template renderer. In any one pass through the `templates/` directory, more than one generation tool may be invoked.
#### The Generator Header
A file that requires a generation tool must declare this on the first line of the file using one of the following syntaxes:
```
//helm:generate TOOL [ARGS]\n
#helm:generate TOOL [ARGS]\n
/*helm:generate TOOL [ARGS]*/
```
`TOOL` corresponds to a registered tool name (see [this proposal](https://github.com/kubernetes/kubernetes/pull/18215#issuecomment-168885511)). `[ARGS]` are zero or more space-separated strings that will be passed unmodified to the tool. The first two formats require a terminating line feed. The third format requires a terminating `*/` sequence.
**Example:**
```
#helm:generate dm_template
{% set PROPERTIES = properties or {} %}
{% set WORKERS = PROPERTIES['workers'] or 2 %}
resources:
- name: spark-master
type: ReplicationController
properties:
kind: ReplicationController
apiVersion: v1
metadata:
name: spark-master-controller
spec:
…
```
In the example above, the `#helm:generate dm_template` indicates that the remainder of the file contents should be processed using whatever handler is registered for handling `dm_template`.
Generator tools may take arguments. No format is specified for arguments. For example, one might use UNIX-like flags.
```
#helm:generate dm_template --ignore-timezone -s
{% set PROPERTIES = properties or {} %}
{% set WORKERS = PROPERTIES['workers'] or 2 %}
resources:
- name: spark-master
type: ReplicationController
properties:
kind: ReplicationController
apiVersion: v1
metadata:
name: spark-master-controller
spec:
…
```
Any arguments are passed into the generator unaltered. Generators may ignore arguments that they do not support or understand.
A generator tool _must_ not overwrite any files (including itself) present in the chart’s `templates/` directory. It must not alter the `README.md`, the `LICENSE`, the `Chart.yaml`, or the contents of the `hooks/` directory. These restrictions maintain the reproducibility of the build over subsequent generator runs.
One common form of generator tool is a template renderer. Such a tool takes a template (and possibly other supporting files) as input, processes the template, and outputs one or more generated files or data streams. The location of output is not specified by this proposal (though it is subject to the caveats above).
An implementation of this specification may support any number of template engines. However, two are explicitly defined: Python/Jinja templates (formerly DM Templates), and simple Go templates (formerly Helm Templates).
#### Python/Jinja Templates (aka DM Templates)
Python/Jinja templates, [defined here](https://github.com/kubernetes/deployment-manager/blob/master/docs/design/design.md), have been supported since DM’s inception. The only amendment this proposal makes to the existing format is that template and Python files must have `helm:generate` headers to be processed. (Schema files do not need generate headers because no operations are run directly on these files.)
The reserved generator name for such templates is `dm_template`.
#### Go Templates (formerly Helm Templates)
Helm 0.3 and later supported Go templates, [defined here](https://github.com/helm/helm/blob/master/docs/generate-and-template.md). The only change this proposal makes to the existing specification is that templates must include the form of the `helm:generate` header elaborated here.
The reserved generator name for such templates is `go_template`.
Example:
The following simple manifest (`manifests/secret.yaml`) declares a secret that is randomly generated. The Go template directive is bolded.
```
#helm:generate go_template
apiVersion: v1
kind: Secret
metadata:
name: builder-key-auth
namespace: deis
labels:
heritage: deis
type: Opaque
data:
builder-key: {{ randAscii 64 | b64enc }}
```
The above generates a 64 character random ASCII string and then base-64 encodes it.
### The Chart File
The `Chart.yaml` file specifies package metadata for the definition. Package metadata is any information that explains the package structure, purpose, and provenance. Its intended audience is tooling that surfaces such information to the user (e.g. a command line client, a web interface, a search engine).
Michelle Noorali
9 years ago