Define HTTPRoutes for HAProxy Unified Gateway

The Gateway API defines specialized resources for routing different types of network traffic. You would use an HTTPRoute resource to route HTTP traffic.

Prerequisites checklist Jump to heading

Before continuing, ensure that you’ve met these prerequisites:

Define a Gateway. When defining a Gateway, add an HTTP and/or HTTPS listener that sets its allowedRoutes property to accept routes of kind HTTPRoute.

Implement hostname-based routing Jump to heading

Hostname-based routing is useful when you want to route traffic based on the domain. For example, you want to route traffic for api.example.com and web.example.com to different services.

To implement hostname-based routing:

If your Gateway resource sets a hostname field, update it and omit or comment out hostname. This ensures that the Gateway will relay traffic for all of your domains. You’ll filter by hostname in the HTTPRoute resource.

gateway.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-haproxy-gateway
  namespace: default
spec:
  gatewayClassName: haproxy
  listeners:
    - name: http
      protocol: HTTP
      port: 31080
      # hostname: "example.com"
      allowedRoutes:
        kinds:
          - group: gateway.networking.k8s.io
            kind: HTTPRoute
        namespaces:
          from: Same

gateway.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-haproxy-gateway
  namespace: default
spec:
  gatewayClassName: haproxy
  listeners:
    - name: http
      protocol: HTTP
      port: 31080
      # hostname: "example.com"
      allowedRoutes:
        kinds:
          - group: gateway.networking.k8s.io
            kind: HTTPRoute
        namespaces:
          from: Same

Apply the changes with kubectl:

nix
kubectl apply -f gateway.yaml

nix
kubectl apply -f gateway.yaml

output
text
gateway.gateway.networking.k8s.io/example-haproxy-gateway configured

output
text
gateway.gateway.networking.k8s.io/example-haproxy-gateway configured

Define an HTTPRoute resource for your target domain(s). In this example, we route traffic for the hostname web.example.com.

Section	Description
parentRefs	References one or more Gateways to which an HTTPRoute tries to attach. This HTTPRoute will attach to `Gateway` resources that have listeners with `allowedRoutes` matching the `HTTPRoute` kind and a matching namespace. The `sectionName` field specifies the name of the listener on the Gateway to attach to. In this example, we attach to the HTTP listener, but you could attach to the HTTPS listener.
hostnames	Lists hostnames to accept traffic for.
rules	Each entry has a `backendRefs` section to route to the specified service. For example, requests for `web.example.com` will route to `web-svc`. A `backendRefs` entry refers to the name of a Service resource and its listening port.

hostname-based-route.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-hostname-route
  namespace: default
spec:
  parentRefs:
    - name: example-haproxy-gateway
      sectionName: http-listener
  hostnames: 
    - web.example.com
  rules:
    - backendRefs:
        - name: web-svc
          namespace: default
          port: 80

hostname-based-route.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-hostname-route
  namespace: default
spec:
  parentRefs:
    - name: example-haproxy-gateway
      sectionName: http-listener
  hostnames: 
    - web.example.com
  rules:
    - backendRefs:
        - name: web-svc
          namespace: default
          port: 80

Apply the changes with kubectl:

nix
kubectl apply -f hostname-based-route.yaml

nix
kubectl apply -f hostname-based-route.yaml

output
text
httproute.gateway.networking.k8s.io/web-hostname-route created

output
text
httproute.gateway.networking.k8s.io/web-hostname-route created

If your HTTPRoute resource lists a backendRefs Service that’s in a namespace that’s different from the namespace where the HTTPRoute is defined, you’ll need to add a ReferenceGrant for cross-namespace service references.

Implement path-based routing Jump to heading

Migrating from Ingress API

Path-based routing with Gateway API behaves similarly to traditional Ingress rules. This makes it easy to migrate from HAProxy Kubernetes Ingress Controller or other Ingress controller implementations.

Path-based routing is useful when you have multiple applications under the same domain and want to route traffic based on the URL path. For example, you want to route traffic for example.com/web.

To implement path-based routing:

Define an HTTPRoute for routing HTTP traffic for the target URL paths. In this example, we route traffic for the path /web.

