Helm Maven Plugin

This is a Maven plugin for testing, packaging and uploading HELM charts. "HELM is a tool for managing Kubernetes charts. Charts are packages of pre-configured Kubernetes resources."

Visit https://docs.helm.sh for detailed information.

Currently the upload to ChartMuseum, Artifactory and Nexus is supported.

Helm v3

From version 5.0 Helm v3 is required. There is no longer support for Helm v2. For convenience reasons the stable repo is added by default.

Helm v2 users can still use plugin version 4.13.

Why?

Currently (October 2017) there is no simple Maven plugin to package existing HELM charts.

How?

By default, the plugin automatically downloads Helm at the specified version. You can also manually specify the download URL. Next to that it is possible to specify a local Helm binary. In all cases Helm will be executed in the background.

Add following dependency to your pom.xml:

<dependency>
  <groupId>io.kokuwa.maven</groupId>
  <artifactId>helm-maven-plugin</artifactId>
  <version>6.16.0</version>
</dependency>

Configuration Examples

Helm URL Auto Detection

The default setting is to construct the Helm download URL based upon the detected OS and architecture:

<build>
  <plugins>
    <plugin>
      <groupId>io.kokuwa.maven</groupId>
      <artifactId>helm-maven-plugin</artifactId>
      <version>6.16.0</version>
      <configuration>
        <chartDirectory>${project.basedir}</chartDirectory>
        <chartVersion>${project.version}</chartVersion>
      </configuration>
    </plugin>
  </plugins>
</build>

