diff --git a/modules/cert-manager-config-metrics-collection.adoc b/modules/cert-manager-config-metrics-collection.adoc new file mode 100644 index 000000000000..ee3d1b268c90 --- /dev/null +++ b/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: <1> +spec: + endpoints: + - honorLabels: false + interval: 60s + path: /metrics + scrapeTimeout: 30s + targetPort: 9402 + namespaceSelector: + matchNames: + - <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 `` 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. \ No newline at end of file diff --git a/modules/cert-manager-enabling-istio.adoc b/modules/cert-manager-enabling-istio.adoc deleted file mode 100644 index becb153d282f..000000000000 --- a/modules/cert-manager-enabling-istio.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// 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 ----- \ No newline at end of file diff --git a/modules/cert-manager-istio-csr-config-ca-cert.adoc b/modules/cert-manager-istio-csr-config-ca-cert.adoc new file mode 100644 index 000000000000..7a3c6eaf72e0 --- /dev/null +++ b/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 <1> +---- +<1> Replace `` 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: <1> + name: <2> + 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. diff --git a/modules/cert-manager-istio-csr-config-namespace-sel.adoc b/modules/cert-manager-istio-csr-config-namespace-sel.adoc new file mode 100644 index 000000000000..02774223f986 --- /dev/null +++ b/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 <1> +---- +<1> Replace `` 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 `=`. ++ +[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. \ No newline at end of file diff --git a/modules/cert-manager-istio-csr-customizing.adoc b/modules/cert-manager-istio-csr-customizing.adoc new file mode 100644 index 000000000000..6e539ccd5f07 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/modules/cert-manager-istio-csr-setting-log-level.adoc b/modules/cert-manager-istio-csr-setting-log-level.adoc new file mode 100644 index 000000000000..82731d91fe16 --- /dev/null +++ b/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 <1> +---- +<1> Replace `` 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. diff --git a/modules/cert-manager-istio-csr-updating.adoc b/modules/cert-manager-istio-csr-updating.adoc deleted file mode 100644 index ae71dcc8a211..000000000000 --- a/modules/cert-manager-istio-csr-updating.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// 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. \ No newline at end of file diff --git a/modules/cert-manager-query-metrics-for-istio-csr-operand.adoc b/modules/cert-manager-query-metrics-for-istio-csr-operand.adoc new file mode 100644 index 000000000000..2c5fd454d78c --- /dev/null +++ b/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. diff --git a/security/cert_manager_operator/cert-manager-monitoring.adoc b/security/cert_manager_operator/cert-manager-monitoring.adoc index 20c4a3b034a1..83fbb29f97c2 100644 --- a/security/cert_manager_operator/cert-manager-monitoring.adoc +++ b/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] diff --git a/security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc b/security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc index cfaf8bc15c03..ca64ece6aec1 100644 --- a/security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc +++ b/security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc @@ -6,9 +6,6 @@ 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. @@ -16,9 +13,6 @@ With this Istio-CSR integration, Istio can now obtain certificates from the {cer [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] \ No newline at end of file +// 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] \ No newline at end of file