[enterprise-4.18] OSDOCS#15839: istio-csr integration for cert-manager GA

modules/cert-manager-config-metrics-collection.adoc

@@ -0,0 +1,65 @@
+// Module included in the following assemblies:
+//
+// * security/cert_manager_operator/cert-manager-monitoring.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="cert-manager-config-metrics-collection_{context}"]
+= Configuring metrics collection for the istio-csr operand
+
+The istio-csr operand exposes metrics by default on port `9402` at the `/metrics` service endpoint. You can configure metrics collection for the operand by creating a `ServiceMonitor` custom resource (CR), which enables the Prometheus Operator to collect custom metrics. For more information, see "Configuring user workload monitoring".
+
+.Prerequisites
+
+* You have access to the cluster with `cluster-admin` privileges.  
+* You have installed the {cert-manager-operator}.  
+* You have enabled user workload monitoring.
+
+.Procedure
+
+. Create the `ServiceMonitor` CR definition file:
++
+.Example `servicemonitor-istio-csr.yaml` file
+[source,yaml]
+----
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  labels:
+    app: cert-manager-istio-csr
+    app.kubernetes.io/instance: cert-manager-istio-csr
+    app.kubernetes.io/name: cert-manager-istio-csr
+  name: cert-manager-istio-csr
+  namespace: <istio_csr_project_name> <1>
+spec:
+  endpoints:
+    - honorLabels: false
+      interval: 60s
+      path: /metrics
+      scrapeTimeout: 30s
+      targetPort: 9402
+  namespaceSelector:
+    matchNames:
+      - <istio_csr_project_name> <1>
+  selector:
+    matchLabels:
+      app: cert-manager-istio-csr
+      app.kubernetes.io/instance: cert-manager-istio-csr
+      app.kubernetes.io/name: cert-manager-istio-csr
+----
+<1> Replace `<istio_csr_project_name>` with the namespace where you created the `IstioCSR` CR.
+
+. Create the `ServiceMonitor` CR by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f servicemonitor-istio-csr.yaml
+----
+
+After the `ServiceMonitor` CR is created, the user workload Prometheus instance starts collecting metrics from the istio-csr operand. The collected metrics are labeled with `job="cert-manager-istio-csr"`.
+
+.Verification
+
+. Log in to the {product-title} web console.
+. Click *Observe* -> *Targets*.
+. In the **Label filter** field, enter the `service=cert-manager-istio-csr` label to filter the metrics targets.
+. Confirm that the *Status* column shows *Up* for the `cert-manager-istio-csr` target.

modules/cert-manager-istio-csr-config-ca-cert.adoc

@@ -0,0 +1,47 @@
+:_mod-docs-content-type: PROCEDURE
+[id="cert-manager-istio-csr-config-ca-cert_{context}"]
+= Configuring the CA certificate for the Istio server
+
+You can configure the `ConfigMap` that contains the CA bundle used by Istio workloads to verify the Istio server certificate. If not configured, the {cert-manager-operator} looks for the CA certificate in the configured issuer and in the Kubernetes Secret that contains the Istio certificates.
+
+.Prerequisites
+
+* You have access to the cluster with `cluster-admin` privileges.
+* You have created the `IstioCSR` custom resource (CR).
+
+.Procedure
+
+. Edit the `IstioCSR` CR by running the following command:
++
+[source,terminal]
+----
+oc edit istiocsrs.operator.openshift.io default -n <istio_csr_project_name> <1>
+----
+<1> Replace `<istio_csr_project_name>` with the namespace where you created the `IstioCSR` CR.
+
+. Configure the CA bundle by editing the `spec.istioCSRConfig.certManager` section:
++
+.Sample `IstioCSR` CR with CA bundle configuration
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1alpha1
+kind: IstioCSR
+...
+spec:
+  istioCSRConfig:
+    certManager:
+      istioCACertificate:
+        key: <key_in_the_configmap> <1>
+        name: <configmap_name> <2>
+        namespace: <configmap_namespace> <3>
+----
+<1> Specify the key name in the `ConfigMap` that contains the CA bundle.  
+<2> Specify the name of the `ConfigMap`. Ensure that the referenced `ConfigMap` and key exist before you update this field.
+<3> Optional: Specify the namespace where the `ConfigMap` exists. If you do not set this field, the {cert-manager-operator} searches for the `ConfigMap` in the namespace where you have installed the `IstioCSR` CR.
++
+[NOTE]
+====
+Whenever the CA certificate is rotated, you must manually update the `ConfigMap` with the latest certificate.
+====
+
+. Save and close the editor to apply your changes. After the changes are applied, the cert-manager Operator updates the CA bundle for the `istio-csr` operand.

