Merge pull request #43981 from openshift-cherrypick-robot/cherry-pick…

…-41725-to-enterprise-4.7

[enterprise-4.7] OSSMDOC-395: Configure Federation for failover.

modules/ossm-federation-config-destinationrule-failover.adoc

@@ -0,0 +1,75 @@
+////
+This module included in the following assemblies:
+* service_mesh/v2x/ossm-federation.adoc
+////
+:_content-type: PROCEDURE
+[id="ossm-federation-config-destinationrule-failover_{context}"]
+= Configuring a DestinationRule for failover
+
+Create a `DestinationRule` resource that configures the following:
+
+* Outlier detection for the service. This is required in order for failover to function properly. In particular, it configures the sidecar proxies to know when endpoints for a service are unhealthy, eventually triggering a failover to the next locality.
+
+* Failover policy between regions. This ensures that failover beyond a region boundary will behave predictably.
+
+.Procedure
+
+. Log in to the {product-title} CLI as a user with the `cluster-admin` role. Enter the following command. Then, enter your username and password when prompted.
++
+[source,terminal]
+----
+$ oc login --username=<NAMEOFUSER> <API token> https://<HOSTNAME>:6443
+----
++
+. Change to the project where you installed the control plane.
++
+[source,terminal]
+----
+$ oc project <smcp-system>
+----
++
+For example, `green-mesh-system`.
++
+[source,terminal]
+----
+$ oc project green-mesh-system
+----
++
+. Create a `DestinationRule` file based on the following example where if green-mesh is unavailable, the traffic should be routed from the green-mesh in the `us-east` region to the red-mesh in `us-west`.
++
+.Example `DestinationRule`
+[source,yaml]
+----
+apiVersion: networking.istio.io/v1beta
+kind: DestinationRule
+metadata:
+  name: default
+  namespace: green-mesh-system
+spec:
+  host: "*.green-mesh-system.svc.cluster.local"
+  trafficPolicy:
+    loadBalancer:
+      localityLbSetting:
+        enabled: true
+        failover:
+          - from: us-east
+            to: us-west
+    outlierDetection:
+      consecutive5xxErrors: 1
+      interval: 5m
+      baseEjectionTime: 1m
+----
++
+. Deploy the `DestinationRule`, where `<DestinationRule>` includes the full path to your file, enter the following command:
++
+[source,terminal]
+----
+$ oc create -n <smcp-system> -f <DestinationRule.yaml>
+----
++
+For example:
++
+[source,terminal]
+----
+$ oc create -n green-mesh-system -f green-mesh-usWestDestinationRule.yaml
+----

modules/ossm-federation-config-export.adoc

@@ -122,7 +122,7 @@ spec:
 |
 |===
 
-//PLEASE CHECK THESE EXAMPLES
+
 
 .Export services with the name "ratings" from all namespaces in the red-mesh to blue-mesh.
 [source,yaml]

modules/ossm-federation-config-failover-overview.adoc

@@ -0,0 +1,18 @@
+////
+This module included in the following assemblies:
+* service_mesh/v2x/ossm-federation.adoc
+////
+:_content-type: CONCEPT
+[id="ossm-federation-config-failover-overview_{context}"]
+= Configuring a federated mesh for failover
+
+Failover is the ability to switch automatically and seamlessly to a reliable backup system, for example another server. In the case of a federated mesh, you can configure a service in one mesh to failover to a service in another mesh.
+
+You configure Federation for failover by setting the `importAsLocal` and `locality` settings in a `ServiceImportSet` resource and then configuring a `DestinationRule` that configures failover for the service to the locality specified in the `ServiceImportSet`.
+
+.Prerequisites
+
+* Two or more {product-title} 4.6 or above clusters already networked and federated.
+* `ExportServiceSet` resources already created for each mesh peer in the federated mesh.
+* `ImportServiceSet` resources already created for each mesh peer in the federated mesh.
+* An account with the cluster-admin role.

modules/ossm-federation-config-import.adoc

@@ -94,7 +94,7 @@ spec:
 |===
 
 
-//PLEASE CHECK MY EXAMPLES
+
 
 .Import the "bookinfo/ratings" service from the red-mesh into blue-mesh
 [source,yaml]

modules/ossm-federation-config-importserviceset-failover.adoc

