Manual cherry pick #27812 to 4.5 branch.

_topic_map.yml

@@ -2193,6 +2193,8 @@ Topics:
     File: ossm-traffic-manage
   - Name: Using the 3scale Istio adapter
     File: threescale-adapter
+  - Name: Removing Service Mesh
+    File: removing-ossm
 ---
 Name: Jaeger
 Dir: jaeger

modules/ossm-security-cert-manage-1x.adoc

@@ -0,0 +1,169 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v1x/ossm-security.adoc
+
+
+[id="ossm-cert-manage_{context}"]
+= Adding an external certificate authority key and certificate
+
+By default, {ProductName} generates self-signed root certificate and key, and uses them to sign the workload certificates. You can also use the user-defined certificate and key to sign workload certificates, with user-defined root certificate. This task demonstrates an example to plug certificates and key into {ProductShortName}.
+
+.Prerequisites
+
+* You must have installed {ProductName} with mutual TLS enabled to configure certificates.
+* This example uses the certificates from the link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repository]. For production, use your own certificates from your certificate authority.
+* You must deploy the Bookinfo sample application to verify the results with these instructions.
+
+[id="ossm-cert-manage-add-cert-key_{context}"]
+== Adding an existing certificate and key
+
+To use an existing signing (CA) certificate and key, you must create a chain of trust file that includes the CA certificate, key, and root certificate. You must use the following exact file names for each of the corresponding certificates. The CA certificate is called `ca-cert.pem`, the key is `ca-key.pem`, and the root certificate, which signs `ca-cert.pem`, is called `root-cert.pem`. If your workload uses intermediate certificates, you must specify them in a `cert-chain.pem` file.
+
+Add the certificates to {ProductShortName} by following these steps. Save the example certificates from the link:https://github.com/maistra/istio/tree/maistra-1.1/samples/certs[Maistra repo] locally and replace `<path>` with the path to your certificates.
+
+. Create a secret `cacert` that includes the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`.
++
+[source,terminal]
+----
+$ oc create secret generic cacerts -n istio-system --from-file=<path>/ca-cert.pem \
+    --from-file=<path>/ca-key.pem --from-file=<path>/root-cert.pem \
+    --from-file=<path>/cert-chain.pem
+----
++
+. In the `ServiceMeshControlPlane` resource set `global.mtls.enabled` to `true` and `security.selfSigned` set to `false`. {ProductShortName} reads the certificates and key from the secret-mount files.
++
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshControlPlane
+spec:
+  istio:
+    global:
+      mtls:
+        enabled: true
+    security:
+      selfSigned: false
+----
++
+. To make sure the workloads add the new certificates promptly, delete the secrets generated by {ProductShortName}, named `istio.*`. In this example, `istio.default`. {ProductShortName} issues new certificates for the workloads.
++
+[source,terminal]
+----
+$ oc delete secret istio.default
+----
+
+[id="ossm-cert-manage-verify-cert_{context}"]
+== Verifying your certificates
+
+Use the Bookinfo sample application to verify your certificates are mounted correctly. First, retrieve the mounted certificates. Then, verify the certificates mounted on the pod.
+
+. Store the pod name in the variable `RATINGSPOD`.
++
+[source,terminal]
+----
+$ RATINGSPOD=`oc get pods -l app=ratings -o jsonpath='{.items[0].metadata.name}'`
+----
++
+. Run the following commands to retrieve the certificates mounted on the proxy.
++
+[source,terminal]
+----
+$ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/root-cert.pem > /tmp/pod-root-cert.pem
+----
++
+The file `/tmp/pod-root-cert.pem` contains the root certificate propagated to the pod.
++
+[source,terminal]
+----
+$ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/cert-chain.pem > /tmp/pod-cert-chain.pem
+----
++
+The file `/tmp/pod-cert-chain.pem` contains the workload certificate and the CA certificate propagated to the pod.
++
+. Verify the root certificate is the same as the one specified by the Operator. Replace `<path>` with the path to your certificates.
++
+[source,terminal]
+----
+$ openssl x509 -in <path>/root-cert.pem -text -noout > /tmp/root-cert.crt.txt
+----
++
+[source,terminal]
+----
+$ openssl x509 -in /tmp/pod-root-cert.pem -text -noout > /tmp/pod-root-cert.crt.txt
+----
++
+[source,terminal]
+----
+$ diff /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt
+----
++
+Expect the output to be empty.
++
+. Verify the CA certificate is the same as the one specified by Operator. Replace `<path>` with the path to your certificates.
++
+[source,terminal]
+----
+$ sed '0,/^-----END CERTIFICATE-----/d' /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-ca.pem
+----
++
+[source,terminal]
+----
+$ openssl x509 -in <path>/ca-cert.pem -text -noout > /tmp/ca-cert.crt.txt
+----
++
+[source,terminal]
+----
+$ openssl x509 -in /tmp/pod-cert-chain-ca.pem -text -noout > /tmp/pod-cert-chain-ca.crt.txt
+----
++
+[source,terminal]
+----
+$ diff /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt
+----
++
+Expect the output to be empty.
++
+. Verify the certificate chain from the root certificate to the workload certificate. Replace `<path>` with the path to your certificates.
++
+[source,terminal]
+----
+$ head -n 21 /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-workload.pem
+----
++
+[source,terminal]
+----
+$ openssl verify -CAfile <(cat <path>/ca-cert.pem <path>/root-cert.pem) /tmp/pod-cert-chain-workload.pem
+----
++
+.Example output
+[source,terminal]
+----
+/tmp/pod-cert-chain-workload.pem: OK
+----
+
+[id="ossm-cert-cleanup_{context}"]
+== Removing the certificates
+
+To remove the certificates you added, follow these steps.
+
+. Remove the secret `cacerts`.
++
+[source,terminal]
+----
+$ oc delete secret cacerts -n istio-system
+----
++
+. Redeploy {ProductShortName} with a self-signed root certificate in the `ServiceMeshControlPlane` resource.
++
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshControlPlane
+spec:
+  istio:
+    global:
+      mtls:
+        enabled: true
+    security:
+      selfSigned: true
+----

modules/ossm-security-cert-manage.adoc

@@ -1,27 +1,26 @@
 // Module included in the following assemblies:
 //
-// * service_mesh/v1x/ossm-security.adoc
 // * service_mesh/v2x/ossm-security.adoc
 
 [id="ossm-cert-manage_{context}"]
 = Adding an external certificate authority key and certificate
 
-By default, {ProductName} generates self-signed root certificate and key, and uses them to sign the workload certificates. You can also use the Operator-specified certificate and key to sign workload certificates, with Operator-specified root certificate. This task demonstrates an example to plug certificates and key into {ProductShortName}.
+By default, {ProductName} generates self-signed root certificate and key, and uses them to sign the workload certificates. You can also use the user-defined certificate and key to sign workload certificates, with user-defined root certificate. This task demonstrates an example to plug certificates and key into {ProductShortName}.
 
 .Prerequisites
 
 * You must have installed {ProductName} with mutual TLS enabled to configure certificates.
-* This example uses the certificates from link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repo]. For production, use your own certificates from your certificate authority.
+* This example uses the certificates from the link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repository]. For production, use your own certificates from your certificate authority.
 * You must deploy the Bookinfo sample application to verify the results with these instructions.
 
 [id="ossm-cert-manage-add-cert-key_{context}"]
 == Adding an existing certificate and key
 
 To use an existing signing (CA) certificate and key, you must create a chain of trust file that includes the CA certificate, key, and root certificate. You must use the following exact file names for each of the corresponding certificates. The CA certificate is called `ca-cert.pem`, the key is `ca-key.pem`, and the root certificate, which signs `ca-cert.pem`, is called `root-cert.pem`. If your workload uses intermediate certificates, you must specify them in a `cert-chain.pem` file.
 
-Add the certificates to {ProductShortName} by following these steps. Save the certificates from the link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repo] locally and replace `<path>` with the path to your certificates.
+Add the certificates to {ProductShortName} by following these steps. Save the example certificates from the link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repo] locally and replace `<path>` with the path to your certificates.
 
-1. Create a secret `cacert` that includes the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`.
+. Create a secret `cacert` that includes the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`.
 +
 [source,terminal]
 ----
@@ -30,22 +29,25 @@ $ oc create secret generic cacerts -n istio-system --from-file=<path>/ca-cert.pe
     --from-file=<path>/cert-chain.pem
 ----
 +
-2. In the `ServiceMeshControlPlane` resource set `global.mtls.enabled` to `true` and `security.selfSigned` set to `false`. {ProductShortName} reads the certificates and key from the secret-mount files.
+. In the `ServiceMeshControlPlane` resource set `spec.security.dataPlane.mtls: true` to `true` and configure your certificateAuthority like the following example. The default `rootCADir` is `/etc/cacerts`. You do not need to set the `privateKey` if the key and certs are mounted in the default location.  {ProductShortName} reads the certificates and key from the secret-mount files.
 +
 [source,yaml]
 ----
-apiVersion: maistra.io/v1
+apiVersion: maistra.io/v2
 kind: ServiceMeshControlPlane
 spec:
-  istio:
-    global:
-      mtls:
-        enabled: true
-    security:
-      selfSigned: false
+  security:
+    dataPlane:
+      mtls: true
+    certificateAuthority:
+      type: Istiod
+      istiod:
+        type: PrivateKey
+        privateKey:
+          rootCADir:  /etc/cacerts
 ----
 +
-3. To make sure the workloads add the new certificates promptly, delete the secrets generated by {ProductShortName}, named `istio.*`. In this example, `istio.default`. {ProductShortName} issues new certificates for the workloads.
+. To make sure the workloads add the new certificates promptly, delete the secrets generated by {ProductShortName}, named `istio.*`. In this example, `istio.default`. {ProductShortName} issues new certificates for the workloads.
 +
 [source,terminal]
 ----
@@ -57,14 +59,14 @@ $ oc delete secret istio.default
 
 Use the Bookinfo sample application to verify your certificates are mounted correctly. First, retrieve the mounted certificates. Then, verify the certificates mounted on the pod.
 
-1. Store the pod name in the variable `RATINGSPOD`.
+. Store the pod name in the variable `RATINGSPOD`.
 +
 [source,terminal]
 ----
 $ RATINGSPOD=`oc get pods -l app=ratings -o jsonpath='{.items[0].metadata.name}'`
 ----
 +
-Run the following commands to retrieve the certificates mounted on the proxy.
+. Run the following commands to retrieve the certificates mounted on the proxy.
 +
 [source,terminal]
 ----
@@ -80,7 +82,7 @@ $ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/cert-chain.pem >
 +
 The file `/tmp/pod-cert-chain.pem` contains the workload certificate and the CA certificate propagated to the pod.
 +
-3. Verify the root certificate is the same as the one specified by the Operator. Replace `<path>` with the path to your certificates.
+. Verify the root certificate is the same as the one specified by the Operator. Replace `<path>` with the path to your certificates.
 +
 [source,terminal]
 ----
@@ -99,7 +101,7 @@ $ diff /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt
 +
 Expect the output to be empty.
 +
-4. Verify the CA certificate is the same as the one specified by Operator. Replace `<path>` with the path to your certificates.
+. Verify the CA certificate is the same as the one specified by Operator. Replace `<path>` with the path to your certificates.
 +
 [source,terminal]
 ----
@@ -123,7 +125,7 @@ $ diff /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt
 +
 Expect the output to be empty.
 +
-5. Verify the certificate chain from the root certificate to the workload certificate. Replace `<path>` with the path to your certificates.
+. Verify the certificate chain from the root certificate to the workload certificate. Replace `<path>` with the path to your certificates.
 +
 [source,terminal]
 ----
@@ -146,24 +148,20 @@ $ openssl verify -CAfile <(cat <path>/ca-cert.pem <path>/root-cert.pem) /tmp/pod
 
 To remove the certificates you added, follow these steps.
 
-1. Remove the secret `cacerts`.
+. Remove the secret `cacerts`.
 +
 [source,terminal]
 ----
 $ oc delete secret cacerts -n istio-system
 ----
 +
-2. Redeploy {ProductShortName} with a self-signed root certificate in the `ServiceMeshControlPlane` resource.
+. Redeploy {ProductShortName} with a self-signed root certificate in the `ServiceMeshControlPlane` resource.
 +
 [source,yaml]
 ----
-apiVersion: maistra.io/v1
+apiVersion: maistra.io/v2
 kind: ServiceMeshControlPlane
 spec:
-  istio:
-    global:
-      mtls:
-        enabled: true
-    security:
-      selfSigned: true
+  dataPlane:
+    mtls: true
 ----

service_mesh/v1x/installing-ossm.adoc

@@ -37,13 +37,10 @@ include::modules/ossm-install-kiali.adoc[leveloffset=+1]
 
 include::modules/ossm-install-ossm-operator.adoc[leveloffset=+1]
 
-
-
 include::modules/ossm-control-plane-deploy-1x.adoc[leveloffset=+1]
 
 For a multitenant installation, {ProductName} supports multiple independent control planes within the cluster.  You can create reusable configurations with `ServiceMeshControlPlane` templates.  For more information, see xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#ossm-control-plane-templates_deploying-applications-ossm-v1x[Creating control plane templates].
 
-
 include::modules/ossm-member-roll-create.adoc[leveloffset=+1]
 
 include::modules/ossm-member-roll-modify.adoc[leveloffset=+1]
@@ -55,19 +52,8 @@ OLM uses CatalogSources, which use the Operator Registry API, to query for avail
 
 * For more information about how {product-title} handled upgrades, refer to the xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-overview_olm-understanding-olm[Operator Lifecycle Manager] documentation.
 
-
 include::modules/ossm-update-app-sidecar.adoc[leveloffset=+2]
 
-= Removing {ProductName}
-
-This process allows you to remove {ProductName} from an existing {product-title} instance. Remove the control plane before removing the operators.
-
-include::modules/ossm-member-roll-delete.adoc[leveloffset=+2]
-
-include::modules/ossm-control-plane-remove.adoc[leveloffset=+1]
-
-include::modules/ossm-operatorhub-remove.adoc[leveloffset=+1]
-
 == Next steps
 
 * xref:../../service_mesh/v1x/customizing-installation-ossm.adoc#customize-installation-ossm-v1x[Customize the {ProductName} installation].

service_mesh/v1x/ossm-architecture.adoc

@@ -10,17 +10,17 @@ include::modules/ossm-understanding-service-mesh.adoc[leveloffset=+1]
 
 include::modules/ossm-architecture-1x.adoc[leveloffset=+1]
 
-= Understanding Kiali
+== Understanding Kiali
 
 Kiali provides visibility into your service mesh by showing you the microservices in your service mesh, and how they are connected.
 
-include::modules/ossm-kiali-overview.adoc[leveloffset=+1]
+include::modules/ossm-kiali-overview.adoc[leveloffset=+2]
 
-include::modules/ossm-kiali-architecture.adoc[leveloffset=+1]
+include::modules/ossm-kiali-architecture.adoc[leveloffset=+2]
 
-include::modules/ossm-kiali-features.adoc[leveloffset=+1]
+include::modules/ossm-kiali-features.adoc[leveloffset=+2]
 
-= Understanding Jaeger
+== Understanding Jaeger
 
 Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate in order to produce a response.
 The path of this request is a distributed transaction.
@@ -34,11 +34,11 @@ Jaeger records the execution of individual requests across the whole stack of mi
 
 A *span* represents a logical unit of work in Jaeger that has an operation name, the start time of the operation, and the duration. Spans may be nested and ordered to model causal relationships.
 
-include::modules/jaeger-product-overview.adoc[leveloffset=+1]
+include::modules/jaeger-product-overview.adoc[leveloffset=+2]
 
-include::modules/jaeger-architecture.adoc[leveloffset=+1]
+include::modules/jaeger-architecture.adoc[leveloffset=+2]
 
-include::modules/jaeger-features.adoc[leveloffset=+1]
+include::modules/jaeger-features.adoc[leveloffset=+2]
 
 
 == Next steps

service_mesh/v1x/ossm-security.adoc

@@ -11,4 +11,4 @@ include::modules/ossm-security-mtls.adoc[leveloffset=+1]
 
 include::modules/ossm-security-cipher.adoc[leveloffset=+1]
 
-include::modules/ossm-security-cert-manage.adoc[leveloffset=+1]
+include::modules/ossm-security-cert-manage-1x.adoc[leveloffset=+1]