OSDOCS-3417: separate out sharding docs

Author: jldohmann

_topic_maps/_topic_map.yml

@@ -1074,6 +1074,8 @@ Topics:
 - Name: Understanding the Ingress Operator
   File: ingress-operator
   Distros: openshift-enterprise,openshift-origin
+- Name: Ingress sharding
+  File: ingress-sharding
 - Name: Understanding the Ingress Node Firewall Operator
   File: ingress-node-firewall-operator
   Distros: openshift-enterprise,openshift-origin

images/nw-sharding-namespace-labels.png

@@ -0,0 +1,55 @@
+// Module include in the following assemblies:
+//
+// * ingress-operator.adoc
+// * networking/ingress-sharding.adoc
+
+:_content-type: PROCEDURE
+[id="nw-ingress-sharding-default_{context}"]
+= Sharding the default Ingress Controller
+
+After creating a new Ingress shard, there might be routes that are admitted to your new Ingress shard that are also admitted by the default Ingress Controller. This is because the default Ingress Controller has no selectors and admits all routes by default.
+
+You can restrict an Ingress Controller from servicing routes with specific labels using either namespace selectors or route selectors. The following procedure restricts the default Ingress Controller from servicing your newly sharded `finance`, `ops`, and `dev`, routes using a namespace selector. This adds further isolation to Ingress shards.
+
+[IMPORTANT]
+====
+You must keep all of {product-title}'s administration routes on the same Ingress Controller. Therefore, avoid adding additional selectors to the default Ingress Controller that exclude these essential routes.
+====
+
+.Prerequisites
+
+* You installed the OpenShift CLI (`oc`).
+* You are logged in as a project administrator.
+
+.Procedure
+
+. Modify the default Ingress Controller by running the following command:
++
+[source,terminal]
+----
+$ oc edit ingresscontroller -n openshift-ingress-operator default
+----
+
+. Edit the Ingress Controller to contain a `namespaceSelector` that excludes the routes with any of the `finance`, `ops`, and `dev` labels:
++
+[source,yaml]
+----
+apiVersion: v1
+items:
+- apiVersion: operator.openshift.io/v1
+  kind: IngressController
+  metadata:
+    name: default
+    namespace: openshift-ingress-operator
+  spec:
+  namespaceSelector:
+    matchExpressions:
+    - key: type
+      operator: NotIn
+      values:
+      - finance
+      - ops
+      - dev
+----
+
+The default Ingress Controller will no longer serve the namespaces labeled `name:finance`, `name:ops`, and `name:dev`.

images/nw-sharding-route-labels.png

@@ -0,0 +1,19 @@
+// Module included in the folllowing assemblies:
+//
+// * networking/ingress-sharding.adoc
+
+:_content-type: CONCEPT
+[id="nw-ingress-sharding-dns_{context}"]
+= Ingress sharding and DNS
+
+The cluster administrator is responsible for making a separate DNS entry for each router in a project. A router will not forward unknown routes to another router.
+
+Consider the following example:
+
+* Router A lives on host 192.168.0.5 and has routes with `*.foo.com`.
+* Router B lives on host 192.168.1.9 and has routes with `*.example.com`.
+
+Separate DNS entries must resolve `\*.foo.com` to the node hosting Router A and `*.example.com` to the node hosting Router B:
+
+* `*.foo.com A IN 192.168.0.5`
+* `*.example.com A IN 192.168.1.9`

modules/nw-ingress-sharding-default.adoc

@@ -11,16 +11,14 @@ Ingress Controller sharding by using namespace labels means that the Ingress
 Controller serves any route in any namespace that is selected by the namespace
 selector.
 
+.Ingress sharding using namespace labels
+image::nw-sharding-namespace-labels.png[A diagram showing multiple Ingress Controllers with different namespace selectors serving routes that belong to the namespace containing a label that matches a given namespace selector]
+
 Ingress Controller sharding is useful when balancing incoming traffic load among
 a set of Ingress Controllers and when isolating traffic to a specific Ingress
 Controller. For example, company A goes to one Ingress Controller and company B
 to another.
 
-[WARNING]
-====
-If you deploy the Keepalived Ingress VIP, do not deploy a non-default Ingress Controller with value `HostNetwork` for the `endpointPublishingStrategy` parameter. Doing so might cause issues. Use value `NodePort` instead of `HostNetwork` for `endpointPublishingStrategy`.
-====
-
 .Procedure
 
 . Edit the `router-internal.yaml` file:

