Merge pull request #51239 from JStickler/OSSMDOC-520

OSSMDOC-520: Update traffic management headings and reorganize assembly.

Author: JStickler

modules/ossm-auto-route-annotations.adoc

@@ -3,13 +3,13 @@
 //
 
 [id="ossm-auto-route-annotations_{context}"]
-= {SMProductName} route labels and annotations
+= Route labels and annotations
 
-Sometimes specific labels or annotations are needed in an OpenShift Route.
+Sometimes specific labels or annotations are needed in an OpenShift route.
 ifdef::openshift-enterprise[]
-For example, some advanced features in OpenShift Routes are managed using special annotations. See "Route-specific annotations" in the following "Additional resources" section.
+For example, some advanced features in OpenShift routes are managed using special annotations. See "Route-specific annotations" in the following "Additional resources" section.
 endif::[]
 
-For this and other use cases, {SMProductName} will copy all labels and annotations present in the Istio Gateway resource (with the exception of annotations starting with `kubectl.kubernetes.io`) into the managed OpenShift Route resource.
+For this and other use cases, {SMProductName} will copy all labels and annotations present in the Istio gateway resource (with the exception of annotations starting with `kubectl.kubernetes.io`) into the managed OpenShift route resource.
 
-If you need specific labels or annotations in the OpenShift Routes created by {SMProductShortName}, create them in the Istio Gateway resource and they will be copied into the OpenShift Route resources managed by the {SMProductShortName}.
+If you need specific labels or annotations in the OpenShift routes created by {SMProductShortName}, create them in the Istio gateway resource and they will be copied into the OpenShift route resources managed by the {SMProductShortName}.

modules/ossm-auto-route-enable.adoc

@@ -3,24 +3,28 @@
 //
 :_content-type: REFERENCE
 [id="ossm-auto-route-enable_{context}"]
-= Disabling automatic creation of routes
+= Disabling automatic route creation
 
-By default, the `ServiceMeshControlPlane` resource automatically synchronizes the Gateway resources with OpenShift routes. Disabling the automatic route creation allows you more flexibility to control routes if you have a special case or prefer to control routes manually.
+By default, the `ServiceMeshControlPlane` resource automatically synchronizes the Istio gateway resources with OpenShift routes. Disabling the automatic route creation allows you more flexibility to control routes if you have a special case or prefer to control routes manually.
 
 [id="disabling-automatic-route-creation-specific-cases_{context}"]
 == Disabling automatic route creation for specific cases
 
-If you want to disable the automatic management of OpenShift routes for a specific Istio Gateway, you must add the annotation `maistra.io/manageRoute: false` to the Gateway metadata definition. {SMProductName} will ignore Istio Gateways with this annotation, while keeping the automatic management of the other Istio Gateways.
+If you want to disable the automatic management of OpenShift routes for a specific Istio gateway, you must add the annotation `maistra.io/manageRoute: false` to the gateway metadata definition. {SMProductName} will ignore Istio gateways with this annotation, while keeping the automatic management of the other Istio gateways.
 
 [id="disabling-automatic-route-creation-all-cases_{context}"]
 == Disabling automatic route creation for all cases
 
-You can disable the automatic management of OpenShift routes for all Gateways in your mesh.
+You can disable the automatic management of OpenShift routes for all gateways in your mesh.
 
-Disable integration between Istio Gateways and OpenShift Routes by setting the `ServiceMeshControlPlane` field `gateways.openshiftRoute.enabled` to `false`. For example, see the following resource snippet.
+Disable integration between Istio gateways and OpenShift routes by setting the `ServiceMeshControlPlane` field `gateways.openshiftRoute.enabled` to `false`. For example, see the following resource snippet.
 
 [source,yaml]
 ----
+apiVersion: maistra.io/v1alpha1
+kind:
+metadata:
+  namespace: istio-system
 spec:
   gateways:
     openshiftRoute:

modules/ossm-auto-route.adoc

@@ -27,7 +27,7 @@ spec:
     - bookinfo.example.com
 ----
 
-The 'Gateway' resource creates the following OpenShift Routes. You can check that the routes are created by using the following command. In this example, `istio-system` is the name of the {SMProductShortName} control plane project.
+The `Gateway` resource creates the following OpenShift routes. You can check that the routes are created by using the following command. In this example, `istio-system` is the name of the {SMProductShortName} control plane project.
 
 [source,terminal]
 ----
@@ -42,4 +42,4 @@ gateway1-lvlfn bookinfo.example.com        istio-ingressgateway   <all>
 gateway1-scqhv www.bookinfo.com            istio-ingressgateway   <all>               None
 ----
 
