Helm Extension for Quarkus

Helm is a package and install manager that standardizes and simplifies packaging and deployment of containerized applications with Kubernetes.

Under the hood, the Quarkus Helm extension uses Dekorate to generate the Helm chart manifests at build time.

Before getting started, make sure you’re using the right Quarkus Helm version that is compatible with the Quarkus version you’re using in your project. See the following table to see the compatibility among versions:

Quarkus Helm Version Quarkus Version

1.2.6

Quarkus 3.16+

1.2.5

Quarkus 3.5.0+

1.2.4

Quarkus 3.5.0+

1.2.3

Quarkus 3.5.0+

1.2.2

Quarkus 3.5.0+

1.2.1

Quarkus 3.5.0+

1.2.0

Quarkus 3.5.0+

1.1.0

Quarkus 3.3.0+

1.0.9

Quarkus 3.2.0+

1.0.8

Quarkus 3.1.0+

1.0.7

Quarkus 3.1.0+

1.0.6

Quarkus 3.0.0+

1.0.5

Quarkus 3.0.0+

1.0.4

Quarkus 3.0.0+

1.0.3

Quarkus 3.0.0+

1.0.1

Quarkus 3.0.0+

1.0.0

Quarkus 3.0.0.Alpha - Quarkus 3.0.0.Beta

0.2.9

Quarkus 2.16+

0.2.8

Quarkus 2.16+

0.2.7

Quarkus 2.16+

0.2.6

Quarkus 2.16+

0.2.5

Quarkus 2.16+

0.2.4

Quarkus 2.16+

0.2.3

Quarkus 2.16+

0.2.2

Quarkus 2.16+

0.2.1

Quarkus 2.14.2 - 2.14.3 - 2.15+

0.2.0

Quarkus 2.14.0 - 2.14.1

0.1.2

Quarkus 2.13

0.1.1

Quarkus 2.13

0.1.0

Quarkus 2.13

0.0.7

Quarkus 2.13

0.0.6

Quarkus 2.12

Apart from all the features supported by the Quarkus Helm extension, in this documentation you will also find several examples about how to use this extension in:

Using the Helm Extension in Kubernetes

To complete this guide, you need:

  • roughly 10 minutes

  • JDK 11+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.8.1+

  • Docker installed

  • Helm command line installed

  • Have connected/logged to a Kubernetes cluster

Create a Quarkus application with the Helm extension

The Quarkus Helm extension will generate the Helm Chart of a Quarkus application.

In this example, we’ll create a Quarkus application with the Quarkus Helm extension by running the following command:

mvn io.quarkus.platform:quarkus-maven-plugin:3.17.0:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=helm-quickstart \
    -DclassName="org.acme.quickstart.GreetingResource" \
    -Dpath="/hello" \
    -Dextensions="resteasy-reactive,helm"
cd helm-quickstart

If you already have your Quarkus project configured, you can add the helm extension to your project by running the following command in your project base directory:

./mvnw quarkus:add-extension -Dextensions="helm"

This command will add the following dependency to your pom.xml file:

<dependency>
    <groupId>io.quarkiverse.helm</groupId>
    <artifactId>quarkus-helm</artifactId>
    <version>1.2.6</version>
</dependency>

After you add the Quarkus Helm extension to your project, you can now generate the Helm resources by running the following Maven command:

./mvnw clean package

When using the Quarkus Helm extension, the Quarkus Kubernetes extension will be transitively loaded as well. So, the helm resources will include the following templates at target/helm/kubernetes/<chart name>/:

  • Chart.yaml

  • values.yaml

  • /charts

  • /templates

  • /templates/deployment.yaml

  • /templates/ingress.yaml

  • /templates/service.yaml

  • /templates/NOTES.txt

The <chart name> is set from either the property quarkus.helm.name or the @HelmChart annotation or the Quarkus application.

Chart Installation

Let’s now see how to install the previously generated Helm resources on a Kubernetes cluster.

First, you need to build the application container image and push it into a container registry. For doing this, Quarkus provides some container image extensions to ease up this step. Let’s add the Quarkus container image docker extension in this example:

./mvnw quarkus:add-extension -Dextensions="container-image-docker"

Now, we can generate the Helm resources and build/push the application container image at once by running the following Maven command:

./mvnw clean package -Dquarkus.container-image.build=true -Dquarkus.container-image.push=true -Dquarkus.container-image.registry=<your container registry> -Dquarkus.container-image.group=<your container registry namespace>

Make sure the application container image is public and available to be used by your Kubernetes cluster.

Finally, let’s use Helm to deploy it into the cluster:

helm install helm-example ./target/helm/kubernetes/<chart name>

The above command will use the default values, which are located in ./target/helm/kubernetes/<chart name>/values.yaml. To override the default values, pass as parameter you own value file --values /path/to/another.values.yaml or set them using --set key1=val1 --set key2=val2.

How can I update my deployment?

  • Either via the upgrade option of Helm command line:

After making changes to your project and regenerating the Helm resources and the application container image, then you need to upgrade your deployment:

helm upgrade helm-example ./target/helm/kubernetes/<chart name>

  • Or via the set option of Helm command line:

helm upgrade helm-example ./target/helm/kubernetes/<chart name> --set app.replicas=1

How can we delete my deployment?

helm uninstall helm-example

Using the Helm Extension in OpenShift

To complete this guide, you need:

  • roughly 10 minutes

  • JDK 11+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.8.1+

  • Docker installed

  • Helm command line installed

  • Have connected/logged to a OpenShift cluster

