[Enterprise-4.15] OSDOCS 13077: Added istio-csr itegration feature to cert-manager

_topic_maps/_topic_map.yml

@@ -1140,6 +1140,8 @@ Topics:
     File: cert-manager-operator-issuer-acme
   - Name: Configuring certificates with an issuer
     File: cert-manager-creating-certificate
+  - Name: Integrating the cert-manager Operator with Istio-CSR
+    File: cert-manager-operator-integrating-istio
   - Name: Monitoring the cert-manager Operator for Red Hat OpenShift
     File: cert-manager-monitoring
   - Name: Configuring log levels for cert-manager and the cert-manager Operator for Red Hat OpenShift

modules/cert-manager-enabling-istio.adoc

@@ -0,0 +1,37 @@
+// Module included in the following assemblies:
+//
+// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="cert-manager-enabling-istio_{context}"]
+= Enabling the Istio-CSR feature
+
+Use this procedure to enable the Istio-CSR feature in {cert-manager-operator}.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+
+.Procedure
+
+* Update the deployment for the {cert-manager-operator} to use the config map by running the following command:
++
+[source,terminal]
+----
+$ oc -n cert-manager-operator patch subscription openshift-cert-manager-operator --type='merge' -p '{"spec":{"config":{"env":[{"name":"UNSUPPORTED_ADDON_FEATURES","value":"IstioCSR=true"}]}}}'
+----
+
+.Verification
+
+. Verify that the deployments have finished rolling out by running the following command:
++
+[source,terminal]
+----
+$ oc rollout status deployment/cert-manager-operator-controller-manager -n cert-manager-operator
+----
++
+.Example output
+[source,terminal]
+----
+deployment "cert-manager-operator-controller-manager" successfully rolled out
+----

modules/cert-manager-istio-creating-issuer.adoc

@@ -0,0 +1,76 @@
+// Module included in the following assemblies:
+//
+// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="cert-manager-istio-creating-issuer_{context}"]
+= Creating a root CA issuer for the Istio-CSR agent
+
+Use this procedure to create the root CA issuer for Istio-CSR agent.
+
+[NOTE]
+====
+Other supported issuers can be used, except for the ACME issuer, which is not supported. For more information, see "{cert-manager-operator} issuer providers".
+====
+
+* Create a YAML file, for example, `issuer.yaml`, that defines the `Issuer` and `Certificate` objects:
++
+.Example `issuer.yaml` file
+[source,yaml]
+----
+apiVersion: cert-manager.io/v1
+kind: Issuer <1>
+metadata:
+  name: selfsigned
+  namespace: <istio_project_name> <2>
+spec:
+  selfSigned: {}
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: istio-ca
+  namespace: <istio_project_name>
+spec:
+ isCA: true
+  duration: 87600h # 10 years
+  secretName: istio-ca
+  commonName: istio-ca
+  privateKey:
+    algorithm: ECDSA
+    size: 256
+  subject:
+    organizations:
+      - cluster.local
+      - cert-manager
+  issuerRef:
+    name: selfsigned
+    kind: Issuer <1>
+    group: cert-manager.io
+---
+kind: Issuer
+metadata:
+  name: istio-ca
+  namespace: <istio_project_name> <2>
+spec:
+  ca:
+    secretName: istio-ca
+----
+<1> Specify the `Issuer` or `ClusterIssuer`.
+<2> Specify the name of the Istio project.
+
+.Verification
+
+* Verify that the Issuer is created and ready to use by running the following command:
++
+[source,terminal]
+----
+$ oc get issuer istio-ca -n <istio_project_name>
+----
++
+.Example output
+[source,terminal]
+----
+NAME       READY   AGE
+istio-ca   True    3m
+----

modules/cert-manager-istio-csr-installing.adoc

