GlobalConfiguration

The GlobalConfiguration resource allows you to define global configuration parameters for ANIC. It is implemented as a custom resource.

The resource supports configuring listeners for TCP and UDP load balancing. Listeners are required for TransportServer resources.

Prerequisites

When installing ANIC with manifests, you must specify a reference to the GlobalConfiguration resource in the command line argument -global-configuration. Only one GlobalConfiguration resource is required for ANIC.

GlobalConfiguration Specification

The GlobalConfiguration resource defines global configuration parameters for ANIC. Below is an example:

apiVersion: k8s.angie.software/v1alpha1
kind: GlobalConfiguration
metadata:
  name: angie-configuration
  namespace: angie-ingress
spec:
  listeners:
  - name: dns-udp
    port: 5353
    protocol: UDP
  - name: dns-tcp
    port: 5353
    protocol: TCP

Field	Description	Type	Required
listeners	List of listeners.	[]listener	No

Listener

A listener defines a combination of protocol and port that Angie will use when receiving traffic for TransportServer:

name: dns-tcp
port: 5353
protocol: TCP

Field	Description	Type	Required
name	The name of the listener. This must be a valid DNS label as defined in RFC 1035. For example, valid values are hello and listener-123. 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 listener port. The port must be in the range 1..65535 with the following exceptions: 80, 443, port [status](/angie-ingress-controller/logging-and-monitoring/status-page). The combination of port and protocol must be unique among all listeners.	int	Yes
protocol	The listener protocol. Supported values: TCP and UDP.	string	Yes

Using GlobalConfiguration

You can use standard kubectl commands to interact with the GlobalConfiguration resource.

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

$ kubectl apply -f global-configuration.yaml

    globalconfiguration.k8s.angie.software/angie-configuration created

Assuming the resource namespace is called angie-ingress, you can retrieve the resource by running:

$ kubectl get globalconfiguration angie-configuration -n angie-ingress

    NAME                  AGE
    angie-configuration   13s

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

Validation

There are two types of validation available for the GlobalConfiguration resource:

• Structural validation using kubectl and the Kubernetes API server.

• Comprehensive validation using ANIC.

Structural Validation

The custom resource definition for GlobalConfiguration includes an OpenAPI structural schema that describes the type of each field in the resource.

If you attempt to create (or update) a resource that violates the structural schema (for example, using a string value for the listener port field), kubectl and the 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
      software.angie.k8s.v1alpha1.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 "angie-configuration" is invalid: []: Invalid
      value: map[string]interface {}{ ... }: validation failure list:
      spec.listeners.port in body must be of type integer: "string"
  

If the resource is not rejected (i.e., does not violate the structural schema), ANIC will further validate it.

Comprehensive Validation

ANIC checks the fields of the GlobalConfiguration resource. If the resource is invalid, ANIC will not use it. Consider the following two scenarios:

1. If the GlobalConfiguration resource is invalid when ANIC starts a pod, ANIC will fail to start and exit with an error.

2. If the GlobalConfiguration resource becomes invalid while ANIC is running, ANIC will ignore the new version. It will report an error and continue using the previous version. When the resource becomes valid again, ANIC will start using it.

Note

If the GlobalConfiguration resource was deleted while ANIC is running, it will continue to use the previous version of the resource.

You can check if ANIC successfully applied the configuration for the GlobalConfiguration. For our GlobalConfiguration resource angie-configuration, we can run:

$ kubectl describe gc angie-configuration -n angie-ingress

    . . .
    Events:
      Type     Reason    Age   From                      Message


      Normal   Updated   11s   angie-ingress-controller  GlobalConfiguration
      angie-ingress/angie-configuration was updated

Note that the "Events" section includes a Normal event with the reason Updated, which informs us that the configuration was successfully applied.

If you create an invalid resource, ANIC will reject it and issue a Rejected event. For example, if you create a GlobalConfiguration resource angie-configuration with multiple listeners that have the same UDP protocol and port 53, you will receive:

$ kubectl describe gc angie-configuration -n angie-ingress

    . . .
    Events:
     Type     Reason    Age   From                      Message


    Normal    Updated   55s   angie-ingress-controller  GlobalConfiguration
    angie-ingress/angie-configuration was updated

    Warning   Rejected  6s    angie-ingress-controller  GlobalConfiguration
    angie-ingress/angie-configuration is invalid and was rejected:
    spec.listeners: Duplicate value: "Duplicated port/protocol combination
    53/UDP"

Note that the "Events" section includes a warning event indicating the reason for rejection.