XTesting/kubespray/docs/ha-mode.md

   1 # HA endpoints for K8s
   2
   3 The following components require a highly available endpoints:
   4
   5 * etcd cluster,
   6 * kube-apiserver service instances.
   7
   8 The latter relies on a 3rd side reverse proxy, like Nginx or HAProxy, to
   9 achieve the same goal.
  10
  11 ## Etcd
  12
  13 The etcd clients (kube-api-masters) are configured with the list of all etcd peers. If the etcd-cluster has multiple instances, it's configured in HA already.
  14
  15 ## Kube-apiserver
  16
  17 K8s components require a loadbalancer to access the apiservers via a reverse
  18 proxy. Kubespray includes support for an nginx-based proxy that resides on each
  19 non-master Kubernetes node. This is referred to as localhost loadbalancing. It
  20 is less efficient than a dedicated load balancer because it creates extra
  21 health checks on the Kubernetes apiserver, but is more practical for scenarios
  22 where an external LB or virtual IP management is inconvenient.  This option is
  23 configured by the variable `loadbalancer_apiserver_localhost` (defaults to
  24 `True`. Or `False`, if there is an external `loadbalancer_apiserver` defined).
  25 You may also define the port the local internal loadbalancer uses by changing,
  26 `loadbalancer_apiserver_port`.  This defaults to the value of
  27 `kube_apiserver_port`. It is also important to note that Kubespray will only
  28 configure kubelet and kube-proxy on non-master nodes to use the local internal
  29 loadbalancer.
  30
  31 If you choose to NOT use the local internal loadbalancer, you will need to
  32 use the [kube-vip](kube-vip.md) ansible role or configure your own loadbalancer to achieve HA. By default, it only configures a non-HA endpoint, which points to the
  33 `access_ip` or IP address of the first server node in the `kube_control_plane` group.
  34 It can also configure clients to use endpoints for a given loadbalancer type.
  35 The following diagram shows how traffic to the apiserver is directed.
  36
  37 ![Image](figures/loadbalancer_localhost.png?raw=true)
  38
  39 A user may opt to use an external loadbalancer (LB) instead. An external LB
  40 provides access for external clients, while the internal LB accepts client
  41 connections only to the localhost.
  42 Given a frontend `VIP` address and `IP1, IP2` addresses of backends, here is
  43 an example configuration for a HAProxy service acting as an external LB:
  44
  45 ```raw
  46 listen kubernetes-apiserver-https
  47   bind <VIP>:8383
  48   mode tcp
  49   option log-health-checks
  50   timeout client 3h
  51   timeout server 3h
  52   server master1 <IP1>:6443 check check-ssl verify none inter 10000
  53   server master2 <IP2>:6443 check check-ssl verify none inter 10000
  54   balance roundrobin
  55 ```
  56
  57   Note: That's an example config managed elsewhere outside of Kubespray.
  58
  59 And the corresponding example global vars for such a "cluster-aware"
  60 external LB with the cluster API access modes configured in Kubespray:
  61
  62 ```yml
  63 apiserver_loadbalancer_domain_name: "my-apiserver-lb.example.com"
  64 loadbalancer_apiserver:
  65   address: <VIP>
  66   port: 8383
  67 ```
  68
  69   Note: The default kubernetes apiserver configuration binds to all interfaces,
  70   so you will need to use a different port for the vip from that the API is
  71   listening on, or set the `kube_apiserver_bind_address` so that the API only
  72   listens on a specific interface (to avoid conflict with haproxy binding the
  73   port on the VIP address)
  74
  75 This domain name, or default "lb-apiserver.kubernetes.local", will be inserted
  76 into the `/etc/hosts` file of all servers in the `k8s_cluster` group and wired
  77 into the generated self-signed TLS/SSL certificates as well. Note that
  78 the HAProxy service should as well be HA and requires a VIP management, which
  79 is out of scope of this doc.
  80
  81 There is a special case for an internal and an externally configured (not with
  82 Kubespray) LB used simultaneously. Keep in mind that the cluster is not aware
  83 of such an external LB and you need no to specify any configuration variables
  84 for it.
  85
  86   Note: TLS/SSL termination for externally accessed API endpoints' will **not**
  87   be covered by Kubespray for that case. Make sure your external LB provides it.
  88   Alternatively you may specify an externally load balanced VIPs in the
  89   `supplementary_addresses_in_ssl_keys` list. Then, kubespray will add them into
  90   the generated cluster certificates as well.
  91
  92 Aside of that specific case, the `loadbalancer_apiserver` considered mutually
  93 exclusive to `loadbalancer_apiserver_localhost`.
  94
  95 Access API endpoints are evaluated automatically, as the following:
  96
  97 | Endpoint type                | kube_control_plane                       | non-master              | external              |
  98 |------------------------------|------------------------------------------|-------------------------|-----------------------|
  99 | Local LB (default)           | `https://dbip:sp`                        | `https://lc:nsp`        | `https://m[0].aip:sp` |
 100 | Local LB (default) + cbip    | `https://cbip:sp` and `https://lc:nsp`   | `https://lc:nsp`        | `https://m[0].aip:sp` |
 101 | Local LB + Unmanaged here LB | `https://dbip:sp`                        | `https://lc:nsp`        | `https://ext`         |
 102 | External LB, no internal     | `https://dbip:sp`                        | `<https://lb:lp>`       | `https://lb:lp`       |
 103 | No ext/int LB                | `https://dbip:sp`                        | `<https://m[0].aip:sp>` | `https://m[0].aip:sp` |
 104
 105 Where:
 106
 107 * `m[0]` - the first node in the `kube_control_plane` group;
 108 * `lb` - LB FQDN, `apiserver_loadbalancer_domain_name`;
 109 * `ext` - Externally load balanced VIP:port and FQDN, not managed by Kubespray;
 110 * `lc` - localhost;
 111 * `cbip` - a custom bind IP, `kube_apiserver_bind_address`;
 112 * `dbip` - localhost for the default bind IP '0.0.0.0';
 113 * `nsp` - nginx secure port, `loadbalancer_apiserver_port`, defers to `sp`;
 114 * `sp` - secure port, `kube_apiserver_port`;
 115 * `lp` - LB port, `loadbalancer_apiserver.port`, defers to the secure port;
 116 * `ip` - the node IP, defers to the ansible IP;
 117 * `aip` - `access_ip`, defers to the ip.
 118
 119 A second and a third column represent internal cluster access modes. The last
 120 column illustrates an example URI to access the cluster APIs externally.
 121 Kubespray has nothing to do with it, this is informational only.
 122
 123 As you can see, the masters' internal API endpoints are always
 124 contacted via the local bind IP, which is `https://bip:sp`.
 125
 126 ## Optional configurations
 127
 128 ### ETCD with a LB
 129
 130 In order to use an external loadbalancing (L4/TCP or L7 w/ SSL Passthrough VIP), the following variables need to be overridden in group_vars
 131
 132 * `etcd_access_addresses`
 133 * `etcd_client_url`
 134 * `etcd_cert_alt_names`
 135 * `etcd_cert_alt_ips`
 136
 137 #### Example of a VIP w/ FQDN
 138
 139 ```yaml
 140 etcd_access_addresses: https://etcd.example.com:2379
 141 etcd_client_url: https://etcd.example.com:2379
 142 etcd_cert_alt_names:
 143   - "etcd.kube-system.svc.{{ dns_domain }}"
 144   - "etcd.kube-system.svc"
 145   - "etcd.kube-system"
 146   - "etcd"
 147   - "etcd.example.com" # This one needs to be added to the default etcd_cert_alt_names
 148 ```
 149
 150 #### Example of a VIP w/o FQDN (IP only)
 151
 152 ```yaml
 153 etcd_access_addresses: https://2.3.7.9:2379
 154 etcd_client_url: https://2.3.7.9:2379
 155 etcd_cert_alt_ips:
 156   - "2.3.7.9"
 157 ```