modules/nw-ingress-sharding-dns.adoc

@@ -11,6 +11,9 @@ Ingress Controller sharding by using route labels means that the Ingress
 Controller serves any route in any namespace that is selected by the route
 selector.
 
+.Ingress sharding using route labels
+image::nw-sharding-route-labels.png[A diagram showing multiple Ingress Controllers with different route selectors serving any route containing a label that matches a given route selector regardless of the namespace a route belongs to]
+
 Ingress Controller sharding is useful when balancing incoming traffic load among
 a set of Ingress Controllers and when isolating traffic to a specific Ingress
 Controller. For example, company A goes to one Ingress Controller and company B

modules/nw-ingress-sharding-namespace-labels.adoc

@@ -1,17 +1,105 @@
 // Module included in the following assemblies:
 //
-// * configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc
 // * ingress-operator.adoc
+// * networking/ingress-sharding.adoc
 
+:_content-type: CONCEPT
 [id="nw-ingress-sharding_{context}"]
 = Ingress Controller sharding
 
-As the primary mechanism for traffic to enter the cluster, the demands on the Ingress Controller, or router, can be significant. As a cluster administrator, you can shard the routes to:
+You can use Ingress sharding, also known as router sharding, to distribute a set of routes across multiple routers by adding labels to routes, namespaces, or both. The Ingress Controller uses a corresponding set of selectors to admit only the routes that have a specified label. Each Ingress shard comprises the routes that are filtered using a given selection expression.
+
+As the primary mechanism for traffic to enter the cluster, the demands on the Ingress Controller can be significant. As a cluster administrator, you can shard the routes to:
 
 * Balance Ingress Controllers, or routers, with several routes to speed up responses to changes.
 * Allocate certain routes to have different reliability guarantees than other routes.
 * Allow certain Ingress Controllers to have different policies defined.
 * Allow only specific routes to use additional features.
 * Expose different routes on different addresses so that internal and external users can see different routes, for example.
+* Transfer traffic from one version of an application to another during a blue green deployment.
+
+When Ingress Controllers are sharded, a given route is admitted to zero or more Ingress Controllers in the group. A route's status describes whether an Ingress Controller has admitted it or not. An Ingress Controller will only admit a route if it is unique to its shard.
+
+An Ingress Controller can use three sharding methods:
+
+* Adding only a namespace selector to the Ingress Controller, so that all routes in a namespace with labels that match the namespace selector are in the Ingress shard.
+
+* Adding only a route selector to the Ingress Controller, so that all routes with labels that match the route selector are in the Ingress shard.
+
+* Adding both a namespace selector and route selector to the Ingress Controller, so that routes with labels that match the route selector in a namespace with labels that match the namespace selector are in the Ingress shard.
+
+With sharding, you can distribute subsets of routes over multiple Ingress Controllers. These subsets can be non-overlapping, also called _traditional_ sharding, or overlapping, otherwise known as _overlapped_ sharding.
+
+== Traditional sharding example
+
+An Ingress Controller `finops-router` is configured with the label selector `spec.namespaceSelector.matchLabels.name` set to `finance` and `ops`:
+
+.Example YAML definition for `finops-router`
+[source,yaml]
+----
+apiVersion: v1
+items:
+- apiVersion: operator.openshift.io/v1
+  kind: IngressController
+  metadata:
+    name: finops-router
+    namespace: openshift-ingress-operator
+  spec:
+    namespaceSelector:
+      matchLabels:
+        name:
+          - finance
+          - ops
+----
+
+A second Ingress Controller `dev-router` is configured with the label selector `spec.namespaceSelector.matchLabels.name` set to `dev`:
+
+.Example YAML definition for `dev-router`
+[source,yaml]
+----
+apiVersion: v1
+items:
+- apiVersion: operator.openshift.io/v1
+  kind: IngressController
+  metadata:
+    name: dev-router
+    namespace: openshift-ingress-operator
+  spec:
+    namespaceSelector:
+      matchLabels:
+        name: dev
+----
+
+If all application routes are in separate namespaces, each labeled with `name:finance`, `name:ops`, and `name:dev` respectively, this configuration effectively distributes your routes between the two Ingress Controllers. {product-title} routes for console, authentication, and other purposes should not be handled.
+
+In the above scenario, sharding becomes a special case of partitioning, with no overlapping subsets. Routes are divided between router shards.
+
+[WARNING]
+====
+The `default` Ingress Controller continues to serve all routes unless the `namespaceSelector` or `routeSelector` fields contain routes that are meant for exclusion. See this link:https://access.redhat.com/solutions/5097511[Red Hat Knowledgebase solution] and the section "Sharding the default Ingress Controller" for more information on how to exclude routes from the default Ingress Controller.
+====
+
+== Overlapped sharding example
+
+In addition to `finops-router` and `dev-router` in the example above, you also have `devops-router`, which is configured with the label selector `spec.namespaceSelector.matchLabels.name` set to `dev` and `ops`:
+
+.Example YAML definition for `devops-router`
+[source,yaml]
+----
+apiVersion: v1
+items:
+- apiVersion: operator.openshift.io/v1
+  kind: IngressController
+  metadata:
+    name: devops-router
+    namespace: openshift-ingress-operator
+  spec:
+    namespaceSelector:
+      matchLabels:
+        name:
+          - dev
+          - ops
+----
+The routes in the namespaces labeled `name:dev` and `name:ops` are now serviced by two different Ingress Controllers. With this configuration, you have overlapping subsets of routes.
 
