TransportServer Resource

Contents

• TransportServer Resource
  • Contents
  • Prerequisites
  • TransportServer Specification
    • Listener
    • Upstream
    • UpstreamParameters
    • Action
  • Using TransportServer
    • Validation
      • Structural Validation
      • Comprehensive Validation
  • Customization via ConfigMap
  • Limitations

Prerequisites

• For TCP and UDP, the TransportServer resource must be used in conjunction with the GlobalConfiguration resource, which must be created separately.
• For TLS Passthrough, make sure to enable the -enable-tls-passthrough command-line argument of the Ingress Controller.

TransportServer Specification

The TransportServer resource defines load balancing configuration for TCP, UDP, or TLS Passthrough traffic. Below are a few examples:

• TCP load balancing:

  apiVersion: k8s.nginx.org/v1alpha1
  kind: TransportServer
  metadata:
    name: dns-tcp
  spec:
    listener:
      name: dns-tcp 
      protocol: TCP
    upstreams:
    - name: dns-app
      service: dns-service
      port: 5353
    action:
      pass: dns-app
  

• UDP load balancing:

  apiVersion: k8s.nginx.org/v1alpha1
  kind: TransportServer
  metadata:
    name: dns-udp
  spec:
    listener:
      name: dns-udp 
      protocol: UDP
    upstreams:
    - name: dns-app
      service: dns-service
      port: 5353
    upstreamParameters:
      udpRequests: 1
      udpResponses: 1
    action:
      pass: dns-app
  

• TLS passthrough load balancing:

  apiVersion: k8s.nginx.org/v1alpha1
  kind: TransportServer
  metadata:
    name: secure-app
  spec:
    listener:
      name: tls-passthrough
      protocol: TLS_PASSTHROUGH
    host: app.example.com
    upstreams:
    - name: secure-app
      service: secure-app
      port: 8443
    action:
      pass: secure-app
  

* – Required for TLS Passthrough load balancing.

listener:
  name: dns-udp 
  protocol: UDP 

name: secure-app 
service: secure-app
port: 8443

upstreamParameters:
  udpRequests: 1
  udpResponses: 1

action:
  pass: dns-app

Using TransportServer

You can use the usual kubectl commands to work with TransportServer resources, similar to Ingress resources.

For example, the following command creates a TransportServer resource defined in transport-server-passthrough.yaml with the name secure-app:

$ kubectl apply -f transport-server-passthrough.yaml
transportserver.k8s.nginx.org/secure-app created

You can get the resource by running:

$ kubectl get transportserver secure-app
NAME         AGE
secure-app   46sm

In the kubectl get and similar commands, you can also use the short name ts instead of transportserver.

$ kubectl describe ts secure-app
. . .
Events:
  Type    Reason          Age   From                      Message
  ----    ------          ----  ----                      -------
  Normal  AddedOrUpdated  3s    nginx-ingress-controller  Configuration for default/secure-app was added or updated

$ kubectl describe ts secure-app
. . .
Events:
  Type     Reason    Age   From                      Message
  ----     ------    ----  ----                      -------
  Warning  Rejected  2s    nginx-ingress-controller  TransportServer default/secure-app is invalid and was rejected: spec.action.pass: Not found: "some-app"

Customization via ConfigMap

The ConfigMap keys (except for stream-snippets and stream-log-format) do not affect TransportServer resources.

Limitations

As of Release 1.7, the TransportServer resource is a preview feature. Currently, it comes with the following limitations:

• When using TLS Passthrough, it is not possible to configure Proxy Protocol for port 443 both for regular HTTPS and TLS Passthrough traffic.
• If multiple TCP (or UDP) TransportServers reference the same listener, only one of them will receive the traffic. Moreover, until there is only one TransportServer, NGINX will fail to reload. If this happens, the IC will report a warning event with the AddedOrUpdatedWithError reason for the resource, which caused the problem, and also report the error in the logs.
• If multiple TLS Passthrough TransportServers have the same hostname, only one of them will receive the traffic. If this happens, the IC will report a warning in the logs like host "app.example.com" is used by more than one TransportServers.