openshift · JStickler · Nov 4, 2020 · Oct 12, 2020
diff --git a/_topic_map.yml b/_topic_map.yml
@@ -2166,6 +2166,8 @@ Topics:
 #     File: preparing-ossm-installation
 #   - Name: Installing Service Mesh
 #     File: installing-ossm
+#   - Name: Upgrading from 1.1 to 2.0
+#     File: upgrading-ossm
 #   - Name: Customizing the installation
 #     File: customizing-installation-ossm
 #   - Name: Deploying applications on Service Mesh

diff --git a/modules/ossm-cr-pilot.adoc b/modules/ossm-cr-pilot.adoc
@@ -5,18 +5,41 @@
 [id="ossm-cr-pilot_{context}"]
 = Istio Pilot configuration
 
-Here is an example that illustrates the Istio Pilot parameters for the `ServiceMeshControlPlane` and a description of the available parameters with appropriate values.
+You can configure Pilot to schedule or set limits on resource allocation. 
+The following example illustrates the Pilot parameters for the `ServiceMeshControlPlane` and a description of the available parameters with appropriate values.
 
 .Example pilot parameters
 [source,yaml]
 ----
-  pilot:
-    resources:
-      requests:
-        cpu: 100m
-        memory: 128Mi
-    autoscaleEnabled: false
-    traceSampling: 100
+spec:
+  runtime:
+    components:
+      pilot:
+        deployment:
+          autoScaling:
+            enabled: true
+            minReplicas: 1
+            maxReplicas: 5
+            targetCPUUtilizationPercentage: 85
+        pod:
+          tolerations:
+          - key: node.kubernetes.io/unreachable
+            operator: Exists
+            effect: NoExecute
+            tolerationSeconds: 60
+          affinity:
+            podAntiAffinity:
+              requiredDuringScheduling:
+              - key: istio
+                topologyKey: kubernetes.io/hostname
+                operator: In
+                values:
+                - pilot
+        container:
+          resources:
+            limits:
+              cpu: 100m
+              memory: 128M
 ----
 
 .Istio Pilot parameters

diff --git a/modules/ossm-security-cert-manage-1x.adoc b/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.
+
+1. 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
+----
++
+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.
++
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshControlPlane
+spec:
+  istio:
+    global:
+      mtls:
+        enabled: true
+    security:
+      selfSigned: false
+----
++
+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.
++
+[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.
+
+1. 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.
++
+3. 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.
++
+4. 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.
++
+5. 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.
+
+1. 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.
++
+[source,yaml]
+----
+apiVersion: maistra.io/v1
+kind: ServiceMeshControlPlane
+spec:
+  istio:
+    global:
+      mtls:
+        enabled: true
+    security:
+      selfSigned: true
+----
diff --git a/modules/ossm-security-cert-manage.adoc b/modules/ossm-security-cert-manage.adoc
@@ -1,25 +1,24 @@
 // 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`.
 +
@@ -30,19 +29,22 @@ $ 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.
+2. 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.
@@ -157,13 +159,9 @@ $ oc delete secret cacerts -n istio-system
 +
 [source,yaml]
 ----
-apiVersion: maistra.io/v1
+apiVersion: maistra.io/v2
 kind: ServiceMeshControlPlane
 spec:
-  istio:
-    global:
-      mtls:
-        enabled: true
-    security:
-      selfSigned: true
+  dataPlane:
+    mtls: true
 ----