Heimdall Helm Chart

Introduction

This chart helps you deploy heimdall into your Kubernetes cluster using Helm.

Note	Heimdall follows the Kubernetes support policy and supports at least the three latest minor Kubernetes versions. General functionality cannot be guaranteed for versions older than that.

Prerequisites

• A Kubernetes version >= 1.30

• Helm 3.10+

• Git (optional)

Installing The Chart

This chart supports setting of environment variables for the deployment, e.g. to provide OTEL configuration, which can be configured using either the env or envFrom keys. The latter allows pulling the corresponding values from referenced configmaps or secrets.

If you need to override the name of the heimdall resources such as the deployment or services, the traditional nameOverride and fullnameOverride properties are supported.

If you want to have detailed CPU & memory profiling information, you can enable the profiling service and let your APM scrape the corresponding pprof data. If the profiling service is enabled, the required annotations for Phlare are automatically set.

Installing A Release

Since you can obtain the chart from heimdall’s git repository, its Helm repository hosted on GitHub Pages, or as an OCI image, the following examples don’t differentiate between these sources. Instead, the code fragments are using a <chart-reference> placeholder.

If you want to install a release from its sources, perform the following steps first. The actual value for abovesaid <chart-reference> would then be ./charts/heimdall.

1. Clone the heimdall repo:

   $ git clone https://github.com/dadrus/heimdall

2. Change your working directory to the root directory of the cloned repository:

   $ cd heimdall

If you want to install the release from the Helm repository hosted on GitHub Pages, perform the following steps. The actual value for abovesaid <chart-reference> would then be dadrus/heimdall.

1. Make the chart repository known to Helm

   $ helm repo add dadrus https://dadrus.github.io/heimdall/charts

2. Update information of available charts

   $ helm repo update

