Write your first template¶

Extend the bundled configuration with a snippet when you need behavior the available settings don't cover. A snippet adds a small piece of HAProxy configuration at an extension point. You can also replace the complete configuration or read your own resource types.

This walkthrough adds an X-Team: storefront response header to the shared HTTP routing frontend. It uses an existing Helm installation named haptic in the haptic namespace. Install HAPTIC first if needed. You can learn the template syntax in your browser without installing anything.

1. Add a snippet to your values¶

Keep your existing settings and add this snippet to your complete Helm values file, haptic-values.yaml:

controller:
  config:
    templateSnippets:
      frontend-extra-400-team-header:
        template: |
          http-response set-header X-Team storefront

The frontend-extra-* extension point includes matching snippets in the shared HTTP frontend. The rest of the bundled templates continue to generate routing, backends, and certificates. Snippets with the same name replace one another; choose a new name when adding behavior.

2. Apply your values¶

Upgrade with the complete file:

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

The chart's validation hook checks the candidate before rollout. To run that check separately, follow Validate before deploying. For ongoing customization, add tests for the behavior you expect.

3. Check the result¶

Inspect the generated configuration using the CLI already in a controller pod:

kubectl exec --namespace haptic deployment/haptic-controller --container controller \
  -- haptic config view --namespace haptic

Find http-response set-header X-Team storefront in the HTTP frontend. Then send a request through one of your Ingress routes and inspect its response headers. If you used the sample application, start port forwarding:

kubectl port-forward --namespace haptic svc/haptic-haproxy 8080:80

In another terminal:

curl -i -H 'Host: echo.example.local' http://localhost:8080/

The response includes X-Team: storefront. If the generated directive exists but the response doesn't include the header, check deployment status and confirm that the request reaches this installation.

To remove the example, delete frontend-extra-400-team-header from your values and run the same upgrade command.

Custom template variables¶

To let the same template use different settings in each environment, supply values through templatingSettings.extraContext. Replace the first example with this version to choose the team name in your values file:

controller:
  config:
    templatingSettings:
      extraContext:
        team: storefront
    templateSnippets:
      frontend-extra-400-team-header:
        template: |
          http-response set-header X-Team {{ extraContext.team }}

Use extraContext for settings you control. Validate values from other users before inserting them into HAProxy directives; see annotation helpers.

Continue with your use case¶

Generate configuration and files¶

Follow the examples in Generate configuration and files to create a complete HAProxy configuration, maps, error pages, or certificates.

Learn the syntax¶

Learn expressions, loops, helper functions, and whitespace control with the interactive examples in Template syntax.

Read Kubernetes resources¶

Use Kubernetes resources in your templates: access typed fields, read annotations, and look up related resources.

Report resource status¶

Report resource status with patches and conditions for the resources your templates manage.

For a complete resource-driven routing implementation, see the Ingress library and the custom-resource example. Use the template reference to look up functions and template libraries to share your changes.

Found a problem on this page? Report it