@@ -0,0 +1,95 @@
+////
+This module included in the following assemblies:
+* service_mesh/v2x/ossm-federation.adoc
+////
+:_content-type: PROCEDURE
+[id="ossm-federation-config-importserviceset-failover_{context}"]
+= Configuring an ImportServiceSet for failover
+
+Locality-weighted load balancing allows administrators to control the distribution of traffic to endpoints based on the localities of where the traffic originates and where it will terminate. These localities are specified using arbitrary labels that designate a hierarchy of localities in {region}/{zone}/{sub-zone} form.
+
+In the examples in this section, the `green-mesh` is located in the `us-east` region, and the `red-mesh` is located in the `us-west` region.
+
+.Example `ImportServiceSet` resource from red-mesh to green-mesh
+[source,yaml]
+----
+kind: ImportedServiceSet
+apiVersion: federation.maistra.io/v1
+metadata:
+  name: red-mesh #name of mesh that exported the service
+  namespace: green-mesh-system #mesh namespace that service is being imported into
+spec:
+  importRules: # first matching rule is used
+  # import ratings.bookinfo as ratings.bookinfo
+  - type: NameSelector
+    importAsLocal: true
+    nameSelector:
+      namespace: bookinfo
+      name: ratings
+      alias:
+        # service will be imported as ratings.bookinfo.svc.red-mesh-imports.local
+        namespace: bookinfo
+        name: ratings
+  #Locality within which imported services should be associated.
+  locality:
+    region: us-west
+----
+
+.`ImportedServiceLocality` fields table
+|===
+| Name | Description | Type
+
+|region:
+|Region within which imported services are located.
+|string
+
+|subzone:
+|Subzone within which imported services are located.  I Subzone is specified, Zone must also be specified.
+|string
+
+|zone:
+|Zone within which imported services are located.  If Zone is specified, Region must also be specified.
+|string
+|===
+
+
+.Procedure
+
+. Log in to the {product-title} CLI as a user with the `cluster-admin` role, enter the following command:
++
+[source,terminal]
+----
+$ oc login --username=<NAMEOFUSER> <API token> https://<HOSTNAME>:6443
+----
++
+. Change to the project where you installed the control plane, enter the following command:
++
+[source,terminal]
+----
+$ oc project <smcp-system>
+----
++
+For example, `green-mesh-system`.
++
+[source,terminal]
+----
+$ oc project green-mesh-system
+----
++
+.  Edit the `ImportServiceSet` file, where `<ImportServiceSet.yaml>` includes a full path to the file you want to edit, enter the following command:
++
+[source,terminal]
+----
+$ oc edit -n <smcp-system> -f <ImportServiceSet.yaml>
+----
++
+For example, if you want to modify the file that imports from the red-mesh-system to the green-mesh-system as shown in the previous `ImportServiceSet` example.
++
+[source,terminal]
+----
+$ oc edit -n green-mesh-system -f import-from-red-mesh.yaml
+----
+. Modify the file:
+.. Set `spec.importRules.importAsLocal` to `true`.
+.. Set `spec.locality` to a `region`, `zone`, or `subzone`.
+.. Save your changes.

modules/ossm-federation-config-meshPeer.adoc

@@ -24,8 +24,6 @@ Federating three meshes named `red`, `blue`, and `green` would require six `Serv
 . On blue-mesh-system, create a `ServiceMeshPeer` for the red mesh.
 . On blue-mesh-system, create a `ServiceMeshPeer` for the green mesh.
 
-//TODO Insert ServiceMeshPeer diagram here
-
 Configuration in the `ServiceMeshPeer` resource includes the following:
 
 * The address of the other mesh’s ingress gateway, which is used for discovery and service requests.

modules/ossm-federation-create-export.adoc

@@ -42,7 +42,6 @@ Follow this procedure to create an `ExportServiceSet` with the web console. This
 
 .Procedure from the CLI
 
-//NEED TO TEST THIS
 Follow this procedure to create an `ExportServiceSet` from the command line.
 
 . Log in to the {product-title} CLI as a user with the `cluster-admin` role. Enter the following command. Then, enter your username and password when prompted.

modules/ossm-federation-create-import.adoc

@@ -43,7 +43,6 @@ Follow this procedure to create an `ImportServiceSet` with the web console. This
 
 .Procedure from the CLI
 
-//NEED TO TEST THIS
 Follow this procedure to create an `ImportServiceSet` from the command line.
 
 . Log in to the {product-title} CLI as a user with the `cluster-admin` role. Enter the following command. Then, enter your username and password when prompted.

service_mesh/v2x/ossm-federation.adoc

@@ -40,6 +40,12 @@ include::modules/ossm-federation-config-import.adoc[leveloffset=+1]
 
 include::modules/ossm-federation-create-import.adoc[leveloffset=+2]
 
+include::modules/ossm-federation-config-failover-overview.adoc[leveloffset=+1]
+
+include::modules/ossm-federation-config-importserviceset-failover.adoc[leveloffset=+2]
+
+include::modules/ossm-federation-config-destinationrule-failover.adoc[leveloffset=+2]
+
 include::modules/ossm-federation-remove-service.adoc[leveloffset=+1]
 
 include::modules/ossm-federation-remove-mesh.adoc[leveloffset=+1]