TCP
The following guide deploys a sample TCP echo app, sets up a TCP listener on the gateway, and creates a TCPRoute to the sample app.
Before you begin
-
Follow the Get started guide to install kgateway.
-
Install the experimental channel of the Kubernetes Gateway API so that you can use TCPRoutes.
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/experimental-install.yaml
-
Decide whether to set up a listener inline on the Gateway resource or as a separate ListenerSet resource. For more information, see the Listener overview.
ListenerSets: This feature is available in kgateway version 2.1.x or later. Also, you must install the experimental channel of the Kubernetes Gateway API at version 1.3 or later.
-
Deploy the sample TCP echo app.
kubectl apply -f- <<EOF apiVersion: v1 kind: Pod metadata: labels: app: tcp-echo name: tcp-echo namespace: default spec: containers: - image: soloio/tcp-echo:latest imagePullPolicy: IfNotPresent name: tcp-echo restartPolicy: Always --- apiVersion: v1 kind: Service metadata: labels: app: tcp-echo name: tcp-echo namespace: default spec: ports: - name: http port: 1025 protocol: TCP targetPort: 1025 selector: app: tcp-echo EOF
Set up the Gateway for TCP routes
Create a TCP listener so that the gateway can route TCP traffic. In the following example, all TCP streams on port 8000 of the gateway are forwarded to port 1025 of the example TCP echo service.
If you plan to set up your listener as part of a ListenerSet, keep the following considerations in mind. For more information, see ListenerSets (experimental).
- This feature is available in kgateway version 2.1.x or later.
- You must install the experimental channel of the Kubernetes Gateway API at version 1.3 or later.
-
Create a Gateway resource with a TCP listener.
kubectl apply -f- <<EOF apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: tcp-gateway namespace: kgateway-system labels: app: tcp-echo spec: gatewayClassName: kgateway listeners: - protocol: TCP port: 8000 name: tcp allowedRoutes: kinds: - kind: TCPRoute EOF
Review the following table to understand this configuration.
Setting Description spec.gatewayClassName
The name of the Kubernetes GatewayClass that you want to use to configure the Gateway. When you set up kgateway, a default GatewayClass is set up for you. spec.listeners
Configure the listeners for this Gateway. In this example, you configure a TCP Gateway that listens for incoming traffic on port 8000. The Gateway can serve TCPRoutes from any namespace.
-
Create a Gateway that enables the attachment of ListenerSets.
kubectl apply -f- <<EOF apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: tcp-gateway namespace: kgateway-system labels: app: tcp-echo spec: gatewayClassName: kgateway allowedListeners: namespaces: from: All listeners: - protocol: TCP port: 80 name: generic-tcp allowedRoutes: kinds: - kind: TCPRoute EOF
Review the following table to understand this configuration.
Setting Description spec.gatewayClassName
The name of the Kubernetes GatewayClass that you want to use to configure the Gateway. When you set up kgateway, a default GatewayClass is set up for you. spec.allowedListeners
Enable the attachment of ListenerSets to this Gateway. The example allows listeners from any namespace. spec.listeners
Optionally, you can configure a listener that is specific to the Gateway. Note that due to a Gateway API limitation, you must configure at least one listener on the Gateway resource, even if the listener is not used and is a generic, “dummy” listener. This generic listener cannot conflict with the listener that you configure in the ListenerSet, such as using the same port or name. In this example, the generic listener is configured on port 80, which differs from port 8000 in the ListenerSet that you create later. -
Create a ListenerSet that configures a TCP listener for the Gateway.
kubectl apply -f- <<EOF apiVersion: gateway.networking.x-k8s.io/v1alpha1 kind: XListenerSet metadata: name: my-tcp-listenerset namespace: kgateway-system labels: app: tcp-echo spec: parentRef: name: tcp-gateway namespace: kgateway-system kind: Gateway group: gateway.networking.k8s.io listeners: - protocol: TCP port: 8000 name: tcp-listener-set allowedRoutes: kinds: - kind: TCPRoute EOF
Review the following table to understand this configuration.
Setting Description spec.parentRef
The name of the Gateway to attach the ListenerSet to. spec.listeners
Configure the listeners for this ListenerSet. In this example, you configure a TCP listener for port 8000. The gateway can serve TCPRoutes from any namespace.
-
Check the status of the Gateway to make sure that your configuration is accepted. Note that in the output, a
NoConflicts
status ofFalse
indicates that the Gateway is accepted and does not conflict with other Gateway configuration.kubectl get gateway tcp-gateway -n kgateway-system -o yaml
Example output:
status: addresses: - type: IPAddress value: ${INGRESS_GW_ADDRESS} conditions: - lastTransitionTime: "2024-11-20T16:01:25Z" message: "" observedGeneration: 2 reason: Accepted status: "True" type: Accepted - lastTransitionTime: "2024-11-20T16:01:25Z" message: "" observedGeneration: 2 reason: Programmed status: "True" type: Programmed
-
Create a ReferenceGrant to allow TCPRoutes to reference the tcp-echo service.
kubectl apply -f- <<EOF apiVersion: gateway.networking.k8s.io/v1beta1 kind: ReferenceGrant metadata: name: allow-tcp-route-to-echo namespace: default spec: from: - group: gateway.networking.k8s.io kind: TCPRoute namespace: kgateway-system to: - group: "" kind: Service EOF
Create a TCPRoute
kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
name: tcp-route-echo
namespace: kgateway-system
labels:
app: tcp-echo
spec:
parentRefs:
- name: tcp-gateway
namespace: kgateway-system
sectionName: tcp
rules:
- backendRefs:
- name: tcp-echo
namespace: default
port: 1025
EOF
kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
name: tcp-route-echo
namespace: kgateway-system
labels:
app: tcp-echo
spec:
parentRefs:
- name: my-tcp-listenerset
namespace: kgateway-system
kind: XListenerSet
group: gateway.networking.x-k8s.io
sectionName: tcp-listener-set
rules:
- backendRefs:
- name: tcp-echo
namespace: default
port: 1025
EOF
-
Verify that the TCPRoute is applied successfully.
kubectl get tcproute/tcp-route-echo -n kgateway-system -o yaml
Example output:
status: parents: - conditions: - lastTransitionTime: "2024-11-21T16:22:52Z" message: "" observedGeneration: 1 reason: Accepted status: "True" type: Accepted - lastTransitionTime: "2024-11-21T16:22:52Z" message: "" observedGeneration: 1 reason: ResolvedRefs status: "True" type: ResolvedRefs controllerName: kgateway.dev/kgateway parentRef: group: gateway.networking.k8s.io kind: Gateway name: tcp-gateway namespace: kgateway-system sectionName: tcp
Verify the TCP route
Verify that the TCP route to the TCP echo app is working.
-
Get the external address of the gateway and save it in an environment variable.
export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-system tcp-gateway -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}") echo $INGRESS_GW_ADDRESS
kubectl port-forward deployment/tcp-gateway -n kgateway-system 8000:8000
-
Send a TCP request to the external address of the TCP gateway on port 8000. You might use a tool such as telnet or netcat as in the following example.
nc $INGRESS_GW_ADDRESS 8000
nc localhost 8000
The output is an open session for you to send more requests.
-
Enter any string to verify that the TCP echo service “echoes,” returning the same string back.
hello
Example output:
hello hello
Cleanup
You can remove the resources that you created in this guide.kubectl delete -A gateways,tcproutes,pod,svc -l app=tcp-echo