Service Mesh JTBD work for Configure, Observe, Secure, and other categories

.gitignore

@@ -16,5 +16,13 @@ bin
 commercial_package
 .vscode
 .vale/styles/AsciiDoc
+.vale/styles/AsciiDocDITA
 .vale/styles/OpenShiftAsciiDoc
 .vale/styles/RedHat
+migrating/JIRA-9894-dns-capture-documentation-plan.md
+migrating/modules/ossm-migrating-a-multitenant-deployment.html
+analysis/
+artifacts/
+update/ossm-preparing-for-rhel-10-migration.adoc
+modules/ossm-migrate-to-nftables-rhel10-ambient.adoc
+modules/ossm-migrate-to-nftables-rhel10-sidecar.adoc

.vale.ini

@@ -2,11 +2,11 @@ StylesPath = .vale/styles
 
 MinAlertLevel = suggestion
 
-Packages = RedHat, AsciiDoc, OpenShiftAsciiDoc
+Packages = RedHat, AsciiDoc, OpenShiftAsciiDoc, https://github.com/jhradilek/asciidoctor-dita-vale/releases/latest/download/AsciiDocDITA.zip
 
 # Ignore files in dirs starting with `.` to avoid raising errors for `.vale/fixtures/*/testinvalid.adoc` files
 [[!.]*.adoc]
-BasedOnStyles = RedHat, AsciiDoc, OpenShiftAsciiDoc
+BasedOnStyles = RedHat, AsciiDoc, OpenShiftAsciiDoc, AsciiDocDITA
 
 # Disabling rules (NO)
 RedHat.ReleaseNotes = NO

.vale/styles/Vocab/OpenShiftDocs/accept.txt

@@ -18,3 +18,5 @@ Operators
 NICs?
 Mellanox
 VFs?
+[Ww]aypoint
+[Zz]tunnel

_attributes/common-attributes.adoc

@@ -17,7 +17,7 @@
 :SMProductName: Red{nbsp}Hat OpenShift Service Mesh
 :SMProduct: OpenShift Service Mesh
 :SMProductShortName: Service Mesh
-:SMProductVersion: 3.2.0
+:SMProductVersion: 3.4.0
 //service mesh v2
 //Update when there is a new 2.6.z release
 :SMv2Version: 2.6.10

_topic_maps/_topic_map.yml

@@ -10,53 +10,55 @@ Topics:
 - Name: Service Mesh 3.x feature support tables
   File: ossm-release-notes-feature-support-tables
 ---
-Name: Migrating from Service Mesh 2 to Service Mesh 3
-Dir: migrating
-Distros: openshift-service-mesh
-Topics:
-- Name: Migrating from Service Mesh 2 to Service Mesh 3
-  File: ossm-migrating-from-service-mesh-2-to-3
-- Name: Before migrating
-  Dir: checklists
-  Topics:
-  - Name: Important information to know before migrating
-    File: ossm-migrating-read-me
-  - Name: Premigration checklists
-    File: ossm-migrating-premigration-checklists
-  - Name: Migrating network policies
-    File: ossm-migrating-network-policies
-  - Name: Kiali differences for Service Mesh 3
-    File: ossm-migrating-kiali-differences
-- Name: Multitenant migration guide
-  Dir: multitenant
-  Topics:
-  - Name: Multitenant migration guide
-    File: ossm-migrating-multitenant
-- Name: Cluster-wide migration guide
-  Dir: cluster-wide
-  Topics:
-  - Name: Cluster-wide migration guide
-    File: ossm-migrating-cluster-wide
-- Name: Migrating gateways
-  Dir: migrating-gateways
-  Topics:
-  - Name: Migrating gateways
-    File: ossm-migrating-gateways
-- Name: Completing the migration
-  Dir: done
-  Topics:
-  - Name: Completing the Migration
-    File: ossm-migrating-complete
-- Name: Reference
-  Dir: reference
-  Topics:
-  - Name: Migrating references
-    File: ossm-migrating-references
----
+# Name: Migrating from Service Mesh 2 to Service Mesh 3
+# Dir: migrating
+# Distros: openshift-service-mesh
+# Topics:
+# - Name: Migrating from Service Mesh 2 to Service Mesh 3
+#   File: ossm-migrating-from-service-mesh-2-to-3
+# - Name: Before migrating
+#  Dir: checklists
+#  Topics:
+#  - Name: Important information to know before migrating
+#     File: ossm-migrating-read-me
+#   - Name: Premigration checklists
+#     File: ossm-migrating-premigration-checklists
+#   - Name: Migrating network policies
+#     File: ossm-migrating-network-policies
+#   - Name: Kiali differences for Service Mesh 3
+#     File: ossm-migrating-kiali-differences
+# - Name: Multitenant migration guide
+#   Dir: multitenant
+#   Topics:
+#   - Name: Multitenant migration guide
+#     File: ossm-migrating-multitenant
+# - Name: Cluster-wide migration guide
+#   Dir: cluster-wide
+#   Topics:
+#   - Name: Cluster-wide migration guide
+#     File: ossm-migrating-cluster-wide
+# - Name: Migrating gateways
+#   Dir: migrating-gateways
+#   Topics:
+#   - Name: Migrating gateways
+#     File: ossm-migrating-gateways
+# - Name: Completing the migration
+#   Dir: done
+#   Topics:
+#   - Name: Completing the Migration
+#     File: ossm-migrating-complete
+# - Name: Reference
+#   Dir: reference
+#   Topics:
+#   - Name: Migrating references
+#     File: ossm-migrating-references
+# ---
 Name: About
 Dir: about
 Distros: openshift-service-mesh
 Topics:
