From f3b080a0a7be63e39e4f173cfc8fa7b9ee446646 Mon Sep 17 00:00:00 2001 From: Ashleigh Brennan Date: Wed, 28 Sep 2022 10:18:15 -0500 Subject: [PATCH] Add kafka sink security config docs --- ...less-kafka-broker-sasl-default-config.adoc | 2 +- modules/serverless-kafka-sasl-channels.adoc | 2 +- modules/serverless-kafka-sasl-source.adoc | 4 +- ...serverless-kafka-sink-security-config.adoc | 91 +++++++++++++++++++ .../admin_guide/serverless-kafka-admin.adoc | 7 ++ 5 files changed, 102 insertions(+), 4 deletions(-) create mode 100644 modules/serverless-kafka-sink-security-config.adoc diff --git a/modules/serverless-kafka-broker-sasl-default-config.adoc b/modules/serverless-kafka-broker-sasl-default-config.adoc index a0b43ecac6..a7be740bb9 100644 --- a/modules/serverless-kafka-broker-sasl-default-config.adoc +++ b/modules/serverless-kafka-broker-sasl-default-config.adoc @@ -6,7 +6,7 @@ [id="serverless-kafka-broker-sasl-default-config_{context}"] = Configuring SASL authentication for Kafka brokers -_Simple Authentication and Security Layer_ (SASL) is used by Apache Kafka for authentication. If you use SASL authentication on your cluster, users must provide credentials to Knative for communicating with the Kafka cluster, otherwise events cannot be produced or consumed. +_Simple Authentication and Security Layer_ (SASL) is used by Apache Kafka for authentication. If you use SASL authentication on your cluster, users must provide credentials to Knative for communicating with the Kafka cluster; otherwise events cannot be produced or consumed. .Prerequisites diff --git a/modules/serverless-kafka-sasl-channels.adoc b/modules/serverless-kafka-sasl-channels.adoc index 8ef1184cee..8137357958 100644 --- a/modules/serverless-kafka-sasl-channels.adoc +++ b/modules/serverless-kafka-sasl-channels.adoc @@ -6,7 +6,7 @@ [id="serverless-kafka-sasl-channels_{context}"] = Configuring SASL authentication for Kafka channels -_Simple Authentication and Security Layer_ (SASL) is used by Apache Kafka for authentication. If you use SASL authentication on your cluster, users must provide credentials to Knative for communicating with the Kafka cluster, otherwise events cannot be produced or consumed. +_Simple Authentication and Security Layer_ (SASL) is used by Apache Kafka for authentication. If you use SASL authentication on your cluster, users must provide credentials to Knative for communicating with the Kafka cluster; otherwise events cannot be produced or consumed. .Prerequisites diff --git a/modules/serverless-kafka-sasl-source.adoc b/modules/serverless-kafka-sasl-source.adoc index f6c3020540..11018a591f 100644 --- a/modules/serverless-kafka-sasl-source.adoc +++ b/modules/serverless-kafka-sasl-source.adoc @@ -6,7 +6,7 @@ [id="serverless-kafka-sasl-source_{context}"] = Configuring SASL authentication for Kafka sources -_Simple Authentication and Security Layer_ (SASL) is used by Apache Kafka for authentication. If you use SASL authentication on your cluster, users must provide credentials to Knative for communicating with the Kafka cluster, otherwise events cannot be produced or consumed. +_Simple Authentication and Security Layer_ (SASL) is used by Apache Kafka for authentication. If you use SASL authentication on your cluster, users must provide credentials to Knative for communicating with the Kafka cluster; otherwise events cannot be produced or consumed. .Prerequisites @@ -53,7 +53,7 @@ spec: secretKeyRef: name: key: password - saslType: + type: secretKeyRef: name: key: saslType diff --git a/modules/serverless-kafka-sink-security-config.adoc b/modules/serverless-kafka-sink-security-config.adoc new file mode 100644 index 0000000000..89d9047bee --- /dev/null +++ b/modules/serverless-kafka-sink-security-config.adoc @@ -0,0 +1,91 @@ +// Module is included in the following assemblies: +// +// * serverless/admin_guide/serverless-kafka-admin.adoc + +:_content-type: PROCEDURE +[id="serverless-kafka-sink-security-config_{context}"] += Configuring security for Kafka sinks + +_Transport Layer Security_ (TLS) is used by Apache Kafka clients and servers to encrypt traffic between Knative and Kafka, as well as for authentication. TLS is the only supported method of traffic encryption for Knative Kafka. + +_Simple Authentication and Security Layer_ (SASL) is used by Apache Kafka for authentication. If you use SASL authentication on your cluster, users must provide credentials to Knative for communicating with the Kafka cluster; otherwise events cannot be produced or consumed. + +.Prerequisites + +* The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` custom resources (CRs) are installed on your {product-title} cluster. +* Kafka sink is enabled in the `KnativeKafka` CR. +* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. +* You have a Kafka cluster CA certificate stored as a `.pem` file. +* You have a Kafka cluster client certificate and a key stored as `.pem` files. +* You have installed the OpenShift (`oc`) CLI. +* You have chosen the SASL mechanism to use, for example, `PLAIN`, `SCRAM-SHA-256`, or `SCRAM-SHA-512`. + +.Procedure + +. Create the certificate files as a secret in the same namespace as your `KafkaSink` object: ++ +[IMPORTANT] +==== +Certificates and keys must be in PEM format. +==== + +** For authentication using SASL without encryption: ++ +[source,terminal] +---- +$ oc create secret -n generic \ + --from-literal=protocol=SASL_PLAINTEXT \ + --from-literal=sasl.mechanism= \ + --from-literal=user= \ + --from-literal=password= +---- + +** For authentication using SASL and encryption using TLS: ++ +[source,terminal] +---- +$ oc create secret -n generic \ + --from-literal=protocol=SASL_SSL \ + --from-literal=sasl.mechanism= \ + --from-file=ca.crt= \ <1> + --from-literal=user= \ + --from-literal=password= +---- +<1> The `ca.crt` can be omitted to use the system's root CA set if you are using a public cloud managed Kafka service, such as Red Hat OpenShift Streams for Apache Kafka. + +** For authentication and encryption using TLS: ++ +[source,terminal] +---- +$ oc create secret -n generic \ + --from-literal=protocol=SSL \ + --from-file=ca.crt= \ <1> + --from-file=user.crt= \ + --from-file=user.key= +---- +<1> The `ca.crt` can be omitted to use the system's root CA set if you are using a public cloud managed Kafka service, such as Red Hat OpenShift Streams for Apache Kafka. + +. Create or modify a `KafkaSink` object and add a reference to your secret in the `auth` spec: ++ +[source,yaml] +---- +apiVersion: eventing.knative.dev/v1alpha1 +kind: KafkaSink +metadata: + name: + namespace: +spec: +... + auth: + secret: + ref: + name: +... +---- + +. Apply the `KafkaSink` object: ++ +[source,terminal] +---- +$ oc apply -f +---- diff --git a/serverless/admin_guide/serverless-kafka-admin.adoc b/serverless/admin_guide/serverless-kafka-admin.adoc index cc43d99604..fe8db5b49d 100644 --- a/serverless/admin_guide/serverless-kafka-admin.adoc +++ b/serverless/admin_guide/serverless-kafka-admin.adoc @@ -42,12 +42,19 @@ Kafka clusters are generally secured by using the TLS or SASL authentication met Red Hat recommends that you enable both SASL and TLS together. ==== +// kafka broker security config include::modules/serverless-kafka-broker-tls-default-config.adoc[leveloffset=+2] include::modules/serverless-kafka-broker-sasl-default-config.adoc[leveloffset=+2] + +// kafka channel security config include::modules/serverless-kafka-tls-channels.adoc[leveloffset=+2] include::modules/serverless-kafka-sasl-channels.adoc[leveloffset=+2] include::modules/serverless-kafka-sasl-source.adoc[leveloffset=+2] +// kafka sink security config +include::modules/serverless-kafka-sink-security-config.adoc[leveloffset=+2] + +// kafka broker general configmap include::modules/serverless-kafka-broker-configmap.adoc[leveloffset=+1] [role="_additional-resources"]