<commit_before>// Module included in the following assemblies:
//
// * networking/openshift_sdn/assigning-egress-ips.adoc
// * networking/ovn_kubernetes_network_provider/assigning-egress-ips-ovn.adoc

ifeval::["{context}" == "egress-ips"]
:openshift-sdn:
endif::[]
ifeval::["{context}" == "configuring-egress-ips-ovn"]
:ovn:
endif::[]

ifdef::ovn[]
[id="nw-egress-ips-about_{context}"]
= Egress IP address architectural design and implementation

The {product-title} egress IP address functionality allows you to ensure that the traffic from one or more pods in one or more namespaces has a consistent source IP address for services outside the cluster network.

For example, you might have a pod that periodically queries a database that is hosted on a server outside of your cluster. To enforce access requirements for the server, a packet filtering device is configured to allow traffic only from specific IP addresses.
To ensure that you can reliably allow access to the server from only that specific pod, you can configure a specific egress IP address for the pod that makes the requests to the server.

An egress IP address is implemented as an additional IP address on the primary network interface of a node and must be in the same subnet as the primary IP address of the node. The additional IP address must not be assigned to any other node in the cluster.

[id="nw-egress-ips-platform-support_{context}"]
== Platform support

Support for the egress IP address functionality on various platforms is summarized in the following table:

[IMPORTANT]
====
The egress IP address implementation is not compatible with Amazon Web Services (AWS), Azure Cloud, or any other public cloud platform incompatible with the automatic layer 2 network manipulation required by the egress IP feature.
====

[cols="1,1",options="header"]
|===

| Platform | Supported

| Bare metal | Yes
| vSphere | Yes
| {rh-openstack-first} | No
| Public cloud | No

|===

[id="nw-egress-ips-considerations_{context}"]
== Assignment of egress IPs to pods

To assign one or more egress IPs to a namespace or specific pods in a namespace, the following conditions must be satisfied:

- At least one node in your cluster must have the `k8s.ovn.org/egress-assignable: ""` label.
- An `EgressIP` object exists that defines one or more egress IP addresses to use as the source IP address for traffic leaving the cluster from pods in a namespace.

[IMPORTANT]
====
If you create `EgressIP` objects prior to labeling any nodes in your cluster for egress IP assignment, {product-title} might assign every egress IP address to the first node with the `k8s.ovn.org/egress-assignable: ""` label.

To ensure that egress IP addresses are widely distributed across nodes in the cluster, always apply the label to the nodes you intent to host the egress IP addresses before creating any `EgressIP` objects.
====

[id="nw-egress-ips-node-assignment_{context}"]
== Assignment of egress IPs to nodes

When creating an `EgressIP` object, the following conditions apply to nodes that are labeled with the `k8s.ovn.org/egress-assignable: ""` label:

- An egress IP address is never assigned to more than one node at a time.
- An egress IP address is equally balanced between available nodes that can host the egress IP address.
- If the `spec.EgressIPs` array in an `EgressIP` object specifies more than one IP address, no node will ever host more than one of the specified addresses.
- If a node becomes unavailable, any egress IP addresses assigned to it are automatically reassigned, subject to the previously described conditions.

When a pod matches the selector for multiple `EgressIP` objects, there is no guarantee which of the egress IP addresses that are specified in the `EgressIP` objects is assigned as the egress IP address for the pod.

[id="nw-egress-ips-node-architecture_{context}"]
== Architectural diagram of an egress IP address configuration

The following diagram depicts an egress IP address configuration. The diagram describes four pods in two different namespaces running on three nodes in a cluster. The nodes are assigned IP addresses from the `192.168.126.0/18` CIDR block on the host network.

// Source: https://github.com/redhataccess/documentation-svg-assets/blob/master/for-web/121_OpenShift/121_OpenShift_engress_IP_Topology_1020.svg
image::nw-egress-ips-diagram.svg[Architectural diagram for the egress IP feature.]

Both Node 1 and Node 3 are labeled with `k8s.ovn.org/egress-assignable: ""` and thus available for the assignment of egress IP addresses.

The dashed lines in the diagram depict the traffic flow from pod1, pod2, and pod3 traveling through the pod network to egress the cluster from Node 1 and Node 3. When an external service receives traffic from any of the pods selected by the example `EgressIP` object, the source IP address is either `192.168.126.10` or `192.168.126.102`.

The following resources from the diagram are illustrated in detail:

`Namespace` objects::
+
--
The namespaces are defined in the following manifest:

.Namespace objects
[source,yaml]
----
apiVersion: v1
kind: Namespace
metadata:
  name: namespace1
  labels:
    env: prod
---
apiVersion: v1
kind: Namespace
metadata:
  name: namespace2
  labels:
    env: prod
----<commit_msg>Multiple egressIPs are load balanced with OVN-Kubernetes<commit_after>// Module included in the following assemblies:
//
// * networking/openshift_sdn/assigning-egress-ips.adoc
// * networking/ovn_kubernetes_network_provider/assigning-egress-ips-ovn.adoc