+- Name: Planning your service mesh deployment
+  File: ossm-planning
 - Name: About OpenShift Service Mesh
   File: ossm-about-openshift-service-mesh
 - Name: Understanding Service Mesh
@@ -74,8 +76,12 @@ Topics:
   File: ossm-sidecar-injection
 - Name: Istio ambient mode
   File: ossm-istio-ambient-mode
+- Name: Coexistence of ambient and sidecar modes
+  File: ossm-ambient-sidecar-coexistence
 - Name: Red Hat OpenShift Service Mesh and cert-manager
   File: ossm-cert-manager
+- Name: SPIRE integration for mesh security
+  File: ossm-SPIRE
 - Name: Multi-Cluster topologies
   File: ossm-multi-cluster-topologies
 - Name: Deploying multiple service meshes on a single cluster

modules/ossm-api-settings-mesh-ha-replicacount.adoc → _unused_topics/unused_modules/ossm-api-settings-mesh-ha-replicacount.adoc

@@ -1,4 +1,5 @@
 // This module is used in the following assemblies:
+//
 // * service-mesh-docs-main/install/ossm-installing-service-mesh.adoc
 
 :_mod-docs-content-type: REFERENCE

modules/ossm-cert-manager-installing-istio-resource.adoc → _unused_topics/unused_modules/ossm-cert-manager-installing-istio-resource.adoc

@@ -8,11 +8,6 @@
 
 [role="_abstract"]
 
-//TP1 content influx. Title, etc may change.
-//Content is very similar to 2.x content
-//all kinds of formatting things to fix. want to see if a build will generate to have a look, and see how it fits structurally with the IA.
-
-
 After you have installed `istio-csr` by following the procedure for either an in place or revision based update strategy, you can install the `Istio` resource.
 
 You need to disable Istio's built in CA server and tell istiod to use the `istio-csr` CA server. The `istio-csr` CA server issues certificates for both istiod and user workloads.

modules/ossm-cert-manager-verifying-install.adoc → _unused_topics/unused_modules/ossm-cert-manager-verifying-install.adoc

@@ -8,10 +8,6 @@
 
 [role="_abstract"]
 
-//TP1 content influx. Title, etc may change.
-//Content is very similar to 2.x content
-//all kinds of formatting things to fix. want to see if a build will generate to have a look, and see how it fits structurally with the IA.
-
 You can use the sample `httpbin` service and `sleep` application to check communication between the workloads. You can also check the workload certificate of the proxy to verify that the cert-manager tool is installed correctly.
 
 .Procedure

modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label-with-cert-manager.adoc → _unused_topics/unused_modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label-with-cert-manager.adoc

@@ -12,7 +12,7 @@ You can perform a canary upgrade with the gradual migration of data plane namesp
 
 You must relabel 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".
+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
 
@@ -31,7 +31,8 @@ The `bookinfo` application is used as an example for the `Istio` resource. For m
 
 . Check that your {SMProduct} 2 `ServiceMeshControlPlane` resource is configured with the cert-manager-tool:
 +
-.Example `ServiceMeshControlPlane` cert-manager configuration
+You can see the following example configuration for reference:
++
 [source,yaml]
 ----
 apiVersion: maistra.io/v2
@@ -62,10 +63,12 @@ spec:
       --reuse-values \
       --namespace istio-system \
       --wait \
