From 1ea2b911e192c8896c3e9220dd39b30f0dcf574c Mon Sep 17 00:00:00 2001 From: Tomas Hruby Date: Fri, 27 Mar 2026 12:00:35 -0700 Subject: [PATCH] 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 eeb0e0105f..28da56891f 100644 --- a/sidebars-calico-cloud.js +++ b/sidebars-calico-cloud.js @@ -360,6 +360,7 @@ module.exports = { 'networking/configuring/custom-bgp-config', '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 1f4a792134..01b24cdcd0 100644 --- a/sidebars-calico-enterprise.js +++ b/sidebars-calico-enterprise.js @@ -180,6 +180,7 @@ module.exports = { 'networking/configuring/custom-bgp-config', '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 f4845c6b89..311bde3ffe 100644 --- a/sidebars-calico.js +++ b/sidebars-calico.js @@ -280,6 +280,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',