TransportServer Resource

Listener

The listener field references a listener that NGINX will use to accept incoming traffic for the TransportServer. For TCP and UDP, the listener must be defined in the GlobalConfiguration resource. When referencing a listener, both the name and the protocol must match. For TLS Passthrough, use the built-in listener with the name tls-passthrough and the protocol TLS_PASSTHROUGH.

An example:

listener:
  name: dns-udp 
  protocol: UDP 

Upstream

The upstream defines a destination for the TransportServer. For example:

name: secure-app 
service: secure-app
port: 8443
maxFails: 3
failTimeout: 30s

Upstream.Healthcheck

The Healthcheck defines an active health check. In the example below we enable a health check for an upstream and configure all the available parameters:

name: secure-app 
service: secure-app
port: 8443
healthCheck:
  enable: true
  interval: 20s
  timeout: 30s
  jitter: 3s
  fails: 5
  passes: 5
  port: 8080

Note: This feature is supported only in NGINX Plus.

UpstreamParameters

The upstream parameters define various parameters for the upstreams:

upstreamParameters:
  udpRequests: 1
  udpResponses: 1
  connectTimeout: 60s
  nextUpstream: true
  nextUpstreamTimeout: 50s
  nextUpstreamTries: 1

SessionParameters

The session parameters define various parameters for TCP connections and UDP sessions.

sessionParameters:
  timeout: 50s

Action

The action defines an action to perform for a client connection/datagram.

In the example below, client connections/datagrams are passed to an upstream dns-app:

action:
  pass: dns-app

Using Snippets

Snippets allow you to insert raw NGINX config into different contexts of NGINX configuration. In the example below, we use snippets to configure access control in a TransportServer:

apiVersion: k8s.nginx.org/v1alpha1
kind: TransportServer
metadata:
  name: cafe
spec:
  host: cafe.example.com
  serverSnippets: |
    deny  192.168.1.1;
    allow 192.168.1.0/24;
  upstreams:
  - name: tea
    service: tea-svc
    port: 80

Snippets are intended to be used by advanced NGINX users who need more control over the generated NGINX configuration.

However, because of the disadvantages described below, snippets are disabled by default. To use snippets, set the enable-snippets command-line argument.

Disadvantages of using snippets:

• Complexity. To use snippets, you will need to:
  • Understand NGINX configuration primitives and implement a correct NGINX configuration.
  • Understand how the IC generates NGINX configuration so that a snippet doesn’t interfere with the other features in the configuration.
• Decreased robustness. An incorrect snippet makes the NGINX config invalid which will lead to a failed reload. This will prevent any new configuration updates, including updates for the other TransportServer resource until the snippet is fixed.
• Security implications. Snippets give access to NGINX configuration primitives and those primitives are not validated by the Ingress Controller.

Note: during a period when the NGINX config includes an invalid snippet, NGINX will continue to operate with the latest valid configuration.

Note: to configure snippets in the stream context, use stream-snippets ConfigMap key.

Validation

Two types of validation are available for the TransportServer resource:

• Structural validation by the kubectl and Kubernetes API server.
• Comprehensive validation by the Ingress Controller.

$ 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"