Alternatively, you can use the OCI image (oci://ghcr.io/dadrus/heimdall/chart) published to GHCR, which provides enhanced security. The OCI image is signed and includes SLSA provenance, which can be verified for authenticity and integrity as described in Verification of Heimdall Artifacts.

To install the chart with the release name "my-release" ("my-release" is the name that you choose), perform

$ helm install my-release <chart-reference> \
  -n <namespace-to-install-heimdall-into> \
  -f <path/to/your/values.yaml> \
  -f <path/to/your/heimdall/config.yaml>

A list of supported chart values can be found at the end of this README. For heimdall specific configuration, please refer to heimdall’s documentation.

If you have configured heimdall to use the kubernetes provider, heimdall will require the RuleSet CRD being installed in the cluster. The Helm chart is configured to install it automatically on first heimdall installation and if this CRD is not already present in the cluster.

Post-Install Steps

Integration With Ingress/Gateway API

Regardless of the installation method, if heimdall is running in decision mode, you need to connect it to your Ingress Controller or Gateway API implementation. This ensures traffic is validated by heimdall prior to being routed to the downstream services. Check the existing Guides for more information.

Upgrading An Existing Release

Upgrading The CRD

The Helm chart upgrades the RuleSet CRD alongside heimdall’s resources only when explicitly enabled by setting the crds.updateEnabled property to true.

If you prefer to manage CRD upgrades manually, you can render and apply the new CRD yourself using the following command:

helm template <release-name> ./charts/heimdall \
  --show-only templates/crds/ruleset.yaml \
  --set crds.updateEnabled=true \
  -n <namespace-heimdall-is-installed-into> \
  -f <path/to/your/values.yaml> \
  -f <path/to/your/heimdall/config.yaml> | \
  kubectl apply -f -

Note

Starting with v0.18.0, Heimdall implements a conversion service that is registered as a webhook in the RuleSet CRD. This allows the Kubernetes API server to convert between different RuleSet resource versions. Please note that the API server requires the conversion service to be accessible via TLS. Therefore, it will only be exposed and configured in the CRD if, and only if, heimdall’s kubernetes provider is configured to expose the corresponding controller service endpoints via TLS. For more information about the migration process and also how to migrate between RuleSet versions, please refer to the Migration section in heimdall’s documentation.

Upgrading The Release

To upgrade the release named "my-release" perform:

$ helm upgrade my-release <chart-reference> \
  -n <namespace-heimdall-was-installed-into> \
  -f <path/to/your/values.yaml> \
  -f <path/to/your/heimdall/config.yaml>

Uninstalling The Chart

Uninstalling The Release

To uninstall/delete the release "my-release", execute

$ helm uninstall my-release

This command removes all Kubernetes components associated with the release.

Uninstalling The CRDs

Uninstalling the release does not remove the CRDs. To remove them, run:

$ kubectl delete rulesets.heimdall.dadrus.github.com

Warning

This will also remove all RuleSet resources deployed to the cluster.

Configuration

The configuration of heimdall itself is simply added to the root of the helm values. It is not included in the list below, please refer to the [general documentation](https://dadrus.github.io/heimdall/dev/docs/operations/configuration/).

Note	It is recommended to keep heimdall-specific configuration and chart-specific configuration in separate files and supply both as value files to Helm. This is, however, not strictly required. Example: helm install -f /path/to/chart-values.yaml -f /path/to/heimdall-config.yaml ...

The following table lists the other configurable parameters of the chart and their default values.

Parameter	Default Value
operationMode The mode of operation for the heimdall installation. Can be proxy or decision	decision
image.repository The image repository to load heimdall image from	ghcr.io/dadrus/heimdall
image.tag The tag of the image to use	latest
image.pullPolicy The pull policy to apply	IfNotPresent
image.pullSecrets Image pull secrets	[] (empty list)
nameOverride Enables you to override the name used for heimdall (which is "heimdall")	""
fullnameOverride Enables you to override the name used for the service created for the heimdall deployment	""
deployment.annotations Enables you to set additional annotations for the deployment	{} (empty map)
deployment.labels Enables you to set additional labels for the deployment	{} (empty map)
deployment.pod.annotations Enables you to set additional annotations for the pod. If metrics are not disabled, the OTEL_METRICS_EXPORTER environment variable is set to "prometheus" and either podMonitor.enabled (see below) is set to false, or the CRD defining the PodMonitor schema is not deployed to the cluster, the following Prometheus scraping annotations are added: prometheus.io/scrape: "true" prometheus.io/path: "/metrics" prometheus.io/port: 9464 The used port can be adjusted via the OTEL_EXPORTER_PROMETHEUS_PORT environment variable If profiling is enabled, following annotations are added as well phlare.grafana.com/scrape: "true" phlare.grafana.com/port: 10251 The port value in the above annotation depends on the settings for the profiling service.	{} (empty map)
deployment.pod.securityContext Enables you to set the security context for the pod	{} (empty map)
deployment.securityContext Enables you to set the security context for the deployment	capabilities: drop: - ALL readOnlyRootFilesystem: true runAsNonRoot: true runAsUser: 1000
deployment.resources Specifies resource requests and limits for the deployment. Note: Memory usage depends on the cache backend and its configuration. By default, heimdall uses an in-memory cache limited to 128Mi. With Redis (with client-side caching), the limit is also 128Mi. The heimdall process itself requires ~64Mi. Example: deployment: resources: limits: cpu: 125m memory: 256Mi requests: cpu: 125m memory: 256Mi	{} (empty map)
deployment.replicaCount Allows specifying the amount of desired replicas (only used if HPA is disabled)	1
deployment.autoscaling.enabled Enables or disables HPA based on CPU and memory utilization If enabled, deployment.resources.requests must be configured.	false
deployment.autoscaling.minReplicas Minimal amount of desired replicas	2
deployment.autoscaling.maxReplicas Maximim amount of desired replicas	10
deployment.autoscaling.targetCPUUtilizationPercentage Target CPU utilization in % to scale up Requires deployment.resources.requests.cpu to be configured	80
deployment.autoscaling.targetMemoryUtilizationPercentage Target Memory utilization in % to scale up Requires deployment.resources.requests.memory to be configured	80
deployment.nodeSelector Node selector settings for the deployment	{} (empty map)
deployment.tolerations Tolerations for the deploment	[] (empty array)
deployment.affinity Affinity settings for the deploment	{} (empty map)
deployment.volumes Optional volumes to use	[] (empty array)
deployment.volumeMounts Optional volumeMounts to use	[] (empty array)
service.default.labels Labels for the Service resource created for heimdall’s main and management ports.	{} (empty map)
service.default.annotations Annotations for the Service resource created for heimdall’s main and management ports.	{} (empty map)
service.default.mainPort The main port configured in the Service resource created for heimdall’s main and management ports.	4456
service.default.mainPortName The name of the main port configured in the Service resource created for heimdall’s main and management ports.	main
service.default.managementPort The management port configured in the Service resource created for heimdall’s main and management ports.	4457
service.default.managementPortName The name of the port configured in the Service resource created for heimdall’s main and management ports.	management
service.validation.labels Labels for the Service resource created for heimdall’s validation controller endpoint.	{} (empty map)
service.validation.annotations Annotations for the Service resource created for heimdall’s validation controller endpoint.	{} (empty map)
service.validation.port The port configured in the Service resource created for heimdall’s validation controller endpoint.	4458
service.validation.portName The name of the port configured in the Service resource created for heimdall’s validation controller endpoint.	validation-webhook
service.conversion.labels Labels for the Service resource created for heimdall’s conversion controller endpoint.	{} (empty map)
service.conversion.annotations Annotations for the Service resource created for heimdall’s conversion controller endpoint.	{} (empty map)
service.conversion.port The port configured in the Service resource created for heimdall’s conversion controller endpoint.	4459
service.conversion.portName The name of the port configured in the Service resource created for heimdall’s conversion controller endpoint.	conversion-webhook
webhooks.caBundle Allows setting the caBundle used by the Kubernetes API server to verify the TLS certificates of all heimdall controllers configured as webhooks. Alternatively, you can configure annotations for a particular webhook to inject the required values (see below).	""
webhooks.conversion.annotations Can be used to specify required annotations for the RuleSet CRD, like e.g. cert-manager.io/inject-ca-from: <secret name>, service.beta.openshift.io/inject-cabundle=true and alike.	{} (empty map)
webhooks.validation.labels Allows setting additional labels for the ValidatingWebhookConfiguration resource used to let the API server communicate with heimdall to validate RuleSet resources, before these made available to heimdall for loading.	{} (empty map)
webhooks.validation.annotations Can be used to specify required annotations for the ValidatingWebhookConfiguration resource, like e.g. cert-manager.io/inject-ca-from: <secret name>, service.beta.openshift.io/inject-cabundle=true and alike.	{} (empty map)
webhooks.validation.namespaceSelector Allows specifying a namespaceSelector for the ValidatingWebhookConfiguration resource	{} (empty map)
webhooks.validation.timeoutSeconds How long the webhook implemented by the admission controller is allowed to run while validating RuleSet resources. After the timeout passes, the webhook call will be ignored by the API server resulting in discarding the affected RuleSet ressource.	5
env Environment variables, which should be made available to the heimdall deployment. Variables can be specified as key-value pairs with string values or as an object referencing a ConfigMap or Secret key. E.g. env: OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: grpc OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: http://tempo.tempo.svc.cluster.local:4317 EXAMPLE_KEY: configMapKeyRef: name: example-configmap key: EXAMPLE_KEY	{} (empty map)
envFrom Environment variables, which should be made available to the heimdall deployment, but are pulled from a ConfigMap or Secret resource instead of specified directly. envFrom: - configMapRef: name: example-configmap	[] (empty array)
extraArgs Optional extra arguments to pass to heimdall when starting. E.g. to start heimdall in decision mode for integration with envoy v3 ext_auth, set it to: extraArgs: - --envoy-grpc	[] (empty array)
crds.updateEnabled Controls whether the CRD should be updated.	false
crds.storageVersion Defines which RuleSet schema is used as storage version in etcd.	v1beta1
podMonitor.enabled Controls, whether a PodMonitor resource should be deployed. It will only be deployed if following conditions are satisfied: Metrics are not disabled (Heimdall emits metrics by default). The deployment of the PodMonitor resource (this setting) is not disabled The OTEL_METRICS_EXPORTER environment variable is set to "prometheus" The CRD defining the PodMonitor resource is deployed to the cluster	true
podMonitor.namespace Namespace to deploy the PodMonitor resource into. If not set, defaults to the release namespace.	""
podMonitor.labels Enables you to set additional labels for the PodMonitor resource	{} (empty map)
podMonitor.jobLabel The label to use from heimdall’s Pod to retrieve the job name from.	<namespace>/<name>
podMonitor.targetLabels Labels which are transferred from heimdall’s Pod object onto the ingested metrics.	[] (empty array)
podMonitor.interval Interval at which Prometheus scrapes the metrics from the target. If set to "" Prometheus will use the global scrape interval.	30s
podMonitor.scrapeTimeout Defines the timeout after which Prometheus considers the scrape to be failed. Must be bigger then the scrape interval (podMonitor.interval). If set to "" Prometheus will use the global scrape timeout unless it is less than the scrape interval value in which the latter is used.	30s
podMonitor.metricRelabelings Relabeling rules to apply to the samples before ingestion.	[] (empty array)
podMonitor.relabelings Defines the relabeling rules to apply the target’s metadata labels. See relabel_config for more details.	[] (empty array)