[service-mesh-docs-3.0.0tp1] OSSM 3.0 TP1: OSSM-6060 OSSM3 with cert-manager and istio-csr

_topic_maps/_topic_map.yml

@@ -23,6 +23,8 @@ Topics:
   File: ossm-installing-openshift-service-mesh
 - Name: Running Service Mesh 2.6 in the same cluster as Service Mesh 3
   File: ossm-running-v2-same-cluster-as-v3-assembly
+- Name: Red Hat OpenShift Service Mesh and cert-manager
+  File: ossm-cert-manager-assembly
 ---
 Name: Updating
 Dir: update

install/ossm-cert-manager-assembly.adoc

@@ -0,0 +1,48 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ossm-cert-manager-assembly"]
+= OpenShift Service Mesh and cert-manager
+include::_attributes/common-attributes.adoc[]
+:context: ossm-cert-manager-assembly
+
+//Working IA. The IA for 3.x is influx. Putting in "Installing" for now as most of the content relates to installing cert-manager, istio-csr, and then creating and installing the Istio resource.
+//TP1 content. Likely structure, titles, content, etc will change for GA
+//User must install cert-manager before they create and install an Istio resource. However, the spec.updateStrategy they decide on for the Istio resource dictates specific steps istio-csr and cert-manager, esp in regards to how istio-csr and cert-manager are updated.
+
+toc::[]
+
+The cert-manager tool is a solution for X.509 certificate management on Kubernetes. It delivers a unified API to integrate applications with private or public key infrastructure (PKI), such as Vault, Google Cloud Certificate Authority Service, Let's Encrypt, and other providers.
+
+[IMPORTANT]
+====
+The cert-manager tool must be installed before you create and install your `Istio` resource.
+====
+
+The cert-manager tool ensures the certificates are valid and up-to-date by attempting to renew certificates at a configured time before they expire.
+
+include::modules/ossm-about-cert-manager.adoc[leveloffset=+1]
+include::modules/ossm-installing-cert-manager.adoc[leveloffset=+1]
+
+.Next steps
+To install `istio-csr`, you must follow the `istio-csr` installation instructions for the type of update strategy you want. By default, `spec.updateStrategy` is set to `InPlace` when you create and install your `Istio` resource. You create and install your `Istio` resource after you install `istio-csr`.
+
+* xref:../install/ossm-cert-manager-assembly.adoc#inplace-istio-csr-installation_ossm-cert-manager-assembly[Installing the istio-csr agent by using the in place update strategy]
+* xref:../install/ossm-cert-manager-assembly.adoc#revision-based-istio-csr-installation_ossm-cert-manager-assembly[Installing the istio-csr agent by using the revision based update strategy]
+
+include::modules/ossm-cert-manager-istio-csr-inplace-update-strategy.adoc[leveloffset=+2]
+
+.Next steps
+* xref:../install/ossm-cert-manager-assembly.adoc#installing-istio-resource_ossm-cert-manager-assembly[Installing your Istio resource]
+
+include::modules/ossm-cert-manager-istio-csr-revisionbased-strategy.adoc[leveloffset=+2]
+
+[id="additional-resources_{context}"]
+.Additional resources
+* link:https://github.com/cert-manager/istio-csr/tree/main/deploy/charts/istio-csr#appistiorevisions0--string[istio-csr deployment]
+
+
+.Next steps
+* xref:../install/ossm-cert-manager-assembly.adoc#installing-istio-resource_ossm-cert-manager-assembly[Installing your Istio resource]
+
+include::modules/ossm-cert-manager-installing-istio-resource.adoc[leveloffset=+2]
+include::modules/ossm-cert-manager-verifying-install.adoc[leveloffset=+2]
+include::modules/ossm-cert-manager-update-istio-csr-revisionbased-only.adoc[leveloffset=+1]

modules/ossm-about-cert-manager.adoc

@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/install/ossm-cert-manager-assembly.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-cert-manager-integration-istio_{context}"]
+= About integrating Service Mesh with cert-manager and istio-csr
+//TP1 content influx. Title, etc may change.
+
+The cert-manager tool provides integration with Istio through an external agent called `istio-csr`. The `istio-csr` agent handles certificate signing requests (CSR) from Istio proxies and the `controlplane` in the following ways:
+
+. Verifying the identity of the workload.
+. Creating a CSR through cert-manager for the workload.
+
+The cert-manager tool then creates a CSR to the configured CA Issuer, which signs the certificate.
+
+[NOTE]
+====
+Red{nbsp}Hat provides support for integrating with `istio-csr` and cert-manager. Red{nbsp}Hat does not provide direct support for the `istio-csr` or the community cert-manager components. The use of community cert-manager shown here is for demonstration purposes only.
+====
+
+//For Istio users, cert-manager also provides integration with `istio-csr`, which is a certificate authority (CA) server that handles certificate signing requests (CSR) from Istio proxies. The server then delegates signing to cert-manager, which forwards CSRs to the configured CA server.
+
+.Prerequisites
+* One of these versions of cert-manager:
+** Red Hat cert-manager Operator 1.10 or later
+** community cert-manager Operator 1.11 or later
+** cert-manager 1.11 or later
+* {SMProductName} 3.0 or later
+* An `IstioCNI` instance is running in the cluster
+* Istio CLI (`istioctl`) tool is installed
+* `jq` is installed
+* Helm is installed
+
+//Note to add {cert-manager-operator} to stand alone common attributes file. That is outside the scope of this PR and there is an existing Jira to add common attributes for OSSM GA.

