github.com/cilium/cilium@v1.16.2/Documentation/network/clustermesh/affinity.rst (about)

     1  .. _gs_clustermesh_service_affinity:
     2  
     3  ****************
     4  Service Affinity
     5  ****************
     6  
     7  This tutorial will guide you to enable service affinity across multiple
     8  Kubernetes clusters.
     9  
    10  Prerequisites
    11  #############
    12  
    13  You need to have a functioning Cluster Mesh with a Global Service, please
    14  follow the guide :ref:`gs_clustermesh` and :ref:`gs_clustermesh_services`
    15  to set it up.
    16  
    17  Enabling Global Service Affinity
    18  ################################
    19  
    20  Load-balancing across multiple clusters might not be ideal in some cases.
    21  The annotation ``service.cilium.io/affinity: "local|remote|none"`` can be used
    22  to specify the preferred endpoint destination.
    23  
    24  For example, if the value of annotation ``service.cilium.io/affinity`` is local,
    25  the Global Service will load-balance across healthy ``local`` backends, and only user
    26  remote endpoints if and only if all of local backends are not available or unhealthy.
    27  
    28  .. code-block:: yaml
    29  
    30     apiVersion: v1
    31     kind: Service
    32     metadata:
    33       name: rebel-base
    34       annotations:
    35          service.cilium.io/global: "true"
    36          # Possible values:
    37          # - local
    38          #    preferred endpoints from local cluster if available
    39          # - remote
    40          #    preferred endpoints from remote cluster if available
    41          # none (default)
    42          #    no preference. Default behavior if this annotation does not exist
    43          service.cilium.io/affinity: "local"
    44     spec:
    45       type: ClusterIP
    46       ports:
    47       - port: 80
    48       selector:
    49         name: rebel-base
    50  
    51  
    52  1. In cluster 1, add ``service.cilium.io/affinity="local"`` to existing global service
    53  
    54     .. code-block:: shell-session
    55  
    56        kubectl annotate service rebel-base service.cilium.io/affinity=local --overwrite
    57  
    58  2. From cluster 1, access the global service:
    59  
    60     .. code-block:: shell-session
    61  
    62        kubectl exec -ti deployment/x-wing -- curl rebel-base
    63  
    64     You will see replies from pods in ``cluster 1`` only.
    65  
    66  3. From cluster 2, access the global service:
    67  
    68     .. code-block:: shell-session
    69  
    70        kubectl exec -ti deployment/x-wing -- curl rebel-base
    71  
    72     You will see replies from pods in both clusters as usual.
    73  
    74  4. From cluster 1, check the service endpoints, the local endpoints are marked
    75     as preferred.
    76  
    77     .. code-block:: shell-session
    78  
    79        kubectl exec -n kube-system -ti ds/cilium -- cilium-dbg service list --clustermesh-affinity
    80  
    81        ID   Frontend            Service Type   Backend
    82        1    10.96.0.1:443       ClusterIP      1 => 172.18.0.3:6443 (active)
    83        2    10.96.0.10:53       ClusterIP      1 => 10.244.1.171:53 (active)
    84                                                2 => 10.244.2.206:53 (active)
    85        3    10.96.0.10:9153     ClusterIP      1 => 10.244.1.171:9153 (active)
    86                                                2 => 10.244.2.206:9153 (active)
    87        4    10.96.210.49:2379   ClusterIP      1 => 10.244.2.216:2379 (active)
    88        5    10.96.173.113:80    ClusterIP      1 => 10.244.2.136:80 (active)
    89                                                2 => 10.244.1.61:80 (active) (preferred)
    90                                                3 => 10.244.2.31:80 (active) (preferred)
    91                                                4 => 10.244.2.200:80 (active)
    92  
    93  5. In cluster 1, change ``service.cilium.io/affinity`` value to ``remote`` for existing global service
    94  
    95     .. code-block:: shell-session
    96  
    97        kubectl annotate service rebel-base service.cilium.io/affinity=remote --overwrite
    98  
    99  6. From cluster 1, access the global service:
   100  
   101     .. code-block:: shell-session
   102  
   103        kubectl exec -ti deployment/x-wing -- curl rebel-base
   104  
   105     This time, the replies are coming from pods in ``cluster 2`` only.
   106  
   107  7. From cluster 1, check the service endpoints, now the remote endpoints are marked
   108     as preferred.
   109  
   110     .. code-block:: shell-session
   111  
   112        kubectl exec -n kube-system -ti ds/cilium -- cilium-dbg service list --clustermesh-affinity
   113  
   114        ID   Frontend            Service Type   Backend
   115        1    10.96.0.1:443       ClusterIP      1 => 172.18.0.3:6443 (active)
   116        2    10.96.0.10:53       ClusterIP      1 => 10.244.1.171:53 (active)
   117                                                2 => 10.244.2.206:53 (active)
   118        3    10.96.0.10:9153     ClusterIP      1 => 10.244.1.171:9153 (active)
   119                                                2 => 10.244.2.206:9153 (active)
   120        4    10.96.210.49:2379   ClusterIP      1 => 10.244.2.216:2379 (active)
   121        5    10.96.173.113:80    ClusterIP      1 => 10.244.2.136:80 (active) (preferred)
   122                                                2 => 10.244.1.61:80 (active)
   123                                                3 => 10.244.2.31:80 (active)
   124                                                4 => 10.244.2.200:80 (active) (preferred)
   125  
   126  8. From cluster 2, access the global service:
   127  
   128     .. code-block:: shell-session
   129  
   130        kubectl exec -ti deployment/x-wing -- curl rebel-base
   131  
   132     You will see replies from pods in both clusters as usual.
   133  
   134  9. In cluster 1, remove ``service.cilium.io/affinity`` annotation for existing global service
   135  
   136     .. code-block:: shell-session
   137  
   138        kubectl annotate service rebel-base service.cilium.io/affinity- --overwrite
   139  
   140  10. From either cluster, access the global service:
   141  
   142      .. code-block:: shell-session
   143  
   144          kubectl exec -ti deployment/x-wing -- curl rebel-base
   145  
   146      You will see replies from pods in both clusters again.