Skip to content

Deploying with Helm

Install HAPTIC with the Helm chart. It deploys the controller, two HAProxy replicas, custom resource definitions (CRDs), and the template libraries for Ingress and Gateway API. Configure the installation through Helm values. For a first installation and an optional sample route, follow Getting started.

Prerequisites

Note

Set haproxyVersion to select matching controller and HAProxy images. The default is 3.4; see HAProxy versions for supported alternatives.

Installation

helm install haptic oci://registry.gitlab.com/haproxy-haptic/haptic/charts/haptic \
  --version 0.2.0 --namespace haptic --create-namespace

With custom values:

helm install haptic oci://registry.gitlab.com/haproxy-haptic/haptic/charts/haptic \
  --version 0.2.0 --namespace haptic --create-namespace \
  -f haptic-values.yaml

Check the installation

Wait for the controller and HAProxy Deployments to become ready:

kubectl rollout status deployment/haptic-controller --namespace haptic --timeout=180s
kubectl rollout status deployment/haptic-haproxy --namespace haptic --timeout=180s

These names use the release and namespace from the install command. For a failed rollout, follow installation troubleshooting.

Change settings

Keep your custom settings in haptic-values.yaml. Add the values shown in these guides to that file, then pass the complete file when you install or upgrade.

If you already have a values file for this release, use it. If you don't, export the values from your installed release before making changes:

helm get values haptic --namespace haptic --output yaml > haptic-values.yaml
if [ "$(cat haptic-values.yaml)" = null ]; then
  printf '{}\n' > haptic-values.yaml
fi

This includes settings supplied with --set. Keep them when adding a new setting; passing only the new setting to helm upgrade can restore other settings to their chart defaults. Use the upgrade command to apply the edited file.

The chart manages the controller, HAProxy pods, configuration, permissions, and validation hooks. See HAProxy deployment settings to change the pod and Service settings, or the values reference for all options.

Running multiple HAPTIC instances in one cluster

The example below gives a second HAPTIC release its own namespace, classes, and controller identifiers. This separates its configuration and HAProxy fleet from the first installation:

Setting Values key Purpose
Release name and namespace helm install <name> --namespace <ns> Separates workloads, configuration, Secrets, and the leader-election lease
Ingress class ingressClass.name The controller watches only Ingresses whose spec.ingressClassName equals this value. Two releases sharing it would both process the same Ingresses
Gateway class gatewayClass.name The controller watches only Gateways whose spec.gatewayClassName equals this value
Controller identifier ingressClass.controllerName and gatewayClass.controllerName The GatewayClass watch is filtered to spec.controllerName; two releases sharing it would fight over the same GatewayClasses' status. Default: haproxy-haptic.org/controller

The chart derives watch filters from ingressClass.name and gatewayClass.name. Set the class names in values; the chart updates the filters to match.

The leader-election lease name defaults to the release's full name. The configuration name defaults to haptic-config, independently of the release name. If you place releases in the same namespace, give each a distinct controller.configName and ensure they don't share managed Secrets. Separate namespaces avoid those ownership conflicts.

Example values for a second release with its own classes:

# team-b-values.yaml
ingressClass:
  name: haptic-team-b
  controllerName: haproxy-haptic.org/team-b
gatewayClass:
  name: haptic-team-b
  controllerName: haproxy-haptic.org/team-b

helm install haptic-team-b oci://registry.gitlab.com/haproxy-haptic/haptic/charts/haptic \
  --version 0.2.0 \
  --namespace haptic-team-b --create-namespace \
  -f team-b-values.yaml

Ingress and Gateway authors then select this release with ingressClassName: haptic-team-b or gatewayClassName: haptic-team-b.

Upgrading

For an upgrade from 0.1.0 or a 0.2.0 alpha, read the 0.2 upgrade notes before applying your values.

Pass your complete values file when upgrading. If you configured the release with --set and have no saved file, export its values first:

helm upgrade haptic oci://registry.gitlab.com/haproxy-haptic/haptic/charts/haptic \
  --version 0.2.0 --namespace haptic \
  -f haptic-values.yaml

For an installation with no custom settings, you can upgrade without a values file:

helm upgrade haptic oci://registry.gitlab.com/haproxy-haptic/haptic/charts/haptic \
  --version 0.2.0 --namespace haptic

Check the Deployments after an upgrade.

The chart owns the HAProxyTemplateConfig

Put persistent configuration changes under controller.config in your values file. Edits made with kubectl edit or kubectl patch take effect immediately, but a later helm upgrade can overwrite them. Helm also owns the library objects it creates.

Recover a failed upgrade

Check the release status and validation Job for the default installation:

helm status haptic --namespace haptic
kubectl get jobs --namespace haptic
kubectl logs --namespace haptic job/haptic-haptic-pre-rollout

If pre-rollout validation fails, fix the reported values or templates and repeat the upgrade command with your complete values file. Existing HAProxy workers keep their last configuration while this check blocks rollout. Earlier hooks may already have updated CRDs or certificates; a failed upgrade doesn't mean every resource is unchanged.

If validation passed but a Deployment doesn't become ready, follow installation troubleshooting. Keep hooks and validation enabled when retrying.

Helm rollback doesn't reverse CRD changes or run the chart's pre-upgrade validation. HAPTIC doesn't guarantee downgrades across configuration API changes. Recover with corrected values or a corrected forward release, and check the upgrade notes for version-specific migrations.

Uninstalling

helm uninstall haptic --namespace haptic

Use the release name and namespace from installation. Uninstall removes the release workloads and configuration. CRDs, retained default-certificate Secrets, and runtime-created agent certificate Secrets remain. Keep the agent issuer and identity Secrets together if you plan to reuse them on reinstall.

Delete the CRDs only when no HAPTIC installation still needs them. This deletes every instance of these resources across all namespaces, including route policies and custom configurations:

kubectl delete crd \
  haproxytemplateconfigs.haproxy-haptic.org \
  haproxytemplatelibraries.haproxy-haptic.org \
  haproxycfgs.haproxy-haptic.org \
  haproxygeneralfiles.haproxy-haptic.org \
  haproxycrtlistfiles.haproxy-haptic.org \
  haproxymapfiles.haproxy-haptic.org \
  haproxyroutepolicies.haproxy-haptic.org

Where to go next

Found a problem on this page? Report it