XTesting/kubespray/docs/cilium.md

   1 # Cilium
   2
   3 ## Kube-proxy replacement with Cilium
   4
   5 Cilium can run without kube-proxy by setting `cilium_kube_proxy_replacement`
   6 to `strict`.
   7
   8 Without kube-proxy, cilium needs to know the address of the kube-apiserver
   9 and this must be set globally for all cilium components (agents and operators).
  10 Hence, in this configuration in Kubespray, Cilium will always contact
  11 the external loadbalancer (even from a node in the control plane)
  12 and if there is no external load balancer It will ignore any local load
  13 balancer deployed by Kubespray and **only contacts the first master**.
  14
  15 ## Cilium Operator
  16
  17 Unlike some operators, Cilium Operator does not exist for installation purposes.
  18 > The Cilium Operator is responsible for managing duties in the cluster which should logically be handled once for the entire cluster, rather than once for each node in the cluster.
  19
  20 ### Adding custom flags to the Cilium Operator
  21
  22 You can set additional cilium-operator container arguments using `cilium_operator_custom_args`.
  23 This is an advanced option, and you should only use it if you know what you are doing.
  24
  25 Accepts an array or a string.
  26
  27 ```yml
  28 cilium_operator_custom_args: ["--foo=bar", "--baz=qux"]
  29 ```
  30
  31 or
  32
  33 ```yml
  34 cilium_operator_custom_args: "--foo=bar"
  35 ```
  36
  37 You do not need to add a custom flag to enable debugging. Instead, feel free to use the `CILIUM_DEBUG` variable.
  38
  39 ### Adding extra volumes and mounting them
  40
  41 You can use `cilium_operator_extra_volumes` to add extra volumes to the Cilium Operator, and use `cilium_operator_extra_volume_mounts` to mount those volumes.
  42 This is an advanced option, and you should only use it if you know what you are doing.
  43
  44 ```yml
  45 cilium_operator_extra_volumes:
  46   - configMap:
  47       name: foo
  48     name: foo-mount-path
  49
  50 cilium_operator_extra_volume_mounts:
  51   - mountPath: /tmp/foo/bar
  52     name: foo-mount-path
  53     readOnly: true
  54 ```
  55
  56 ## Choose Cilium version
  57
  58 ```yml
  59 cilium_version: v1.11.3
  60 ```
  61
  62 ## Add variable to config
  63
  64 Use following variables:
  65
  66 Example:
  67
  68 ```yml
  69 cilium_config_extra_vars:
  70   enable-endpoint-routes: true
  71 ```
  72
  73 ## Change Identity Allocation Mode
  74
  75 Cilium assigns an identity for each endpoint. This identity is used to enforce basic connectivity between endpoints.
  76
  77 Cilium currently supports two different identity allocation modes:
  78
  79 - "crd" stores identities in kubernetes as CRDs (custom resource definition).
  80   - These can be queried with `kubectl get ciliumid`
  81 - "kvstore" stores identities in an etcd kvstore.
  82
  83 ## Enable Transparent Encryption
  84
  85 Cilium supports the transparent encryption of Cilium-managed host traffic and
  86 traffic between Cilium-managed endpoints either using IPsec or Wireguard.
  87
  88 Wireguard option is only available in Cilium 1.10.0 and newer.
  89
  90 ### IPsec Encryption
  91
  92 For further information, make sure to check the official [Cilium documentation.](https://docs.cilium.io/en/stable/gettingstarted/encryption-ipsec/)
  93
  94 To enable IPsec encryption, you just need to set three variables.
  95
  96 ```yml
  97 cilium_encryption_enabled: true
  98 cilium_encryption_type: "ipsec"
  99 ```
 100
 101 The third variable is `cilium_ipsec_key.` You need to create a secret key string for this variable.
 102 Kubespray does not automate this process.
 103 Cilium documentation currently recommends creating a key using the following command:
 104
 105 ```shell
 106 echo "3 rfc4106(gcm(aes)) $(echo $(dd if=/dev/urandom count=20 bs=1 2> /dev/null | xxd -p -c 64)) 128"
 107 ```
 108
 109 Note that Kubespray handles secret creation. So you only need to pass the key as the `cilium_ipsec_key` variable.
 110
 111 ### Wireguard Encryption
 112
 113 For further information, make sure to check the official [Cilium documentation.](https://docs.cilium.io/en/stable/gettingstarted/encryption-wireguard/)
 114
 115 To enable Wireguard encryption, you just need to set two variables.
 116
 117 ```yml
 118 cilium_encryption_enabled: true
 119 cilium_encryption_type: "wireguard"
 120 ```
 121
 122 Kubespray currently supports Linux distributions with Wireguard Kernel mode on Linux 5.6 and newer.
 123
 124 ## Install Cilium Hubble
 125
 126 k8s-net-cilium.yml:
 127
 128 ```yml
 129 cilium_enable_hubble: true ## enable support hubble in cilium
 130 cilium_hubble_install: true ## install hubble-relay, hubble-ui
 131 cilium_hubble_tls_generate: true ## install hubble-certgen and generate certificates
 132 ```
 133
 134 To validate that Hubble UI is properly configured, set up a port forwarding for hubble-ui service:
 135
 136 ```shell script
 137 kubectl port-forward -n kube-system svc/hubble-ui 12000:80
 138 ```
 139
 140 and then open [http://localhost:12000/](http://localhost:12000/).
 141
 142 ## Hubble metrics
 143
 144 ```yml
 145 cilium_enable_hubble_metrics: true
 146 cilium_hubble_metrics:
 147   - dns
 148   - drop
 149   - tcp
 150   - flow
 151   - icmp
 152   - http
 153 ```
 154
 155 [More](https://docs.cilium.io/en/v1.9/operations/metrics/#hubble-exported-metrics)
 156
 157 ## Upgrade considerations
 158
 159 ### Rolling-restart timeouts
 160
 161 Cilium relies on the kernel's BPF support, which is extremely fast at runtime but incurs a compilation penalty on initialization and update.
 162
 163 As a result, the Cilium DaemonSet pods can take a significant time to start, which scales with the number of nodes and endpoints in your cluster.
 164
 165 As part of cluster.yml, this DaemonSet is restarted, and Kubespray's [default timeouts for this operation](../roles/network_plugin/cilium/defaults/main.yml)
 166 are not appropriate for large clusters.
 167
 168 This means that you will likely want to update these timeouts to a value more in-line with your cluster's number of nodes and their respective CPU performance.
 169 This is configured by the following values:
 170
 171 ```yaml
 172 # Configure how long to wait for the Cilium DaemonSet to be ready again
 173 cilium_rolling_restart_wait_retries_count: 30
 174 cilium_rolling_restart_wait_retries_delay_seconds: 10
 175 ```
 176
 177 The total time allowed (count * delay) should be at least `($number_of_nodes_in_cluster * $cilium_pod_start_time)` for successful rolling updates. There are no
 178 drawbacks to making it higher and giving yourself a time buffer to accommodate transient slowdowns.
 179
 180 Note: To find the `$cilium_pod_start_time` for your cluster, you can simply restart a Cilium pod on a node of your choice and look at how long it takes for it
 181 to become ready.
 182
 183 Note 2: The default CPU requests/limits for Cilium pods is set to a very conservative 100m:500m which will likely yield very slow startup for Cilium pods. You
 184 probably want to significantly increase the CPU limit specifically if short bursts of CPU from Cilium are acceptable to you.