On this page

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.

warning

This feature is experimental in the upstream Kubernetes Gateway API and subject to change.

Before you begin

Follow the Get started guide to install Gloo Gateway.

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 with Gloo Gateway 2.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 with Gloo Gateway 2.x or later.
You must install the experimental channel of the Kubernetes Gateway API at version 1.3 or later.

Create a Gateway with a TCP listener. To use the default Envoy-based Gloo Gateway proxy, set the gatewayClassName to gloo-gateway-v2. To use agentgateway, set the gatewayClassName to agentgateway.

  kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tcp-gateway
  namespace: gloo-system
  labels:
    app: tcp-echo
spec:
  gatewayClassName: gloo-gateway-v2
  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 Gloo Gateway, a default GatewayClass is set up for you. To use the default Envoy-based Gloo Gateway proxy, set the `gatewayClassName` to `gloo-gateway-v2`. To use agentgateway, set the `gatewayClassName` to `agentgateway`.
`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: gloo-system
  labels:
    app: tcp-echo
spec:
  gatewayClassName: gloo-gateway-v2
  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 Gloo Gateway, a default GatewayClass is set up for you. To use the default Envoy-based Gloo Gateway proxy, set the `gatewayClassName` to `gloo-gateway-v2`. To use agentgateway, set the `gatewayClassName` to `agentgateway`.
`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: gloo-system
  labels:
    app: tcp-echo
spec:
  parentRef:
    name: tcp-gateway
    namespace: gloo-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 of False indicates that the Gateway is accepted and does not conflict with other Gateway configuration.

  kubectl get gateway tcp-gateway -n gloo-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: gloo-system
  to:
    - group: ""
      kind: Service
EOF

Create a TCPRoute

Create the TCPRoute resource.

  kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: tcp-route-echo
  namespace: gloo-system
  labels:
    app: tcp-echo
spec:
  parentRefs:
    - name: tcp-gateway
      namespace: gloo-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: gloo-system
  labels:
    app: tcp-echo
spec:
  parentRefs:
    - name: my-tcp-listenerset
      namespace: gloo-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 gloo-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: gloo-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 gloo-system tcp-gateway -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
echo $INGRESS_GW_ADDRESS

  kubectl port-forward deployment/tcp-gateway -n gloo-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.
Cloud Provider LoadBalancer Port-forward for local testing
```
  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

TCP

Before you begin link

Set up the Gateway for TCP routes link

Create a TCPRoute link

Verify the TCP route link

Cleanup link

link

Before you begin

Set up the Gateway for TCP routes

Create a TCPRoute

Verify the TCP route

Cleanup