From b765b49a5d4dff5a4a6c22976086cefc4c63e9c9 Mon Sep 17 00:00:00 2001 From: Tim O'Keefe Date: Fri, 28 Feb 2025 11:13:54 -0500 Subject: [PATCH] OSSM-8509: Cluster-wide migration with cert manager broken build --- .../ossm-migrating-cluster-wide-assembly.adoc | 50 +++++-- ...stio-revision-label-with-cert-manager.adoc | 132 ++++++++++++++++++ ...stio-revision-label-with-cert-manager.adoc | 116 +++++++++++++++ 3 files changed, 286 insertions(+), 12 deletions(-) create mode 100644 modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc create mode 100644 modules/ossm-migrating-workloads-using-the-istio-revision-label-with-cert-manager.adoc diff --git a/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc b/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc index 1094e74e409c..a957603788c8 100644 --- a/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc +++ b/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc @@ -1,3 +1,7 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc + :_mod-docs-content-type: ASSEMBLY [id=ossm-migrating-cluster-wide-assembly] = Cluster-wide migration guide @@ -17,31 +21,41 @@ 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"] -.Additional resources +include::modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc[leveloffset=+2] -* xref:../../install/ossm-sidecar-injection-assembly.adoc#ossm-identifying-revision-name_ossm-sidecar-injection-assembly[Identifying the revision name] +.Next steps -include::modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc[leveloffset=+2] +If you are using gateways, you must migrate them before you complete the migration process. -include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces.adoc[leveloffset=+1] +* 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, 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 the Istio revision label with cert-manager +include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc[leveloffset=+1] + +include::modules/ossm-migrating-workloads-using-the-istio-revision-label-with-cert-manager.adoc[leveloffset=+2] .Next steps -You can proceed to complete the migration and remove {SMProduct} 2 resources. +If you are using gateways, you must migrate them before you complete the migration process. -* xref:../../migrating/done/ossm-migrating-complete-assembly.adoc[Completing the Migration] +* xref:../../migrating/migrating-gateways/ossm-migrating-gateways-assembly.adoc[Migrating gateways from Service Mesh 2 to Service Mesh 3] -// 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] +If you are not using gateways, and have verified your cluster-wide migration, you can proceed to complete the migration and remove {SMProduct} 2 resources. -[role="_additional-resources"] -.Additional resources +* xref:../../migrating/done/ossm-migrating-complete-assembly.adoc[Completing the Migration] -* xref:../../install/ossm-sidecar-injection-assembly.adoc#ossm-identifying-revision-name_ossm-sidecar-injection-assembly[Identifying the revision name] +// The following tasks are for the Istio injection label + +include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc[leveloffset=+1] include::modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc[leveloffset=+2] @@ -53,6 +67,14 @@ If you are using gateways, you must migrate them before you complete the migrati If you are not using gateways, and have verified your cluster-wide migration, create a default revision tag and re-label namespaces. +include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces.adoc[leveloffset=+2] + +.Next steps + +You can proceed to complete the migration and remove {SMProduct} 2 resources. + +* xref:../../migrating/done/ossm-migrating-complete-assembly.adoc[Completing the Migration] + [IMPORTANT] ==== Before creating a default revision tag and relabelling the namespaces, you must migrate all remaining workload namespaces, including gateways. @@ -61,3 +83,7 @@ Before creating a default revision tag and relabelling the namespaces, you must // 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 +[role="_additional-resources"] +.Additional resources + +* xref:../../install/ossm-sidecar-injection-assembly.adoc#ossm-identifying-revision-name_ossm-sidecar-injection-assembly[Identifying the revision name] diff --git a/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc b/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc new file mode 100644 index 000000000000..33d1a9219e92 --- /dev/null +++ b/modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc @@ -0,0 +1,132 @@ +// 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-revision-label-with-cert-manager_{context}"] += Migrating a cluster-wide deployment by using the Istio revision label with cert-manager + +You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the `istio.io/rev` label with cert-manager. + +The `bookinfo` application is used as an example for the `Istio` resource. For more information on configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "Configuration fields mapping between Service Mesh 2 and Service Mesh 3." + +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 installed the {SMProduct} {SMv2Version} Operator. +* You have installed the {SMProduct} 3 Operator. +* You have created an `IstioCNI` resource. +* You have installed the `istioctl` tool. +* You are using the cert-manager and istio-csr tools in a cluster-wide deployment. +* Your {SMProduct} 2 `ServiceMeshControlPlane` resource is configured with the cert-manager tool. + +.Procedure + +. Check that your {SMProduct} 2 `ServiceMeshControlPlane` resource 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,ossm-3-v1-24-3}" <1> +---- ++ +<1> The `app.istio.revisions` field must 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. + +. 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: ++ +.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 + global: + caAddress: cert-manager-istio-csr.istio-system.svc:443 + pilot: + env: + ENABLE_CA_SERVER: "false" +---- +<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> If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations. + +. Apply the YAML file by running the following command: ++ +[source,terminal] +---- +$ oc apply -f ossm-3.yaml +---- + +. 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-revision-label-with-cert-manager.adoc b/modules/ossm-migrating-workloads-using-the-istio-revision-label-with-cert-manager.adoc new file mode 100644 index 000000000000..8578aa67d470 --- /dev/null +++ b/modules/ossm-migrating-workloads-using-the-istio-revision-label-with-cert-manager.adoc @@ -0,0 +1,116 @@ +// 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-revision-label-with-cert-manager_{context}"] += Migrating workloads by using the Istio revision label with cert-manager + +After migrating a cluster-wide deployment, you can migrate your workloads workloads from the {SMProduct} 2.6 control plane to the {SMproduct} 3.0 control plane. + +To maintain simplicity, revision tags are not used in this example. When migrating large meshes, you can use revision tags to avoid re-labeling all namespaces during future 3.y.z upgrades. + +[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 value in the `ACTIVE REVISION` column 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 `dataplane` 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 +---- ++ +Running 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 `istio.io/rev` label. + +.. 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 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 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 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 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 expected workloads are managed by the new control plane 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-1-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 restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between services still works. + +. If the 2.6 installation contains additional data plane 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. +====