@@ -0,0 +1,117 @@
+// Module included in the following assemblies:
+//
+// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="cert-manager-istio-csr-installing_{context}"]
+= Creating the `IstioCSR` custom resource
+
+Use this procedure to install the Istio-CSR agent through {cert-manager-operator}.
+
+.Prerequisites
+
+* You have access to the cluster with `cluster-admin` privileges.
+* You have enabled the Istio-CSR feature.
+* You have created the `Issuer` or `ClusterIssuer` resources required for generating certificates for the Istio-CSR agent.
++
+[NOTE]
+====
+If you are using `Issuer` resource, create the `Issuer` and `Certificate` resources in the {SMProductName} or `Istiod` namespace. Certificate requests are generated in the same namespace, and role-based access control (RBAC) is configured accordingly.  
+==== 
+
+.Procedure
+
+. Create a new project for installing Istio-CSR by running the following command. You can use an existing project and skip this step.
++
+[source,terminal]
+----
+$ oc new-project <istio_csr_project_name>
+----
+
+. Create the `IstioCSR` custom resource to enable Istio-CSR agent managed by the {cert-manager-operator} for processing Istio workload and control plane certificate signing requests.
++
+[NOTE]  
+====  
+Only one `IstioCSR` custom resource (CR) is supported at a time. If multiple `IstioCSR` CRs are created, only one will be active. Use the `status` sub-resource of `IstioCSR` to check if a resource is unprocessed.  
+
+* If multiple `IstioCSR` CRs are created simultaneously, none will be processed.  
+* If multiple `IstioCSR` CRs are created sequentially, only the first one will be processed. 
+* To prevent new requests from being rejected, delete any unprocessed `IstioCSR` CRs.
+* The Operator does not automatically remove objects created for `IstioCSR`. If an active `IstioCSR` resource is deleted and a new one is created in a different namespace without removing the previous deployments, multiple `istio-csr` deployments may remain active. This behavior is not recommended and is not supported.    
+====  
+
+.. Create a YAML file, for example, `istiocsr.yaml`, that defines the `IstioCSR` object:
++
+.Example `IstioCSR.yaml` file
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1alpha1
+kind: IstioCSR
+metadata:
+  name: default
+  namespace: <istio_csr_project_name>
+spec:
+  IstioCSRConfig:
+    certManager:
+      issuerRef:
+        name: istio-ca  <1>
+        kind: Issuer <2>
+        group: cert-manager.io
+    istiodTLSConfig:
+      trustDomain: cluster.local
+    istio:
+      namespace: istio-system
+----
+<1> Specify the `Issuer` or `ClusterIssuer` name. It should be the same name as the CA issuer defined in the `issuer.yaml` file.
+<2> Specify the `Issuer` or `ClusterIssuer` kind. It should be the same kind as the CA issuer defined in the `issuer.yaml` file.
+
+.. Create the `IstioCSR` custom resource by running the following command:
++
+[source,terminal]
+----
+$ oc create -f IstioCSR.yaml
+----
+
+.Verification
+
+. Verify that the Istio-CSR deployment is ready by running the following command:
++
+[source,terminal]
+----
+$ oc get deployment -n <istio_csr_project_name>
+----
++
+.Example output
+[source,terminal]
+----
+NAME                     READY   UP-TO-DATE   AVAILABLE   AGE
+cert-manager-istio-csr   1/1     1            1           24s
+----
+
+. Verify that the Istio-CSR pods are running by running the following command:
++
+[source,terminal]
+----
+$ oc get pod -n <istio_csr_project_name>
+----
++
+.Example output
+[source,terminal]
+----
+NAME                                  	 READY   STATUS	  RESTARTS    AGE
+cert-manager-istio-csr-5c979f9b7c-bv57w  1/1     Running  0           45s
+----
+
+** Verify that the Istio-CSR pod is not reporting any errors in the logs by running the following command:
++
+[source,terminal]
+----
+$ oc -n <istio_csr_project_name> logs <istio_csr_pod_name>
+----
+
+** Verify that the {cert-manager-operator} pod is not reporting any errors by running the following command:
++
+[source,terminal]
+----
+$ oc -n cert-manager-operator logs <cert_manager_operator_pod_name>
+----

modules/cert-manager-istio-csr-uninstalling.adoc

