Gradle Helm Plugin

This plugin does little more than add the plugin library to your build’s classpath so you can define tasks for various Helm CLI commands. It creates the helm DSL block which you can use to configure common settings for all tasks, like the Helm home path and the Kubecontext. Apart from this, it does not create any tasks automatically.

Use this if you want to use Helm CLI commands directly as tasks, without any of the declarative DSL that the helm plugin offers.

All the other plugins imply helm-commands, so you don’t need to apply this plugin if you use any of the others.

This is the main plugin of the suite. It enables a variety of extra DSL blocks inside helm, for example charts and repositories.

Use this plugin to publish charts to a remote chart repository like ChartMuseum.

It enables the helm.publishing DSL block and adds publishing tasks for each chart.

Use this plugin to manage Helm releases (install/upgrade/uninstall) on a remote Kubernetes cluster.

It enables the helm.releases DSL block, where you can declare your releases using Gradle DSL, referencing either Helm charts built using the other projects, or existing charts from a Helm repository.

The following properties can be set on the helm extension in the Gradle build script.

Starting with Helm 3, Helm does not have a "helm home" directory anymore, and dropped the need for a call to helm init before working with Helm. Instead, local Helm directories are governed by 3 environment variables, which can be configured in the Gradle helm extension. By default, these directories are set to paths inside the Gradle project, so that any helm invocation from the Gradle build is independent from the Helm configuration present on the local machine.

It is also possible to set these properties via gradle.properties or pass them using the -P flag on the Gradle command line (see Configuration from Project Properties).

See the Helm docs for details about how XDG base directories are used by the Helm CLI.

As an alternative to using a locally installed Helm client, the plugin can automatically download a Helm client distribution from the official Helm website. This allows build scripts to be more independent from the environment found on the local machine where the Gradle build runs.

The download can be configured either through the helm.downloadClient DSL block or through project properties (e.g. in the gradle.properties file). Project properties have the advantage of being automatically inherited by subprojects, and are easier to adapt for different build environments.

The following example shows how the download can be configured in the build script:

The following example shows how the download can be configured using the gradle.properties file:

From the above chart definition, a number of tasks will be created automatically:

In addition, the plugin creates a task named helmPackage that will depend on all charts' package task, so it can be used to build all the project’s charts. Most of the time, you will just call helmPackage to build your charts.

The following configurations and artifacts will be created for each chart:

For the typical case of building a single Helm chart in a project, the Helm plugin provides some useful conventions so that a single "main" chart can be built with a minimum of configuration.

If you don’t define any charts in the helm.charts DSL block, and your project contains a file src/main/helm/Chart.yaml, then by convention a chart named main will be defined automatically, equivalent to the following:

The main chart will not be instantiated if you define any other charts; however you can create the main chart explicitly if you would like to use it anyway:

Of course, instead of defining multiple charts in one Gradle project, you can also have a multi-project build where each subproject defines a single main chart. That way, you can take advantage of the main chart convention in every project.

However, note that the values defined in the helm block are not automatically inherited by subprojects. If you want to define your Helm CLI options in one central place, you can add a subprojects clause in the root project:

Each chart defined in the DSL has an extraFiles property which is a Gradle CopySpec. It allows you to copy additional files into the chart when it is built.

In most cases, the source files of the chart should be put into the chart source directory. The extraFiles mechanism is primarily designed for cases where some parts of the chart need to be dynamically generated during the Gradle build.

If a chart repository requires authentication, you can configure credentials using the credentials block. It works very similarly to other places in Gradle where credentials are used.

In addition to username/password credentials, certificate credentials based on PEM files are also supported:

The filtering is enabled by default. You can set the filtering.enabled property to false if you would not like the chart to be filtered. This can be done either on the project level or the chart level:

By default, filtering applies only to the Chart.yaml, requirements.yaml and values.yaml files directly in the chart directory, but not to any templates or other files in the chart.

The filtering block has a filePatterns property which holds the (Ant-style) patterns of files to be filtered. If this list is empty, it is equivalent to the pattern * so all files in the chart will be filtered.

Use the filtering.values property to define additional values to be available in filtering expressions. Again, values may be specified in the project-level filtering block, as well as on a filtering block for an individual chart. Project-level and chart-level values are merged, with the chart-level values having precedence if a value is defined in both places.