modules/ossm-cert-manager-installing-istio-resource.adoc

@@ -0,0 +1,72 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/install/ossm-cert-manager-assembly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="installing-istio-resource_{context}"]
+= Installing your Istio resource
+
+//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.
+
+.Procedure
+
+. Create the `Istio` object as shown in the following example:
++
+.Example `istio.yaml` object
+[source, yaml]
+----
+apiVersion: sailoperator.io/v1alpha1
+kind: Istio
+metadata:
+  name: default
+spec:
+  version: v1.23.0
+  namespace: istio-system
+  values:
+    global:
+      caAddress: cert-manager-istio-csr.cert-manager.svc:443
+    pilot:
+      env:
+        ENABLE_CA_SERVER: "false"
+      volumeMounts:
+        - mountPath: /tmp/var/run/secrets/istiod/tls
+          name: istio-csr-dns-cert
+          readOnly: true
+----
++
+[NOTE]
+====
+If you installed your CSR agent with a revision based update strategy, then you need to add the following to your `Istio` object YAML:
+
+[source, yaml]
+----
+kind: Istio
+metadata:
+  name: default
+spec:
+  updateStrategy:
+    type: RevisionBased
+----
+====
+
+. Create the `Istio` resource by running the following command:
++
+[source, terminal]
+----
+$ oc apply -f istio.yaml
+----
+
+. Wait for the `Istio` object to become ready by running the following command:
++
+[source, terminal]
+----
+$ oc wait --for=condition=Ready istios/default -n istio-system
+----
+

modules/ossm-cert-manager-istio-csr-inplace-update-strategy.adoc

@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/install/ossm-cert-manager-assembly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="inplace-istio-csr-installation_{context}"]
+= Installing the istio-csr agent by using the in place update strategy
+
+Istio resources use the in place update strategy by default. Follow this procedure if you plan to leave `spec.updateStrategy` as `InPlace` when you create and install your `Istio` resource.
+
+.Procedure
+
+. Add the Jetstack charts repository to your local Helm repository by running the following command:
++
+[source, terminal]
+----
+$ helm repo add jetstack https://charts.jetstack.io --force-update
+----
+
+. Install the `istio-csr` chart by running the following command:
++
+[source, terminal]
+----
+$ helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
+    --install \
+    --namespace cert-manager \
+    --wait \
+    --set "app.tls.rootCAFile=/var/run/secrets/istio-csr/ca.pem" \
+    --set "volumeMounts[0].name=root-ca" \
+    --set "volumeMounts[0].mountPath=/var/run/secrets/istio-csr" \
+    --set "volumes[0].name=root-ca" \
+    --set "volumes[0].secret.secretName=istio-root-ca" \
+    --set "app.istio.namespace=istio-system"
+----

modules/ossm-cert-manager-istio-csr-revisionbased-strategy.adoc

@@ -0,0 +1,42 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/install/ossm-cert-manager-assembly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="revision-based-istio-csr-installation_{context}"]
+= Installing the istio-csr agent by using the revision based update strategy
+
+Istio resources use the in place update strategy by default. Follow this procedure if you plan to change `spec.updateStrategy` to `RevisionBased` when you create and install your `Istio` resource.
+
+.Procedure
+
+. Specify all the Istio revisions to your `istio-csr` deployment. See "istio-csr deployment".
+
+. Add the Jetstack charts to your local Helm repository by running the following command:
++
+[source, terminal]
+----
+$ helm repo add jetstack https://charts.jetstack.io --force-update
+----
+
+. Install the `istio-csr` chart with your revision name by running the following command:
++
+[source, terminal]
+----
+$ helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
+    --install \
+    --namespace cert-manager \
+    --wait \
+    --set "app.tls.rootCAFile=/var/run/secrets/istio-csr/ca.pem" \
+    --set "volumeMounts[0].name=root-ca" \
+    --set "volumeMounts[0].mountPath=/var/run/secrets/istio-csr" \
+    --set "volumes[0].name=root-ca" \
+    --set "volumes[0].secret.secretName=istio-root-ca" \
+    --set "app.istio.namespace=istio-system" \
+    --set "app.istio.revisions={default-v1-23-0}"
+----
++
+[NOTE]
+====
+Revision names use the following format, `<istio-name>-v<major_version>-<minor_version>-<patch_version>`. For example: `default-v1-23-0`.
+====