modules/cert-manager-istio-csr-config-namespace-sel.adoc

@@ -0,0 +1,51 @@
+:_mod-docs-content-type: PROCEDURE
+[id="cert-manager-istio-csr-config-namespace-sel_{context}"]
+= Configuring the namespace selector for CA bundle distribution
+
+The Istio-CSR agent creates and updates the `istio-ca-root-cert` `ConfigMap`, which contains the CA bundle. Workloads in the service mesh use this CA bundle to validate connections to the Istio control plane. You can configure a namespace selector to specify the namespaces in which the Istio-CSR agent creates this `ConfigMap`. If you do not configure a selector, the Istio-CSR agent creates the `ConfigMap` in all namespaces.
+
+.Prerequisites
+
+* You have access to the cluster with `cluster-admin` privileges.
+* You have created the `IstioCSR` custom resource (CR).
+
+.Procedure
+
+. Edit the `IstioCSR` CR by running the following command:
++
+[source,terminal]
+----
+oc edit istiocsrs.operator.openshift.io default -n <istio_csr_project_name> <1>
+----
+<1> Replace `<istio_csr_project_name>` with the namespace where you created the `IstioCSR` CR.
+
+. Configure the `spec.istioCSRConfig.istioDataPlaneNamespaceSelector` section to set the namespace selector:
++
+.Sample IstioCSR CR configuration with a namespace selector
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1alpha1
+kind: IstioCSR
+...
+spec:
+  istioCSRConfig:
+    istioDataPlaneNamespaceSelector: maistra.io/member-of=istio-system <1>
+# ...
+----
+<1> Replace `maistra.io/member-of=istio-system` with the label key and value that identify the namespaces in your service mesh. Use the format `<key>=<value>`.
++
+[NOTE]
+====
+The istio-csr component does not delete or manage `ConfigMap` objects in namespaces that do not match the configured selector. If you create or update the selector after deploying the `IstioCSR` CR, or if you remove a label from a namespace, you must manually delete these `ConfigMap` objects to avoid conflicts.
+
+You can run the following command to list `ConfigMap` objects that are not in namespaces matching the selector. In this example, the selector is `maistra.io/member-of=istio-system`:
+[source,terminal]
+----
+printf "%-25s %10s\n" "ConfigMap" "Namespace"; \
+for ns in $(oc get namespaces -l "maistra.io/member-of!=istio-system" -o=jsonpath='{.items[*].metadata.name}'); do \
+  oc get configmaps -l "istio.io/config=true" -n $ns --no-headers -o jsonpath='{.items[*].metadata.name}{"\t"}{.items[*].metadata.namespace}{"\n"}' --ignore-not-found; \
+done
+----
+====
+
+. Save and close the editor to apply your changes. After the changes are applied, the {cert-manager-operator} updates the namespace selector configuration for the istio-csr operand.

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

@@ -0,0 +1,10 @@
+// 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-customizing_{context}"]
+
+= Customizing the IstioCSR custom resource
+
+You can modify the `IstioCSR` custom resource (CR) to define how Istio workloads interact with the cert-manager Operator.

modules/cert-manager-istio-csr-setting-log-level.adoc