You can pass values to the linter using the values, fileValues and valueFiles.

Passing values to helm lint may be necessary to avoid warnings if you use the required function in your Helm templates (see Helm issue #2347). Also, it can be useful if you have conditional templates which would not be rendered when using the default values from values.yaml.

Values and value files defined in the global lint block are automatically inherited by each chart; however a chart can add additional values or value files.

You can disable the lint step altogether by setting the lint.enabled property to false. This works on a global as well as on a chart level. (Again, the chart setting is inherited from the global setting).

Many charts use conditional expressions like {{ if }} …​ {{ else }} to include parts of a template based on the supplied values. This can make it difficult to completely lint the chart in one go, because often there is no combination of values that can be supplied to the linter that would really render everything in the chart.

The plugin addresses this by supporting multiple linter configurations: Inside the lint block for a chart, you have a container for configurations, and each configuration can have its own values, fileValues and valueFiles. Each lint configuration will give rise to a separate HelmLint task that will run the linter with the specified input.

The values, fileValues and valueFiles for each lint configuration are merged with (and can selectively override) the corresponding properties from the chart’s lint block and the global lint block, allowing you to have a hierarchy of common and more specialized values.

Now, running helmLint<Chart>Chart (or other tasks that depend on it, such as helmPackage) will invoke helm lint for each configuration, by way of a separate HelmLint task per configuration that it depends on.

You can also run the linter for a single configuration using the helmLint<Chart>Chart<Configuration>.

To declare a dependency from one chart onto another, use the dependencies block inside a chart.

The following example defines two charts foo and bar, and declares a dependency from bar onto foo:

Instead of using the name, it is also possible to refer directly to the HelmChart DSL object in the dependency:

Since the dependency resolution done by this plugin is simply a package-and-extract operation, it is not necessary to mention the dependency in your Chart.yaml file (or requirements.yaml for API version v1). However, for some advanced configuration of the dependency (e.g. when using an alias or import-values), you can still declare it. In that case, you should omit the repository so that helm dependency update will not attempt to resolve it from a chart repository:

When running helm dependency update (via the helmUpdateBarDependencies task), it will output something like:

If you have a Gradle multi-project build, chart dependencies can also refer to charts built by other projects.

Use the project parameter when adding a dependency, in addition to the chart parameter:

The chart parameter defaults to "main", so if a dependency references another project’s main chart, the chart parameter can be omitted:

A chart may have external dependencies (to be resolved by helm dependency update) in addition to the dependencies managed by the Gradle plugin.

At the point when helm dependency update is run, the resolved charts from Gradle will already be present in the charts/ sub-directory, and helm dependency update should be smart enough to ignore them.

The dependency resolution mechanism described here is primarily intended for resolving dependencies on charts in the same Gradle project, or in another Gradle project that is part of the same multi-project build. For dependencies on external charts, it is best to publish those to a chart repository (for example, using the helm-publish plugin) and then use Helm’s standard dependency mechanism to resolve them.

However, in some cases you might prefer to use Gradle to resolve those dependencies. For example, if you already have a Maven repository for your internal artifacts, and only a few common charts to be used as dependencies, it might be more convenient to publish those charts to your Maven repository instead.

The Helm plugin internally creates a dependency configuration called helm<Chart>Dependencies, for example helmFooDependencies for a chart named foo. You can use Gradle’s standard dependencies block to add external module dependencies to this configuration. It is required that these resolve to a single tar.gz compressed file, like the one that is produced by helm package.

When you declare a chart in your build script using the helm.charts construct, the plugin will register a task for each chart named helmRender<Name>Chart to invoke helm template on the packaged chart. The rendered manifests will be placed in helm/render/<chart>/default/ beneath the project’s build directory.

For example, given the following build script:

Then there will be a task named helmRenderAwesomeChart that will render the templates of the chart into build/helm/render/awesome/default.

The helmRender task will render all charts in the project. This can be useful if you have multiple charts defined in the project, or simply for the convenience of a short task name.

Each chart has a renderings container where you can fine-tune the renderings. The options of a rendering correspond with the arguments to the helm template invocation.

A rendering named default will automatically be available for each chart (if you don’t create one named default yourself), and it starts out with a basic configuration. You can adjust the default rendering in your script, for example to add some values:

Additional renderings can be added, for example to supply a different set of values to catch all conditional branches in your template logic:

The following tasks will execute the renderings:

The output for each rendering (i.e. the rendered manifests) will be placed in the build/helm/render/main/<name> directory. You can access the output directory with the outputDir property of each rendering, for example to configure other tasks that perform further work on the output of helm template.

The following repository types are supported:

Most likely, a chart repository will require some credentials for write access. You can configure credentials in the same way as for repositories:

By default, all charts defined in the project will be published. You can prevent this for a specific chart by setting its publish property to false:

For each release defined in the releases block, the following Gradle tasks will be generated:

In addition, there will be the following tasks to manage all releases in the project at once:

You can influence the order in which releases are installed or uninstalled by calling mustInstallAfter on the release. This is similar to what the mustRunAfter method from the Gradle DSL does for tasks: mustInstallAfter does not express a "hard" dependency on another release; instead it only influences the order in which their install tasks are called when both are requested to be installed in the current Gradle invocation.

Currently it is not possible to refer to releases in another Gradle project.

Similarly, influencing the order of uninstalls is also possible using the mustUninstallAfter method. Note that mustInstallAfter and mustUninstallAfter are completely independent; neither of them implies the other. If you want to express both installation and uninstallation ordering between two releases, you must do so explicitly by calling both mustInstallAfter and mustUninstallAfter:

The dependsOn property and method on a release allows you to indicate that a certain release depends on another release. As a consequence, when release A depends on release B, then release B will automatically installed before release A is installed, and uninstalled after release A is uninstalled.

The installation task that the plugin creates for each release, named helmInstall<Name>Release, will perform an install or upgrade based on the following logic:

Sometimes it is necessary to execute other task dependencies before a release can be installed. For example, when using Helm and jib together, you may want to call the jib task that builds your Docker image before you install the release.

You can declare such dependencies using the installDependsOn property or method on the release:

A frequent requirement when using Helm is to designate different release targets, with target-specific configuration applied to each chart depending on the target. For example, you might use release targets to model different server environments, stages of development (e.g. dev / test / production), or different variants of installation.

Often you want to declare multiple releases in your build script, but you want to selectively install only a subset of them. For example, when installing a set of applications in a local cluster, you might want to include infrastructure components like a database or message queue as well, but exclude them when installing to production because they can be assumed to be managed externally.

The helm-releases plugin offers a powerful tagging mechanism for such setups:

In the following example, we create two releases myApp and mongodb, and assign them tags application and database, respectively:

Now we can specify a select expression in our release targets to configure which releases should be installed to each target. In its simplest form, the select expression is just the name of a tag, which must then be present on the release. The expression * (which is also the default) matches any release.

You can combine tags in a select expression using the operators & (and), | (or) and ! (not). Comma and space also mean "or". Some examples:

In addition to setting selectTags on a release target, you can also set the property helm.release.tags on the command line to further narrow down the set of releases per-build.

INFO: If both helm.release.tags and the active release target contain a select expression for tags, they will be both combined using "and". This means that a release will only be installed if it matches both the helm.release.tags expression and the selectTags expression of the release target.

Helm includes a facility for testing charts after they have been installed on a remote cluster. Tests are Kubernetes Job resources with an annotation helm.sh/hook: test. See the Chart Tests section in the Helm documentation for details.

The helm-releases plugin integrates chart testing by exposing a HelmTest task for every release that is declared in the build script. Like other release options, tests can be configured (or even completely disabled) for a release, a release target, or a specific combination of the two.

For each release/target combination, the helm-releases plugin will provide a task named helmStatus<Release>On<Target> to check the status of the release. Internally, this will map to a call of helm status <release-name>.

For example, to check the status of the "awesome" release on the "local" target:

In addition, you can also check the status of a release on the active target (as indicated by the helm.release.target project property) using the helmStatus<Release> task:

You can configure repositories entirely from Gradle properties — just the presence of a set of helm.repositories.<name>.<xyz> properties will automatically create a corresponding repository.