Add OVN-Kubernetes egress IP support [4.6]

_topic_map.yml

@@ -675,6 +675,10 @@ Topics:
     File: editing-egress-firewall-ovn
   - Name: Removing an egress firewall from a project
     File: removing-egress-firewall-ovn
+  - Name: Configuring an egress IP address
+    File: configuring-egress-ips-ovn
+  - Name: Assigning an egress IP address
+    File: assigning-egress-ips-ovn
   - Name: Enabling multicast for a project
     File: enabling-multicast
   - Name: Disabling multicast for a project

modules/nw-egress-ips-about.adoc

@@ -1,7 +1,115 @@
 // Module included in the following assemblies:
 //
-// * networking/assigning-egress-ips.adoc
+// * 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::[]
+
+:rhosp: Red Hat OpenStack Platform
+
+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
+
+While you can use the egress IP address functionality on any platform that {product-title} supports, the following platform specific considerations apply:
+
+Cloud platforms::
+Additional IP addresses must be assigned manually to appropriate nodes by an administrator.
+
+{rhosp}::
+Additional configuration by an administrator is necessary to allow {product-title} to automatically assign additional IP addresses to nodes.
+
+vSphere::
+Additional configuration by an administrator is necessary to allow {product-title} to automatically assign additional IP addresses to nodes.
+
+[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 is deleted by a cluster administrator, any egress IP addresses assigned to it are automatically reassigned, subject to the previously described conditions.
+
+////
+(True after BZ-1877273 is resolved.)
+- 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 the relationship between three nodes in a cluster and four pods running on that cluster in two different namespaces.
+
+// 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 following `EgressIP` object describes a configuration that selects all pods in the `namespace1` namespace, with the `192.168.126.10` and `192.168.126.102` egress IP addresses specified.
+
+.`EgressIP` object
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: EgressIP
+metadata:
+  name: egressips
+spec:
+  egressIPs:
+  - 192.168.126.10
+  - 192.168.126.102
+  namespaceSelector:
+    matchLabels:
+      name: namespace1
+status:
+  assignments:
+  - node: node1
+    egressIP: 192.168.126.10
+  - node: node3
+    egressIP: 192.168.126.102
+----
+
+After creating the `EgressIP` object, {product-title} assigns both egress IP addresses to the available nodes. The `status` field reflects the whether and where the egress IP addresses are assigned.
+
+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`.
+endif::ovn[]
+
+ifdef::openshift-sdn[]
 [id="nw-egress-ips-about_{context}"]
 = Egress IP address assignment for project egress traffic
 
@@ -59,3 +167,13 @@ When using the manual assignment approach for egress IP addresses the following
 When a namespace has multiple egress IP addresses, if the node hosting the first egress IP address is unreachable, {product-title} will automatically switch to using the next available egress IP address until the first egress IP address is reachable again.
 
 This approach is recommended for clusters installed in public cloud environments, where there can be limitations on associating additional IP addresses with nodes.
+endif::openshift-sdn[]
+
+ifdef::openshift-sdn[]
+:!openshift-sdn:
+endif::openshift-sdn[]
+ifdef::ovn[]
+:!ovn:
+endif::ovn[]
+
+:!rhosp:

modules/nw-egress-ips-assign.adoc

@@ -0,0 +1,51 @@
+// Module included in the following assemblies:
+//
+// * networking/ovn_kubernetes_network_provider/assigning-egress-ips-ovn.adoc
+
+[id="nw-egress-ips-assign_{context}"]
+= Assigning an egress IP address to a namespace
+
+You can assign one or more egress IP addresses to a namespace or to specific pods in a namespace.
+
+.Prerequisites
+
+* Install the OpenShift CLI (`oc`).
+* Log in to the cluster as a cluster administrator.
+* Configure at least one node to host an egress IP address.
+
+.Procedure
+
+. Create an `EgressIP` object:
+.. Create a `<egressips_name>.yaml` file where `<egressips_name>` is the name of the object.
+.. In the file that you created, define an `EgressIPs` object, as in the following example:
++
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: EgressIP
+metadata:
+  name: egress-project1
+spec:
+  egressIPs:
+  - 192.168.127.10
+  - 192.168.127.11
+  namespaceSelector:
+    matchLabels:
+      name: project1
+----
+
+. To create the object, enter the following command.
++
+[source,terminal]
+----
+$ oc apply -f <egressips_name>.yaml <1>
+----
+<1> Replace `<egressips_name>` with the name of the object.
++
+.Example output
+[source,terminal]
+----
+egressips.k8s.ovn.org/<egressips_name> created
+----
+
+. Optional: Save the `<egressips_name>.yaml` file so that you can make changes later.

modules/nw-egress-ips-node.adoc

@@ -0,0 +1,24 @@
+// Module included in the following assemblies:
+//
+// * networking/ovn_kubernetes_network_provider/configuring-egress-ips-ovn.adoc
+
+[id="nw-egress-ips-node_{context}"]
+= Labeling a node to host egress IP addresses
+
+You can apply the `k8s.ovn.org/egress-assignable=""` label to a node in your cluster so that {product-title} can assign one or more egress IP addresses to the node.
+
+.Prerequisites
+
+* Install the OpenShift CLI (`oc`).
+* Log in to the cluster as a cluster administrator.
+
+.Procedure
+
+* To label a node so that it can host one or more egress IP addresses, enter the following command:
++
+[source,terminal]
+----
+$ oc label nodes <node_name> k8s.ovn.org/egress-assignable="" <1>
+----
++
+<1> The name of the node to label.

modules/nw-egress-ips-object.adoc

@@ -0,0 +1,94 @@
+// Module included in the following assemblies:
+//
+// * networking/ovn_kubernetes_network_provider/assigning-egress-ips-ovn.adoc
+
+[id="nw-egress-ips-object_{context}"]
+= EgressIP object
+
+The following YAML describes the API for the `EgressIP` object. The scope of the object is cluster-wide; it is not created in a namespace.
+
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: EgressIP
+metadata:
+  name: <name> <1>
+spec:
+  egressIPs: <2>
+  - <ip_address>
+  namespaceSelector: <3>
+    ...
+  podSelector: <4>
+    ...
+----
+<1> The name for the `EgressIPs` object.
+
+<2> An array of one or more IP addresses.
+
+<3> One or more selectors for the namespaces to associate the egress IP addresses with.
+
+<4> Optional: One or more selectors for pods in the specified namespaces to associate egress IP addresses with. Applying these selectors allows for the selection of a subset of pods within a namespace.
+
+The following YAML describes the stanza for the namespace selector:
+
+.Namespace selector stanza
+[source,yaml]
+----
+namespaceSelector: <1>
+  matchLabels:
+    name: <namespace_name>
+----
+<1> One or more matching rules for namespaces. If more than one match rule is provided, all matching namespaces are selected.
+
+The following YAML describes the optional stanza for the pod selector:
+
+.Pod selector stanza
+[source,yaml]
+----
+podSelector: <1>
+  matchLabels:
+    name: <pod_name>
+----
+<1> Optional: One or more matching rules for pods in the namespaces that match the specified `namespaceSelector` rules. If specified, only pods that match are selected. Others pods in the namespace are not selected.
+
+In the following example, the `EgressIP` object associates the `192.168.126.11` and `192.168.126.102` egress IP addresses with the pod that is named `my-pod` in the namespace that is named `my-namespace`:
+
+.Example `EgressIP` object
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: EgressIP
+metadata:
+  name: egress-group1
+spec:
+  egressIPs:
+  - 192.168.126.11
+  - 192.168.126.102
+  podSelector:
+    matchLabels:
+      name: my-pod
+  namespaceSelector:
+    matchLabels:
+      name: my-namespace
+----
+
+In the following example, the `EgressIP` object associates the `192.168.127.30` and `192.168.127.40` egress IP addresses with any pods that do not have the `environment` label set to `development`:
+
+.Example `EgressIP` object
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: EgressIP
+metadata:
+  name: egress-group2
+spec:
+  egressIPs:
+  - 192.168.127.30
+  - 192.168.127.40
+  namespaceSelector:
+    matchExpressions:
+    - key: environment
+      operator: NotIn
+      values:
+      - development
+----