OSDOCS-1855: OVN Egress Router

Replace old doc with the new process that uses
the `EgressRouter` object.

Feedback from Daniel:
* Acknowledge that the Operator adds the NAD and deployment.
* The operator also removes them when an egress router is
  deleted.
* Change "Failover config" to describe the deployment and
  mention svc rather that suggest customers can do this for
  themselves.

Remove the technology preview admonition.

Remove file modules/nw-egress-router-network-attachment.adoc because
customers do not need to make the NAD themselves after this release.

Change from "Partial support" to "Supported" in the
Supported default CNI network provider feature matrix and change
the numbering to be *more* sequential.

Add `fallbackIP` based on openshift/cluster-network-operator#1094.

Specify IP address in CIDR notation. Correction from Mohamed. Remove
the `spec.networkInterface` field, also from Mohamed.

Update migration process to indicate redirect is supported and
that HTTP mode and DNS mode are not supported. Also indicate
that the Operator does not offer a provision for a node selector.

Add `metadata.namespace` to the YAML.

Review from Ashley.

Author: mikemckiernan

modules/nw-egress-router-about.adoc

@@ -21,7 +21,7 @@ endif::[]
 [id="nw-egress-router-about_{context}"]
 = About an egress router pod
 
-The {product-title} egress router pod redirects traffic to a specified remote server from a private source IP address that is not used for any other purpose. An egress router pod enables you to send network traffic to servers that are set up to allow access only from specific IP addresses.
+The {product-title} egress router pod redirects traffic to a specified remote server from a private source IP address that is not used for any other purpose. An egress router pod can send network traffic to servers that are set up to allow access only from specific IP addresses.
 
 [NOTE]
 ====
@@ -49,7 +49,7 @@ endif::openshift-sdn[]
 ifdef::ovn[]
 [NOTE]
 ====
-The egress router CNI plug-in supports redirect mode only. This is a difference with the egress router implementation that you can deploy with OpenShift SDN. Unlike the egress router for OpenShift SDN, the egress router CNI plug-in does not support _HTTP proxy mode_ or _DNS proxy mode_.
+The egress router CNI plug-in supports redirect mode only. This is a difference with the egress router implementation that you can deploy with OpenShift SDN. Unlike the egress router for OpenShift SDN, the egress router CNI plug-in does not support HTTP proxy mode or DNS proxy mode.
 ====
 endif::ovn[]
 
@@ -73,6 +73,14 @@ An egress router is a pod that has two network interfaces. For example, the pod
 
 Traffic that leaves the egress router exits through a node, but the packets
 have the MAC address of the `net1` interface from the egress router pod.
+
+When you add an egress router custom resource, the Cluster Network Operator creates the following objects:
+
+* The network attachment definition for the `net1` secondary network interface of the pod.
+
+* A deployment for the egress router.
+
+If you delete an egress router custom resource, the Operator deletes the two objects in the preceding list that are associated with the egress router.
 endif::ovn[]
 
 [id="nw-egress-router-about-deployments_{context}"]
@@ -107,9 +115,9 @@ Specifically, ensure that the following are enabled:
 [id="nw-egress-router-about-failover_{context}"]
 == Failover configuration
 
+ifdef::openshift-sdn[]
 To avoid downtime, you can deploy an egress router pod with a `Deployment` resource, as in the following example. To create a new `Service` object for the example deployment, use the `oc expose deployment/egress-demo-controller` command.
 
-ifdef::openshift-sdn[]
 [source,yaml,subs="attributes+"]
 ----
 apiVersion: apps/v1
@@ -134,36 +142,38 @@ spec:
       containers:
         ...
 ----
+<1> Ensure that replicas is set to `1`, because only one pod can use a given egress source IP address at any time. This means that only a single copy of the router runs on a node.
+
+<2> Specify the `Pod` object template for the egress router pod.
 endif::openshift-sdn[]
 
 ifdef::ovn[]
+To avoid downtime, the Cluster Network Operator deploys the egress router pod as a deployment resource. The deployment name is `egress-router-cni-deployment`. The pod that corresponds to the deployment has a label of `app=egress-router-cni`.
+
+To create a new service for the deployment, use the `oc expose deployment/egress-router-cni-deployment --port <port_number>` command or create a file like the following example:
+
 [source,yaml,subs="attributes+"]
 ----
-apiVersion: apps/v1
-kind: Deployment
+apiVersion: v1
+kind: Service
 metadata:
-  name: egress-demo-controller
+  name: app-egress
 spec:
-  replicas: 1  <1>
+  ports:
+  - name: tcp-8080
+    protocol: TCP
+    port: 8080
+  - name: tcp-8443
+    protocol: TCP
+    port: 8443
+  - name: udp-80
+    protocol: UDP
+    port: 80
+  type: ClusterIP
   selector:
