IP pool
An IP pool resource (IPPool
) represents a collection of IP addresses from which Calico Enterprise expects
endpoint IPs to be assigned.
For kubectl
commands, the following case-insensitive aliases may be used to specify the resource type on the CLI: ippool.projectcalico.org
, ippools.projectcalico.org
as well as abbreviations such as ippool.p
and ippools.p
.
Sample YAML​
apiVersion: projectcalico.org/v3
kind: IPPool
metadata:
name: my.ippool-1
spec:
cidr: 10.1.0.0/16
ipipMode: CrossSubnet
natOutgoing: true
disabled: false
nodeSelector: all()
allowedUses:
- Workload
- Tunnel
IP pool definition​
Metadata​
Field | Description | Accepted Values | Schema |
---|---|---|---|
name | The name of this IPPool resource. Required. | Alphanumeric string with optional . , _ , or - . | string |
Spec​
Field | Description | Accepted Values | Schema | Default |
---|---|---|---|---|
cidr | IP range to use for this pool. | A valid IPv4 or IPv6 CIDR. Subnet length must be at least big enough to fit a single block (by default /26 for IPv4 or /122 for IPv6). Must not overlap with the Link Local range 169.254.0.0/16 or fe80::/10 . | string | |
blockSize | The CIDR size of allocation blocks used by this pool. Blocks are allocated on demand to hosts and are used to aggregate routes. The value can only be set when the pool is created. | 20 to 32 (inclusive) for IPv4 and 116 to 128 (inclusive) for IPv6 | int | 26 for IPv4 pools and 122 for IPv6 pools. |
ipipMode | The mode defining when IPIP will be used. Cannot be set at the same time as vxlanMode . | Always, CrossSubnet, Never | string | Never |
vxlanMode | The mode defining when VXLAN will be used. Cannot be set at the same time as ipipMode . | Always, CrossSubnet, Never | string | Never |
natOutgoing | When enabled, packets sent from Calico Enterprise networked containers in this pool to destinations outside of any Calico IP pools will be masqueraded. | true, false | boolean | false |
disabled | When set to true, Calico Enterprise IPAM will not assign addresses from this pool. | true, false | boolean | false |
disableBGPExport (since v3.11.0) | Disable exporting routes from this IP Pool’s CIDR over BGP. | true, false | boolean | false |
nodeSelector | Selects the nodes where Calico Enterprise IPAM should assign pod addresses from this pool. Can be overridden if a pod explicitly identifies this IP pool by annotation. | selector | all() | |
allowedUses (since v3.11.0) | Controls whether the pool will be used for automatic assignments of certain types. See below. | Workload, Tunnel, HostSecondaryInterface | list of strings | ["Workload", "Tunnel"] |
awsSubnetID (since v3.11.0) | May be set to the ID of an AWS VPC Subnet that contains the CIDR of this IP pool to activate the AWS-backed pool feature. See below. | Valid AWS Subnet ID. | string |
Do not use a custom blockSize
until all Calico Enterprise components have been updated to a version that
supports it (at least v2.3.0). Older versions of components do not understand the field so they may corrupt the
IP pool by creating blocks of incorrect size.
Allowed uses​
When automatically assigning IP addresses to workloads, only pools with "Workload" in their allowedUses
field are
consulted. Similarly, when assigning IPs for tunnel devices, only "Tunnel" pools are eligible. Finally, when
assigning IP addresses for AWS secondary ENIs, only pools with allowed use "HostSecondaryInterface" are candidates.
If the allowedUses
field is not specified, it defaults to ["Workload", "Tunnel"]
for compatibility with older
versions of Calico. It is not possible to specify a pool with no allowed uses.
The allowedUses
field is only consulted for new allocations, changing the field has no effect on previously allocated
addresses.
Calico Enterprise supports Kubernetes annotations that force the use of specific IP addresses. These annotations take precedence over the allowedUses
field.
AWS-backed pools​
Calico Enterprise supports IP pools that are backed by the AWS fabric. This feature was added in order to support egress gateways on the AWS fabric; the restrictions and requirements are currently documented as part of the egress gateways on AWS guide.
IPIP​
Routing of packets using IP-in-IP will be used when the destination IP address
is in an IP Pool that has IPIP enabled. In addition, if the ipipMode
is set to CrossSubnet
,
Calico Enterprise will only route using IP-in-IP if the IP address of the destination node is in a different
subnet. The subnet of each node is configured on the node resource (which may be automatically
determined when running the cnx-node
service).
For details on configuring IP-in-IP on your deployment, please refer to Configuring IP-in-IP.
Setting natOutgoing
is recommended on any IP Pool with ipip
enabled.
When ipip
is enabled without natOutgoing
routing between Workloads and
Hosts running Calico Enterprise is asymmetric and may cause traffic to be filtered due to
RPF checks failing.
VXLAN​
Routing of packets using VXLAN will be used when the destination IP address
is in an IP Pool that has VXLAN enabled.. In addition, if the vxlanMode
is set to CrossSubnet
,
Calico Enterprise will only route using VXLAN if the IP address of the destination node is in a different
subnet. The subnet of each node is configured on the node resource (which may be automatically
determined when running the cnx-node
service).
Setting natOutgoing
is recommended on any IP Pool with vxlan
enabled.
When vxlan
is enabled without natOutgoing
routing between Workloads and
Hosts running Calico Enterprise is asymmetric and may cause traffic to be filtered due to
RPF checks failing.
Block sizes​
The default block sizes of 26
for IPv4 and 122
for IPv6 provide blocks of 64 addresses. This allows addresses to be allocated in groups to workloads running on the same host. By grouping addresses, fewer routes need to be exchanged between hosts and to other BGP peers. If a host allocates all of the addresses in a block then it will be allocated an additional block. If there are no more blocks available then the host can take addresses from blocks allocated to other hosts. Specific routes are added for the borrowed addresses which has an impact on route table size.
Increasing the block size from the default (e.g., using 24
for IPv4 to give 256 addresses per block) means fewer blocks per host, and potentially fewer routes. But try to ensure that there are at least as many blocks in the pool as there are hosts.
Reducing the block size from the default (e.g., using 28
for IPv4 to give 16 addresses per block) means more blocks per host and therefore potentially more routes. This can be beneficial if it allows the blocks to be more fairly distributed amongst the hosts.
Node Selector​
For details on configuring IP pool node selectors, please read the Assign IP addresses based on topology guide..
To prevent an IP pool from being used automatically by Calico Enterprise IPAM, while still allowing
it to be used manually for static assignments, set the IPPool
's nodeSelector
to !all()
. Since the selector
matches no nodes, the IPPool will not be used automatically and, unlike setting disabled: true
, it can still be
used for manual assignments.
Selector reference​
A label selector is an expression which either matches or does not match a resource based on its labels.
Calico Enterprise label selectors support a number of operators, which can be combined into larger expressions using the boolean operators and parentheses.
Expression | Meaning |
---|---|
Logical operators | |
( <expression> ) | Matches if and only if <expression> matches. (Parentheses are used for grouping expressions.) |
! <expression> | Matches if and only if <expression> does not match. Tip: ! is a special character at the start of a YAML string, if you need to use ! at the start of a YAML string, enclose the string in quotes. |
<expression 1> && <expression 2> | "And": matches if and only if both <expression 1> , and, <expression 2> matches |
\<expression 1> || \<expression 2> | "Or": matches if and only if either <expression 1> , or, <expression 2> matches. |
Match operators | |
all() | Match all in-scope resources. To match no resources, combine this operator with ! to form !all() . |
global() | Match all non-namespaced resources. Useful in a namespaceSelector to select global resources such as global network sets. |
k == 'v' | Matches resources with the label 'k' and value 'v'. |
k != 'v' | Matches resources without label 'k' or with label 'k' and value not equal to v |
has(k) | Matches resources with label 'k', independent of value. To match pods that do not have label k , combine this operator with ! to form !has(k) |
k in { 'v1', 'v2' } | Matches resources with label 'k' and value in the given set |
k not in { 'v1', 'v2' } | Matches resources without label 'k' or with label 'k' and value not in the given set |
k contains 's' | Matches resources with label 'k' and value containing the substring 's' |
k starts with 's' | Matches resources with label 'k' and value starting with the substring 's' |
k ends with 's' | Matches resources with label 'k' and value ending with the substring 's' |
Operators have the following precedence:
- Highest: all the match operators
- Parentheses
( ... )
- Negation with
!
- Conjunction with
&&
- Lowest: Disjunction with
||
For example, the expression
! has(my-label) || my-label starts with 'prod' && role in {'frontend','business'}
Would be "bracketed" like this:
((!(has(my-label)) || ((my-label starts with 'prod') && (role in {'frontend','business'}))
It would match:
- Any resource that did not have label "my-label".
- Any resource that both:
- Has a value for
my-label
that starts with "prod", and, - Has a role label with value either "frontend", or "business".
- Has a value for
Supported operations​
Datastore type | Create/Delete | Update | Get/List | Notes |
---|---|---|---|---|
Kubernetes API server | Yes | Yes | Yes |
See also​
The IPReservation
resource allows for small parts of an IP pool to be reserved so that they will
not be used for automatic IPAM assignments.