Helm Concepts: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
No edit summary
 
(117 intermediate revisions by the same user not shown)
Line 2: Line 2:


* [[Helm#Subjects|Helm]]
* [[Helm#Subjects|Helm]]
* [[Helm Templates]]
* [[Helm Templates|Templates]]
* [[Helm Dependencies]]
* [[Helm Configuration|Configuration]]
* [[Helm Dependencies|Dependencies]]


=Overview=
=Overview=


Helm is a tool for managing Kubernetes packages called [[#Chart|charts]]. Helm creates new charts from scratch, packages charts into [[#Chart_Archive|chart archives]] (tgz) files, interacts with [[#Repository|chart repositories]] where charts are stored, and finally installs and manages the release cycle of chats into an existing Kubernetes cluster. The installation process takes a chart, applies custom, operational environment-specific [[Helm_Configuration#Overview|configuration]] and installs the chart into the Kubernetes cluster, creating a [[#Release|release]].
Helm is a tool for managing Kubernetes packages called [[#Chart|charts]]. Helm creates new charts from scratch, packages charts into [[#Chart_Archive|chart archives]] (tgz) files, interacts with [[#Repository|chart repositories]] where charts are stored, and finally installs and manages the release cycle of the underlying applications into an existing Kubernetes cluster. The installation process takes a chart, applies custom, operational environment-specific [[Helm_Configuration#Overview|configuration]] and installs the chart into the Kubernetes cluster, creating a [[#Release|release]].


Helm allows defining an application as a set of Kubernetes cluster components and provides mechanisms to manage these sets for their entire lifecycle.
Helm allows defining an application as a set of Kubernetes cluster components and provides mechanisms to manage these sets for their entire lifecycle.
Line 14: Line 15:
{{External|[https://helm.sh/docs/glossary/#chart Helm Glossary - Chart]}}
{{External|[https://helm.sh/docs/glossary/#chart Helm Glossary - Chart]}}


A chart is a Helm package and a package format, the Kubernetes equivalent of a [[yum]] RPM file or a [[Brew|Homebrew]] formula. A chart contains all resource definitions necessary to deploy and run an application inside Kubernetes, arranged in a specific [[#Layout|layout]]. A chart may be used to deploy a simple application, or a full web application stack with multiple dependencies, such as HTTP servers, database, caches and so on. A chart can be '''unpackaged''', in which case it is a folder with files that follow the Helm chart rules and conventions. An unpackaged chart can be deployed directly to a cluster. A chart can also be '''packaged''', as a tar.gz [[#Chart_Archive|chart archive]]. Packaged charts can be dployed directly to the cluster.
A chart is a Helm package and a package format, the Kubernetes equivalent of a [[yum]] RPM file or a [[Brew|Homebrew]] formula. A chart contains all resource definitions necessary to deploy and run an application inside Kubernetes, arranged in a specific [[#Layout|layout]]. A chart may be used to deploy a simple application, or a full web application stack with multiple dependencies, such as HTTP servers, database, caches and so on. A chart can be '''unpackaged''', in which case it is a folder with files that follow the Helm chart rules and conventions. A chart can also be '''packaged''', as a tar.gz [[#Chart_Archive|chart archive]].  


====Chart Name====
====Chart Name====
A chart is identified by its '''name''' in [[Helm_Repositories#Overview|repositories]]. Examples: "nginx" or "postgresql". The chart name is sometimes referred to as [[Helm_Repositories#Chart_Reference|chart reference]]. The name is part of the package identification, along with [[#Chart_Version|chart version]]. The name of the chart is also specified in the <code>[[Helm_Chart_Chart.yaml#name|name]]</code> field of the <code>Chart.yaml</code> metadata file. Chart names should use lower case letter and numbers, and start with a letter. Hyphens are allowed. Uppercase letter, underscores or dots should not be used in chart names.


A chart is identified by its '''name''' in [[#Repository|repositories]]. Examples: "nginx" or "postgresql". The chart name is sometimes referred to as [[#Chart_Reference|chart reference]]. The name is part of the package identification, along with [[#Chart_Version|chart version]]. For custom charts, the name of the chart is specified in the [[Helm_Chart_Chart.yaml#name|name]] field of the Chart.yaml metadata file. Chart names should use lower case letter and numbers, and start with a letter. Hyphens are allowed. Uppercase letter, underscores or dots should not be used in chart names. The directory that contains a chart must have the same name as the chart. For more details see [https://helm.sh/docs/chart_best_practices/#chart-names Chart Names Best Practices].
The directory that contains a chart must have the same name as the chart.  
 
For more details see [https://helm.sh/docs/chart_best_practices/#chart-names Chart Names Best Practices].


====Chart Versioning====
====Chart Versioning====
<code>Chart.yaml</code> carries two version fields: the <span id='Chart_Version'></span>'''chart version''' (<code>[[Helm_Chart_Chart.yaml#version|version]]</code>) and the <span id='Application_Version'></span>'''application version''' (<code>[[Helm_Chart_Chart.yaml#appVersion|appVersion]]</code>).


[[Helm_Chart_Chart.yaml#version|Chart.yaml]] carries two version fields: the <span id='Chart_Version'></span>'''chart version''' ([[Helm_Chart_Chart.yaml#version|version]]) and the <span id='Application_Version'></span>'''application version''' ([[Helm_Chart_Chart.yaml#appVersion|appVersion]]).  
Every chart must have a [[Software_Development#Semantic_Versioning|SemVer 2]] version specified in the <code>version</code> field of the <code>Chart.yaml</code> metadata file.  


Every chart must have a [[Software_Development#Semantic_Versioning|SemVer 2]] version specified as the [[Helm_Chart_Chart.yaml#version|version]] field of the Chart.yaml metadata file. Packages exposed by [[#Repository|repositories]], as well as packages generated by [[helm package]] are identified by their [[#Chart_Name|name]] '''and''' their version. For example, the [[#Chart_Archive|chart archive]] of an "nginx" package whose version filed is "1.2.3" will be named "nginx-1.2.3.tgz". Helm also uses the version number as [[#Release_Marker|release marker]]. Many other Helm tools, such as the [[#The_Helm_Client|CLI]] and the [[#The_Tiller_Server|Tiller server]] use the version information. It is assumed that the version number in the chart package name matches the version field in Chart.yaml. A mismatch will cause errors. For more details on chart version see [https://helm.sh/docs/chart_best_practices/#version-numbers Chart Version Numbers Best Practices].
Packages exposed by [[#Repository|repositories]], as well as packages generated by [[helm package]] are identified by their [[#Chart_Name|name]] '''and''' their version. For example, the [[#Chart_Archive|chart archive]] of an "nginx" package whose version filed is "1.2.3" will be named:
<font size=-1>
nginx-1.2.3.tgz
</font>
Helm tools rely on the version section of the chart archive file name as [[#Release_Marker|release marker]]. The system assumes that the version number in the chart package name matches the version number in the <code>Chart.yaml</code>. Failure to meet this assumption will cause an error. For more details on chart version see [https://helm.sh/docs/chart_best_practices/#version-numbers Chart Version Numbers Best Practices].


The [[Helm_Chart_Chart.yaml#appVersion|appVersion]] field is intended to carry an informal application version, not necessarily [[Software_Development#Semantic_Versioning|SemVer 2]], and independent from the [[Helm_Chart_Chart.yaml#version|version]] field. This field is informational, and has no impact on chart version calculations. It is very common for the chart version and app version to be different:
The <code>[[Helm_Chart_Chart.yaml#appVersion|appVersion]]</code> field is intended to carry an informal application version, not necessarily [[Software_Development#Semantic_Versioning|SemVer 2]], and independent from the <code>[[Helm_Chart_Chart.yaml#version|version]]</code> field. This field is informational, and has no impact on chart version calculations. It is very common for the chart version and app version to be different:


NAME                               CHART VERSION APP VERSION DESCRIPTION
<syntaxhighlight lang='text'>
stable/postgresql                 6.3.2        11.5.0     Chart for PostgreSQL, an object-relational database manag...
NAME                     CHART VERSION APP VERSION DESCRIPTION
stable/postgresql         6.3.2        11.5.0     Chart for PostgreSQL, an object-relational database manag...
</syntaxhighlight>


====Chart Archive====
====Chart Archive====


A chart archive is a chart in a packaged (tgz) format. The [[#Repository|chart repositories]] expose chart archives.  [[helm package]] creates chart archives.
A chart archive is a chart in a packaged (tgz) format. The [[#Repository|chart repositories]] expose chart archives.  The <code>[[helm package]]</code> command creates chart archives.
 
====Chart Type====
 
The type designates a chart as 'application' or 'library'. 'application' is the default type. A 'library' or 'helper' chart provides utilities or functions for the chart builder, it has no resource object and therefore is not installable. Example: https://github.com/helm/charts/tree/master/incubator/common.
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. No resource objects contained by the chart will be rendered.


==Chart Installation==
==Chart Installation==
Charts are installed into a target Kubernetes cluster and turned into [[#Release|releases]] with:
<font size=-1>
[[helm install]]
</font>
The installation is an asynchronous process, the Helm client does not wait until all resources are running before it exits, this is because charts may need large container images that take long to install in the cluster. Without additional input, a chart will be installed with the [[Helm_Configuration#Default_Configuration|default configuration]], but [[Helm_Configuration#Overriding_Default_Configuration|custom configuration changes]] can be applied during the installation process.


Charts are installed into a target Kubernetes cluster and turned into [[#Release|releases]] with [[helm install]]. The installation is an asynchronous process, the Helm client does not wait until all resources are running before it exits, this is because charts may require large Docker images that take long to install in the cluster. Without additional input, a chart will be installed with the [[Helm_Configuration#Default_Configuration|default configuration]], but [[Helm_Configuration#Overriding_Default_Configuration|custom configuration changes]] can be applied during the installation process.
The default option for the helm install command is to install from the [[Helm_Repositories#Default_Repository|default repository]]. However, the chart may come from other sources: a [[Helm_repo#Add_a_New_Repository|different repository]], a [[Helm_install#Installing_from_a_File|local file]], an [[Helm_install#Installing_from_an_Unpacked_Chart_Directory|unpacked chart directory]] or a [[Helm_install#Installing_from_a_URL|URL]].
 
The default option for the helm install command is to install from the [[#Default_Repository|default repository]]. However, the chart may come from other sources: a [[Helm_repo#Add_a_New_Repository|different repository]], a [[Helm_install#Installing_from_a_File|local file]], an [[Helm_install#Installing_from_an_Unpacked_Chart_Directory|unpacked chart directory]] or a [[Helm_install#Installing_from_a_URL|URL]].


===Resource Installation and De-Installation Order===
===Resource Installation and De-Installation Order===
Line 48: Line 67:


This section describes a typical chart directory tree. The top level directory is the chart name, without the version information.
This section describes a typical chart directory tree. The top level directory is the chart name, without the version information.
 
<font size=-1>
  archaeopteryx
  archaeopteryx
    |
  ├─ <span id='Chart.yaml'></span>[[Helm_Chart_Chart.yaml#Overview|Chart.yaml]]
    |- <span id='Chart.yaml'></span>[[Helm Chart Chart.yaml|Chart.yaml]]
  ├─ <span id='values.yaml'></span>[[Helm Chart values.yaml|values.yaml]]
    |- <span id='values.yaml'></span>[[Helm Chart values.yaml|values.yaml]]
  ├─ <span id='LICENSE'></span>[[Helm Chart License|LICENSE]]
    |- <span id='requirements.yaml'></span>[[Helm Chart requirements.yaml|requirements.yaml]]
  ├─ <span id='README'></span>[[Helm Chart README|README.md]]
    |- <span id='requirements.lock'></span>[[Helm Chart requirements.lock|requirements.lock]]
  ├─ <span id='.helmignore'></span>[[Helm Chart .helmignore|.helmignore]]
    |- <span id='LICENSE'></span>[[Helm Chart License|LICENSE]]
  ├─ [[#charts_Directory|charts]]
    |- <span id='README'></span>[[Helm Chart README|README.md]]
  └─ [[Helm_Templates#The_templates.2F_Directory|templates]]
    |- <span id='.helmignore'></span>[[Helm Chart .helmignore|.helmignore]]
      ├─ <span id='NOTES.txt'></span>[[Helm Chart NOTES.txt|NOTES.txt]]
    |- [[#charts_Directory|charts]]
      ├─ <span id='_helpers.tpl'></span>[[Helm Chart _helpers.tpl|_helpers.tpl]]
    +- [[Helm_Templates#The_templates.2F_Directory|templates]]
      ├─ deployment.yaml
          |
      ├─ service.yaml
          |- <span id='NOTES.txt'>[[Helm Chart NOTES.txt|NOTES.txt]]
      │ ...
          |- <span id='_helpers.tpl'></span>[[Helm Chart _helpers.tpl|_helpers.tpl]]
      └─ tests
          |- deployment.yaml
</font>
          |- service.yaml
          | ...
          +- tests


===<span id='charts_Directory'></span>charts/ Directory===
===<span id='charts_Directory'></span><tt>charts/</tt> Directory===


The 'charts' directory contains any charts upon which this chart depends. The content of the directory can either [[Helm Dependencies#Manual_Dependency|manually managed]], or it can be [[Helm Dependencies#Dynamic_Dependency|updated dynamically]] for dependencies declared in [[Helm_Chart_requirements.yaml|requirements.yaml]]. A dependency can be either a [[#Chart_Archive|chart archive]] or an unpacked chart directory. If the name of the dependency, either file or directory, starts with '_' or '.', the dependency will be ignored by the chart loader.
The 'charts' directory contains any charts upon which this chart depends. The content of the directory can either [[Helm Dependencies#Manual_Dependency|manually managed]], or it can be [[Helm Dependencies#Dynamic_Dependency|updated dynamically]] for dependencies declared in <code>[[Helm_Chart_Chart.yaml|Chart.yaml]]</code> for Helm 3 or <code>[[Helm_Chart_requirements.yaml|requirements.yaml]]</code> for Helm 2. A dependency can be either a [[#Chart_Archive|chart archive]] or an unpacked chart directory. If the name of the dependency, either file or directory, starts with '_' or '.', the dependency will be ignored by the chart loader. For more details on dependencies see: {{Internal|Helm_Dependencies#How_Helm_Dependencies_Work|How Helm Dependencies Work}}


===<span id='templates_Directory'></span>templates/ Directory===
===<span id='templates_Directory'></span><tt>templates/</tt> Directory===


{{Internal|Helm_Templates#The_templates.2F_Directory|The templates/ Directory}}
{{Internal|Helm_Templates#The_templates.2F_Directory|The <tt>templates/</tt> Directory}}


==Developing Custom Charts==
==Developing Custom Charts==


The development of a custom chart could start with [[helm create]], which is a command that creates a standard chart directory layout along with some common files typically used in a chart. The command provides just a basic example and is not meant to cover all Kubernetes resources. While a chart is being developed, the syntactic consistency can be checked with [[helm lint]]. Then the chart is ready for delivery, it can be packaged with [[helm package]].
The development of a custom chart could start with the <code>[[helm create]]</code> command, which is a command that creates a standard chart directory layout along with some common files typically used in a chart. The command provides just a basic example and is not meant to cover all Kubernetes resources. While a chart is being developed, the syntactic consistency can be checked with the <code>[[helm lint]]</code> command. Then the chart is ready for delivery, it can be packaged with <code>[[helm package]]</code>.


==Chart Operations==
==Chart Operations==


* [[helm create]]
* <code>[[helm create]]</code>
* [[helm lint]]
* <code>[[helm lint]]</code>
* [[helm package]]
* <code>[[helm package]]</code>
* [[helm install]]
* <code>[[helm install]]</code>
* [[helm show]]
* <code>[[helm show]]</code>
* [[Helm_get#Get_Manifest|helm get manifest]]
* <code>[[Helm_get#Get_Manifest|helm get manifest]]</code>
 
=Configuration=
{{Internal|Helm Configuration|Configuration}}
 
=<span id='Dependency'></span><span id='Dynamic_Dependencies'></span><span id='Dependency_Selective_Loading'></span><span id='Importing_Child_Values'></span><span id='Manual_Dependencies'></span><span id='Subcharts'></span><span id='Dependency_Operations'></span><span id='Dynamic_.28requirements.yaml.29_Dependencies'></span>Dependencies=
{{Internal|Helm Dependencies|Dependencies}}
 
=Repository=
 
{{External|[https://helm.sh/docs/glossary/#repository-repo-chart-repository Helm Glossary - Repository]}}
{{External|[https://helm.sh/docs/developing_charts/#the-chart-repository-guide The Chart Repository Guide]}}
 
A repository is a place - usually a HTTP server - where [[#Chart|charts]] are collected and shared. The charts are exposed in an [[Helm_Concepts#Chart_Archive|archived format]]. A repository must expose in its root an index.yaml file that contains a list of all packages supplied by repository, together with metadata that allows retrieving and verifying those packages. When Helm is installed, it is pre-configured with a [[#Default_Repository|default repository]]. New repositories an be [[Helm_repo#Add_a_New_Repository|added]]. The list of locally-configured repository can be inspected with [[Helm_repo#List_Repositories_Helm_is_Configured_With|helm repo list]], which essentially reads ~/.helm/repository/repositories.yaml. Repositories can be searched for charts with [[helm search]]. Because chart repositories change frequently, it is recommended to [[Helm_repo#Update_the_Local_Repository_Cache|update the local cache]].
 
Helm comes with a built-in package server for developer testing. For more details see [[helm serve]].
 
Using Helm repositories is recommended practice, but they are optional. A Helm chart can be deployed directly from the filesystem.
 
==Repository Name==
 
Each locally-added repository is known under a name, which is associated with the [[#Repository_URL|repository URL]].
 
==Repository URL==
 
The repository URL represents the endpoint of a Helm repository - the endpoint's root must contain an index.yaml file. Also see the discussion for the special case of dependency charts that [[Helm_Chart_requirements.yaml#repository|exist on the local file system]].
 
==Default Repository==
 
When Helm is installed, it is pre-configured to look into the official [https://github.com/helm/charts Helm Charts GitHub repository], named "stable".
 
==Local Cache==
 
The local repository cache is maintained under ~/.helm/repository.
 
<font color=darkgray>TODO investigate ~/.helm/repository</font>
 
==Chart Reference==
 
A chart stored in a chart repository can be identified by its '''chart reference''', relative to the repository. The chart reference and the [[#Chart_Name|chart name]] are semantically equivalent. The chart reference, or the [[#Chart_Name|chart name]], is used to specify the chart [[Helm_install#Chart_Reference|when installed]].
 
==Repository Operations==
 
* [[helm repo]]
* [[helm search]]
* [[helm serve]]
 
=<span id='Template'></span>Templates=
 
{{Internal|Helm Templates|Helm Templates}}


=Release=
=Release=
A release is a running instance of a [[#Chart|chart]], to which a specific [[Helm_Configuration#Overview|configuration]] was applied. Whenever a chart is installed, a new release is created. One chart can be installed multiple times into the same cluster, and each can be independently managed and upgraded. Each release has its own [[#Release_Name|release name]]. It is important to know that releases are namespace-scoped. There could be two releases with the same name, but in two different namespaces.


A release is a running instance of a [[#Chart|chart]], to which a specific [[#Config|config]] was applied. Whenever a [[#Chart|chart]] is installed, a new release is created. One chart can be installed multiple times into the same cluster, and each can be independently managed and upgraded. Each release has its own [[#Release_Name|release name]].
When a new version of a chart is released, or when the configuration of a release changes, the release can be upgraded with the <code>[[helm upgrade]]</code> command. Helm tries to perform the least invasive upgrade, and only upgraded things that changed since the last release. If something fails during the upgrade, a rollback can be performed with the <code>[[helm rollback]]</code> command.
 
When a new version of a chart is released, or when the configuration of a release must be changes, the release can be upgraded with [[helm upgrade]]. Helm tries to perform the least invasive upgrade, and only upgraded things that changed since the last release. If something fails during the upgrade, a rollback can be performed with [[helm rollback]].


Releases can be of course uninstalled with [[helm uninstall]]. Helm keeps a history of deleted releases, which can be retrieved with [[Helm_list#Show_Deleted_Releases|helm list --deleted]].
At a certain moment in time, a release is in a certain [[#Release_State|state]].


Releases can be uninstalled with the <code>[[helm uninstall]]</code>. Helm keeps a history of deleted releases, which can be retrieved with the <code>[[Helm_list#Show_Deleted_Releases|helm list --deleted]]</code>.
==Release Name==
==Release Name==


If not specified, release names are generated (e.g. "happy-panda"). To specify a release name, use [[Helm_install#Specifying_a_Release_Name|helm install --name]]. Helm keeps records of deleted releases, so a release name first used by a deleted release cannot be re-used (unless --replace is used). The release name is available in templates as a built-in object:
If not specified, release names are generated (e.g. "happy-panda"). To specify a release name, use the <code>[[Helm_install#Specifying_a_Release_Name|helm install <name> ...]]</code> command. Helm keeps records of deleted releases, so a release name first used by a deleted release cannot be re-used (unless <code>--replace</code> is used). The release name is available in templates as a built-in object:
<font size=-1>
   &#123;{ [[Helm_Templates#Release.Name|.Release.Name]] }}
   &#123;{ [[Helm_Templates#Release.Name|.Release.Name]] }}
</font>
Many charts are configured so Kubernetes resources created during a Helm installation carry a "release" [[#Labels|label]] with the value set to the release name.


==Release Revision==
==Release Revision==


A release version (revision) is incremental. Every time an install, upgrade or rollback happens, the revision number is incremented by 1, and the first revision is always 1. The revision numbers for a certain release can be inspected with [[helm history]]. A release revision can be used during a [[helm rollback|rollback]]. The release revision is available in templates as a built-in object:
A release version (revision) is incremental. Every time an install, upgrade or rollback happens, the revision number is incremented by 1, and the first revision is always 1. The revision numbers for a certain release can be inspected with the <code>[[helm history]]</code> command. A release revision can be used during a [[helm rollback|rollback]]. The release revision is available in templates as a built-in object:
<font size=-1>
   &#123;{ [[Helm_Templates#Release.Revision|.Release.Revision]] }}
   &#123;{ [[Helm_Templates#Release.Revision|.Release.Revision]] }}
</font>
==Release State==
The release state is reported by the <code>[[Helm_status|helm status]]</code> command.
A release state is one of:
===<tt>unknown</tt>===
===<tt>deployed</tt>===
===<tt>uninstalled</tt>===
===<tt>superseded</tt>===
===<tt>failed</tt>===
===<tt>uninstalling</tt>===
===<tt>pending-install</tt>===
===<tt>pending-upgrade</tt>===
===<tt>pending-rollback</tt>===


==Release Marker==
==Release Marker==
Line 162: Line 149:
==Release Lifecycle==
==Release Lifecycle==


==Release Operations==
==Resource Association with a Release==
 
Resources created by Helm are associated with their Helm release via annotations:
<syntaxhighlight lang='yaml'>
kind: ...
metadata:
  annotations:
    meta.helm.sh/release-name: release-example
    meta.helm.sh/release-namespace: namespace-example
  labels:
    app.kubernetes.io/managed-by: Helm
</syntaxhighlight>


* [[helm install]]
==Preventing Resource Deletion upon Uninstallation==
* [[Helm_get#Get_Manifest|helm get manifest]] - display the manifest content that was posted to the server as part of the installation process.
{{External|https://helm.sh/docs/howto/charts_tips_and_tricks/#tell-helm-not-to-uninstall-a-resource}}
* [[helm list]] - display currently deployed releases.
* [[helm history]]
* [[helm status]]
* [[helm upgrade]]
* [[helm rollback]]
* [[helm uninstall]]


=Runtime=
Normally, all resources created by a Helm installation are removed upon uninstallation: Helm uninstalls by default all resources created by the chart for the release being uninstalled. There are cases when we may want to keep resources around: one case is when we want to keep a PersistentVolumeClaim because deleting it would make the a PersistentVolume outside of our control unavailable for binding for the subsequent release.


==The Helm Client==
To indicate to Helm that a resource should be kept on uninstall, use the <code>"helm.sh/resource-policy"</code> annotation in template:


The Helm client is a command-line client for end users. The client is responsible for managing [[#Chart|charts]]. It helps with [[#Developing_Custom_Charts|local chart development]], manages the interaction with [[#Repository|chart repositories]] and interacts with the [[#The_Tiller_Server|Tiller server]]. The interaction with the server consists in installing charts and providing a CLI for the [[#Release|release]] life cycle (the server manages the releases).
<syntaxhighlight lang='yaml'>
kind: Something
  metadata:
    annotations:
      helm.sh/resource-policy: keep
</syntaxhighlight>


==The Tiller Server==
The <code>"helm.sh/resource-policy"</code> instructs helm to skip deleting the resource on uninstall, [[Helm upgrade|upgrade]] or [[Helm rollback|rollback]] operations.


The Tiller server is an in-cluster component that interacts with the [[#The_Helm_Client|Helm client]] and interfaces with the Kubernetes API Server.  
Note that this resource becomes orphaned, it will be no longer be managed by Helm. This can lead to problems when using the <code>[[Helm_install#--replace|helm install --replace]]</code> command on a release that has already been uninstalled, but has kept resources.


The server is responsible for managing [[#Release|releases]]. It does that by handling client requests, combining a chart and the [[#Config|configuration]] to build a [[#Release|release]], installing charts and then tracking their subsequent release, then upgrading and uninstalling charts.
<font color=darkgray>Helm does not seem to remove the [[Helm_Concepts#Resource_Association_with_a_Release|annotations and labels it placed on the resource]], so how does it know not to manage it anymore?</font>


Tiller stores release information in [[Kubernetes_Cluster_Configuration_Concepts#ConfigMap|ConfigMaps]] in the namespace where it is running. It could be configured to use a storage backend that uses [[Kubernetes_Cluster_Configuration_Concepts#Secret|Secrets]] for storing release information. More [https://helm.sh/docs/using_helm/#secret-storage-backend here]. It could also be configured to use an SQL storage backend for storing release information. More [https://helm.sh/docs/using_helm/#sql-storage-backend here].
==Release Operations==
* <code>[[helm install]]</code>
* <code>[[Helm_get#Get_Manifest|helm get manifest]]</code> - display the manifest content that was posted to the server as part of the installation process.
* <code>[[helm list]]</code> - display currently deployed releases.
* <code>[[helm history]]</code>
* <code>[[helm status]]</code>
* <code>[[helm upgrade]]</code>
* <code>[[helm rollback]]</code>
* <code>[[helm uninstall]]</code>
=<span id='Runtime'></span>The Helm Client=
The Helm client is a command-line client for end users. The client is responsible for managing [[#Chart|charts]]. It helps with [[#Developing_Custom_Charts|local chart development]] and manages the interaction with [[#Repository|chart repositories]]. The interaction with the server consists in installing charts and providing a CLI for the [[#Release|release]] life cycle (the server manages the releases).
=<span id='Template'></span>Templates=
{{Internal|Helm Templates|Helm Templates}}


<font color=darkgray>
=Configuration=
TODO: https://helm.sh/docs/using_helm/#tiller-namespaces-and-rbac
{{Internal|Helm Configuration|Configuration}}
</font>
 
=<span id='Dependency'></span><span id='Dynamic_Dependencies'></span><span id='Dependency_Selective_Loading'></span><span id='Importing_Child_Values'></span><span id='Manual_Dependencies'></span><span id='Subcharts'></span><span id='Dependency_Operations'></span><span id='Dynamic_.28requirements.yaml.29_Dependencies'></span>Dependencies=
{{Internal|Helm Dependencies|Helm Dependencies}}
 
=<span id='Repository_Name'></span><span id='Repository_URL'></span><span id='Default_Repository'></span><span id='Local_Cache'></span><span id='Chart_Reference'></span><span id='Repository_Operations'></span>Repository=
{{Internal|Helm Repositories|Helm Repository}}


=Hooks=
=Hooks=
 
{{Internal|Helm Hooks|Hooks}}
<font color=darkgray>TODO: https://helm.sh/docs/developing_charts/#hooks</font>


=Security=
=Security=
Line 204: Line 217:


=Tests=
=Tests=
{{Internal|Helm Chart Tests|Helm Chart Tests}}
=Labels=
Most charts configure the Kubernetes resources created by them to carry a "release" label, whose value is the [[#Release_Name|release name]]. This convention could be useful in providing a mechanism to identify these resources using [[Kubernetes Selector Concepts|label selectors]].


<font color=darkgray>TODO: https://helm.sh/docs/developing_charts/#chart-tests</font>
=<span id='Deprecated_Elements'></span>Helm 2 Deprecated Elements=
* <code>[[Helm Chart requirements.yaml|requirements.yaml]]</code>
* <code>[[Helm Chart requirements.lock|requirements.lock]]</code>
* [[Helm Tiller|Tiller]]

Latest revision as of 00:23, 6 February 2022

Internal

Overview

Helm is a tool for managing Kubernetes packages called charts. Helm creates new charts from scratch, packages charts into chart archives (tgz) files, interacts with chart repositories where charts are stored, and finally installs and manages the release cycle of the underlying applications into an existing Kubernetes cluster. The installation process takes a chart, applies custom, operational environment-specific configuration and installs the chart into the Kubernetes cluster, creating a release.

Helm allows defining an application as a set of Kubernetes cluster components and provides mechanisms to manage these sets for their entire lifecycle.

Chart

Helm Glossary - Chart

A chart is a Helm package and a package format, the Kubernetes equivalent of a yum RPM file or a Homebrew formula. A chart contains all resource definitions necessary to deploy and run an application inside Kubernetes, arranged in a specific layout. A chart may be used to deploy a simple application, or a full web application stack with multiple dependencies, such as HTTP servers, database, caches and so on. A chart can be unpackaged, in which case it is a folder with files that follow the Helm chart rules and conventions. A chart can also be packaged, as a tar.gz chart archive.

Chart Name

A chart is identified by its name in repositories. Examples: "nginx" or "postgresql". The chart name is sometimes referred to as chart reference. The name is part of the package identification, along with chart version. The name of the chart is also specified in the name field of the Chart.yaml metadata file. Chart names should use lower case letter and numbers, and start with a letter. Hyphens are allowed. Uppercase letter, underscores or dots should not be used in chart names.

The directory that contains a chart must have the same name as the chart.

For more details see Chart Names Best Practices.

Chart Versioning

Chart.yaml carries two version fields: the chart version (version) and the application version (appVersion).

Every chart must have a SemVer 2 version specified in the version field of the Chart.yaml metadata file.

Packages exposed by repositories, as well as packages generated by helm package are identified by their name and their version. For example, the chart archive of an "nginx" package whose version filed is "1.2.3" will be named:

nginx-1.2.3.tgz

Helm tools rely on the version section of the chart archive file name as release marker. 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. For more details on chart version see Chart Version Numbers Best Practices.

The appVersion field is intended to carry an informal application version, not necessarily SemVer 2, and independent from the version field. This field is informational, and has no impact on chart version calculations. It is very common for the chart version and app version to be different:

NAME                      CHART VERSION	APP VERSION DESCRIPTION
stable/postgresql         6.3.2        	11.5.0      Chart for PostgreSQL, an object-relational database manag...

Chart Archive

A chart archive is a chart in a packaged (tgz) format. The chart repositories expose chart archives. The helm package command creates chart archives.

Chart Type

The type designates a chart as 'application' or 'library'. 'application' is the default type. A 'library' or 'helper' chart provides utilities or functions for the chart builder, it has no resource object and therefore is not installable. Example: https://github.com/helm/charts/tree/master/incubator/common. 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. No resource objects contained by the chart will be rendered.

Chart Installation

Charts are installed into a target Kubernetes cluster and turned into releases with:

helm install

The installation is an asynchronous process, the Helm client does not wait until all resources are running before it exits, this is because charts may need large container images that take long to install in the cluster. Without additional input, a chart will be installed with the default configuration, but custom configuration changes can be applied during the installation process.

The default option for the helm install command is to install from the default repository. However, the chart may come from other sources: a different repository, a local file, an unpacked chart directory or a URL.

Resource Installation and De-Installation Order

Template Installation and De-Installation Order

Chart Layout

This section describes a typical chart directory tree. The top level directory is the chart name, without the version information.

archaeopteryx
 ├─ Chart.yaml
 ├─ values.yaml
 ├─ LICENSE
 ├─ README.md
 ├─ .helmignore
 ├─ charts
 └─ templates
     ├─ NOTES.txt
     ├─ _helpers.tpl
     ├─ deployment.yaml
     ├─ service.yaml
     │ ...
     └─ tests

charts/ Directory

The 'charts' directory contains any charts upon which this chart depends. The content of the directory can either manually managed, or it can be updated dynamically for dependencies declared in Chart.yaml for Helm 3 or requirements.yaml for Helm 2. A dependency can be either a chart archive or an unpacked chart directory. If the name of the dependency, either file or directory, starts with '_' or '.', the dependency will be ignored by the chart loader. For more details on dependencies see:

How Helm Dependencies Work

templates/ Directory

The templates/ Directory

Developing Custom Charts

The development of a custom chart could start with the helm create command, which is a command that creates a standard chart directory layout along with some common files typically used in a chart. The command provides just a basic example and is not meant to cover all Kubernetes resources. While a chart is being developed, the syntactic consistency can be checked with the helm lint command. Then the chart is ready for delivery, it can be packaged with helm package.

Chart Operations

Release

A release is a running instance of a chart, to which a specific configuration was applied. Whenever a chart is installed, a new release is created. One chart can be installed multiple times into the same cluster, and each can be independently managed and upgraded. Each release has its own release name. It is important to know that releases are namespace-scoped. There could be two releases with the same name, but in two different namespaces.

When a new version of a chart is released, or when the configuration of a release changes, the release can be upgraded with the helm upgrade command. Helm tries to perform the least invasive upgrade, and only upgraded things that changed since the last release. If something fails during the upgrade, a rollback can be performed with the helm rollback command.

At a certain moment in time, a release is in a certain state.

Releases can be uninstalled with the helm uninstall. Helm keeps a history of deleted releases, which can be retrieved with the helm list --deleted.

Release Name

If not specified, release names are generated (e.g. "happy-panda"). To specify a release name, use the helm install <name> ... command. Helm keeps records of deleted releases, so a release name first used by a deleted release cannot be re-used (unless --replace is used). The release name is available in templates as a built-in object:

 {{ .Release.Name }}

Many charts are configured so Kubernetes resources created during a Helm installation carry a "release" label with the value set to the release name.

Release Revision

A release version (revision) is incremental. Every time an install, upgrade or rollback happens, the revision number is incremented by 1, and the first revision is always 1. The revision numbers for a certain release can be inspected with the helm history command. A release revision can be used during a rollback. The release revision is available in templates as a built-in object:

 {{ .Release.Revision }}

Release State

The release state is reported by the helm status command.

A release state is one of:

unknown

deployed

uninstalled

superseded

failed

uninstalling

pending-install

pending-upgrade

pending-rollback

Release Marker

The package version is included in the release marker.

Release Lifecycle

Resource Association with a Release

Resources created by Helm are associated with their Helm release via annotations:

kind: ...
metadata:
  annotations:
    meta.helm.sh/release-name: release-example
    meta.helm.sh/release-namespace: namespace-example
  labels:
    app.kubernetes.io/managed-by: Helm

Preventing Resource Deletion upon Uninstallation

https://helm.sh/docs/howto/charts_tips_and_tricks/#tell-helm-not-to-uninstall-a-resource

Normally, all resources created by a Helm installation are removed upon uninstallation: Helm uninstalls by default all resources created by the chart for the release being uninstalled. There are cases when we may want to keep resources around: one case is when we want to keep a PersistentVolumeClaim because deleting it would make the a PersistentVolume outside of our control unavailable for binding for the subsequent release.

To indicate to Helm that a resource should be kept on uninstall, use the "helm.sh/resource-policy" annotation in template:

kind: Something
  metadata:
    annotations:
      helm.sh/resource-policy: keep

The "helm.sh/resource-policy" instructs helm to skip deleting the resource on uninstall, upgrade or rollback operations.

Note that this resource becomes orphaned, it will be no longer be managed by Helm. This can lead to problems when using the helm install --replace command on a release that has already been uninstalled, but has kept resources.

Helm does not seem to remove the annotations and labels it placed on the resource, so how does it know not to manage it anymore?

Release Operations

The Helm Client

The Helm client is a command-line client for end users. The client is responsible for managing charts. It helps with local chart development and manages the interaction with chart repositories. The interaction with the server consists in installing charts and providing a CLI for the release life cycle (the server manages the releases).

Templates

Helm Templates

Configuration

Configuration

Dependencies

Helm Dependencies

Repository

Helm Repository

Hooks

Hooks

Security

Security Concepts

Plugins

Plugin Concepts

Tests

Helm Chart Tests

Labels

Most charts configure the Kubernetes resources created by them to carry a "release" label, whose value is the release name. This convention could be useful in providing a mechanism to identify these resources using label selectors.

Helm 2 Deprecated Elements