Skip to content

Commit 899b450

Browse files
rh-tokeeferh-tokeefe
committed
OSSM-6260: Document migration from SMCP managed gateways
1 parent 01674d3 commit 899b450

7 files changed

+256
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4077,6 +4077,10 @@ Topics:
40774077
File: ossm-security
40784078
- Name: Traffic management
40794079
File: ossm-traffic-manage
4080+
- Name: Gateway migration
4081+
File: ossm-gateway-migration
4082+
- Name: Route migration
4083+
File: ossm-route-migration
40804084
- Name: Metrics, logs, and traces
40814085
File: ossm-observability
40824086
- Name: Performance and scalability

‎modules/ossm-about-gateway-migration.adoc

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/ossm-gateway-migration.adoc
3+
4+
:_mod-docs-content-type: CONCEPT
5+
[id="ossm-about-gateway-migration_{context}"]
6+
7+
= About gateway migration
8+
9+
In {SMProductName} 2.x, the {SMProductShortName} Operator creates an ingress and egress gateway in the control plane namespace by default. You can define additional gateways in the `ServiceMeshControlPlane` resource.
10+
11+
Deploying ingress and egress gateways with a `Deployment` resource using gateway injection provides greater flexibility and control. This deployment approach is a better practice because it allows you to manage gateways alongside the corresponding applications rather than in the control plane resource. Therefore, you should disable the default gateways, move away from the Service Mesh Control Plane declaration, and begin to use gateway injection.

‎modules/ossm-migrating-from-ior-to-explicitly-managed-routes.adoc

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/ossm-route-migration.adoc
3+
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="ossm-migrating-from-ior-to-explicitly-managed-routes_{context}"]
6+
= Migrating from Istio OpenShift Routing to explicitly-managed routes
7+
8+
This procedure explains how to disable Istio OpenShift Routing (IOR) in {SMProductName}, and how to continue to use and manage Routes that were originally created using IOR. This procedure also provides an example of how to explicitly create a new Route targeting an existing gateway `Service` object.
9+
10+
.Prerequisites
11+
12+
* Before migrating to explicitly-managed routes, export the existing route configurations managed by Istio OpenShift Routing (IOR) to files. Save the files so that in the future you can recreate the route configurations without requiring IOR.
13+
14+
.Procedure
15+
16+
* Modify the `ServiceMeshControlPlane` resource to disable IOR:
17+
+
18+
[source,yaml]
19+
----
20+
apiVersion: maistra.io/v2
21+
kind: ServiceMeshControlPlane
22+
spec:
23+
gateways:
24+
openshiftRoute:
25+
enabled: false
26+
----
27+
+
28+
You can continue to use the old routes that were previously created using IOR or you can create routes that explicitly target the ingress gateway `Service` object. The following example specifies how to create routes that explicitly target the ingress gateway `Service` object:
29+
+
30+
[source,yaml]
31+
----
32+
kind: Route
33+
apiVersion: route.openshift.io/v1
34+
metadata:
35+
name: example-gateway
36+
namespace: istio-system <1>
37+
spec:
38+
host: www.example.com
39+
to:
40+
kind: Service
41+
name: istio-ingressgateway <2>
42+
weight: 100
43+
port:
44+
targetPort: http2
45+
wildcardPolicy: None
46+
----
47+
<1> Specify new routes in the same namespace as the ingress gateway `Service` object.
48+
<2> Use the name of ingress gateway `Service` object that is the target.

