Ingress

Configure Ingress resources

Before you configure Ingress resources, enable Ingress support. This page shows you how to choose which Ingress resources the controller manages, define an Ingress, terminate TLS, route requests to a default backend, and customize backend behavior with Backend CRs.

Choose which Ingress resources to handle Jump to heading

HAProxy Unified Gateway uses the same IngressClass rules as HAProxy Kubernetes Ingress Controller. The IngressClass resource is what connects an Ingress to the controller.

Create an IngressClass Jump to heading

Create an IngressClass whose spec.controller is haproxy.org/ingress-controller:

ingressclass.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: hug
spec:
controller: haproxy.org/ingress-controller
ingressclass.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: hug
spec:
controller: haproxy.org/ingress-controller

Apply the manifest:

nix
kubectl apply -f ingressclass.yaml
nix
kubectl apply -f ingressclass.yaml
output
text
ingressclass.networking.k8s.io/hug created
output
text
ingressclass.networking.k8s.io/hug created

The IngressClass name is arbitrary. Use hug in your Ingress resources, or pick a name that matches your naming conventions.

If you start the controller with --ingress-class=<suffix>, set spec.controller to haproxy.org/ingress-controller/<suffix> instead:

ingressclass.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: hug-prod
spec:
controller: haproxy.org/ingress-controller/prod
ingressclass.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: hug-prod
spec:
controller: haproxy.org/ingress-controller/prod

Control class matching Jump to heading

The controller decides whether to handle an Ingress from the class named by the Ingress, or from the default class when the Ingress has no class specified. The table below shows how each option behaves.

The IngressClass must exist

The controller reads the controller name from the IngressClass resource. An Ingress that names a class that isn’t configured in the cluster is ignored, even when the class name looks correct. The controller re-evaluates Ingress resources when their IngressClass appears or changes, so it may pick up a previously ignored Ingress.

Controller configuration The controller manages
No --ingress-class Ingress resources that refer, through spec.ingressClassName, to an IngressClass with spec.controller set to haproxy.org/ingress-controller. Also includes Ingress resources with no class specified when there is no default IngressClass, or when the default IngressClass names that controller.
--ingress-class=<suffix> Ingress resources that refer, through spec.ingressClassName, to an IngressClass with spec.controller set to haproxy.org/ingress-controller/<suffix>. Also includes Ingress resources with no class specified when the default IngressClass has that controller.
--ingress-class with --empty-ingress-class The same Ingress resources, plus every Ingress with no class specified.

Info

The controller ignores Ingress resources that use an IngressClass with a different controller name. It also clears status.loadBalancer.ingress on Ingress resources it considers ineligible, unless you start it with --disable-ingress-status-update. In a cluster with another ingress controller, use that flag or scope HAProxy Unified Gateway to its own namespaces.

--empty-ingress-class claims every Ingress without an IngressClass specified, even when another controller owns the default class. Use it only when HAProxy Unified Gateway should own those Ingress resources.

--namespaces also limits Ingress support. The controller watches Ingress resources only in the namespaces you list, so an Ingress in another namespace is ignored even when its class matches.

Tip

To make an IngressClass the cluster default, add the ingressclass.kubernetes.io/is-default-class: "true" annotation:

ingressclass.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: hug
annotations:
ingressclass.kubernetes.io/is-default-class: "true"
spec:
controller: haproxy.org/ingress-controller
ingressclass.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: hug
annotations:
ingressclass.kubernetes.io/is-default-class: "true"
spec:
controller: haproxy.org/ingress-controller

Define an Ingress Jump to heading

An Ingress resource maps a host and path to a Service. Start with a single host and a prefix path. You can then enable TLS and customize backend behavior.

To define an Ingress:

  1. Create the Ingress.
  2. Optional: Test the route.

Create the Ingress Jump to heading

ingress.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
namespace: default
spec:
ingressClassName: hug
rules:
- host: example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web-svc
port:
number: 80
ingress.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
namespace: default
spec:
ingressClassName: hug
rules:
- host: example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web-svc
port:
number: 80

Apply the manifest:

nix
kubectl apply -f ingress.yaml
nix
kubectl apply -f ingress.yaml
output
text
ingress.networking.k8s.io/web created
output
text
ingress.networking.k8s.io/web created

The fields in this example do the following:

Field Description
ingressClassName Names the IngressClass that connects this Ingress to HAProxy Unified Gateway.
rules[].host Matches requests for example.com. Use *.example.com for a wildcard host, or leave the host empty to match every host.
pathType Prefix matches / and every path below it. Use Exact when only the exact path should match.
backend.service Names the Service and port that receive the request. You can use port.number or port.name.

