3.0 GA OSSM-8673 Pre-migration checklist for product docs #86912

gwynnemonahan · 2025-01-10T17:12:29Z

THIS PR IS BEING USED TO STRUCTURE ALL OSSM 2.6.Z TO 3.0 MIGRATION CONTENT

Content in this PR is not in line with current style. This PR is being used to establish the Information Architecture of the Migration Guides.

This PR will likely be broken up into separate PRs that correspond to the respective section Jiras found in the Migration Guides Epic.

01/21/2025: This PR has been shared via the Service Mesh AMA meeting notes, the Service Mesh Program Call notes, and the team-ossm-all Slack channel for the purposes of feedback on the information architecture, how users may move through this content, etc.

OSSM 3.0 GA

https://issues.redhat.com/browse/OSSM-8673

Merge to: https://github.com/openshift/openshift-docs/tree/service-mesh-docs-main

Cherry pick to: TBD but likely something like https://github.com/openshift/openshift-docs/tree/service-mesh-docs-3.0.0

This PR is part of the standalone doc set for the OpenShift Service Mesh project. Kathryn is aware that this content applies for a product that is part of a Technology Preview release. The project is seeking feedback from early adopters.

Version(s):

Technology Preview.

OSSM 3.0 is moving to stand alone format so it will not be cherry-picked back to OCP core branches.

Issue:
https://issues.redhat.com/browse/OSSM-8673

Link to docs preview:
https://86912--ocpdocs-pr.netlify.app/openshift-service-mesh/latest/migrating/checklist/ossm-migrating-migration-guides-assembly.html
https://86912--ocpdocs-pr.netlify.app/openshift-service-mesh/latest/migrating/checklist/ossm-migrating-premigration-checklist-assembly.html
https://86912--ocpdocs-pr.netlify.app/openshift-service-mesh/latest/migrating/checklist/ossm-migrating-read-me-assembly.html
https://86912--ocpdocs-pr.netlify.app/openshift-service-mesh/latest/migrating/multitenant/ossm-migrating-multitenant-assembly.html
https://86912--ocpdocs-pr.netlify.app/openshift-service-mesh/latest/migrating/multitenant/ossm-migrating-multitenant-cert-manager-assembly.html
https://86912--ocpdocs-pr.netlify.app/openshift-service-mesh/latest/migrating/ossm-migrating-from-2-6-to-3-0-assembly.html

QE review:

QE has approved this change.

Additional information:

ocpdocs-previewbot · 2025-01-10T17:21:44Z

🤖 Thu Jan 23 21:11:44 - Prow CI generated the docs preview:
https://86912--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

longmuir · 2025-01-13T22:04:44Z

migrating/ossm-migrating-premigration-checklist-assembly.adoc

+** [ ] Disable Kiali by setting `spec.addons.kiali.enabled=false``. See "Kiali Operator provided by Red Hat" for instructions installing and configuring {KialiProduct} with {SMProduct} 3.0.
+** [ ] Disable Grafana by setting `spec.addons.grafana.enabled=false`.
+** [ ] Disable {DTProductName} by setting `spec.tracing.type=None`. See "{DTProductName}" for instructions on configuring {SMProduct} 3.0 with {DTProductName}.
+IOR is disabled.


For the last two steps, "IOR is disabled" and "Disable default ingress and egress gateways", we should link to the specific content that describes how to make these changes. That is, Route migration and Gateway Migration

longmuir · 2025-01-13T22:05:33Z

migrating/ossm-migrating-premigration-checklist-assembly.adoc

+These addons are not supported in {SMProduct} 3.0 and must be disabled before migrating.
+
+** [ ] Disable network policy management by setting `spec.security.manageNetworkPolicy=false`. If you wish to keep the Network Policies created by the 2.6 ServiceMeshControlPlane, you will need to recreate and manage these manually.
+** [ ] Disable Prometheus by setting `spec.addons.prometheus.enabled=false`. See "User workload monitoring" for instructions configuring {SMProduct}h 3.0 with OpenShift Monitoring as a replacement for Prometheus.


Users may want to make this change before migrating to OSSM 3, in which case, we should link to the 2.x documentation for using user-workload monitoring, located here: https://docs.openshift.com/container-platform/4.17/service_mesh/v2x/ossm-observability.html#ossm-integrating-with-user-workload-monitoring_observability.

longmuir · 2025-01-13T22:07:04Z

migrating/ossm-migrating-premigration-checklist-assembly.adoc

+** [ ] Disable Prometheus by setting `spec.addons.prometheus.enabled=false`. See "User workload monitoring" for instructions configuring {SMProduct}h 3.0 with OpenShift Monitoring as a replacement for Prometheus.
+** [ ] Disable Kiali by setting `spec.addons.kiali.enabled=false``. See "Kiali Operator provided by Red Hat" for instructions installing and configuring {KialiProduct} with {SMProduct} 3.0.
+** [ ] Disable Grafana by setting `spec.addons.grafana.enabled=false`.
+** [ ] Disable {DTProductName} by setting `spec.tracing.type=None`. See "{DTProductName}" for instructions on configuring {SMProduct} 3.0 with {DTProductName}.