-If the gateway is deleted, {SMProductName} deletes the routes. However, routes created manually are never modified by {SMProductName}.
+If you delete the gateway, {SMProductName} deletes the routes. However, routes you have manually created are never modified by {SMProductName}.

modules/ossm-config-disable-networkpolicy.adoc

@@ -4,13 +4,13 @@ This module included in the following assemblies:
 ////
 :_content-type: PROCEDURE
 [id="ossm-config-disable-networkpolicy_{context}"]
-= Disabling automatic creation of network policies
+= Disabling automatic NetworkPolicy creation
 
-If you want to disable the automatic creation and management of `NetworkPolicy` resources, for example to enforce company security policies, or to allow direct access to pods in the mesh, you can do so.  You can edit the `ServiceMeshControlPlane` and set `spec.security.manageNetworkPolicy` to `false`.
+If you want to disable the automatic creation and management of `NetworkPolicy` resources, for example to enforce company security policies, or to allow direct access to pods in the mesh, you can do so. You can edit the `ServiceMeshControlPlane` and set `spec.security.manageNetworkPolicy` to `false`.
 
 [NOTE]
 ====
-When you disable `spec.security.manageNetworkPolicy` {SMProductName} will not create *any* `NetworkPolicy` objects.  The system administrator is responsible for managing the network and fixing any issues this might cause.
+When you disable `spec.security.manageNetworkPolicy` {SMProductName} will not create *any* `NetworkPolicy` objects. The system administrator is responsible for managing the network and fixing any issues this might cause.
 ====
 
 .Prerequisites

modules/ossm-gateways.adoc

@@ -0,0 +1,61 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v1x/ossm-traffic-manage.adoc
+// * service_mesh/v2x/ossm-traffic-manage.adoc
+
+:_content-type: CONCEPT
+[id="ossm-gateways_{context}"]
+= Using gateways
+
+You can use a gateway to manage inbound and outbound traffic for your mesh to specify which traffic you want to enter or leave the mesh. Gateway configurations are applied to standalone Envoy proxies that are running at the edge of the mesh, rather than sidecar Envoy proxies running alongside your service workloads.
+
+Unlike other mechanisms for controlling traffic entering your systems, such as the Kubernetes Ingress APIs, {SMProductName} gateways allow you to use the full power and flexibility of traffic routing. The {SMProductName} gateway resource can layer 4-6 load balancing properties, such as ports, to expose and configure {SMProductName} TLS settings. Instead of adding application-layer traffic routing (L7) to the same API resource, you can bind a regular {SMProductName} virtual service to the gateway and manage gateway traffic like any other data plane traffic in a service mesh.
+
+Gateways are primarily used to manage ingress traffic, but you can also configure egress gateways. An egress gateway lets you configure a dedicated exit node for the traffic leaving the mesh. This enables you to limit which services have access to external networks, which adds security control to your service mesh. You can also use a gateway to configure a purely internal proxy.
+
+.Gateway example
+
+A gateway resource describes a load balancer operating at the edge of the mesh receiving incoming or outgoing HTTP/TCP connections. The specification describes a set of ports that should be exposed, the type of protocol to use, SNI configuration for the load balancer, and so on.
+
+The following example shows a sample gateway configuration for external HTTPS ingress traffic:
+
+[source,yaml]
+----
+apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  name: ext-host-gwy
+spec:
+  selector:
+    istio: ingressgateway # use istio default controller
+  servers:
+  - port:
+      number: 443
+      name: https
+      protocol: HTTPS
+    hosts:
+    - ext-host.example.com
+    tls:
+      mode: SIMPLE
+      serverCertificate: /tmp/tls.crt
+      privateKey: /tmp/tls.key
+----
+
+This gateway configuration lets HTTPS traffic from `ext-host.example.com` into the mesh on port 443, but doesn’t specify any routing for the traffic.
+
+To specify routing and for the gateway to work as intended, you must also bind the gateway to a virtual service. You do this using the virtual service's gateways field, as shown in the following example:
+
+[source,yaml]
+----
+apiVersion: networking.istio.io/v1alpha3
+kind: VirtualService
+metadata:
+  name: virtual-svc
+spec:
+  hosts:
+  - ext-host.example.com
+  gateways:
+    - ext-host-gwy
+----
+
+You can then configure the virtual service with routing rules for the external traffic.

modules/ossm-routing-bookinfo-example.adoc

@@ -4,11 +4,11 @@
 // * service_mesh/v2x/ossm-traffic-manage.adoc
 
 [id="ossm-routing-bookinfo_{context}"]
-= Routing tutorial
+= Bookinfo routing tutorial
 
 The {SMProductShortName} Bookinfo sample application consists of four separate microservices, each with multiple versions. After installing the Bookinfo sample application, three different versions of the `reviews` microservice run concurrently.
 