Create a Quarkus application with the Helm extension

The Quarkus Helm extension will generate the Helm Chart of a Quarkus application.

In this example, we’ll create a Quarkus application with the Quarkus Helm and the Quarkus OpenShift extensions by running the following command:

mvn io.quarkus.platform:quarkus-maven-plugin:3.17.0:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=helm-quickstart \
    -DclassName="org.acme.quickstart.GreetingResource" \
    -Dpath="/hello" \
    -Dextensions="resteasy-reactive,openshift,helm"
cd helm-quickstart

If you already have your Quarkus project configured, you can add the helm extension to your project by running the following command in your project base directory:

./mvnw quarkus:add-extension -Dextensions="helm"

This command will add the following dependency to your pom.xml file:

<dependency>
    <groupId>io.quarkiverse.helm</groupId>
    <artifactId>quarkus-helm</artifactId>
    <version>1.2.6</version>
</dependency>

If you want to expose your application in OpenShift, you also need to enable the Route resource by adding the following configuration in your application properties:

quarkus.openshift.route.expose=true

And since the Quarkus OpenShift extension will also generate the Kubernetes manifests, you need to explicitly specify the deployment target you want to use:

quarkus.helm.repository.deployment-target=openshift

Once we add the Quarkus Helm extension to your project, you can now generate the Helm resources by running the following Maven command:

./mvnw clean package

Then the helm resources will include the following templates at target/helm/openshift/<chart name>/:

  • Chart.yaml

  • values.yaml

  • /charts

  • /templates

  • /templates/deployment.yaml

  • /templates/route.yaml

  • /templates/service.yaml

  • /templates/NOTES.txt

The <chart name> is set from either the property quarkus.helm.name or the @HelmChart annotation or the Quarkus application.

Chart Installation

Let’s now see how to install the previously generated Helm resources on a OpenShift cluster.

First, you need to build the application container image and push it into a container registry. For doing this, Quarkus provides some container image extensions to ease up this step. Let’s add the Quarkus container image docker extension in this example:

./mvnw quarkus:add-extension -Dextensions="container-image-docker"

Now, we can generate the Helm resources and build/push the application container image at once by running the following Maven command:

./mvnw clean package -Dquarkus.container-image.builder=docker -Dquarkus.container-image.build=true -Dquarkus.container-image.push=true -Dquarkus.container-image.registry=<your container registry> -Dquarkus.container-image.group=<your container registry namespace>

Make sure the application container image is public and available to be used by your Kubernetes cluster.

Finally, let’s use Helm to deploy it into the cluster:

helm install helm-example ./target/helm/openshift/<chart name>

The above command will use the default values, which are located in ./target/helm/openshift/<chart name>/values.yaml. To override the default values, pass as parameter you own value file --values /path/to/another.values.yaml or set them using --set key1=val1 --set key2=val2.

How can I update my deployment?

  • Either via the upgrade option of Helm command line:

After making changes to your project and regenerating the Helm resources and the application container image, then you need to upgrade your deployment:

helm upgrade helm-example ./target/helm/openshift/<chart name>

  • Or via the set option of Helm command line:

helm upgrade helm-example ./target/helm/openshift/<chart name> --set app.replicas=1

How can we delete my deployment?

helm uninstall helm-example

Generating the Helm Values file

By default, the Quarkus Helm extension will generate the Helm values file (values.yaml) by mapping the following pre-configured properties:

  • The Kubernetes/Openshift replicas

  • The Kubernetes/Openshift image

  • The Kubernetes/Openshift Env Var values (only for plain values - secrets or configmaps are not supported yet)

  • The Kubernetes ingress host

  • The Openshift S2i builder image

If you would like to automatically map any other pre-configured properties, please submit a feature request at this repository, and we’ll work on it.

For example, if you set 3 replicas for your deployment:

quarkus.helm.name=my-chart
quarkus.helm.description=Description of my Chart

# Set replicas to 3
quarkus.kubernetes.replicas=3

The extension will generate the next Helm values file at target/helm/<deployment target>/<chart name>/values.yaml:

app:
  replicas: 3

And the Deployment file at target/helm/<deployment target>/<chart name>/templates/deployment.yaml will have a reference to this value:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: helm-on-kubernetes-example
spec:
  replicas: '{{ .Values.app.replicas }}'

This is done transparently to users.

Adding custom properties to the Helm Values file using YAMLPath expressions

As we have introduced in the previous section, the Quarkus Helm extension will automatically map some properties like the replicas or the images to the Values helm file. Still, some users might need to map more properties. For example, let’s see the following YAML resource:

apiVersion: v1
kind: Service
metadata:
  name: helm-on-kubernetes-example

The property at metadata.name, with value helm-on-kubernetes-example, will not be replaced with {{ .Values.app.name }} in the Helm templates. However, the extension allows users to define YAMLPath expressions to map these properties into the Helm values file. Let’s see how to do it using the above example to map the property metadata.name with {{ .Values.app.name }}. You only need to add the following properties to your configuration:

quarkus.helm.name=my-chart
quarkus.helm.description=Description of my Chart

# Map all the metadata name resources
quarkus.helm.values.name.paths=metadata.name

The resulting values.yaml file will look like as:

app:
  name: helm-on-kubernetes-example

The app.name value is set automatically by the Quarkus Helm extension. However, users can provide other values using the value property:

