GlobalConfiguration resource

This page explains how to use the GlobalConfiguration resource to define the global configuration parameters of F5 NGINX Ingress Controller.

The resource supports configuring listeners for TCP and UDP load balancing, and is implemented as a Custom resource.

Listeners are required by TransportServer resources and can be used to configure custom listeners for VirtualServers.

Prerequisites

When installing NGINX Ingress Controller using Manifests, you need to reference a GlobalConfiguration resource in the -global-configuration command-line argument. NGINX Ingress Controller only needs one GlobalConfiguration resource.

GlobalConfiguration specification

The GlobalConfiguration resource defines the global configuration parameters of the Ingress Controller. Below is an example:

apiVersion: k8s.nginx.org/v1
kind: GlobalConfiguration
metadata:
  name: nginx-configuration
  namespace: nginx-ingress
spec:
  listeners:
  - name: dns-udp
    port: 5353
    protocol: UDP
  - name: dns-tcp
    port: 5353
    protocol: TCP
  - name: http-8083
    port: 8083
    protocol: HTTP
  - name: https-8443
    port: 8443
    protocol: HTTP
    ssl: true
Field Description Type Required
listeners A list of listeners. listener No

Listener

The listeners: key defines a listener (a combination of a protocol and a port) that NGINX will use to accept traffic for a TransportServer and a VirtualServer:

- name: dns-tcp
  port: 5353
  protocol: TCP
- name: http-8083
  port: 8083
  protocol: HTTP
Field Description Type Required
name The name of the listener. Must be a valid DNS label as defined in RFC 1035. For example, hello and listener-123 are valid. The name must be unique among all listeners. The name tls-passthrough is reserved for the built-in TLS Passthrough listener and cannot be used. string Yes
port The port of the listener. The port must fall into the range 1..65535 with the following exceptions: 80, 443, the status port, the Prometheus metrics port. Among all listeners, only a single combination of a port-protocol is allowed. int Yes
protocol The protocol of the listener. Supported values: TCP, UDP and HTTP. string Yes
ssl Configures the listener with SSL. This is currently only supported for HTTP listeners. Default value is false bool No

Using GlobalConfiguration

You can use the usual kubectl commands to work with a GlobalConfiguration resource.

For example, the following command creates a GlobalConfiguration resource defined in global-configuration.yaml with the name nginx-configuration:

kubectl apply -f global-configuration.yaml

globalconfiguration.k8s.nginx.org/nginx-configuration created

Assuming the namespace of the resource is nginx-ingress, you can get the resource by running:

kubectl get globalconfiguration nginx-configuration -n nginx-ingress

NAME                  AGE
nginx-configuration   13s

With kubectl get and similar commands, you can use the short name gc instead of globalconfiguration.

Validation

Two types of validation are available for the GlobalConfiguration resource:

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

Structural validation

The custom resource definition for the GlobalConfiguration includes structural OpenAPI schema which describes the type of every field of the resource.

If you try to create (or update) a resource that violates the structural schema (for example, you use a string value for the port field of a listener), kubectl and Kubernetes API server will reject such a resource:

  • Example of kubectl validation:

    kubectl apply -f global-configuration.yaml

    error: error validating "global-configuration.yaml": error validating data: ValidationError(GlobalConfiguration.spec.listeners[0].port): invalid type for org.nginx.k8s.v1.GlobalConfiguration.spec.listeners.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false

  • Example of Kubernetes API server validation:

    kubectl apply -f global-configuration.yaml --validate=false

    The GlobalConfiguration "nginx-configuration" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list:
spec.listeners.port in body must be of type integer: "string"

If a resource is not rejected (it doesn’t violate the structural schema), NGINX Ingress Controller will validate it further.

Comprehensive validation

NGINX Ingress Controller validates the fields of a GlobalConfiguration resource. If a GlobalConfiguration resource is partially invalid, NGINX Ingress Controller use the valid listeners and emit events about invalid listeners.

You can check if the Ingress Controller successfully applied the configuration for a GlobalConfiguration. For our nginx-configuration GlobalConfiguration, we can run:

kubectl describe gc nginx-configuration -n nginx-ingress

...
Events:
  Type     Reason    Age   From                      Message
  ----     ------    ----  ----                      -------
  Normal   Updated   11s   nginx-ingress-controller  GlobalConfiguration nginx-ingress/nginx-configuration was updated

The events section includes a Normal event with the Updated reason that informs us that the configuration was successfully applied.

If you create a GlobalConfiguration nginx-configuration with two or more listeners that have the same protocol UDP and port 53, you will get:

kubectl describe gc nginx-configuration -n nginx-ingress

Events:
  Type     Reason    Age   From                      Message
  ----     ------    ----  ----                      -------
  Normal   Updated   55s   nginx-ingress-controller  GlobalConfiguration nginx-ingress/nginx-configuration was updated
  Warning  AddedOrUpdatedWithError  6s    nginx-ingress-controller  GlobalConfiguration nginx-ingress/nginx-configuration is invalid and was rejected: spec.listeners: Duplicate value: "Duplicated port/protocol combination 53/UDP"

The events section includes a Warning event with the AddedOrUpdatedWithError reason.