Section	Description
parentRefs	References one or more Gateways to which an HTTPRoute tries to attach. This HTTPRoute will attach to `Gateway` resources that have listeners with `allowedRoutes` matching the `HTTPRoute` kind and a matching namespace. The `sectionName` field specifies the name of the listener on the Gateway to attach to. In this example, we attach to the HTTP listener, but you could attach to the HTTPS listener.
rules	Each entry has a `matches` and `backendRefs` section. For a path-matching rule, set the `type` to `PathPrefix`. This means that URL paths that begin with the specified `value` will be routed to the service specified by the `backendRefs` entry. For example, requests beginning with `/web` will route to `web-svc`. A `backendRefs` entry refers to the name of a Service resource and its listening port.

path-based-route.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: path-based-route
  namespace: default
spec:
  parentRefs:
    - name: example-haproxy-gateway
      sectionName: http-listener
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /web
      backendRefs:
        - name: web-svc
          namespace: default
          port: 80

path-based-route.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: path-based-route
  namespace: default
spec:
  parentRefs:
    - name: example-haproxy-gateway
      sectionName: http-listener
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /web
      backendRefs:
        - name: web-svc
          namespace: default
          port: 80

Apply the changes with kubectl:

nix
kubectl apply -f path-based-route.yaml

nix
kubectl apply -f path-based-route.yaml

output
text
httproute.gateway.networking.k8s.io/path-based-route created

output
text
httproute.gateway.networking.k8s.io/path-based-route created

Optional: If your HTTPRoute resource lists a backendRefs Service that’s in a namespace that’s different from the namespace where the HTTPRoute is defined, you’ll need to add a ReferenceGrant for cross-namespace service references.

Optional: When using path-based routing, you may want to restrict which hostnames your Gateway will accept traffic for.

Update your Gateway resource to set the hostname field on the listener.

gateway.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-haproxy-gateway
  namespace: default
spec:
  gatewayClassName: haproxy
  listeners:
    - name: http
      protocol: HTTP
      port: 31080
      hostname: "example.com"
      allowedRoutes:
        kinds:
          - group: gateway.networking.k8s.io
            kind: HTTPRoute
        namespaces:
          from: Same

gateway.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-haproxy-gateway
  namespace: default
spec:
  gatewayClassName: haproxy
  listeners:
    - name: http
      protocol: HTTP
      port: 31080
      hostname: "example.com"
      allowedRoutes:
        kinds:
          - group: gateway.networking.k8s.io
            kind: HTTPRoute
        namespaces:
          from: Same

Apply the changes with kubectl:

nix
kubectl apply -f gateway.yaml

nix
kubectl apply -f gateway.yaml

output
text
gateway.gateway.networking.k8s.io/example-haproxy-gateway configured

output
text
gateway.gateway.networking.k8s.io/example-haproxy-gateway configured

Optional: To test connectivity with the Gateway and HTTPRoute you just defined, deploy the example application using Deployment and Service resources. The application uses the hashicorp/http-echo Docker container image. It’ll receive HTTP traffic on port 5678 and respond with text indicating the application’s name.

Note that the Service is named web-svc, which is the same Service name you specified when you defined your HTTPRoute in the previous steps, and it listens on port 80. This is how the HTTPRoute knows the Service to route to.

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:0.2.3
          args: ["-text=WEB RESPONSE"]
          ports:
            - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
  name: web-svc
  namespace: default
spec:
  selector:
    app: web-svc
  ports:
    - 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:0.2.3
          args: ["-text=WEB RESPONSE"]
          ports:
            - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
  name: web-svc
  namespace: default
spec:
  selector:
    app: web-svc
  ports:
    - port: 80
      targetPort: 5678

Apply the changes with kubectl:

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

Implement weighted traffic splitting Jump to heading

Use weighted traffic splitting when you want different percentages of traffic to route to different services. One use case is canary deployments. A canary deployment means routing a small percentage of traffic to the new version of your application, and then gradually ramping up, allowing you to release the new version in the safest possible way.

Define an HTTPRoute for routing HTTP traffic to your service.

Section	Description
parentRefs	References one or more Gateways to which the HTTPRoute wants to attach, which in this case is `example-haproxy-gateway`. The `sectionName` field specifies the name of the listener on the Gateway to attach to.
hostnames	We’re using hostname-based routing, so we’re including the `hostnames` section. In this example, we attach to the HTTP listener, but you could attach to the HTTPS listener.
rules	Lists two services, `blue` and `green`. The `blue` service will receive 90% of the traffic and the `green` service will receive 10% of the traffic.

http-route.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-route
  namespace: default
