Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCS-2416: Rewrites OSS system requirements for Kubernetes as plain MDX #1830

Merged
merged 1 commit into from
Jan 6, 2025
Merged

DOCS-2416: Rewrites OSS system requirements for Kubernetes as plain MDX #1830

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 90 additions & 5 deletions calico/getting-started/kubernetes/requirements.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,78 @@
description: Review requirements before installing Calico to ensure success.
---

import ReqsSys from '@site/calico/_includes/components/ReqsSys';
import ReqsKernel from '@site/calico/_includes/components/ReqsKernel';

# System requirements

<ReqsSys orch='Kubernetes' />
## Node requirements

* x86-64, arm64, ppc64le, or s390x processor

* Calico must be able to manage `cali*` interfaces on the host.
When IPIP is enabled (the default), Calico also needs to be able to manage `tunl*` interfaces.
When VXLAN is enabled, Calico also needs to be able to manage the `vxlan.calico` interface.

* Linux kernel 3.10 or later with [required dependencies](#kernel-dependencies). The following distributions have the required kernel, its dependencies, and are known to work well with Calico and Kubernetes.
* RedHat Linux 7
* CentOS 7
* Flatcar Container Linux
* Fedora CoreOS
* Ubuntu 18.04
* Debian 8
Comment on lines +15 to +21
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to update this minimum requirement list as most distros are eol'ed and kernel 3.x maybe too old for some Calico feature to work.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, there are A LOT of updates that need to happen. This PR is the first step on a path to overhauling the system requirements.

I'll be in touch to talk specifics in the coming weeks.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Here, I'm just changing the way we build the page. No substantive changes to the content.)


:::note

