-
Notifications
You must be signed in to change notification settings - Fork 177
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
29 additions
and
87 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,121 +1,63 @@ | ||
| --- | ||
| hip: "9999" | ||
| title: "Helm OCI MediaType Registration" | ||
| authors: [ "Andrew Block <andy.block@gmail.com>" ] | ||
| created: "2022-06-09" | ||
| type: "informational" | ||
| title: "Helm Release Tag" | ||
| authors: [ "Nicholas Colbert <45cali@gmail.com>" ] | ||
| created: "2022-08-03" | ||
| type: "feature" | ||
| status: "draft" | ||
| --- | ||
|
|
||
| ## Abstract | ||
|
|
||
| The use of OCI artifacts is one of the packaging methods available in Helm. A Helm OCI artifact is comprised of multiple component, each defined by a specific Media Type. Media Types are managed by the [Internet Assigned Numbers Authority (IANA)](https://www.iana.org) and each type should be registered with IANA so that it can not only be known by the organization, but also discoverable by end users. The canonical location for Helm Media Types information below is intended to be the IANA [application registry](https://www.iana.org/assignments/media-types/media-types.xhtml#application). This document describes the necessary fields that are associated within the [registration of a Media Type to IANA](https://www.iana.org/form/media-types) form. | ||
| Add an optional release-tag flag for when deploying a helm chart. | ||
|
|
||
| ## Motivation | ||
|
|
||
| Support for the storage of Helm charts as OCI artifacts was released in released in General Availability (GA) in version 3.8.0 and with the continued adoption of this storage format, the specifications should be readily available for producers and consumers. Registration of Media Types with the Internet Assigned Numbers Authority has become a standard process within other technologies whom also make use of OCI artifacts so that not only the packaging types can be understood, but also documented. | ||
| Many organizations write a helm chart that they use internally and is not tied to any specific source code. This makes the appVersion in the Chart.yaml file useless because it never gets updated. In addition, appVersion cannot be changed easily on the fly. Adding a release-tag flag for `helm install` and `helm upgrade` gives users the ability to add in important information about the deployment. For example If you need to do a helm rollback to a specific version, its currently difficult to figure out what commit or branch you should rollback to. | ||
|
|
||
| ## Rationale | ||
|
|
||
| A Generally Available (GA) feature that implements a particular specification should account for its usage. Not only does the registration of Media Types to IANA follow a practice that has been implemented previously, but also provides a better understanding of the Helm project. | ||
| Add a `--release-tag` flag to `helm install` and `helm upgrade` and give `Release Tag` its own column for the `helm history` command. The flag should be optional and not required. | ||
|
|
||
| ## Specification | ||
|
|
||
| Each Media Type that Helm implements requires their own separate registration to IANA. The sections below detail the properties associated within the registration form for each of the Media Type's that will be submitted to IANA. | ||
|
|
||
| ### Helm Config | ||
|
|
||
| The [OCI config](https://github.com/opencontainers/image-spec/blob/main/config.md) containing a JSON formatted representation of the Helm `Chart.yaml` file. | ||
|
|
||
| | | ||
| ------ | ----- | ||
| | Type Name | application | | ||
| | Tree | Vendor Tree (vnd prefix) | | ||
| | Subtype Name | `cncf.helm.config.v1+json` | | ||
| | Required Parameters | Fields as required per the Chart.yaml definition | | ||
| | Optional Parameters | Remaining fields which as defined within the Chart.yaml definition which are not noted as required | | ||
| | Encoding Considerations | Encoding considerations are identical to those specified for the "application/json" media type. See [RFC8259](https://datatracker.ietf.org/doc/html/rfc8259). | | ||
| | Security Considerations | Similar security concerns common to all JSON content types. See [RFC 7159 Section #12](https://tools.ietf.org/html/rfc7159#section-12) for additional information. The included content as defined by the Helm chart definition may include sensitive assets including personal contact information, source code repositories or other referenceable locations. | | ||
| | Interoperability Consideration | N/A | | ||
| | Published specification | [https://helm.sh/docs/topics/charts/#the-chartyaml-file](https://helm.sh/docs/topics/charts/#the-chartyaml-file) | | ||
| | Application Usage | Internally within the Helm package manager as well as various interfacing applications | | ||
| | Fragment Identifier Considerations | N/A | | ||
| | Restrictions on Usage | N/A | | ||
| | Provisional Registrations | N/A | | ||
| | Additional Information | <ol><li>Deprecated alias names for this type: None</li><li>Magic number(s): None</li><li>File extension(s): .json</li><li>Macintosh file type code: TEXT</li><li>Object Identifiers: None</li></ol>| | ||
| | Intended Usage | Common | | ||
| | Other Information and Comments | N/A | | ||
|
|
||
| ### Helm Content | ||
|
|
||
| Represents the packaged Helm chart. | ||
|
|
||
| | | ||
| ------ | ----- | ||
| | Type Name | application | | ||
| | Tree | Vendor Tree (vnd prefix) | | ||
| | Subtype Name | `cncf.helm.chart.content.v1.tar+gzip` | | ||
| | Required Parameters | N/A | | ||
| | Optional Parameters | N/A | | ||
| | Encoding Considerations | Binary | | ||
| | Security Considerations | No security controls are enforced by Helm. The content of a Helm package is not intended to – but may potentially – contain resources that are sensitive in nature. | | ||
| | Interoperability Consideration | N/A |` | ||
| | Published specification | None | | ||
| | Application Usage | Internally within the Helm package manager as well as various interfacing applications | | ||
| | Fragment Identifier Considerations | N/A | | ||
| | Restrictions on Usage | N/A | | ||
| | Provisional Registrations | N/A | | ||
| | Additional Information | <ol><li>Deprecated alias names for this type: None</li><li>Magic number(s): None</li><li>File extension(s): None</li><li>Macintosh file type code: None</li><li>Object Identifiers: None</li></ol> | ||
| | Intended Usage | Common | | ||
| | Other Information and Comments | N/A | | ||
|
|
||
| ### Helm Provenance | ||
|
|
||
| Represents the Helm Provenance file associated with a signed chart. | ||
|
|
||
| | | ||
| ------ | ----- | ||
| | Type Name | application | | ||
| | Tree |Vendor Tree (vnd prefix) | | ||
| | Subtype Name | `cncf.helm.chart.provenance.v1.prov` | | ||
| | Required Parameters | Fields as specified within Helm provenance file definition | | ||
| | Optional Parameters N/A | | ||
| | Encoding Considerations | The utf-8 charset is always used for this type | | ||
| | Security Considerations | The contents of a Helm provenance file contains a GnuPG detached ASCII-armored signature of the Helm chart definition file as well as the definition itself. The Helm chart definition may include sensitive assets including personal contact information, source code repositories or other referenceable locations. | ||
| | Interoperability Consideration | N/A | | ||
| | Published specification | <https://helm.sh/docs/topics/provenance/#the-provenance-file> | | ||
| | Application Usage | Internally within the Helm package manager as well as various interfacing applications | | ||
| | Fragment Identifier Considerations | N/A | | ||
| | Restrictions on Usage | N/A | | ||
| | Provisional Registrations | N/A | | ||
| | Additional Information | <ol><li>Deprecated alias names for this type: None</li><li>Magic number(s): None</li><li>File extension(s): None</li><li>Macintosh file type code: Text</li><li>Object Identifiers: None</li></ol> | | ||
| | Intended Usage | Common | | ||
| | Other Information and Comments | N/A | | ||
| Running helm install should look look this | ||
| `helm install <release> --release-tag` | ||
|
|
||
| Running helm upgrade should look like this | ||
| `helm upgrade <release> --release-tag` | ||
|
|
||
| The output of helm history should look similar to this | ||
| ``` | ||
| go run ./ history demo-nginx | ||
| REVISION UPDATED STATUS CHART APP VERSION DESCRIPTION RELEASE TAG | ||
| 1 Tue Jul 19 15:31:37 2022 superseded nginx-13.1.2 1.23.0 Release Mock 921103db | ||
| 2 Tue Jul 19 15:31:52 2022 superseded nginx-13.1.2 1.23.0 Release Mock 1a6f3966 | ||
| 3 Tue Jul 19 15:32:05 2022 superseded nginx-13.1.2 1.23.0 Release Mock 211bd2b6 | ||
| 4 Tue Jul 19 15:32:19 2022 deployed nginx-13.1.2 1.23.0 Release Mock 886f1e55 | ||
| ``` | ||
|
|
||
| ## Backwards Compatibility | ||
|
|
||
| N/A | ||
| This is adding an additional field and is not a required flag. There should be no issue with backwards compatability. | ||
|
|
||
| ## Security implications | ||
|
|
||
| N/A | ||
| Cannot think of any security concerns with this feature. | ||
|
|
||
| ## Reference implementation | ||
|
|
||
| The responses associated with each Media Type registration has been inspired by the previously registered [IANA Media Types](https://www.iana.org/assignments/media-types/media-types.xhtml). | ||
| There is a open pr for this feature. | ||
| https://github.com/helm/helm/pull/11165 | ||
|
|
||
| ## Rejected ideas | ||
|
|
||
| None | ||
| N/A | ||
|
|
||
| ## Open issues | ||
|
|
||
| None | ||
| https://github.com/helm/helm/issues/8194 | ||
|
|
||
| ## References | ||
|
|
||
| Existing Media Types of similar category and purpose can be found within the list of registered [IANA Media Types](https://www.iana.org/assignments/media-types/media-types.xhtml). The following are examples of media types that have been registered with IANA: | ||
|
|
||
| * [json](https://www.iana.org/assignments/media-types/application/json) | ||
| * [gzip](https://www.iana.org/assignments/media-types/application/gzip) | ||
| * [wasm](https://www.iana.org/assignments/media-types/application/wasm) | ||
| N/A |