If you leave helmVersion and helmDownloadUrl empty the plugin will determine the latest version based on [https://api.github.com/repos/helm/helm/releases/latest].

Usage with Downloaded Binary

<build>
  <plugins>
  ...
    <plugin>
      <groupId>io.kokuwa.maven</groupId>
      <artifactId>helm-maven-plugin</artifactId>
      <version>6.16.0</version>
      <configuration>
        <chartDirectory>${project.basedir}</chartDirectory>
        <chartVersion>${project.version}</chartVersion>
        <!-- This is the related section when using binary download -->
        <helmDownloadUrl>https://get.helm.sh/helm-v3.8.1-linux-amd64.tar.gz</helmDownloadUrl>
      </configuration>
    </plugin>
  ...
  </plugins>
</build>

Usage with Local Binary

When useLocalHelmBinary is enabled, the plugin by default will search for the helm executable in PATH:

<build>
  <plugins>
  ...
    <plugin>
      <groupId>io.kokuwa.maven</groupId>
      <artifactId>helm-maven-plugin</artifactId>
      <version>6.16.0</version>
      <configuration>
        <chartDirectory>${project.basedir}</chartDirectory>
        <chartVersion>${project.version}</chartVersion>
        <!-- This is the related section to use local binary with auto-detection enabled. -->
        <useLocalHelmBinary>true</useLocalHelmBinary>
      </configuration>
    </plugin>
  ...
  </plugins>
</build>

The following is an example configuration that explicitly sets the directory in which to look for the helm executable, and disables the auto-detection feature:

<build>
  <plugins>
  ...
    <plugin>
      <groupId>io.kokuwa.maven</groupId>
      <artifactId>helm-maven-plugin</artifactId>
      <version>6.16.0</version>
      <configuration>
        <chartDirectory>${project.basedir}</chartDirectory>
        <chartVersion>${project.version}</chartVersion>
        <!-- This is the related section to use local binary with auto-detection disabled. -->
        <useLocalHelmBinary>true</useLocalHelmBinary>
        <autoDetectLocalHelmBinary>false</autoDetectLocalHelmBinary>
        <helmExecutableDirectory>/usr/local/bin</helmExecutableDirectory>        
      </configuration>
    </plugin>
  ...
  </plugins>
</build>

Configure Plugin to Use Credentials from settings.xml for Upload

<build>
  <plugins>
  ...
    <plugin>
      <groupId>io.kokuwa.maven</groupId>
      <artifactId>helm-maven-plugin</artifactId>
      <version>6.16.0</version>
      <configuration>
        <chartDirectory>${project.basedir}</chartDirectory>
        <chartVersion>${project.version}</chartVersion>
        <!-- This is the related section to configure upload repos -->
        <uploadRepoStable>
            <name>stable-repo</name>
            <url>https://repo.example.com/artifactory/helm-stable</url>
            <type>ARTIFACTORY</type>
        </uploadRepoStable>
        <uploadRepoSnapshot>
            <name>snapshot-repo</name>
            <url>https://my.chart.museum:8080/api/charts</url>
            <type>CHARTMUSEUM</type>
        </uploadRepoSnapshot>
        <helmDownloadUrl>https://get.helm.sh/helm-v3.8.1-linux-amd64.tar.gz</helmDownloadUrl>
      </configuration>
    </plugin>
  ...
  </plugins>
</build>

More Complex Example

<build>
  <plugins>
  ...
    <plugin>
      <groupId>io.kokuwa.maven</groupId>
      <artifactId>helm-maven-plugin</artifactId>
      <version>6.16.0</version>
      <configuration>
        <chartDirectory>${project.basedir}</chartDirectory>
        <chartVersion>${project.version}</chartVersion>
        <uploadRepoStable>
            <name>stable-repo</name>
            <url>https://repo.example.com/artifactory/helm-stable</url>
            <type>ARTIFACTORY</type>
            <username>foo</username>
            <password>bar</password>
        </uploadRepoStable>
        <uploadRepoSnapshot>
            <name>snapshot-repo</name>
            <url>https://my.chart.museum/api/charts</url>
            <type>CHARTMUSEUM</type>
        </uploadRepoSnapshot>
        <helmDownloadUrl>https://get.helm.sh/helm-v3.8.2-linux-amd64.tar.gz</helmDownloadUrl>
        <registryConfig>~/.config/helm/registry.json</registryConfig>
        <repositoryCache>~/.cache/helm/repository</repositoryCache>
        <repositoryConfig>~/.config/helm/repositories.yaml</repositoryConfig>
        <!-- Add a gpg signature to the chart -->
        <keyring>~/.gpg/secring.gpg</keyring>
        <key>MySigningKey</key>
        <passphrase>SecretPassPhrase</passphrase>
        <!-- Lint with strict mode -->
        <lintStrict>true</lintStrict>
        <!-- Disable adding of default repo stable https://charts.helm.sh/stable -->
        <addDefaultRepo>false</addDefaultRepo>
        <!-- Exclude a directory to avoid processing -->
        <excludes>
          <exclude>${project.basedir}/excluded</exclude>
          <exclude>${project.basedir}/**/excluded*</exclude>
        </excludes>
        <!-- Add an additional repo -->
        <helmExtraRepos>
          <helmRepo>
            <name>kokuwa</name>
            <url>https://kokuwa.github.io</url>
          </helmRepo>
        </helmExtraRepos>
        <!-- extra value settings for the lint command -->
        <values>
          <overrides>
            <component1.install.path>/opt/component1</component1.install.path>
          </overrides>
          <yamlFile>${project.basedir}/src/test/resources/myOverrides.yaml</yamlFile>
          <yamlFiles>
              <yamlFile>${project.basedir}/src/test/resources/myOverrides-1.yaml</yamlFile>
              <yamlFile>${project.basedir}/src/test/resources/myOverrides-2.yaml</yamlFile>
          </yamlFiles>
        </values>
      </configuration>
    </plugin>
  ...
  </plugins>
</build>

Features

• Package Helm charts from standard folder structure
• Test Helm charts (Helm lint)
• Recursive chart detection (subcharts)
• Helm does not need to be installed
• Upload to ChartMuseum or Artifactory
• Repository names are interpreted as server IDs to retrieve basic authentication from server list in settings.xml.

Usage

Goals

• helm:init initializes Helm by downloading a specific version
• helm:dependency-build resolves the chart dependencies
• helm:dependency-update verifies that the required chart dependencies are present
• helm:package packages the given charts (chart.tar.gz)
• helm:lint tests the given charts
• helm:template Locally render templates
• helm:dry-run simulates an install
• helm:upload upload charts via HTTP PUT
• helm:registry-login login into docker registry
• helm:registry-logout login from docker registry
• helm:push push charts to OCI (docker registry)
• helm:upgrade upgrade an already existing installation

Configuration

Packaging with the Helm Lifecycle

To keep your pom files small you can use 'helm' packaging. This binds helm:init to the initialize phase, helm:dependency-build to the process-resources phase, helm:lint to the test phase,helm:package to the package phase and helm:upload to the deploy phase.

<pom>
  <artifactId>my-helm-charts</artifactId>
  <version>0.0.1</version>
  <packaging>helm</packaging>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>io.kokuwa.maven</groupId>
        <artifactId>helm-maven-plugin</artifactId>
        <!-- Mandatory when you use a custom lifecycle -->
        <extensions>true</extensions>
        <configuration>
          ...
        </configuration>
      </plugin>
    </plugins>
    ....
  </build>
</pom>