Many Linux distributions, such as most of the above, include NetworkManager.
By default, NetworkManager does not allow Calico to manage interfaces.
If your nodes have NetworkManager, complete the steps in [Preventing NetworkManager from controlling Calico interfaces](../../operations/troubleshoot/troubleshooting.mdx#configure-networkmanager) before installing Calico.

:::

* If your Linux distribution comes with installed Firewalld or another iptables manager it should be disabled.
These may interfere with rules added by Calico and result in unexpected behavior.

:::note

If a host firewall is needed, it can be configured by Calico HostEndpoint and GlobalNetworkPolicy.
More information about configuration at Security for host.

:::

## Key/value store

Calico requires a key/value store accessible by all Calico components.
On Kubernetes, you can configure Calico to access an etcdv3 cluster directly or to use the Kubernetes API datastore.

## Network requirements

Ensure that your hosts and firewalls allow the necessary traffic based on your configuration.

| Configuration | Host(s) | Connection Type | Port/Protocol |
|---------------------------------------------------|----------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------|
| Calico networking (BGP) | All | Bidirectional | TCP 179 |
| Calico networking with IP-in-IP enabled (default) | All | Bidirectional | IP-in-IP, often represented by its protocol number `4` |
| Calico networking with VXLAN enabled | All | Bidirectional | UDP 4789 |
| Calico networking with Typha enabled | Typha agent hosts | Incoming | TCP 5473 (default) |
| Calico networking with IPv4 Wireguard enabled | All | Bidirectional | UDP 51820 (default) |
| Calico networking with IPv6 Wireguard enabled | All | Bidirectional | UDP 51821 (default) |
| flannel networking (VXLAN) | All | Bidirectional | UDP 4789 |
| All | kube-apiserver hosts | Incoming | Often TCP 443 or 6443\* |
| etcd datastore | etcd hosts | Incoming | [Officially](http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt) TCP 2379 but can vary |

\* *The value passed to kube-apiserver using the `--secure-port` flag.
If you cannot locate this, check the `targetPort` value returned by `kubectl get svc kubernetes -o yaml`.*

## Privileges

Ensure that Calico has the `CAP_SYS_ADMIN` privilege.

The simplest way to provide the necessary privilege is to run Calico as root or in a privileged container.

When installed as a Kubernetes daemon set, Calico meets this requirement by running as a privileged container.
This requires that the kubelet be allowed to run privileged containers.
There are two ways this can be achieved.

* Specify `--allow-privileged` on the kubelet (deprecated).
* Use a pod security policy.

## Kubernetes requirements

Expand Down Expand Up @@ -66,4 +132,23 @@ Note that Kubernetes version 1.16+ requires Istio version 1.2 or greater.
Note that Istio version 1.9 requires Kubernetes version 1.17-1.20.
Note that Istio version 1.10 is supported on Kubernetes version 1.18-1.21, but has been tested on Kubernetes version 1.22.

<ReqsKernel />
## Kernel Dependencies

:::tip

If you are using one of the recommended distributions, you will already satisfy these.

:::

Due to the large number of distributions and kernel version out there, it’s hard to be precise about the names of the particular kernel modules that are required to run Calico.
However, in general, you’ll need:

* The `iptables` modules (both the “legacy” and “nft” variants are supported). These are typically broken up into many small modules, one for each type of match criteria and one for each type of action. Calico requires:
* The “base” modules (including the IPv6 versions if IPv6 is enabled in your cluster).
* At least the following match criteria: `set`, `rpfilter`, `addrtype`, `comment`, `conntrack`, `icmp`, `tcp`, `udp`, `ipvs`, `icmpv6` (if IPv6 is enabled in your kernel), `mark`, `multiport`, `rpfilter`, `sctp`, `ipvs` (if using `kube-proxy` in IPVS mode).
* At least the following actions: `REJECT`, `ACCEPT`, `DROP`, `LOG`.
* IP sets support.
* Netfilter Conntrack support compiled in (with SCTP support if using SCTP).
* IPVS support if using `kube-proxy` in IPVS mode.
* IPIP, VXLAN, Wireguard support, if using Calico networking in one of those modes.
* eBPF (including the `tc` hook support) and XDP (if you want to use the eBPF dataplane).
95 changes: 90 additions & 5 deletions calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,78 @@
description: Review requirements before installing Calico to ensure success.
---

import ReqsSys from '@site/calico_versioned_docs/version-3.29/_includes/components/ReqsSys';
import ReqsKernel from '@site/calico_versioned_docs/version-3.29/_includes/components/ReqsKernel';

# System requirements

<ReqsSys orch='Kubernetes' />
## Node requirements

* x86-64, arm64, ppc64le, or s390x processor

* Calico must be able to manage `cali*` interfaces on the host.
When IPIP is enabled (the default), Calico also needs to be able to manage `tunl*` interfaces.
When VXLAN is enabled, Calico also needs to be able to manage the `vxlan.calico` interface.

* Linux kernel 3.10 or later with [required dependencies](#kernel-dependencies). The following distributions have the required kernel, its dependencies, and are known to work well with Calico and Kubernetes.
* RedHat Linux 7
* CentOS 7
* Flatcar Container Linux
* Fedora CoreOS
* Ubuntu 18.04
* Debian 8

:::note

Many Linux distributions, such as most of the above, include NetworkManager.
By default, NetworkManager does not allow Calico to manage interfaces.
If your nodes have NetworkManager, complete the steps in [Preventing NetworkManager from controlling Calico interfaces](../../operations/troubleshoot/troubleshooting.mdx#configure-networkmanager) before installing Calico.

:::

* If your Linux distribution comes with installed Firewalld or another iptables manager it should be disabled.

Check failure on line 31 in calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Firewalld'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Firewalld'?", "location": {"path": "calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx", "range": {"start": {"line": 31, "column": 51}}}, "severity": "ERROR"}
These may interfere with rules added by Calico and result in unexpected behavior.

:::note

If a host firewall is needed, it can be configured by Calico HostEndpoint and GlobalNetworkPolicy.
More information about configuration at [Policy for hosts and VMs](../../network-policy/hosts/index.mdx).

:::

## Key/value store

Calico requires a key/value store accessible by all Calico components.
On Kubernetes, you can configure Calico to access an etcdv3 cluster directly or to use the Kubernetes API datastore.

Check failure on line 44 in calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'datastore'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'datastore'?", "location": {"path": "calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx", "range": {"start": {"line": 44, "column": 107}}}, "severity": "ERROR"}

## Network requirements

Ensure that your hosts and firewalls allow the necessary traffic based on your configuration.

| Configuration | Host(s) | Connection Type | Port/Protocol |
|---------------------------------------------------|----------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------|
| Calico networking (BGP) | All | Bidirectional | TCP 179 |
| Calico networking with IP-in-IP enabled (default) | All | Bidirectional | IP-in-IP, often represented by its protocol number `4` |
| Calico networking with VXLAN enabled | All | Bidirectional | UDP 4789 |
| Calico networking with Typha enabled | Typha agent hosts | Incoming | TCP 5473 (default) |
| Calico networking with IPv4 Wireguard enabled | All | Bidirectional | UDP 51820 (default) |

Check failure on line 56 in calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Wireguard'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Wireguard'?", "location": {"path": "calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx", "range": {"start": {"line": 56, "column": 31}}}, "severity": "ERROR"}
| Calico networking with IPv6 Wireguard enabled | All | Bidirectional | UDP 51821 (default) |

Check failure on line 57 in calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Wireguard'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Wireguard'?", "location": {"path": "calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx", "range": {"start": {"line": 57, "column": 31}}}, "severity": "ERROR"}
| flannel networking (VXLAN) | All | Bidirectional | UDP 4789 |
| All | kube-apiserver hosts | Incoming | Often TCP 443 or 6443\* |
| etcd datastore | etcd hosts | Incoming | [Officially](http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt) TCP 2379 but can vary |

Check failure on line 60 in calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'datastore'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'datastore'?", "location": {"path": "calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx", "range": {"start": {"line": 60, "column": 8}}}, "severity": "ERROR"}

\* *The value passed to kube-apiserver using the `--secure-port` flag.
If you cannot locate this, check the `targetPort` value returned by `kubectl get svc kubernetes -o yaml`.*

## Privileges

Ensure that Calico has the `CAP_SYS_ADMIN` privilege.

The simplest way to provide the necessary privilege is to run Calico as root or in a privileged container.

When installed as a Kubernetes daemon set, Calico meets this requirement by running as a privileged container.
This requires that the kubelet be allowed to run privileged containers.
There are two ways this can be achieved.

* Specify `--allow-privileged` on the kubelet (deprecated).
* Use a [pod security policy](https://kubernetes.io/docs/concepts/policy/pod-security-policy/).

## Kubernetes requirements

Expand Down Expand Up @@ -66,4 +132,23 @@
Note that Istio version 1.9 requires Kubernetes version 1.17-1.20.
Note that Istio version 1.10 is supported on Kubernetes version 1.18-1.21, but has been tested on Kubernetes version 1.22.

<ReqsKernel />
## Kernel Dependencies

:::tip

If you are using one of the recommended distributions, you will already satisfy these.

:::

Due to the large number of distributions and kernel version out there, it’s hard to be precise about the names of the particular kernel modules that are required to run Calico.
However, in general, you’ll need:

* The `iptables` modules (both the “legacy” and “nft” variants are supported). These are typically broken up into many small modules, one for each type of match criteria and one for each type of action. Calico requires:

Check failure on line 146 in calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'nft'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'nft'?", "location": {"path": "calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx", "range": {"start": {"line": 146, "column": 50}}}, "severity": "ERROR"}
* The “base” modules (including the IPv6 versions if IPv6 is enabled in your cluster).
* At least the following match criteria: `set`, `rpfilter`, `addrtype`, `comment`, `conntrack`, `icmp`, `tcp`, `udp`, `ipvs`, `icmpv6` (if IPv6 is enabled in your kernel), `mark`, `multiport`, `rpfilter`, `sctp`, `ipvs` (if using `kube-proxy` in IPVS mode).
* At least the following actions: `REJECT`, `ACCEPT`, `DROP`, `LOG`.
* IP sets support.
* Netfilter Conntrack support compiled in (with SCTP support if using SCTP).

Check failure on line 151 in calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Netfilter'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Netfilter'?", "location": {"path": "calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx", "range": {"start": {"line": 151, "column": 3}}}, "severity": "ERROR"}

Check failure on line 151 in calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Conntrack'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Conntrack'?", "location": {"path": "calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx", "range": {"start": {"line": 151, "column": 13}}}, "severity": "ERROR"}
* IPVS support if using `kube-proxy` in IPVS mode.
* IPIP, VXLAN, Wireguard support, if using Calico networking in one of those modes.

Check failure on line 153 in calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Wireguard'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Wireguard'?", "location": {"path": "calico_versioned_docs/version-3.29/getting-started/kubernetes/requirements.mdx", "range": {"start": {"line": 153, "column": 16}}}, "severity": "ERROR"}
* eBPF (including the `tc` hook support) and XDP (if you want to use the eBPF dataplane).
Loading