* A **Chart** is a folder or archive containing a _Chart.yaml_ file, a _templates/_ directory with one or more template files and supporting files, such as schemas and UI directives, and optionally a _README.md_ and _LICENSE_ file.
* A **chart** is a folder or archive containing a _Chart.yaml_ file, a _templates/_ directory with one or more template files, supporting files, such as schemas and UI directives, and optionally a _README.md_ and _LICENSE_ file.
* When a chart is **released**, it is tested, versioned, provenanced, and loaded into a chart repository.
* When a chart is **released**, it is tested, versioned, and loaded into a chart repository.
* A **Chart Repository** is organized according to the conventions of object storage. It is accessible by combining a domain with a repository ID (bucket), and can be browsed. A chart repository contains one or more versioned charts.
* A **chart repository** is organized according to the conventions of object storage. It is accessible by combining a domain with a repository ID (bucket), and can be browsed. A chart repository contains one or more versioned charts.
* There are three ways to reference charts. A **local reference** references a chart by relative or absolute file system path. It is intended for development. A **long name**, or fully qualified URL, refers to a released chart (in a chart repository) by URL. A **short name**, or mnemonic, is a shortened reference to a chart in a chart repository. A short name can be converted to a **long name** deterministically, and can therefore be used anywhere a long name can be used.
* There are three ways to reference charts. A **local reference** references a chart by relative or absolute file system path. It is intended for development. A **long name**, or fully qualified URL, refers to a released chart (in a chart repository) by URL. A **short name**, or mnemonic, is a shortened reference to a chart in a chart repository. A short name can be converted to a **long name** deterministically, and can therefore be used anywhere a long name can be used.
## Goals
## Goals
The goal of this proposal is to define the following aspects of Helm-DM charts:
The goal of this document is to define the following aspects of Helm charts:
* The **format of a Chart**
* The **format of a chart**
* The **layout of a Chart repository**, with recommendations about implementations
* The **layout of a chart repository**, with recommendations about implementations
* The format of a **short name** (mnemonic name) of a chart, as well as its fully qualified **long name**, and conventions for referencing local charts instead of short/long names.
* The format of a **short name** (mnemonic name) of a chart, as well as its fully qualified **long name**, and conventions for referencing local charts instead of short/long names.
...
@@ -66,19 +58,19 @@ We assume that we are developing a technology that will enjoy widespread use amo
...
@@ -66,19 +58,19 @@ We assume that we are developing a technology that will enjoy widespread use amo
* Advanced users may be interested in, and willing to, learn advanced features to build much more interesting charts
* Advanced users may be interested in, and willing to, learn advanced features to build much more interesting charts
Based on these, our design goal is to make it **easy to find, use, author, release, and maintain charts**, while still making it possible for advanced users to build sophisticated charts. Furthermore, we have begun the process of **attaching provenance to charts**.
Based on these, our design goal is to make it **easy to find, use, author, release, and maintain charts**, while still making it possible for advanced users to build sophisticated charts.
This design is based on the integration of Deployment Manager (DM) and Helm, formerly at github.com/deis/helm. It does not lose any of the functionality of DM, and loses only Helm functionality that we believe is disposable. Substantial portions of the chart and template handling logic from the original implementations of these two tools have changed as a result of this integration. The new chart format, described in this document, is one of the primary drivers of those changes.
We have attempted to build a proposal that does not lose any of the functionality of DM, and which loses only Helm functionality that we believe is disposable. But both tools will need to change substantial portions of their chart-handling logic.
### Non-Goals
This proposal doesn’t define how either the client or the server must use this data, though we make some non-normative recommendations (e.g. “this data may be displayed to the user” or “a suitable backend will be able to translate this to a fully qualified URL”).
### Non-Goals
This document does not define how either the client or the server must use this data, though we make some non-normative recommendations (e.g. “this data may be displayed to the user” or “a suitable backend will be able to translate this to a fully qualified URL”).
Consequently, this document does not describe the implementation of either client or server sides of this spec. While it defines the pieces necessary for developing and deploying a chart, it does not define a development workflow. Some considerations are listed in [Appendix B](#appendix-b-the-standard-chart-repository).
Consequently, this document does not describe the implementation of either client or server sides of this spec. While it defines the pieces necessary for developing and deploying a chart, it does not define a development workflow. Development workflows are discussed in [another document](../workflow/team-workflows.md).
## The Chart Format
## The Chart Format
Borrowing the nomenclature from Helm, we define a Chart as a bundle of data and metadata whose contents are sufficient for installing a workload into a Kubernetes cluster running DM.
We define a Chart as a bundle of data and metadata whose contents are sufficient for installing a workload into a Kubernetes cluster.
A Chart is composed of the following pieces:
A Chart is composed of the following pieces:
...
@@ -89,17 +81,13 @@ A Chart is composed of the following pieces:
...
@@ -89,17 +81,13 @@ A Chart is composed of the following pieces:
3. An optional `README.md` file
3. An optional `README.md` file
4. An optional `LICENSE` file
4. An optional `LICENSE` file
5. An optional `docs/` directory
5. An optional `docs/` directory
6. An optional `hooks/` directory
7. An optional `icon.svg`
7. An optional `icon.svg.`
A chart _may_ have other directories and files, but such files are not defined by or required by this proposal. For the purposes of this proposal, any additional files do not contribute to the core functionality of chart installation.
_Note: When a chart file is deployed, a [provenance file](#the-provenance-file) is generated for the chart. That file is not stored inside of the chart, but is considered part of the chart’s packaged format._
A chart _may_ have other directories and files, but such files are not defined by or required by this document. For the purposes of this document, any additional files do not contribute to the core functionality of chart installation.
The chart.yaml file format is described [later in this document](#the-chart-file).
The Chart.yaml file format is described [later in this document](#the-chart-file).
The `templates/` directory contains one or more template files, as defined in the [Directory Layout](#directory-layout) section. Templates, along with all of their supporting files, are located therein.
The `templates/` directory contains one or more template files, as defined in the [Directory Layout](#directory-layout) section. Templates, along with all of their supporting files, are located therein.
...
@@ -113,9 +101,6 @@ An optional `LICENSE` file may be present, which specifies license information f
...
@@ -113,9 +101,6 @@ An optional `LICENSE` file may be present, which specifies license information f
An optional `docs/` directory may be present, and may contain one or more documentation files. This directory contains documentation that is more specific, verbose, or thorough than what is present in the `README.md` file.
An optional `docs/` directory may be present, and may contain one or more documentation files. This directory contains documentation that is more specific, verbose, or thorough than what is present in the `README.md` file.
An optional `hooks/` directory may be present. **This is reserved for future use.** A deployment engine may specify lifecycle hooks, such as `pre-install`, `pre-render`, `post-install` and `post-render`. Lifecycle hooks provide an opportunity for a chart author to run additional steps in the processing pipeline. Implementations of these hooks are stored here. _No other files may be stored in this directory._
### Directory Layout
### Directory Layout
A chart is laid out as follows. The top level directory (represented by the placeholder ROOT) must be the name of the chart (verified by linter). For example, if the chart is named `nginx`, the ROOT directory must be named `nginx/`.
A chart is laid out as follows. The top level directory (represented by the placeholder ROOT) must be the name of the chart (verified by linter). For example, if the chart is named `nginx`, the ROOT directory must be named `nginx/`.
...
@@ -140,10 +125,7 @@ Templates are stored in a separate directory for the following reasons:
...
@@ -140,10 +125,7 @@ Templates are stored in a separate directory for the following reasons:
* It allows for the possibility that a chart definition may be embedded inside of project code.
* It allows for the possibility that a chart definition may be embedded inside of project code.
Charts must not assume that they can perform file system operations to load another chart or supporting resources directly via the filesystem, nor should they store any operational files outside of the chart directory. This point becomes important in the case where there is python/jinja or other executable code inside the chart. These executable components especially should not assume they can access the filesystem. It should be possible to archive the chart directory (e.g. `tar -cf ROOT.tar ROOT/`) and not lose any necessary information. A chart is an all-encompassing unit that can be processed by the client/server.
Charts must not assume that they can perform file system operations to load another chart or supporting resources directly via the filesystem, nor should they store any operational files outside of the chart directory. This point becomes important in the case where there is Python/Jinja or other executable code inside the chart. These executable components especially should not assume they can access the host filesystem. It should be possible to archive the chart directory (e.g. `tar -cf ROOT.tar ROOT/`) and not lose any necessary information. A chart is an all-encompassing unit that can be processed by the client/server.
### 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.
### The Chart File
### 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).
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).
...
@@ -155,30 +137,23 @@ A definition file does not specify anything about individual pieces of the defin
...
@@ -155,30 +137,23 @@ A definition file does not specify anything about individual pieces of the defin
Fields:
Fields:
* Name: A human-readable name of the definition. This may contain UTF-8 alphanumeric text, together with dash and underscore characters.
* name: A human-readable name of the definition. This may contain UTF-8 alphanumeric text, together with dash and underscore characters.
* Description: A human-readable description of the definition, not to exceed one paragraph of text. No text formatting is supported. A description may use any printable text characters allowed by the file format.
* description: A human-readable description of the definition, not to exceed one paragraph of text. No text formatting is supported. A description may use any printable text characters allowed by the file format.
* Version: A SemVer 2 semantic version of the chart (template files). Refer to the [instruction on semver.org](http://semver.org/).
* version: A SemVer 2 semantic version of the chart (template files). Refer to the [instruction on semver.org](http://semver.org/).
* Keywords: A list of human-readable keywords. A keyword may contain alphanumeric text and spaces.
* keywords: A list of human-readable keywords. A keyword may contain alphanumeric text and spaces.
* Maintainers: A list of author objects, where an author object has two properties:
* maintainers: A list of author objects, where an author object has two properties:
** Name: Author name
* name: Author name
** Email: Author email (optional)
* email: Author email (optional)
* Source: A URL to the source code for this chart
* source: A URL to the source code for this chart
* Home: A URL to the home page for the project
* home: A URL to the home page for the project
* Dependencies:
* expander: Indicates how to process the contents of templates/ (optional)
* Charts:
* name: The name of the expander, as a Kubernetes service name or URL.
* Name: definition name
* entrypoint: If the expander requires an entrypoint, gives the file (optional).
* Location: Full URL where definition can be found
* schema: The file used to validate the properties (user-configurable inputs) of this chart before expansion. (optional)
* Version: SemVer version range (e.g. ~1.2, `^2`, `>=4.1.1,<5.0.0`). If no version is present, fall back to the Location field (if this has a long name or short name, version info may be present). If there is no version there, use the latest version as found in the destination repository.
* Environment
* Name: Currently, always Kubernetes.
* Version: Version of Kubernetes required. SemVer version ranges are supported for this field (e.g. ~1.2).
* Extensions: List of extension names that are required (`extensions/v1beta1`). These should correspond to paths inside of the `apis/` endpoint on Kubernetes.
* APIGroups: List of API groups this chart requires in order to function.
```
Example:
Example:
```
name: nginx
name: nginx
description: The nginx web server as a replication controller and service pair.
description: The nginx web server as a replication controller and service pair.
version: 0.5.1
version: 0.5.1
...
@@ -189,27 +164,18 @@ keywords:
...
@@ -189,27 +164,18 @@ keywords:
* proxy
* proxy
source: https://github.com/foo/bar
source: https://github.com/foo/bar
home: http://nginx.com
home: http://nginx.com
depends:
expander:
charts:
name: goexpander-service
- name: memcached
schema: Schema.yaml
location: helm.sh/charts/memcached
version: 0.9.3
kubernetes:
version: “>=1.0.0”
extensions:
- extensions/v1beta1
```
```
#### Dependency Information
### Expanders and Templates
The chart format allows the specification of _runtime dependencies_ (not build-time dependencies). For example, a Wordpress chart might have a runtime dependency on a MySQL database. The database needn’t be present for processing the template file, but must be present in the cluster in order for Wordpress to function.
The content of the `templates/` directory and the schema file are defined by the particular expander invoked by name in the Chart.yaml file. Such expanders consume these files, in the context of properties, to generate content. If a schema is given, the expander may use it to validate the properties before expansion. Discussion of the available expanders and how they intepret the content of /templates is outside the scope of this document.
If no expander is specified, files with yaml or json extensions in the templates/ directory are parsed as Kubernetes API objects and included in the deployment without transformation. Charts may therefore contain Kubernetes API objects that do not contain any parameters or require any server side processing before being sent to Kubernetes. Such charts can therefore not invoke other charts.
Dependencies hold between charts. That is, one chart may depend upon another chart.
The resolution of dependencies is not covered in this proposal, as it is an implementation detail of the DM service.
### Releasing a Chart
### Releasing a Chart
A chart is _released_ when the source of the chart is tested, versioned, packaged into a gzipped tar file, and provenanced. Testing and provenancing attach badges to the Chart that attest to its quality and provenance. At that point, that particular release of a chart is considered immutable. No further changes are allowed. To enforce immutability through tamper detection, Charts must be digitally signed.
A chart is _released_ when the source of the chart is tested, versioned, packaged into a gzipped tar file. At that point, that particular release of a chart is considered immutable. No further changes are allowed. To enforce immutability through tamper detection, Charts must be digitally signed.
-> uploading to gs://kubernetes-charts/nginx-1.1.2.tgz
-> uploading to https://helm.sh/charts/nginx/1.1.2
-> done
-> done
```
```
## The Chart Repository
## The Chart Repository
A _Chart Repository_ is a place where _released copies_ of one or more charts may reside. (Unreleased charts are explicitly disallowed.) A Helm-DM Chart Repository is analogous to a Debian package repository or a Ruby Gems repository. It is a remote storage location accessible over a well-documented protocol (HTTP(S), and following fixed structural conventions.
A _Chart Repository_ is a place where _released copies_ of one or more charts may reside. A Helm Chart Repository is analogous to a Debian package repository or a Ruby Gems repository. It is a remote storage location accessible over a well-documented protocol (HTTP(S), and following fixed structural conventions.
Chart repositories are styled after the predominant pattern on[object storage systems](https://cloud.google.com/storage/docs/key-terms). A _domain_ hosts one or more _repositories_. A repository is a bucket in which one or more charts may be stored. In an object storage system, this is represented by the pattern: **https://domain/bucket/object**. In object storage, the _object_ part of the URL may contain slashes, hyphens, underscores, and dots. Thus in the URL [https://storage.googleapis.com/helm/nginx-1.1.2] the object is _nginx-1.1.2_. The general pattern of a chart repository is: https://domain/repository/chart
Chart repositories are styled after the predominant pattern of[object storage systems](https://cloud.google.com/storage/docs/key-terms). A _domain_ hosts one or more _repositories_. A repository is a bucket in which one or more charts may be stored. In an object storage system, this is represented by the pattern: **https://domain/bucket/object**. In object storage, the _object_ part of the URL may contain slashes, hyphens, underscores, and dots. Thus in the URL [https://storage.googleapis.com/helm/nginx-1.1.2] the object is _nginx-1.1.2_. The general pattern of a chart repository is: https://domain/repository/chart
A chart name should be of the form _name-version.ext_, where _name_ is the chart name (alpha-numeric plus dash and underscore), and version is a SemVer v2 version. The extension, _ext_, should reflect the type of compression used to archive the object. This specification only discusses gzipped tar archives, but other mechanisms could be supported.
A chart name should be of the form _name-version.ext_, where _name_ is the chart name (alpha-numeric plus dash and underscore), and version is a SemVer v2 version. The extension, _ext_, should reflect the type of compression used to archive the object. This specification only discusses gzipped tar archives, but other mechanisms could be supported.
Every release should have an accompanying provenance (_.prov_) file. Its name should be exactly the same as the versioned file, but with the prov extension.
Because of the way object storage systems work, a repository should be viewable as a directory tree:
Because of the way object storage systems work, a repository should be viewable as a directory tree:
```
```
https://helm.sh/charts/
gs://kubernetes-charts/charts/
apache-2.3.4.tgz
apache-2.3.4.tgz
apache-2.3.4.prov
nginx-1.1.1.tgz
nginx-1.1.1.tgz
nginx-1.1.1.prov
nginx-1.1.2.tgz
nginx-1.1.2.tgz
nginx-1.1.2.prov
redis-0.4.0-alpha.1.tgz
redis-0.4.0-alpha.1.tgz
redis-0.4.0-alpha.1.prov
```
```
A helm chart is a gzip-compressed tar archive (e.g. `tar -zcf …`). Each chart has an accompanying signature that provides a signed representation of the Chart.yaml file. This is for cryptographic verification and provenance information.
A helm chart is a gzip-compressed tar archive (e.g. `tar -zcf …`).
### The Provenance File
The provenance file contains a chart’s YAML file plus several pieces of verification information. Provenance files are designed to be automatically generated.
The following pieces of provenance data are added:
* The chart file (Chart.yaml) is included to give both humans and tools an easy view into the contents of the chart.
* Every image file that the project references is checksummed (SHA-256?), and the sum included here. If two versions of the same image are used by the template, both checksums are included.
* The signature (SHA-256) of the chart package (the .tgz file) is included, and may be used to verify the integrity of the chart package.
* The entire body is signed using PGP (see [http://keybase.io] for an emerging way of making crypto signing and verification easy).
The combination of this gives users the following assurances:
* The images this chart references at build time are still the same exact version when installed (checksum images).
* This is distinct from asserting that the image Kubernetes is running is exactly the same version that a chart references. Kubernetes does not currently give us a way of verifying this.
* The package itself has not been tampered with (checksum package tgz).
* The entity who released this package is known (via the GPG/PGP signature).
The format of the file is as follows:
```
-----BEGIN PGP SIGNED MESSAGE-----
name: nginx
description: The nginx web server as a replication controller and service pair.
Note that the YAML section contains two documents (separated by ---\n). The first is the Chart.yaml. The second is the checksums, defined as follows.
* Files: A map of filenames to SHA-256 checksums (value shown is fake/truncated)
* Images: A map of image URLs to checksums (value shown is fake/truncated)
The signature block is a standard PGP signature, which provides [tamper resistance](http://www.rossde.com/PGP/pgp_signatures.html).
### Repository Protocol
### Repository Protocol
A repository must implement HTTP(S) GET operations on both chart names (nginx-1.2.3) and chart signatures (nginx-1.2.3.sig). HTTP GET is a rational base level of functionality because it is well understood, nearly ubiquitous, and simple.
A repository must implement HTTP(S) GET operations on both chart names (nginx-1.2.3) and chart signatures (nginx-1.2.3.sig). HTTP GET is a rational base level of functionality because it is well understood, nearly ubiquitous, and simple.
...
@@ -333,7 +227,7 @@ A repository may implement the full Object Storage APIs for compatibility with S
...
@@ -333,7 +227,7 @@ A repository may implement the full Object Storage APIs for compatibility with S
Object storage is a rational choice for this model because it is [optimized for highly resilient, distributed, highly available read-heavy traffic](https://en.wikipedia.org/wiki/Object_storage). The S3-like API has become a de facto standard, with myriad client libraries and tools, and major implementations both as services (S3, GCS), platforms (OpenStack Swift), and individual stand-alone servers (RiakCS, Minio, Ceph).
Object storage is a rational choice for this model because it is [optimized for highly resilient, distributed, highly available read-heavy traffic](https://en.wikipedia.org/wiki/Object_storage). The S3-like API has become a de facto standard, with myriad client libraries and tools, and major implementations both as services (S3, GCS), platforms (OpenStack Swift), and individual stand-alone servers (RiakCS, Minio, Ceph).
This proposal does not mandate a particular authentication mechanism, but implementors may implement the authentication token mechanisms on GCS and S3 compatible object storage systems.
This document does not mandate a particular authentication mechanism, but implementors may implement the authentication token mechanisms on GCS and S3 compatible object storage systems.
### Aside: Why a Flat Repository Namespace?
### Aside: Why a Flat Repository Namespace?
The format for a repository has packages stored in a flat namespace, with version information appended to the filename. There are a few reasons we opted for this over against more hierarchical directory structures:
The format for a repository has packages stored in a flat namespace, with version information appended to the filename. There are a few reasons we opted for this over against more hierarchical directory structures:
...
@@ -347,7 +241,7 @@ The format for a repository has packages stored in a flat namespace, with versio
...
@@ -347,7 +241,7 @@ The format for a repository has packages stored in a flat namespace, with versio
* Brevity is desirable when developers have occasion to type these URLs directly, as is done in chart/template references (see, for example, the [S3 API](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingObjects.html)).
* Brevity is desirable when developers have occasion to type these URLs directly, as is done in chart/template references (see, for example, the [S3 API](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingObjects.html)).
### Aside: Why Not Git(Hub) or VCS?
### Aside: Why Not Git(Hub) or VCS?
In their first incarnations, both Helm and DM used GitHub-backed repositories for released charts. The Helm team believes we made a huge mistake by going this route. This method suffers from some severe limitations (listed below). The proposal above is designed to work around those limitations.
GitHub-backed repositories for released charts suffer from some severe limitations (listed below). Our repository design does not have these limitations.
* Versioning Multiple Things
* Versioning Multiple Things
...
@@ -356,7 +250,7 @@ In their first incarnations, both Helm and DM used GitHub-backed repositories fo
...
@@ -356,7 +250,7 @@ In their first incarnations, both Helm and DM used GitHub-backed repositories fo
* Developer Experience
* Developer Experience
* Combining release artifacts and source code causes confusion
* Combining release artifacts and source code causes confusion
* Substantial development workflow overhead (and over-reliance on conventions) make directory-based versioning problematic
* Substantial development workflow overhead (and over-reliance on conventions) make directory-based versioning problematic
* In most of the models specified, there is no way of determining whether a resource is the in development, or is complete
* In most of the models specified, there is no way of determining whether a resource is in development, or is complete
* Infrastructure
* Infrastructure
* Both teams have hit GitHub API rate limiting
* Both teams have hit GitHub API rate limiting
* Git is optimized for fetching an entire repository, not a small fraction of the repository
* Git is optimized for fetching an entire repository, not a small fraction of the repository
...
@@ -394,7 +288,7 @@ The following URI schemes must be supported:
...
@@ -394,7 +288,7 @@ The following URI schemes must be supported:
#### Special Form Google Storage and S3
#### Special Form Google Storage and S3
The [Google Storage scheme](https://cloud.google.com/storage/docs/interoperability)(`gs://`) and the S3 scheme (`s3://`) can also be support. These forms do not follow the URL standard (bucket name is placed in the host field), but their behavior is well-documented.
The [Google Storage scheme](https://cloud.google.com/storage/docs/interoperability)(`gs://`) and the S3 scheme (`s3://`) can also be supported. These forms do not follow the URL standard (bucket name is placed in the host field), but their behavior is well-documented.
Examples:
Examples:
...
@@ -412,7 +306,13 @@ A generic short form maps to an object storage reference (`DOMAIN/REPOSITORY/REL
...
@@ -412,7 +306,13 @@ A generic short form maps to an object storage reference (`DOMAIN/REPOSITORY/REL
helm:example.com/charts/nginx-1.2.3.tgz
helm:example.com/charts/nginx-1.2.3.tgz
```
```
For the purpose of providing versioning ranges, and also for backward compatibility, version requirements may be treated as as suffix condition, instead of part of the path:
Or, in the case of the Google Storage (`gs://`) and the S3 scheme (`s3://`), the domain indicates the storage scheme.
```
helm:gs/kubernetes-charts/nginx-1.2.3.tgz
```
For the purpose of providing versioning ranges, and also for backward compatibility, version requirements are expressed as a suffix condition, instead of as part of the path:
```
```
helm:example.com/charts/nginx#1.2.3 // Exact version
helm:example.com/charts/nginx#1.2.3 // Exact version
...
@@ -446,105 +346,7 @@ Legal examples of this include:
...
@@ -446,105 +346,7 @@ Legal examples of this include:
Unprefixed relative paths are not valid. For example, `foo/` is not allowed as a local path, as it conflicts with a legal short name, and is thus ambiguous.
Unprefixed relative paths are not valid. For example, `foo/` is not allowed as a local path, as it conflicts with a legal short name, and is thus ambiguous.
## References
## Appendix A: User Stories for Charts
Personas:
- Operator: Responsible for running an application in production.
- Service Dev: Responsible for developing new definitions
- App Dev: Developer who creates applications that make use of existing definitions, but does not create definitions.
Stories:
- As an operator, I want a build that is 100% reproducible (exact versions)
- As an app dev, I want to be able to search for chart definitions using keys definied in the [chart file](#the-chart-file)...
* by keyword, where one app may have multiple keywords (e.g. Redis has storage, message queue)
* by name (meaning name of the chart), where name may be "fuzzy".
* by author
* by last updated date
- As a service dev, I want a well-defined set of practices to follow
- As a service dev, I want to be able to work with a team on the same definition
- As a service dev, I want to be able to indicate when a particular definition is stable, and how stable it is
- As a service dev, I want to indicate the role I played in building a definition
- As a service dev, I want to be able to use all of the low-level Kubernetes kinds
- As an operator, I want to be able to determine how stable a package is
- As an operator, I want to be able to determine what version of Kubernetes I need to run a definition
- As an operator, I want to determine whether a definition requires extension kinds (e.g. DaemonSet or something custom), and determine this _before_ I try to install
- As a service dev, I want to be able to express that my definition depends on others, even to the extent that I specify the version or version range of the other definition upon which I depend
- As a service dev, I do not want to install additional tooling to write, test, or locally run a definition (this relates to the file format in that the format should not require additional tooling)
- As a service dev, I want to be able to store auxiliary files of arbitrary type inside of a definition (e.g. a PDF with documentation, or a logo for my product)
- As a service dev, I want to be able to store my definition in one repository, but reference a definition in another repository
- As a service dev, I want to embed my template inside of the code that it references. For example, I want to have the code to build a docker image and the definition to all live in the same source code repository.
## Appendix B: The Standard Chart Repository
We have talked about adding a standard (default) chart repository that we are the gatekeepers on. This would hold only curated/vetted charts over which we have control. The following table illustrates how we’re thinking about implementing this:
_Note: When a chart file is deployed, a [provenance file](#the-provenance-file) is generated for the chart. That file is not stored inside of the chart, but is considered part of the chart’s packaged format._
Testing and provenancing attach badges to the Chart that attest to its quality and provenance.
### The Provenance File
The provenance file contains a chart’s YAML file plus several pieces of verification information. Provenance files are designed to be automatically generated.
The following pieces of provenance data are added:
* The chart file (Chart.yaml) is included to give both humans and tools an easy view into the contents of the chart.
* Every image file that the project references is checksummed (SHA-256?), and the sum included here. If two versions of the same image are used by the template, both checksums are included.
* The signature (SHA-256) of the chart package (the .tgz file) is included, and may be used to verify the integrity of the chart package.
* The entire body is signed using PGP (see [http://keybase.io] for an emerging way of making crypto signing and verification easy).
The combination of this gives users the following assurances:
* The images this chart references at build time are still the same exact version when installed (checksum images).
* This is distinct from asserting that the image Kubernetes is running is exactly the same version that a chart references. Kubernetes does not currently give us a way of verifying this.
* The package itself has not been tampered with (checksum package tgz).
* The entity who released this package is known (via the GPG/PGP signature).
The format of the file is as follows:
```
-----BEGIN PGP SIGNED MESSAGE-----
name: nginx
description: The nginx web server as a replication controller and service pair.
- Operator: Responsible for running an application in production.
- Chart Dev: Responsible for developing new charts
- App Dev: Developer who creates applications that make use of existing charts, but does not create charts.
Stories:
- As an operator, I want a deployment that is 100% reproducible (exact versions)
- As an app dev, I want to be able to search for charts using keys defined in the [chart file](#the-chart-file)...
* by keyword, where one app may have multiple keywords (e.g. Redis has storage, message queue)
* by name (meaning name of the chart), where name may be "fuzzy".
* by author
* by last updated date
- As a chart dev, I want a well-defined set of practices to follow
- As a chart dev, I want to be able to work with a team on the same chart
- As a chart dev, I want to be able to indicate when a particular chart is stable, and how stable it is
- As a chart dev, I want to indicate the role I played in building a chart
- As a chart dev, I want to be able to use all of the low-level Kubernetes kinds
- As an operator, I want to be able to determine how stable a package is
- As an operator, I want to be able to determine what version of Kubernetes I need to run a chart
- As an operator, I want to determine whether a chart requires extension kinds (e.g. DaemonSet or something custom), and determine this _before_ I try to install
- As a chart dev, I want to be able to express that my chart depends on others, even to the extent that I specify the version or version range of the other chart upon which I depend
- As a chart dev, I do not want to install additional tooling to write, test, or locally run a chart (this relates to the file format in that the format should not require additional tooling)
- As a chart dev, I want to be able to store auxiliary files of arbitrary type inside of a chart (e.g. a PDF with documentation)
- As a chart dev, I want to be able to store my chart in one repository, but reference a chart in another repository
- As a chart dev, I want to embed my template inside of the code that it references. For example, I want to have the code to build a docker image and the chart to all live in the same source code repository.
The _Helm Official_ project focuses on maintaining a repository of high-quality production-ready charts. Charts may be contributed by anyone in the broad community, and they are vetted and maintained by the Helm Official core contributors.
The _Helm Official_ project focuses on maintaining a repository of high-quality production-ready charts. Charts may be contributed by anyone in the broad community, and they are vetted and maintained by the charts-maintainers team in the Github Kubernetes organization.
