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-web/configuration/handling-host-and-listener-collisions.md
+63-9Lines changed: 63 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,20 @@
1
-
# Handling Host Collisions
1
+
# Handling Host and Listener Collisions
2
2
3
-
A host collision occurs when multiple resources configure the same `host`. The Ingress Controller supports two options for handling host collisions:
3
+
This document explains how the Ingress Controller handles host and listener collisions among resources.
4
+
5
+
## Winner Selection Algorithm
6
+
7
+
If multiple resources contend for the same host/listener, the Ingress Controller will pick the winner based on the `creationTimestamp` of the resources: the oldest resource will win. In case there are more than one oldest resource (their `creationTimestamp` is the same), the Ingress Controller will choose the resource with the lexicographically smallest `uid`.
8
+
9
+
Note: the `creationTimestamp` and `uid` fields are part of the resource [ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#objectmeta-v1-meta).
10
+
11
+
## Host Collisions
12
+
13
+
A host collision occurs when multiple Ingress, VirtualServer, and TransportServer (configured for TLS Passthrough) resources configure the same `host`. The Ingress Controller supports two options for handling host collisions:
4
14
* Choosing the winner so that only one resource handles the host.
5
15
* Merging configuration of the conflicting resources.
6
16
7
-
## Choosing the Winner
17
+
###Choosing the Winner
8
18
9
19
Consider the following two resources:
10
20
*`cafe-ingress` Ingress:
@@ -31,11 +41,7 @@ Consider the following two resources:
31
41
. . .
32
42
```
33
43
34
-
If a user creates both resources in the cluster, a host collision will occur. As a result, the Ingress Controller will pick the winner using the following algorithm:
35
-
36
-
> If multiple resources contend for the same host, the Ingress Controller will pick the winner based on the `creationTimestamp` of the resources: the oldest resource will win. In case there are more than one oldest resources (their `creationTimestamp` is the same), the Ingress Controller will choose the resource with the lexicographically smallest `uid`.
37
-
38
-
> Note: the `creationTimestamp` and `uid` fields are part of the resource [ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#objectmeta-v1-meta).
44
+
If a user creates both resources in the cluster, a host collision will occur. As a result, the Ingress Controller will pick the winner using the [winner selection algorithm](#winner-selection-algorithm).
39
45
40
46
In our example, if `cafe-virtual-server` was created first, it will win the host `cafe.example.com` and the Ingress Controller will reject `cafe-ingress`. This will be reflected in the events and in the resource's status field:
41
47
```
@@ -62,8 +68,56 @@ Events:
62
68
63
69
Similarly, if `cafe-ingress` was created first, it will win `cafe.example.com` and the Ingress Controller will reject `cafe-virtual-server`.
64
70
65
-
## Merging Configuration for the Same Host
71
+
### Merging Configuration for the Same Host
66
72
67
73
It is possible to merge configuration for multiple Ingress resources for the same host. One common use case for this approach is distributing resources across multiple namespaces. See the [Cross-namespace Configuration](/nginx-ingress-controller/configuration/ingress-resources/cross-namespace-configuration/) doc for more information.
68
74
69
75
It is *not* possible to merge the configurations for multiple VirtualServer resources for the same host. However, you can split the VirtualServers into multiple VirtualServerRoute resources, which a single VirtualServer can then reference. See the [corresponding example](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples-of-custom-resources/cross-namespace-configuration) on GitHub.
76
+
77
+
It is *not* possible to merge configuration for multiple TransportServer resources.
78
+
79
+
## Listener Collisions
80
+
81
+
Listener collisions occur when multiple TransportServer resources (configured for TCP/UDP load balancing) configure the same `listener`. The Ingress Controller will choose the winner, which will own the listener.
82
+
83
+
### Choosing the Winner
84
+
85
+
Consider the following two resources:
86
+
* `tcp-1` TransportServer:
87
+
```yaml
88
+
apiVersion: k8s.nginx.org/v1alpha1
89
+
kind: TransportServer
90
+
metadata:
91
+
name: tcp-1
92
+
spec:
93
+
listener:
94
+
name: dns-tcp
95
+
protocol: TCP
96
+
. . .
97
+
```
98
+
* `tcp-2` TransportServer:
99
+
```yaml
100
+
apiVersion: k8s.nginx.org/v1alpha1
101
+
kind: TransportServer
102
+
metadata:
103
+
name: tcp-2
104
+
spec:
105
+
listener:
106
+
name: dns-tcp
107
+
protocol: TCP
108
+
. . .
109
+
```
110
+
111
+
If a user creates both resources in the cluster, a listener collision will occur. As a result, the Ingress Controller will pick the winner using the [winner selection algorithm](#winner-selection-algorithm).
112
+
113
+
In our example, if `tcp-1` was created first, it will win the listener `dns-tcp` and the Ingress Controller will reject `tcp-2`. This will be reflected in the events and in the resource's status field:
114
+
```
115
+
$ kubectl describe ts tcp-2
116
+
. . .
117
+
Events:
118
+
Type Reason Age From Message
119
+
---- ------ ---- ---- -------
120
+
Warning Rejected 10s nginx-ingress-controller Listener dns-tcp is taken by another resource
121
+
```
122
+
123
+
Similarly, if `tcp-2` was created first, it will win `dns-tcp` and the Ingress Controller will reject `tcp-1`.
Copy file name to clipboardExpand all lines: docs-web/configuration/transportserver-resource.md
+2-4Lines changed: 2 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -425,7 +425,5 @@ The [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/con
425
425
426
426
## Limitations
427
427
428
-
As of Release 1.7, the TransportServer resource is a preview feature. Currently, it comes with the following limitations:
429
-
* When using TLS Passthrough, it is not possible to configure [Proxy Protocol](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples/proxy-protocol) for port 443 both for regular HTTPS and TLS Passthrough traffic.
430
-
* If multiple TCP (or UDP) TransportServers reference the same listener, only one of them will receive the traffic. Moreover, until there is only one TransportServer, NGINX will fail to reload. If this happens, the IC will report a warning event with the `AddedOrUpdatedWithError` reason for the resource, which caused the problem, and also report the error in the logs.
431
-
* If multiple TLS Passthrough TransportServers have the same hostname, only one of them will receive the traffic. If this happens, the IC will report a warning in the logs like `host "app.example.com" is used by more than one TransportServers`.
428
+
The TransportServer resource is a preview feature. Currently, it comes with the following limitation:
429
+
* When using TLS Passthrough, it is not possible to configure [Proxy Protocol](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples/proxy-protocol) for port 443 both for regular HTTPS and TLS Passthrough traffic.
0 commit comments