Use a specific IP address with a pod

Big picture

Choose the IP address for a pod instead of allowing Calico to choose automatically.

Value

Some applications require the use of stable IP addresses. Also, you may want to create entries in external DNS servers that point directly to pods, and this requires static IPs.

Concepts

Kubernetes pod CIDR

The Kubernetes pod CIDR is the range of IPs Kubernetes expects pod IPs to be assigned from. It is defined for the entire cluster and is used by various Kubernetes components to determine whether an IP belongs to a pod. For example, kube-proxy treats traffic differently if an IP is from a pod than if it is not. All pod IPs must be in the CIDR range for Kubernetes to function correctly.

IP Pools

IP pools are ranges of IP addresses from which Calico assigns pod IPs. Static IPs must be in an IP pool.

Before you begin…

Your cluster must be using Calico IPAM to use this feature.

If you are not sure which IPAM your cluster is using, the way to tell depends on install method.

  • Operator
  • Manifest

The IPAM plugin can be queried on the default Installation resource.

  1. kubectl get installation default -o go-template --template {{.spec.cni.ipam.type}}

If your cluster is using Calico IPAM, the above command should return a result of Calico.

SSH to one of your Kubernetes nodes and examine the CNI configuration.

  1. cat /etc/cni/net.d/10-calico.conflist

Look for the entry:

  1.          "ipam": {
  2.               "type": "calico-ipam"
  3.           },

If it is present, you are using the Calico IPAM. If the IPAM is not Calico, or the 10-calico.conflist file does not exist, you cannot use these features in your cluster.

How to

Annotate the pod with cni.projectcalico.org/ipAddrs set to a list of IP addresses to assign, enclosed in brackets. For example:

  1.   "cni.projectcalico.org/ipAddrs": "[\"192.168.0.1\"]"

Note the use of the escaped \" for the inner double quotes around the addresses.

The address must be within a configured Calico IP pool and not currently in use. The annotation must be present when the pod is created; adding it later has no effect.

Note that currently only a single IP address is supported per-pod using this annotation.

Reserving IPs for manual assignments

The cni.projectcalico.org/ipAddrs annotation requires the IP address to be within an IP pool. This means that, by default, Calico may decide to use the IP address that you select for another workload or for an internal tunnel address. To prevent this, there are several options:

  • To reserve a whole IPPool for manual allocations, you can set its node selector to "!all()". Since the !all()
    cannot match any nodes, the IPPool will not be used for any automatic assignments.

  • To reserve part of a pool, you can create an IPReservation resource. This allows for certain IPs to be reserved so that Calico IPAM will not use them automatically. However, manual assignments (using the annotation) can still use IPs that are “reserved”.

  • To prevent Calico from using IPs from a certain pool for internal IPIP and/or VXLAN tunnel addresses, you can set the allowedUses field on the IPPool to ["Workload"].

Additional resources

For help configuring Calico CNI and Calico IPAM, see Configuring the Calico CNI Plugins.