-    matchLabels:
-      name: egress-router
-  template:
-    metadata:
-      name: egress-router
-      labels:
-        name: egress-router
-      annotations:
-        k8s.v1.cni.cncf.io/networks: egress-router-redirect
-    spec:  <2>
-      containers:
-        - name: egress-router-redirect
-          image: {egress-pod-image-name}
+    app: egress-router-cni
 ----
 endif::ovn[]
-<1> Ensure that replicas is set to `1`, because only one pod can use a given egress source IP address at any time. This means that only a single copy of the router runs on a node.
-
-<2> Specify the `Pod` object template for the egress router pod.
 
 // Clear temporary attributes
 ifdef::openshift-sdn[]
@@ -173,4 +183,4 @@ endif::[]
 ifdef::ovn[]
 :!ovn:
 :!egress-pod-image-name:
-endif::[]
+endif::[]

modules/nw-egress-router-cr.adoc

@@ -0,0 +1,110 @@
+// Module included in the following assemblies:
+//
+// * networking/ovn_kubernetes_network_provider/deploying-egress-router-ovn-redirection.adoc
+
+ifeval::["{context}" == "deploying-egress-router-ovn-redirection"]
+:redirect:
+:router-type: redirect
+endif::[]
+:router-name: egress-router-{router-type}
+
+[id="nw-egress-router-ovn-cr_{context}"]
+= Egress router custom resource
+
+Define the configuration for an egress router pod in an egress router custom resource. The following YAML describes the fields for the configuration of an egress router in {router-type} mode:
+
+// cluster-network-operator/manifests/0000_70_cluster-network-operator_01_egr_crd.yaml
+[source,yaml,subs="attributes+"]
+----
+apiVersion: network.operator.openshift.io/v1
+kind: EgressRouter
+metadata:
+  name: <egress_router_name>
+  namespace: <namespace>  <.>
+spec:
+  addresses: [  <.>
+    {
+      ip: "<egress_router>",  <.>
+      gateway: "<egress_gateway>"  <.>
+    }
+  ]
+  mode: Redirect
+  redirect: {
+    redirectRules: [  <.>
+      {
+        destinationIP: "<egress_destination>",
+        port: <egress_router_port>,
+        targetPort: <target_port>,  <.>
+        protocol: <network_protocol>  <.>
+      },
+      ...
+    ],
+    fallbackIP: "<egress_destination>" <.>
+  }
+----
+// openshift/api:networkoperator/v1/001-egressrouter.crd.yaml
+<.> Optional: The `namespace` field specifies the namespace to create the egress router in. If you do not specify a value in the file or on the command line, the `default` namespace is used.
+
+<.> The `addresses` field specifies the IP addresses to configure on the secondary network interface.
+
+<.> The `ip` field specifies the reserved source IP address and netmask from the physical network that the node is on to use with egress router pod. Use CIDR notation to specify the IP address and netmask.
+
+<.> The `gateway` field specifies the IP address of the network gateway.
+
+<.> Optional: The `redirectRules` field specifies a combination of egress destination IP address, egress router port, and protocol. Incoming connections to the egress router on the specified port and protocol are routed to the destination IP address.
+
+<.> Optional: The `targetPort` field specifies the network port on the destination IP address. If this field is not specified, traffic is routed to the same network port that it arrived on.
+
+<.> The `protocol` field supports TCP, UDP, or SCTP.
+
+<.> Optional: The `fallbackIP` field specifies a destination IP address. If you do not specify any redirect rules, the egress router sends all traffic to this fallback IP address. If you specify redirect rules, any connections to network ports that are not defined in the rules are sent by the egress router to this fallback IP address. If you do not specify this field, the egress router rejects connections to network ports that are not defined in the rules.
+
+.Example egress router specification
+[source,yaml,subs="attributes+"]
+----
+apiVersion: network.operator.openshift.io/v1
+kind: EgressRouter
+metadata:
+  name: {router-name}
+spec:
+  networkInterface: {
+    macvlan: {
+      mode: "bridge"
+    }
+  }
+  addresses: [
+    {
+      ip: "192.168.12.99/24",
+      gateway: "192.168.12.1"
+    }
+  ]
+  mode: Redirect
+  redirect: {
+    redirectRules: [
+      {
+        destinationIP: "10.0.0.99",
+        port: 80,
+        protocol: UDP
+      },
+      {
+        destinationIP: "203.0.113.26",
+        port: 8080,
+        targetPort: 80,
+        protocol: TCP
+      },
+      {
+        destinationIP: "203.0.113.27",
+        port: 8443,
+        targetPort: 443,
+        protocol: TCP
+      }
+    ]
+  }
+----
+
+// clear temporary attributes
+:!router-name:
+:!router-type:
+ifdef::redirect[]
+:!redirect:
+endif::[]