Skip to content

docs: update Calico installation docs #11993

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

Closed
wants to merge 1 commit into from
Closed

docs: update Calico installation docs #11993

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
106 changes: 49 additions & 57 deletions website/content/v1.11/kubernetes-guides/network/deploying-calico.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,14 +39,48 @@ kubectl create -f https://docs.tigera.io/calico/latest/manifests/tigera-operator

### Configuring Calico Networking

Calico has a pluggable dataplane architecture that lets you choose the networking technology based on your use case. You can configure the dataplane by setting the `linuxDataplane` key in the installation manifest.
Calico has a pluggable dataplane architecture that lets you choose the networking technology based on your use case. Networking technology is the backend that allows your nodes to move a packet from a source or destination to your Kubernetes resources.

> **Note** If you like to learn more about the available Calico configurations [checkout this document](https://docs.tigera.io/calico/latest/reference/installation/api).

{{< tabpane text=true >}}
{{% tab header="NFTables" %}}

> **Note**: Calico also supports iptables backend, if you wish to run Calico in iptables mode change `linuxdataplane` value to `Iptables`.
Copy link
Contributor Author

@frozenprocess frozenprocess Oct 9, 2025

Choose a reason for hiding this comment

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

@james-callahan WDYT? I think this should be a bit more clear that I'm not suggesting what you should pick.

Copy link
Contributor

@james-callahan james-callahan Oct 9, 2025

Choose a reason for hiding this comment

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

Yeah that's fine.

As a side note, you might want to point out that you don't have to use the tigera-operator (we don't)


Use the following command to run Calico with NFTables backend.

```bash
kubectl create -f -<<EOF
# This section includes base Calico installation configuration.
apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
name: default
spec:
calicoNetwork:
bgp: Disabled
linuxDataplane: Nftables
ipPools:
- name: default-ipv4-ippool
blockSize: 26
cidr: 10.244.0.0/16
encapsulation: VXLAN
natOutgoing: Enabled
nodeSelector: all()
kubeletVolumePluginPath: None
---
apiVersion: operator.tigera.io/v1
kind: APIServer
metadata:
name: default
EOF
```

{{% /tab %}}
{{% tab header="eBPF" %}}

By default, Calico uses the `/var` directory to mount cgroups. However, since this path is not writable in Talos, you need to change it to `/sys/fs/cgroup`.
By default, Calico uses the `/var` directory to mount cgroups. However, since this path is not writable in Talos Linux, you need to change it to `/sys/fs/cgroup`.
Copy link
Contributor

@james-callahan james-callahan Oct 9, 2025

Choose a reason for hiding this comment

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

if using eBPF mode.

Also might want to prefix this section and point out that eBPF mode has downsides+doesn't work everywhere. e.g. it doesn't support all architectures


Use the following command to update the cgroup mount path:

Expand All @@ -61,28 +95,21 @@ spec:
EOF
```

> **Note** If you’d like to learn more about the available Calico configurations, [checkout this document](https://docs.tigera.io/calico/latest/reference/installation/api).

In eBPF mode, Calico completely replaces the need for kube-proxy by programming all networking logic via eBPF programs. Before disabling kube-proxy, however, you need to ensure that Calico components can reach the API server. This can be done by creating a `kubernetes-services-endpoint` ConfigMap.

Store the following YAML template in a file (e.g., `endpoint.yaml`), and replace <API server host> and <API server port> with your Kubernetes API server host and port.
If [KubePrism]({{< relref "../configuration/kubeprism" >}}) is enabled (which is the default), use `localhost` as the API server host and `7445` as the port.
> **Note**: In this part we assume you are using [KubePrism]({{< relref "../configuration/kubeprism" >}}) (which is enabled by the default).

```yaml
```bash
kubectl create -f -<<EOF
kind: ConfigMap
apiVersion: v1
metadata:
name: kubernetes-services-endpoint
namespace: tigera-operator
data:
KUBERNETES_SERVICE_HOST: '<API server host>'
KUBERNETES_SERVICE_PORT: '<API server port>'
```

After editing the file, apply it using:

```bash
kubectl create -f endpoint.yaml
KUBERNETES_SERVICE_HOST: 'localhost'
KUBERNETES_SERVICE_PORT: '7445'
EOF
```

You can now safely disable `kube-proxy` by using the following command:
Expand All @@ -104,49 +131,14 @@ spec:
calicoNetwork:
bgp: Disabled
linuxDataplane: BPF
cni:
ipam:
type: HostLocal
type: Calico
kubeletVolumePluginPath: None
---
# Kubectl integration for Calico unique resources.
Copy link
Contributor Author

@frozenprocess frozenprocess Oct 9, 2025

Choose a reason for hiding this comment

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

@smira I removed API server since I found a bug (not talos related) with it when using kubeprsim IP. I'll have another update later to include it but for now it is safe to remove it.

Copy link
Contributor

@james-callahan james-callahan Oct 9, 2025

Choose a reason for hiding this comment

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

Out of curiousity, what's the bug? (I'm currently debugging something related to calico and talking to api server right now; so maybe you found it!)

apiVersion: operator.tigera.io/v1
kind: APIServer
metadata:
name: default
spec: {}
EOF
```

{{% /tab %}}
{{% tab header="NFTables" %}}

Use the following command to run Calico with NFTables backend.

```bash
kubectl create -f -<<EOF
# This section includes base Calico installation configuration.
apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
name: default
spec:
calicoNetwork:
bgp: Disabled
linuxDataplane: Nftables
cni:
ipam:
type: HostLocal
type: Calico
ipPools:
- name: default-ipv4-ippool
blockSize: 26
cidr: 10.244.0.0/16
Copy link
Contributor