@@ -0,0 +1,39 @@
+:_mod-docs-content-type: PROCEDURE
+[id="cert-manager-istio-csr-setting-log-level_{context}"]
+= Setting the log level for the istio-csr component
+
+You can set the log level for the istio-csr component to control the verbosity and format of its log messages.
+
+.Prerequisites
+
+* You have access to the cluster with `cluster-admin` privileges.
+* You have created the `IstioCSR` custom resource (CR).
+
+.Procedure
+
+. Edit the `IstioCSR` CR by running the following command:
++
+[source,terminal]
+----
+oc edit istiocsrs.operator.openshift.io default -n <istio_csr_project_name> <1>
+----
+<1> Replace `<istio_csr_project_name>` with the namespace where you created the `IstioCSR` CR.
+
+. Configure the log level and format in the `spec.istioCSRConfig` section:
++
+.Sample IstioCSR CR configuration for setting the log level
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1alpha1
+kind: IstioCSR
+...
+spec:
+  istioCSRConfig:
+    logFormat: text <1>
+    logLevel: 2 <2>
+# ...
+----
+<1> Specify the log output format. You can set this field to either `text` or `json`.  
+<2> Set the log level. Supported values are in the range `1` through `5`, as defined by Kubernetes logging guidelines. The default value is `1`.
+
+. Save and close the editor to apply your changes. After the changes are applied, the cert-manager Operator updates the log configuration for the istio-csr operand.

modules/cert-manager-query-metrics-for-istio-csr-operand.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * security/cert_manager_operator/cert-manager-monitoring.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="cert-manager-query-metrics-for-istio-csr-operand_{context}"]
+= Querying metrics for the istio-csr operand
+
+Cluster administrators, or users with view access to all namespaces, can query metrics for the istio-csr operand by using the {product-title} web console. For more information, see "Accessing metrics".
+
+.Prerequisites
+
+* You have access to the cluster with `cluster-admin` privileges.  
+* You have installed the {cert-manager-operator}.  
+* You have enabled monitoring and metrics collection by creating the `ServiceMonitor` object for the istio-csr operand.
+
+.Procedure
+
+. Log in to the {product-title} web console.
+. Click *Observe* -> *Metrics*.  
+. In the query field, enter the following PromQL expression to query the `istio-csr` operand metrics:
++
+`{job="cert-manager-istio-csr"}`
+
+The results display metrics collected for the istio-csr operand, which can help you monitor its performance and behavior.

security/cert_manager_operator/cert-manager-monitoring.adoc

@@ -30,3 +30,19 @@ include::modules/cert-manager-query-metrics.adoc[leveloffset=+1]
 .Additional resources
 
 * xref:../../observability/monitoring/accessing-metrics/accessing-metrics-as-an-administrator.adoc#accessing-metrics[Accessing metrics]
+
+// Configuring metrics collection for cert-manager Operator for Red Hat OpenShift istio-csr operand by using a ServiceMonitor
+include::modules/cert-manager-config-metrics-collection.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../observability/monitoring/configuring-user-workload-monitoring/preparing-to-configure-the-monitoring-stack-uwm.adoc#configurable-monitoring-components_preparing-to-configure-the-monitoring-stack-uwm[Configuring user workload monitoring]
+
+// Querying metrics for the istio-csr operand
+include::modules/cert-manager-query-metrics-for-istio-csr-operand.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../observability/monitoring/accessing-metrics/accessing-metrics-as-an-administrator.adoc#accessing-metrics-as-an-administrator[Accessing metrics as an administrator]

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

@@ -6,19 +6,13 @@ include::_attributes/common-attributes.adoc[]
 
 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]
 
@@ -30,8 +24,17 @@ include::modules/cert-manager-istio-creating-issuer.adoc[leveloffset=+2]
 // 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]
+// Customizing the IstioCSR custom resource
+include::modules/cert-manager-istio-csr-customizing.adoc[leveloffset=+1]
+
+// Setting a log level for istio-csr
+include::modules/cert-manager-istio-csr-setting-log-level.adoc[leveloffset=+2]
 
-// Updating Istio-CSR 
-include::modules/cert-manager-istio-csr-updating.adoc[leveloffset=+1]
+// Configuring the namespace selector for CA bundle distribution [leveloffset=+3]
+include::modules/cert-manager-istio-csr-config-namespace-sel.adoc[leveloffset=+2]
+
+// Configuring the CA certificate of the istio server [leveloffset=+3]
+include::modules/cert-manager-istio-csr-config-ca-cert.adoc[leveloffset=+2]
+
+// Uninstalling cert-manager Operator with Istio-CSR
+include::modules/cert-manager-istio-csr-uninstalling.adoc[leveloffset=+1]