spec:
  parentRefs:
  - name: example-haproxy-gateway
    sectionName: http-listener
  hostnames:
  - "example.com"
  rules:
  - backendRefs:
    - name: blue
      namespace: default
      port: 80
      weight: 9
    - name: green
      namespace: default
      port: 80
      weight: 1

http-route.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-route
  namespace: default
spec:
  parentRefs:
  - name: example-haproxy-gateway
    sectionName: http-listener
  hostnames:
  - "example.com"
  rules:
  - backendRefs:
    - name: blue
      namespace: default
      port: 80
      weight: 9
    - name: green
      namespace: default
      port: 80
      weight: 1

Apply the changes with kubectl:

nix
kubectl apply -f http-route.yaml

nix
kubectl apply -f http-route.yaml

output
text
httproute.gateway.networking.k8s.io/canary-route created

output
text
httproute.gateway.networking.k8s.io/canary-route created

Optional: To test connectivity with the Gateway and HTTPRoute, deploy two test applications using Deployments and Services. Here, we define two example applications using the hashicorp/http-echo Docker container image. They will each receive HTTP traffic on port 5678 and respond with text indicating receipt of the request.

Note that the Services are named blue and green, the same Service names you specified when you defined your HTTPRoute in the previous steps, both listening on port 80, which you defined in the HTTPRoute as well. This is how the HTTPRoute knows the Service to route to.

apps.yaml
yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: blue
 namespace: default
spec:
 replicas: 1
 selector:
   matchLabels:
     app: blue
 template:
   metadata:
     labels:
       app: blue
   spec:
     containers:
       - name: blue
         image: hashicorp/http-echo
         args:
           - "-text=Hello from blue"
         ports:
           - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
 name: blue
 namespace: default
spec:
 selector:
   app: blue
 ports:
   - port: 80
     targetPort: 5678
---
apiVersion: apps/v1
kind: Deployment
metadata:
 name: green
 namespace: default
spec:
 replicas: 1
 selector:
   matchLabels:
     app: green
 template:
   metadata:
     labels:
       app: green
   spec:
     containers:
       - name: green
         image: hashicorp/http-echo
         args:
           - "-text=Hello from green"
         ports:
           - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
 name: green
 namespace: default
spec:
 selector:
   app: green
 ports:
   - port: 80
     targetPort: 5678

apps.yaml
yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: blue
 namespace: default
spec:
 replicas: 1
 selector:
   matchLabels:
     app: blue
 template:
   metadata:
     labels:
       app: blue
   spec:
     containers:
       - name: blue
         image: hashicorp/http-echo
         args:
           - "-text=Hello from blue"
         ports:
           - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
 name: blue
 namespace: default
spec:
 selector:
   app: blue
 ports:
   - port: 80
     targetPort: 5678
---
apiVersion: apps/v1
kind: Deployment
metadata:
 name: green
 namespace: default
spec:
 replicas: 1
 selector:
   matchLabels:
     app: green
 template:
   metadata:
     labels:
       app: green
   spec:
     containers:
       - name: green
         image: hashicorp/http-echo
         args:
           - "-text=Hello from green"
         ports:
           - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
 name: green
 namespace: default
spec:
 selector:
   app: green
 ports:
   - port: 80
     targetPort: 5678

Apply the changes with kubectl:

nix
kubectl apply -f apps.yaml

nix
kubectl apply -f apps.yaml

output
text
deployment.apps/blue created
service/blue created
deployment.apps/green created
service/green created

output
text
deployment.apps/blue created
service/blue created
deployment.apps/green created
service/green created

Add a ReferenceGrant for cross-namespace service references Jump to heading

If your HTTPRoute lists a Service under backendRefs that’s in a different namespace than the HTTPRoute resource, you’ll need to define a ReferenceGrant resource to allow cross-namespace communication between the HTTPRoute and the Service.

Below, we allow an HTTPRoute in the default namespace to reference a Service in the foo namespace. Note that the to section doesn’t need a namespace because a ReferenceGrant can refer only to resources defined in its own namespace.

foo-referencegrant.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: ReferenceGrant
metadata:
  name: refgrantns1
  namespace: foo
spec:
  from:
    - group: "gateway.networking.k8s.io"
      kind: "HTTPRoute"
      namespace: default
  to:
    - group: ""
      kind: "Service"

foo-referencegrant.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: ReferenceGrant
metadata:
  name: refgrantns1
  namespace: foo
spec:
  from:
    - group: "gateway.networking.k8s.io"
      kind: "HTTPRoute"
      namespace: default
  to:
    - group: ""
      kind: "Service"

