github.com/nginxinc/kubernetes-ingress@v1.12.5/docs-web/configuration/handling-host-and-listener-collisions.md (about)

     1  # Handling Host and Listener Collisions
     2  
     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:
    14  * Choosing the winner so that only one resource handles the host.
    15  * Merging configuration of the conflicting resources.
    16  
    17  ### Choosing the Winner
    18  
    19  Consider the following two resources:
    20  * `cafe-ingress` Ingress:
    21      ```yaml
    22      apiVersion: networking.k8s.io/v1beta1
    23      kind: Ingress
    24      metadata:
    25        name: cafe-ingress
    26        annotations:
    27          kubernetes.io/ingress.class: "nginx"
    28      spec:
    29        rules:
    30        - host: cafe.example.com
    31          . . .
    32      ```
    33  * `cafe-virtual-server` VirtualServer:
    34      ```yaml
    35      apiVersion: k8s.nginx.org/v1
    36      kind: VirtualServer
    37      metadata:
    38        name: cafe-virtual-server
    39      spec:
    40        host: cafe.example.com
    41        . . .
    42      ```
    43  
    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).
    45  
    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:
    47  ```
    48  $ kubectl describe vs cafe-virtual-server
    49  . . .
    50  Status:
    51    . . .
    52    Message:  Configuration for default/cafe-virtual-server was added or updated
    53    Reason:   AddedOrUpdated
    54    State:    Valid
    55  Events:
    56    Type    Reason          Age   From                      Message
    57    ----    ------          ----  ----                      -------
    58    Normal  AddedOrUpdated  9s    nginx-ingress-controller  Configuration for default/cafe-virtual-server was added or updated
    59  
    60  $ kubectl describe ingress cafe-ingress
    61  . . .
    62  Events:
    63    Type     Reason    Age   From                      Message
    64    ----     ------    ----  ----                      -------
    65    Warning  Rejected  66s   nginx-ingress-controller  All hosts are taken by other resources
    66  ```
    67  > Note: You can configure multiple hosts for Ingress resources. As a result, it's possible that an Ingress resource can be the winner for some of its hosts and a loser for the others. For example, if `cafe-ingress` had an additional rule host rule -- `pub.example.com` -- the Ingress Controller would not reject the Ingress. Rather, it would allow `cafe-ingress` to handle `pub.example.com`.
    68  
    69  Similarly, if `cafe-ingress` was created first, it will win `cafe.example.com` and the Ingress Controller will reject `cafe-virtual-server`.
    70  
    71  ### Merging Configuration for the Same Host
    72  
    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.
    74  
    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/v1.12.5/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`.