Helm is the most popular package manager that finds, shares, and deploys software built for Kubernetes. It would be best if you packaged Java applications as Helm charts containing all of the necessary metadata and resource definitions to configure them for distribution through Helm. This article introduces the Dekorate Helm extension as an easier way to generate and maintain Helm chart resources.
What are Helm charts?
A Helm chart is a collection of files inside a directory. The following files are mandatory:
Chart.yaml: Chart metadata, such as name, version, and developers.values.yaml: Default configuration values for the chart in YAML.templates: A directory containing the list of resources that, combined withvalues.yaml, generate the application when the chart is installed. The resources are also specified in YAML.
How to configure the Dekorate Helm extension
Dekorate (starting with version 2.11) can generate the Helm chart resources for you. You should include the Dekorate Helm dependency in your POM file using the latest version of Dekorate from Maven Central as follows:
<dependency>
<groupId>io.dekorate</groupId>
<artifactId>helm-annotations</artifactId>
<version>{dekorate.version}</version>
</dependency>
Then, configure Helm via properties as follows:
# This name property is mandatory to generate the Helm chart
dekorate.helm.name=myChart
# If the version is not provided, the application version will be used instead
dekorate.helm.version=1.0.0-SNAPSHOT
# The description property is optional
dekorate.helm.description=Description of my Chart
Alternatively, add the @HelmChart annotation to one of your Java source files:
@HelmChart(name = "myChart", version = "1.0.0-SNAPSHOT", description = "Description of my Chart")
@SpringBootApplication
public class Main {
public static void main(String[] args) {
SpringApplication.run(Main.class, args);
}
}
Now you can generate the Helm resources using the Maven build command:
$ mvn clean package
The generated Helm chart will be in the target/classes/META-INF/dekorate/helm/<chart name>/ directory.
Dekorate extensions determine which templates appear in the chart. For example, if your project uses the Kubernetes Dekorate extension, the Helm resources include the following files in the target/classes/META-INF/dekorate/helm/<chart name>/templates directory:
deployment.yamlingress.yamlservice.yaml
How to use Helm
Let's see how to use the previously generated Helm chart.
First, make sure you have installed the Helm command-line interface (CLI) and logged into a Kubernetes cluster.
Then run the following Maven command to generate the Helm artifacts:
$ mvn clean package
Finally, install the generated Helm chart into the cluster:
$ helm install helm-example ./target/classes/META-INF/dekorate/helm/<chart name>
The helm command waits until the chart is fully installed and the application is up and running.
2 ways to update your deployment
Method #1: Update deployment via the upgrade option of the Helm command line. After making changes to your project, regenerate the resources using this Maven command:
$ mvn clean package
Then upgrade your deployment:
$ helm upgrade helm-example ./target/classes/META-INF/dekorate/helm/<chart name>
Method #2: Update a deployment through the --set option of the helm upgrade command:
$ helm upgrade helm-example ./target/classes/META-INF/dekorate/helm/<chart name> --set app.replicas=1
The app.replicas option is a parameterized property mapped by the values.yaml file. We will explore this function more in the next section.
To delete a deployment, enter:
$ helm uninstall helm-example
Mapping values using path expressions
Helm allows mapping to set properties of your resources during or after chart installation. For instance, suppose your deployment template in the templates/deployment.yaml file looks like this:
apiVersion: apps/v1
kind: Deployment
metadata:
name: myModule
spec:
replicas: {{ .Values.app.replicas }}
Use the helm command to set the number of replicas to use for installing the chart, as shown in the previous section:
$ helm install helm-example ./target/classes/META-INF/dekorate/helm/<chart name> --set app.replicas=1
Alternatively, set the number of the replicas in the values.yaml file, located in the chart's directory at target/classes/META-INF/dekorate/helm/<chart name>/values.yaml:
app:
replicas: 1
The good news is that Dekorate also generates the Helm values.yaml file and automatically maps preconfigured properties, such as Kubernetes replicas or ingress host properties. The complete list of preconfigured properties is in the official Dekorate Helm site documentation.
Let's try an example of configuring the replicas using the Dekorate Kubernetes dekorate.kubernetes.replicas property. This example will demonstrate how Dekorate Helm automatically maps it into the generated Helm chart.
Set 3 replicas for your deployment:
# Set replicas to 3
dekorate.kubernetes.replicas=3
The generated Helm values file at target/classes/META-INF/dekorate/helm/<chart name>/values.yaml contain the replicas value:
---
app:
replicas: 3
Additionally, the deployment template file at target/classes/META-INF/dekorate/helm/<chart name>/templates/deployment.yaml will have a reference to this value.
What if you want to map other properties that are not preconfigured? For example, mapping the value myModule that appears in the metadata.name property with the following deployment template file:
apiVersion: apps/v1
kind: Deployment
metadata:
name: myModule -- let's map this value!
spec:
replicas: {{ .Values.app.replicas }}
You can configure Dekorate to map any properties in your resources using YAMLPath expressions. To continue with the preceding example, you need only add the following configuration to your properties:
dekorate.helm.values[0].property=resource
dekorate.helm.values[0].paths=metadata.name
In the first line, property is the property name to be set. In the second line, paths is a list of YAMLPath expressions that identify the properties you want to use (metadata.name in the example).
Using the properties just defined, the resulting Helm values file at target/classes/META-INF/dekorate/helm/<chart name>/values.yaml will include:
app:
resource: myModule
The following is the deployment template resource at target/classes/META-INF/dekorate/helm/<chart name>/templates/deployment.yaml:
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ .Values.app.resource }}
spec:
replicas: {{ .Values.app.replicas }}
YAMLPath expressions also support more complex scenarios. You can use the expressions to replace properties for a specific resource type or properties described as a key-value map. You can find all the supported features in the official site documentation.
How to use Helm profiles
All properties are, by default, mapped to the same Helm values.yaml file. However, Dekorate also supports the generation of other Helm values files.
For example, let’s say you have two environments: one for testing and another for production. Each environment has a different ingress host that exposes your Kubernetes application. You can configure your application as follows:
# Mapped to `values.yaml` by the preconfigured Ingress decorator
dekorate.kubernetes.ingress.host=my-host
# Overwrite the value of `dekorate.kubernetes.ingress.host` to `values-<profile-name>.yaml`:
dekorate.helm.values[0].property=host
dekorate.helm.values[0].paths=(kind == Ingress).spec.rules.host
dekorate.helm.values[0].value=my-test-host
## `test` is the profile name.
dekorate.helm.values[0].profile=test
Dekorate Helm preconfigures the Ingress host property. Therefore, you will find the my-host value in the target/classes/META-INF/dekorate/helm/<chart name>/values.yaml file:
app:
host: my-host
But because you are also using a profile named test in one of your properties, Dekorate generates a target/classes/META-INF/dekorate/helm/<chart name>/values-test.yaml file with this content:
app:
host: my-test-host
When installing your chart in the test environment, you can use this values file in the following command:
$ helm install -f ./target/classes/META-INF/dekorate/helm/<chart name>/values-test.yaml helm-example ./target/classes/META-INF/dekorate/helm/<chart name>
Dekorate reduces the complexity of Helm chart generation
Generating Helm charts can be a complex process. In this article, we demonstrated three Helm processes that illustrate how Dekorate simplifies Helm chart generation:
-
How to easily generate Helm charts using Dekorate.
-
How to map properties to be set when installing or updating your charts.
-
How to use Helm profiles.
Learn more about Helm charts in the official Helm documentation.
Last updated: October 31, 2023