Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Revert "Update gc doc with vs listeners (#4492)" #4498

Merged
merged 1 commit into from
Oct 11, 2023
Merged

Revert "Update gc doc with vs listeners (#4492)" #4498

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 22 additions & 48 deletions docs/content/configuration/global-configuration/globalconfiguration-resource.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,13 @@ docs: "DOCS-588"
---


The GlobalConfiguration resource allows you to define the global configuration parameters of the Ingress Controller.
The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
The GlobalConfiguration resource allows you to define the global configuration parameters of the Ingress Controller. The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).

The resource supports configuring listeners for TCP, UDP and HTTP/S load balancing. Listeners are required by
[TransportServer resources](/nginx-ingress-controller/configuration/transportserver-resource) and
can be used to configure custom listerners as specified [here](/nginx-ingress-controller/tutorials/virtual-server-with-custom-listener-ports)
The resource supports configuring listeners for TCP and UDP load balancing. Listeners are required by [TransportServer resources](/nginx-ingress-controller/configuration/transportserver-resource).

## Prerequisites

When [installing](/nginx-ingress-controller/installation/installation-with-manifests) the Ingress Controller,
you need to reference a GlobalConfiguration resource in the
[`-global-configuration`](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-global-configuration)
command-line argument. The Ingress Controller only needs one GlobalConfiguration resource.
When [installing](/nginx-ingress-controller/installation/installation-with-manifests) the Ingress Controller, you need to reference a GlobalConfiguration resource in the [`-global-configuration`](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-global-configuration) command-line argument. The Ingress Controller only needs one GlobalConfiguration resource.

## GlobalConfiguration Specification

Expand All @@ -41,13 +35,6 @@ spec:
- name: dns-tcp
port: 5353
protocol: TCP
- name: http-8083
port: 8083
protocol: HTTP
- name: https-8443
port: 8443
protocol: HTTP
ssl: true
```
{{% table %}}
Expand All @@ -58,8 +45,7 @@ spec:
### Listener
The listener defines a listener (a combination of a protocol and a port) that NGINX will use to accept traffic for a
[TransportServer](/nginx-ingress-controller/configuration/transportserver-resource) and a [VirtualServer](nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources):
The listener defines a listener (a combination of a protocol and a port) that NGINX will use to accept traffic for a [TransportServer](/nginx-ingress-controller/configuration/transportserver-resource):
```yaml
name: dns-tcp
Expand All @@ -80,17 +66,16 @@ protocol: TCP
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`:
For example, the following command creates a GlobalConfiguration resource defined in `global-configuration.yaml` with the name `nginx-configuration`:

```shell
```
$ 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:

```shell
```
$ kubectl get globalconfiguration nginx-configuration -n nginx-ingress
NAME AGE
nginx-configuration 13s
Expand All @@ -107,47 +92,39 @@ Two types of validation are available for the GlobalConfiguration resource:

#### Structural Validation

The custom resource definition for the GlobalConfiguration includes structural OpenAPI schema which describes the type
of every field of the resource.
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:
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:

```shell
```
$ 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.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:

```shell
```
$ 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"
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), the Ingress Controller will validate it further.

#### Comprehensive Validation

The Ingress Controller validates the fields of a GlobalConfiguration resource. If a resource is invalid,
the Ingress Controller will not use it. Consider the following two cases:
The Ingress Controller validates the fields of a GlobalConfiguration resource. If a resource is invalid, the Ingress Controller will not use it. Consider the following two cases:

1. When the Ingress Controller pod starts, if the GlobalConfiguration resource is invalid, the Ingress Controller will
fail to start and exit with an error.
2. When the Ingress Controller is running, if the GlobalConfiguration resource becomes invalid, the Ingress Controller
will ignore the new version. It will report an error and continue to use the previous version. When the resource becomes
valid again, the Ingress Controller will start using it.
1. When the Ingress Controller pod starts, if the GlobalConfiguration resource is invalid, the Ingress Controller will fail to start and exit with an error.
1. When the Ingress Controller is running, if the GlobalConfiguration resource becomes invalid, the Ingress Controller will ignore the new version. It will report an error and continue to use the previous version. When the resource becomes valid again, the Ingress Controller will start using it.

**Note**: If a GlobalConfiguration is deleted while the Ingress Controller is running, the controller will keep using
the previous version of the resource.
**Note**: If a GlobalConfiguration is deleted while the Ingress Controller is running, the controller will keep using the previous version of the resource.

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

```shell
```
$ kubectl describe gc nginx-configuration -n nginx-ingress
. . .
Events:
Expand All @@ -156,14 +133,11 @@ Events:
Normal Updated 11s nginx-ingress-controller GlobalConfiguration nginx-ingress/nginx-configuration was updated
```

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

If you create an invalid resource, the Ingress Controller will reject it and emit a Rejected event. For example, if you
create a GlobalConfiguration `nginx-configuration` with two or more listeners that have the same protocol UDP and port 53,
you will get:
If you create an invalid resource, the Ingress Controller will reject it and emit a Rejected event. For example, if you create a GlobalConfiguration `nginx-configuration` with two or more listeners that have the same protocol UDP and port 53, you will get:

```shell
```
$ kubectl describe gc nginx-configuration -n nginx-ingress
. . .
Events:
Expand Down