Difference between revisions of "Helm Dependencies"

From NovaOrdis Knowledge Base
Jump to: navigation, search
(Transitive Dependencies)
 
(15 intermediate revisions by the same user not shown)
Line 12: Line 12:
 
This was written for Helm 2.14.3.
 
This was written for Helm 2.14.3.
  
A Helm chart may declared dependencies, which are other Helm charts published in external repositories, conveniently packaged by people who presumably know the respective components well, thus they know how to best deploy them on Kubernetes.
+
All applications, maybe with the exception of the most trivial, usually depend on other runtime components, such as web servers, caches, databases, etc. Helm provides a mechanisms to formally specify, manage and deploy these dependencies as part of a [[Helm Concepts#Release|release]]. A Helm chart may declared dependencies, which are other Helm charts published in external repositories, conveniently packaged by people who presumably know the respective components well, thus they know how to best deploy them on Kubernetes.
  
 
During the installation or upgrade process, the Helm client looks into the ./charts sub-directory of the chart being installed, and installs/upgrades the charts whose [[Helm_Concepts#Chart_Archive|chart archives]] are found in that subdirectory. The content of the [[Helm_Concepts#charts_Directory|charts/]] subdirectory is '''the one and only source of truth''' on dependencies to be installed or upgraded. If a dependency chart is not present in the charts/ subdirectory at the time of installation/upgrade, it is not installed/upgraded. All charts present in the charts/ subdirectory at the time of installation/upgraded are installed/upgraded.
 
During the installation or upgrade process, the Helm client looks into the ./charts sub-directory of the chart being installed, and installs/upgrades the charts whose [[Helm_Concepts#Chart_Archive|chart archives]] are found in that subdirectory. The content of the [[Helm_Concepts#charts_Directory|charts/]] subdirectory is '''the one and only source of truth''' on dependencies to be installed or upgraded. If a dependency chart is not present in the charts/ subdirectory at the time of installation/upgrade, it is not installed/upgraded. All charts present in the charts/ subdirectory at the time of installation/upgraded are installed/upgraded.
Line 20: Line 20:
 
{{Note|This charts/ content management functionality ([[helm dependency]]) must be explicitly invoked and it is NOT automatically triggered during the installation or update process. However, some sanity checks are performed by [[helm install]], which fails if dependencies are declared in requirements.yaml but not present in charts/.}}
 
{{Note|This charts/ content management functionality ([[helm dependency]]) must be explicitly invoked and it is NOT automatically triggered during the installation or update process. However, some sanity checks are performed by [[helm install]], which fails if dependencies are declared in requirements.yaml but not present in charts/.}}
  
If a dependency is present in the charts/ subdirectory but not in requirements.yaml, it will be installed.
+
[[helm dependency|helm dependency update]] parses the requirements.yaml file and downloads chart archives in the charts/ subdirectory, while updating the [[Helm Chart requirements.lock|requirements.lock]] file.
 +
 
 +
If a dependency is present in the charts/ subdirectory but not in requirements.yaml, it will be considered a manually-managed dependency and it will be installed.
 +
 
 +
Helm documentation recommends [[Helm_Chart_requirements.yaml|requirements.yaml]] as the preferred method to manage dependencies. Some documents will refer to dependencies specified in requirement.yaml as <span id='Dynamic_.28requirements.yaml.29_Dependencies'></span><span id='Dynamicl_Dependency'></span><span id='Dynamic_Dependencies''></span>'''dynamic dependencies'''.
  
 
==Transitive Dependencies==
 
==Transitive Dependencies==
  
A dependency is a transitive dependency of a chart, if it is a dependency of one of the chart's dependencies. The transitive dependency must exist in the dependency chart's charts/ sub-directory. Simply declaring it in the dependency chart's requirements.yaml file does not make it a transitive dependency, in that the <code>[[helm dependency|helm dependency update]]</code> executed on the current chart will identify the direct dependency, but not the "transitive" dependency.
+
A dependency is a transitive dependency of a chart, if it is a dependency of one of the chart's dependencies. The transitive dependency must exist in the dependency chart's charts/ sub-directory. Simply declaring it in the dependency chart's requirements.yaml file does not make it a transitive dependency, in that the [[helm dependency|helm dependency update]] executed on the current chart will identify the direct dependency, but not the "transitive" dependency.
 +
 
 +
As an example, if the chart <code>a</code> declares in its requirements.yaml that it depends on chart <code>b</code>, and chart <code>b</code> declares in its requirements.yaml that it depends on chart <code>c</code>, but [[helm dependency|helm dependency update]] is not executed on <code>b</code>, so no chart archives are downloaded in b/charts/, executing [[helm dependency|helm dependency update]] on chart <code>a</code> identifies <code>b</code> as a dependency, but no <code>c</code>. In other words, [[helm dependency|helm dependency update]] does not look at requirements.yaml, only at the content of the charts/ directory.
  
 
Each chart is responsible for contributing  the continuity of the transitive dependency graph by insuring that its dependencies are present in charts/. Simply mentioning them in its requirements.yaml is not sufficient.
 
Each chart is responsible for contributing  the continuity of the transitive dependency graph by insuring that its dependencies are present in charts/. Simply mentioning them in its requirements.yaml is not sufficient.
  
==Transitive Dependencies and requirements.lock File==
+
Continuing with the above example, if the chart <code>b</code> has the <code>c</code>'s chart archive in its charts/, [[helm dependency|helm dependency update]] executed on <code>a</code> with update requirements.lock to indicate <code>b</code> as dependency, but will bring <code>b</code> chart archive in charts/, and the chart archive file includes the <code>c</code> chart archive.
  
requirements.yaml lists only the immediate dependencies of the chart. Those dependencies might have their own dependencies, and so on. The transitive closure of the entire set of dependencies of the chart constitutes the transitive dependency tree of the chart.
+
{{External|[https://github.com/ovidiuf/playground/tree/master/helm/dependency-examples/transitive-dependencies Transitive Dependency Playground Example]}}
  
When the chart is installed for the first time with [[helm install]], Helm builds the transitive dependency tree of the chart and writes it into requirements.lock file. This allows Helm to track the entire dependency tree of the chart and recreate it exactly as it last worked, even if some of the dependencies, or their dependencies are updated later. If the requirements.yaml does not change, Helm will use requirements.lock to identify dependencies. If requirements.yaml changes, Helm will notice that the file changes and will update requirements.lock to reflect those changes.
 
  
[[Helm_dependency#Dependency_Update|helm dependencies update]] also recreates the requirements.lock file.
 
  
  
  
 
<font color=darkgray>
 
<font color=darkgray>
 
 
All applications, maybe with the exception of the most trivial, usually depend on other runtime components, such as web servers, caches, databases, etc. Helm provides a mechanisms to formally specify, manage and deploy these dependencies as part of a [[Helm Concepts#Release|release]].
 
 
There are two ways to specify dependencies:
 
* '''Dynamically'''  by specifying a dependency chart's name, version and repository in [[Helm_Chart_requirements.yaml|requirements.yaml]]. Helm will download the [[Helm_Concepts#Chart_Archive|chart archive]] in the dependent's chart/ directory and use it during installation.
 
* '''Manually''' by bringing the [[#Chart_Archive|chart archive]] in the charts/ sub-directory of our chart and manage it manually.
 
The preferred method to manage dependencies is the dynamic one: declare the dependencies in [[Helm_Chart_requirements.yaml|requirements.yaml]]. Manual dependency management might be needed in specific cases, though.
 
 
</font>
 
 
=<span id='Dynamic_.28requirements.yaml.29_Dependencies'></span><span id='Dynamicl_Dependency'></span>Dynamic Dependencies=
 
 
The dependencies declared in [[Helm_Chart_requirements.yaml|requirements.yaml]] are dynamic dependencies. Dynamic dependencies can get [[Helm_Chart_requirements.yaml#alias|aliases]].
 
  
 
==Dynamic Dependency Management Workflow==
 
==Dynamic Dependency Management Workflow==
Line 114: Line 104:
 
=Retrieve Individual Chart Archives=
 
=Retrieve Individual Chart Archives=
  
  helm fetch stable/postgresql
+
  helm pull stable/postgresql
  
 
=Dependency Operations=
 
=Dependency Operations=
  
* [[helm fetch]]  
+
* [[helm pull]]  
 
* [[helm dependency]]
 
* [[helm dependency]]
 
* [[helm repo]]
 
* [[helm repo]]

Latest revision as of 20:45, 29 November 2019

External

Chart Dependencies

Internal

Overview

How Helm Dependencies Work

This was written for Helm 2.14.3.

All applications, maybe with the exception of the most trivial, usually depend on other runtime components, such as web servers, caches, databases, etc. Helm provides a mechanisms to formally specify, manage and deploy these dependencies as part of a release. A Helm chart may declared dependencies, which are other Helm charts published in external repositories, conveniently packaged by people who presumably know the respective components well, thus they know how to best deploy them on Kubernetes.

During the installation or upgrade process, the Helm client looks into the ./charts sub-directory of the chart being installed, and installs/upgrades the charts whose chart archives are found in that subdirectory. The content of the charts/ subdirectory is the one and only source of truth on dependencies to be installed or upgraded. If a dependency chart is not present in the charts/ subdirectory at the time of installation/upgrade, it is not installed/upgraded. All charts present in the charts/ subdirectory at the time of installation/upgraded are installed/upgraded.

However, Helm provides additional convenience functionality to manage the content of the charts/ subdirectory based on a list of dependency "coordinates" (name, version and repository URL) specified in the chart's requirements.yaml. The helm dependency commands operate on requirements.yaml, with the goal of keeping the content of the charts/ subdirectory in sync with the content of requirements.yaml.


This charts/ content management functionality (helm dependency) must be explicitly invoked and it is NOT automatically triggered during the installation or update process. However, some sanity checks are performed by helm install, which fails if dependencies are declared in requirements.yaml but not present in charts/.

helm dependency update parses the requirements.yaml file and downloads chart archives in the charts/ subdirectory, while updating the requirements.lock file.

If a dependency is present in the charts/ subdirectory but not in requirements.yaml, it will be considered a manually-managed dependency and it will be installed.

Helm documentation recommends requirements.yaml as the preferred method to manage dependencies. Some documents will refer to dependencies specified in requirement.yaml as dynamic dependencies.

Transitive Dependencies

A dependency is a transitive dependency of a chart, if it is a dependency of one of the chart's dependencies. The transitive dependency must exist in the dependency chart's charts/ sub-directory. Simply declaring it in the dependency chart's requirements.yaml file does not make it a transitive dependency, in that the helm dependency update executed on the current chart will identify the direct dependency, but not the "transitive" dependency.

As an example, if the chart a declares in its requirements.yaml that it depends on chart b, and chart b declares in its requirements.yaml that it depends on chart c, but helm dependency update is not executed on b, so no chart archives are downloaded in b/charts/, executing helm dependency update on chart a identifies b as a dependency, but no c. In other words, helm dependency update does not look at requirements.yaml, only at the content of the charts/ directory.

Each chart is responsible for contributing the continuity of the transitive dependency graph by insuring that its dependencies are present in charts/. Simply mentioning them in its requirements.yaml is not sufficient.

Continuing with the above example, if the chart b has the c's chart archive in its charts/, helm dependency update executed on a with update requirements.lock to indicate b as dependency, but will bring b chart archive in charts/, and the chart archive file includes the c chart archive.

Transitive Dependency Playground Example



Dynamic Dependency Management Workflow

Find a repository that exposes the dependency. You can start by searching the locally-added repositories with helm search. Also you can add additional repositories with helm repo add. Before searching, update the locally-cached information with helm repo update.

Once the dependency is identified, specify its name, chart version and full repository URLin requirements.yaml.

Then the dependency must be explicitly downloaded from the remote repository into the chart's charts/directory with helm dependency update. If the update step is not performed, an attempt to install the chart will end up in:

Error: found in requirements.yaml, but missing in charts/ directory: postgresql

Configure integration points in the top level, dependent's values.yaml.

Then the chart is installed with helm install. The dependency will be also installed.

Dependency Configuration

Dependency configuration values should be specified in the top values.yaml, and should be prefixed with the dependency name.

TODO example.

It is recommended to only override values in the top level chart, and not in any subchart.

Dependency Selective Loading

All dependencies declared in requirements.yaml are loaded by default. However, tags and conditions can be used to perform selective loading. Conditions are YAML paths specified in values.yaml that can be declared to be 'true' or 'false'. Tags are list of labels associated with a specific dependency. The tags can be enabled or disabled in values.yaml by specifying the tag and a boolean value. Also, the helm instal --set parameter can be used to alter tag and condition values at installation time.

Conditions or tags should be added to any dependencies that are optional.

TODO: https://helm.sh/docs/developing_charts/#tags-and-condition-resolution.

Importing Child Values

TODO: https://helm.sh/docs/developing_charts/#importing-child-values-via-requirements-yaml

Manual Dependencies

The dependencies declared in the charts/ directory are manually managed.

TODO: https://helm.sh/docs/developing_charts/#managing-dependencies-manually-via-the-charts-directory

Subcharts

The charts declared in the "charts/" subdirectory are named "subcharts".

TODO: https://helm.sh/docs/chart_template_guide/#subcharts-and-global-values

Subcharts and Global Values

TODO: https://helm.sh/docs/chart_template_guide/#subcharts-and-global-values

Operational Considerations

When Helm installs or updates a chart that has dependencies, it will aggregate all Kubernetes objects declared by the chart and dependencies in a single set. sort the object by types, then by name, and create/update in that order. Also see Installation and De-Installation Order.

Retrieve Individual Chart Archives

helm pull stable/postgresql

Dependency Operations


Aliases

Each element of the "dependencies" array in the requirements.yaml file allows for an optional "alias" attribute.

TODO: https://helm.sh/docs/developing_charts/#alias-field-in-requirements-yaml

Dependency TODO