You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/content/configuration/global-configuration/globalconfiguration-resource.md
+22-48Lines changed: 22 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,19 +9,13 @@ docs: "DOCS-588"
9
9
---
10
10
11
11
12
-
The GlobalConfiguration resource allows you to define the global configuration parameters of the Ingress Controller.
13
-
The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
12
+
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/).
14
13
15
-
The resource supports configuring listeners for TCP, UDP and HTTP/S load balancing. Listeners are required by
16
-
[TransportServer resources](/nginx-ingress-controller/configuration/transportserver-resource) and
17
-
can be used to configure custom listerners as specified [here](/nginx-ingress-controller/tutorials/virtual-server-with-custom-listener-ports)
14
+
The resource supports configuring listeners for TCP and UDP load balancing. Listeners are required by [TransportServer resources](/nginx-ingress-controller/configuration/transportserver-resource).
18
15
19
16
## Prerequisites
20
17
21
-
When [installing](/nginx-ingress-controller/installation/installation-with-manifests) the Ingress Controller,
22
-
you need to reference a GlobalConfiguration resource in the
command-line argument. The Ingress Controller only needs one GlobalConfiguration resource.
18
+
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.
25
19
26
20
## GlobalConfiguration Specification
27
21
@@ -41,13 +35,6 @@ spec:
41
35
- name: dns-tcp
42
36
port: 5353
43
37
protocol: TCP
44
-
- name: http-8083
45
-
port: 8083
46
-
protocol: HTTP
47
-
- name: https-8443
48
-
port: 8443
49
-
protocol: HTTP
50
-
ssl: true
51
38
```
52
39
53
40
{{% table %}}
@@ -58,8 +45,7 @@ spec:
58
45
59
46
### Listener
60
47
61
-
The listener defines a listener (a combination of a protocol and a port) that NGINX will use to accept traffic for a
62
-
[TransportServer](/nginx-ingress-controller/configuration/transportserver-resource) and a [VirtualServer](nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources):
48
+
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):
63
49
64
50
```yaml
65
51
name: dns-tcp
@@ -80,17 +66,16 @@ protocol: TCP
80
66
81
67
You can use the usual `kubectl` commands to work with a GlobalConfiguration resource.
82
68
83
-
For example, the following command creates a GlobalConfiguration resource defined in `global-configuration.yaml` with
84
-
the name `nginx-configuration`:
69
+
For example, the following command creates a GlobalConfiguration resource defined in `global-configuration.yaml` with the name `nginx-configuration`:
85
70
86
-
```shell
71
+
```
87
72
$ kubectl apply -f global-configuration.yaml
88
73
globalconfiguration.k8s.nginx.org/nginx-configuration created
89
74
```
90
75
91
76
Assuming the namespace of the resource is `nginx-ingress`, you can get the resource by running:
92
77
93
-
```shell
78
+
```
94
79
$ kubectl get globalconfiguration nginx-configuration -n nginx-ingress
95
80
NAME AGE
96
81
nginx-configuration 13s
@@ -107,47 +92,39 @@ Two types of validation are available for the GlobalConfiguration resource:
107
92
108
93
#### Structural Validation
109
94
110
-
The custom resource definition for the GlobalConfiguration includes structural OpenAPI schema which describes the type
111
-
of every field of the resource.
95
+
The custom resource definition for the GlobalConfiguration includes structural OpenAPI schema which describes the type of every field of the resource.
112
96
113
-
If you try to create (or update) a resource that violates the structural schema (for example, you use a string value for
114
-
the port field of a listener), `kubectl` and Kubernetes API server will reject such a resource:
97
+
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:
115
98
116
99
- Example of `kubectl` validation:
117
100
118
-
```shell
101
+
```
119
102
$ kubectl apply -f global-configuration.yaml
120
103
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
The GlobalConfiguration "nginx-configuration" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list:
128
-
spec.listeners.port in body must be of type integer: "string"
110
+
The GlobalConfiguration "nginx-configuration" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list:
111
+
spec.listeners.port in body must be of type integer: "string"
129
112
```
130
113
131
114
If a resource is not rejected (it doesn't violate the structural schema), the Ingress Controller will validate it further.
132
115
133
116
#### Comprehensive Validation
134
117
135
-
The Ingress Controller validates the fields of a GlobalConfiguration resource. If a resource is invalid,
136
-
the Ingress Controller will not use it. Consider the following two cases:
118
+
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:
137
119
138
-
1. When the Ingress Controller pod starts, if the GlobalConfiguration resource is invalid, the Ingress Controller will
139
-
fail to start and exit with an error.
140
-
2. When the Ingress Controller is running, if the GlobalConfiguration resource becomes invalid, the Ingress Controller
141
-
will ignore the new version. It will report an error and continue to use the previous version. When the resource becomes
142
-
valid again, the Ingress Controller will start using it.
120
+
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.
121
+
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.
143
122
144
-
**Note**: If a GlobalConfiguration is deleted while the Ingress Controller is running, the controller will keep using
145
-
the previous version of the resource.
123
+
**Note**: If a GlobalConfiguration is deleted while the Ingress Controller is running, the controller will keep using the previous version of the resource.
146
124
147
-
You can check if the Ingress Controller successfully applied the configuration for a GlobalConfiguration.
148
-
For our `nginx-configuration` GlobalConfiguration, we can run:
125
+
You can check if the Ingress Controller successfully applied the configuration for a GlobalConfiguration. For our `nginx-configuration` GlobalConfiguration, we can run:
Normal Updated 11s nginx-ingress-controller GlobalConfiguration nginx-ingress/nginx-configuration was updated
157
134
```
158
135
159
-
Note how the events section includes a Normal event with the Updated reason that informs us that the configuration was
160
-
successfully applied.
136
+
Note how the events section includes a Normal event with the Updated reason that informs us that the configuration was successfully applied.
161
137
162
-
If you create an invalid resource, the Ingress Controller will reject it and emit a Rejected event. For example, if you
163
-
create a GlobalConfiguration `nginx-configuration` with two or more listeners that have the same protocol UDP and port 53,
164
-
you will get:
138
+
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:
0 commit comments