Likewise, users may wish to make this migration before moving to 3.0, which can be done by following these instructions: https://docs.openshift.com/container-platform/4.17/service_mesh/v2x/ossm-observability.html#ossm-overview-distr-tracing_observability

nrfox · 2025-01-22T11:45:39Z

migrating/checklist/ossm-migrating-premigration-checklist-assembly.adoc

+//Applicable PR: https://github.com/openshift/openshift-docs/pull/86917
+//will contain both mulitenant and cert-manager procedures
+
+.Next steps for multitenant deployments with cert-manager


Not sure if this affects how you structure things or not but the migration guide for cert-manager is essentially the same for both MultiTenant and ClusterWide. The only difference is that some MultiTenant deployments might be using a specific field/feature of cert-manager in which case they will need to handle it differently than ClusterWide.

I'm remembering now we discussed that some duplication was better than having the guide more scattered

nrfox · 2025-01-22T11:52:04Z

modules/ossm-migrating-multitenant-migration-guide.adoc

+*2*. Ensure the `bookinfo` application is still working correctly.
+
+   ```sh
+   oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage
+   ```
+
+   Example response:
+
+   ```html
+   ...
+           <p>Absolutely fun and entertaining. The play lacks thematic depth when compared to other plays by Shakespeare.</p>
+           <small>Reviewer2</small>
+
+
+           <font color="black">
+             <!-- full stars: -->
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <!-- empty stars: -->
+
+             <span class="glyphicon glyphicon-star-empty"></span>
+
+           </font>
+
+
+         </blockquote>
+
+         <dl>
+           <dt>Reviews served by:</dt>
+           <u>reviews-v2-6dd458b5db-frrlb</u>
+
+         </dl>
+   ...
+   ```


I wonder if we need to include this step. I know it was included in the OSSM docs but this example just shows that bookinfo is working correctly however users will not be migrating bookinfo. They will be migrating their own apps which will have their own ways of verifying that they work correctly and having this bookinfo specific step here may confuse people and I think is unnecessary. Simply having the previous step showing the updated proxy connected to the 3.0 controlplane is enough.

nrfox · 2025-01-22T11:53:54Z

modules/ossm-migrating-multitenant-migration-guide.adoc

+*2*. `curl` the productpage pod in `bookinfo` to ensure proxies can still communicate with one another.
+
+   ```sh
+   oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage
+   ```
+
+   You should see
+
+   ```html
+   ...
+           <p>Absolutely fun and entertaining. The play lacks thematic depth when compared to other plays by Shakespeare.</p>
+           <small>Reviewer2</small>
+
+
+           <font color="black">
+             <!-- full stars: -->
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <!-- empty stars: -->
+
+             <span class="glyphicon glyphicon-star-empty"></span>
+
+           </font>
+
+
+         </blockquote>
+
+         <dl>
+           <dt>Reviews served by:</dt>
+           <u>reviews-v2-6dd458b5db-frrlb</u>
+
+         </dl>
+   ...
+   ```


Same comment as below with removing this example since it is specific to bookinfo and not generally useful to users' actual apps.

nrfox · 2025-01-22T11:55:11Z

modules/ossm-migrating-multitenant-with-cert-manager.adoc

+*2*. `curl` the productpage pod in `bookinfo` to ensure proxies can still communicate with one another.
+
+   ```sh
+   oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage
+   ```
+
+   You should see
+
+   ```html
+   ...
+           <p>Absolutely fun and entertaining. The play lacks thematic depth when compared to other plays by Shakespeare.</p>
+           <small>Reviewer2</small>
+
+
+           <font color="black">
+             <!-- full stars: -->
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <!-- empty stars: -->
+
+             <span class="glyphicon glyphicon-star-empty"></span>
+
+           </font>
+
+
+         </blockquote>
+
+         <dl>
+           <dt>Reviews served by:</dt>
+           <u>reviews-v2-6dd458b5db-frrlb</u>
+
+         </dl>
+   ...
+   ```


Same comment here as above.

nrfox · 2025-01-22T11:55:22Z

modules/ossm-migrating-multitenant-with-cert-manager.adoc

+*2*. Ensure the `bookinfo` application is still working correctly.
+
+   ```sh
+   oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage
+   ```
+
+   Example response:
+
+   ```html
+   ...
+           <p>Absolutely fun and entertaining. The play lacks thematic depth when compared to other plays by Shakespeare.</p>
+           <small>Reviewer2</small>
+
+
+           <font color="black">
+             <!-- full stars: -->
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <!-- empty stars: -->
+
+             <span class="glyphicon glyphicon-star-empty"></span>
+
+           </font>
+
+
+         </blockquote>
+
+         <dl>
+           <dt>Reviews served by:</dt>
+           <u>reviews-v2-6dd458b5db-frrlb</u>
+
+         </dl>
+   ...
+   ```