An Ingress with several rules creates several synthetic routes. Each rule can name its own host.

Use a wildcard host or a named port

The host can be a wildcard, and the backend port can be a named port. In this example, we route every subdomain of example.com to the http port on the web-svc Service:

ingress-wildcard.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-wildcard
namespace: default
spec:
ingressClassName: hug
rules:
- host: "*.example.com"
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web-svc
port:
name: http
ingress-wildcard.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-wildcard
namespace: default
spec:
ingressClassName: hug
rules:
- host: "*.example.com"
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web-svc
port:
name: http

Apply the manifest:

nix
kubectl apply -f ingress-wildcard.yaml
nix
kubectl apply -f ingress-wildcard.yaml
output
text
ingress.networking.k8s.io/web-wildcard created
output
text
ingress.networking.k8s.io/web-wildcard created

The Service must have a port named http. A named port is resolved against the Service in the Ingress namespace.

The controller also sets status.loadBalancer.ingress on managed Ingress resources so that tools can discover the address. To turn off status updates, start the controller with --disable-ingress-status-update.

Test the route Jump to heading

To test the route that was created using your Ingress definition:

  1. Optional: Deploy a test application.

    Deploy an example application

    If you don’t have an application to test with, deploy one that returns a fixed response:

    app.yaml
    yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
    name: web-svc
    namespace: default
    spec:
    replicas: 1
    selector:
    matchLabels:
    app: web-svc
    template:
    metadata:
    labels:
    app: web-svc
    spec:
    containers:
    - name: web
    image: hashicorp/http-echo:1.0
    args: ["-text=WEB RESPONSE"]
    ports:
    - containerPort: 5678
    ---
    apiVersion: v1
    kind: Service
    metadata:
    name: web-svc
    namespace: default
    spec:
    selector:
    app: web-svc
    ports:
    - name: http
    port: 80
    targetPort: 5678
    app.yaml
    yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
    name: web-svc
    namespace: default
    spec:
    replicas: 1
    selector:
    matchLabels:
    app: web-svc
    template:
    metadata:
    labels:
    app: web-svc
    spec:
    containers:
    - name: web
    image: hashicorp/http-echo:1.0
    args: ["-text=WEB RESPONSE"]
    ports:
    - containerPort: 5678
    ---
    apiVersion: v1
    kind: Service
    metadata:
    name: web-svc
    namespace: default
    spec:
    selector:
    app: web-svc
    ports:
    - name: http
    port: 80
    targetPort: 5678

    Apply the manifest:

    nix
    kubectl apply -f app.yaml
    nix
    kubectl apply -f app.yaml
    output
    text
    deployment.apps/web-svc created
    service/web-svc created
    output
    text
    deployment.apps/web-svc created
    service/web-svc created
  2. Forward the Ingress HTTP port from the controller Pod:

    Caution

    In production, point your DNS or external load balancer at the Service address instead of using port-forward. Don’t use kubectl port-forward in production.

    nix
    kubectl port-forward -n haproxy-unified-gateway deploy/haproxy-unified-gateway 8080:8080
    nix
    kubectl port-forward -n haproxy-unified-gateway deploy/haproxy-unified-gateway 8080:8080
    output
    text
    Forwarding from 127.0.0.1:8080 -> 8080
    Forwarding from [::1]:8080 -> 8080
    output
    text
    Forwarding from 127.0.0.1:8080 -> 8080
    Forwarding from [::1]:8080 -> 8080
  3. In another terminal, send a request with the host from the Ingress:

    nix
    curl -H "Host: example.com" http://localhost:8080/
    nix
    curl -H "Host: example.com" http://localhost:8080/

    You should get a response from your application or from the test applicaton if you deployed it.

    output with test application
    text
    WEB RESPONSE
    output with test application
    text
    WEB RESPONSE

Terminate TLS Jump to heading

