Helm install: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(72 intermediate revisions by the same user not shown)
Line 5: Line 5:
* [[Helm Operations#Commands|Helm Operations]]
* [[Helm Operations#Commands|Helm Operations]]
* [[Helm Concepts#Chart|Helm Concepts]]
* [[Helm Concepts#Chart|Helm Concepts]]
* <code>[[helm upgrade]]</code>


=Overview=
=Overview=
{{Note|<center>Revised for Helm 3</center>}}
<code>helm install</code> installs a chart, that may come from different [[#Chart_Sources|sources]], and creates a [[Helm Concepts#Release|release]]:
<code>helm install</code> installs a [[Helm Concepts#Chart_Archive|chart archive]] and creates a [[Helm Concepts#Release|release]]:
<font size=-1>
 
  helm install <''release-name''> <''chart''> [options]
  helm install <''release-name''> <''chart''> [options]
</font>
<span id='Specifying_a_Release_Name'></span>The release name must be specified explicitly, and it must be the first argument. If it should be generated, <code>[[#--generate-name|--generate-name]]</code> must be used instead of the release name.


<span id='Specifying_a_Release_Name'></span>The release name must be specified explicitly. If it should be generated, [[#--generate-name|--generate-name]] must be used instead of the release name. Charts may come from different [[#Chart_Sources|sources]].
=<span id='Installing_from_Different_Sources'></span>Chart Sources=


=<span id='Installing_from_Different_Sources'></span>Chart Sources=
There are five types of chart sources:
# [[#Unpacked_Chart|Unpacked charts on the local filesystem]]
# [[#Packaged_Chart|tgz packaged chart on the local filesystem]]
# [[#Absolute_URL|Absolute URL of a chart archive in a remote repository]]
# [[#Chart_Reference|Chart reference in a remote repository]]
# [[#Using_a_Repository_Prefix|Chart is present in a locally cached repository, and specified by its chart name and repository prefix]]


==<span id='Installing_from_an_Unpacked_Chart_Directory'></span>Path to an Unpacked Chart==
==<span id='Installing_from_an_Unpacked_Chart_Directory'></span><span id='Unpacked_Chart'></span>Path to an Unpacked Chart==
The chart argument of the install command can be an unpacked local chart directory. [[Helm_Concepts#Chart_Name|The directory name must be identical with the chart name specified in Chart.yaml]]).
The chart argument of the install command can be an unpacked local chart directory. [[Helm_Concepts#Chart_Name|The directory name must be identical with the chart name specified in Chart.yaml]]).
 
<font size=-1>
  helm install simplest ./playground/helm/simplest
  helm install simplest ./playground/helm/simplest
</font>


==<span id='Installing_from_a_File'></span>Path to a Packaged Chart==
==<span id='Installing_from_a_File'></span><span id='Packaged_Chart'></span>Path to a Packaged Chart==
  helm install simplest ./simplest-1.0.0.tgz
  helm install simplest ./simplest-1.0.0.tgz
Charts can be packaged with [[helm package]] command.
Charts can be packaged with [[helm package]] command.


==<span id=''Installing_from_a_URL></span><span id=''URL></span>Absolute URL==
<font color=darkgray>Where is the chart expanded locally?</font>
 
==<span id='Installing_from_a_URL'></span><span id=''URL></span>Absolute URL==


The absolute URL of a chart can be used as such:
The absolute URL of a chart can be used as such:


helm install https&#58;//example.com/charts/something-1.0.0.tgz
<syntaxhighlight lang='bash'>
helm install something https://example.com/charts/something-1.0.0.tgz
</syntaxhighlight>
 
The version is built into the name of the chart, this is the [[Helm_Concepts#Chart_Versioning|default Helm versioning convention]]. The chart does not need to be cached in the local repository and the repository does not need to be cached locally with [[Helm_repo#Add_a_New_Repository|repo add]].
 
If the remote repository is password-protected, [[#--username.2C_--password|the username and the password]] can be specified on the command line with:
<syntaxhighlight lang='bash'>
helm install something https://example.com/charts/something-1.0.0.tgz --username <username> --password <password>
</syntaxhighlight>
 
<font color=darkgray>Where is the chart expanded locally?</font>


==Chart Reference==
==Chart Reference==


A chart available in a [[Helm_Concepts#Repository|chart repository]] can be specified by a [[Helm_Concepts#Chart_Reference|chart reference]] (which is the same thing as the [[Helm_Concepts#Chart_Name|chart name]]) when installed. There are two ways to specify a chart reference:
A chart available in a [[Helm_Concepts#Repository|chart repository]] can be specified by a [[Helm_Concepts#Chart_Reference|chart reference]] (which is the same thing as the [[Helm_Concepts#Chart_Name|chart name]]) when installed. There are two ways to specify a chart reference:
===Using an Explicit Repository URL with --repo===
A repository URL can be specified in-line in the install command line with --repo, without being previously added with [[Helm_repo#Add_a_New_Repository|helm repo add]]:
<syntaxhighlight lang='bash'>
helm install --repo https://example.com/charts/ mynginx [--version 1.2.3] nginx
</syntaxhighlight>
If [[#--version|--version]] is not specified, the latest present version is installed.
<font color=darkgray>Where is the chart expanded locally?</font>


===Using a Repository Prefix===
===Using a Repository Prefix===


helm install postgresql example/postgresql
If the repository was [[Helm_repo#Add_a_New_Repository|added locally]] under a specific name ("myRepository" in the example below), then the chart can be referred by <repository-name>/<chart-name>. If no version specification is provided, the latest stable version of the chart will be installed:


Note that the "example" is a name of a repository that has been previously added locally with [[Helm_repo#Add_a_New_Repository|helm repo add]]. If no other version specification is provided, the latest stable version of the chart will be installed. A specific version can be requested with --version.
<syntaxhighlight lang='bash'>
helm install postgresql myRepository/postgresql
</syntaxhighlight>


===Using an Explicit Repository URL with --repo===
A specific version can be requested with [[#--version|--version]].


A repository URL can be specified in-line in the install command line with --repo, without being previously added with [[Helm_repo#Add_a_New_Repository|helm repo add]]:
<syntaxhighlight lang='bash'>
helm install postgresql --version 1.2.3 myRepository/postgresql
</syntaxhighlight>


helm install --repo https&#58;//example.com/charts/ mynginx nginx
The charts available in the repository can be listed with:
<syntaxhighlight lang='bash'>
helm search repo myRepository
</syntaxhighlight>


=helm install and Dependencies=
=helm install and Dependencies=
<font color=darkgray>
<font color=darkgray>
If the chart has dependencies, they must be present in the [[Helm_Concepts#charts_Directory|charts/]] subdirectory at the time of the installation. <code>helm install</code> does not manage dependencies, <code>[[helm dependency]]</code> does. <code>helm install</code> performs some sanity checks, such as comparing the content of [[Helm_Chart_requirements.yaml|requirements.yaml]] with the content of the charts/ subdirectory and failing if requirements.yaml contains dependencies that are not in charts/. However, if a dependency is present in charts/ but not in requirements.yaml, it will be installed. For more details on dependencies and how they work, see: {{Internal|Helm_Dependencies#How_Helm_Dependencies_Work|How Helm Dependencies Work}}
If the chart has dependencies, they must be present in the [[Helm_Concepts#charts_Directory|charts/]] subdirectory at the time of the installation. <code>helm install</code> does not manage dependencies, <code>[[helm dependency]]</code> does. <code>helm install</code> performs some sanity checks, such as comparing the content of [[Helm_Chart_requirements.yaml|requirements.yaml]] with the content of the charts/ subdirectory and failing if requirements.yaml contains dependencies that are not in charts/. However, if a dependency is present in charts/ but not in requirements.yaml, it will be installed. For more details on dependencies and how they work, see: {{Internal|Helm_Dependencies#How_Helm_Dependencies_Work|How Helm Dependencies Work}}
TODO: [[#--dependency-update|--dependency-update]].
</font>
</font>
=<span id='Helm_install#Overriding_Default_Configuration'></span>Overriding Default Configuration or Providing New Cofiguration=
=<span id='Helm_install#Overriding_Default_Configuration'></span>Overriding Default Configuration or Providing New Cofiguration=
 
==<tt>-f|--values</tt>==
==-f|--values==


Default configuration can be overridden or new configuration can be specified with:
Default configuration can be overridden or new configuration can be specified with:
 
<font size=-1>
  helm install -f|--values <''configuration-overrides-file''.yaml> <''chart name''>
  helm install -f|--values <''configuration-overrides-file''.yaml> <''chart name''>
</font>
The <code>-f|--values</code> flag can be specified multiple times on the command line, and the rightmost value will take precedence. The effective configuration actually applied to the chart is computed by using the chart's <code>values.yaml</code> as base and then logically overlaying the configuration files from left to right. An overlay step leaves configuration paths that exist in the base but are not present in the overlay unchanged, overwrites configuration paths that are present both in the base and the overlay with the value present in the overlay, and adds new configuration paths that do not exist in the base but exist in the overlay. The process is repeated from left to right for all files present on command line.


The -f|--values flag can be specified multiple time on the command line, and the rightmost value will take precedence. For more details on Helm configuration see: {{Internal|Helm_Configuration#Values_Supplied_in_Files|Helm Configuration}}
For more details on Helm configuration see: {{Internal|Helm_Configuration#Values_Supplied_in_Files|Helm Configuration}}


==--set-file==
==<tt>--set-file</tt>==
<font size=-1>
--set-file stringArray   
</font>
"names" the content of a file, and makes it available from templates using the name. Set values from respective files specified via the command line. Multiple or separate values can be specified as <code>key1=path1,key2=path2)</code>


<font color=darkgray>TODO: Clarify use cases and file content syntax.</font>
<font color=darkkhaki>TODO:  
<font size=-1>
--set-file certificate=/path/to/the/file
</font>
then call <code>.Values.certificate</code> in the template to access the file's data.
</font>


For more details on Helm configuration see: {{Internal|Helm_Configuration#Values_Supplied_in_Files|Helm Configuration}}
For more details on Helm configuration see: {{Internal|Helm_Configuration#Values_Supplied_in_Files|Helm Configuration}}


==<span id='--set'></span>--set, --set--string==
==<span id='--set'></span><tt>--set, --set--string</tt>==
 
Individual configuration options can be specified with --set or --set-string.


Individual configuration options can be specified with <code>--set</code> or <code>--set-string</code>.
<font size=-1>
  helm install --set size=10 <''chart name''>
  helm install --set size=10 <''chart name''>
 
</font>
--set can be specified multiple times. If specified multiple time for the same value, the priority will be given to the last (right-most) set specified. For more details on overriding or specifying configuration see: {{Internal|Helm_Configuration#--set_Command_Line_Arguments|Helm Configuration}}
For more details on overriding or specifying configuration see: {{Internal|Helm_Configuration#--set_Command_Line_Arguments|Helm Configuration &#124; <tt>--set</tt> Command Line Arguments}}


=Overriding Tags and Conditions=
=Overriding Tags and Conditions=
Line 79: Line 131:


=Options=
=Options=
==--generate-name==


==Generic Options==
{{Internal|Helm_Operations#Generic_Options|Generic Options}}
==<tt>--generate-name</tt>==
Generate a release name:
Generate a release name:


  helm install --generate-name <''chart''>
  helm install --generate-name <''chart''>


If used, a name based on the chart name will be generated. If the chart is named "simplest", the generated name is similar to "simplest-1-1575057340".
If used, the user-supplied name must be omitted from the command line, and a name based on the chart name will be generated. If the chart is named "simplest", the generated name is similar to "simplest-1-1575057340".


==<span id='Dry_Run'></span>--dry-run==
==<span id='Dry_Run'></span><tt>--dry-run</tt>==


In this mode, the installation is simulated, without actually modifying anything on the Kubernetes cluster. Instead of installing the chart, the rendered template are sent to stdout so they can be inspected. Note that in this mode, it is not guaranteed that Kubernetes cluster will accept the generated manifest.
In this mode, the installation is simulated, without actually modifying anything on the Kubernetes cluster. Instead of installing the chart, the rendered template are sent to stdout so they can be inspected. Note that in this mode, it is not guaranteed that Kubernetes cluster will accept the generated manifest.
Line 97: Line 151:
  helm install --dry-run --debug ...
  helm install --dry-run --debug ...


==--debug==
==<tt>--debug</tt>==
  helm install --debug ...
  helm install --debug ...


Line 103: Line 157:
* [[Helm_Concepts#Effective_Values|user-supplied values and computed values]]
* [[Helm_Concepts#Effective_Values|user-supplied values and computed values]]


==--verify==
==<tt>--verify</tt>==


If --verify is used, the chart must have a provenance file, and the provenance file must pass all verification steps.
If --verify is used, the chart must have a provenance file, and the provenance file must pass all verification steps.


==--atomic==
==<tt>--atomic</tt>==


Installation process purges chart on fail. The [[#--wait|--wait]] flag will be set automatically if --atomic is used.
Installation process purges chart on fail. The [[#--wait|--wait]] flag will be set automatically if --atomic is used.


==--wait==
==<tt>--version</tt>==
==--version==
Specify the exact chart version to install. If this is not specified, the latest version is installed.
 
==<tt>--dependency-update==
 
Run [[Helm_dependency#Dependency_Update|helm dependency update]] before installing the chart. <font color=darkgray>TODO: more research here.</font>
 
==<tt>--name-template</tt>==
 
<font color=darkgray>Specify template used to name the release.</font>
 
==<tt>--output</tt>==
<font color=darkgray>Prints the output in the specified format. Allowed values: table, json, yaml (default table).</font>
==<tt>--wait</tt>==
If set, Helm will wait until all Pods, PVCs, Services, and minimum number of Pods of a Deployment, StatefulSet, or ReplicaSet are in a ready state before marking the release as successful. It will wait for as long as [[#--timeout|--timeout]]:
<syntaxhighlight lang='bash'>
helm instal ... --wait --timeout 60s
</syntaxhighlight>
If timeout occurs, the helm command will exit with a non-zero exit code, but the installation will continue and it may eventually succeed.
 
==<tt>--timeout</tt>==
The time to wait for any individual Kubernetes operation. The default value is 5 minutes.
<syntaxhighlight lang='bash'>
helm install --timeout 5m0s
</syntaxhighlight>
Also see [[#--wait|--wait]] above.
 
==<tt>--replace</tt>==
Also see [[Helm_uninstall#Keep_a_Resource_from_Being_Uninstalled|helm uninstall - Keep a Resource from being Uninstalled]] to understand implication on orphaned resources.
 
==<tt>--username, --password</tt>==
See [[#Absolute_URL|Absolute URL of a chart in a remote repository]] above.
==<tt>-n,--namespace</tt>==
Specifies the namespace scope for this installation.
<font size=-1>
helm install -n test blue ./src/mian/helm/blue
</font>
Note that the namespace must exist, otherwise Helm installation will fail:
<syntaxhighlight lang='text'>
Error: create: failed to create: namespaces "test" not found
</syntaxhighlight>
The namespace specified with -n can be retrieved in templates with the [[Helm_Templates#Release.Namespace|.Release.Namespace]] built-in object.
 
==<tt>--create-namespace</tt>==
Create the release namespace if not present.
 
=Scenarios=
==Using External Files during Installation==
<font color=darkgray>TODO:</font>
{{External|https://github.com/helm/helm/issues/3276}}
==Accessing Arbitrary Files inside Templates==
{{Internal|Helm Accessing Arbitrary Files inside Templates#Overview|Accessing Arbitrary Files inside Templates}}

Latest revision as of 19:02, 2 March 2022

External

Internal

Overview

helm install installs a chart, that may come from different sources, and creates a release:

helm install <release-name> <chart> [options]

The release name must be specified explicitly, and it must be the first argument. If it should be generated, --generate-name must be used instead of the release name.

Chart Sources

There are five types of chart sources:

  1. Unpacked charts on the local filesystem
  2. tgz packaged chart on the local filesystem
  3. Absolute URL of a chart archive in a remote repository
  4. Chart reference in a remote repository
  5. Chart is present in a locally cached repository, and specified by its chart name and repository prefix

Path to an Unpacked Chart

The chart argument of the install command can be an unpacked local chart directory. The directory name must be identical with the chart name specified in Chart.yaml).

helm install simplest ./playground/helm/simplest

Path to a Packaged Chart

helm install simplest ./simplest-1.0.0.tgz

Charts can be packaged with helm package command.

Where is the chart expanded locally?

Absolute URL

The absolute URL of a chart can be used as such:

helm install something https://example.com/charts/something-1.0.0.tgz

The version is built into the name of the chart, this is the default Helm versioning convention. The chart does not need to be cached in the local repository and the repository does not need to be cached locally with repo add.

If the remote repository is password-protected, the username and the password can be specified on the command line with:

helm install something https://example.com/charts/something-1.0.0.tgz --username <username> --password <password>

Where is the chart expanded locally?

Chart Reference

A chart available in a chart repository can be specified by a chart reference (which is the same thing as the chart name) when installed. There are two ways to specify a chart reference:

Using an Explicit Repository URL with --repo

A repository URL can be specified in-line in the install command line with --repo, without being previously added with helm repo add:

helm install --repo https://example.com/charts/ mynginx [--version 1.2.3] nginx

If --version is not specified, the latest present version is installed.

Where is the chart expanded locally?

Using a Repository Prefix

If the repository was added locally under a specific name ("myRepository" in the example below), then the chart can be referred by <repository-name>/<chart-name>. If no version specification is provided, the latest stable version of the chart will be installed:

helm install postgresql myRepository/postgresql

A specific version can be requested with --version.

helm install postgresql --version 1.2.3 myRepository/postgresql

The charts available in the repository can be listed with:

helm search repo myRepository

helm install and Dependencies

If the chart has dependencies, they must be present in the charts/ subdirectory at the time of the installation. helm install does not manage dependencies, helm dependency does. helm install performs some sanity checks, such as comparing the content of requirements.yaml with the content of the charts/ subdirectory and failing if requirements.yaml contains dependencies that are not in charts/. However, if a dependency is present in charts/ but not in requirements.yaml, it will be installed. For more details on dependencies and how they work, see:

How Helm Dependencies Work

TODO: --dependency-update.

Overriding Default Configuration or Providing New Cofiguration

-f|--values

Default configuration can be overridden or new configuration can be specified with:

helm install -f|--values <configuration-overrides-file.yaml> <chart name>

The -f|--values flag can be specified multiple times on the command line, and the rightmost value will take precedence. The effective configuration actually applied to the chart is computed by using the chart's values.yaml as base and then logically overlaying the configuration files from left to right. An overlay step leaves configuration paths that exist in the base but are not present in the overlay unchanged, overwrites configuration paths that are present both in the base and the overlay with the value present in the overlay, and adds new configuration paths that do not exist in the base but exist in the overlay. The process is repeated from left to right for all files present on command line.

For more details on Helm configuration see:

Helm Configuration

--set-file

--set-file stringArray     

"names" the content of a file, and makes it available from templates using the name. Set values from respective files specified via the command line. Multiple or separate values can be specified as key1=path1,key2=path2)

TODO:

--set-file certificate=/path/to/the/file

then call .Values.certificate in the template to access the file's data.

For more details on Helm configuration see:

Helm Configuration

--set, --set--string

Individual configuration options can be specified with --set or --set-string.

helm install --set size=10 <chart name>

For more details on overriding or specifying configuration see:

Helm Configuration | --set Command Line Arguments

Overriding Tags and Conditions

Use --set to override default tag and condition values at installation time.

Options

Generic Options

Generic Options

--generate-name

Generate a release name:

helm install --generate-name <chart>

If used, the user-supplied name must be omitted from the command line, and a name based on the chart name will be generated. If the chart is named "simplest", the generated name is similar to "simplest-1-1575057340".

--dry-run

In this mode, the installation is simulated, without actually modifying anything on the Kubernetes cluster. Instead of installing the chart, the rendered template are sent to stdout so they can be inspected. Note that in this mode, it is not guaranteed that Kubernetes cluster will accept the generated manifest.

helm install --dry-run ...

--dry-run can be combined with --debug for more information:

helm install --dry-run --debug ...

--debug

helm install --debug ...

The --debug flag displays:

--verify

If --verify is used, the chart must have a provenance file, and the provenance file must pass all verification steps.

--atomic

Installation process purges chart on fail. The --wait flag will be set automatically if --atomic is used.

--version

Specify the exact chart version to install. If this is not specified, the latest version is installed.

--dependency-update

Run helm dependency update before installing the chart. TODO: more research here.

--name-template

Specify template used to name the release.

--output

Prints the output in the specified format. Allowed values: table, json, yaml (default table).

--wait

If set, Helm will wait until all Pods, PVCs, Services, and minimum number of Pods of a Deployment, StatefulSet, or ReplicaSet are in a ready state before marking the release as successful. It will wait for as long as --timeout:

helm instal ... --wait --timeout 60s

If timeout occurs, the helm command will exit with a non-zero exit code, but the installation will continue and it may eventually succeed.

--timeout

The time to wait for any individual Kubernetes operation. The default value is 5 minutes.

helm install --timeout 5m0s

Also see --wait above.

--replace

Also see helm uninstall - Keep a Resource from being Uninstalled to understand implication on orphaned resources.

--username, --password

See Absolute URL of a chart in a remote repository above.

-n,--namespace

Specifies the namespace scope for this installation.

helm install -n test blue ./src/mian/helm/blue

Note that the namespace must exist, otherwise Helm installation will fail:

Error: create: failed to create: namespaces "test" not found

The namespace specified with -n can be retrieved in templates with the .Release.Namespace built-in object.

--create-namespace

Create the release namespace if not present.

Scenarios

Using External Files during Installation

TODO:

https://github.com/helm/helm/issues/3276

Accessing Arbitrary Files inside Templates

Accessing Arbitrary Files inside Templates