quarkus.helm.name=my-chart
quarkus.helm.description=Description of my Chart

# Map all the metadata name resources
quarkus.helm.values.name.paths=metadata.name
## Overwrite value:
quarkus.helm.values.name.value=this-is-another-name

And the values.yaml file will now contain:

app:
  name: this-is-another-name

Using values in the application properties

We can directly use the configuration from the generated Values yaml file in the application.properties file. For example, if the generated values.yaml contains:

app:
  greetings: Hello

We can map this value into the application.properties as this property was a system property:

greetings.message=${app.greetings}

Now, when installing the Helm chart, we can configure the greetings message by doing:

helm install helm-example ./target/helm/kubernetes/<chart name> --set app.greetings=Hola

Mapping System Properties

Mapping system properties only works with string/text properties. For mapping other types, you would need to use the Kubernetes Config extension. See example here.

It’s a very common use case to expose some properties to be configurable when installing the Helm chart. For example, the data source JDBC url:

quarkus.datasource.jdbc.url=jdbc:postgresql://host:1111/database
quarkus.datasource.username=user
quarkus.datasource.password=pass

If we add the above properties into the application.properties file, the connection to the datasource is hardcoded to use a Postgresql instance at jdbc:postgresql://host:1111/database, and you won’t be able to change it when installing the Helm chart.

To allow some properties to be configurable at installing the Helm chart, you have several options:

This extension allows mounting ConfigMap and/or Secret resources where to take the application properties from. You can find more information about how to use it, in the official guide.

  • Using system properties:

You can map the actual configuration you would like to change at installing the Helm chart using system properties, for example:

