From a7e66471ae679bf7221a9d933712378c9e7bda40 Mon Sep 17 00:00:00 2001 From: Matthias Wessendorf Date: Thu, 10 Dec 2020 16:05:41 +0100 Subject: [PATCH] Adding configuration description for TLS/SASL for the KafkaChannel (#3067) * Adding configuration description for TLS/SASL for the KafkaChannel Signed-off-by: Matthias Wessendorf * Updating based on feedback Signed-off-by: Matthias Wessendorf * :lipstick: a little more context and polishing Signed-off-by: Matthias Wessendorf * Fixing typo Signed-off-by: Matthias Wessendorf --- docs/eventing/samples/kafka/channel/README.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/eventing/samples/kafka/channel/README.md b/docs/eventing/samples/kafka/channel/README.md index f804bda34..d75a3a2e2 100644 --- a/docs/eventing/samples/kafka/channel/README.md +++ b/docs/eventing/samples/kafka/channel/README.md @@ -151,3 +151,73 @@ Now you can see the events in the log of the `ksvc` using the command: ``` kubectl logs --selector='serving.knative.dev/service=broker-kafka-display' -c user-container ``` + +## Authentication against an Apache Kafka + +In production environments it is common that the Apache Kafka cluster is secured using [TLS](http://kafka.apache.org/documentation/#security_ssl) or [SASL](http://kafka.apache.org/documentation/#security_sasl). This section shows how to confiugure the `KafkaChannel` to work against a protected Apache Kafka cluster, with the two supported TLS and SASL authentication methods. + +### TLS authentication + +To use TLS authentication you must create: + +* A CA certificate +* A client certificate and key + +**NOTE:** Kafka channels require these files to be in `.pem` format. If your files are in a different format, you must convert them to `.pem`. + + +1. Create the certificate files as secrets in your chosen namespace: +``` +$ kubectl create secret --namespace generic \ + --from-file=ca.crt=caroot.pem \ + --from-file=user.crt=certificate.pem \ + --from-file=user.key=key.pem + ``` + +*NOTE:* It is important to use the same keys (`ca.crt`, `user.crt` and `user.key`). + +Reference your secret and the namespace of the secret in the `config-kafka` ConfigMap: +``` +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-kafka + namespace: knative-eventing +data: + bootstrapServers: + authSecretName: + authSecretNamespace: + ``` + +### SASL authentication + +To use SASL authentication, you will need the following information: + +* A username and password. +* The type of SASL mechanism you wish to use. For example; `PLAIN`, `SCRAM-SHA-256` or `SCRAM-SHA-512`. + +**NOTE:** It is recommended to also enable TLS. If you enable this, you will also need the `ca.crt` certificate as described in the previous section. + +1. Create the certificate files as secrets in your chosen namespace: +``` +$ kubectl create secret --namespace generic \ + --from-file=ca.crt=caroot.pem \ + --from-literal=password="SecretPassword" \ + --from-literal=saslType="SCRAM-SHA-512" \ + --from-literal=user="my-sasl-user" +``` + +*NOTE:* It is important to use the same keys; `user`, `password` and `saslType`. + +Reference your secret and the namespace of the secret in the `config-kafka` ConfigMap: +``` +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-kafka + namespace: knative-eventing +data: + bootstrapServers: + authSecretName: + authSecretNamespace: +```