Ingress TLS termination uses the certificates in spec.tls. HAProxy Unified Gateway creates the HTTPS listener the first time a managed Ingress declares a TLS secret. To terminate TLS:

  1. Create a Secret that contains the certificate and key for your host. Specify your certificate and key:

    Create the Secret first

    If an Ingress references a Secret that doesn’t exist, the controller skips the HTTPS listener and removes the hug_https_8443 frontend. HTTPS traffic stops for every managed Ingress until the Secret exists or the Ingress is removed. Create the Secret before, or together with, the Ingress that references it.

    Tip

    On Linux, you can generate a self-signed TLS certificate for the domain example.com (which this example uses) with this command:

    nix
    openssl req -x509 -nodes -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=example.com" -days 365
    nix
    openssl req -x509 -nodes -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=example.com" -days 365
    nix
    kubectl create secret tls example-tls --cert=tls.crt --key=tls.key
    nix
    kubectl create secret tls example-tls --cert=tls.crt --key=tls.key
    output
    text
    secret/example-tls created
    output
    text
    secret/example-tls created
  2. Add a tls section to the Ingress:

    ingress.yaml
    yaml
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
    name: web
    namespace: default
    spec:
    ingressClassName: hug
    tls:
    - secretName: example-tls
    rules:
    - host: example.com
    http:
    paths:
    - path: /
    pathType: Prefix
    backend:
    service:
    name: web-svc
    port:
    number: 80
    ingress.yaml
    yaml
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
    name: web
    namespace: default
    spec:
    ingressClassName: hug
    tls:
    - secretName: example-tls
    rules:
    - host: example.com
    http:
    paths:
    - path: /
    pathType: Prefix
    backend:
    service:
    name: web-svc
    port:
    number: 80
  3. Apply the updated Ingress manifest:

    nix
    kubectl apply -f ingress.yaml
    nix
    kubectl apply -f ingress.yaml
    output
    text
    ingress.networking.k8s.io/web configured
    output
    text
    ingress.networking.k8s.io/web configured

    Info

    The controller collects the certificate Secrets from every managed Ingress into one HTTPS listener and uses HAProxy’s SNI handling to select the certificate for each request. The spec.tls[].hosts field is standard Ingress syntax, but the controller doesn’t use it to create per-host listeners.

  4. Optional: Test the HTTPS route with the controller’s HTTPS port:

    nix
    kubectl port-forward -n haproxy-unified-gateway deploy/haproxy-unified-gateway 8443:8443
    nix
    kubectl port-forward -n haproxy-unified-gateway deploy/haproxy-unified-gateway 8443:8443
    output
    text
    Forwarding from 127.0.0.1:8443 -> 8443
    Forwarding from [::1]:8443 -> 8443
    output
    text
    Forwarding from 127.0.0.1:8443 -> 8443
    Forwarding from [::1]:8443 -> 8443
    nix
    curl --resolve example.com:8443:127.0.0.1 https://example.com:8443/ -k
    nix
    curl --resolve example.com:8443:127.0.0.1 https://example.com:8443/ -k
    output
    text
    WEB RESPONSE
    output
    text
    WEB RESPONSE

    Caution

    The -k flag accepts the self-signed certificate from the test Secret. Don’t use it with a production certificate, and don’t use kubectl port-forward in production.

Route requests with a default backend Jump to heading

spec.defaultBackend handles requests that don’t match a rule. The controller translates it into a hostless route with a / prefix match, which gives it the lowest routing precedence. In the example below, requests for api.example.com/api match the rule. Requests for hosts or paths that no other Ingress matches fall through to defaultBackend.

ingress-default.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-default
namespace: default
spec:
ingressClassName: hug
defaultBackend:
service:
name: web-svc
port:
number: 80
rules:
- host: api.example.com
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: web-svc
port:
number: 80
ingress-default.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-default
namespace: default
spec:
ingressClassName: hug
defaultBackend:
service:
name: web-svc
port:
number: 80
rules:
- host: api.example.com
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: web-svc
port:
number: 80

Customize backend behavior Jump to heading

Use a Backend CR to customize how the load balancer should route traffic to your Pods. For example, you can use a Backend CR to:

  • Choose a load balancing algorithm such as leastconn for long-lived connections or source for client affinity.
  • Set server timeouts for slow or streaming APIs.
  • Add health checks so that the load balancer removes unhealthy endpoints.
  • Add or modify request and response headers for tracing, caching, or security.
  • Apply HTTP request and response rules, such as header changes or access checks.

The cr-backend annotation on the Ingress points at the Backend CR; the settings live in the CR.

Backend configuration comes from custom resources

If your Ingress has annotations such as balance, timeout-server, and check, they are ignored. The only annotation on Ingress that the controller uses is the cr-backend annotation. Use Gateway API filters or settings for frontend behavior.

To customize the backend:

  1. Install the Backend CRD.
  2. Attach a Backend CR.

Install the Backend CRD Jump to heading

The cr-backend annotation requires the ingress.v3.haproxy.org Backend CRD from HAProxy Kubernetes Ingress Controller. If it isn’t installed, install it:

