XTesting/kubespray/docs/calico.md

   1 # Calico
   2
   3 Check if the calico-node container is running
   4
   5 ```ShellSession
   6 docker ps | grep calico
   7 ```
   8
   9 The **calicoctl.sh** is wrap script with configured access credentials for command calicoctl allows to check the status of the network workloads.
  10
  11 * Check the status of Calico nodes
  12
  13 ```ShellSession
  14 calicoctl.sh node status
  15 ```
  16
  17 * Show the configured network subnet for containers
  18
  19 ```ShellSession
  20 calicoctl.sh get ippool -o wide
  21 ```
  22
  23 * Show the workloads (ip addresses of containers and their location)
  24
  25 ```ShellSession
  26 calicoctl.sh get workloadEndpoint -o wide
  27 ```
  28
  29 and
  30
  31 ```ShellSession
  32 calicoctl.sh get hostEndpoint -o wide
  33 ```
  34
  35 ## Configuration
  36
  37 ### Optional : Define datastore type
  38
  39 The default datastore, Kubernetes API datastore is recommended for on-premises deployments, and supports only Kubernetes workloads; etcd is the best datastore for hybrid deployments.
  40
  41 Allowed values are `kdd` (default) and `etcd`.
  42
  43 Note: using kdd and more than 50 nodes, consider using the `typha` daemon to provide scaling.
  44
  45 To re-define you need to edit the inventory and add a group variable `calico_datastore`
  46
  47 ```yml
  48 calico_datastore: kdd
  49 ```
  50
  51 ### Optional : Define network backend
  52
  53 In some cases you may want to define Calico network backend. Allowed values are `bird`, `vxlan` or `none`. `vxlan` is the default value.
  54
  55 To re-define you need to edit the inventory and add a group variable `calico_network_backend`
  56
  57 ```yml
  58 calico_network_backend: none
  59 ```
  60
  61 ### Optional : Define the default pool CIDRs
  62
  63 By default, `kube_pods_subnet` is used as the IP range CIDR for the default IP Pool, and `kube_pods_subnet_ipv6` for IPv6.
  64 In some cases you may want to add several pools and not have them considered by Kubernetes as external (which means that they must be within or equal to the range defined in `kube_pods_subnet` and `kube_pods_subnet_ipv6` ), it starts with the default IP Pools of which IP range CIDRs can by defined in group_vars (k8s_cluster/k8s-net-calico.yml):
  65
  66 ```ShellSession
  67 calico_pool_cidr: 10.233.64.0/20
  68 calico_pool_cidr_ipv6: fd85:ee78:d8a6:8607::1:0000/112
  69 ```
  70
  71 ### Optional : BGP Peering with border routers
  72
  73 In some cases you may want to route the pods subnet and so NAT is not needed on the nodes.
  74 For instance if you have a cluster spread on different locations and you want your pods to talk each other no matter where they are located.
  75 The following variables need to be set:
  76 `peer_with_router` to enable the peering with the datacenter's border router (default value: false).
  77 you'll need to edit the inventory and add a hostvar `local_as` by node.
  78
  79 ```ShellSession
  80 node1 ansible_ssh_host=95.54.0.12 local_as=xxxxxx
  81 ```
  82
  83 ### Optional : Defining BGP peers
  84
  85 Peers can be defined using the `peers` variable (see docs/calico_peer_example examples).
  86 In order to define global peers, the `peers` variable can be defined in group_vars with the "scope" attribute of each global peer set to "global".
  87 In order to define peers on a per node basis, the `peers` variable must be defined in hostvars.
  88 NB: Ansible's `hash_behaviour` is by default set to "replace", thus defining both global and per node peers would end up with having only per node peers. If having both global and per node peers defined was meant to happen, global peers would have to be defined in hostvars for each host (as well as per node peers)
  89
  90 Since calico 3.4, Calico supports advertising Kubernetes service cluster IPs over BGP, just as it advertises pod IPs.
  91 This can be enabled by setting the following variable as follow in group_vars (k8s_cluster/k8s-net-calico.yml)
  92
  93 ```yml
  94 calico_advertise_cluster_ips: true
  95 ```
  96
  97 Since calico 3.10, Calico supports advertising Kubernetes service ExternalIPs over BGP in addition to cluster IPs advertising.
  98 This can be enabled by setting the following variable in group_vars (k8s_cluster/k8s-net-calico.yml)
  99
 100 ```yml
 101 calico_advertise_service_external_ips:
 102 - x.x.x.x/24
 103 - y.y.y.y/32
 104 ```
 105
 106 ### Optional : Define global AS number
 107
 108 Optional parameter `global_as_num` defines Calico global AS number (`/calico/bgp/v1/global/as_num` etcd key).
 109 It defaults to "64512".
 110
 111 ### Optional : BGP Peering with route reflectors
 112
 113 At large scale you may want to disable full node-to-node mesh in order to
 114 optimize your BGP topology and improve `calico-node` containers' start times.
 115
 116 To do so you can deploy BGP route reflectors and peer `calico-node` with them as
 117 recommended here:
 118
 119 * <https://hub.docker.com/r/calico/routereflector/>
 120 * <https://docs.projectcalico.org/v3.1/reference/private-cloud/l3-interconnect-fabric>
 121
 122 You need to edit your inventory and add:
 123
 124 * `calico_rr` group with nodes in it. `calico_rr` can be combined with
 125   `kube_node` and/or `kube_control_plane`. `calico_rr` group also must be a child
 126    group of `k8s_cluster` group.
 127 * `cluster_id` by route reflector node/group (see details
 128 [here](https://hub.docker.com/r/calico/routereflector/))
 129
 130 Here's an example of Kubespray inventory with standalone route reflectors:
 131
 132 ```ini
 133 [all]
 134 rr0 ansible_ssh_host=10.210.1.10 ip=10.210.1.10
 135 rr1 ansible_ssh_host=10.210.1.11 ip=10.210.1.11
 136 node2 ansible_ssh_host=10.210.1.12 ip=10.210.1.12
 137 node3 ansible_ssh_host=10.210.1.13 ip=10.210.1.13
 138 node4 ansible_ssh_host=10.210.1.14 ip=10.210.1.14
 139 node5 ansible_ssh_host=10.210.1.15 ip=10.210.1.15
 140
 141 [kube_control_plane]
 142 node2
 143 node3
 144
 145 [etcd]
 146 node2
 147 node3
 148 node4
 149
 150 [kube_node]
 151 node2
 152 node3
 153 node4
 154 node5
 155
 156 [k8s_cluster:children]
 157 kube_node
 158 kube_control_plane
 159 calico_rr
 160
 161 [calico_rr]
 162 rr0
 163 rr1
 164
 165 [rack0]
 166 rr0
 167 rr1
 168 node2
 169 node3
 170 node4
 171 node5
 172
 173 [rack0:vars]
 174 cluster_id="1.0.0.1"
 175 calcio_rr_id=rr1
 176 calico_group_id=rr1
 177 ```
 178
 179 The inventory above will deploy the following topology assuming that calico's
 180 `global_as_num` is set to `65400`:
 181
 182 ![Image](figures/kubespray-calico-rr.png?raw=true)
 183
 184 ### Optional : Define default endpoint to host action
 185
 186 By default Calico blocks traffic from endpoints to the host itself by using an iptables DROP action. When using it in kubernetes the action has to be changed to RETURN (default in kubespray) or ACCEPT (see <https://github.com/projectcalico/felix/issues/660> and <https://github.com/projectcalico/calicoctl/issues/1389).> Otherwise all network packets from pods (with hostNetwork=False) to services endpoints (with hostNetwork=True) within the same node are dropped.
 187
 188 To re-define default action please set the following variable in your inventory:
 189
 190 ```yml
 191 calico_endpoint_to_host_action: "ACCEPT"
 192 ```
 193
 194 ### Optional : Define address on which Felix will respond to health requests
 195
 196 Since Calico 3.2.0, HealthCheck default behavior changed from listening on all interfaces to just listening on localhost.
 197
 198 To re-define health host please set the following variable in your inventory:
 199
 200 ```yml
 201 calico_healthhost: "0.0.0.0"
 202 ```
 203
 204 ### Optional : Configure Calico Node probe timeouts
 205
 206 Under certain conditions a deployer may need to tune the Calico liveness and readiness probes timeout settings. These can be configured like this:
 207
 208 ```yml
 209 calico_node_livenessprobe_timeout: 10
 210 calico_node_readinessprobe_timeout: 10
 211 ```
 212
 213 ## Config encapsulation for cross server traffic
 214
 215 Calico supports two types of encapsulation: [VXLAN and IP in IP](https://docs.projectcalico.org/v3.11/networking/vxlan-ipip). VXLAN is the more mature implementation and enabled by default, please check your environment if you need *IP in IP* encapsulation.
 216
 217 *IP in IP* and *VXLAN* is mutualy exclusive modes.
 218
 219 Kubespray defaults have changed after version 2.18 from auto-enabling `ipip` mode to auto-enabling `vxlan`. This was done to facilitate wider deployment scenarios including those where vxlan acceleration is provided by the underlying network devices.
 220
 221 If you are running your cluster with the default calico settings and are upgrading to a release post 2.18.x (i.e. 2.19 and later or `master` branch) then you have two options:
 222
 223 * perform a manual migration to vxlan before upgrading kubespray (see migrating from IP in IP to VXLAN below)
 224 * pin the pre-2.19 settings in your ansible inventory (see IP in IP mode settings below)
 225
 226 ### IP in IP mode
 227
 228 To configure Ip in Ip mode you need to use the bird network backend.
 229
 230 ```yml
 231 calico_ipip_mode: 'Always'  # Possible values is `Always`, `CrossSubnet`, `Never`
 232 calico_vxlan_mode: 'Never'
 233 calico_network_backend: 'bird'
 234 ```
 235
 236 ### BGP mode
 237
 238 To enable BGP no-encapsulation mode:
 239
 240 ```yml
 241 calico_ipip_mode: 'Never'
 242 calico_vxlan_mode: 'Never'
 243 calico_network_backend: 'bird'
 244 ```
 245
 246 ### Migrating from IP in IP to VXLAN
 247
 248 If you would like to migrate from the old IP in IP with `bird` network backends default to the new VXLAN based encapsulation you need to perform this change before running an upgrade of your cluster; the `cluster.yml` and `upgrade-cluster.yml` playbooks will refuse to continue if they detect incompatible settings.
 249
 250 Execute the following sters on one of the control plane nodes, ensure the cluster in healthy before proceeding.
 251
 252 ```shell
 253 calicoctl.sh patch felixconfig default -p '{"spec":{"vxlanEnabled":true}}'
 254 calicoctl.sh patch ippool default-pool -p '{"spec":{"ipipMode":"Never", "vxlanMode":"Always"}}'
 255 ```
 256
 257 **Note:** if you created multiple ippools you will need to patch all of them individually to change their encapsulation. The kubespray playbooks only handle the default ippool creaded by kubespray.
 258
 259 Wait for the `vxlan.calico` interfaces to be created on all cluster nodes and traffic to be routed through it then you can disable `ipip`.
 260
 261 ```shell
 262 calicoctl.sh patch felixconfig default -p '{"spec":{"ipipEnabled":false}}'
 263 ```
 264
 265 ## Configuring interface MTU
 266
 267 This is an advanced topic and should usually not be modified unless you know exactly what you are doing. Calico is smart enough to deal with the defaults and calculate the proper MTU. If you do need to set up a custom MTU you can change `calico_veth_mtu` as follows:
 268
 269 * If Wireguard is enabled, subtract 60 from your network MTU (i.e. 1500-60=1440)
 270 * If using VXLAN or BPF mode is enabled, subtract 50 from your network MTU (i.e. 1500-50=1450)
 271 * If using IPIP, subtract 20 from your network MTU (i.e. 1500-20=1480)
 272 * if not using any encapsulation, set to your network MTU (i.e. 1500 or 9000)
 273
 274 ```yaml
 275 calico_veth_mtu: 1440
 276 ```
 277
 278 ## Cloud providers configuration
 279
 280 Please refer to the official documentation, for example [GCE configuration](http://docs.projectcalico.org/v1.5/getting-started/docker/installation/gce) requires a security rule for calico ip-ip tunnels. Note, calico is always configured with ``calico_ipip_mode: Always`` if the cloud provider was defined.
 281
 282 ### Optional : Ignore kernel's RPF check setting
 283
 284 By default the felix agent(calico-node) will abort if the Kernel RPF setting is not 'strict'. If you want Calico to ignore the Kernel setting:
 285
 286 ```yml
 287 calico_node_ignorelooserpf: true
 288 ```
 289
 290 Note that in OpenStack you must allow `ipip` traffic in your security groups,
 291 otherwise you will experience timeouts.
 292 To do this you must add a rule which allows it, for example:
 293
 294 ### Optional : Felix configuration via extraenvs of calico node
 295
 296 Possible environment variable parameters for [configuring Felix](https://docs.projectcalico.org/reference/felix/configuration)
 297
 298 ```yml
 299 calico_node_extra_envs:
 300     FELIX_DEVICEROUTESOURCEADDRESS: 172.17.0.1
 301 ```
 302
 303 ```ShellSession
 304 neutron  security-group-rule-create  --protocol 4  --direction egress  k8s-a0tp4t
 305 neutron  security-group-rule-create  --protocol 4  --direction igress  k8s-a0tp4t
 306 ```
 307
 308 ### Optional : Use Calico CNI host-local IPAM plugin
 309
 310 Calico currently supports two types of CNI IPAM plugins, `host-local` and `calico-ipam` (default).
 311
 312 To allow Calico to determine the subnet to use from the Kubernetes API based on the `Node.podCIDR` field, enable the following setting.
 313
 314 ```yml
 315 calico_ipam_host_local: true
 316 ```
 317
 318 Refer to Project Calico section [Using host-local IPAM](https://docs.projectcalico.org/reference/cni-plugin/configuration#using-host-local-ipam) for further information.
 319
 320 ### Optional : Disable CNI logging to disk
 321
 322 Calico CNI plugin logs to /var/log/calico/cni/cni.log and to stderr.
 323 stderr of CNI plugins can be found in the logs of container runtime.
 324
 325 You can disable Calico CNI logging to disk by setting `calico_cni_log_file_path: false`.
 326
 327 ## eBPF Support
 328
 329 Calico supports eBPF for its data plane see [an introduction to the Calico eBPF Dataplane](https://www.projectcalico.org/introducing-the-calico-ebpf-dataplane/) for further information.
 330
 331 Note that it is advisable to always use the latest version of Calico when using the eBPF dataplane.
 332
 333 ### Enabling eBPF support
 334
 335 To enable the eBPF dataplane support ensure you add the following to your inventory. Note that the `kube-proxy` is incompatible with running Calico in eBPF mode and the kube-proxy should be removed from the system.
 336
 337 ```yaml
 338 calico_bpf_enabled: true
 339 ```
 340
 341 **NOTE:** there is known incompatibility in using the `kernel-kvm` kernel package on Ubuntu OSes because it is missing support for `CONFIG_NET_SCHED` which is a requirement for Calico eBPF support. When using Calico eBPF with Ubuntu ensure you run the `-generic` kernel.
 342
 343 ### Cleaning up after kube-proxy
 344
 345 Calico node cannot clean up after kube-proxy has run in ipvs mode. If you are converting an existing cluster to eBPF you will need to ensure the `kube-proxy` DaemonSet is deleted and that ipvs rules are cleaned.
 346
 347 To check that kube-proxy was running in ipvs mode:
 348
 349 ```ShellSession
 350 # ipvsadm -l
 351 ```
 352
 353 To clean up any ipvs leftovers:
 354
 355 ```ShellSession
 356 # ipvsadm -C
 357 ```
 358
 359 ### Calico access to the kube-api
 360
 361 Calico node, typha and kube-controllers need to be able to talk to the kubernetes API. Please reference the [Enabling eBPF Calico Docs](https://docs.projectcalico.org/maintenance/ebpf/enabling-bpf) for guidelines on how to do this.
 362
 363 Kubespray sets up the `kubernetes-services-endpoint` configmap based on the contents of the `loadbalancer_apiserver` inventory variable documented in [HA Mode](/docs/ha-mode.md).
 364
 365 If no external loadbalancer is used, Calico eBPF can also use the localhost loadbalancer option. In this case Calico Automatic Host Endpoints need to be enabled to allow services like `coredns` and `metrics-server` to communicate with the kubernetes host endpoint. See [this blog post](https://www.projectcalico.org/securing-kubernetes-nodes-with-calico-automatic-host-endpoints/) on enabling automatic host endpoints.
 366
 367 ```yaml
 368 loadbalancer_apiserver_localhost: true
 369 use_localhost_as_kubeapi_loadbalancer: true
 370 ```
 371
 372 ### Tunneled versus Direct Server Return
 373
 374 By default Calico usese Tunneled service mode but it can use direct server return (DSR) in order to optimize the return path for a service.
 375
 376 To configure DSR:
 377
 378 ```yaml
 379 calico_bpf_service_mode: "DSR"
 380 ```
 381
 382 ### eBPF Logging and Troubleshooting
 383
 384 In order to enable Calico eBPF mode logging:
 385
 386 ```yaml
 387 calico_bpf_log_level: "Debug"
 388 ```
 389
 390 To view the logs you need to use the `tc` command to read the kernel trace buffer:
 391
 392 ```ShellSession
 393 tc exec bpf debug
 394 ```
 395
 396 Please see [Calico eBPF troubleshooting guide](https://docs.projectcalico.org/maintenance/troubleshoot/troubleshoot-ebpf#ebpf-program-debug-logs).
 397
 398 ## Wireguard Encryption
 399
 400 Calico supports using Wireguard for encryption. Please see the docs on [encryptiong cluster pod traffic](https://docs.projectcalico.org/security/encrypt-cluster-pod-traffic).
 401
 402 To enable wireguard support:
 403
 404 ```yaml
 405 calico_wireguard_enabled: true
 406 ```
 407
 408 The following OSes will require enabling the EPEL repo in order to bring in wireguard tools:
 409
 410 * CentOS 7 & 8
 411 * AlmaLinux 8
 412 * Rocky Linux 8
 413 * Amazon Linux 2
 414
 415 ```yaml
 416 epel_enabled: true
 417 ```