Getting started¶

Install HAPTIC with Helm, then route your applications. The optional walkthrough creates a sample route you can test locally.

To try HAPTIC without a cluster, use the browser example.

Prerequisites¶

A Kubernetes 1.33 or newer cluster
kubectl configured to access the cluster
Helm 3.8 or newer
Capacity for the default installation: about 1 CPU core and 5.4 GiB of memory requests, plus room for installation Jobs

Install with Helm¶

If HAPTIC is already installed, continue to the sample app below or follow Upgrading with Helm to change its version.

For a new installation, install the released chart below. Choose that version in the documentation menu when following other guides; dev includes unreleased features.

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

The chart installs the controller, HAProxy, and routing templates. Admission validation checks proposed routing changes before Kubernetes accepts them.

The chart creates a default HTTPS certificate. It uses cert-manager for issuance and renewal when available; otherwise, it creates a self-signed certificate. For your own domains, configure SSL certificates.

Wait for the two controller replicas and two HAProxy replicas to become ready:

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

The chart creates IngressClass haptic and, when the Gateway API CRDs are available, GatewayClass haptic.

For your own applications, use ingressClassName: haptic on an Ingress or gatewayClassName: haptic on a Gateway. See the Ingress examples or Gateway routing guide.

Optional walkthrough: route a sample app¶

Follow this walkthrough to try a route, or continue with your own applications using the routing guides.

Deploy a sample app¶

Create a simple echo service:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: echo
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: echo
  template:
    metadata:
      labels:
        app: echo
    spec:
      containers:
      - name: echo
        image: ealen/echo-server:latest
        ports:
        - containerPort: 80
        env:
        - name: PORT
          value: "80"
---
apiVersion: v1
kind: Service
metadata:
  name: echo
  namespace: default
spec:
  selector:
    app: echo
  ports:
  - port: 80
    targetPort: 80

Save as echo-app.yaml and apply:

kubectl apply -f echo-app.yaml
kubectl -n default rollout status deployment/echo --timeout=180s

Create an Ingress¶

Create an Ingress that routes your test hostname to the echo service:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: echo-ingress
  namespace: default
spec:
  ingressClassName: haptic
  rules:
  - host: echo.example.local
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: echo
            port:
              number: 80

Save as echo-ingress.yaml and apply:

kubectl apply -f echo-ingress.yaml

The route also serves HTTPS with the chart's default certificate. For your own hostname, follow TLS certificate setup.

Test the routing¶

Forward a local port to HAProxy:

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

In another terminal:

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

The response includes the request headers and the serving pod's HOSTNAME. Repeat the request to check that HAProxy distributes traffic across the echo pods. If the request fails, follow routing troubleshooting.

To inspect what HAPTIC generated, see configuration debugging.

Next steps¶

What you want to do	Read next
Route your applications	Ingress or Gateway API
Replace another ingress controller	Migration guide
Change chart settings	Helm deployment and values reference
Add a custom annotation or routing rule	Templating
Use your own resource types	Watching resources
Prepare for production traffic	High availability, security, and monitoring

If installation or routing fails, follow troubleshooting.

Clean up¶

Stop port forwarding with Ctrl+C, then remove the sample app if you deployed it:

kubectl delete ingress echo-ingress -n default
kubectl delete deployment echo -n default
kubectl delete service echo -n default

HAPTIC remains installed for your own applications. To remove the controller and HAProxy too, follow Uninstalling.

Try in your browser¶

This example turns sample Ingress resources into HAProxy configuration without connecting to a cluster.

In Resources, change shop.example.com to store.example.com. The maps output shows the new hostname in host.map.

Found a problem on this page? Report it