-When you access the Bookinfo app `/product` page in a browser and refresh several times, sometimes the book review output contains star ratings and other times it does not. Without an explicit default service version to route to, {SMProductShortName} routes requests to all available versions one after the other. 
+When you access the Bookinfo app `/product` page in a browser and refresh several times, sometimes the book review output contains star ratings and other times it does not. Without an explicit default service version to route to, {SMProductShortName} routes requests to all available versions one after the other.
 
 This tutorial helps you apply rules that route all traffic to `v1` (version 1) of the microservices. Later, you can apply a rule to route traffic based on the value of an HTTP request header.
 

modules/ossm-routing-bookinfo-route.adoc

@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v1x/ossm-traffic-manage.adoc
+// * service_mesh/v2x/ossm-traffic-manage.adoc
 :_content-type: PROCEDURE
 [id="ossm-routing-bookinfo-route_{context}"]
 = Route based on user identity
@@ -24,8 +28,8 @@ $ oc get virtualservice reviews -o yaml
 
 . On the `/productpage` of the Bookinfo app, log in as user `jason` with no password.
 +
-.. Refresh the browser. The star ratings appear next to each review.
+. Refresh the browser. The star ratings appear next to each review.
 
-. Log in as another user (pick any name you wish). Refresh the browser. Now the stars are gone. Traffic is now routed to `reviews:v1` for all users except Jason.
+. Log in as another user (pick any name you want). Refresh the browser. Now the stars are gone. Traffic is now routed to `reviews:v1` for all users except Jason.
 
 You have successfully configured the Bookinfo sample application to route traffic based on user identity.

modules/ossm-routing-bookinfo-test.adoc

@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v1x/ossm-traffic-manage.adoc
+// * service_mesh/v2x/ossm-traffic-manage.adoc
 :_content-type: PROCEDURE
 [id="ossm-routing-bookinfo-test_{context}"]
 = Testing the new route configuration

modules/ossm-routing-destination-rules.adoc

@@ -0,0 +1,46 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v1x/ossm-traffic-manage.adoc
+// * service_mesh/v2x/ossm-traffic-manage.adoc
+
+:_content-type: CONCEPT
+[id="ossm-routing-destination-rules_{context}"]
+= Understanding destination rules
+
+Destination rules are applied after virtual service routing rules are evaluated, so they apply to the traffic's real destination. Virtual services route traffic to a destination. Destination rules configure what happens to traffic at that destination.
+
+By default, {SMProductName} uses a round-robin load balancing policy, where each service instance in the pool gets a request in turn. {SMProductName} also supports the following models, which you can specify in destination rules for requests to a particular service or service subset.
+
+* Random: Requests are forwarded at random to instances in the pool.
+* Weighted: Requests are forwarded to instances in the pool according to a specific percentage.
+* Least requests: Requests are forwarded to instances with the least number of requests.
+
+.Destination rule example
+
+The following example destination rule configures three different subsets for the `my-svc` destination service, with different load balancing policies:
+
+[source,yaml]
+----
+apiVersion: networking.istio.io/v1alpha3
+kind: DestinationRule
+metadata:
+  name: my-destination-rule
+spec:
+  host: my-svc
+  trafficPolicy:
+    loadBalancer:
+      simple: RANDOM
+  subsets:
+  - name: v1
+    labels:
+      version: v1
+  - name: v2
+    labels:
+      version: v2
+    trafficPolicy:
+      loadBalancer:
+        simple: ROUND_ROBIN
+  - name: v3
+    labels:
+      version: v3
+----

modules/ossm-routing-gateways.adoc

@@ -1,11 +1,11 @@
 // Module included in the following assemblies:
 //
-// * service_mesh/v1x/ossm-config.adoc
-// * service_mesh/v2x/ossm-config.adoc
+// * service_mesh/v1x/ossm-traffic-manage.adoc
+// * service_mesh/v2x/ossm-traffic-manage.adoc
 
 :_content-type: PROCEDURE
-[id="ossm-routing-gateways_{context}"]
-= Configuring ingress using a gateway
+[id="ossm-routing-ingress-gateway_{context}"]
+= Configuring an ingress gateway
 
 An ingress gateway is a load balancer operating at the edge of the mesh that receives incoming HTTP/TCP connections. It configures exposed ports and protocols but does not include any traffic routing configuration. Traffic routing for ingress traffic is instead configured with routing rules, the same way as for internal service requests.
 
@@ -47,7 +47,7 @@ $ oc apply -f gateway.yaml
 +
 .. Create a YAML file, and copy the following YAML into it.
 +
-.Virtual service example vs.yaml
+.Virtual service example
 [source,yaml]
 ----
 apiVersion: networking.istio.io/v1alpha3