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.yamlyamlapiVersion: networking.k8s.io/v1kind: IngressClassmetadata:name: hugspec:controller: haproxy.org/ingress-controller
ingressclass.yamlyamlapiVersion: networking.k8s.io/v1kind: IngressClassmetadata:name: hugspec:controller: haproxy.org/ingress-controller
Apply the manifest:
nixkubectl apply -f ingressclass.yaml
nixkubectl apply -f ingressclass.yaml
outputtextingressclass.networking.k8s.io/hug created
outputtextingressclass.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.yamlyamlapiVersion: networking.k8s.io/v1kind: IngressClassmetadata:name: hug-prodspec:controller: haproxy.org/ingress-controller/prod
ingressclass.yamlyamlapiVersion: networking.k8s.io/v1kind: IngressClassmetadata:name: hug-prodspec: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.yamlyamlapiVersion: networking.k8s.io/v1kind: IngressClassmetadata:name: hugannotations:ingressclass.kubernetes.io/is-default-class: "true"spec:controller: haproxy.org/ingress-controller
ingressclass.yamlyamlapiVersion: networking.k8s.io/v1kind: IngressClassmetadata:name: hugannotations: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:
- Create the Ingress.
- Optional: Test the route.
Create the Ingress Jump to heading
ingress.yamlyamlapiVersion: networking.k8s.io/v1kind: Ingressmetadata:name: webnamespace: defaultspec:ingressClassName: hugrules:- host: example.comhttp:paths:- path: /pathType: Prefixbackend:service:name: web-svcport:number: 80
ingress.yamlyamlapiVersion: networking.k8s.io/v1kind: Ingressmetadata:name: webnamespace: defaultspec:ingressClassName: hugrules:- host: example.comhttp:paths:- path: /pathType: Prefixbackend:service:name: web-svcport:number: 80
Apply the manifest:
nixkubectl apply -f ingress.yaml
nixkubectl apply -f ingress.yaml
outputtextingress.networking.k8s.io/web created
outputtextingress.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.yamlyamlapiVersion: networking.k8s.io/v1kind: Ingressmetadata:name: web-wildcardnamespace: defaultspec:ingressClassName: hugrules:- host: "*.example.com"http:paths:- path: /pathType: Prefixbackend:service:name: web-svcport:name: http
ingress-wildcard.yamlyamlapiVersion: networking.k8s.io/v1kind: Ingressmetadata:name: web-wildcardnamespace: defaultspec:ingressClassName: hugrules:- host: "*.example.com"http:paths:- path: /pathType: Prefixbackend:service:name: web-svcport:name: http
Apply the manifest:
nixkubectl apply -f ingress-wildcard.yaml
nixkubectl apply -f ingress-wildcard.yaml
outputtextingress.networking.k8s.io/web-wildcard created
outputtextingress.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:
-
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.yamlyamlapiVersion: apps/v1kind: Deploymentmetadata:name: web-svcnamespace: defaultspec:replicas: 1selector:matchLabels:app: web-svctemplate:metadata:labels:app: web-svcspec:containers:- name: webimage: hashicorp/http-echo:1.0args: ["-text=WEB RESPONSE"]ports:- containerPort: 5678---apiVersion: v1kind: Servicemetadata:name: web-svcnamespace: defaultspec:selector:app: web-svcports:- name: httpport: 80targetPort: 5678app.yamlyamlapiVersion: apps/v1kind: Deploymentmetadata:name: web-svcnamespace: defaultspec:replicas: 1selector:matchLabels:app: web-svctemplate:metadata:labels:app: web-svcspec:containers:- name: webimage: hashicorp/http-echo:1.0args: ["-text=WEB RESPONSE"]ports:- containerPort: 5678---apiVersion: v1kind: Servicemetadata:name: web-svcnamespace: defaultspec:selector:app: web-svcports:- name: httpport: 80targetPort: 5678Apply the manifest:
nixkubectl apply -f app.yamlnixkubectl apply -f app.yamloutputtextdeployment.apps/web-svc createdservice/web-svc createdoutputtextdeployment.apps/web-svc createdservice/web-svc created -
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 usekubectl port-forwardin production.nixkubectl port-forward -n haproxy-unified-gateway deploy/haproxy-unified-gateway 8080:8080nixkubectl port-forward -n haproxy-unified-gateway deploy/haproxy-unified-gateway 8080:8080outputtextForwarding from 127.0.0.1:8080 -> 8080Forwarding from [::1]:8080 -> 8080outputtextForwarding from 127.0.0.1:8080 -> 8080Forwarding from [::1]:8080 -> 8080 -
In another terminal, send a request with the host from the Ingress:
nixcurl -H "Host: example.com" http://localhost:8080/nixcurl -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 applicationtextWEB RESPONSEoutput with test applicationtextWEB 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:
-
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_8443frontend. 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:nixopenssl req -x509 -nodes -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=example.com" -days 365nixopenssl req -x509 -nodes -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=example.com" -days 365nixkubectl create secret tls example-tls --cert=tls.crt --key=tls.keynixkubectl create secret tls example-tls --cert=tls.crt --key=tls.keyoutputtextsecret/example-tls createdoutputtextsecret/example-tls created -
Add a
tlssection to the Ingress:ingress.yamlyamlapiVersion: networking.k8s.io/v1kind: Ingressmetadata:name: webnamespace: defaultspec:ingressClassName: hugtls:- secretName: example-tlsrules:- host: example.comhttp:paths:- path: /pathType: Prefixbackend:service:name: web-svcport:number: 80ingress.yamlyamlapiVersion: networking.k8s.io/v1kind: Ingressmetadata:name: webnamespace: defaultspec:ingressClassName: hugtls:- secretName: example-tlsrules:- host: example.comhttp:paths:- path: /pathType: Prefixbackend:service:name: web-svcport:number: 80 -
Apply the updated Ingress manifest:
nixkubectl apply -f ingress.yamlnixkubectl apply -f ingress.yamloutputtextingress.networking.k8s.io/web configuredoutputtextingress.networking.k8s.io/web configuredInfo
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[].hostsfield is standard Ingress syntax, but the controller doesn’t use it to create per-host listeners. -
Optional: Test the HTTPS route with the controller’s HTTPS port:
nixkubectl port-forward -n haproxy-unified-gateway deploy/haproxy-unified-gateway 8443:8443nixkubectl port-forward -n haproxy-unified-gateway deploy/haproxy-unified-gateway 8443:8443outputtextForwarding from 127.0.0.1:8443 -> 8443Forwarding from [::1]:8443 -> 8443outputtextForwarding from 127.0.0.1:8443 -> 8443Forwarding from [::1]:8443 -> 8443nixcurl --resolve example.com:8443:127.0.0.1 https://example.com:8443/ -knixcurl --resolve example.com:8443:127.0.0.1 https://example.com:8443/ -koutputtextWEB RESPONSEoutputtextWEB RESPONSECaution
The
-kflag accepts the self-signed certificate from the test Secret. Don’t use it with a production certificate, and don’t usekubectl port-forwardin 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.yamlyamlapiVersion: networking.k8s.io/v1kind: Ingressmetadata:name: web-defaultnamespace: defaultspec:ingressClassName: hugdefaultBackend:service:name: web-svcport:number: 80rules:- host: api.example.comhttp:paths:- path: /apipathType: Prefixbackend:service:name: web-svcport:number: 80
ingress-default.yamlyamlapiVersion: networking.k8s.io/v1kind: Ingressmetadata:name: web-defaultnamespace: defaultspec:ingressClassName: hugdefaultBackend:service:name: web-svcport:number: 80rules:- host: api.example.comhttp:paths:- path: /apipathType: Prefixbackend:service:name: web-svcport: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
leastconnfor long-lived connections orsourcefor 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:
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:
nixkubectl apply -f https://www.haproxy.com/documentation/kubernetes-ingress/community/crd/v3-2/ingress.v3.haproxy.org_backends.yaml
nixkubectl apply -f https://www.haproxy.com/documentation/kubernetes-ingress/community/crd/v3-2/ingress.v3.haproxy.org_backends.yaml
outputtextcustomresourcedefinition.apiextensions.k8s.io/backends.ingress.v3.haproxy.org created
outputtextcustomresourcedefinition.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.yamlyamlapiVersion: networking.k8s.io/v1kind: Ingressmetadata:name: webnamespace: defaultannotations:cr-backend: web-backendspec:ingressClassName: hugrules:- host: example.comhttp:paths:- path: /pathType: Prefixbackend:service:name: web-svcport:number: 80
ingress.yamlyamlapiVersion: networking.k8s.io/v1kind: Ingressmetadata:name: webnamespace: defaultannotations:cr-backend: web-backendspec:ingressClassName: hugrules:- host: example.comhttp:paths:- path: /pathType: Prefixbackend:service:name: web-svcport: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.yamlyamlapiVersion: ingress.v3.haproxy.org/v3kind: Backendmetadata:name: web-backendnamespace: defaultspec:balance:algorithm: leastconnserver_timeout: 71000http_request_rule_list:- type: set-headerhdr_name: X-Served-Byhdr_format: hug
backend.yamlyamlapiVersion: ingress.v3.haproxy.org/v3kind: Backendmetadata:name: web-backendnamespace: defaultspec:balance:algorithm: leastconnserver_timeout: 71000http_request_rule_list:- type: set-headerhdr_name: X-Served-Byhdr_format: hug
Apply both resources:
nixkubectl apply -f backend.yaml -f ingress.yaml
nixkubectl apply -f backend.yaml -f ingress.yaml
outputtextbackend.ingress.v3.haproxy.org/web-backend createdingress.networking.k8s.io/web configured
outputtextbackend.ingress.v3.haproxy.org/web-backend createdingress.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.yamlyamlapiVersion: v1kind: Servicemetadata:name: web-svcnamespace: defaultannotations:gate.v3.haproxy.org/cr-backend: web-backendspec:selector:app: web-svcports:- name: httpport: 80targetPort: 5678
service.yamlyamlapiVersion: v1kind: Servicemetadata:name: web-svcnamespace: defaultannotations:gate.v3.haproxy.org/cr-backend: web-backendspec:selector:app: web-svcports:- name: httpport: 80targetPort: 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.