From 0e16438561b758131944d3e31cbd32bf509f598e Mon Sep 17 00:00:00 2001 From: Tomas Hruby Date: Fri, 27 Mar 2026 12:00:35 -0700 Subject: [PATCH 1/2] Add allowedSourcePrefixes annotation documentation Document the cni.projectcalico.org/allowedSourcePrefixes pod annotation across all three products (Calico, Calico Enterprise, Calico Cloud). This annotation allows pods to send egress traffic with source IPs outside their own address, requiring workloadSourceSpoofing: Any in FelixConfiguration. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../configuring/allowed-source-prefixes.mdx | 52 +++++++++++++++++++ .../configuring/allowed-source-prefixes.mdx | 52 +++++++++++++++++++ .../configuring/allowed-source-prefixes.mdx | 52 +++++++++++++++++++ sidebars-calico-cloud.js | 1 + sidebars-calico-enterprise.js | 1 + sidebars-calico.js | 1 + 6 files changed, 159 insertions(+) create mode 100644 calico-cloud/networking/configuring/allowed-source-prefixes.mdx create mode 100644 calico-enterprise/networking/configuring/allowed-source-prefixes.mdx create mode 100644 calico/networking/configuring/allowed-source-prefixes.mdx diff --git a/calico-cloud/networking/configuring/allowed-source-prefixes.mdx b/calico-cloud/networking/configuring/allowed-source-prefixes.mdx new file mode 100644 index 0000000000..3370bee047 --- /dev/null +++ b/calico-cloud/networking/configuring/allowed-source-prefixes.mdx @@ -0,0 +1,52 @@ +--- +description: Allow pods to send traffic with a source IP address outside their own using the allowedSourcePrefixes annotation. +--- + +# Allow pods to use additional source IP prefixes + +## Big picture + +Allow pods to send egress traffic using source IP addresses outside their own pod IP, by specifying allowed source prefixes. + +## Value + +By default, Calico blocks egress traffic from pods when the source IP does not match the pod IP. This is a security measure to prevent IP spoofing. In certain use cases, such as pods acting as a transparent proxy that preserves the original source IP, pods need to send traffic with a different source address. + +## Concepts + +### Source IP spoofing protection + +Calico programs dataplane rules that drop egress packets from a pod if the source IP does not match the pod's own IP. The `allowedSourcePrefixes` annotation relaxes this restriction for specific IP prefixes on a per-pod basis. + +### FelixConfiguration prerequisite + +Because allowing non-pod source IPs is a security-sensitive operation, Felix disables support for the annotation by default. You must explicitly opt in by setting `workloadSourceSpoofing: Any` in the FelixConfiguration resource before the annotation takes effect. + +## Before you begin... + +Enable `workloadSourceSpoofing` in the FelixConfiguration resource: + +```yaml +apiVersion: crd.projectcalico.org/v1 +kind: FelixConfiguration +metadata: + name: default +spec: + workloadSourceSpoofing: Any +``` + +:::caution + +Enabling `workloadSourceSpoofing` allows any pod with the annotation to send traffic with arbitrary source IPs within the specified prefixes. Ensure you have proper admission control in place to restrict which pods can use this annotation. + +::: + +## How to + +Annotate the pod with `cni.projectcalico.org/allowedSourcePrefixes` set to a JSON list of CIDR prefixes. For example: + +```yaml +cni.projectcalico.org/allowedSourcePrefixes: '["192.168.10.0/24"]' +``` + +The annotation must be present when the pod is created; adding it later has no effect. diff --git a/calico-enterprise/networking/configuring/allowed-source-prefixes.mdx b/calico-enterprise/networking/configuring/allowed-source-prefixes.mdx new file mode 100644 index 0000000000..3370bee047 --- /dev/null +++ b/calico-enterprise/networking/configuring/allowed-source-prefixes.mdx @@ -0,0 +1,52 @@ +--- +description: Allow pods to send traffic with a source IP address outside their own using the allowedSourcePrefixes annotation. +--- + +# Allow pods to use additional source IP prefixes + +## Big picture + +Allow pods to send egress traffic using source IP addresses outside their own pod IP, by specifying allowed source prefixes. + +## Value + +By default, Calico blocks egress traffic from pods when the source IP does not match the pod IP. This is a security measure to prevent IP spoofing. In certain use cases, such as pods acting as a transparent proxy that preserves the original source IP, pods need to send traffic with a different source address. + +## Concepts + +### Source IP spoofing protection + +Calico programs dataplane rules that drop egress packets from a pod if the source IP does not match the pod's own IP. The `allowedSourcePrefixes` annotation relaxes this restriction for specific IP prefixes on a per-pod basis. + +### FelixConfiguration prerequisite + +Because allowing non-pod source IPs is a security-sensitive operation, Felix disables support for the annotation by default. You must explicitly opt in by setting `workloadSourceSpoofing: Any` in the FelixConfiguration resource before the annotation takes effect. + +## Before you begin... + +Enable `workloadSourceSpoofing` in the FelixConfiguration resource: + +```yaml +apiVersion: crd.projectcalico.org/v1 +kind: FelixConfiguration +metadata: + name: default +spec: + workloadSourceSpoofing: Any +``` + +:::caution + +Enabling `workloadSourceSpoofing` allows any pod with the annotation to send traffic with arbitrary source IPs within the specified prefixes. Ensure you have proper admission control in place to restrict which pods can use this annotation. + +::: + +## How to + +Annotate the pod with `cni.projectcalico.org/allowedSourcePrefixes` set to a JSON list of CIDR prefixes. For example: + +```yaml +cni.projectcalico.org/allowedSourcePrefixes: '["192.168.10.0/24"]' +``` + +The annotation must be present when the pod is created; adding it later has no effect. diff --git a/calico/networking/configuring/allowed-source-prefixes.mdx b/calico/networking/configuring/allowed-source-prefixes.mdx new file mode 100644 index 0000000000..3370bee047 --- /dev/null +++ b/calico/networking/configuring/allowed-source-prefixes.mdx @@ -0,0 +1,52 @@ +--- +description: Allow pods to send traffic with a source IP address outside their own using the allowedSourcePrefixes annotation. +--- + +# Allow pods to use additional source IP prefixes + +## Big picture + +Allow pods to send egress traffic using source IP addresses outside their own pod IP, by specifying allowed source prefixes. + +## Value + +By default, Calico blocks egress traffic from pods when the source IP does not match the pod IP. This is a security measure to prevent IP spoofing. In certain use cases, such as pods acting as a transparent proxy that preserves the original source IP, pods need to send traffic with a different source address. + +## Concepts + +### Source IP spoofing protection + +Calico programs dataplane rules that drop egress packets from a pod if the source IP does not match the pod's own IP. The `allowedSourcePrefixes` annotation relaxes this restriction for specific IP prefixes on a per-pod basis. + +### FelixConfiguration prerequisite + +Because allowing non-pod source IPs is a security-sensitive operation, Felix disables support for the annotation by default. You must explicitly opt in by setting `workloadSourceSpoofing: Any` in the FelixConfiguration resource before the annotation takes effect. + +## Before you begin... + +Enable `workloadSourceSpoofing` in the FelixConfiguration resource: + +```yaml +apiVersion: crd.projectcalico.org/v1 +kind: FelixConfiguration +metadata: + name: default +spec: + workloadSourceSpoofing: Any +``` + +:::caution + +Enabling `workloadSourceSpoofing` allows any pod with the annotation to send traffic with arbitrary source IPs within the specified prefixes. Ensure you have proper admission control in place to restrict which pods can use this annotation. + +::: + +## How to + +Annotate the pod with `cni.projectcalico.org/allowedSourcePrefixes` set to a JSON list of CIDR prefixes. For example: + +```yaml +cni.projectcalico.org/allowedSourcePrefixes: '["192.168.10.0/24"]' +``` + +The annotation must be present when the pod is created; adding it later has no effect. diff --git a/sidebars-calico-cloud.js b/sidebars-calico-cloud.js index aac54d51b1..6ed28e58b1 100644 --- a/sidebars-calico-cloud.js +++ b/sidebars-calico-cloud.js @@ -337,6 +337,7 @@ module.exports = { 'networking/configuring/secure-bgp', 'networking/configuring/workloads-outside-cluster', 'networking/configuring/pod-mac-address', + 'networking/configuring/allowed-source-prefixes', 'networking/configuring/node-local-dns-cache', 'networking/configuring/qos-controls', 'networking/configuring/add-maglev-load-balancing', diff --git a/sidebars-calico-enterprise.js b/sidebars-calico-enterprise.js index 25e073c38b..8dd7e80742 100644 --- a/sidebars-calico-enterprise.js +++ b/sidebars-calico-enterprise.js @@ -185,6 +185,7 @@ module.exports = { 'networking/configuring/secure-bgp', 'networking/configuring/workloads-outside-cluster', 'networking/configuring/pod-mac-address', + 'networking/configuring/allowed-source-prefixes', 'networking/configuring/node-local-dns-cache', 'networking/configuring/qos-controls', 'networking/configuring/add-maglev-load-balancing', diff --git a/sidebars-calico.js b/sidebars-calico.js index 79c2dabcf7..e3e0e7a472 100644 --- a/sidebars-calico.js +++ b/sidebars-calico.js @@ -282,6 +282,7 @@ module.exports = { 'networking/configuring/use-ipvs', 'networking/configuring/sidecar-acceleration', 'networking/configuring/pod-mac-address', + 'networking/configuring/allowed-source-prefixes', 'networking/configuring/node-local-dns-cache', 'networking/configuring/qos-controls', 'networking/configuring/add-maglev-load-balancing', From 332bd3394aed130855b54dbd41c6959bf413c68b Mon Sep 17 00:00:00 2001 From: Tomas Hruby Date: Wed, 22 Jul 2026 08:41:32 -0700 Subject: [PATCH 2/2] Address review feedback and verify against Calico code - Add Calico CNI prerequisite with product-correct link (OSS uses configure-cni-plugins.mdx; Enterprise/Cloud use component-resources/configuration.mdx). The three pages are no longer byte-identical for this reason. - Fix FelixConfiguration apiVersion from crd.projectcalico.org/v1 to projectcalico.org/v3, matching the rest of the docs. - Note the annotation is enforced in both iptables/nftables and eBPF dataplanes. - Clarify that Felix drops (does not program) a pod requesting source prefixes until workloadSourceSpoofing: Any is set, per felix/calc/validation_filter.go. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../configuring/allowed-source-prefixes.mdx | 31 ++++++++++--------- .../configuring/allowed-source-prefixes.mdx | 31 ++++++++++--------- .../configuring/allowed-source-prefixes.mdx | 31 ++++++++++--------- 3 files changed, 48 insertions(+), 45 deletions(-) diff --git a/calico-cloud/networking/configuring/allowed-source-prefixes.mdx b/calico-cloud/networking/configuring/allowed-source-prefixes.mdx index 3370bee047..0878be99cc 100644 --- a/calico-cloud/networking/configuring/allowed-source-prefixes.mdx +++ b/calico-cloud/networking/configuring/allowed-source-prefixes.mdx @@ -10,43 +10,44 @@ Allow pods to send egress traffic using source IP addresses outside their own po ## Value -By default, Calico blocks egress traffic from pods when the source IP does not match the pod IP. This is a security measure to prevent IP spoofing. In certain use cases, such as pods acting as a transparent proxy that preserves the original source IP, pods need to send traffic with a different source address. +By default, Calico blocks egress traffic from a pod when the source IP does not match the pod's IP. This prevents IP spoofing. Some workloads, such as a pod that acts as a transparent proxy and preserves the original client source IP, need to send traffic with a different source address. The `allowedSourcePrefixes` annotation relaxes the spoofing check for the prefixes you list on a specific pod. ## Concepts ### Source IP spoofing protection -Calico programs dataplane rules that drop egress packets from a pod if the source IP does not match the pod's own IP. The `allowedSourcePrefixes` annotation relaxes this restriction for specific IP prefixes on a per-pod basis. +Calico programs dataplane rules that drop egress packets from a pod when the source IP does not match the pod's own IP. The `allowedSourcePrefixes` annotation relaxes this restriction for specific IP prefixes on a per-pod basis. It works with both the iptables/nftables and the eBPF dataplanes. ### FelixConfiguration prerequisite -Because allowing non-pod source IPs is a security-sensitive operation, Felix disables support for the annotation by default. You must explicitly opt in by setting `workloadSourceSpoofing: Any` in the FelixConfiguration resource before the annotation takes effect. +Allowing non-pod source IPs is security-sensitive, so Felix rejects the annotation by default. You must opt in by setting `workloadSourceSpoofing` to `Any` in the FelixConfiguration resource. Until you do, a pod that requests source prefixes is not programmed into the dataplane. ## Before you begin... -Enable `workloadSourceSpoofing` in the FelixConfiguration resource: +- Your cluster must be using Calico CNI to use this feature. See [Configuring the Calico CNI Plugins](../../reference/component-resources/configuration.mdx). +- Enable `workloadSourceSpoofing` in the FelixConfiguration resource: -```yaml -apiVersion: crd.projectcalico.org/v1 -kind: FelixConfiguration -metadata: - name: default -spec: - workloadSourceSpoofing: Any -``` + ```yaml + apiVersion: projectcalico.org/v3 + kind: FelixConfiguration + metadata: + name: default + spec: + workloadSourceSpoofing: Any + ``` :::caution -Enabling `workloadSourceSpoofing` allows any pod with the annotation to send traffic with arbitrary source IPs within the specified prefixes. Ensure you have proper admission control in place to restrict which pods can use this annotation. +Setting `workloadSourceSpoofing` to `Any` lets any pod that carries the annotation send traffic with arbitrary source IPs. Use admission control to restrict which pods can set the annotation. ::: ## How to -Annotate the pod with `cni.projectcalico.org/allowedSourcePrefixes` set to a JSON list of CIDR prefixes. For example: +Annotate the pod with `cni.projectcalico.org/allowedSourcePrefixes` set to a JSON list of CIDRs. For example: ```yaml -cni.projectcalico.org/allowedSourcePrefixes: '["192.168.10.0/24"]' + cni.projectcalico.org/allowedSourcePrefixes: '["192.168.10.0/24"]' ``` The annotation must be present when the pod is created; adding it later has no effect. diff --git a/calico-enterprise/networking/configuring/allowed-source-prefixes.mdx b/calico-enterprise/networking/configuring/allowed-source-prefixes.mdx index 3370bee047..0878be99cc 100644 --- a/calico-enterprise/networking/configuring/allowed-source-prefixes.mdx +++ b/calico-enterprise/networking/configuring/allowed-source-prefixes.mdx @@ -10,43 +10,44 @@ Allow pods to send egress traffic using source IP addresses outside their own po ## Value -By default, Calico blocks egress traffic from pods when the source IP does not match the pod IP. This is a security measure to prevent IP spoofing. In certain use cases, such as pods acting as a transparent proxy that preserves the original source IP, pods need to send traffic with a different source address. +By default, Calico blocks egress traffic from a pod when the source IP does not match the pod's IP. This prevents IP spoofing. Some workloads, such as a pod that acts as a transparent proxy and preserves the original client source IP, need to send traffic with a different source address. The `allowedSourcePrefixes` annotation relaxes the spoofing check for the prefixes you list on a specific pod. ## Concepts ### Source IP spoofing protection -Calico programs dataplane rules that drop egress packets from a pod if the source IP does not match the pod's own IP. The `allowedSourcePrefixes` annotation relaxes this restriction for specific IP prefixes on a per-pod basis. +Calico programs dataplane rules that drop egress packets from a pod when the source IP does not match the pod's own IP. The `allowedSourcePrefixes` annotation relaxes this restriction for specific IP prefixes on a per-pod basis. It works with both the iptables/nftables and the eBPF dataplanes. ### FelixConfiguration prerequisite -Because allowing non-pod source IPs is a security-sensitive operation, Felix disables support for the annotation by default. You must explicitly opt in by setting `workloadSourceSpoofing: Any` in the FelixConfiguration resource before the annotation takes effect. +Allowing non-pod source IPs is security-sensitive, so Felix rejects the annotation by default. You must opt in by setting `workloadSourceSpoofing` to `Any` in the FelixConfiguration resource. Until you do, a pod that requests source prefixes is not programmed into the dataplane. ## Before you begin... -Enable `workloadSourceSpoofing` in the FelixConfiguration resource: +- Your cluster must be using Calico CNI to use this feature. See [Configuring the Calico CNI Plugins](../../reference/component-resources/configuration.mdx). +- Enable `workloadSourceSpoofing` in the FelixConfiguration resource: -```yaml -apiVersion: crd.projectcalico.org/v1 -kind: FelixConfiguration -metadata: - name: default -spec: - workloadSourceSpoofing: Any -``` + ```yaml + apiVersion: projectcalico.org/v3 + kind: FelixConfiguration + metadata: + name: default + spec: + workloadSourceSpoofing: Any + ``` :::caution -Enabling `workloadSourceSpoofing` allows any pod with the annotation to send traffic with arbitrary source IPs within the specified prefixes. Ensure you have proper admission control in place to restrict which pods can use this annotation. +Setting `workloadSourceSpoofing` to `Any` lets any pod that carries the annotation send traffic with arbitrary source IPs. Use admission control to restrict which pods can set the annotation. ::: ## How to -Annotate the pod with `cni.projectcalico.org/allowedSourcePrefixes` set to a JSON list of CIDR prefixes. For example: +Annotate the pod with `cni.projectcalico.org/allowedSourcePrefixes` set to a JSON list of CIDRs. For example: ```yaml -cni.projectcalico.org/allowedSourcePrefixes: '["192.168.10.0/24"]' + cni.projectcalico.org/allowedSourcePrefixes: '["192.168.10.0/24"]' ``` The annotation must be present when the pod is created; adding it later has no effect. diff --git a/calico/networking/configuring/allowed-source-prefixes.mdx b/calico/networking/configuring/allowed-source-prefixes.mdx index 3370bee047..1872b27359 100644 --- a/calico/networking/configuring/allowed-source-prefixes.mdx +++ b/calico/networking/configuring/allowed-source-prefixes.mdx @@ -10,43 +10,44 @@ Allow pods to send egress traffic using source IP addresses outside their own po ## Value -By default, Calico blocks egress traffic from pods when the source IP does not match the pod IP. This is a security measure to prevent IP spoofing. In certain use cases, such as pods acting as a transparent proxy that preserves the original source IP, pods need to send traffic with a different source address. +By default, Calico blocks egress traffic from a pod when the source IP does not match the pod's IP. This prevents IP spoofing. Some workloads, such as a pod that acts as a transparent proxy and preserves the original client source IP, need to send traffic with a different source address. The `allowedSourcePrefixes` annotation relaxes the spoofing check for the prefixes you list on a specific pod. ## Concepts ### Source IP spoofing protection -Calico programs dataplane rules that drop egress packets from a pod if the source IP does not match the pod's own IP. The `allowedSourcePrefixes` annotation relaxes this restriction for specific IP prefixes on a per-pod basis. +Calico programs dataplane rules that drop egress packets from a pod when the source IP does not match the pod's own IP. The `allowedSourcePrefixes` annotation relaxes this restriction for specific IP prefixes on a per-pod basis. It works with both the iptables/nftables and the eBPF dataplanes. ### FelixConfiguration prerequisite -Because allowing non-pod source IPs is a security-sensitive operation, Felix disables support for the annotation by default. You must explicitly opt in by setting `workloadSourceSpoofing: Any` in the FelixConfiguration resource before the annotation takes effect. +Allowing non-pod source IPs is security-sensitive, so Felix rejects the annotation by default. You must opt in by setting `workloadSourceSpoofing` to `Any` in the FelixConfiguration resource. Until you do, a pod that requests source prefixes is not programmed into the dataplane. ## Before you begin... -Enable `workloadSourceSpoofing` in the FelixConfiguration resource: +- Your cluster must be using Calico CNI to use this feature. See [Configuring the Calico CNI Plugins](../../reference/configure-cni-plugins.mdx). +- Enable `workloadSourceSpoofing` in the FelixConfiguration resource: -```yaml -apiVersion: crd.projectcalico.org/v1 -kind: FelixConfiguration -metadata: - name: default -spec: - workloadSourceSpoofing: Any -``` + ```yaml + apiVersion: projectcalico.org/v3 + kind: FelixConfiguration + metadata: + name: default + spec: + workloadSourceSpoofing: Any + ``` :::caution -Enabling `workloadSourceSpoofing` allows any pod with the annotation to send traffic with arbitrary source IPs within the specified prefixes. Ensure you have proper admission control in place to restrict which pods can use this annotation. +Setting `workloadSourceSpoofing` to `Any` lets any pod that carries the annotation send traffic with arbitrary source IPs. Use admission control to restrict which pods can set the annotation. ::: ## How to -Annotate the pod with `cni.projectcalico.org/allowedSourcePrefixes` set to a JSON list of CIDR prefixes. For example: +Annotate the pod with `cni.projectcalico.org/allowedSourcePrefixes` set to a JSON list of CIDRs. For example: ```yaml -cni.projectcalico.org/allowedSourcePrefixes: '["192.168.10.0/24"]' + cni.projectcalico.org/allowedSourcePrefixes: '["192.168.10.0/24"]' ``` The annotation must be present when the pod is created; adding it later has no effect.