OSSM-8509: Cluster-wide migration using the Istio revision label with cert manager #89396
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ---- |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
| ==== | ||
|
There was a problem hiding this comment. Next steps show up in the preview output but not here. I am puzzled! There was a problem hiding this comment. @aspauldi the next steps reside in the assembly file, not the module file. |
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.