ifeval::["{context}" == "egress-ips"]
:openshift-sdn:
endif::[]
ifeval::["{context}" == "configuring-egress-ips-ovn"]
:ovn:
endif::[]

ifdef::ovn[]
[id="nw-egress-ips-about_{context}"]
= Egress IP address architectural design and implementation

The {product-title} egress IP address functionality allows you to ensure that the traffic from one or more pods in one or more namespaces has a consistent source IP address for services outside the cluster network.

For example, you might have a pod that periodically queries a database that is hosted on a server outside of your cluster. To enforce access requirements for the server, a packet filtering device is configured to allow traffic only from specific IP addresses.
To ensure that you can reliably allow access to the server from only that specific pod, you can configure a specific egress IP address for the pod that makes the requests to the server.

An egress IP address is implemented as an additional IP address on the primary network interface of a node and must be in the same subnet as the primary IP address of the node. The additional IP address must not be assigned to any other node in the cluster.

[id="nw-egress-ips-platform-support_{context}"]
== Platform support

Support for the egress IP address functionality on various platforms is summarized in the following table:

[IMPORTANT]
====
The egress IP address implementation is not compatible with Amazon Web Services (AWS), Azure Cloud, or any other public cloud platform incompatible with the automatic layer 2 network manipulation required by the egress IP feature.
====

[cols="1,1",options="header"]
|===

| Platform | Supported

| Bare metal | Yes
| vSphere | Yes
| {rh-openstack-first} | No
| Public cloud | No

|===

[id="nw-egress-ips-considerations_{context}"]
== Assignment of egress IPs to pods

To assign one or more egress IPs to a namespace or specific pods in a namespace, the following conditions must be satisfied:

- At least one node in your cluster must have the `k8s.ovn.org/egress-assignable: ""` label.
- An `EgressIP` object exists that defines one or more egress IP addresses to use as the source IP address for traffic leaving the cluster from pods in a namespace.

[IMPORTANT]
====
If you create `EgressIP` objects prior to labeling any nodes in your cluster for egress IP assignment, {product-title} might assign every egress IP address to the first node with the `k8s.ovn.org/egress-assignable: ""` label.

To ensure that egress IP addresses are widely distributed across nodes in the cluster, always apply the label to the nodes you intent to host the egress IP addresses before creating any `EgressIP` objects.
====

[id="nw-egress-ips-node-assignment_{context}"]
== Assignment of egress IPs to nodes

When creating an `EgressIP` object, the following conditions apply to nodes that are labeled with the `k8s.ovn.org/egress-assignable: ""` label:

- An egress IP address is never assigned to more than one node at a time.
- An egress IP address is equally balanced between available nodes that can host the egress IP address.
- If the `spec.EgressIPs` array in an `EgressIP` object specifies more than one IP address, the following conditions apply:
* No node will ever host more than one of the specified IP addresses.
* Traffic is balanced roughly equally between the specified IP addresses for a given namespace.
- If a node becomes unavailable, any egress IP addresses assigned to it are automatically reassigned, subject to the previously described conditions.

When a pod matches the selector for multiple `EgressIP` objects, there is no guarantee which of the egress IP addresses that are specified in the `EgressIP` objects is assigned as the egress IP address for the pod.

[id="nw-egress-ips-node-architecture_{context}"]
== Architectural diagram of an egress IP address configuration

The following diagram depicts an egress IP address configuration. The diagram describes four pods in two different namespaces running on three nodes in a cluster. The nodes are assigned IP addresses from the `192.168.126.0/18` CIDR block on the host network.

// Source: https://github.com/redhataccess/documentation-svg-assets/blob/master/for-web/121_OpenShift/121_OpenShift_engress_IP_Topology_1020.svg
image::nw-egress-ips-diagram.svg[Architectural diagram for the egress IP feature.]

Both Node 1 and Node 3 are labeled with `k8s.ovn.org/egress-assignable: ""` and thus available for the assignment of egress IP addresses.

The dashed lines in the diagram depict the traffic flow from pod1, pod2, and pod3 traveling through the pod network to egress the cluster from Node 1 and Node 3. When an external service receives traffic from any of the pods selected by the example `EgressIP` object, the source IP address is either `192.168.126.10` or `192.168.126.102`. The traffic is balanced roughly equally between these two nodes.

The following resources from the diagram are illustrated in detail:

`Namespace` objects::
+
--
The namespaces are defined in the following manifest:

.Namespace objects
[source,yaml]
----
apiVersion: v1
kind: Namespace
metadata:
  name: namespace1
  labels:
    env: prod
---
apiVersion: v1
kind: Namespace
metadata:
  name: namespace2
  labels:
    env: prod
----
{'fraction_non_alphanumeric': 0.06981710147618606, 'fraction_numerical': 0.0116980781728716, 'mean_word_length': 4.642744892613934, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 6, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1342531', 'n_tokens_mistral': 2950, 'n_tokens_neox': 2815, 'n_words': 1455}