Extend the automatic discovery of bootstrap address feature to handle TLS listeners

proposals/010-automatic-discovery-of-strimzi-bootstrap-server-tls.md

@@ -0,0 +1,115 @@
+# Extend the automatic discovery of bootstrap address feature to handle TLS listeners
+
+This proposal aims to extend the automatic discovery of bootstrap address feature to handle TLS listeners where Strimzi is configured to use its own generated certificates. This will reduce manual configuration, create a tighter, more declarative integration with the Strimzi ecosystem. The use cases where brokers are using certificates signed by a public CA or a private-CA are not impacted by this proposal.
+
+## Current situation
+
+Currently, with the integration of automatic discovery of bootstrap address of a Strimzi Kafka cluster [feature](https://github.com/kroxylicious/kroxylicious/pull/2693), we are able to retrieve the bootstrap address of the plain listeners by using `strimziKafkaRef` section in the KafkaService, but currently it doesn't support `tls`. When dealing with tls protected Strimzi Kafka cluster, if Strimzi is signing the broker certificates using its own certificate authority, the users still need to use the old approach of manually setting the bootstrap address and then using the `trustAnchorRef` field to configure trust for the Kafka cluster.
+
+## Motivation
+
+The current process is manual and any errors while configuring TLS in the Kroxylicious operator can result in the operator not working properly.
+Adding this feature help us get rid of the manual configuration and would also increase the integration of the Strimzi ecosystem with Kroxylicious.
+
+## Proposal
+
+This proposal aims to extend the already existing boostrap address discovery feature for plain listeners for TLS.
+If a user uses the `strimziKafkaRef` field in their Kafka CR, then the Kroxylicious operator should be able to proxy it without needing to explicitly configure trust.
+
+### Algorithm
+
+#### Initial process
+
+The initial process will be similar to what we have for discovery of bootstrap address the plain listeners:
+
+1. The user will make use of the `strimziKafkaRef` field to make use of the automated bootstrap discovery process.
+2. Then they should set the `listener` name and mention the `group`, `kind`, `name`, `namespace` of the cluster.
+3. The users will also set `trustStrimziCaCertificate` field to `true` to signal that they want to trust the certificates generated by Strimzi.
+
+   Example of the KafkaService CR:
+    ```yaml
+    apiVersion: kroxylicious.io/v1alpha1
+    kind: KafkaService
+    metadata:
+      name: my-cluster
+      namespace: my-proxy
+    spec:
+      strimziKafkaRef:
+        group: kafka.strimzi.io
+        kind: Kafka
+        name: my-cluster         # Name of the Kafka CR
+        namespace: kafka        # Namespace of the Kafka CR
+        listenerName: tls       # The specific listener to use from the Kafka CR status
+        trustStrimziCaCertificate: false    # false by default. Should be used when using TLS configuration
+    ```
+
+4. The operator would then look at the specified Strimzi Kafka resource, find the listener named `tls` in its status, and extract the `bootstrapServers` from there and add it to `bootstrapServers` field in the `KafkaService` status.
+
+5. Once the above steps are complete, we can then start to look for the Strimzi generated certificate and key.
+
+#### Process for looking up for certificate and key.
+
+It is possible even when using Strimzi cluster, the users can provide certificate signed by public CA (Verisign etc), then we (as a client) don't need a trust anchor. In these case we should be using system trust anchor. Taking the trust anchor from Strimzi in this situation is harmful. 
+
+To tackle this issue, we can create a `spec.strimziKafkaRef.trustStrimziCaCertificate` flag which will control whether we want to retrieve the trust anchor from Strimzi or we want the user to configure the trust anchor themselves.
+
+We will be making use of the below algorithm to discover the cert and key for the trust.
+
+```text
+if `spec.tls.trustAnchorRef` is defined:
+    use ref to the trust anchor
+else if spec.strimziKafkaRef.trustStrimziCaCertificate true:  
+    use ref to the cert from <cluster_name>-cluster-ca-cert
+end if
+```
+
+In case the `spec.strimziKafkaRef.trustStrimziCaCertificate` is set to true, then it means that we can trust the certificate generated by Strimzi, and we will refer to `<cluster_name>-cluster-ca-cert` generated by Strimzi.
+In case the user plans to use their own CA (private/corporate), then they should use the `spec.tls.trustAnchorRef` field.
+
+The below table covers all the possible scenarios on which certificates will be used based on the `spec.strimziKafkaRef.trustStrimziCaCertificate` and `spec.tls.trustAnchorRef` configuration.
+
+| Use case                        | if spec.tls.trustAnchorRef? | spec.strimziKafkaRef.trustStrimziCaCertificate? | Outcome                                                                                               |
+|---------------------------------|-----------------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------|
+| private CA                      | provided                    | value ignored                                   | The trust anchors provided by `spec.tls.trustAnchorRef` will be used  when connecting to the Brokers. |
+| Strimzi issued CA (development) | not provided                | true                                            | Trust anchor generated Strimzi will be used when connecting to the Brokers.                           |
+| public CA                       | not provided                | value ignored                                   | Trust anchors provided by the JVM running the Proxy will be used  when connecting to the Brokers.     |
+
+Once the certificate and key lookup is complete, the status of the KafkaService will reflect the trust anchor to be used by the proxy when connecting to the brokers.
+
+```yaml
+kind: KafkaService
+apiVersion: kroxylicious.io/v1alpha1
+metadata:
+  name: fooref
+  namespace: proxy-ns
+  generation: 6
+spec:
+   strimziKafkaRef:
+     group: kafka.strimzi.io
+     kind: Kafka
+     name: my-cluster        
+     namespace: kafka     
+     listenerName: tls
+     trustStrimziCaCertificate: true
+status:
+   bootstrapServers: my-cluster-kafka-bootstrap.kafka.svc.cluster.local:9093
+   trustAnchorRef:
+      name: <Name of the cert>
+      kind: <Kind of the cert>
+      key: <Key of the cert>
+```
+
+#### What happens if the secret/key doesn't exist
+
+The `KafkaProxyReconciler` will refer to the `status.trustAnchorRef` section of the `KafkaService` CR.
+In case the operator is not able to find the expected secret, then the `KafkaServiceReconciler` would generate a condition based on `ReferencedResourceNotReconciled` exception with the help of the `KafkaServiceStatusFactory` and add it to status of the `KafkaService` CR.
+In case the key doesn't exist, then the `KafkaServiceReconciler` would generate a condition based upon the `InvalidReferencedResource` exception with the help of the `KafkaServiceStatusFactory` and add it to the status of the `KafkaService` CR.
+
+## Affected/not affected projects
+
+The `kroxylicious-operator` module will be affected by the logic changes required for the above feature
+
+## Compatibility
+
+This feature will not affect backwards compatibility. 
+This feature is compatible with the [Strimzi certificate manager](https://github.com/strimzi/proposals/pull/135) changes.