nix
kubectl apply -f https://www.haproxy.com/documentation/kubernetes-ingress/community/crd/v3-2/ingress.v3.haproxy.org_backends.yaml
nix
kubectl apply -f https://www.haproxy.com/documentation/kubernetes-ingress/community/crd/v3-2/ingress.v3.haproxy.org_backends.yaml
output
text
customresourcedefinition.apiextensions.k8s.io/backends.ingress.v3.haproxy.org created
output
text
customresourcedefinition.apiextensions.k8s.io/backends.ingress.v3.haproxy.org created

If you installed HAProxy Kubernetes Ingress Controller with Helm, the CRD is already installed.

Info

The cr-backend annotation on an Ingress points at an ingress.v3.haproxy.org Backend, which is the custom resource from HAProxy Kubernetes Ingress Controller. HAProxy Kubernetes Ingress Controller uses the same annotation, so an Ingress that already references a Backend CR keeps the reference when you migrate. The CRD must be installed in the cluster. If the controller can’t resolve the Backend CR, it builds the backend with default settings.

Caution

The HAProxy Kubernetes Ingress Controller ingress.v3.haproxy.org Backend CRD and the HAProxy Unified Gateway gate.v3.haproxy.org Backend CRD are separate resources. They are not interchangeable.

Attach a Backend CR Jump to heading

Add the cr-backend annotation to the Ingress. The value is the name of an ingress.v3.haproxy.org Backend custom resource in the same namespace:

ingress.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
namespace: default
annotations:
cr-backend: web-backend
spec:
ingressClassName: hug
rules:
- host: example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web-svc
port:
number: 80
ingress.yaml
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
namespace: default
annotations:
cr-backend: web-backend
spec:
ingressClassName: hug
rules:
- host: example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web-svc
port:
number: 80

In this example, we’ll set the load balancing algorithm to leastconn and add an X-Served-By header.

Create the Backend custom resource:

backend.yaml
yaml
apiVersion: ingress.v3.haproxy.org/v3
kind: Backend
metadata:
name: web-backend
namespace: default
spec:
balance:
algorithm: leastconn
server_timeout: 71000
http_request_rule_list:
- type: set-header
hdr_name: X-Served-By
hdr_format: hug
backend.yaml
yaml
apiVersion: ingress.v3.haproxy.org/v3
kind: Backend
metadata:
name: web-backend
namespace: default
spec:
balance:
algorithm: leastconn
server_timeout: 71000
http_request_rule_list:
- type: set-header
hdr_name: X-Served-By
hdr_format: hug

Apply both resources:

nix
kubectl apply -f backend.yaml -f ingress.yaml
nix
kubectl apply -f backend.yaml -f ingress.yaml
output
text
backend.ingress.v3.haproxy.org/web-backend created
ingress.networking.k8s.io/web configured
output
text
backend.ingress.v3.haproxy.org/web-backend created
ingress.networking.k8s.io/web configured

Apply the Backend CR before the Ingress, or at the same time. The controller rebuilds the backends when the Backend CR changes. For the full set of fields in the Ingress Controller Backend CR, see Backend CRD.

Use an HAProxy Unified Gateway Backend CR Jump to heading

Info

For new Ingress resources, use this HAProxy Unified Gateway Backend path. The Ingress-level cr-backend path exists for migration from HAProxy Kubernetes Ingress Controller.

The cr-backend annotation on an Ingress points at an HAProxy Kubernetes Ingress Controller ingress.v3.haproxy.org Backend. To use an HAProxy Unified Gateway gate.v3.haproxy.org Backend instead, attach the annotation to the Service that the Ingress routes to:

service.yaml
yaml
apiVersion: v1
kind: Service
metadata:
name: web-svc
namespace: default
annotations:
gate.v3.haproxy.org/cr-backend: web-backend
spec:
selector:
app: web-svc
ports:
- name: http
port: 80
targetPort: 5678
service.yaml
yaml
apiVersion: v1
kind: Service
metadata:
name: web-svc
namespace: default
annotations:
gate.v3.haproxy.org/cr-backend: web-backend
spec:
selector:
app: web-svc
ports:
- name: http
port: 80
targetPort: 5678

HAProxy Unified Gateway merges the gate.v3.haproxy.org Backend CR named web-backend into the backend it builds for this Service. The annotation applies to every Ingress or Gateway API route that uses the Service. The Ingress-level cr-backend annotation is only for HAProxy Kubernetes Ingress Controller Backends.

For the fields available in a HAProxy Unified Gateway Backend CR, see Backend CRD.

If a route doesn’t work, see Troubleshoot Ingress resources. If you’re moving from another controller, see Migrate from HAProxy Kubernetes Ingress Controller or Migrate from an NGINX ingress controller.

Do you have any suggestions on how we can improve the content of this page? Please leave feedback!