Skip to content

Commit fe88b86

Browse files
JSticklerJStickler
authored
Merge pull request #41725 from JStickler/OSSMDOC-395
OSSMDOC-395: Configure Federation for failover.
2 parents c2afe57 + bb3029b commit fe88b86

9 files changed

+196
-6
lines changed

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

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
////
2+
This module included in the following assemblies:
3+
* service_mesh/v2x/ossm-federation.adoc
4+
////
5+
:_content-type: PROCEDURE
6+
[id="ossm-federation-config-destinationrule-failover_{context}"]
7+
= Configuring a DestinationRule for failover
8+
9+
Create a `DestinationRule` resource that configures the following:
10+
11+
* 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.
12+
13+
* Failover policy between regions. This ensures that failover beyond a region boundary will behave predictably.
14+
15+
.Procedure
16+
17+
. 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.
18+
+
19+
[source,terminal]
20+
----
21+
$ oc login --username=<NAMEOFUSER> <API token> https://<HOSTNAME>:6443
22+
----
23+
+
24+
. Change to the project where you installed the control plane.
25+
+
26+
[source,terminal]
27+
----
28+
$ oc project <smcp-system>
29+
----
30+
+
31+
For example, `green-mesh-system`.
32+
+
33+
[source,terminal]
34+
----
35+
$ oc project green-mesh-system
36+
----
37+
+
38+
. 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`.
39+
+
40+
.Example `DestinationRule`
41+
[source,yaml]
42+
----
43+
apiVersion: networking.istio.io/v1beta
44+
kind: DestinationRule
45+
metadata:
46+
name: default
47+
namespace: green-mesh-system
48+
spec:
49+
host: "*.green-mesh-system.svc.cluster.local"
50+
trafficPolicy:
51+
loadBalancer:
52+
localityLbSetting:
53+
enabled: true
54+
failover:
55+
- from: us-east
56+
to: us-west
57+
outlierDetection:
58+
consecutive5xxErrors: 1
59+
interval: 5m
60+
baseEjectionTime: 1m
61+
----
62+
+
63+
. Deploy the `DestinationRule`, where `<DestinationRule>` includes the full path to your file, enter the following command:
64+
+
65+
[source,terminal]
66+
----
67+
$ oc create -n <smcp-system> -f <DestinationRule.yaml>
68+
----
69+
+
70+
For example:
71+
+
72+
[source,terminal]
73+
----
74+
$ oc create -n green-mesh-system -f green-mesh-usWestDestinationRule.yaml
75+
----

‎modules/ossm-federation-config-export.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ spec:
122122
|
123123
|===
124124

125-
//PLEASE CHECK THESE EXAMPLES
125+
126126

127127
.Export services with the name "ratings" from all namespaces in the red-mesh to blue-mesh.
128128
[source,yaml]

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
////
2+
This module included in the following assemblies:
3+
* service_mesh/v2x/ossm-federation.adoc
4+
////
5+
:_content-type: CONCEPT
6+
[id="ossm-federation-config-failover-overview_{context}"]
7+
= Configuring a federated mesh for failover
8+
9+
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.
10+
11+
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`.
12+
13+
.Prerequisites
14+
15+
* Two or more {product-title} 4.6 or above clusters already networked and federated.
16+
* `ExportServiceSet` resources already created for each mesh peer in the federated mesh.
17+
* `ImportServiceSet` resources already created for each mesh peer in the federated mesh.
18+
* An account with the cluster-admin role.

‎modules/ossm-federation-config-import.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ spec:
9494
|===
9595

9696

97-
//PLEASE CHECK MY EXAMPLES
97+
9898