-      --set "app.istio.revisions={basic,ossm-3-v1-24-3}" <1>
+      --set "app.istio.revisions={basic,ossm-3-v1-24-3}"
 ----
 +
-<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.
+where:
+
+`app.istio.revisions`:: This field should 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:
 +
@@ -74,7 +77,8 @@ spec:
 $ oc get smcp -A
 ----
 +
-.Example output:
+You get an output similar to the following example:
++
 [source,terminal]
 ----
 NAMESPACE      NAME                   READY   STATUS            PROFILES      VERSION   AGE
@@ -88,21 +92,22 @@ istio-system   install-istio-system   6/6     ComponentsReady   ["default"]   2.
 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
+You can see the following example configuration for reference:
++
 [source,yaml,subs="attributes,verbatim"]
 ----
 apiVersion: sailoperator.io/v1
 kind: Istio
 metadata:
-  name: ossm-3 # <1>
+  name: ossm-3
 spec:
   updateStrategy:
     type: RevisionBased
-  namespace: istio-system # <2>
+  namespace: istio-system
   version: v1.24.3
   values:  
     meshConfig:
-      extensionProviders: # <3>
+      extensionProviders:
         - name: prometheus
           prometheus: {}
         - name: otel
@@ -115,9 +120,9 @@ spec:
       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.
+* `metadata.name` specifies the name of the `IstioRevision` resource. The `updateStrategy` and `version` fields specify how the resource is updated. For more information, see "Identifying the revision name".
+* `spec.namespace` specifies the namespace where the 3.0 and 2.6 control planes must run.
+* `spec.values` specifies the configuration values for the 3.0 control plane. If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations.
 +
 [NOTE]
 ====
@@ -138,7 +143,8 @@ $ oc apply -f ossm-3.yaml
 $ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret'
 ----
 +
-.Example output:
+You get an output similar to the following example:
++
 [source,terminal]
 ----
 2024-12-18T08:13:53.788959Z	info	pkica	Load signing key and cert from existing secret istio-system/istio-ca-secret

modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc → _unused_topics/unused_modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc

@@ -10,14 +10,14 @@
 
 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."
+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 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.
@@ -30,7 +30,8 @@ You can follow these same steps with your own workloads.
 
 . Check that your {SMProduct} 2 `ServiceMeshControlPlane` resource is configured with the cert-manager tool.
 +
-.Example `ServiceMeshControlPlane` cert-manager configuration
+You can see the following example configuration for reference:
++
 [source,yaml]
 ----
 apiVersion: maistra.io/v2
@@ -61,10 +62,12 @@ spec:
       --reuse-values \
       --namespace istio-system \
       --wait \
-      --set "app.istio.revisions={basic,ossm-3-v1-24-3}" <1>
+      --set "app.istio.revisions={basic,ossm-3-v1-24-3}"
 ----
 +
-<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.
+where:
++
+`app.istio.revisions`:: This 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:
 +
@@ -73,30 +76,32 @@ spec:
 $ oc get smcp -A
 ----
 +
-.Example output:
+You get an output similar to the following example:
++
 [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:
+. 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:
++
+You can see the following example configuration for reference:
 +
-.Example `Istio` resource
 [source,yaml,subs="attributes,verbatim"]
 ----
 apiVersion: sailoperator.io/v1
 kind: Istio
 metadata:
-  name: ossm-3 # <1>
+  name: ossm-3
 spec:
   updateStrategy:
     type: RevisionBased
-  namespace: istio-system # <2>
+  namespace: istio-system
   version: v1.24.3
   values:  
     meshConfig:
-      extensionProviders: # <3>
+      extensionProviders:
         - name: prometheus
           prometheus: {}
         - name: otel
@@ -109,9 +114,9 @@ spec:
       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.
+* `metadata.name` specifies the name of the `IstioRevision` resource. The `updateStrategy` and `version` fields specify how the resource is updated. For more information, see "Identifying the revision name."
+* `spec.namespace` specifies the namespace where the 3.0 and 2.6 control planes must run.
+* `spec.values` specifies the configuration values for the 3.0 control plane. 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:
 +
@@ -127,7 +132,8 @@ $ oc apply -f ossm-3.yaml
 $ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret'
 ----
 +
-.Example output:
+You get an output similar to the following example:
++
 [source,terminal]
 ----
 2024-12-18T08:13:53.788959Z	info	pkica	Load signing key and cert from existing secret istio-system/istio-ca-secret