Usage and Examples

This document describes how to use the helm-maven-plugin from within your Maven build.

Overview

The helm-maven-plugin project makes working with Helm possible from inside Maven by supplying Maven plugins that make use of the microbean-helm project.

The project consists of several mojos that are fully documented in the Goals document.

Recipes

The following are recipes to follow to accomplish common Helm-oriented tasks as part of your Maven build.

Packaging a Helm Chart

Let’s say you have the contents of a Helm chart you want to package up. Let’s further assume you have them in src/helm/charts/your-project, a directory in a Maven project whose artifactId is your-project. That directory might look like this:

Chart.yaml
values.yaml
templates/
.helmignore
requirements.yaml
charts/

…or might contain fewer or more files in accordance with what a Helm chart needs to look like. Let’s also assume that you’re going to package this chart up with an intent to do something else with it (like install it) later, but you haven’t gotten that far yet.

You’ll want to archive this directory as a .tar.gz file as part of the build, and place the resulting packaged chart somewhere you can make use of it later. For this simplest of all cases, you could do this with the maven-assembly-plugin, but we’ll do it with the helm-maven-plugin as part of the generate-sources lifecycle phase as follows:

<plugin>
  <groupId>org.microbean</groupId>
  <artifactId>helm-maven-plugin</artifactId>
  <version>2.8.2.1.1.2</version>
  <executions>
    <execution>
      <id>Package your-project chart</id>
      <phase>generate-sources</phase> <!-- pick a suitable phase, though this seems good -->
      <goals>
        <goal>package</goal>
      </goals>
    </execution>
  </executions>
</plugin>

This example uses a minimal amount of configuration. It takes advantage of the fact that by default the package goal will read from your src/helm/charts/${project.artifactId} directory and will write a file named ${project.build.directory}/generated-sources/helm/charts/${project.artifactId}.tgz.

Here is the same stanza, explicitly configured this time:

<plugin>
  <groupId>org.microbean</groupId>
  <artifactId>helm-maven-plugin</artifactId>
  <version>2.8.2.1.1.2</version>
  <executions>
    <execution>
      <id>Package your-project chart</id>
      <phase>generate-sources</phase> <!-- pick a suitable phase, though this seems good -->
      <goals>
        <goal>package</goal>
      </goals>
      <configuration>
        <chartContentsUri>file:${project.basedir}/src/helm/charts/${project.artifactId}</chartContentsUri>
        <chartTargetUri>file:${project.build.directory}/generated-sources/helm/charts/${project.artifactId}.tgz</chartTargetUri>
      </configuration>
    </execution>
  </executions>
</plugin>

Note that the chartContentsUri and chartTargetUri configuration elements are actually URIs. This permits writing a chart archive to an FTP or HTTP server, for example.

Installing a Chart to Create a Release

Once you have a Helm chart in packaged or unpackaged form, you need to read it in and send it to Tiller, thus creating a release.

To do this, you use the install goal. install needs to know where your chart is, and needs to know how to connect to your Kubernetes cluster. The configuration required below is to accomplish those goals.

Here is a minimally configured stanza that will take a chart from file:${project.build.directory}/generated-sources/helm/charts/${project.artifactId} (note that the default is a directory, not a file, i.e. created perhaps by way of [Maven resources][maven-resources] or some other mechanism, and will connect to the cluster using all the mechanisms available to the DefaultKubernetesClient class:

<plugin>
  <groupId>org.microbean</groupId>
  <artifactId>helm-maven-plugin</artifactId>
  <version>2.8.2.1.1.2</version>
  <executions>
    <execution>
      <id>Install your-project chart</id>
      <phase>deploy</phase> <!-- pick a suitable phase -->
      <goals>
        <goal>install</goal>
      </goals>
    </execution>
  </executions>
</plugin>

This example uses a minimal amount of configuration. It takes advantage of the fact that by default the install goal will read from your ${project.build.directory}/generated-sources/helm/charts/${project.artifactId} directory, if it exists, and will connect to your Kubernetes cluster using all the mechanisms available to the DefaultKubernetesClient class (including a ~/.kube/config file if you have one). Since no explicit release name is specified, the release will be named by Tiller according to the rules embodied by this Github project.

Here is the same stanza, this time fully configured, and specifying a release name, and specifying a value for your made-up chart’s hypothetical frobnicationInterval setting:

<plugin>
  <groupId>org.microbean</groupId>
  <artifactId>helm-maven-plugin</artifactId>
  <version>2.8.2.1.1.2</version>
  <executions>
    <execution>
      <id>Install your-project chart</id>
      <phase>deploy</phase> <!-- pick a suitable phase -->
      <goals>
        <goal>install</goal>
      </goals>
      <configuration>
        <chartUrl>file:${project.build.directory}/generated-sources/helm/charts/${project.artifactId}</chartUrl>
        <releaseName>your-first-release</releaseName>
        <valuesYaml><[!CDATA[frobnicationInterval: 37]]></valuesYaml>
      </configuration>
    </execution>
  </executions>
</plugin>

Note in particular the <valuesYaml> setting; CDATA will help you here since most non-trivial YAML requires strict indentation.

In the <configuration> element, you could, if you wanted, set up a custom Config object, by specifying a <clientConfiguration> child element and following the rules of Maven plugin instantiation.

Listing the Contents of a Release

This example shows you how to make use of a release that has already been installed into your Kubernetes cluster. The key thing to look at here is the listeners-oriented stanza, which shows how you can customize the basic behavior. The behavior here is of the log-to-STDOUT variety, but if you supplied your own listener you could do more interesting things:

<plugin>
  <groupId>org.microbean</groupId>
  <artifactId>helm-maven-plugin</artifactId>
  <version>2.8.2.1.1.2</version>
  <executions>
    <execution>
      <id>List the contents of your-first-release</id>
      <phase>test</phase> <!-- pick a suitable phase -->
      <goals>
        <goal>content</goal>
      </goals>
      <configuration>
        <releaseName>your-first-release</releaseName>
        <releaseContentListeners>
          <abstractReleaseContentListener/>
        </releaseContentListeners>
      </configuration>
    </execution>
  </executions>
</plugin>

Note the <abstractReleaseContentListener/> element, which follows the rules of Maven plugin configuration, which allows for customizable behavior. Here, the org.microbean.helm.maven.AbstractReleaseContentListener class is instantiated.

Uninstalling a Release

Building on what we’ve learned, here’s a stanza that uninstalls a release using the uninstall goal:

<plugin>
  <groupId>org.microbean</groupId>
  <artifactId>helm-maven-plugin</artifactId>
  <version>2.8.2.1.1.2</version>
  <executions>
    <execution>
      <id>Uninstall your-first-release</id>
      <phase>test</phase> <!-- pick a suitable phase -->
      <goals>
        <goal>uninstall</goal>
      </goals>
      <configuration>
        <purge>true</purge>
        <releaseName>your-first-release</releaseName>
      </configuration>
    </execution>
  </executions>
</plugin>

microBean Helm Maven Plugin