Restrict a pod to use an IP address in a specific range

Big picture

Restrict the IP address chosen for a pod to a specific range of IP addresses.

Value

When Kubernetes pods interact with external systems that make decisions based on IP ranges (for example legacy firewalls), it can be useful to define several IP ranges and explicitly assign pods to those ranges. Using Calico IP Address Management (IPAM), you can restrict a pod to use an address from within a specific range.

Features

This how-to guide uses the following features:

  • Calico IPAM
  • IPPool resource

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 that traffic is from a pod than if it is not. All pod IPs must be in the CIDR range for Kubernetes to function correctly.

IP Pool

IP pools are ranges of IP addresses from which Calico assigns pod IPs. By default, Calico creates an IP pool for the entire Kubernetes pod CIDR, but you can change this to break the pod CIDR up into several pools. You can control which pool Calico uses for each pod using node selectors, or annotations on the pod or the pod’s namespace.

Before you begin…

The features in this How to guide require:

  • Calico IPAM

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.

Additionally, cluster administrators must have configured IP pools to define the valid IP ranges to use for allocating pod IP addresses.

How to

Restrict a pod to use an IP address range

Annotate the pod with key cni.projectcalico.org/ipv4pools and/or cni.projectcalico.org/ipv6pools and value set to a list of IP pool names, enclosed in brackets. For example:

  1. cni.projectcalico.org/ipv4pools: '["pool-1", "pool-2"]'

Note the use of the escaped \“ for the inner double quotes around the pool names.

Restrict all pods within a namespace to use an IP address range

Annotate the namespace with key cni.projectcalico.org/ipv4pools and/or cni.projectcalico.org/ipv6pools and value set to a list of IP pool names, enclosed in brackets. For example:

  1. cni.projectcalico.org/ipv4pools: '["pool-1", "pool-2"]'

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

If both the pod and the pod’s namespace have the annotation, the pod annotation takes precedence.

The annotation must be present at the time the pod is created. Adding it to an existing pod has no effect.

Additional resources

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