diff --git a/migrating/docinfo.xml b/migrating/docinfo.xml index 9a4ee9a83107..d38a1acf4f94 100644 --- a/migrating/docinfo.xml +++ b/migrating/docinfo.xml @@ -10,4 +10,3 @@ Red Hat OpenShift Documentation Team - diff --git a/migrating/done/ossm-migrating-complete-assembly.adoc b/migrating/done/ossm-migrating-complete-assembly.adoc index f5b8866da20f..9a5bd866c202 100644 --- a/migrating/done/ossm-migrating-complete-assembly.adoc +++ b/migrating/done/ossm-migrating-complete-assembly.adoc @@ -2,6 +2,15 @@ [id=ossm-migrating-complete-assembly.adoc] = Completing the Migration include::_attributes/common-attributes.adoc[] -:context: ossm-migrating-deleting-2-6-assembly +:context: ossm-migrating-complete-assembly toc::[] + +include::modules/ossm-migrating-complete-multitant-cert-manager.adoc[leveloffset=+1] + +.Next steps + +* Remove {Smproduct} 2 + +//exrefs handled by OSSM-8852 +//may not be necessary; will depend on all the other migrating complete content in other PRs \ No newline at end of file diff --git a/migrating/multitenant/docinfo.xml b/migrating/multitenant/docinfo.xml index 6bddd07023f6..e287ecdc54be 100644 --- a/migrating/multitenant/docinfo.xml +++ b/migrating/multitenant/docinfo.xml @@ -1,12 +1,12 @@ Multitenant migration guide {product-title} {product-version} -Migrating a multitenant deployment +Multitenant migration guide - This document provides important information and step-by-step procedures for migrating a multitenant deployment from OpenShift Service Mesh 2 to OpenShift Service Mesh 3. + This document provides important information for migrating a multitenant deployment, and a multitenant deployment with the cert-manager tool. Red Hat OpenShift Documentation Team - \ No newline at end of file + diff --git a/migrating/multitenant/ossm-migrating-multitenant-assembly.adoc b/migrating/multitenant/ossm-migrating-multitenant-assembly.adoc index bdc402e50598..8956f6a972ef 100644 --- a/migrating/multitenant/ossm-migrating-multitenant-assembly.adoc +++ b/migrating/multitenant/ossm-migrating-multitenant-assembly.adoc @@ -6,3 +6,48 @@ include::_attributes/common-attributes.adoc[] toc::[] +This guide is for users who are currently running a multitenant deployment of {SMProductName} {SMv2Version}, and are migrating to {SMProduct} 3.0. + +[IMPORTANT] +==== +If you have not completed the premigration checklists, you must complete them first before you can start migrating your deployment. +==== + +include::modules/ossm-migrating-a-multitenant-deployment.adoc[leveloffset=+1] +include::modules/ossm-migrating-multitenant-workloads.adoc[leveloffset=+1] + +.Next steps + +If you are using gateways, you must migrate them before you complete the migration process for your deployment and workloads. + +* Migrate gateways +// +//xrefs across Migration Guides will be handled by OSSM-8852 + +If you are not using gateways, and have verified your mulitenant migration, you can proceed to complete the migration and remove {SMProduct} 2 resources. + +* Cleanup {SMProduct} 2 +// +//xrefs across Migration Guides will be handled by OSSM-8852 + +include::modules/ossm-migrating-multitenant-with-cert-manager.adoc[leveloffset=+1] +include::modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc[leveloffset=+1] + +.Next steps + +If you are using gateways, you must migrate them before you can complete the migration process for your deployment and workloads. + +* Migrate gateways +// +//xrefs across Migration Guides are handled by OSSM-8852 + +After you have migrated your gateways, you must update the `app.controller.configmapNamespaceSelector` field in your `istio-csr` deployment. + +If you are not using gateways, you can complete your migration with cert-manager. + +* Complete your migration with cert-manager +// +//xrefs across Migration Guides will be handled by OSSM-8852 + + +//Migration likely to resemble https://docs.openshift.com/container-platform/4.17/migrating_from_ocp_3_to_4/about-migrating-from-3-to-4.html#about-migrating-from-3-to-4 when done for OSSM 3.0 GA. \ No newline at end of file diff --git a/modules/ossm-migrating-a-multitenant-deployment.adoc b/modules/ossm-migrating-a-multitenant-deployment.adoc new file mode 100644 index 000000000000..49083ab6ad21 --- /dev/null +++ b/modules/ossm-migrating-a-multitenant-deployment.adoc @@ -0,0 +1,68 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-multitenant-assembly.adoc + +:_mod-docs-content-type: PROCEDURE +[id="migrating-a-multitenant-deployment_{context}""] += Migrating a multitenant deployment + +The `bookinfo` example application is being used for demonstration purposes with a minimal example for the `Istio` resource. For more information on configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping". + +You can follow these same steps with your own workloads. + +.Prerequisites + +* You have deployed {ocp-product-title} 4.14 or later. +* You are logged in to the {ocp-product-title} web console as a user with the cluster-admin role. +* You have completed the premigration checklists. +* You have the {SMProduct} {SMv2Version} Operator installed. +* You have the {SMProduct} 3 Operator installed. +* You created an `IstioCNI` resource. +* You have the `istioctl` tool installed. +* You are running a `MultiTenant` `ServiceMeshControlPlane`. +* You have installed the `bookinfo` application. + +.Procedure + +. Create your `Istio` resource. ++ +.Example `Istio` resource ++ +[source,yaml] +---- +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: + name: istio-tenant-a + spec: + namespace: istio-system-tenant-a <1> + version: v1.24.3 + values: + meshConfig: + discoverySelectors: <2> + - matchLabels: + tenant: tenant-a + extensionProviders: <3> + - name: prometheus + prometheus: {} + - name: otel + opentelemetry: + port: 4317 + service: otel-collector.opentelemetrycollector-3.svc.cluster.local +---- ++ +<1> The `spec.namespace` field in your `Istio` resource must be the same namespace as your `ServiceMeshControlPlane` resource. If you set the `spec.namespace` field in your `Istio` resource to a different namespace than your `ServiceMeshControlPlane` resource, the migration does not complete successfully. +<2> By default, control planes watch the entire cluster. When managing multiple control planes on a single cluster, you must narrow the scope of each control plane by setting `discoverySelectors` fields. In this example, the label `tenant` is used, but you can use any label or combination of labels. +<3> Optional: If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. + +. Add your `tenant` label to each one of your dataplane namespaces by running the following command for each dataplane namespace: ++ +[source,terminal] +---- +$ oc label ns bookinfo tenant=tenant-a +---- ++ +[NOTE] +==== +With {SMProduct} 2.6, namespaces were enrolled into the mesh by adding them to the `ServiceMeshMemberRoll` resource. In {SMProduct} 3, you must label each one of your dataplane namespaces to match your `discoverySelectors` fields. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-complete-multitant-cert-manager.adoc b/modules/ossm-migrating-complete-multitant-cert-manager.adoc new file mode 100644 index 000000000000..c8a63f228cac --- /dev/null +++ b/modules/ossm-migrating-complete-multitant-cert-manager.adoc @@ -0,0 +1,28 @@ + +// Module included in the following assemblies: +// +// * service-mesh-docs-main/multitenant/ossm-migrating-multitenant-assembly.adoc + +:_mod-docs-content-type: PROCEDURE +[id="migrating-complete-multitant-cert-manager_{context}""] += Completing a multitenant deployment with cert-manager + +.Prerequisites + +* You have migrated a multitenant deployment with the cert-manager and istio-csr tools. + +.Procedure + +. Verify that your new injection label is present in all workload namespaces. + +. Update the `app.controller.configmapNamespaceSelector` field by running the following command: ++ +[source,terminal] +---- +helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \ + --install \ + --reuse-values \ + --namespace istio-system \ + --wait \ + --set "app.controller.configmapNamespaceSelector=tenant=tenant-a" +---- diff --git a/modules/ossm-migrating-multitenant-with-cert-manager.adoc b/modules/ossm-migrating-multitenant-with-cert-manager.adoc new file mode 100644 index 000000000000..c325e3cc076d --- /dev/null +++ b/modules/ossm-migrating-multitenant-with-cert-manager.adoc @@ -0,0 +1,113 @@ + +// Module included in the following assemblies: +// +// * service-mesh-docs-main/multitenant/ossm-migrating-multitenant-assembly.adoc + +:_mod-docs-content-type: PROCEDURE +[id="migrating-multitenant-with-cert-manager_{context}""] += Migrating a multitenant deployment with cert-manager + +The `bookinfo` example application is being used for demonstration purposes with a minimal example for the `Istio` resource. For more information on configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping". + +You can follow these same steps with your own workloads. + +.Prerequisites + +* You have deployed {ocp-product-title} 4.14 or later. +* You are logged in to the {ocp-product-title} web console as a user with the cluster-admin role. +* You have completed the premigration checklists. +* You have the {SMProduct} {SMv2Version} Operator installed. +* You have the {SMProduct} 3 Operator installed. +* You created an `IstioCNI` resource. +* You have the `istioctl` tool installed. +* You are using the cert-manager and istio-csr tools in a multitenant deployment. +//change to "You are using the cert-manager and istio-csr tools in a cluster-wide deployment" for the cluster-wide procedure +* Your {SMProduct} 2 `ServiceMeshControlPlane` is configured with the cert-manager tool. + +.Procedure + +. Check that your {SMProduct} 2 `ServiceMeshControlPlane` is configured with the cert-manager-tool: ++ +.Example `ServiceMeshControlPlane` cert-manager configuration +[source,yaml] +---- +apiVersion: maistra.io/v2 +kind: ServiceMeshControlPlane +metadata: + name: basic + namespace: istio-system +spec: + ... + security: + certificateAuthority: + cert-manager: + address: cert-manager-istio-csr.istio-system.svc:443 + type: cert-manager + dataPlane: + mtls: true + identity: + type: ThirdParty + manageNetworkPolicy: false +---- + +. Update the `istio-csr` deployment to include your {SMProduct} 3 control plane by running the following command: ++ +[source,terminal] +---- + helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \ + --install \ + --reuse-values \ + --namespace istio-system \ + --wait \ + --set "app.istio.revisions={basic,istio-tenant-a}" <1> +---- ++ +<1> The `app.istio.revisions` field needs to include your {SMProduct} 3.0 control plane revision _before_ you create your `Istio` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane. + +. Create your `Istio` resource. ++ +.Example `Istio` resource with cert-manager ++ +[source,yaml] +---- +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: + name: istio-tenant-a +spec: + namespace: istio-system-tenant-a <1> + version: v1.24.3 + values: + meshConfig: + discoverySelectors: + - matchLabels: + tenant: tenant-a <2> + extensionProviders: <3> + - name: prometheus + prometheus: {} + - name: otel + opentelemetry: + port: 4317 + service: otel-collector.opentelemetrycollector-3.svc.cluster.local + global: + caAddress: cert-manager-istio-csr.istio-system.svc:443 + pilot: + env: + ENABLE_CA_SERVER: "false" +---- ++ +<1> The `spec.namespace` field in your `Istio` resource must be the _same_ namespace as your `ServiceMeshControlPlane` resource. If you set the `spec.namespace` field in your `Istio` resource to a different namespace than your `ServiceMeshControlPlane` resource, the migration will not work properly. +<2> By default, control planes watch the entire cluster. When managing multiple control planes on a single cluster, you must narrow the scope of each control plane by setting `discoverySelectors` fields. In this example, the label `tenant` is used, but you can use any label or combination of labels. +<3> Optional: If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. + +. Add your `tenant` label to each one of your dataplane namespaces by running the following command for each dataplane namespace: ++ +[source,terminal] +---- +$ oc label ns bookinfo tenant=tenant-a +---- ++ +[NOTE] +==== +With {SMProduct} 2.6, namespaces were enrolled into the mesh by adding them to the `ServiceMeshMemberRoll` resource. In {SMProduct} 3, you must label each one of your dataplane namespaces to match your `discoverySelectors` fields. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc b/modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc new file mode 100644 index 000000000000..6d06c7c5c08b --- /dev/null +++ b/modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc @@ -0,0 +1,128 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-multitenant-assembly.adoc + +:_mod-docs-content-type: PROCEDURE +[id="migrating-multitenant-workloads-with-cert-manager_{context}""] += Migrating workloads in a multitenant deployment with cert-manager + +Now you can migrate your workloads from the {SMProduct} 2.6 control plane to the {SMproduct} 3.0 control plane. + +[NOTE] +==== +You can migrate workloads and gateways separately, and in any order. For more information, see "Migrating gateways". +==== + +.Procedure + +. Find the current `IstioRevision` for your {SMProduct} 3.0 control plane by running the following command: ++ +[source,terminal] +---- +$ oc get istios istio-tenant-a +---- ++ +.Example output ++ +[source,terminal] +---- +NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE +istio-tenant-a 1 1 0 istio-tenant-a Healthy v1.24.1 30s +---- ++ +[NOTE] +==== +The naming format of your revisions depends on which upgrade strategy you choose for your `Istio` instance. +==== + +. Copy the `ACTIVE REVISION` to use as your `istio.io/rev` label in the next step. + +. Update injection labels on the `dataplane` namespace by running the following command: ++ +[source,terminal] +---- +$ oc label ns bookinfo istio.io/rev=istio-tenant-a maistra.io/ignore-namespace="true" --overwrite=true +---- ++ +This adds the following labels to the namespace: ++ +.. The `istio.io/rev: istio-tenant-a` label: Ensures that any new pods that get created in that namespace connect to the {SMProduct} 3.0 proxy. ++ +.. The `maistra.io/ignore-namespace: "true"` label: Disables sidecar injection for {SMProduct} 2.6 proxies in the namespace so {SMProduct} 2.6 stops injecting proxies in this namespace, and any new proxies are injected by {SMProduct} 3.0. Without this label, the {SMProduct} 2.6 injection webhook tries to inject the pod and the injected sidecar proxy will refuse to start since it will have both the {SMProduct} 2.6 and the {SMProduct} 3.0 Container Network Interface(CNI) annotations. ++ +[NOTE] +==== +Once you apply the `maistra.io/ignore-namespace` label, any new pod that gets created in the namespace connects to the {SMProduct} 3.0 proxy. Workloads can still communicate with each other regardless of which controlplane they are connected to. +==== + +. Restart the workloads by using one of the following options: ++ +.. To restart all the workloads at once so that the new pods are injected with the {SMProduct} 3.0 proxy, run the following command: ++ +.Example command for `bookinfo` application +[source,terminal] +---- +$ oc rollout restart deployments -n bookinfo +---- + +.. To restart each workload individually, run the following command for each workload: ++ +.Example command with `bookinfo` application +[source,terminal] +---- +$ oc rollout restart deployments productpage-v1 -n bookinfo +---- + +. Wait for the `productpage` application to restart by running the following command: ++ +[source,terminal] +---- +$ oc rollout status deployment productpage-v1 -n bookinfo +---- + +.Verification + +. Check that your workload is connected to the new control plane. + +.. Fetch the list of proxies that are still connected to the {SMProduct} 2.6 control plane with the `istioctl` tool by running the following command: ++ +[source,terminal] +---- +$ istioctl ps --istioNamespace istio-system-tenant-a --revision basic +---- ++ +In this example, `basic` is the name of your `ServiceMeshControlPlane`: ++ +.Example output ++ +[source,terminal] +---- + NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION + details-v1-7b49464bc-zr7nr.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-basic-6c9f8d9894-sh6lx 1.20.8 + ratings-v1-d6f449f59-9rds2.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-basic-6c9f8d9894-sh6lx 1.20.8 + reviews-v1-686cd989df-9x59z.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-basic-6c9f8d9894-sh6lx 1.20.8 + reviews-v2-785b8b48fc-l7xkj.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-basic-6c9f8d9894-sh6lx 1.20.8 + reviews-v3-67889ffd49-7bhxn.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-basic-6c9f8d9894-sh6lx 1.20.8 +---- + +.. View the list proxies that have been migrated to the new {SMProduct} 3.0 control plane by running the following command: ++ +[source,terminal] +---- +$ istioctl ps --istioNamespace istio-system-tenant-a --revision istio-tenant-a +---- ++ +.Example output ++ +[source, terminal] +---- +NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION +productpage-v1-7745c5cc94-wpvth.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED istiod-5bbf98dccf-n8566 1.24.3 +---- + +. Verify your application is still working correctly. For the `bookinfo` application, run the following command: ++ +[source,terminal] +---- +$ oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage +---- \ No newline at end of file diff --git a/modules/ossm-migrating-multitenant-workloads.adoc b/modules/ossm-migrating-multitenant-workloads.adoc new file mode 100644 index 000000000000..65828c9a63dc --- /dev/null +++ b/modules/ossm-migrating-multitenant-workloads.adoc @@ -0,0 +1,128 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-multitenant-assembly.adoc + +:_mod-docs-content-type: PROCEDURE +[id="migrating-multitenant-workloads_{context}""] += Migrating workloads in a multitenant deployment + +Now you can migrate your workloads from the {SMProduct} 2.6 control plane to the {SMproduct} 3.0 control plane. + +[NOTE] +==== +You can migrate workloads and gateways separately, and in any order. For more information, see "Migrating gateways". +==== + +.Procedure + +. Find the current `IstioRevision` for your {SMProduct} 3.0 control plane by running the following command: ++ +[source,terminal] +---- +$ oc get istios istio-tenant-a +---- ++ +.Example output ++ +[source,terminal] +---- +NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE +istio-tenant-a 1 1 0 istio-tenant-a Healthy v1.24.1 30s +---- ++ +[NOTE] +==== +The naming format of your revisions depends on which upgrade strategy you choose for your `Istio` instance. +==== + +. Copy the `ACTIVE REVISION` to use as your `istio.io/rev` label in the next step. + +. Update injection labels on the `dataplane` namespace by running the following command: ++ +[source,terminal] +---- +$ oc label ns bookinfo istio.io/rev=istio-tenant-a maistra.io/ignore-namespace="true" --overwrite=true +---- ++ +This adds the following labels to the namespace: ++ +.. The `istio.io/rev: istio-tenant-a` label: Ensures that any new pods that get created in that namespace connect to the {SMProduct} 3.0 proxy. ++ +.. The `maistra.io/ignore-namespace: "true"` label: Disables sidecar injection for {SMProduct} 2.6 proxies in the namespace so {SMProduct} 2.6 stops injecting proxies in this namespace, and any new proxies are injected by {SMProduct} 3.0. Without this label, the {SMProduct} 2.6 injection webhook tries to inject the pod and the injected sidecar proxy will refuse to start since it will have both the {SMProduct} 2.6 and the {SMProduct} 3.0 Container Network Interface(CNI) annotations. ++ +[NOTE] +==== +Once you apply the `maistra.io/ignore-namespace` label, any new pod that gets created in the namespace will connect to the {SMProduct} 3.0 proxy. Workloads can still communicate with each other regardless of which controlplane they are connected to. +==== + +. Restart the workloads by using one of the following options: ++ +.. To restart all the workloads at once so that the new pods are injected with the {SMProduct} 3.0 proxy, run the following command: ++ +.Example command for `bookinfo` application +[source,terminal] +---- +$ oc rollout restart deployments -n bookinfo +---- + +.. To restart each workload individually, run the following command for each workload: ++ +.Example command with `bookinfo` application +[source,terminal] +---- +$ oc rollout restart deployments productpage-v1 -n bookinfo +---- + +. Wait for the `productpage` application to restart by running the following command: ++ +[source,terminal] +---- +$ oc rollout status deployment productpage-v1 -n bookinfo +---- + +.Verification + +. Check that your workload is connected to the new control plane. + +.. Fetch the list of proxies that are still connected to the {SMProduct} 2.6 control plane with the `istioctl` tool by running the following command: ++ +[source,terminal] +---- +$ istioctl ps --istioNamespace istio-system-tenant-a --revision basic +---- ++ +In this example, `basic` is the name of your `ServiceMeshControlPlane`: ++ +.Example output ++ +[source,terminal] +---- + NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION + details-v1-7b49464bc-zr7nr.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-basic-6c9f8d9894-sh6lx 1.20.8 + ratings-v1-d6f449f59-9rds2.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-basic-6c9f8d9894-sh6lx 1.20.8 + reviews-v1-686cd989df-9x59z.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-basic-6c9f8d9894-sh6lx 1.20.8 + reviews-v2-785b8b48fc-l7xkj.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-basic-6c9f8d9894-sh6lx 1.20.8 + reviews-v3-67889ffd49-7bhxn.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-basic-6c9f8d9894-sh6lx 1.20.8 +---- + +.. View the list proxies that have been migrated to the new {SMProduct} 3.0 control plane by running the following command: ++ +[source,terminal] +---- +$ istioctl ps --istioNamespace istio-system-tenant-a --revision istio-tenant-a +---- ++ +.Example output ++ +[source, terminal] +---- +NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION +productpage-v1-7745c5cc94-wpvth.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED istiod-5bbf98dccf-n8566 1.24.3 +---- + +. Verify your application is still working correctly. For the `bookinfo` application, run the following command: ++ +[source,terminal] +---- +$ oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage +---- \ No newline at end of file