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
allowedRoutesproperty to accept routes of kindTCPRoute.
Define routing rules Jump to heading
In your TCPRoutes, you’ll define rules for routing TCP packets to your backend applications.
-
Define a TCPRoute resource.
Section Description parentRefs References one or more Gateways to which a TCPRoute tries to attach. This TCPRoute will attach to Gatewayresources that have listeners withallowedRoutesmatching theTCPRoutekind and a matching namespace. ThesectionNamefield 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 backendRefssection to route to the specified service. For example, traffic that the Gateway’s TCP listener receives will route totcp-svc. AbackendRefsentry refers to the name of a Service resource and its listening port.tcproute.yamlyamlapiVersion: gateway.networking.k8s.io/v1kind: TCPRoutemetadata:name: tcp-routenamespace: defaultspec:parentRefs:- name: example-haproxy-gatewaysectionName: tcp-listenerrules:- backendRefs:- name: tcp-svcnamespace: defaultport: 3000tcproute.yamlyamlapiVersion: gateway.networking.k8s.io/v1kind: TCPRoutemetadata:name: tcp-routenamespace: defaultspec:parentRefs:- name: example-haproxy-gatewaysectionName: tcp-listenerrules:- backendRefs:- name: tcp-svcnamespace: defaultport: 3000 -
Apply the changes with
kubectl:nixkubectl apply -f tcproute.yamlnixkubectl apply -f tcproute.yamloutputtexttcproute.gateway.networking.k8s.io/tcp-route createdoutputtexttcproute.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.
-
Create a file named
busybox.yamland paste the following YAML into it to define the example application. Both the Deployment and the Service are present in this YAML:busybox.yamlyamlapiVersion: apps/v1kind: Deploymentmetadata:name: busybox-deploymentnamespace: defaultlabels:app: busyboxspec:replicas: 1selector:matchLabels:app: busyboxtemplate:metadata:labels:app: busyboxspec:containers:- name: busyboximage: busyboxcommand: ["sh", "-c", "while true; do nc -v -lk -p 3000; done"]ports:- containerPort: 3000protocol: TCP---apiVersion: v1kind: Servicemetadata:name: tcp-svcnamespace: defaultspec:selector:app: busyboxports:- protocol: TCPport: 3000targetPort: 3000busybox.yamlyamlapiVersion: apps/v1kind: Deploymentmetadata:name: busybox-deploymentnamespace: defaultlabels:app: busyboxspec:replicas: 1selector:matchLabels:app: busyboxtemplate:metadata:labels:app: busyboxspec:containers:- name: busyboximage: busyboxcommand: ["sh", "-c", "while true; do nc -v -lk -p 3000; done"]ports:- containerPort: 3000protocol: TCP---apiVersion: v1kind: Servicemetadata:name: tcp-svcnamespace: defaultspec:selector:app: busyboxports:- protocol: TCPport: 3000targetPort: 3000This YAML contains the definitions for:
- A Deployment for BusyBox named
busybox-deployment, which uses the busybox image. - Its container sets a
containerPortof3000. 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 port3000. - A Service named
tcp-svcexposes port3000. It’s the same name and port that the TCPRoute uses in itsbackendRef.
- A Deployment for BusyBox named
-
Apply the changes to create the resources:
nixkubectl apply -f busybox.yamlnixkubectl apply -f busybox.yamloutputtextdeployment.apps/busybox-deployment createdservice/tcp-svc createdoutputtextdeployment.apps/busybox-deployment createdservice/tcp-svc created -
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.
nixkubectl get service -n haproxy-unified-gateway haproxy-unified-gatewaynixkubectl get service -n haproxy-unified-gateway haproxy-unified-gatewayoutputtextNAME TYPE PORT(S)haproxy-unified-gateway NodePort ... 31024:31024/TCP,31060:31060/TCP,31090:31898/TCPoutputtextNAME TYPE PORT(S)haproxy-unified-gateway NodePort ... 31024:31024/TCP,31060:31060/TCP,31090:31898/TCP -
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.nixnc 127.0.0.1 31090nixnc 127.0.0.1 31090 -
Get the name of the BusyBox pod by calling
kubectl get pod:nixkubectl get podnixkubectl get podoutputtextNAME READY STATUS RESTARTS AGEbusybox-deployment-6fbb645fd4-cfkwp 1/1 Running 0 12moutputtextNAME READY STATUS RESTARTS AGEbusybox-deployment-6fbb645fd4-cfkwp 1/1 Running 0 12m -
Check the BusyBox pod’s logs to confirm that a connection was made:
nixkubectl logs busybox-deployment-6fbb645fd4-cfkwpnixkubectl logs busybox-deployment-6fbb645fd4-cfkwpoutputtextconnect 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)outputtextconnect 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.yamlyamlapiVersion: gateway.networking.k8s.io/v1kind: TCPRoutemetadata:name: tcp-routenamespace: defaultspec:parentRefs:- name: example-haproxy-gatewaysectionName: tcp-listenerrules:- backendRefs:- name: tcp-svc-1namespace: defaultport: 3000weight: 90- name: tcp-svc-2namespace: defaultport: 3000weight: 10
tcproute.yamlyamlapiVersion: gateway.networking.k8s.io/v1kind: TCPRoutemetadata:name: tcp-routenamespace: defaultspec:parentRefs:- name: example-haproxy-gatewaysectionName: tcp-listenerrules:- backendRefs:- name: tcp-svc-1namespace: defaultport: 3000weight: 90- name: tcp-svc-2namespace: defaultport: 3000weight: 10
See also Jump to heading
- Refer to the Gateway API’s TCPRoute documentation.