From a077bc9d85e7b6851e0cbb7bc03422fd907e5ca6 Mon Sep 17 00:00:00 2001
From: bmcelvee <bmcelvee@redhat.com>
Date: Fri, 22 Jan 2021 16:07:37 -0500
Subject: [PATCH] OSDOCS-1772 document dual-stack router configuration

---
 modules/nw-router-configuring-dual-stack.adoc | 76 +++++++++++++++++++
 networking/routes/route-configuration.adoc    |  2 +
 2 files changed, 78 insertions(+)
 create mode 100644 modules/nw-router-configuring-dual-stack.adoc

diff --git a/modules/nw-router-configuring-dual-stack.adoc b/modules/nw-router-configuring-dual-stack.adoc
new file mode 100644
index 0000000000..7025990209
--- /dev/null
+++ b/modules/nw-router-configuring-dual-stack.adoc
@@ -0,0 +1,76 @@
+// Module included in the following assemblies:
+//
+// * networking/routes/route-configuration.adoc
+
+[id="nw-router-configuring-dual-stack_{context}"]
+= Configuring the {product-title} Ingress Controller for dual-stack networking
+
+If your {product-title} cluster is configured for IPv4 and IPv6 dual-stack networking, your cluster is is externally reachable by {product-title} routes.
+
+The Ingress Controller automatically serves services that have both IPv4 and IPv6 endpoints, but you can configure the Ingress Controller for single-stack or dual-stack services.
+
+.Prerequisites
+
+* You deployed an {product-title} cluster on bare metal.
+* You installed the OpenShift CLI (`oc`).
+
+.Procedure
+
+. To have the Ingress Controller serve traffic over IPv4/IPv6 to a workload, you can create a service YAML file or modify an existing service YAML file by setting the `ipFamilies` and `ipFamilyPolicy` fields. For example:
++
+.Sample service YAML file
+[source,yaml]
+----
+apiVersion: v1
+  kind: Service
+  metadata:
+    creationTimestamp: yyyy-mm-ddT00:00:00Z
+    labels:
+      name: <service_name>
+      manager: kubectl-create
+      operation: Update
+      time: yyyy-mm-ddT00:00:00Z
+    name: <service_name>
+    namespace: <namespace_name>
+    resourceVersion: "<resource_version_number>"
+    selfLink: "/api/v1/namespaces/<namespace_name>/services/<service_name>"
+    uid: <uid_number>
+  spec:
+    clusterIP: 172.30.0.0/16
+    clusterIPs: <1>
+    - 172.30.0.0/16
+    - <second_IP_address>
+    ipFamilies: <2>
+    - IPv4
+    - IPv6
+    ipFamilyPolicy: RequireDualStack <3>
+    ports:
+    - port: 8080
+      protocol: TCP
+      targetport: 8080
+    selector:
+      name: <namespace_name>
+    sessionAffinity: None
+    type: ClusterIP
+  status:
+    loadbalancer: {}
+----
+<1> In a dual-stack instance, there are two different `clusterIPs` provided.
+<2> For a single-stack instance, enter `IPv4` or `IPv6`. For a dual-stack instance, enter both `IPv4` and `IPv6`.
+<3> For a single-stack instance, enter `SingleStack`. For a dual-stack instance, enter `RequireDualStack`.
++
+These resources generate corresponding `endpoints`. The Ingress Controller now watches `endpointslices`.
++
+. To view `endpoints`, enter the following command:
++
+[source,terminal]
+----
+$ oc get endpoints
+----
++
+. To view `endpointslices`, enter the following command:
++
+[source,terminal]
+----
+$ oc get endpointslices
+----
diff --git a/networking/routes/route-configuration.adoc b/networking/routes/route-configuration.adoc
index 0c7aac089a..466f52af31 100644
--- a/networking/routes/route-configuration.adoc
+++ b/networking/routes/route-configuration.adoc
@@ -27,3 +27,5 @@ include::modules/nw-route-specific-annotations.adoc[leveloffset=+1]
 include::modules/nw-route-admission-policy.adoc[leveloffset=+1]
 
 include::modules/nw-ingress-creating-a-route-via-an-ingress.adoc[leveloffset=+1]
+
+include::modules/nw-router-configuring-dual-stack.adoc[leveloffset=+1]