For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

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.5.1/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.

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.

1. Create a Gateway with a TCP listener. Set the gatewayClassName to kgateway.

   Gateway listenersListenerSets

   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. Set the gatewayClassName to kgateway.
   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.

   1. 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. Set the gatewayClassName to kgateway.
      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.

   2. Create a ListenerSet that configures a TCP listener for the Gateway.

      kubectl apply -f- <<EOF
      apiVersion: gateway.networking.k8s.io/v1
      kind: ListenerSet
      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.

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

1. Create the TCPRoute resource.

   Gateway listenersListenerSets

   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: ListenerSet
         group: gateway.networking.k8s.io
         sectionName: tcp-listener-set
     rules:
       - backendRefs:
           - name: tcp-echo
             namespace: default
             port: 1025
   EOF

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