Install Calico for policy and flannel (aka Canal) for networking
Before you begin
Note: Calico includes native VXLAN capabilities without the need for flannel. If you’re planning on using flannel for VXLAN, we recommend instead installing Calico using IP-in-IP or VXLAN mode. See how to determine the best networking option for your cluster. If you’re already using flannel for networking, you can migrate your existing clusters to Calico networking.
Ensure that you have a Kubernetes cluster that meets the Calico system requirements. If you don’t, follow the steps in Installing kubeadm.
Installing Calico for policy and flannel (aka Canal) for networking
Selecting a datastore type
The procedure differs according to your datastore type. Refer to the section that matches your type.
-
Kubernetes API datastore (recommended)
Installing with the Kubernetes API datastore (recommended)
-
Ensure that the Kubernetes controller manager has the following flags set:
--cluster-cidr=<your-pod-cidr>
and--allocate-node-cidrs=true
.Tip: On kubeadm, you can pass
--pod-network-cidr=<your-pod-cidr>
to kubeadm to set both Kubernetes controller flags. -
Download the flannel networking manifest for the Kubernetes API datastore.
curl https://raw.githubusercontent.com/projectcalico/calico/v3.25.0/manifests/canal.yaml -O
-
If you are using pod CIDR
10.244.0.0/16
, skip to the next step. If you are using a different pod CIDR with kubeadm, no changes are required - Calico will automatically detect the CIDR based on the running configuration. For other platforms, make sure you uncomment the CALICO_IPV4POOL_CIDR variable in the manifest and set it to the same value as your chosen pod CIDR. -
Issue the following command to install Calico.
kubectl apply -f canal.yaml
-
If you wish to enforce application layer policies and secure workload-to-workload communications with mutual TLS authentication, continue to Enable application layer policy (optional).
The geeky details of what you get:
Kubernetes network policies are implemented by network plugins rather than Kubernetes itself. Simply creating a network policy resource without a network plugin to implement it, will have no effect on network traffic.
The Calico plugin implements the full set of Kubernetes network policy features. In addition, Calico supports Calico network policies, providing additional features and capabilities beyond Kubernetes network policies. Kubernetes and Calico network policies work together seamlessly, so you can choose whichever is right for you, and mix and match as desired.
How Kubernetes assigns IP address to pods is determined by the IPAM (IP Address Management) plugin being used.
The Host-local IPAM plugin allocates a static range of IP addresses for each node at node creation time. The pods on each node are then allocated IP addresses from within each node’s static range.
By default, the static range is a /24 (256 IP addresses).
For most deployments, Host-local IPAM is a simple and adequate solution. However, using a static address range per node typically means less efficient use of the available IP address space. If you are running particularly large clusters, or have other significant enterprise address space demands, then it may be worth considering Calico IPAM as an alternative to provide more efficient address space management.
The CNI (Container Network Interface) plugin being used by Kubernetes determines the details of exactly how pods are connected to the underlying network.
The Calico CNI plugin connects pods to the host networking using L3 routing, without the need for an L2 bridge. This is simple and easy to understand, and more efficient than other common alternatives such as kubenet or flannel.
An overlay network allows pods to communicate between nodes without the underlying network being aware of the pods or pod IP addresses.
Packets between pods on different nodes are encapsulated using VXLAN, wrapping each original packet in an outer packet that uses node IPs, and hiding the pod IPs of the inner packet. This can be done very efficiently by the Linux kernel, but it still represents a small overhead, which you might want to avoid if running particularly network intensive workloads.
For completeness, in contrast, operating without using an overlay provides the highest performance network. The packets that leave your pods are the packets that go on the wire.
Static routes are used to route pod traffic between nodes. The static routes are typically added to the host, and if required, the underlying network, by the installation framework used to create the Kubernetes deployment. Static routes are usually used in conjunction with the Host-local IPAM plugin, which statically assigns a /24 pod IP address range per node.
Calico stores the operational and configuration state of your cluster in a central datastore. If the datastore is unavailable, your Calico network continues operating, but cannot be updated (no new pods can be networked, no policy changes can be applied, etc.).
Calico has two datastore drivers you can choose from
- etcd - for direct connection to an etcd cluster
- Kubernetes - for connection to a Kubernetes API server
The advantages of using Kubernetes as the datastore are:
- It doesn’t require an extra datastore, so is simpler to install and manage
- You can use Kubernetes RBAC to control access to Calico resources
- You can use Kubernetes audit logging to generate audit logs of changes to Calico resources
For completeness, the advantages of using etcd as the datastore are:
- Allows you to run Calico on non-Kubernetes platforms (e.g. OpenStack)
- Allows separation of concerns between Kubernetes and Calico resources, for example allowing you to scale the datastores independently
- Allows you to run a Calico cluster that contains more than just a single Kubernetes cluster, for example, bare metal servers with Calico host protection interworking with a Kubernetes cluster or multiple Kubernetes clusters.
Calico’s flexible modular architecture supports a wide range of deployment options, so you can select the best networking and network policy options for your specific environment. This includes the ability to run with a variety of CNI and IPAM plugins, and underlying networking options.
The Calico Getting Started guides default to the options most commonly used in each environment, so you don’t have to dive into the details unless you want to.
You can click on any deployment option to learn more.
Installing with the etcd datastore
We strongly recommend using the Kubernetes API datastore, but if you prefer to use etcd, complete the following steps.
-
Download the Calico networking manifest.
curl https://raw.githubusercontent.com/projectcalico/calico/v3.25.0/manifests/canal-etcd.yaml -O
-
If you are using pod CIDR
10.244.0.0/16
, skip to the next step. If you are using a different pod CIDR with kubeadm, no changes are required - Calico will automatically detect the CIDR based on the running configuration. For other platforms, make sure you uncomment the CALICO_IPV4POOL_CIDR variable in the manifest and set it to the same value as your chosen pod CIDR. -
In the
ConfigMap
namedcalico-config
, set the value ofetcd_endpoints
to the IP address and port of your etcd server.Tip: You can specify more than one using commas as delimiters.
-
Apply the manifest using the following command.
kubectl apply -f canal-etcd.yaml
-
If you wish to enforce application layer policies and secure workload-to-workload communications with mutual TLS authentication, continue to Enable application layer policy (optional).
The geeky details of what you get:
Kubernetes network policies are implemented by network plugins rather than Kubernetes itself. Simply creating a network policy resource without a network plugin to implement it, will have no effect on network traffic.
The Calico plugin implements the full set of Kubernetes network policy features. In addition, Calico supports Calico network policies, providing additional features and capabilities beyond Kubernetes network policies. Kubernetes and Calico network policies work together seamlessly, so you can choose whichever is right for you, and mix and match as desired.
How Kubernetes assigns IP address to pods is determined by the IPAM (IP Address Management) plugin being used.
The Host-local IPAM plugin allocates a static range of IP addresses for each node at node creation time. The pods on each node are then allocated IP addresses from within each node’s static range.
By default, the static range is a /24 (256 IP addresses).
For most deployments, Host-local IPAM is a simple and adequate solution. However, using a static address range per node typically means less efficient use of the available IP address space. If you are running particularly large clusters, or have other significant enterprise address space demands, then it may be worth considering Calico IPAM as an alternative to provide more efficient address space management.
The CNI (Container Network Interface) plugin being used by Kubernetes determines the details of exactly how pods are connected to the underlying network.
The Calico CNI plugin connects pods to the host networking using L3 routing, without the need for an L2 bridge. This is simple and easy to understand, and more efficient than other common alternatives such as kubenet or flannel.
An overlay network allows pods to communicate between nodes without the underlying network being aware of the pods or pod IP addresses.
Packets between pods on different nodes are encapsulated using VXLAN, wrapping each original packet in an outer packet that uses node IPs, and hiding the pod IPs of the inner packet. This can be done very efficiently by the Linux kernel, but it still represents a small overhead, which you might want to avoid if running particularly network intensive workloads.
For completeness, in contrast, operating without using an overlay provides the highest performance network. The packets that leave your pods are the packets that go on the wire.
Static routes are used to route pod traffic between nodes. The static routes are typically added to the host, and if required, the underlying network, by the installation framework used to create the Kubernetes deployment. Static routes are usually used in conjunction with the Host-local IPAM plugin, which statically assigns a /24 pod IP address range per node.
Calico stores the operational and configuration state of your cluster in a central datastore. If the datastore is unavailable, your Calico network continues operating, but cannot be updated (no new pods can be networked, no policy changes can be applied, etc.).
Calico has two datastore drivers you can choose from:
- etcd - for direct connection to an etcd cluster
- Kubernetes - for connection to a Kubernetes API server
The advantages of using etcd as the datastore are:
- Allows you to run Calico on non-Kubernetes platforms (e.g. OpenStack)
- Allows separation of concerns between Kubernetes and Calico resources, for example allowing you to scale the datastores independently
- Allows you to run a Calico cluster that contains more than just a single Kubernetes cluster, for example, bare metal servers with Calico host protection interworking with a Kubernetes cluster or multiple Kubernetes clusters.
For completeness, the advantages of using Kubernetes as the datastore are:
- It doesn’t require an extra datastore, so is simpler to install and manage
- You can use Kubernetes RBAC to control access to Calico resources
- You can use Kubernetes audit logging to generate audit logs of changes to Calico resources.
Calico’s flexible modular architecture supports a wide range of deployment options, so you can select the best networking and network policy options for your specific environment. This includes the ability to run with a variety of CNI and IPAM plugins, and underlying networking options.
The Calico Getting Started guides default to the options most commonly used in each environment, so you don’t have to dive into the details unless you want to.
You can click on any deployment option to learn more.