‎modules/ossm-migrating-from-smcp-defined-gateways-to-gateway-injection.adoc

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service_mesh/v2x/ossm-gateway-migration.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="ossm-migrating-from-smcp-defined-gateways-to-gateway-injection_{context}"]
7+
= Migrate from SMCP-Defined gateways to gateway injection
8+
9+
This procedure explains how to migrate with zero downtime from gateways defined in the `ServiceMeshControlPlane` resource to gateways that are managed using gateway injection. This migration is achieved by using the existing gateway `Service` object to target a new gateway deployment that is created using gateway injection.
10+
11+
.Prerequisites
12+
13+
* You are logged in to the {product-title} web console as `cluster-admin`.
14+
15+
* The {SMProductName} Operator must be installed.
16+
17+
* The `ServiceMeshControlPlane` resource must be deployed and an ingress gateway exists in the configuration.
18+
19+
.Procedure
20+
21+
. Create a new ingress gateway that is configured to use gateway injection.
22+
+
23+
[NOTE]
24+
====
25+
This procedure migrates away from the default ingress gateway deployment defined in the `ServiceMeshControlPlane` resource to gateway injection. The procedure may be modified to migrate from additional ingress gateways configured in the SMCP.
26+
====
27+
+
28+
.Example ingress gateway resource with gateway injection
29+
[source,yaml, subs="attributes,verbatim"]
30+
----
31+
apiVersion: apps/v1
32+
kind: Deployment
33+
metadata:
34+
name: istio-ingressgateway-canary
35+
namespace: istio-system <1>
36+
spec:
37+
selector:
38+
matchLabels:
39+
app: istio-ingressgateway
40+
istio: ingressgateway
41+
template:
42+
metadata:
43+
annotations:
44+
inject.istio.io/templates: gateway
45+
labels: <2>
46+
app: istio-ingressgateway
47+
istio: ingressgateway
48+
sidecar.istio.io/inject: "true"
49+
spec:
50+
containers:
51+
- name: istio-proxy
52+
image: auto
53+
serviceAccountName: istio-ingressgateway
54+
---
55+
apiVersion: v1
56+
kind: ServiceAccount
57+
metadata:
58+
name: istio-ingressgateway
59+
namespace: istio-system
60+
---
61+
apiVersion: rbac.authorization.k8s.io/v1
62+
kind: Role
63+
metadata:
64+
name: secret-reader
65+
namespace: istio-system
66+
rules:
67+
- apiGroups: [""]
68+
resources: ["secrets"]
69+
verbs: ["get", "watch", "list"]
70+
---
71+
apiVersion: rbac.authorization.k8s.io/v1
72+
kind: RoleBinding
73+
metadata:
74+
name: istio-ingressgateway-secret-reader
75+
namespace: istio-system
76+
roleRef:
77+
apiGroup: rbac.authorization.k8s.io
78+
kind: Role
79+
name: secret-reader
80+
subjects:
81+
- kind: ServiceAccount
82+
name: istio-ingressgateway
83+
---
84+
apiVersion: networking.k8s.io/v1
85+
kind: NetworkPolicy <3>
86+
metadata:
87+
name: gatewayingress
88+
namespace: istio-system
89+
spec:
90+
podSelector:
91+
matchLabels:
92+
istio: ingressgateway
93+
ingress:
94+
- {}
95+
policyTypes:
96+
- Ingress
97+
----
98+
<1> The gateway injection deployment and all supporting resources should be deployed in the same namespace as the SMCP-defined gateway.
99+
<2> Ensure that the labels specified in the pod template include all of the label selectors specified in the `Service` object associated with the existing SMCP-defined gateway.
100+
<3> Grant access to the new gateway from outside the cluster. This access is required whenever the `spec.security.manageNetworkPolicy` of the `ServiceMeshControlPlane` resource is set to `true`, which is the default setting.
101+
102+
. Verify that the new gateway deployment is successfully handling requests.
103+
+
104+
If access logging was configured in the `ServiceMeshControlPlane` resource, view the access logs of the new gateway deployment to confirm the behavior.
105+
106+
. Scale down the old deployment and scale up the new deployment.
107+
+
108+
Gradually shift traffic from the old gateway deployment to the new gateway deployment by performing the following steps:
109+
110+
.. Increase the number of replicas for the new gateway deployment by running the following command:
111+
+
112+
[source,terminal]
113+
----
114+
$ oc scale -n istio-system deployment/<new_gateway_deployment> --replicas <new_number_of_replicas>
115+
----
116+
.. Decrease the number of replicas for the old gateway deployment by running the following command:
117+
+
118+
[source,terminal]
119+
----
120+
$ oc scale -n istio-system deployment/<old_gateway_deployment> --replicas <new_number_of_replicas>
121+
----
122+
123+
.. Repeat running the previous two commands. Each time, increase the number of replicas for the new gateway deployment and decrease the number of replicas for the old gateway deployment. Continue repeating until the new gateway deployment handles all traffic to the gateway `Service` object.
124+
125+
. Remove the `app.kubernetes.io/managed-by` label from the gateway `Service` object by running the following command:
126+
+
127+
[source,terminal]
128+
----
129+
$ oc label service -n istio-system istio-ingressgateway app.kubernetes.io/managed-by-
130+
----
131+
+
132+
Removing the label prevents the service from being deleted when the gateway is disabled in the `ServiceMeshControlPlane` resource.
133+
134+
. Remove the `ownerReferences` object from the gateway `Service` object by running the following command:
135+
+
136+
[source,terminal]
137+
----
138+
$ oc patch service -n istio-system istio-ingressgateway --type='json' -p='[{"op": "remove", "path": "/metadata/ownerReferences"}]'
139+
----
140+
+
141+
Removing this object prevents the service from being garbage collected when the `ServiceMeshControlPlane` resource is deleted.
142+
143+
. Disable the old gateway deployment that was managed by the `ServiceMeshControlPlane` resource by running the following command:
144+
+
145+
[source,terminal]
146+
----
147+
$ oc patch smcp -n istio-system <smcp_name> --type='json' -p='[{"op": "replace", "path": "/spec/gateways/ingress/enabled", "value": false}]'
148+
----
149+
+
150+
[NOTE]
151+
====
152+
When the old ingress gateway `Service` object is disabled it is not deleted. You may save this `Service` object to a file and manage it alongside the new gateway injection resources.
153+
====