9999
.Import the "bookinfo/ratings" service from the red-mesh into blue-mesh
100100
[source,yaml]

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

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
////
2+
This module included in the following assemblies:
3+
* service_mesh/v2x/ossm-federation.adoc
4+
////
5+
:_content-type: PROCEDURE
6+
[id="ossm-federation-config-importserviceset-failover_{context}"]
7+
= Configuring an ImportServiceSet for failover
8+
9+
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.
10+
11+
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.
12+
13+
.Example `ImportServiceSet` resource from red-mesh to green-mesh
14+
[source,yaml]
15+
----
16+
kind: ImportedServiceSet
17+
apiVersion: federation.maistra.io/v1
18+
metadata:
19+
name: red-mesh #name of mesh that exported the service
20+
namespace: green-mesh-system #mesh namespace that service is being imported into
21+
spec:
22+
importRules: # first matching rule is used
23+
# import ratings.bookinfo as ratings.bookinfo
24+
- type: NameSelector
25+
importAsLocal: true
26+
nameSelector:
27+
namespace: bookinfo
28+
name: ratings
29+
alias:
30+
# service will be imported as ratings.bookinfo.svc.red-mesh-imports.local
31+
namespace: bookinfo
32+
name: ratings
33+
#Locality within which imported services should be associated.
34+
locality:
35+
region: us-west
36+
----
37+
38+
.`ImportedServiceLocality` fields table
39+
|===
40+
| Name | Description | Type
41+
42+
|region:
43+
|Region within which imported services are located.
44+
|string
45+
46+
|subzone:
47+
|Subzone within which imported services are located. I Subzone is specified, Zone must also be specified.
48+
|string
49+
50+
|zone:
51+
|Zone within which imported services are located. If Zone is specified, Region must also be specified.
52+
|string
53+
|===
54+
55+
56+
.Procedure
57+
58+
. Log in to the {product-title} CLI as a user with the `cluster-admin` role, enter the following command:
59+
+
60+
[source,terminal]
61+
----
62+
$ oc login --username=<NAMEOFUSER> <API token> https://<HOSTNAME>:6443
63+
----
64+
+
65+
. Change to the project where you installed the control plane, enter the following command:
66+
+
67+
[source,terminal]
68+
----
69+
$ oc project <smcp-system>
70+
----
71+
+
72+
For example, `green-mesh-system`.
73+
+
74+
[source,terminal]
75+
----
76+
$ oc project green-mesh-system
77+
----
78+
+
79+
. Edit the `ImportServiceSet` file, where `<ImportServiceSet.yaml>` includes a full path to the file you want to edit, enter the following command:
80+
+
81+
[source,terminal]
82+
----
83+
$ oc edit -n <smcp-system> -f <ImportServiceSet.yaml>
84+
----
85+
+
86+
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.
87+
+
88+
[source,terminal]
89+
----
90+
$ oc edit -n green-mesh-system -f import-from-red-mesh.yaml
91+
----
92+
. Modify the file:
93+
.. Set `spec.importRules.importAsLocal` to `true`.
94+
.. Set `spec.locality` to a `region`, `zone`, or `subzone`.
95+
.. Save your changes.

‎modules/ossm-federation-config-meshPeer.adoc‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,6 @@ Federating three meshes named `red`, `blue`, and `green` would require six `Serv
2424
. On blue-mesh-system, create a `ServiceMeshPeer` for the red mesh.
2525
. On blue-mesh-system, create a `ServiceMeshPeer` for the green mesh.
2626

27-
//TODO Insert ServiceMeshPeer diagram here
28-
2927
Configuration in the `ServiceMeshPeer` resource includes the following:
3028

3129
* The address of the other mesh’s ingress gateway, which is used for discovery and service requests.

‎modules/ossm-federation-create-export.adoc‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,6 @@ Follow this procedure to create an `ExportServiceSet` with the web console. This
4242

4343
.Procedure from the CLI
4444

45-
//NEED TO TEST THIS
4645
Follow this procedure to create an `ExportServiceSet` from the command line.
4746

4847
. 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‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,6 @@ Follow this procedure to create an `ImportServiceSet` with the web console. This
4343

4444
.Procedure from the CLI
4545

46-
//NEED TO TEST THIS
4746
Follow this procedure to create an `ImportServiceSet` from the command line.
4847

4948
. 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‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,12 @@ include::modules/ossm-federation-config-import.adoc[leveloffset=+1]
4040

4141
include::modules/ossm-federation-create-import.adoc[leveloffset=+2]
4242

43+
include::modules/ossm-federation-config-failover-overview.adoc[leveloffset=+1]
44+
45+
include::modules/ossm-federation-config-importserviceset-failover.adoc[leveloffset=+2]
46+
47+
include::modules/ossm-federation-config-destinationrule-failover.adoc[leveloffset=+2]
48+
4349
include::modules/ossm-federation-remove-service.adoc[leveloffset=+1]
4450

4551
include::modules/ossm-federation-remove-mesh.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)