docs(opa): update of metrics and security content (#11307)

Signed-off-by: prmellor <[email protected]>

Author: PaulRMellor

documentation/assemblies/metrics/assembly-metrics.adoc

@@ -6,39 +6,23 @@
 = Introducing metrics
 
 [role="_abstract"]
-Collecting metrics is critical for understanding the health and performance of your Kafka deployment. 
-By monitoring metrics, you can actively identify issues before they become critical and make informed decisions about resource allocation and capacity planning. Without metrics, you may be left with limited visibility into the behavior of your Kafka deployment, which can make troubleshooting more difficult and time-consuming. Setting up metrics can save you time and resources in the long run, and help ensure the reliability of your Kafka deployment.
+Collecting metrics is essential for understanding the health and performance of your Kafka deployment. 
+By monitoring metrics, you can actively identify issues before they become critical and make informed decisions about resource allocation and capacity planning. 
+Without metrics, you may be left with limited visibility into the behavior of your Kafka deployment, which can make troubleshooting more difficult and time-consuming. 
+Setting up metrics can save you time and resources, and help ensure the reliability of your Kafka deployment.
 
-Metrics are available for each component in Strimzi, providing valuable insights into their individual performance. 
-While other components require configuration to expose metrics, Strimzi operators automatically expose Prometheus metrics by default. 
-These metrics include:
-
-* Reconciliation count
-* Custom Resource count being processed
-* Reconciliation duration
-* JVM metrics
-
-You can also collect metrics specific to `oauth` authentication and `opa` or `keycloak` authorization by enabling the `enableMetrics` property in the listener or authorization configuration of the `Kafka` resource.
-Similarly, you can enable metrics for `oauth` authentication in custom resources such as `KafkaBridge`, `KafkaConnect`, and `KafkaMirrorMaker2`.
-
-You can use Prometheus and Grafana to monitor Strimzi.
-Prometheus consumes metrics from the running pods in your cluster when configured with Prometheus rules. 
+Metrics can be collected from Strimzi components using Prometheus and visualized in Grafana.
+Prometheus collects metrics from running pods in your cluster when configured with appropriate rules. 
 Grafana visualizes these metrics on dashboards, providing an intuitive interface for monitoring. 
 
-To facilitate metrics integration, Strimzi provides example Prometheus rules and Grafana dashboards for Strimzi components. 
-You can customize the example Grafana dashboards to suit your specific deployment requirements.
-You can use rules to define conditions that trigger alerts based on specific metrics.
-
-Depending on your monitoring requirements, you can do the following:
-
-* xref:assembly-metrics-setup-{context}[Set up and deploy Prometheus to expose metrics]
-* xref:proc-metrics-kafka-deploy-options-{context}[Deploy Kafka Exporter to provide additional metrics]
-* xref:proc-metrics-grafana-dashboard-{context}[Use Grafana to present the Prometheus metrics]
+While the Strimzi operators expose their own Prometheus metrics by default, such as reconciliation counts and durations, JVM data, and resource processing statistics, other Strimzi components and features that support metrics, including OAuth 2.0 integration, require configuration to expose them.
 
+Strimzi provides example Prometheus rules and Grafana dashboards, which you can customize to fit your deployment. 
+These tools help visualize metrics and define alerts based on specific conditions.
 Additionally, you can configure your deployment to track messages end-to-end by xref:assembly-distributed-tracing-str[setting up distributed tracing].
 
-NOTE: Strimzi provides example installation files for Prometheus and Grafana, which can serve as a starting point for monitoring your Strimzi deployment. 
-For further support, try engaging with the Prometheus and Grafana developer communities.
+NOTE: Strimzi provides example installation files for Prometheus and Grafana to help get you started. 
+For further support, refer to the Prometheus and Grafana developer communities.
 
 .Supporting documentation for metrics and monitoring tools
 For more information on the metrics and monitoring tools, refer to the supporting documentation:
@@ -47,7 +31,7 @@ For more information on the metrics and monitoring tools, refer to the supportin
 * {PrometheusConfig}
 * {kafka-exporter-project}
 * {GrafanaHome}
-* link:http://kafka.apache.org/documentation/#monitoring[Apache Kafka Monitoring] describes JMX metrics exposed by Apache Kafka
+* link:http://kafka.apache.org/documentation/#monitoring[Apache Kafka Monitoring^] describes JMX metrics exposed by Apache Kafka
 
 //what is Consumer lag?
 include::../../modules/metrics/con_kafka-exporter-lag.adoc[leveloffset=+1]

documentation/modules/con-common-configuration-properties.adoc

@@ -115,7 +115,7 @@ tls:
   trustedCertificates: []
 ----
 
-Similarly, you can use the `tlstrustedCertificates` property in the configuration for `oauth`, `keycloak`, and `opa` authentication and authorization types that integrate with authorization servers.
+Similarly, you can use the `tlsTrustedCertificates` property in the configuration for `oauth` and `keycloak` authentication and authorization types that integrate with authorization servers.
 The configuration sets up encrypted TLS connections to the authorization server.
 
 .Example TLS encryption configuration for authentication types

documentation/modules/configuring/con-config-kafka-kraft.adoc

@@ -172,7 +172,7 @@ spec:
 <15> Healthchecks to know when to restart a container (liveness) and when a container can accept traffic (readiness).
 <16> JVM configuration options to optimize performance for the Virtual Machine (VM) running Kafka.
 <17> ADVANCED OPTION: Container image configuration, which is recommended only in special situations.
-<18> Authorization enables simple, OAUTH 2.0, or OPA authorization on the Kafka broker. Simple authorization uses the `AclAuthorizer` and `StandardAuthorizer` Kafka plugins.
+<18> Authorization enables simple, OAuth 2.0, custom, or OPA (deprecated) authorization on the Kafka broker. Simple authorization uses the `StandardAuthorizer` Kafka plugin.
 <19> Rack awareness configuration to spread replicas across different racks, data centers, or availability zones. The `topologyKey` must match a node label containing the rack ID. The example used in this configuration specifies a zone using the standard `{K8sZoneLabel}` label.
 <20> Prometheus metrics enabled. In this example, metrics are configured for the Prometheus JMX Exporter (the default metrics exporter).
 <21> Rules for exporting metrics in Prometheus format to a Grafana dashboard through the Prometheus JMX Exporter, which are enabled by referencing a ConfigMap containing configuration for the Prometheus JMX exporter. You can enable metrics without further configuration using a reference to a ConfigMap containing an empty file under `metricsConfig.valueFrom.configMapKeyRef.key`.

documentation/modules/metrics/proc-metrics-kafka-deploy-options.adoc

@@ -6,26 +6,31 @@
 = Enabling Prometheus metrics through configuration
 
 [role="_abstract"]
-To enable and expose metrics in Strimzi for Prometheus, use metrics configuration properties. 
+To enable and expose metrics in Strimzi for Prometheus, configure the appropriate properties in the custom resources for the components you want to monitor.
 
-The following components require `metricsConfig` configuration to expose metrics:
+Use `metricsConfig` to expose metrics for these components:
 
 * Kafka 
-* KafkaConnect
+* Kafka Connect
 * MirrorMaker
 * Cruise Control
 
-This configuration enables the {JMXExporter} to expose metrics through an HTTP endpoint.
-The port for the JMX exporter HTTP endpoint is 9404. 
+This enables the {JMXExporter}, which exposes metrics on port 9404 through an HTTP endpoint. 
 Prometheus scrapes this endpoint to collect Kafka metrics.
 
-Set the `enableMetrics` property to `true` in order to expose metrics for these components:
+Set `enableMetrics` to `true` to expose metrics for the following: 
 
-* Kafka Bridge 
-* OAuth 2.0 authentication and authorization framework
-* Open Policy Agent (OPA) for authorization
+* Kafka Bridge
+* OAuth 2.0
+** Configure in the `Kafka` resource for `oauth` or `keycloak` cluster authorization, or `oauth` listener authentication.
+** Configure in the `KafkaBridge`, `KafkaConnect`, or `KafkaMirrorMaker2` resources for `oauth` authentication.
 
-To deploy Prometheus metrics configuration in Strimzi, you can use your own configuration or the xref:ref-metrics-prometheus-metrics-config-{context}[example custom resource configuration files] provided with Strimzi:
+To include xref:con-metrics-kafka-exporter-lag-str[Kafka Exporter] metrics, add `kafkaExporter` configuration to the `Kafka` resource.
+
+IMPORTANT: Kafka Exporter provides additional metrics for consumer lag and offsets only.
+You still need to configure Prometheus metrics in the `Kafka` resource to collect standard Kafka metrics.
+
+You can create your own Prometheus configuration or use the xref:ref-metrics-prometheus-metrics-config-{context}[example custom resource files] provided with Strimzi:
 
 * `kafka-metrics.yaml`
 * `kafka-connect-metrics.yaml`
@@ -34,16 +39,10 @@ To deploy Prometheus metrics configuration in Strimzi, you can use your own conf
 * `kafka-cruise-control-metrics.yaml`
 * `oauth-metrics.yaml`
 
-These files contain the necessary relabeling rules and configuration to enable Prometheus metrics.
-They are a good starting point for trying Prometheus with Strimzi. 
-
-This procedure shows how to deploy example Prometheus metrics configuration in the `Kafka` resource.
-The process is the same when deploying the example files for other resources.
+These files include relabeling rules and example metrics configuration, and are a good starting point for trying Prometheus with Strimzi. 
 
-If you wish to include xref:con-metrics-kafka-exporter-lag-str[Kafka Exporter] metrics, add `kafkaExporter` configuration to your `Kafka` resource.
-
-IMPORTANT: Kafka Exporter only provides additional metrics related to consumer lag and consumer offsets.
-For regular Kafka metrics, configure Prometheus metrics in the `Kafka` resource.
+This procedure shows how to deploy example Prometheus metrics configuration to the `Kafka` resource.
+The same steps apply when deploying the example files for other resources.
 
 .Procedure
 
@@ -180,17 +179,18 @@ spec:
   # ...
 ----
 
-.Enabling metrics for OAuth 2.0 and OPA 
+.Enabling metrics for OAuth 2.0 
 
-To expose metrics for OAuth 2.0 or OPA, set the `enableMetrics` property to `true` in the appropriate custom resource.
+To expose metrics for OAuth 2.0, set the `enableMetrics` property to `true` in the appropriate custom resource.
 
-OAuth 2.0 metrics:: Enable metrics for Kafka cluster authorization and Kafka listener authentication in the `Kafka` resource.
-You can also enable metrics for OAuth 2.0 authentication in the custom resource of other xref:proc-oauth-kafka-config-{context}[supported components].   
-OPA metrics:: Enable metrics for Kafka cluster authorization in the `Kafka` resource similar to OAuth 2.0. 
+* In the Kafka resource for:
+** Cluster authorization (`oauth` or `keycloak`)
+** Listener authentication (`oauth` only)
+* In the `KafkaBridge`, `KafkaConnect`, or `KafkaMirrorMaker2` resources for `oauth` authentication  
 
 In the following example, metrics are enabled for OAuth 2.0 listener authentication and OAuth 2.0 (`keycloak`) cluster authorization.
 
-.Example cluster configuration with metrics enabled for OAuth 2.0
+.Example configuration with OAuth 2.0 metrics enabled
 [source,yaml,subs="+quotes,attributes"]
 ----
 apiVersion: {KafkaApiVersion}
@@ -219,4 +219,8 @@ spec:
 
 To use OAuth 2.0 metrics with Prometheus, copy the `ConfigMap` configuration from the `oauth-metrics.yaml` file to the same `Kafka` resource configuration file where you enabled metrics for OAuth 2.0 and then apply the configuration.
 
+NOTE: You can also enable metrics for the `type: opa` authorization option in the same way as for OAuth 2.0 authorization.
+However, `type: opa` is deprecated and will be removed in a future release.
+To continue using the Open Policy Agent authorizer, use the `type: custom` authorization configuration.
+
 

documentation/modules/overview/con-security-overview.adoc

@@ -32,7 +32,7 @@ Supported authorization mechanisms:
 +
 * Simple authorization using ACL rules
 * OAuth 2.0 authorization (if you are using OAuth 2.0 token-based authentication)
-* Open Policy Agent (OPA) authorization
+* Open Policy Agent (OPA) authorization (deprecated)
 * Custom authorization (supported by Kafka)
 
 Federal Information Processing Standards (FIPS):: Strimzi is designed to run on FIPS-enabled Kubernetes clusters to ensure data security and system interoperability.

documentation/modules/security/con-securing-client-authorization.adoc

@@ -15,8 +15,7 @@ The simple authorization uses the Kafka Admin API to manage the ACL rules inside
 Whether ACL management in the User Operator is enabled or not depends on your authorization configuration in the Kafka cluster.
 
 * For simple authorization, ACL management is always enabled.
-* For OPA authorization, ACL management is always disabled.
-  Authorization rules are configured in the OPA server.
+* For OPA authorization (deprecated), ACL management is always disabled.
 * For Keycloak authorization, you can manage the ACL rules directly in Keycloak.
   You can also delegate authorization to the simple authorizer as a fallback option in the configuration.
   When delegation to the simple authorizer is enabled, the User Operator will enable management of ACL rules as well.