‎service_mesh/v2x/ossm-gateway-migration.adoc

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="ossm-gateway-migration"]
3+
= Gateway migration
4+
include::_attributes/common-attributes.adoc[]
5+
:context: gateway-migration
6+
7+
toc::[]
8+
9+
As a network administrator, the preferred method for deploying ingress and egress gateways is with a `Deployment` resource using gateway injection.
10+
11+
include::modules/ossm-about-gateway-migration.adoc[leveloffset=+1]
12+
13+
include::modules/ossm-migrating-from-smcp-defined-gateways-to-gateway-injection.adoc[leveloffset=+1]
14+
15+
[role="_additional-resources"]
16+
[id="additional-resources_{context}"]
17+
== Additional resources
18+
19+
* xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-automatic-gateway-injection_traffic-management[Enabling gateway injection]
20+
21+
* xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-deploying-automatic-gateway-injection_traffic-management[Deploying automatic gateway injection]

‎service_mesh/v2x/ossm-route-migration.adoc

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="ossm-route-migration"]
3+
= Route migration
4+
include::_attributes/common-attributes.adoc[]
5+
:context: route-migration
6+
7+
toc::[]
8+
9+
Automatic route creation, also known as Istio OpenShift Routing (IOR), is a deprecated feature that is disabled by default for any `ServiceMeshControlPlane` resource that was created using {SMProductName} 2.5 and later. Migrating from IOR to explicitly-managed routes provides a more flexible way to manage and configure ingress gateways. When route resources are explicitly created they can be managed alongside the other gateway and application resources as part of a GitOps management model.
10+
11+
include::modules/ossm-migrating-from-ior-to-explicitly-managed-routes.adoc[leveloffset=+1]
12+
13+
[role="_additional-resources"]
14+
[id="additional-resources_{context}"]
15+
== Additional resources
16+
17+
* xref:../../networking/routes/route-configuration.adoc#nw-creating-a-route_route-configuration[Creating an HTTP-based Route]
18+
* xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-auto-route_traffic-management[Understanding automatic routes]

‎service_mesh/v2x/ossm-traffic-manage.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ include::modules/ossm-gateways.adoc[leveloffset=+1]
1212

1313
// Hiding in ROSA/OSD, dedicated-admin cannot create "services" or "deployments"
1414
ifndef::openshift-rosa,openshift-dedicated[]
15+
1516
include::modules/ossm-automatic-gateway-injection.adoc[leveloffset=+2]
1617

1718
include::modules/ossm-deploying-automatic-gateway-injection.adoc[leveloffset=+2]

0 commit comments

Comments
 (0)