Add dual-stack API support for Egress by XinShuYang · Pull Request #8244 · antrea-io/antrea

XinShuYang · 2026-08-04T15:10:44Z

Extend ExternalIPPool subnet configuration to support IPv4 and IPv6 subnets with a shared VLAN. Add Egress IP family selection and explicit dual-stack Egress IPs while preserving the legacy single-stack fields.

Add CRD and admission validation for IP family consistency, subnet matching, mutually exclusive representations, and immutable pool IP families. Remove the unused externalIPPools field.

luolanzone · 2026-08-08T06:13:42Z

 	return raw
 }

+func mutateEgress(egress *crdv1beta1.Egress, mutate func(*crdv1beta1.Egress)) *crdv1beta1.Egress {


This helper just invokes the mutator and returns the object unchanged — it adds indirection without adding value, turning each test case into nested marshal(mutateEgress(newEgress(...), func(e){ ... })) calls. The repo's test style favors explicit builder functions.

Suggest defining a builder for the dual-stack cases instead, e.g.:

func newDualStackEgress(name, pool string, egressIPs []string, ipFamilies []corev1.IPFamily) *crdv1beta1.Egress

and call it directly from the test table.

Thanks for the suggestion, added newDualStackEgress and refactored the implementation.

luolanzone · 2026-08-08T06:13:42Z

+                        - prefixLength
+                    - required:
+                        - ipFamilySubnets
+                  x-kubernetes-validations:


The x-kubernetes-validations list indentation is inconsistent within this PR: egress.yaml keeps list items at the same level as the key (matching the existing ippool.yaml style), while externalippool.yaml indents them by 2 extra spaces (see also line 76). Suggest unifying on the same-level style.

Sure, updated.

luolanzone · 2026-08-08T06:13:42Z

+	ip    net.IP
+}
+
+func ipFamilyForIP(ip net.IP) corev1.IPFamily {


ipFamilyForIP here and ipFamilyForAddress in pkg/controller/validation/ippool.go are identical in logic. Consider consolidating into a single shared helper (e.g. in pkg/controller/validation or pkg/util/ip) so the two sites don't drift apart semantically — for example, when handling IPv4-mapped IPv6 addresses in the future.

I added IPFamilyForAddress in pkg/util/ip, PTAL.

jianjuns · 2026-08-05T21:00:43Z


-// SubnetInfo specifies subnet attributes for IP Range.
+// SubnetInfo specifies subnet attributes for IP ranges.
 type SubnetInfo struct {


Could we add a new struct, and so IPPool wont be impacted?

Sure, I named the new struct ExternalIPPoolSubnetInfo.

jianjuns · 2026-08-05T21:23:59Z

+	PrefixLength int32 `json:"prefixLength,omitempty"`
+	// IPFamilySubnets specifies subnet attributes by IP family. At most one entry is allowed for each IP family.
+	// It cannot be set together with Gateway or PrefixLength.
+	IPFamilySubnets []IPFamilySubnetInfo `json:"ipFamilySubnets,omitempty"`


I would just call the field Gateways and the struct something like SubnetGateway. I hope you can think of better names though :)

jianjuns · 2026-08-10T19:38:18Z

 	AppliedTo AppliedTo `json:"appliedTo"`
-	// EgressIP specifies the SNAT IP address for the selected workloads.
-	// If ExternalIPPool is empty, it must be specified manually.
+	// EgressIP is the legacy field that specifies one SNAT IP address for the selected workloads.


I would keep the original comment - EgressIP specifies a single SNAT IP address for the selected workloads.

If we want to start deprecating the field, we can add: "// +deprecated:warning="EgressIP is deprecated, use EgressIPs instead."

EgressIP is still used for single-stack Egress, I have updated related comments.

jianjuns · 2026-08-10T19:43:30Z

-	ExternalIPPools []string `json:"externalIPPools,omitempty"`
+	// IPFamilies specifies the IP families for which Egress IPs should be allocated. At most one entry is allowed for
+	// each IP family. It may be omitted for a single-stack ExternalIPPool or when EgressIP or EgressIPs is specified.
+	IPFamilies []corev1.IPFamily `json:"ipFamilies,omitempty"`


Use IPFamilyPolicy instead? Even for dual-stack IPPool, we should default to dual-stack allocation.

Make sense to me, I have updated it to IPFamilyPolicy. The default value is PreferDualStack.

XinShuYang · 2026-08-11T16:38:48Z


+// IPFamilyForAddress returns the Kubernetes IP family for the provided address.
+func IPFamilyForAddress(address netip.Addr) corev1.IPFamily {
+	if address.Unmap().Is4() {


Should IPv4-mapped IPv6 addresses be treated as IPv4 here, or should we reject them during API validation? @jianjuns @luolanzone

jianjuns · 2026-08-11T18:39:25Z

 	EgressIP string `json:"egressIP,omitempty"`
-	// EgressIPs specifies multiple SNAT IP addresses for the selected workloads.
-	// Cannot be set with EgressIP.
+	// EgressIPs specifies the IPv4 and IPv6 SNAT IP addresses for the selected workloads. It must contain exactly two


Can we support single stack allocation in the same version too, even if not in this PR?

Can we support single stack allocation in the same version too, even if not in this PR?

Maybe we can discuss the egressIP/egressIPs unification and compatibility checks after all dual-stack Egress PRs are merged? For now, I‘d prefer to make sure all legacy single-stack Egress behavior remains consistent.

We can discuss separately, but I am not saying you must change the existing EgressIP implementation. I am saying we should support single stack allocation with ExternalIPs too. I would avoid changing API behaviors again in the next Antrea version.

@jianjuns Do you mean supporting single-stack allocation with egressIPs as well? Given Antonin's point about the version bump, I'm now thinking of using spec.egressIPs and status.egressIPs for both single-stack and dual-stack Egresses and removing spec.egressIP and status.egressIP in v1beta2, since the API compatibility concerns would be much less significant. cc @antoninbas @luolanzone @tnqn

jianjuns · 2026-08-11T18:49:55Z

-	// Cannot be set with ExternalIPPool.
-	ExternalIPPools []string `json:"externalIPPools,omitempty"`
+	// IPFamilyPolicy specifies whether the Egress is single-stack or dual-stack. It defaults to PreferDualStack.
+	IPFamilyPolicy *corev1.IPFamilyPolicy `json:"ipFamilyPolicy,omitempty"`


Humm.. seems IPFamilyPolicy cannot specify v4 or v6 for a single stack allocation. Probably let us still use ipFamilies.

Could we by default use the ExternalIPPool's IP families when the filed not set?

I assume this field should be ignored when EgressIP or EgressIPs are specified?

The explicitly specified EgressIP or EgressIPs determines the actual IP family configuration. However, I don't think IPFamilyPolicy should be silently ignored: we should reject contradictory combinations, such as EgressIP with RequireDualStack or EgressIPs with SingleStack. When no explicit IP is provided, the policy controls automatic allocation from the ExternalIPPool.

For single stack allocation, I think we can still get the IP family info from the externalIPPool or egressIP? For the default value of preferDualStack, a single-stack ExternalIPPool can still determine the IP family based on its own configuration. Do you still think there are any blockers to using IPFamilyPolicy? @jianjuns

I am fine if you prefer a strict validation to make EgressIP(s) and specified IP stack(s) consistent.

For single stack allocation, I think we can still get the IP family info from the externalIPPool or egressIP? For the default value of preferDualStack, a single-stack ExternalIPPool can still determine the IP family based on its own configuration. Do you still think there are any blockers to using IPFamilyPolicy?

How to indicate I want to allocate a v6 IP from a dual-stack pool?

How to indicate I want to allocate a v6 IP from a dual-stack pool?

For IPFamilyPolicy in this case, I would let it select the IP family based on the first entry in ipRanges of the dual-stack pool. If you think this is too tricky and we need to support this case explicitly, we probably have to revert to using the ipFamilies field. Could you share more thoughts? @jianjuns

Extend ExternalIPPool subnet configuration to support IPv4 and IPv6 subnets with a shared VLAN. Add Egress IP family selection and explicit dual-stack Egress IPs while preserving the legacy single-stack fields. Add CRD and admission validation for IP family consistency, subnet matching, mutually exclusive representations, and immutable pool IP families. Remove the unused externalIPPools field. Signed-off-by: Shuyang Xin <xin_shuyang@hotmail.com>

antoninbas

Even if we assume the egressIPs and externalIPPools fields were not technically used, I feel like we have to be a bit more careful with the API change, and I think we should bump up the API version to v1beta2.

Bumping the API version allows us to do the following 2 things, which otherwise we should not do:

remove the externalIPPools field
change the validation rules for the egressIPs field

And if we introduce a new API version, we have more freedom when it comes to the new ExternalIPPoolSubnetInfo struct. We can drop gateway and prefixLength for example.

It can also be argued that if we don't bump the API version, we must make sure the top-level gateway and prefixLength fields should match gateways[0]: https://github.com/kubernetes/community/blob/main/contributors/devel/sig-architecture/api_changes.md#making-a-singular-field-plural

The conversion webhook from v1beta1 to v1beta2 should be pretty straightforward to implement.

TLDR; I would strongly recommend introducing a new v1beta2 API version, unless someone can make a valid argument against it.

jianjuns · 2026-08-12T19:08:00Z

-	// If both ExternalIPPool and EgressIP are non-empty, the IP must be in the pool.
+	// EgressIP specifies a single SNAT IP address for the selected workloads. It is used only for single-stack Egresses.
+	// If ExternalIPPool is not specified, the EgressIP field must be specified manually. If ExternalIPPool is specified,
+	// EgressIP field is optional, and an IP will be automatically assigned by Antrea automatically when it is not specified. If both


Could you wrap lines at a fixed length?

jianjuns · 2026-08-12T19:09:05Z

+	// EgressIP specifies a single SNAT IP address for the selected workloads. It is used only for single-stack Egresses.
+	// If ExternalIPPool is not specified, the EgressIP field must be specified manually. If ExternalIPPool is specified,
+	// EgressIP field is optional, and an IP will be automatically assigned by Antrea automatically when it is not specified. If both
+	// ExternalIPPool and EgressIP are specified, the IP must be in the pool.


Probably move EgressIP to be before ExternalIPPool -> "EgressIP and ExternalIPPool are.."

jianjuns · 2026-08-12T19:10:51Z

 	EgressIP string `json:"egressIP,omitempty"`
-	// EgressIPs specifies multiple SNAT IP addresses for the selected workloads.
-	// Cannot be set with EgressIP.
+	// EgressIPs specifies the IPv4 and IPv6 SNAT IP addresses for the selected workloads. It must contain exactly two


We can discuss separately, but I am not saying you must change the existing EgressIP implementation. I am saying we should support single stack allocation with ExternalIPs too. I would avoid changing API behaviors again in the next Antrea version.

jianjuns · 2026-08-12T19:13:42Z

-	// If it is non-empty, the EgressIP will be assigned to a Node specified by the pool automatically and will failover
-	// to a different Node when the Node becomes unreachable.
+	// ExternalIPPool specifies the IP Pool that the EgressIP(s) should be allocated from. If it is not set, the specified EgressIP(s)
+	// should be assigned to a Node manually. If it is specified, the EgressIP(s) will be assigned to a Node specified by the pool


If ExternalIPPool is provided

jianjuns · 2026-08-12T19:13:56Z

-	// If it is empty, the specified EgressIP must be assigned to a Node manually.
-	// If it is non-empty, the EgressIP will be assigned to a Node specified by the pool automatically and will failover
-	// to a different Node when the Node becomes unreachable.
+	// ExternalIPPool specifies the IP Pool that the EgressIP(s) should be allocated from. If it is not set, the specified EgressIP(s)


set -> provided

jianjuns · 2026-08-12T19:14:41Z

-	// If both ExternalIPPool and EgressIP are non-empty, the IP must be in the pool.
+	// EgressIP specifies a single SNAT IP address for the selected workloads. It is used only for single-stack Egresses.
+	// If ExternalIPPool is not specified, the EgressIP field must be specified manually. If ExternalIPPool is specified,
+	// EgressIP field is optional, and an IP will be automatically assigned by Antrea automatically when it is not specified. If both


EgressIP field -> the EgressIP field

jianjuns · 2026-08-12T19:18:07Z

-	// Cannot be set with ExternalIPPool.
-	ExternalIPPools []string `json:"externalIPPools,omitempty"`
+	// IPFamilyPolicy specifies whether the Egress is single-stack or dual-stack. It defaults to PreferDualStack.
+	IPFamilyPolicy *corev1.IPFamilyPolicy `json:"ipFamilyPolicy,omitempty"`


I am fine if you prefer a strict validation to make EgressIP(s) and specified IP stack(s) consistent.

For single stack allocation, I think we can still get the IP family info from the externalIPPool or egressIP? For the default value of preferDualStack, a single-stack ExternalIPPool can still determine the IP family based on its own configuration. Do you still think there are any blockers to using IPFamilyPolicy?

How to indicate I want to allocate a v6 IP from a dual-stack pool?

jianjuns · 2026-08-12T19:21:17Z

Even if we assume the egressIPs and externalIPPools fields were not technically used, I feel like we have to be a bit more careful with the API change, and I think we should bump up the API version to v1beta2.

So, in which Antrea version egressIPs and externalIPPools were added? If it is 2.7, we still have a chance to exclude that change? If it is a released version, why we shipped unused API fields?

antoninbas · 2026-08-12T19:53:10Z

Closed by mistake...

XinShuYang · 2026-08-13T14:07:08Z

Even if we assume the egressIPs and externalIPPools fields were not technically used, I feel like we have to be a bit more careful with the API change, and I think we should bump up the API version to v1beta2.

So, in which Antrea version egressIPs and externalIPPools were added? If it is 2.7, we still have a chance to exclude that change? If it is a released version, why we shipped unused API fields?

@jianjuns AFAIK, it was first introduced in this PR three years ago: #4603

jianjuns · 2026-08-14T00:36:36Z

@jianjuns AFAIK, it was first introduced in this PR three years ago: #4603

Antonin told me the background for that change. I think we probably should not remove the field, at least not with this PR.

XinShuYang marked this pull request as ready for review August 4, 2026 15:11

luolanzone requested review from antoninbas, jianjuns, luolanzone, tnqn and wenyingd and removed request for luolanzone August 5, 2026 02:57

luolanzone added this to the Antrea v2.7 release milestone Aug 5, 2026

XinShuYang force-pushed the egressdsapi branch from d55ab7a to 689aab6 Compare August 5, 2026 15:49

luolanzone reviewed Aug 8, 2026

View reviewed changes

XinShuYang force-pushed the egressdsapi branch from 689aab6 to b644afa Compare August 10, 2026 15:24

jianjuns reviewed Aug 10, 2026

View reviewed changes

XinShuYang force-pushed the egressdsapi branch 2 times, most recently from 73dcef7 to b5cfbb2 Compare August 11, 2026 16:30

XinShuYang commented Aug 11, 2026

View reviewed changes

jianjuns reviewed Aug 11, 2026

View reviewed changes

XinShuYang force-pushed the egressdsapi branch from b5cfbb2 to dc3ca6d Compare August 12, 2026 07:11

antoninbas reviewed Aug 12, 2026

View reviewed changes

jianjuns reviewed Aug 12, 2026

View reviewed changes

antoninbas closed this Aug 12, 2026

antoninbas reopened this Aug 12, 2026

luolanzone modified the milestones: Antrea v2.7 release, Antrea v2.8 release Aug 14, 2026

Uh oh!

Conversation

XinShuYang commented Aug 4, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

XinShuYang Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

XinShuYang Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

XinShuYang Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

antoninbas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

XinShuYang Aug 11, 2026 •

edited

Loading

XinShuYang Aug 13, 2026 •

edited

Loading

XinShuYang Aug 12, 2026 •

edited

Loading