quarkus.datasource.jdbc.url=${POSTGRESQL_URL:jdbc:postgresql://host:1111/database}
quarkus.datasource.username=${POSTGRESQL_USERNAME:user}
quarkus.datasource.password=${POSTGRESQL_PASSWORD:pass}

In Quarkus, you can specify system properties using the pattern ${NAME-OF-THE-PROPERTY:DEFAULT-VALUE} where Quarkus will try to load the system property NAME-OF-THE-PROPERTY and if not found or set, it will use the value DEFAULT-VALUE.

Next, the Quarkus Helm extension will detect that you’re using system properties in your application properties file and will configure the env var resources at the generated Deployment resource, and also map these properties into the generated Helm Chart values file:

app:
  envs:
    POSTGRESQL_URL: jdbc:postgresql://host:1111/database
    POSTGRESQL_USERNAME: user
    POSTGRESQL_PASSWORD: pass

The Quarkus Helm extension does not force you to use a specific naming convention and by consequence, you can declare the system property using one the following:

  1. Uppercase and underscore separating the words. Example: POSTGRESQL_URL,

  2. Camel case format. Example: postgresqlUrl,

  3. Separated by dots. Example: postgresql.url

The extension will use the property names declared as such under the envs properties, except for the case of the separated by dots (example: postgresql.url) that will be split the words as follows:

app:
  envs:
    postgresql:
      url: jdbc:postgresql://host:1111/database

Therefore, you can now change these values when installing or updating the Helm chart by using:

helm install helm-example ./target/helm/kubernetes/<chart name> --set app.envs.POSTGRESQL_URL=foo --set app.envs.POSTGRESQL_USERNAME=bar --set app.envs.POSTGRESQL_PASSWORD=tar

The mapping of system properties is enabled by default. If you want to disable it, you need to add this property quarkus.helm.map-system-properties=false into the application properties file.

Mapping multiple properties at once

What about if the properties are located in different places, for example:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: helm-on-kubernetes-example ## (1)
spec:
  rules:
    - host: my-host
      http:
        paths:
          - backend:
              service:
                name: helm-on-kubernetes-example ## (2)
                port:
                  name: http
            path: /
            pathType: Prefix

From this example, we need to map the value helm-on-kubernetes-example which is used in two places: (1) metadata.name and (2) spec.rules..http.paths..backend.service.name to the same property name. For doing this, we need to provide a comma-separated list of YAMLPath expressions to be mapped to app.name:

quarkus.helm.name=my-chart
quarkus.helm.description=Description of my Chart

# Map all the metadata name resources
## Comma separated list of YAMLPath expressions:
quarkus.helm.values.name.paths=metadata.name,(kind == Ingress).spec.rules.http.paths.backend.service.name

Now, the extension will first map the expression metadata.name and then the expression (kind == Ingress).spec.rules.http.paths.backend.service.name (this expression only applies to Ingress resources).

Alias name

The alias name is the name used to keep all the properties linked as:

app:
  replicas: 3

The alias name in the above example is "app" which is the default value. You can modify it using the property "quarkus.helm.values-root-alias=myAppName" and then the generated Helm resources will look like:

myAppName:
  replicas: 3

Adding Helm dependencies

Sometimes, your application requires of some other services to work. The typical scenario is when your application needs of a database to store the application data in. In this scenario, you need to declare the database service as a Helm dependency. For example, let’s declare the Postgres Bitnami Helm dependency as database instance:

Chart.yaml:

dependencies:
  - name: postgresql
    version: 11.6.22
    repository: https://charts.bitnami.com/bitnami
    alias: database # this is optional. The default value is the `name`.

Before installing or packaging your Helm chart, you need to download the dependencies (you can use the Helm command helm dependency update ./target/helm/<deployment target>/<chart name>)

Next, you can configure the dependencies adding the dependency configuration into the values.yaml file. For example, following the previous Postgres Bitnami dependency:

values.yaml:

database: # the value in the `alias` property, or the `name` if unset.
  global:
    postgresql:
      auth:
        database: my_db_name
        postgresPassword: secret

Let’s now see how you can add this configuration using the Quarkus Helm extension, so the chart.yaml and the values.yaml files are properly populated using a Helm dependency. You simply need to add the following properties:

application.properties:

quarkus.helm.dependencies.postgresql.alias=database
quarkus.helm.dependencies.postgresql.version=11.6.22
quarkus.helm.dependencies.postgresql.repository=https://charts.bitnami.com/bitnami

quarkus.helm.values.0.property=database.global.postgresql.auth.postgresPassword
quarkus.helm.values.0.value=secret
quarkus.helm.values.1.property=postgresql.global.postgresql.auth.database
quarkus.helm.values.1.value=my_db_name

The Quarkus Helm extension will check whether the property set in quarkus.helm.values.xxx.property starts with a dependency alias or name. If so, it will use directly the value set. Otherwise, it will interpret that the property is an application property and will add the prefix set in the property quarkus.helm.values-root-alias (default value is app).

Alternatively, you can provide the properties of your dependency by providing the file values.yaml or the file Chart.yaml at src/main/helm (the path is configurable using the property quarkus.helm.input-directory). Let’s see an example:

src/main/helm/values.yaml:

database: # the value in the `alias` property, or the `name` if unset.
  global:
    postgresql:
      auth:
        database: my_db_name
        postgresPassword: secret

This configuration will be aggregated in the autogenerated values file at target/helm/<deployment target>/<chart name>/values.yaml.

Install the Helm Dependencies in order

By default, Helm will start the Helm dependencies and the application at the same time. This might cause issues when running your application (as one of the dependencies might not have been started yet, for example, the database).

The good news is that you can force the dependency installation order using the Quarkus Helm extension by adding the property quarkus.helm.dependencies.XX.wait-for-service=<service name>:

quarkus.helm.dependencies.postgresql.alias=database
quarkus.helm.dependencies.postgresql.version=11.6.22
quarkus.helm.dependencies.postgresql.repository=https://charts.bitnami.com/bitnami
quarkus.helm.dependencies.postgresql.wait-for-service=chart-database:5432

The service name strongly depends on the Helm dependency to be installed, so you need to know the service name that the chart will expose beforehand.

This configuration will add the following init-containers in the Deployment resource of your Quarkus application:

target/helm/kubernetes/<chart name>/templates/deployment.yaml:

initContainers:
- image: alpine:3.16.2
  args:
  - -c
  - for i in $(seq 1 200); do nc -z -w3 chart-database && exit 0 || sleep 3; done; exit 1
  command:
  - sh

You can configure the image and the argument template to use with the properties quarkus.helm.dependencies.XX.wait-for-service-image, quarkus.helm.dependencies.0.wait-for-service-port-command-template and quarkus.helm.dependencies.0.wait-for-service-only-command-template.

Validating the input

Helm allows validating the input provided by the user when installing/updating the Helm charts. For example, we might want that the minimum value of the replicas is 3, so if users set a lesser value, Helm rejects it.

These validation rules are specified in the values.schema.json file which this extension will automatically generate with: - A description of the automatically mapped properties. - The structure of the properties.

Therefore, to implement your validation rule, all you would need is to set the minimum value for app.replicas to 3 as follows:

quarkus.helm.values-schema.properties.replicas.minimum=3

Apart from minimum, you can also specify a maximum value, or a pattern that the value has to follow or use the required flag.

Using Helm templates/functions

The Quarkus Helm extension partially supports Helm extensions via Helm templates and functions. You can make use of the templates and more complex functions using Helm expressions:

# Example of expressions
quarkus.helm.expressions.0.path=(kind == Service).metadata.annotations.'app.quarkus.io/commit-id'
quarkus.helm.expressions.0.expression={{ .Values.app.favorite.drink | default "tea" | quote }}

# Example of multiline expression
quarkus.helm.expressions.1.path=(kind == ConfigMap && metadata.name == my-configmap).data
quarkus.helm.expressions.1.expression={{- range $key, $val := .Values.app.favorite }}\n\
{{ indent 2 $key }}: {{ $val | quote }}\n\
{{- end }}

The Quarkus Helm extension will replace the specified path with the provided expression.

To provide your custom templates, you can add them into the folder src/main/helm/templates/_helpers.tpl, for example:

{{/*
Expand the name of the chart.
*/}}
{{- define "foo.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 5 }}
{{- end }}

And next, you can use this function using the Helm include primitive:

quarkus.helm.expressions.0.path=(kind == Service).metadata.annotations.'app.quarkus.io/build-timestamp'
quarkus.helm.expressions.0.expression={{ include "foo.name" . }}

Moreover, you can specify your Helm templates to only a concrete kind resource, for example, only for Service resources. To do this, you need to add the resource src/main/helm/templates/<kind>.yaml (following the example src/main/helm/templates/service.yaml). For example, the following resource will add two template functions called "mychart.labels" and "mychart.not-used":

{{- define "mychart.labels" }}
    generator: helm
{{- end }}
{{- define "mychart.not-used" }}
not:
  used: !
{{- end }}

And let’s use the template "mychart.labels":

quarkus.helm.expressions.0.path=(kind == Service && metadata.name == quarkus-helm-integration-tests-kubernetes-with-templates).metadata.labels
quarkus.helm.expressions.0.expression={{- template "mychart.labels" }}

Note that the content of these resources at src/main/helm/templates/<kind>.yaml will only be added at the beginning of the generated resource at target/helm/kubernetes/<chart name>/templates/<kind>.yaml, by no means, it will be merged. If you want to merge existing Kubernetes/OpenShift resources to the autogenerated ones, you need to follow this guide which does not support Helm expressions.

Push to Helm Repositories

A Helm chart repository is a location where packaged charts can be used and shared across the community.

We can configure the Quarkus Helm extension to automatically push the generated Helm charts into Helm repositories using the following configuration:

# To enable pushing to a Helm repository
quarkus.helm.repository.push=true
# The Helm repository type. Options are: `CHARTMUSEUM`, `ARTIFACTORY`, and `NEXUS`.
quarkus.helm.repository.type=CHARTMUSEUM
quarkus.helm.repository.url=<chart museum url>
# Optional
quarkus.helm.repository.username=...
# Optional
quarkus.helm.repository.password=...

Note: At the moment, OCI Helm Repositories like Amazon ECR, Azure Container Registry, …​ are not supported. #371 for future reference and support.

All the previous properties can be set via system properties at build time.

Let’s see a practical example. First, we need to deploy a Helm repository. The easiest way to set up one, it’s installing ChartMuseum via docker:

docker run --rm -u 0 -it -d -p 8080:8080 -e DEBUG=1 -e STORAGE=local -e STORAGE_LOCAL_ROOTDIR=/charts -v $(pwd)/charts:/charts chartmuseum/chartmuseum:latest

The ChartMuseum data will be stored in the "./charts" folder.

Next, we’re going to build the Helm chart with the push to a repository enabled and using the just created helm repository:

mvn clean install -Dquarkus.helm.repository.push=true -Dquarkus.helm.repository.url=http://localhost:8080/api/charts -Dquarkus.helm.repository.type=CHARTMUSEUM

For the local ChartMuseum, we don’t need to provide either the username or the password.

Finally, let’s install the Helm chart from the Helm repository:

helm repo add local http://localhost:8080
helm install --devel my-quarkus local/quarkus-hello-world

Helm Profiles

By default, all the properties are mapped to the same Helm values file values.yaml. However, the Quarkus Helm extension also supports the generation of Helm values by profiles. For example, let’s say we have two environments: one for testing and another one for production; each environment has a different ingress host where your Kubernetes applications will be exposed. We can configure our application as:

quarkus.kubernetes.ingress.expose=true
# Mapped to `values.yaml` by the preconfigured Ingress decorator
quarkus.kubernetes.ingress.host=my-host

# Helm Chart
quarkus.helm.name=my-chart
## Overwrite the value of `quarkus.kubernetes.host` to `values.<profile-name>.yaml`:
quarkus.helm.values.host.paths=(kind == Ingress).spec.rules.host
quarkus.helm.values.host.value=my-test-host
quarkus.helm.values.host.profile=test

This configuration will generate the values.yaml using the value set at the property quarkus.kubernetes.ingress.host:

app:
  host: my-host

But as you are now using a profile named test (see quarkus.helm.values.host.profile) in one of your mapped properties, it will also generate a values.test.yaml file with the content:

app:
  host: my-test-host

By default, Quarkus Helm uses the "." character in the filename of profile specific values files i.e. values.test.yaml. You can configure this separator using the property quarkus.helm.values-profile-separator. For example, using quarkus.helm.values-profile-separator=- would generate values-test.yaml instead.

Conditionally enable/disable resources

Based on a boolean property that is available part of the values.yaml, you can specify whether you want to install or not any resource. For example, we want to install the generated Ingress resource only if I pass the following property app.ingress.enabled=true when installing the chart. Let’s see how to do this using the quarkus.helm.add-if-statement properties:

quarkus.helm.add-if-statement."ingress.enabled".on-resource-kind=Ingress
quarkus.helm.add-if-statement."ingress.enabled".with-default-value=false

This configuration will add the app.ingress.enabled property in the values.yaml file:

app:
  ingress:
    enabled: false

So, when installing the chart, the Ingress resource won’t be installed by default. Now, to install it, you need to explicitly set the app.ingress.enabled=true property as helm install quarkus local/chart --set app.ingress.enabled=false and then the Ingress resource would be installed.

Command line interface

Using the helm binary requires the user to specify things like name and path for each chart, which is a repetitive process. Moreover, on multi-module projects it requires the command to be run for each of the modules providing a chart.

This extension provides a CLI utility that can be used along with the official Quarkus CLI. To use the Quarkus CLI, install the latest version of the Quarkus CLI. Use quarkus -v to verify the version number.

The plugin is enabled automatically when the Quarkus CLI is running from within a module that is using the helm extension.

Note: If the plugin is not added automatically, it is possible that the extension catalog has not yet been updated with a quarkus-helm version that contains the CLI plugin. Until, then please use the manual installation steps.

Manual installation

To manually enable the CLI plugin for quarkus-helm:

quarkus plug add io.quarkiverse.helm:quarkus-helm-cli:{quarkus-helm-version} -d "Helm CLI"

Using the CLI

Listing charts

To list the available charts of the current projects or its sub-modules:

quarkus helm list

To select a specific platform (e.g. kubernetes or openshift):

quarkus helm list --platform kubernetes

Installing charts

To install all the available charts of the current project or its sub-modules;

quarkus helm install

The command supports the --platform option too. The command also supports the --set option from the original helm cli:

quarkus helm install --set app.replicas=3

In case you want to select a single chart among multiple modules for installation (e.g. user-service):

quarkus helm install user-service

Upgrading charts

To upgrade:

quarkus helm upgrade

The upgrade command supports the same options as the install subcommand.

Uninstalling charts

To uninstall a chart:

quarkus helm uninstall

Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.helm.enabled

Enabled the generation of Helm files.

Environment variable: QUARKUS_HELM_ENABLED

boolean

true

quarkus.helm.name

Name of the Helm chart. If not set, it will use the application name.

Environment variable: QUARKUS_HELM_NAME

string

quarkus.helm.home

Project’s home page of the Helm chart. It must be a URL.

Environment variable: QUARKUS_HELM_HOME

string

quarkus.helm.sources

The Helm chart list of URLs to source code for this project.

Environment variable: QUARKUS_HELM_SOURCES

list of string

quarkus.helm.version

Version of the Helm chart. If not set, it will use the application version.

Environment variable: QUARKUS_HELM_VERSION

string

quarkus.helm.description

The Helm chart single-sentence description.

Environment variable: QUARKUS_HELM_DESCRIPTION

string

quarkus.helm.keywords

List of keywords to add to the chart.

Environment variable: QUARKUS_HELM_KEYWORDS

list of string

quarkus.helm.icon

Icon of the Helm chart. It must be a URL to an SVG or PNG image.

Environment variable: QUARKUS_HELM_ICON

string

quarkus.helm.api-version

The Chart API version. The default value is v2.

Environment variable: QUARKUS_HELM_API_VERSION

string

v2

quarkus.helm.condition

The condition to enable this chart.

Environment variable: QUARKUS_HELM_CONDITION

string

quarkus.helm.tags

Tags of this chart.

Environment variable: QUARKUS_HELM_TAGS

string

quarkus.helm.app-version

The version of the application enclosed of this chart.

Environment variable: QUARKUS_HELM_APP_VERSION

string

quarkus.helm.deprecated

Whether this chart is deprecated.

Environment variable: QUARKUS_HELM_DEPRECATED

boolean

quarkus.helm.kube-version

KubeVersion is a SemVer constraint specifying the version of Kubernetes required.

Environment variable: QUARKUS_HELM_KUBE_VERSION

string

quarkus.helm.type

Specifies the chart type: application or library.

Environment variable: QUARKUS_HELM_TYPE

string

quarkus.helm.values-root-alias

Alias of the root element in the generated values file.

Environment variable: QUARKUS_HELM_VALUES_ROOT_ALIAS

string

app

quarkus.helm.notes

Notes template to be generated.

Environment variable: QUARKUS_HELM_NOTES

string

/NOTES.template.txt

quarkus.helm.extension

Extension of the Helm tarball file. Default is tar.gz.

Environment variable: QUARKUS_HELM_EXTENSION

string

tar.gz

quarkus.helm.tar-file-classifier

Classifier to be appended into the generated Helm tarball file.

Environment variable: QUARKUS_HELM_TAR_FILE_CLASSIFIER

string

quarkus.helm.create-tar-file

If Helm tar file is generated.

Environment variable: QUARKUS_HELM_CREATE_TAR_FILE

boolean

false

quarkus.helm.create-values-schema-file

Whether to generate the values.schema.json file that is used to validate the Helm Chart input values.

Environment variable: QUARKUS_HELM_CREATE_VALUES_SCHEMA_FILE

boolean

true

quarkus.helm.create-readme-file

Whether to generate the README.md file that includes the Chart description and table with the configurable parameters and their default values.

Environment variable: QUARKUS_HELM_CREATE_README_FILE

boolean

true

quarkus.helm.input-directory

The input folder in which to place the user-defined Helm files. These files will be used as inputs to populate the generated Helm files. At the moment, the supported Helm files are: README.md, LICENSE, values.schema.json, app-readme.md or app-README.md, questions.yml or questions.yaml, the "crds" directory, and requirements.yml or requirements.yaml. Moreover, you can provide a custom values.yaml or Chart.yaml and the content will be merged with the auto-generated configuration. It also supports absolute paths. By default, it will use the folder "src/main/helm".

Environment variable: QUARKUS_HELM_INPUT_DIRECTORY

string

src/main/helm

quarkus.helm.output-directory

The output folder in which to place the Helm generated folder. The folder is relative to the target output directory in Quarkus that is also configurable using the property quarkus.package.output-directory. It also supports absolute paths. By default, it will be generated in the folder named "helm".

Environment variable: QUARKUS_HELM_OUTPUT_DIRECTORY

string

helm

quarkus.helm.repository.push

If true, it will perform the upload to a Helm repository.

Environment variable: QUARKUS_HELM_REPOSITORY_PUSH

boolean

false

quarkus.helm.repository.deployment-target

The deployment target to push. Options are: kubernetes, openshift, knative…​

Environment variable: QUARKUS_HELM_REPOSITORY_DEPLOYMENT_TARGET

string

${quarkus.kubernetes.deployment-target}

quarkus.helm.repository.type

The Helm repository type. Options are: CHARTMUSEUM, ARTIFACTORY, and NEXUS.

Environment variable: QUARKUS_HELM_REPOSITORY_TYPE

chartmuseum, artifactory, nexus

quarkus.helm.repository.url

The Helm repository URL.

Environment variable: QUARKUS_HELM_REPOSITORY_URL

string

quarkus.helm.repository.username

The Helm repository username.

Environment variable: QUARKUS_HELM_REPOSITORY_USERNAME

string

quarkus.helm.repository.password

The Helm repository password.

Environment variable: QUARKUS_HELM_REPOSITORY_PASSWORD

string

quarkus.helm.map-system-properties

If enabled, the extension will check whether there are properties using system properties in the form of ${XXX} and if so, it will expose these properties as env-var values within the generated container resource.

Environment variable: QUARKUS_HELM_MAP_SYSTEM_PROPERTIES

boolean

true

quarkus.helm.disable-naming-validation

If true, the naming validation will be disabled. The naming validation rejects property names that contain "-" characters.

Environment variable: QUARKUS_HELM_DISABLE_NAMING_VALIDATION

boolean

false

quarkus.helm.values-profile-separator

Configuration for the separator string in the filename of profile specific values files i.e. values.profile.yaml, defaults to "."

Environment variable: QUARKUS_HELM_VALUES_PROFILE_SEPARATOR

string

.

quarkus.helm.values-schema.title

Title of the values schema json file.

Environment variable: QUARKUS_HELM_VALUES_SCHEMA_TITLE

string

Values

quarkus.helm.maintainers."maintainers".name

Name of the maintainer.

Environment variable: QUARKUS_HELM_MAINTAINERS__MAINTAINERS__NAME

string

quarkus.helm.maintainers."maintainers".email

Email of the maintainer.

Environment variable: QUARKUS_HELM_MAINTAINERS__MAINTAINERS__EMAIL

string

quarkus.helm.maintainers."maintainers".url

URL profile of the maintainer.

Environment variable: QUARKUS_HELM_MAINTAINERS__MAINTAINERS__URL

string

quarkus.helm.annotations

Annotations are additional mappings uninterpreted by Helm, made available for inspection by other applications.

Environment variable: QUARKUS_HELM_ANNOTATIONS

Map<String,String>

quarkus.helm.dependencies."dependencies".name

Name of the dependency.

Environment variable: QUARKUS_HELM_DEPENDENCIES__DEPENDENCIES__NAME

string

quarkus.helm.dependencies."dependencies".version

Version of the dependency.

Environment variable: QUARKUS_HELM_DEPENDENCIES__DEPENDENCIES__VERSION

string

required

quarkus.helm.dependencies."dependencies".repository

Repository of the dependency.

Environment variable: QUARKUS_HELM_DEPENDENCIES__DEPENDENCIES__REPOSITORY

string

required

quarkus.helm.dependencies."dependencies".condition

Dependency condition. If the property starts with @., then the property won’t be added under the root element in the generated values.yaml file.

Environment variable: QUARKUS_HELM_DEPENDENCIES__DEPENDENCIES__CONDITION

string

quarkus.helm.dependencies."dependencies".tags

Dependency tags.

Environment variable: QUARKUS_HELM_DEPENDENCIES__DEPENDENCIES__TAGS

list of string

quarkus.helm.dependencies."dependencies".enabled

Whether this dependency should be loaded.

Environment variable: QUARKUS_HELM_DEPENDENCIES__DEPENDENCIES__ENABLED

boolean

quarkus.helm.dependencies."dependencies".alias

Alias of the dependency.

Environment variable: QUARKUS_HELM_DEPENDENCIES__DEPENDENCIES__ALIAS

string

quarkus.helm.dependencies."dependencies".wait-for-service

Instruct the application to wait for the service that should be installed as part of this Helm dependency. You can set only a service name or a combination of a service name plus the service port (service:port).

Environment variable: QUARKUS_HELM_DEPENDENCIES__DEPENDENCIES__WAIT_FOR_SERVICE

string

quarkus.helm.dependencies."dependencies".wait-for-service-image

If wait for service is set, it will use this image to configure the init-containers within the deployment resource.

Environment variable: QUARKUS_HELM_DEPENDENCIES__DEPENDENCIES__WAIT_FOR_SERVICE_IMAGE

string

busybox:1.34.1

quarkus.helm.dependencies."dependencies".wait-for-service-port-command-template

If wait for service is set, it will use this command to run the init-containers within the deployment resource.

Environment variable: QUARKUS_HELM_DEPENDENCIES__DEPENDENCIES__WAIT_FOR_SERVICE_PORT_COMMAND_TEMPLATE

string

for i in $(seq 1 200); do nc -z -w3 ::service-name ::service-port && exit 0; done; exit 1

quarkus.helm.dependencies."dependencies".wait-for-service-only-command-template

If wait for service is set, it will use this command to run the init-containers within the deployment resource.

Environment variable: QUARKUS_HELM_DEPENDENCIES__DEPENDENCIES__WAIT_FOR_SERVICE_ONLY_COMMAND_TEMPLATE

string

until nslookup ::service-name; do echo waiting for service; sleep 2; done

quarkus.helm.values."values".property

The name of the property that will be present in the Helm values file. If the property starts with @., then the property won’t be added under the root element in the generated values.yaml file.

Environment variable: QUARKUS_HELM_VALUES__VALUES__PROPERTY

string

quarkus.helm.values."values".paths

A comma-separated list of YAMLPath expressions to map the Dekorate auto-generated properties to the final Helm values file.

Environment variable: QUARKUS_HELM_VALUES__VALUES__PATHS

list of string

quarkus.helm.values."values".profile

The profile where this value reference will be mapped to. For example, if the profile is dev, then a values.dev.yml file will be created with the value.

Environment variable: QUARKUS_HELM_VALUES__VALUES__PROFILE

string

quarkus.helm.values."values".value

The value that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts.

Environment variable: QUARKUS_HELM_VALUES__VALUES__VALUE

string

quarkus.helm.values."values".value-as-int

The integer value that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts.

Environment variable: QUARKUS_HELM_VALUES__VALUES__VALUE_AS_INT

int

quarkus.helm.values."values".value-as-bool

The boolean value that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts.

Environment variable: QUARKUS_HELM_VALUES__VALUES__VALUE_AS_BOOL

boolean

quarkus.helm.values."values".value-as-map

The map value that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts.

Environment variable: QUARKUS_HELM_VALUES__VALUES__VALUE_AS_MAP

Map<String,String>

quarkus.helm.values."values".value-as-list

A list separated by comma that the property will have in the Helm values file. If not set, the extension will resolve it from the generated artifacts.

Environment variable: QUARKUS_HELM_VALUES__VALUES__VALUE_AS_LIST

list of string

quarkus.helm.values."values".expression

If not provided, it will use {{ .Values.. }}.

Environment variable: QUARKUS_HELM_VALUES__VALUES__EXPRESSION

string

quarkus.helm.values."values".description

Description of the property.

Environment variable: QUARKUS_HELM_VALUES__VALUES__DESCRIPTION

string

quarkus.helm.values."values".minimum

Minimum value allowed for this property.

Environment variable: QUARKUS_HELM_VALUES__VALUES__MINIMUM

int

quarkus.helm.values."values".maximum

Maximum value allowed for this property.

Environment variable: QUARKUS_HELM_VALUES__VALUES__MAXIMUM

int

quarkus.helm.values."values".pattern

Pattern to validate the value of this property.

Environment variable: QUARKUS_HELM_VALUES__VALUES__PATTERN

string

quarkus.helm.values."values".required

If true, then this property is mandatory.

Environment variable: QUARKUS_HELM_VALUES__VALUES__REQUIRED

boolean

false

quarkus.helm.expressions."expressions".path

The YAMLPath path where to include the template within the resource.

Environment variable: QUARKUS_HELM_EXPRESSIONS__EXPRESSIONS__PATH

string

required

quarkus.helm.expressions."expressions".expression

The expression template to include.

Environment variable: QUARKUS_HELM_EXPRESSIONS__EXPRESSIONS__EXPRESSION

string

required

quarkus.helm.add-if-statement."add-if-statement".property

The property to use in the if statement. If the property starts with @., then the property won’t be added under the root element in the generated values.yaml file.

Environment variable: QUARKUS_HELM_ADD_IF_STATEMENT__ADD_IF_STATEMENT__PROPERTY

string

quarkus.helm.add-if-statement."add-if-statement".on-resource-kind

The resource kind where to include the if statement.

Environment variable: QUARKUS_HELM_ADD_IF_STATEMENT__ADD_IF_STATEMENT__ON_RESOURCE_KIND

string

quarkus.helm.add-if-statement."add-if-statement".on-resource-name

The resource kind where to include the if statement.

Environment variable: QUARKUS_HELM_ADD_IF_STATEMENT__ADD_IF_STATEMENT__ON_RESOURCE_NAME

string

quarkus.helm.add-if-statement."add-if-statement".with-default-value

The default value of the property

Environment variable: QUARKUS_HELM_ADD_IF_STATEMENT__ADD_IF_STATEMENT__WITH_DEFAULT_VALUE

boolean

true

quarkus.helm.add-if-statement."add-if-statement".description

Provide custom description of the add-if-statement property.

Environment variable: QUARKUS_HELM_ADD_IF_STATEMENT__ADD_IF_STATEMENT__DESCRIPTION

string

Determine if the resource should be installed or not.

quarkus.helm.values-schema.properties."properties".name

Name of the property to add or update. Example: app.replicas.

Environment variable: QUARKUS_HELM_VALUES_SCHEMA_PROPERTIES__PROPERTIES__NAME

string

quarkus.helm.values-schema.properties."properties".description

Description of the property.

Environment variable: QUARKUS_HELM_VALUES_SCHEMA_PROPERTIES__PROPERTIES__DESCRIPTION

string

quarkus.helm.values-schema.properties."properties".type

Type of the property.

Environment variable: QUARKUS_HELM_VALUES_SCHEMA_PROPERTIES__PROPERTIES__TYPE

string

string

quarkus.helm.values-schema.properties."properties".minimum

Minimum value allowed for this property.

Environment variable: QUARKUS_HELM_VALUES_SCHEMA_PROPERTIES__PROPERTIES__MINIMUM

int

quarkus.helm.values-schema.properties."properties".maximum

Maximum value allowed for this property.

Environment variable: QUARKUS_HELM_VALUES_SCHEMA_PROPERTIES__PROPERTIES__MAXIMUM

int

quarkus.helm.values-schema.properties."properties".pattern

Pattern to validate the value of this property.

Environment variable: QUARKUS_HELM_VALUES_SCHEMA_PROPERTIES__PROPERTIES__PATTERN

string

quarkus.helm.values-schema.properties."properties".required

If true, then this property is mandatory.

Environment variable: QUARKUS_HELM_VALUES_SCHEMA_PROPERTIES__PROPERTIES__REQUIRED

boolean

false

References