…o see the whole picture

…it 2 commits ago (Squash)

… before starting to migratin (Squash)

…ltitenant content (Squash)

…is completed (Squash)

…son (Squash)

…y migration content for 3.0, not just the 2.x content

openshift-ci · 2025-01-23T21:14:54Z

@gwynnemonahan: all tests passed!

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

openshift-ci bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Jan 10, 2025

openshift-ci bot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Jan 10, 2025

longmuir reviewed Jan 13, 2025

View reviewed changes

openshift-ci bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Jan 14, 2025

gwynnemonahan force-pushed the OSSM-8673 branch from 4b7c29a to b894820 Compare January 14, 2025 18:29

gwynnemonahan force-pushed the OSSM-8673 branch from 1eb3f27 to ce99022 Compare January 16, 2025 14:57

openshift-ci bot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Jan 16, 2025

nrfox reviewed Jan 22, 2025

View reviewed changes

gwynnemonahan added 11 commits January 22, 2025 10:18

OSSM-8673 Pre-migration checklist for product docs

410d7ed

Typo (Squas)

05076b4

File reorg (Squash)

d180ba6

PR being used to structure all of the migration content in one spot t…

1fde0aa

…o see the whole picture

Remove extra space (Squash)

ffdeb13

topic map missing Name (Squash)

fdb3640

topic map (Squash)

4cdb67d

testing something (Squash)

4d0ccdc

Moved Important info to Checklist dir (Squash)

6336dca

topic map shenannigans (Squash)

a0dde22

squash it

94ebda4

gwynnemonahan added 13 commits January 22, 2025 10:18

Creating cluster-wide dir (Squash)

6b7bf86

Prow didn't like mutlitenant-cert-manager even though it approved of …

303c391

…it 2 commits ago (Squash)

docinfo updates, missing space in topic_map (Squash)

e707811

Adding Kiali v1 to v2 content in checklist dir as it needs to be done…

2a7cd33

… before starting to migratin (Squash)

Squash

e92e2d9

Added some content to migrating-from assembly (Squash)

f6d19ad

Adding words (Squash)

d78cd7b

Save changes (Squash)

1c7362c

Other 3 Next steps missing (Squash)

7e69800

Squash it squash it squash it

e5226b1

Cluster-wide not mulitenant (Squash)

5ec33a9

Notes (Squash)

15f6a46

Comments and links to mutlitenat PR that will be used to split out mu…

79dde70

…ltitenant content (Squash)

gwynnemonahan force-pushed the OSSM-8673 branch from aeb6a37 to 79dde70 Compare January 22, 2025 16:18

gwynnemonahan added 3 commits January 22, 2025 10:25

Need new dir for when migration is done/complete (Squash)

c1b5111

Next steps, some kind of transition content is needed once migration …

20acf75

…is completed (Squash)

Moving Next into own dir (Squash)

5346c17

openshift-ci bot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Jan 22, 2025

gwynnemonahan added 3 commits January 22, 2025 10:56

Forgot to add the updated topic_map

2e3478d

Missing Topics: (Squash)

c19ae01

Remove duplicate files that got moved or dopied or added for some rea…

90c4a8a

…son (Squash)

openshift-ci bot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Jan 22, 2025

Creating migrating-gateways directory as there is now specific Gatewa…

94453b5

…y migration content for 3.0, not just the 2.x content

openshift-ci bot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Jan 23, 2025

gwynnemonahan added 2 commits January 23, 2025 14:46

Updates to checklist (Squash)

373a359

Fix nesting in checklist (Squash)

3dc310d

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

3.0 GA OSSM-8673 Pre-migration checklist for product docs #86912

3.0 GA OSSM-8673 Pre-migration checklist for product docs #86912

gwynnemonahan commented Jan 10, 2025 •

edited

Loading

ocpdocs-previewbot commented Jan 10, 2025 •

edited

Loading

longmuir Jan 13, 2025

longmuir Jan 13, 2025

longmuir Jan 13, 2025

nrfox Jan 22, 2025

nrfox Jan 22, 2025

nrfox Jan 22, 2025

nrfox Jan 22, 2025

nrfox Jan 22, 2025

nrfox Jan 22, 2025

openshift-ci bot commented Jan 23, 2025

3.0 GA OSSM-8673 Pre-migration checklist for product docs #86912

Are you sure you want to change the base?

3.0 GA OSSM-8673 Pre-migration checklist for product docs #86912

Conversation

gwynnemonahan commented Jan 10, 2025 • edited Loading

ocpdocs-previewbot commented Jan 10, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

openshift-ci bot commented Jan 23, 2025

gwynnemonahan commented Jan 10, 2025 •

edited

Loading

ocpdocs-previewbot commented Jan 10, 2025 •

edited

Loading