Skip to content

Add allowedSourcePrefixes annotation documentation #2613

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
tomastigera wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Add allowedSourcePrefixes annotation documentation #2613

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions calico-cloud/networking/configuring/allowed-source-prefixes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Check failure on line 19 in calico-cloud/networking/configuring/allowed-source-prefixes.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[CalicoStyle.Substitutions] Use 'data plane' instead of 'dataplane'.

Raw Output:
{"message": "[CalicoStyle.Substitutions] Use 'data plane' instead of 'dataplane'.", "location": {"path": "calico-cloud/networking/configuring/allowed-source-prefixes.mdx", "range": {"start": {"line": 19, "column": 17}}}, "severity": "ERROR"}

Check failure on line 19 in calico-cloud/networking/configuring/allowed-source-prefixes.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'dataplane'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'dataplane'?", "location": {"path": "calico-cloud/networking/configuring/allowed-source-prefixes.mdx", "range": {"start": {"line": 19, "column": 17}}}, "severity": "ERROR"}

### 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...

Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page documents a Calico CNI pod annotation, but the prerequisites don’t mention that the cluster must be using Calico CNI (as is done in other annotation docs in this section). Add that prerequisite (and optionally link to the CNI plugin configuration page) before the FelixConfiguration step.

Suggested change
Ensure your Kubernetes cluster is using the Calico CNI plugin.

Copilot uses AI. Check for mistakes.
Enable `workloadSourceSpoofing` in the FelixConfiguration resource:

```yaml
apiVersion: crd.projectcalico.org/v1
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The FelixConfiguration YAML example uses apiVersion: crd.projectcalico.org/v1, but other docs in this product use projectcalico.org/v3 for FelixConfiguration. Please align the apiVersion here (or explicitly call out when each apiVersion applies) to avoid users applying the wrong manifest.

Suggested change
apiVersion: crd.projectcalico.org/v1
apiVersion: projectcalico.org/v3

Copilot uses AI. Check for mistakes.
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.
52 changes: 52 additions & 0 deletions calico-enterprise/networking/configuring/allowed-source-prefixes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Check failure on line 19 in calico-enterprise/networking/configuring/allowed-source-prefixes.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[CalicoStyle.Substitutions] Use 'data plane' instead of 'dataplane'.

Raw Output:
{"message": "[CalicoStyle.Substitutions] Use 'data plane' instead of 'dataplane'.", "location": {"path": "calico-enterprise/networking/configuring/allowed-source-prefixes.mdx", "range": {"start": {"line": 19, "column": 17}}}, "severity": "ERROR"}

Check failure on line 19 in calico-enterprise/networking/configuring/allowed-source-prefixes.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'dataplane'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'dataplane'?", "location": {"path": "calico-enterprise/networking/configuring/allowed-source-prefixes.mdx", "range": {"start": {"line": 19, "column": 17}}}, "severity": "ERROR"}

### 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:

Comment on lines +27 to +28
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page documents a Calico CNI pod annotation, but the prerequisites don’t mention that the cluster must be using Calico CNI (as is done in other annotation docs in this section). Add that prerequisite (and optionally link to the CNI plugin configuration page) before the FelixConfiguration step.

Suggested change
Enable `workloadSourceSpoofing` in the FelixConfiguration resource:
Ensure the following prerequisites are met:
- Your cluster is configured to use the Calico CNI plugin.
- `workloadSourceSpoofing` is enabled in the FelixConfiguration resource:

Copilot uses AI. Check for mistakes.
```yaml
apiVersion: crd.projectcalico.org/v1
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The FelixConfiguration YAML example uses apiVersion: crd.projectcalico.org/v1, but other docs in this product use projectcalico.org/v3 for FelixConfiguration. Please align the apiVersion here (or explicitly call out when each apiVersion applies) to avoid users applying the wrong manifest.

Suggested change
apiVersion: crd.projectcalico.org/v1
apiVersion: projectcalico.org/v3

Copilot uses AI. Check for mistakes.
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.
52 changes: 52 additions & 0 deletions calico/networking/configuring/allowed-source-prefixes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Check failure on line 19 in calico/networking/configuring/allowed-source-prefixes.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'dataplane'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'dataplane'?", "location": {"path": "calico/networking/configuring/allowed-source-prefixes.mdx", "range": {"start": {"line": 19, "column": 17}}}, "severity": "ERROR"}

Check failure on line 19 in calico/networking/configuring/allowed-source-prefixes.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[CalicoStyle.Substitutions] Use 'data plane' instead of 'dataplane'.

Raw Output:
{"message": "[CalicoStyle.Substitutions] Use 'data plane' instead of 'dataplane'.", "location": {"path": "calico/networking/configuring/allowed-source-prefixes.mdx", "range": {"start": {"line": 19, "column": 17}}}, "severity": "ERROR"}

### 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...

Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page documents a Calico CNI pod annotation, but the prerequisites don’t mention that the cluster must be using Calico CNI (as is done in other annotation docs in this section). Add that prerequisite (and optionally link to the CNI plugin configuration page) before the FelixConfiguration step.

Suggested change
Ensure your cluster is configured to use the Calico CNI plugin.

Copilot uses AI. Check for mistakes.
Enable `workloadSourceSpoofing` in the FelixConfiguration resource:

```yaml
apiVersion: crd.projectcalico.org/v1
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The FelixConfiguration YAML example uses apiVersion: crd.projectcalico.org/v1, but other docs in this product use projectcalico.org/v3 for FelixConfiguration. Please align the apiVersion here (or explicitly call out when each apiVersion applies) to avoid users applying the wrong manifest.

Suggested change
apiVersion: crd.projectcalico.org/v1
apiVersion: projectcalico.org/v3

Copilot uses AI. Check for mistakes.
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.
1 change: 1 addition & 0 deletions sidebars-calico-cloud.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
1 change: 1 addition & 0 deletions sidebars-calico-enterprise.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
1 change: 1 addition & 0 deletions sidebars-calico.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
Loading