openshift · kalexand-rh · Aug 8, 2024 · Jul 1, 2024
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -4076,6 +4076,10 @@ Topics:
     File: ossm-security
   - Name: Traffic management
     File: ossm-traffic-manage
+  - Name: Gateway migration
+    File: ossm-gateway-migration
+  - Name: Route migration
+    File: ossm-route-migration
   - Name: Metrics, logs, and traces
     File: ossm-observability
   - Name: Performance and scalability

diff --git a/modules/ossm-about-gateway-migration.adoc b/modules/ossm-about-gateway-migration.adoc
@@ -0,0 +1,11 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/ossm-gateway-migration.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-gateway-migration_{context}"]
+
+= About gateway migration
+
+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. 
+
+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.
diff --git a/modules/ossm-migrating-from-ior-to-explicitly-managed-routes.adoc b/modules/ossm-migrating-from-ior-to-explicitly-managed-routes.adoc
@@ -0,0 +1,48 @@
+// Module included in the following assemblies:
+// * service_mesh/v2x/ossm-route-migration.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-migrating-from-ior-to-explicitly-managed-routes_{context}"]
+= Migrating from Istio OpenShift Routing to explicitly-managed routes
+
+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.
+
+.Prerequisites
+
+* 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.
+
+.Procedure
+
+* Modify the `ServiceMeshControlPlane` resource to disable IOR:
++
+[source,yaml]
+----
+apiVersion: maistra.io/v2
+kind: ServiceMeshControlPlane
+spec:
+  gateways:
+    openshiftRoute:
+      enabled: false
+----
++
+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:
++
+[source,yaml]
+----
+kind: Route
+apiVersion: route.openshift.io/v1
+metadata:
+  name: example-gateway
+  namespace: istio-system <1>
+spec:
+  host: www.example.com
+  to:
+    kind: Service
+    name: istio-ingressgateway <2>
+    weight: 100
+  port:
+    targetPort: http2
+  wildcardPolicy: None
+----
+<1> Specify new routes in the same namespace as the ingress gateway `Service` object.
+<2> Use the name of ingress gateway `Service` object that is the target. 
diff --git a/modules/ossm-migrating-from-smcp-defined-gateways-to-gateway-injection.adoc b/modules/ossm-migrating-from-smcp-defined-gateways-to-gateway-injection.adoc
@@ -0,0 +1,153 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v2x/ossm-gateway-migration.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-migrating-from-smcp-defined-gateways-to-gateway-injection_{context}"]
+= Migrate from SMCP-Defined gateways to gateway injection
+
+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.
+
+.Prerequisites
+
+* You are logged in to the {product-title} web console as `cluster-admin`.
+
+* The {SMProductName} Operator must be installed.
+
+* The `ServiceMeshControlPlane` resource must be deployed and an ingress gateway exists in the configuration.
+
+.Procedure
+
+. Create a new ingress gateway that is configured to use gateway injection. 
++
+[NOTE]
+====
+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.    
+====
++
+.Example ingress gateway resource with gateway injection
+[source,yaml, subs="attributes,verbatim"]
+----
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: istio-ingressgateway-canary 
+  namespace: istio-system <1>
+spec:
+  selector:
+    matchLabels:
+      app: istio-ingressgateway
+      istio: ingressgateway 
+  template:
+    metadata:
+      annotations:
+        inject.istio.io/templates: gateway
+      labels: <2>
+        app: istio-ingressgateway
+        istio: ingressgateway
+        sidecar.istio.io/inject: "true"
+    spec:
+      containers:
+        - name: istio-proxy
+          image: auto
+      serviceAccountName: istio-ingressgateway
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: istio-ingressgateway
+  namespace: istio-system
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: secret-reader
+  namespace: istio-system
+rules:
+  - apiGroups: [""]
+    resources: ["secrets"]
+    verbs: ["get", "watch", "list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: istio-ingressgateway-secret-reader
+  namespace: istio-system
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: secret-reader
+subjects:
+  - kind: ServiceAccount
+    name: istio-ingressgateway
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy <3>
+metadata:
+  name: gatewayingress
+  namespace: istio-system
+spec:
+  podSelector:
+    matchLabels:
+      istio: ingressgateway
+  ingress:
+    - {}
+  policyTypes:
+    - Ingress
+---- 
+<1> The gateway injection deployment and all supporting resources should be deployed in the same namespace as the SMCP-defined gateway. 
+<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.
+<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.
+
+. Verify that the new gateway deployment is successfully handling requests. 
++
+If access logging was configured in the `ServiceMeshControlPlane` resource, view the access logs of the new gateway deployment to confirm the behavior.
+
+. Scale down the old deployment and scale up the new deployment. 
++
+Gradually shift traffic from the old gateway deployment to the new gateway deployment by performing the following steps:
+
+.. Increase the number of replicas for the new gateway deployment by running the following command:
++
+[source,terminal]
+----
+$ oc scale -n istio-system deployment/<new_gateway_deployment> --replicas <new_number_of_replicas>
+----
+.. Decrease the number of replicas for the old gateway deployment by running the following command:
++
+[source,terminal]
+----
+$ oc scale -n istio-system deployment/<old_gateway_deployment> --replicas <new_number_of_replicas>
+----
+
+.. 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. 
+
+. Remove the `app.kubernetes.io/managed-by` label from the gateway `Service` object by running the following command:
++
+[source,terminal]
+----
+$ oc label service -n istio-system istio-ingressgateway app.kubernetes.io/managed-by-
+----
++
+Removing the label prevents the service from being deleted when the gateway is disabled in the `ServiceMeshControlPlane` resource. 
+
+. Remove the `ownerReferences` object from the gateway `Service` object by running the following command:
++
+[source,terminal]
+----
+$ oc patch service -n istio-system istio-ingressgateway --type='json' -p='[{"op": "remove", "path": "/metadata/ownerReferences"}]'
+----
++
+Removing this object prevents the service from being garbage collected when the `ServiceMeshControlPlane` resource is deleted.
+
+. Disable the old gateway deployment that was managed by the `ServiceMeshControlPlane` resource by running the following command:
++
+[source,terminal]
+----
+$ oc patch smcp -n istio-system <smcp_name> --type='json' -p='[{"op": "replace", "path": "/spec/gateways/ingress/enabled", "value": false}]'
+----
++
+[NOTE]
+====
+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.
+====
diff --git a/service_mesh/v2x/ossm-gateway-migration.adoc b/service_mesh/v2x/ossm-gateway-migration.adoc
@@ -0,0 +1,21 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ossm-gateway-migration"]
+= Gateway migration
+include::_attributes/common-attributes.adoc[]
+:context: gateway-migration
+
+toc::[]
+
+As a network administrator, the preferred method for deploying ingress and egress gateways is with a `Deployment` resource using gateway injection.
+
+include::modules/ossm-about-gateway-migration.adoc[leveloffset=+1]
+
+include::modules/ossm-migrating-from-smcp-defined-gateways-to-gateway-injection.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+
+* xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-automatic-gateway-injection_traffic-management[Enabling gateway injection]
+
+* xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-deploying-automatic-gateway-injection_traffic-management[Deploying automatic gateway injection]
diff --git a/service_mesh/v2x/ossm-route-migration.adoc b/service_mesh/v2x/ossm-route-migration.adoc
@@ -0,0 +1,18 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ossm-route-migration"]
+= Route migration
+include::_attributes/common-attributes.adoc[]
+:context: route-migration
+
+toc::[]
+
+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.
+
+include::modules/ossm-migrating-from-ior-to-explicitly-managed-routes.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+
+* xref:../../networking/routes/route-configuration.adoc#nw-creating-a-route_route-configuration[Creating an HTTP-based Route]
+* xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-auto-route_traffic-management[Understanding automatic routes]
diff --git a/service_mesh/v2x/ossm-traffic-manage.adoc b/service_mesh/v2x/ossm-traffic-manage.adoc
@@ -12,6 +12,7 @@ include::modules/ossm-gateways.adoc[leveloffset=+1]
 
 // Hiding in ROSA/OSD, dedicated-admin cannot create "services" or "deployments"
 ifndef::openshift-rosa,openshift-dedicated[]
+
 include::modules/ossm-automatic-gateway-injection.adoc[leveloffset=+2]
 
 include::modules/ossm-deploying-automatic-gateway-injection.adoc[leveloffset=+2]