@@ -0,0 +1,61 @@
+// Module included in the following assemblies:
+//
+// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="cert-manager-istio-csr-uninstalling_{context}"]
+= Uninstalling the Istio-CSR agent managed by {cert-manager-operator}
+
+Use this procedure to uninstall the Istio-CSR agent managed by {cert-manager-operator}.
+
+.Prerequisites
+
+* You have access to the cluster with `cluster-admin` privileges.
+* You have enabled the Istio-CSR feature.
+* You have created the `IstioCSR` custom resource.
+
+.Procedure
+
+. Remove the `IstioCSR` custom resource by running the following command:
++
+[source,terminal]
+----
+$ oc -n <istio-csr_project_name> delete istiocsrs.operator.openshift.io default
+----
+
+. Remove related resources:
++
+[IMPORTANT]
+====
+To avoid disrupting any {SMProductName} or Istio components, ensure that no component is referencing the Istio-CSR service or the certificates issued for Istio before removing the following resources.
+====
+
+.. List the cluster scoped-resources by running the following command and save the names of the listed resources for later reference:
++
+[source,terminal]
+----
+$ oc get clusterrolebindings,clusterroles -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr"
+----
+
+.. List the resources in Istio-csr deployed namespace by running the following command and save the names of the listed resources for later reference:
++
+[source,terminal]
+----
+$ oc get certificate,deployments,services,serviceaccounts -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" -n <istio_csr_project_name>
+----
+
+.. List the resources in {SMProductName} or Istio deployed namespaces by running the following command and save the names of the listed resources for later reference:
++
+[source,terminal]
+----
+$ oc get roles,rolebindings -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" -n <istio_csr_project_name>
+----
+
+.. For each resource listed in previous steps, delete the resource by running the following command:
++
+[source,terminal]
+----
+$ oc -n <istio_csr_project_name> delete <resource_type>/<resource_name>
+----
++
+Repeat this process until all of the related resources have been deleted.

modules/cert-manager-istio-csr-updating.adoc

@@ -0,0 +1,9 @@
+// Module included in the following assemblies:
+//
+// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="cert-manager-istio-csr-updating_{context}"]
+= Upgrading the {cert-manager-operator} with Istio-CSR feature enabled 
+
+When the Istio-CSR TechPreview feature gate is enabled, the Operator cannot be upgraded. To use to the next available version, you must uninstall the {cert-manager-operator} and remove all Istio-CSR resources before reinstalling it.

security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc

@@ -0,0 +1,37 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cert-manager-operator-integrating-istio"]
+= Integrating the {cert-manager-operator} with Istio-CSR
+include::_attributes/common-attributes.adoc[]
+:context: cert-manager-operator-integrating-istio
+
+toc::[]
+
+:FeatureName: Istio-CSR integration for {cert-manager-operator}
+include::snippets/technology-preview.adoc[]
+
+The {cert-manager-operator} provides enhanced support for securing workloads and control plane components in {SMProductName} or Istio. This includes support for certificates enabling mutual TLS (mTLS), which are signed, delivered, and renewed using cert-manager issuers. You can secure Istio workloads and control plane components by using the {cert-manager-operator} managed Istio-CSR agent.
+
+With this Istio-CSR integration, Istio can now obtain certificates from the {cert-manager-operator}, simplifying security and certificate management.
+
+[id="cert-manager-operator-istio-csr-installing_{context}"]
+== Installing the Istio-CSR agent through {cert-manager-operator}
+
+// Enabling Istio-CSR
+include::modules/cert-manager-enabling-istio.adoc[leveloffset=+2]
+
+// Creating issuer
+include::modules/cert-manager-istio-creating-issuer.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../security/cert_manager_operator/index.adoc#cert-manager-issuer-types_cert-manager-operator-about[{cert-manager-operator} issuer providers]
+
+// Installing using Istio-CSR
+include::modules/cert-manager-istio-csr-installing.adoc[leveloffset=+2]
+
+// Uninstalling cert-manager Operator with Istio-CSR
+include::modules/cert-manager-istio-csr-uninstalling.adoc[leveloffset=+1]
+
+// Updating Istio-CSR 
+include::modules/cert-manager-istio-csr-updating.adoc[leveloffset=+1]

security/cert_manager_operator/cert-manager-operator-uninstall.adoc

@@ -12,4 +12,4 @@ You can remove the {cert-manager-operator} from {product-title} by uninstalling
 include::modules/cert-manager-uninstall-console.adoc[leveloffset=+1]
 
 // Removing {cert-manager-operator} resources
-include::modules/cert-manager-remove-resources-console.adoc[leveloffset=+1]
+include::modules/cert-manager-remove-resources-console.adoc[leveloffset=+1]