modules/ossm-cert-manager-update-istio-csr-revisionbased-only.adoc

@@ -0,0 +1,59 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/install/ossm-cert-manager-assembly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="updating-istio-csr-revision-based-only_{context}"]
+= Updating istio-csr agents with revision-based update strategies
+
+If you deployed your Istio resource using the revision based update strategy, you must pass all revisions each time you update your control plane. You must perform the update in the following order:
+
+. Update the `istio-csr` deployment with the new revision.
+. Update the value of `Istio.spec.version` parameter/field.
+
+.Example update for RevisionBased control plane
+
+In this example, the `controlplane` is being updated from `v1.23.0` to `1.23.1.`
+
+. Update the `istio-csr` deployment with the new revision by running the following command:
++
+[source, terminal]
+----
+$ helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
+--wait \
+  --reuse-values \
+  --set "app.istio.revisions={<old_revision>,<new_revision>}"
+----
+where:
+`old_revision` :: Specifies the old revision in the `<istio-name>-v<major_version>-<minor_version>-<patch_version>` format. For example: `default-v1-23-0`.
+`new_revision` :: Specfies the new revision in the `<istio-name>-v<major_version>-<minor_version>-<patch_version>` format. For example: `default-v1-23-1`.
+
+. Update the `istio.spec.version` in the `Istio` object similar to the following example:
++
+.Example `istio.yaml` file
+[source, yaml]
+----
+apiVersion: sailoperator.io/v1alpha1
+kind: Istio
+metadata:
+  name: default
+spec:
+  version: <new_revision> # <1>
+----
+<1> Update to the new revision prefixed with the letter _v_, such as `v1.23.1`
+
+. Remove the old revision from your `istio-csr` deployment by running the following command:
++
+[source, terminal]
+----
+helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
+  --install \
+  --namespace cert-manager \
+  --wait \
+  --reuse-values \
+  --set "app.istio.revisions={default-v1-23-1}"
+----
+
+
+// Additional resources For information about how to install the cert-manager Operator for OpenShift Container Platform, see: [Installing the cert-manager Operator for Red Hat OpenShift](https://docs.openshift.com/container-platform/4.16/security/cert_manager_operator/cert-manager-operator-install.html).
+//temporary comment out so hopefully builds pass

modules/ossm-cert-manager-verifying-install.adoc

@@ -0,0 +1,90 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/install/ossm-cert-manager-assembly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="verifying-cert-manager-installation_{context}"]
+= Verifying cert-manager installation
+
+//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
+
+. Create the `sample` namespace by running the following command:
++
+[source, terminal]
+----
+$ oc new-project sample
+----
+
+. Find your active Istio revision by running the following command:
++
+[source, terminal]
+----
+$ oc get istiorevisions
+----
+
+. Add the injection label for your active revision to the `sample` namespace by running the following command:
++
+[source, terminal]
+----
+$ oc label namespace sample istio.io/rev=<your-active-revision-name> --overwrite=true
+----
+
+. Deploy the sample `httpbin` service by running the following command:
++
+[source, terminal]
+----
+$ oc apply -n sample -f https://raw.githubusercontent.com/openshift-service-mesh/istio/refs/heads/master/samples/httpbin/httpbin.yaml
+----
+
+. Deploy the sample `sleep` application by running the following command:
++
+[source, terminal]
+----
+$ oc apply -n sample -f https://raw.githubusercontent.com/istio/istio/refs/heads/master/samples/sleep/sleep.yaml
+----
+
+. Wait for both applications to become ready by running the following command:
++
+[source, terminal]
+----
+$ oc rollout status -n sample deployment httpbin sleep
+----
+
+. Verify that `sleep` application can access the `httpbin` service by running the following command:
++
+[source, terminal]
+----
+$ oc exec "$(oc get pod -l app=sleep -n sample \
+     -o jsonpath={.items..metadata.name})" -c sleep -n sample -- \
+     curl http://httpbin.sample:8000/ip -s -o /dev/null \
+     -w "%{http_code}\n"
+----
++
+.Example of a successful output
+[source, terminal]
+----
+200
+----
+
+. Run the following command to print the workload certificate for the `httpbin` service and verify the output:
++
+[source, terminal]
+----
+$ istioctl proxy-config secret -n sample $(oc get pods -n sample -o jsonpath='{.items..metadata.name}' --selector app=httpbin) -o json | jq -r '.dynamicActiveSecrets[0].secret.tlsCertificate.certificateChain.inlineBytes' | base64 --decode | openssl x509 -text -noout
+----
++
+.Example output
+[source, terminal]
+----
+...
+Issuer: O = cert-manager + O = cluster.local, CN = istio-ca
+...
+X509v3 Subject Alternative Name:
+  URI:spiffe://cluster.local/ns/sample/sa/httpbin
+----