Add ADR on TLS authentication

modules/contributor/pages/adr/ADR016-tls-authentication.adoc

@@ -0,0 +1,287 @@
+= TLS authentication
+Sebastian Bernauer <sebastian.bernauer@stackable.de>
+v0.1, 2022-05-02
+:status: accepted
+
+* Status: {status}
+* Deciders:
+** Malte Sander
+** Sebastian Bernauer
+** Sönke Liebau
+** Teo Klestrup Röijezon
+* Date: 2022-05-04
+
+Technical Story: https://github.com/stackabletech/zookeeper-operator/issues/466
+
+== Context and Problem Statement
+
+Our products use TLS to encrypt network traffic and/or to authenticate themselves and their clients.
+We want to define a common way - across all the products - to configure these mechanisms.
+
+== Decision Drivers
+* Must support using no TLS usage, TLS only for encryption and TLS for encryption and authentication
+* Should fit into out existing authentication concept from xref:adr/ADR013-user_authentication_for_products.adoc[]
+* Should be easy to understand and use for the user
+
+== Considered Options
+
+* Handle TLS as special case
+* Extend `AuthenticationClass` to support TLS
+* Split server-side and client-side authentication into separate config sections
+
+== Decision Outcome
+
+Chosen option: "Split server-side and client-side authentication into separate config sections", because separating them allowed us to model the underlying structs the best way.
+
+== Pros and Cons of the Options
+
+=== Handle TLS as special case
+We don't support TLS inside `AuthenticationClass`.
+We need a new `tlsConfig` attribute on every product CRD.
+An implementation could look something like this:
+
+[source,yaml]
+----
+---
+apiVersion: zookeeper.stackable.tech/v1alpha1
+kind: ZookeeperCluster
+metadata:
+  name: ssl-zk
+spec:
+  config:
+    tlsConfiguration: # optional
+      quorum: # Communication between between different Zookeeper nodes
+        tls: # commons tls config
+          verification:
+              none: {}
+              # OR
+              server:
+                caCert:
+                    webPki: {}
+                    # OR
+                    secretClass: tls # Reference to SecretClass below
+              # OR
+              mutual:
+                certSecretClass: tls # Reference to SecretClass below
+      clients: # Communication between Zookeeper clients and Zookeeper nodes
+        tls: # commons tls config
+          verification:
+              none: {}
+              # OR
+              server:
+                caCert:
+                    webPki: {}
+                    # OR
+                    secretClass: tls # Reference to SecretClass below
+              # OR
+              mutual:
+                certSecretClass: tls # Reference to SecretClass below
+  servers:
+    roleGroups:
+      primary:
+        replicas: 2
+        config:
+          myidOffset: 10
+      secondary:
+        replicas: 1
+        config:
+          myidOffset: 20
+  version: 3.8.0
+  stopped: false
+---
+apiVersion: secrets.stackable.tech/v1alpha1
+kind: SecretClass
+metadata:
+  name: tls
+spec:
+  backend:
+    autoTls:
+      ca:
+        secret:
+          name: secret-provisioner-tls-ca
+          namespace: default
+        autoGenerate: true
+----
+
+* Good, because simple (no indirection through `AuthenticationClass` object)
+* Bad, because TLS is a special case and does not fit in our `AuthenticationClass` mechanism.
+
+=== Extend `AuthenticationClass` to support TLS
+
+We already have a common `AuthenticationClass` structure discussed in xref:adr/ADR013-user_authentication_for_products.adoc[]
+This option extends the `AuthenticationClass` so that it also support TLS authentication.
+
+[source,yaml]
+----
+---
+apiVersion: zookeeper.stackable.tech/v1alpha1
+kind: ZookeeperCluster
+metadata:
+  name: ssl-zk
+spec:
+  config:
+    tlsAuthenticationConfig:
+      quorum:
+        authenticationClass: zookeeper-tls-mutual
+      clients:
+        authenticationClass: zookeeper-tls
+  servers:
+    roleGroups:
+      primary:
+        replicas: 2
+        config:
+          myidOffset: 10
+      secondary:
+        replicas: 1
+        config:
+          myidOffset: 20
+  version: 3.8.0
+  stopped: false
+---
+apiVersion: authentication.stackable.tech/v1alpha1
+kind: AuthenticationClass
+metadata:
+  name: zookeeper-tls-mutual
+spec:
+  provider:
+    tls:
+      verification:
+          none: {}
+          # OR
+          server:
+            caCert:
+                webPki: {}
+                # OR
+                secretClass: tls # Reference to SecretClass below
+          # OR
+          mutual:
+          certSecretClass: tls # Reference to SecretClass below
+---
+apiVersion: authentication.stackable.tech/v1alpha1
+kind: AuthenticationClass
+metadata:
+  name: zookeeper-tls
+spec:
+  provider:
+    tls:
+      verification:
+          none: {}
+          # OR
+          server:
+            caCert:
+                webPki: {}
+                # OR
+                secretClass: tls # Reference to SecretClass below
+          # OR
+          mutual:
+          certSecretClass: tls # Reference to SecretClass below
+      verification:
+        mutual:
+          caCert:
+            secretClass: tls # Reference to SecretClass below
+---
+apiVersion: secrets.stackable.tech/v1alpha1
+kind: SecretClass
+metadata:
+  name: tls
+spec:
+  backend:
+    autoTls:
+      ca:
+        secret:
+          name: secret-provisioner-tls-ca
+          namespace: default
+        autoGenerate: true
+----
+
+* Good, because TLS is handled via the generic `AuthenticationClass` mechanism.
+* Bad, because an `AuthenticationClass` can express: Don't do any authentication at all
+
+== Split server-side and client-side authentication into separate config sections
+
+[source,yaml]
+----
+---
+apiVersion: zookeeper.stackable.tech/v1alpha1
+kind: ZookeeperCluster
+metadata:
+  name: ssl-zk
+spec:
+  config:
+    tls: # optional, defaults to "secretClass: tls"
+      secretClass: tls # enables encryption and server verification
+    clientAuthentication: # optional, if we should authn the clients via TLS
+      authenticationClass: zookeeper-tls
+    # would probably just be left as default in the vast majority of clusters
+    # Use mutual verification between Zookeeper Nodes
+    # mandatory
+    quorumTlsSecretClass: tls
+  servers:
+    roleGroups:
+      primary:
+        replicas: 2
+        config:
+          myidOffset: 10
+      secondary:
+        replicas: 1
+        config:
+          myidOffset: 20
+  version: 3.8.0
+  stopped: false
+---
+apiVersion: authentication.stackable.tech/v1alpha1
+kind: AuthenticationClass
+metadata:
+  name: zookeeper-tls
+spec:
+  provider:
+    # triggers TLS config to also be used for client authn
+    tls: {}
+    # OR...
+    tls:
+      # overrides secretclass used for provisioning client certs
+      clientCertSecretClass: tls-client
+    # OR...
+    # TLS is still used for server authn, but another
+    # method is used for client authn
+    ldap: ldapStuff{...}
+---
+apiVersion: secrets.stackable.tech/v1alpha1
+kind: SecretClass
+metadata:
+  name: tls
+spec:
+  backend:
+    autoTls:
+      ca:
+        secret:
+          name: secret-provisioner-tls-ca
+          namespace: default
+        autoGenerate: true
+----
+
+As a recap:
+This is how our products connect to TLS-secured services outside of the Stackable Cluster (e.g. Superset to LDAP).
+Mutual verification is not supported this way, as client-side authentication is handled via `AuthenticationClass`.
+[source,yaml]
+----
+---
+[ProductCRD...]
+  tls:
+    verification:
+      none: {}
+      # OR
+      server:
+        caCert:
+          webPki: {}
+          # OR
+          secretClass: tls # Reference to a SecretClass providing the ca.crt
+----
+
+image::adr/16_option3.png[]
+
+* Good, because TLS is handled via the generic `AuthenticationClass` mechanism.
+* Good, because clients don't need to know/understand `AuthenticationClass` objects. They only read the Discovery `ConfigMap` and the contained SecretClasses.
+* Bad, because it's more complicated because of the indirection via `AuthenticationClass`.
+* Bad, because the client operator needs to read the Discovery `ConfigMap` rather than simply mounting it into the client product.
+* Bad, because doing so external clients (outside of Stackable) must need to take more effort to connect to Stackable services e.g. retrieve ca cert from `SecretClass`.

modules/contributor/pages/adr/drafts/_template.adoc

@@ -1,6 +1,6 @@
 = [short title of solved problem and solution]
 Doc Writer <doc.writer@asciidoctor.org>
-v0.1, dd.mm.yyyy
+v0.1, YYYY-MM-DD
 :status: [draft | rejected | accepted | deprecated | … | superseded by link:0005-example.md[ADR-0005]]
 
 * Status: {status}

modules/contributor/partials/current_adrs.adoc

@@ -11,4 +11,5 @@
 **** xref:adr/ADR012-authn_token_management.adoc[]
 **** xref:adr/ADR013-user_authentication_for_products.adoc[]
 **** xref:adr/ARD014-using_values_from_configmaps.adoc[]
-**** xref:adr/ADR015_definition_of_s3_objects.adoc[]
+**** xref:adr/ADR015_definition_of_s3_objects.adoc[]
+**** xref:adr/ADR016-tls-authentication.adoc[]