-Ingress Controller can use either route labels or namespace labels as a sharding method.
+With overlapping subsets of routes you can create more complex routing rules. For example, you can divert higher priority traffic to the dedicated `finops-router` while sending lower priority traffic to `devops-router`.

modules/nw-ingress-sharding-route-labels.adoc

@@ -69,6 +69,8 @@ include::modules/nw-ingress-setting-thread-count.adoc[leveloffset=+2]
 
 include::modules/nw-ingress-sharding.adoc[leveloffset=+2]
 
+include::modules/nw-ingress-sharding-default.adoc[leveloffset=+3]
+
 include::modules/nw-ingress-sharding-route-labels.adoc[leveloffset=+3]
 
 include::modules/nw-ingress-sharding-namespace-labels.adoc[leveloffset=+3]

modules/nw-ingress-sharding.adoc

@@ -0,0 +1,32 @@
+:_content-type: ASSEMBLY
+[id="ingress-sharding"]
+= Ingress sharding in {product-title}
+include::_attributes/common-attributes.adoc[]
+:context: ingress-sharding
+
+toc::[]
+
+In {product-title}, an Ingress Controller can serve all routes, or it can serve a subset of routes. By default, the Ingress Controller serves any route created in any namespace in the cluster. You can add additional Ingress Controllers to your cluster to optimize routing by creating _shards_, which are subsets of routes based on selected characteristics. To mark a route as a member of a shard, use labels in the route or namespace `metadata` field. The Ingress Controller uses _selectors_, also known as a _selection expression_, to select a subset of routes from the entire pool of routes to serve.
+
+Ingress sharding is useful in cases where you want to load balance incoming traffic across multiple Ingress Controllers, when you want to isolate traffic to be routed to a specific Ingress Controller, or for a variety of other reasons described in the next section.
+
+By default, each route uses the default domain of the cluster. However, routes can be configured to use the domain of the router instead. For more information, see xref:../networking/ingress-sharding.adoc#nw-ingress-sharding-route-configuration_ingress-sharding[Creating a route for Ingress Controller Sharding].
+
+include::modules/nw-ingress-sharding.adoc[leveloffset=+1]
+
+include::modules/nw-ingress-sharding-default.adoc[leveloffset=+2]
+
+include::modules/nw-ingress-sharding-dns.adoc[leveloffset=+2]
+
+include::modules/nw-ingress-sharding-route-labels.adoc[leveloffset=+2]
+
+include::modules/nw-ingress-sharding-namespace-labels.adoc[leveloffset=+2]
+
+include::modules/nw-ingress-sharding-route-configuration.adoc[leveloffset=+1]
+
+[discrete]
+[role="_additional-resources"]
+[id="additional-resources_ingress-sharding"]
+== Additional Resources
+
+* xref:../scalability_and_performance/routing-optimization.adoc#baseline-router-performance_routing-optimization[Baseline Ingress Controller (router) performance]