Skip to content

networking: document masquerade subnet size requirement for UDN #116247

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

Open
Ultimate-etamitlU wants to merge 1 commit into
base: main
Choose a base branch
from
+11 −0
Open

networking: document masquerade subnet size requirement for UDN #116247

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
7 changes: 7 additions & 0 deletions modules/nw-ovn-k-day-2-masq-subnet.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,13 @@

You can change the masquerade subnet used by OVN-Kubernetes as a post-installation operation to avoid conflicts with any existing subnets that are already in use in your environment.

[IMPORTANT]
====
If you are using or plan to use UserDefinedNetworks (UDN), the masquerade subnet must be `/18` or larger for IPv4. Each UDN consumes two masquerade IPs, and the allocator supports up to 4,096 networks. A subnet smaller than `/18` exhausts available IPs after a finite number of total UDN create operations — even across delete cycles — causing an _"out of range"_ failure.

Clusters installed before {product-title} 4.17 retain the default `169.254.169.0/29` (8 IPs), which cannot support any UDN. Use `169.254.0.0/17` as described in this procedure before creating any UDNs.
====

.Prerequisites

* Install the OpenShift CLI (`oc`).
Expand Down
4 changes: 4 additions & 0 deletions modules/nw-udn-limitations.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,10 @@ Consider the following limitations before implementing a UDN.

* *Unclear error message for IP address exhaustion*: When the subnet of a user-defined network runs out of available IP addresses, new pods fail to start. When this occurs, the following error is returned: `Warning: Failed to create pod sandbox`. This error message does not clearly specify that IP depletion is the cause. To confirm the issue, you can check the *Events* page in the pod's namespace on the {product-title} web console, where an explicit message about subnet exhaustion is reported.

* *Masquerade subnet size requirement*: When UserDefinedNetworks are in use, the `internalMasqueradeSubnet` must be `/18` or larger for IPv4 (at minimum 16,384 IPs). Each UDN consumes two masquerade IPs derived from a forward-scanning allocator capped at 4,096 networks. A subnet smaller than `/18` will exhaust the available IP range after a finite number of total UDN create operations — even if UDNs are deleted in between — causing `ovnkube-controller` to fail with an _"out of range"_ error and leaving nodes in `CrashLoopBackOff`.
+
Clusters installed before {product-title} 4.17 retain the old default of `169.254.169.0/29` (only 8 IPs, insufficient for any UDN). Use the day-2 masquerade subnet change procedure to set the subnet to `169.254.0.0/17` before creating any UDNs. See _Configuring the OVN-Kubernetes masquerade subnet as a post-installation operation_.

* *Layer2 egress IP limitations* (`UserDefinedNetwork` CRs only):

** Egress IP does not work without a default gateway.
Expand Down