Routes

Define TCPRoutes for HAProxy Unified Gateway

This page applies to:

  • HAProxy Unified Gateway 1.1 and newer

The Gateway API defines specialized resources for routing different types of network traffic. You would use a TCPRoute resource to route TCP traffic that isn’t transporting HTTP messages. Because it routes based solely on the listener’s port and has no ability to match on hostname or other application-layer attributes, its rules consist of just the backend to use. Use cases include routing traffic for databases, message brokers, mail servers, and other TCP-based services.

Prerequisites checklist Jump to heading

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

  • Define a Gateway. When defining a Gateway, add a TCP listener and set its allowedRoutes property to accept routes of kind TCPRoute.

Define routing rules Jump to heading

In your TCPRoutes, you’ll define rules for routing TCP packets to your backend applications.

  1. Define a TCPRoute resource.

    Section Description
    parentRefs References one or more Gateways to which a TCPRoute tries to attach. This TCPRoute will attach to Gateway resources that have listeners with allowedRoutes matching the TCPRoute 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 TCP listener.
    rules Each entry has a backendRefs section to route to the specified service. For example, traffic that the Gateway’s TCP listener receives will route to tcp-svc. A backendRefs entry refers to the name of a Service resource and its listening port.
    tcproute.yaml
    yaml
    apiVersion: gateway.networking.k8s.io/v1
    kind: TCPRoute
    metadata:
    name: tcp-route
    namespace: default
    spec:
    parentRefs:
    - name: example-haproxy-gateway
    sectionName: tcp-listener
    rules:
    - backendRefs:
    - name: tcp-svc
    namespace: default
    port: 3000
    tcproute.yaml
    yaml
    apiVersion: gateway.networking.k8s.io/v1
    kind: TCPRoute
    metadata:
    name: tcp-route
    namespace: default
    spec:
    parentRefs:
    - name: example-haproxy-gateway
    sectionName: tcp-listener
    rules:
    - backendRefs:
    - name: tcp-svc
    namespace: default
    port: 3000
  2. Apply the changes with kubectl:

    nix
    kubectl apply -f tcproute.yaml
    nix
    kubectl apply -f tcproute.yaml
    output
    text
    tcproute.gateway.networking.k8s.io/tcp-route created
    output
    text
    tcproute.gateway.networking.k8s.io/tcp-route created

Test application Jump to heading

