Skip to content

Commit 8426788

Browse files
JSticklerJStickler
authored
Merge pull request #35973 from JStickler/OSSMDOC-381
OSSMDOC-381: Federation configure export/import.
2 parents dc9a41f + a4ac83b commit 8426788

6 files changed

+536
-9
lines changed

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

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
////
2+
This module included in the following assemblies:
3+
* service_mesh/v2x/ossm-federation.adoc
4+
////
5+
6+
[id="ossm-federation-config-export_{context}"]
7+
= Exporting a service from a federated mesh
8+
9+
Exporting services allows a mesh to share one or more of its services with another member of the federated mesh.
10+
11+
//Insert ExportedServiceSet diagram here
12+
13+
You use an `ExportedServiceSet` resource to declare the services from one mesh that you are making available to another peer in the federated mesh. You must explicitly declare each service to be shared with a peer.
14+
15+
* You can select services by namespace or name.
16+
* You can use wildcards to select services; for example, to export all the services in a namespace.
17+
* You can export services using an alias. For example, you can export the `foo/bar` service as `custom-ns/bar`.
18+
// Need non foo/bar example above
19+
* You can only export services that are visible to the mesh’s system namespace. For example, a service in another namespace with a `networking.istio.io/exportTo` label set to ‘.’ would not be a candidate for export.
20+
* For exported services, their target services will only see traffic from the ingress gateway, not the original requestor (that is, they won’t see the client ID of either the other mesh’s egress gateway or the workload originating the request)
21+
22+
The following example is for services that `red-mesh` is exporting to `green-mesh`.
23+
24+
.Example ExportServiceSet resource
25+
[source,yaml]
26+
----
27+
kind: ExportedServiceSet
28+
apiVersion: federation.maistra.io/v1
29+
metadata:
30+
name: green-mesh
31+
namespace: red-mesh-system
32+
spec:
33+
exportRules:
34+
# export ratings.mesh-x-bookinfo as ratings.bookinfo
35+
- type: NameSelector
36+
nameSelector:
37+
namespace: red-mesh-bookinfo
38+
name: red-ratings
39+
alias:
40+
namespace: bookinfo
41+
name: ratings
42+
# export any service in red-mesh-bookinfo namespace with label export-service=true
43+
- type: LabelSelector
44+
labelSelector:
45+
namespace: red-mesh-bookinfo
46+
Selector:
47+
matchLabels:
48+
export-service: “true”
49+
alias: # exported as if they were in the bookinfo namespace
50+
namespace: bookinfo
51+
----
52+
53+
.ExportServiceSet parameters
54+
[options="header"]
55+
[cols="l, a, a"]
56+
|===
57+
|Parameter |Description |Values
58+
|metadata:
59+
name:
60+
|Name of the ServiceMeshPeer you are exposing this service to.
61+
|Must match the `name` value for the mesh in the `ServiceMeshPeer` resource.
62+
63+
|metadata:
64+
namespace:
65+
|Name of the project/namespace containing this resource (should be the system namespace for the mesh) .
66+
|
67+
68+
|spec:
69+
exportRules:
70+
-type:
71+
|Type of rule that will govern the export for this service. The first matching rule found for the service will be used for the export.
72+
|`NameSelector`, `LabelSelector`
73+
74+
|spec:
75+
exportRules:
76+
-type: nameSelector
77+
NameSelector:
78+
namespace:
79+
name:
80+
|To create a `NameSelector` rule, specify the `namespace` of the service and the `name` of the service as defined in the `Deployment` resource.
81+
|
82+
83+
|spec:
84+
exportRules:
85+
-type: NameSelector
86+
NameSelector:
87+
alias:
88+
namespace:
89+
name:
90+
|To create a `NameSelector` rule that uses an alias for the service, after specifying the `namespace` and `name` for the service, then specify the alias for the `namespace` and the alias to be used for `name` of the service.
91+
|
92+
93+
|spec:
94+
exportRules:
95+
-type: LabelSelector
96+
LabelSelector:
97+
namespace: <exportingMesh>
98+
Selector:
99+
matchLabels:
100+
<label>: "true"
101+
|To create a `LabelSelector` rule, specify the `namespace` of the service and specify the `label` defined in the `Deployment` resource. In the example above, the label is `export-service`.
102+
|
103+
104+
|spec:
105+
exportRules:
106+
-type: LabelSelector
107+
LabelSelector:
108+
namespace: <exportingMesh>
109+
Selector:
110+
matchLabels:
111+
<label>: "true"
112+
alias:
113+
namespace:
114+
name:
115+
|To create a `LabelSelector` rule that uses an alias for the service, after specifying the `namespace` and `label`, then specify the alias to be used for `name` or `namespace` of the service. In the example above, the alias is `bookinfo`.
116+
|
117+
|===
118+
119+
//PLEASE CHECK THESE EXAMPLES
120+
121+
.Export services with the name "ratings" from all namespaces in the red-mesh to blue-mesh.
122+
[source,yaml]
123+
----
124+
kind: ExportedServiceSet
125+
apiVersion: federation.maistra.io/v1
126+
metadata:
127+
name: blue-mesh
128+
namespace: red-mesh-system
129+
spec:
130+
exportRules:
131+
- type: NameSelector
132+
nameSelector:
133+
namespace: *
134+
name: ratings
135+
----
136+
137+
.Export all services from the west-data-center namespace to green-mesh
138+
[source,yaml]
139+
----
140+
kind: ExportedServiceSet
141+
apiVersion: federation.maistra.io/v1
142+
metadata:
143+
name: green-mesh
144+
namespace: red-mesh-system
145+
spec:
146+
exportRules:
147+
- type: NameSelector
148+
nameSelector:
149+
namespace: west-data-center
150+
name: *
151+
----

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

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
////
2+
This module included in the following assemblies:
3+
* service_mesh/v2x/ossm-federation.adoc
4+
////
5+
6+
[id="ossm-federation-config-import_{context}"]
7+
= Importing a service into a federated mesh
8+
9+
Importing services lets you explicitly specify which services exported from another mesh should be accessible within your service mesh.
10+
11+
//Insert ImportedServiceSet diagram here
12+
13+
You use an `ImportedServiceSet` resource to select services for import. Only services exported by a mesh peer and explicitly imported are available to the mesh. Services that you do not explicitly import are not made available within the mesh.
14+
15+
* You can select services by namespace or name.
16+
* You can use wildcards to select services, for example, to import all the services that were exported to the namespace.
17+
* You can select services for export using a label selector, which may be global to the mesh, or scoped to a specific member namespace.
18+
* You can import services using an alias. For example, you can import the `custom-ns/bar` service as `other-mesh/bar`.
19+
// Need non foo/bar example above
20+
* You can specify a custom domain suffix, which will be appended to the `name.namespace` of an imported service for its fully qualified domain name; for example, `bar.other-mesh.imported.local`.
21+
22+
The following example is for the `green-mesh` importing a service that was exported by `red-mesh`.
23+
24+
.Example ImportServiceSet
25+
[source,yaml]
26+
----
27+
kind: ImportedServiceSet
28+
apiVersion: federation.maistra.io/v1
29+
metadata:
30+
name: red-mesh #name of mesh that exported the service
31+
namespace: green-mesh-system #mesh namespace that service is being imported into
32+
spec:
33+
importRules: # first matching rule is used
34+
# import ratings.bookinfo as ratings.bookinfo
35+
- type: NameSelector
36+
nameSelector:
37+
importAsLocal: false
38+
namespace: bookinfo
39+
name: ratings
40+
alias:
41+
# service will be imported as ratings.bookinfo.svc.red-mesh-imports.local
42+
namespace: bookinfo
43+
name: ratings
44+
----
45+
46+
.ImportServiceSet parameters
47+
[options="header"]
48+
[cols="l, a, a"]
49+
|===
50+
|Parameter |Description |Values
51+
|metadata:
52+
name:
53+
|Name of the ServiceMeshPeer that exported the service to the federated mesh.
54+
|
55+
56+
|metadata:
57+
namespace:
58+
|Name of the namespace containing the ServiceMeshPeer resource (the mesh system namespace).
59+
|
60+
61+
|spec:
62+
importRules:
63+
-type:
64+
|Type of rule that will govern the import for the service. The first matching rule found for the service will be used for the import.
65+
|`NameSelector`
66+
67+
|spec:
68+
importRules:
69+
-type: NameSelector:
70+
namespace:
71+
name:
72+
|To create a `NameSelector` rule, specify the `namespace` of the service and the `name` of the service, as defined in the `Deployment` resource.
73+
|
74+
75+
|spec:
76+
importRules:
77+
-type: NameSelector:
78+
importAsLocal:
79+
|Set to `true` to aggregate remote endpoint with local services. When `true`, services will be imported as `<name>.<namespace>.svc.cluster.local`
80+
|`true`/`false`
81+
82+
|spec:
83+
importRules:
84+
-type: NameSelector:
85+
importAsLocal:
86+
namespace:
87+
name:
88+
alias:
89+
|To create a `NameSelector` rule that uses an alias for the service, after specifying the `namespace` and `name` for the service, then specify the alias for the `namespace` and the alias to be used for `name` of the service.
90+
|
91+
|===
92+
93+
94+
//PLEASE CHECK MY EXAMPLES
95+
96+
.Import the "bookinfo/ratings" service from the red-mesh into blue-mesh
97+
[source,yaml]
98+
----
99+
kind: ImportedServiceSet
100+
apiVersion: federation.maistra.io/v1
101+
metadata:
102+
name: red-mesh
103+
namespace: blue-mesh-system
104+
spec:
105+
importRules:
106+
- type: NameSelector
107+
nameSelector:
108+
importAsLocal: false
109+
namespace: bookinfo
110+
name: ratings
111+
----
112+
113+
.Import all services from the red-mesh's west-data-center namespace into the green-mesh. These services will be accessible as <name>.west-data-center.svc.red-mesh-imports.local
114+
[source,yaml]
115+
----
116+
kind: ImportedServiceSet
117+
apiVersion: federation.maistra.io/v1
118+
metadata:
119+
name: red-mesh
120+
namespace: green-mesh-system
121+
spec:
122+
importRules:
123+
- type: NameSelector
124+
nameSelector:
125+
importAsLocal: false
126+
namespace: west-data-center
127+
name: *
128+
----

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

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
////
2+
This module included in the following assemblies:
3+
* service_mesh/v2x/ossm-federation.adoc
4+
////
5+
6+
[id="ossm-federation-create-export_{context}"]
7+
= Creating an ExportedServiceSet
8+
9+
You create an `ExportedServiceSet` resource to explicitly declare the services that you want to be available to a mesh peer.
10+
11+
Services are exported as `<export-name>.<export-namespace>.svc.<ServiceMeshPeer.name>-exports.local` and will automatically route to the target service. This is the name by which the exported service is known in the exporting mesh. When the ingress gateway receives a request destined for this name, it will be routed to the actual service being exported. For example, if a service named `ratings.red-mesh-bookinfo` is exported to `green-mesh` as `ratings.bookinfo`, the service will be exported under the name `ratings.bookinfo.svc.green-mesh-exports.local`, and traffic received by the ingress gateway for that hostname will be routed to the `ratings.red-mesh-bookinfo` service.
12+
13+
.Prerequisites
14+
15+
* The cluster and `ServiceMeshControlPlane` have been configured for mesh federation.
16+
* An account with the `cluster-admin` role.
17+
18+
[NOTE]
19+
====
20+
You can configure services for export even if they don't exist yet. When a service that matches the value specified in the ExportedServiceSet is deployed, it will be automatically exported.
21+
====
22+
23+
////
24+
.Procedure from the Console
25+
This is conjecture about what the flow might look like.
26+
27+
Follow this procedure to create an `ExportServiceSet` with the web console. This example shows the red-mesh exporting the ratings service from the bookinfo application to the green-mesh.
28+
29+
. Log in to the {product-title} web console as a user with the cluster-admin role.
30+
. Navigate to *Operators* → *Installed Operators*.
31+
. Click the *Project* menu and select the project where you installed the control plane for the mesh that will export services. For example, `red-mesh-system`.
32+
. Click the {ProductName} Operator, then click *Istio Service Mesh ExportedServiceSet*.
33+
. On the *Istio Service Mesh ExportedServiceSet* tab, click *Create ExportedServiceSet*.
34+
. On the *Create ExportedServiceSet* page, click *YAML* to modify your configuration.
35+
. Modify the default configuration with values for your export.
36+
. Click *Create*. The Operator creates the export based on your configuration parameters.
37+
. To verify the `ExportedServiceSet` resource was created, click the *Istio Service Mesh ExportedServiceSet* tab.
38+
.. Click the name of the new `ExportedServiceSet`; for example, `export-to-green-mesh`.
39+
.. Click the *Resources* tab to see the `ExportedServiceSet` resource the Operator created and configured.
40+
////
41+
42+
.Procedure from the CLI
43+
44+
//NEED TO TEST THIS
45+
Follow this procedure to create an `ExportServiceSet` from the command line.
46+
47+
. 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.
48+
+
49+
[source,terminal]
50+
----
51+
$ oc login --username=<NAMEOFUSER> <API token> https://{HOSTNAME}:6443
52+
----
53+
+
54+
. Change to the project where you installed the control plane; for example, `red-mesh-system`.
55+
+
56+
[source,terminal]
57+
----
58+
$ oc project red-mesh-system
59+
----
60+
+
61+
. Create an `ExportServiceSet` file based on the following example where `red-mesh` is exporting services to `green-mesh`.
62+
+
63+
.Example ExportServiceSet resource from red-mesh to green-mesh
64+
[source,yaml]
65+
----
66+
apiVersion: federation.maistra.io/v1
67+
kind: ExportedServiceSet
68+
metadata:
69+
name: green-mesh
70+
namespace: red-mesh-system
71+
spec:
72+
exportRules:
73+
- type: NameSelector
74+
nameSelector:
75+
name:
76+
namespace: red-mesh-bookinfo
77+
name: red-ratings
78+
alias:
79+
Namespace: bookinfo
80+
name: ratings
81+
----
82+
+
83+
. Run the following command to upload and create the `ExportServiceSet` resource in the red-mesh-system namespace.
84+
+
85+
[source,terminal]
86+
----
87+
$ oc create -n <ControlPlaneNamespace> -f <ExportServiceSet.yaml>
88+
----
89+
+
90+
For example:
91+
+
92+
[source,terminal]
93+
----
94+
$ oc create -n red-mesh-system -f export-to-green-mesh.yaml
95+
----
96+
+
97+
. Create additional `ExportServiceSets` as needed for each mesh peer in your federated mesh.
98+
//TODO - Add sample output after the validation
99+
. To validate the services you've exported from `red-mesh` to share with `green-mesh`, run the following command:
100+
+
101+
[source,terminal]
102+
----
103+
$ oc get exportedserviceset <PeerMeshExportedTo> -o yaml |yaml
104+
----
105+
+
106+
For example:
107+
+
108+
[source,terminal]
109+
----
110+
$ oc get exportedserviceset green-mesh -o yaml |yaml
111+
----

0 commit comments

Comments
 (0)