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

1. Follow the Get started guide to install kgateway.

2. 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
3. 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.

4. 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.

2. Check the status of the Gateway to make sure that your configuration is accepted. Note that in the output, a NoConflicts status of False 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
   

3. 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

5. 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.

1. Get the external address of the gateway and save it in an environment variable.

   Cloud Provider LoadBalancerPort-forward for local testing

   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

2. 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.

   Cloud Provider LoadBalancerPort-forward for local testing

   nc $INGRESS_GW_ADDRESS 8000

   nc localhost 8000

   The output is an open session for you to send more requests.

3. Enter any string to verify that the TCP echo service “echoes,” returning the same string back.

   hello
   

   Example output:

   hello
   hello
   

Cleanup

kubectl delete -A gateways,tcproutes,pod,svc -l app=tcp-echo