Apply the changes with kubectl:

nix
kubectl apply -f foo-referencegrant.yaml

nix
kubectl apply -f foo-referencegrant.yaml

Rewrite the requested URL path Jump to heading

You may want to rewrite the URL path before forwarding the request to the backend, because:

Your backend expects a specific URL structure.
You want to hide internal routing details.
You’re consolidating multiple backend services under a shared URL prefix.
You want to expose a simpler API.
You’re migrating legacy Ingress rules to Gateway API.

To rewrite the requested URL path:

Define an HTTPRoute for routing HTTP traffic to your service.

The path-matching rule specifies the type as PathPrefix. This means that for URL paths that begin with the specified value will be routed to the corresponding service specified by the backendRefs in the rule. There’s also a filter of type: URLRewrite that instructs the HTTPRoute to replace /service with /.

http-route.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: rewrite-route
  namespace: default
spec:
  parentRefs:
    - name: example-haproxy-gateway
      sectionName: http-listener
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /service
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
      backendRefs:
        - name: rewrite-backend-svc
          namespace: default
          port: 80

http-route.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: rewrite-route
  namespace: default
spec:
  parentRefs:
    - name: example-haproxy-gateway
      sectionName: http-listener
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /service
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
      backendRefs:
        - name: rewrite-backend-svc
          namespace: default
          port: 80

Apply the changes with kubectl:

nix
kubectl apply -f http-route.yaml

nix
kubectl apply -f http-route.yaml

output
text
httproute.gateway.networking.k8s.io/rewrite-route created

output
text
httproute.gateway.networking.k8s.io/rewrite-route created

Optional: To test connectivity with the Gateway and HTTPRoute, deploy a test application using a Deployment and a Service. Here, we define an example application using the hashicorp/http-echo Docker container image. It will receive HTTP traffic on port 5678 (the Gateway terminates the TLS connection and then communicates with backend services over HTTP) and respond with text indicating receipt of the request.

Note that the Service is named rewrite-backend-svc, the same Service name you specified when you defined your HTTPRoute in the previous steps, listening on port 80, which you defined in the HTTPRoute as well. This is how the HTTPRoute knows what Service to route to.

apps.yaml
yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: rewrite-backend
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: rewrite-backend
  template:
    metadata:
      labels:
        app: rewrite-backend
    spec:
      containers:
        - name: echo
          image: hashicorp/http-echo
          args:
            - "-text=Rewrite backend reached"
          ports:
            - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
  name: rewrite-backend-svc
  namespace: default
spec:
  selector:
    app: rewrite-backend
  ports:
    - port: 80
      targetPort: 5678

apps.yaml
yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: rewrite-backend
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: rewrite-backend
  template:
    metadata:
      labels:
        app: rewrite-backend
    spec:
      containers:
        - name: echo
          image: hashicorp/http-echo
          args:
            - "-text=Rewrite backend reached"
          ports:
            - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
  name: rewrite-backend-svc
  namespace: default
spec:
  selector:
    app: rewrite-backend
  ports:
    - port: 80
      targetPort: 5678

Apply the changes with kubectl:

nix
kubectl apply -f apps.yaml

nix
kubectl apply -f apps.yaml

output
text
deployment.apps/tls-test created
service/tls-test-svc created

output
text
deployment.apps/tls-test created
service/tls-test-svc created

Product Documentation

API Documentation

Configuration Documentation

Define HTTPRoutes for HAProxy Unified Gateway

Prerequisites checklist Jump to heading

Implement hostname-based routing Jump to heading

Implement path-based routing Jump to heading

Implement weighted traffic splitting Jump to heading

Add a ReferenceGrant for cross-namespace service references Jump to heading

Rewrite the requested URL path Jump to heading

See also Jump to heading

Product Documentation

API Documentation

Configuration Documentation

Prerequisites checklist Jump to heading #

Implement hostname-based routing Jump to heading #

Implement path-based routing Jump to heading #

Implement weighted traffic splitting Jump to heading #

Add a ReferenceGrant for cross-namespace service references Jump to heading #

Rewrite the requested URL path Jump to heading #

See also Jump to heading #

Privacy Settings

Prerequisites checklist Jump to heading

Implement hostname-based routing Jump to heading

Implement path-based routing Jump to heading

Implement weighted traffic splitting Jump to heading

Add a ReferenceGrant for cross-namespace service references Jump to heading

Rewrite the requested URL path Jump to heading

See also Jump to heading