openshift · bburt-rh · Jun 16, 2023 · Apr 7, 2023
diff --git a/modules/ossm-cert-manage-verify-cert.adoc b/modules/ossm-cert-manage-verify-cert.adoc
@@ -4,9 +4,9 @@
 
 :_content-type: PROCEDURE
 [id="ossm-cert-manage-verify-cert_{context}"]
-== Verifying your certificates
+= Verifying your certificates
 
-Use the Bookinfo sample application to verify that the workload certificates are signed by the certificates that were plugged into the CA. This requires you have `openssl` installed on your machine
+Use the Bookinfo sample application to verify that the workload certificates are signed by the certificates that were plugged into the CA. This process requires that you have `openssl` installed on your machine.
 
 . To extract certificates from bookinfo workloads use the following command:
 +

diff --git a/modules/ossm-cert-manager-installation.adoc b/modules/ossm-cert-manager-installation.adoc
@@ -0,0 +1,253 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v2x/ossm-security.adoc
+
+:_content-type: PROCEDURE
+[id="ossm-cert-manager-installation_{context}"]
+= Installing cert-manager
+
+To install cert-manager, follow these steps:
+
+.Procedure
+
+. Create the root cluster issuer:
++
+[source, terminal]
+----
+$ oc apply -f cluster-issuer.yaml
+----
++
+[source, terminal]
+----
+$ oc apply -n istio-system -f istio-ca.yaml
+----
++
+.Example `cluster-issuer.yaml`
+[source, yaml]
+----
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: selfsigned-root-issuer
+  namespace: cert-manager
+spec:
+  selfSigned: {}
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: root-ca
+  namespace: cert-manager
+spec:
+  isCA: true
+  duration: 21600h # 900d
+  secretName: root-ca
+  commonName: root-ca.my-company.net
+  subject:
+    organizations:
+    - my-company.net
+  issuerRef:
+    name: selfsigned-root-issuer
+    kind: Issuer
+    group: cert-manager.io
+---
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: root-ca
+spec:
+  ca:
+    secretName: root-ca
+----
++
+.Example `istio-ca.yaml`
+[source, yaml]
+----
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: istio-ca
+  namespace: istio-system
+spec:
+  isCA: true
+  duration: 21600h
+  secretName: istio-ca
+  commonName: istio-ca.my-company.net
+  subject:
+    organizations:
+    - my-company.net
+  issuerRef:
+    name: root-ca
+    kind: ClusterIssuer
+    group: cert-manager.io
+---
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: istio-ca
+  namespace: istio-system
+spec:
+  ca:
+    secretName: istio-ca
+----
++
+====
+[NOTE]
+The namespace of the `selfsigned-root-issuer` issuer and `root-ca` certificate is `cert-manager` because `root-ca` is a cluster issuer, so the cert-manager looks for a referenced secret in its own namespace. Its own namespace is `cert-manager` in the case of the {cert-manager-operator}.
+====
+
+. Install `istio-csr`:
++
+[source, terminal]
+----
+$ helm install istio-csr jetstack/cert-manager-istio-csr \
+    -n istio-system \
+    -f deploy/examples/cert-manager/istio-csr/istio-csr.yaml
+----
++
+.Example `istio-csr.yaml`
+[source, yaml]
+----
+replicaCount: 2
+
+image:
+  repository: quay.io/jetstack/cert-manager-istio-csr
+  tag: v0.6.0
+  pullSecretName: ""
+
+app:
+  certmanager:
+    namespace: istio-system
+    issuer:
+      group: cert-manager.io
+      kind: Issuer
+      name: istio-ca
+
+  controller:
+    configmapNamespaceSelector: "maistra.io/member-of=istio-system"
+    leaderElectionNamespace: istio-system
+
+  istio:
+    namespace: istio-system
+    revisions: ["basic"]
+
+  server:
+    maxCertificateDuration: 5m
+
+  tls:
+    certificateDNSNames:
+    # This DNS name must be set in the SMCP spec.security.certificateAuthority.cert-manager.address
+    - cert-manager-istio-csr.istio-system.svc
+----
+
+. Deploy SMCP:
++
+[source, terminal]
+----
+$ oc apply -f mesh.yaml -n istio-system
+----
++
+.Example `mesh.yaml`
+[source, yaml]
+----
+apiVersion: maistra.io/v2
+kind: ServiceMeshControlPlane
+metadata:
+  name: basic
+spec:
+  addons:
+    grafana:
+      enabled: false
+    kiali:
+      enabled: false
+    prometheus:
+      enabled: false
+  proxy:
+    accessLogging:
+      file:
+        name: /dev/stdout
+  security:
+    certificateAuthority:
+      cert-manager:
+        address: cert-manager-istio-csr.istio-system.svc:443
+      type: cert-manager
+    dataPlane:
+      mtls: true
+    identity:
+      type: ThirdParty
+  tracing:
+    type: None
+---
+apiVersion: maistra.io/v1
+kind: ServiceMeshMemberRoll
+metadata:
+  name: default
+spec:
+  members:
+  - httpbin
+  - sleep
+----
+
+====
+[NOTE]
+`security.identity.type: ThirdParty` must be set when `security.certificateAuthority.type: cert-manager` is configured.
+====
+
+.Verification
+
+To verify cert-manager is installed, follow these steps:
+
+. Deploy the HTTP and `sleep` apps:
++
+[source, terminal]
+----
+$ oc new-project <namespace>
+----
++
+[source, terminal]
+----
+$ oc apply -f https://raw.githubusercontent.com/maistra/istio/maistra-2.4/samples/httpbin/httpbin.yaml
+----
++
+[source, terminal]
+----
+$ oc apply -f https://raw.githubusercontent.com/maistra/istio/maistra-2.4/samples/sleep/sleep.yaml
+----
+
+. Verify that `sleep` can access the `httpbin` service:
++
+[source, terminal]
+----
+$ oc exec "$(oc get pod -l app=sleep -n <namespace> \
+   -o jsonpath={.items..metadata.name})" -c sleep -n <namespace> -- \
+   curl http://httpbin.<namespace>:8000/ip -s -o /dev/null \
+   -w "%{http_code}\n"
+----
++
+.Example output:
+[source, terminal]
+----
+200
+----
+
+. Check mTLS traffic from the ingress gateway to the `httpbin` service:
++
+[source, terminal]
+----
+$ oc apply -n <namespace> -f https://raw.githubusercontent.com/maistra/istio/maistra-2.4/samples/httpbin/httpbin-gateway.yaml
+----
+
+. Get the `istio-ingressgateway` route:
++
+[source, terminal]
+----
+INGRESS_HOST=$(oc -n istio-system get routes istio-ingressgateway -o jsonpath='{.spec.host}')
+----
+
+. Verify mTLS traffic from the ingress gateway to the `httpbin` service:
++
+[source, terminal]
+----
+$ curl -s -I http://$INGRESS_HOST/headers -o /dev/null -w "%{http_code}" -s
+----
+
diff --git a/modules/ossm-cert-manager-integration-istio.adoc b/modules/ossm-cert-manager-integration-istio.adoc
@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v2x/ossm-security.adoc
+
+:_content-type: CONCEPT
+[id="ossm-cert-manager-integration-istio_{context}"]
+= About integrating Service Mesh with cert-manager and istio-csr
+
+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. 
+
+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. 
+
+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.
+
+[NOTE]
+====
+Red Hat provides support for integrating with `istio-csr` and cert-manager. Red 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.
+====
+
+.Prerequisites
+* One of these versions of cert-manager: 
+** {cert-manager-operator} 1.10 or later
+** community cert-manager Operator 1.11 or later
+** cert-manager 1.11 or later
+
+* OpenShift Service Mesh Operator 2.4 or later
+* `istio-csr` 0.6.0 or later
+
+[NOTE]
+====
+To avoid creating config maps in all namespaces when the `istio-csr` server is installed with the `jetstack/cert-manager-istio-csr` Helm chart, use the following setting: `app.controller.configmapNamespaceSelector: "maistra.io/member-of: <istio-namespace>"` in the `istio-csr.yaml` file.
+====
+
+
diff --git a/service_mesh/v2x/ossm-security.adoc b/service_mesh/v2x/ossm-security.adoc
@@ -34,6 +34,22 @@ include::modules/ossm-security-cert-manage.adoc[leveloffset=+1]
 
 include::modules/ossm-cert-manage-add-cert-key.adoc[leveloffset=+1]
 
-include::modules/ossm-cert-manage-verify-cert.adoc[leveloffset=+1]
+include::modules/ossm-cert-manage-verify-cert.adoc[leveloffset=+2]
 
-include::modules/ossm-cert-cleanup.adoc[leveloffset=+1]
+include::modules/ossm-cert-cleanup.adoc[leveloffset=+1]
+
+include::modules/ossm-cert-manager-integration-istio.adoc[leveloffset=+1]
+
+include::modules/ossm-cert-manager-installation.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+[id="additional-resources_cert-manager-operator-red-hat-openshift"]
+== Additional resources 
+
+For information about how to install the cert-manager Operator for {product-title}, see:
+ifndef::openshift-rosa,openshift-dedicated[]
+xref:../../security/cert_manager_operator/cert-manager-operator-install.adoc[Installing the cert-manager Operator for Red Hat OpenShift].
+endif::[]
+ifdef::openshift-rosa,openshift-dedicated[]
+link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.12/html-single/security_and_compliance/index#cert-manager-operator-install[Installing the cert-manager Operator for Red Hat OpenShift].
+endif::[]