From 87c2bcfbb9084ee451c46be1319613e0cd78b9d9 Mon Sep 17 00:00:00 2001 From: Tim O'Keefe Date: Thu, 27 Feb 2025 10:21:23 -0500 Subject: [PATCH] OSSM-8958: Cluster-wide migration using istio-injection label --- .../ossm-migrating-cluster-wide-assembly.adoc | 28 +++++ ...yment-using-the-istio-injection-label.adoc | 101 ++++++++++++++++ ...loads-using-the-istio-injection-label.adoc | 113 ++++++++++++++++++ 3 files changed, 242 insertions(+) create mode 100644 modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc create mode 100644 modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc diff --git a/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc b/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc index 9f2e749207cc..1094e74e409c 100644 --- a/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc +++ b/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc @@ -17,6 +17,7 @@ include::modules/ossm-control-plane-configuration-migration-requirements.adoc[le include::modules/ossm-cluster-wide-migration-methods.adoc[leveloffset=+1] +// The following tasks are for migration using the Istio revision label include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label.adoc[leveloffset=+1] [role="_additional-resources"] @@ -33,3 +34,30 @@ include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespa You can proceed to complete the migration and remove {SMProduct} 2 resources. * xref:../../migrating/done/ossm-migrating-complete-assembly.adoc[Completing the Migration] + +// The following tasks are for migration using the Istio injection label +include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../../install/ossm-sidecar-injection-assembly.adoc#ossm-identifying-revision-name_ossm-sidecar-injection-assembly[Identifying the revision name] + +include::modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc[leveloffset=+2] + +.Next steps + +If you are using gateways, you must migrate them before you complete the migration process. + +* xref:../../migrating/migrating-gateways/ossm-migrating-gateways-assembly.adoc[Migrating gateways from Service Mesh 2 to Service Mesh 3] + +If you are not using gateways, and have verified your cluster-wide migration, create a default revision tag and re-label namespaces. + +[IMPORTANT] +==== +Before creating a default revision tag and relabelling the namespaces, you must migrate all remaining workload namespaces, including gateways. +==== + +// insert xref to "Creating the default revision tag and relabeling the namespaces" after PR OSSM-9000 is merged + +* Creating the default revision tag and relabeling the namespaces diff --git a/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc b/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc new file mode 100644 index 000000000000..79678c2be077 --- /dev/null +++ b/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc @@ -0,0 +1,101 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label_{context}"] += Migrating a cluster-wide deployment by using the istio injection label + +You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the `istio-injection=enabled` label and the `default` revision tag. + +You must re-label all of the data plane namespaces. However, it is safe to restart any of the workloads at any point during the migration process. + +The `bookinfo` application is used as an example for the `Istio` resource. For more information about configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping". + +.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 have created an `IstioCNI` resource. +* You have installed the `istioctl` tool. +* You are running a cluster-wide Service Mesh control plane resource. +* You have installed the `bookinfo` application. + +.Procedure + +. Identify the namespaces that contain a 2.6 control plane by running the following command: ++ +[source,terminal] +---- +$ oc get smcp -A +---- ++ +.Example output +[source,terminal] +---- +NAMESPACE NAME READY STATUS PROFILES VERSION AGE +istio-system install-istio-system 6/6 ComponentsReady ["default"] 2.6.6 115m +---- + +. Create a YAML file named `ossm-3.yaml`. This procedure creates the {istio} resource for the 3.0 installation in the same namespace as the `ServiceMeshControlPlane` resource for the 2.6 installation. ++ +[NOTE] +==== +In the following example configuration, the {istio} control plane has access to all namespaces on the cluster. If you want to limit the namespaces the control plan has access to, you must define discovery selectors. You must match all the data plane namespaces that you plan to migrate from version 2.6. +==== ++ +.Example `Istio` resource +[source,yaml,subs="attributes,verbatim"] +---- +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: + name: ossm-3 # <1> +spec: + updateStrategy: + type: RevisionBased + namespace: istio-system # <2> + version: v1.24.3 + values: + meshConfig: + extensionProviders: # <3> + - name: prometheus + prometheus: {} + - name: otel + opentelemetry: + port: 4317 + service: otel-collector.opentelemetrycollector-3.svc.cluster.local +---- +<1> The `name`, `updateStrategy` and `version` fields specify how the `IstioRevision` resource name is created. For more information, see "Identifying the revision name". +<2> The 3.0 and 2.6 control planes must run in the same namespace. +<3> Optional: If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. ++ +[NOTE] +==== +To prevent the {SMProduct} 3.0 control plane from injecting proxies in the namespaces that have the `istio-injection=enabled` label applied and are still managed by {SMProduct} 2.6 control plane, do not use use the `default` name for the {istio} resource, and do not create the `default` revision tag in the following steps. You create the `default` revision tag later in this procedure. +==== + +. Apply the YAML file by running the following command: ++ +[source,terminal] +---- +$ oc apply -f ossm-3.yaml +---- + +.Verification + +. Verify that the new `istiod` resource uses the existing root certificate by running the following command: ++ +[source,terminal] +---- +$ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret' +---- ++ +.Example output +[source,terminal] +---- +2024-12-18T08:13:53.788959Z info pkica Load signing key and cert from existing secret istio-system/istio-ca-secret +---- \ No newline at end of file diff --git a/modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc b/modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc new file mode 100644 index 000000000000..36219c9ded01 --- /dev/null +++ b/modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc @@ -0,0 +1,113 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-migrating-workloads-using-the-istio-injection-label_{context}"] += Migrating workloads by using the istio injection label + +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` resource for your {SMProduct} 3.0 control plane by running the following command: ++ +[source,terminal] +---- +$ oc get istios +---- ++ +.Example output ++ +[source,terminal] +---- +NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE +ossm-3 1 1 0 ossm-3-v1-24-3 Healthy v1.24.3 30s +---- + +. Copy the `ACTIVE REVISION` value to use as your `istio.io/rev` label in the next step. ++ +[NOTE] +==== +The naming format of your revisions depends on which upgrade strategy you choose for your `Istio` instance. +==== + +. Update the injection labels on the data plane namespace by running the following command: ++ +[source,terminal] +---- +$ oc label ns bookinfo istio.io/rev=ossm-3-v1-24-3 maistra.io/ignore-namespace="true" istio-injection- --overwrite=true +---- ++ +The `oc label` command performs the following actions: + +.. Removes the `istio-injection` label: This label prevents the 3.0 control plane from injecting the proxy. The `istio-injection` label takes precedence over the `istio.io/rev` label. You must temporarily remove the `istio-injection=enabled` because you cannot create the default `IstioRevisionTag` tag yet. Leaving the `istio-injection=enabled` label applied would prevent the 3.0 control plane from performing proxy injection. + +.. Adds the `istio.io/rev=ossm-3-v1-24-3` label: This label ensures that any newly created or restarted pods in the namespace connect to the {SMProduct} 3.0 proxy. + +.. Adds the `maistra.io/ignore-namespace: "true"` label: This label disables sidecar injection for {SMProduct} 2.6 proxies in the namespace. With the label applied, {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 refuses to start since it will has both the {SMProduct} 2.6 and the {SMProduct} 3.0 Container Network Interface(CNI) annotations. ++ +[NOTE] +==== +After 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 control plane they are connected to. +==== + +. Restart the workloads by using one of the following options: ++ +.. To restart all the workloads at the same time 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 for `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 + +. Verify that the the new control plane manages the expected workloads by running the following command: ++ +[source,terminal] +---- +$ istioctl ps -n bookinfo +---- ++ +.Example output: +[source,terminal] +---- +NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION +details-v1-7f46897b-d497c.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8 +productpage-v1-74bfbd4d65-vsxqm.bookinfo Kubernetes SYNCED (4s) SYNCED (4s) SYNCED (3s) SYNCED (4s) IGNORED istiod-ossm-3-v1-24-3-797bb4d78f-xpchx 1.24.3 +ratings-v1-559b64556-c5ppg.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8 +reviews-v1-847fb7c54d-qxt5d.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8 +reviews-v2-5c7ff5b77b-8jbhd.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8 +reviews-v3-5c5d764c9b-rrx8w.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8 +---- ++ +The output shows that the `productpage-v1` deployment is the only deployment that has been restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between the services still works. + +. If the 2.6 installation contains additional namespaces, migrate the next namespace now. ++ +[NOTE] +==== +Remove the `maistra.io/ignore-namespace="true"` label only after the 2.6 control plane has been uninstalled. +==== \ No newline at end of file