To test connectivity with the Gateway and Route, deploy an example application using a Deployment and a Service. Here, we define an example application using the busybox Docker container image. It runs netcat on port 3000, receiving TCP traffic.

  1. Create a file named busybox.yaml and paste the following YAML into it to define the example application. Both the Deployment and the Service are present in this YAML:

    busybox.yaml
    yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
    name: busybox-deployment
    namespace: default
    labels:
    app: busybox
    spec:
    replicas: 1
    selector:
    matchLabels:
    app: busybox
    template:
    metadata:
    labels:
    app: busybox
    spec:
    containers:
    - name: busybox
    image: busybox
    command: ["sh", "-c", "while true; do nc -v -lk -p 3000; done"]
    ports:
    - containerPort: 3000
    protocol: TCP
    ---
    apiVersion: v1
    kind: Service
    metadata:
    name: tcp-svc
    namespace: default
    spec:
    selector:
    app: busybox
    ports:
    - protocol: TCP
    port: 3000
    targetPort: 3000
    busybox.yaml
    yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
    name: busybox-deployment
    namespace: default
    labels:
    app: busybox
    spec:
    replicas: 1
    selector:
    matchLabels:
    app: busybox
    template:
    metadata:
    labels:
    app: busybox
    spec:
    containers:
    - name: busybox
    image: busybox
    command: ["sh", "-c", "while true; do nc -v -lk -p 3000; done"]
    ports:
    - containerPort: 3000
    protocol: TCP
    ---
    apiVersion: v1
    kind: Service
    metadata:
    name: tcp-svc
    namespace: default
    spec:
    selector:
    app: busybox
    ports:
    - protocol: TCP
    port: 3000
    targetPort: 3000

    This YAML contains the definitions for:

    • A Deployment for BusyBox named busybox-deployment, which uses the busybox image.
    • Its container sets a containerPort of 3000. We run netcat on this port and connect to it through the Gateway.
    • The deployment includes a command that runs netcat (nc) listening on TCP port 3000.
    • A Service named tcp-svc exposes port 3000. It’s the same name and port that the TCPRoute uses in its backendRef.
  2. Apply the changes to create the resources:

    nix
    kubectl apply -f busybox.yaml
    nix
    kubectl apply -f busybox.yaml
    output
    text
    deployment.apps/busybox-deployment created
    service/tcp-svc created
    output
    text
    deployment.apps/busybox-deployment created
    service/tcp-svc created
  3. Use the following command to find the NodePort assigned to your Service. In this example, the NodePort is 31090, the NodePort associated with the TCP port on the HAProxy Unified Gateway Service.

    nix
    kubectl get service -n haproxy-unified-gateway haproxy-unified-gateway
    nix
    kubectl get service -n haproxy-unified-gateway haproxy-unified-gateway
    output
    text
    NAME TYPE PORT(S)
    haproxy-unified-gateway NodePort ... 31024:31024/TCP,31060:31060/TCP,31090:31898/TCP
    output
    text
    NAME TYPE PORT(S)
    haproxy-unified-gateway NodePort ... 31024:31024/TCP,31060:31060/TCP,31090:31898/TCP
  4. From a server that has connection to your cluster, such as the server from which you run kubectl, use netcat to connect to the port. There’s no output from this command.

    nix
    nc 127.0.0.1 31090
    nix
    nc 127.0.0.1 31090
  5. Get the name of the BusyBox pod by calling kubectl get pod:

    nix
    kubectl get pod
    nix
    kubectl get pod
    output
    text
    NAME READY STATUS RESTARTS AGE
    busybox-deployment-6fbb645fd4-cfkwp 1/1 Running 0 12m
    output
    text
    NAME READY STATUS RESTARTS AGE
    busybox-deployment-6fbb645fd4-cfkwp 1/1 Running 0 12m
  6. Check the BusyBox pod’s logs to confirm that a connection was made:

    nix
    kubectl logs busybox-deployment-6fbb645fd4-cfkwp
    nix
    kubectl logs busybox-deployment-6fbb645fd4-cfkwp
    output
    text
    connect to [::ffff:10.244.0.23]:3000 from 10-244-0-22.haproxy-unified-gateway.haproxy-unified-gateway.svc.cluster.local:48288 ([::ffff:10.244.0.22]:48288)
    output
    text
    connect to [::ffff:10.244.0.23]:3000 from 10-244-0-22.haproxy-unified-gateway.haproxy-unified-gateway.svc.cluster.local:48288 ([::ffff:10.244.0.22]:48288)

Weight traffic to a backend Jump to heading

You can assign a weight to a backend reference to send more or less traffic to the backend. Use the weight field to set the proportion of traffic to send, calculated by dividing the weight value by the total weight across all backend references.

In this example, we send roughly 90% of the connections to tcp-svc-1 and 10% to tcp-svc-2.

tcproute.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: TCPRoute
metadata:
name: tcp-route
namespace: default
spec:
parentRefs:
- name: example-haproxy-gateway
sectionName: tcp-listener
rules:
- backendRefs:
- name: tcp-svc-1
namespace: default
port: 3000
weight: 90
- name: tcp-svc-2
namespace: default
port: 3000
weight: 10
tcproute.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: TCPRoute
metadata:
name: tcp-route
namespace: default
spec:
parentRefs:
- name: example-haproxy-gateway
sectionName: tcp-listener
rules:
- backendRefs:
- name: tcp-svc-1
namespace: default
port: 3000
weight: 90
- name: tcp-svc-2
namespace: default
port: 3000
weight: 10

See also Jump to heading

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