@james-callahan james-callahan Oct 9, 2025

Choose a reason for hiding this comment

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

This cidr block came out of nowhere: should mention how to pick it

encapsulation: VXLAN
natOutgoing: Enabled
nodeSelector: all()
kubeletVolumePluginPath: None
---
# Kubectl integration for Calico unique resources.
apiVersion: operator.tigera.io/v1
kind: APIServer
metadata:
name: default
spec: {}
EOF
```

Expand Down
106 changes: 49 additions & 57 deletions website/content/v1.12/kubernetes-guides/network/deploying-calico.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,14 +39,48 @@ kubectl create -f https://docs.tigera.io/calico/latest/manifests/tigera-operator

### Configuring Calico Networking

Calico has a pluggable dataplane architecture that lets you choose the networking technology based on your use case. You can configure the dataplane by setting the `linuxDataplane` key in the installation manifest.
Calico has a pluggable dataplane architecture that lets you choose the networking technology based on your use case. Networking technology is the backend that allows your nodes to move a packet from a source or destination to your Kubernetes resources.

> **Note** If you like to learn more about the available Calico configurations [checkout this document](https://docs.tigera.io/calico/latest/reference/installation/api).

{{< tabpane text=true >}}
{{% tab header="NFTables" %}}

> **Note**: Calico also supports iptables backend, if you wish to run Calico in iptables mode change `linuxdataplane` value to `Iptables`.

Use the following command to run Calico with NFTables backend.

```bash
kubectl create -f -<<EOF
# This section includes base Calico installation configuration.
apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
name: default
spec:
calicoNetwork:
bgp: Disabled
linuxDataplane: Nftables
ipPools:
- name: default-ipv4-ippool
blockSize: 26
cidr: 10.244.0.0/16
encapsulation: VXLAN
natOutgoing: Enabled
nodeSelector: all()
kubeletVolumePluginPath: None
---
apiVersion: operator.tigera.io/v1
kind: APIServer
metadata:
name: default
EOF
```

{{% /tab %}}
{{% tab header="eBPF" %}}

By default, Calico uses the `/var` directory to mount cgroups. However, since this path is not writable in Talos, you need to change it to `/sys/fs/cgroup`.
By default, Calico uses the `/var` directory to mount cgroups. However, since this path is not writable in Talos Linux, you need to change it to `/sys/fs/cgroup`.

Use the following command to update the cgroup mount path:

Expand All @@ -61,28 +95,21 @@ spec:
EOF
```

> **Note** If you’d like to learn more about the available Calico configurations, [checkout this document](https://docs.tigera.io/calico/latest/reference/installation/api).

In eBPF mode, Calico completely replaces the need for kube-proxy by programming all networking logic via eBPF programs. Before disabling kube-proxy, however, you need to ensure that Calico components can reach the API server. This can be done by creating a `kubernetes-services-endpoint` ConfigMap.

Store the following YAML template in a file (e.g., `endpoint.yaml`), and replace <API server host> and <API server port> with your Kubernetes API server host and port.
If [KubePrism]({{< relref "../configuration/kubeprism" >}}) is enabled (which is the default), use `localhost` as the API server host and `7445` as the port.
> **Note**: In this part we assume you are using [KubePrism]({{< relref "../configuration/kubeprism" >}}) (which is enabled by the default).

```yaml
```bash
kubectl create -f -<<EOF
kind: ConfigMap
apiVersion: v1
metadata:
name: kubernetes-services-endpoint
namespace: tigera-operator
data:
KUBERNETES_SERVICE_HOST: '<API server host>'
KUBERNETES_SERVICE_PORT: '<API server port>'
```

After editing the file, apply it using:

```bash
kubectl create -f endpoint.yaml
KUBERNETES_SERVICE_HOST: 'localhost'
KUBERNETES_SERVICE_PORT: '7445'
EOF
```

You can now safely disable `kube-proxy` by using the following command:
Expand All @@ -104,49 +131,14 @@ spec:
calicoNetwork:
bgp: Disabled
linuxDataplane: BPF
cni:
ipam:
type: HostLocal
type: Calico
kubeletVolumePluginPath: None
---
# Kubectl integration for Calico unique resources.
apiVersion: operator.tigera.io/v1
kind: APIServer
metadata:
name: default
spec: {}
EOF
```

{{% /tab %}}
{{% tab header="NFTables" %}}

Use the following command to run Calico with NFTables backend.

```bash
kubectl create -f -<<EOF
# This section includes base Calico installation configuration.
apiVersion: operator.tigera.io/v1
kind: Installation
metadata:
name: default
spec:
calicoNetwork:
bgp: Disabled
linuxDataplane: Nftables
cni:
ipam:
type: HostLocal
type: Calico
ipPools:
- name: default-ipv4-ippool
blockSize: 26
cidr: 10.244.0.0/16
encapsulation: VXLAN
natOutgoing: Enabled
nodeSelector: all()
kubeletVolumePluginPath: None
---
# Kubectl integration for Calico unique resources.
apiVersion: operator.tigera.io/v1
kind: APIServer
metadata:
name: default
spec: {}
EOF
```

Expand Down