Merge pull request #47401 from abrennan89/SRVCOM-1832

abrennan89 · web-flow · commit 587cdef9492f · 2022-07-07T10:00:25.000-05:00
[SRVCOM-1832] Update Serverless abstracts for Jupiter readiness
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -76,7 +76,7 @@ Topics:
 - Name: Installation and update
   Distros: openshift-enterprise,openshift-origin
   File: architecture-installation
-- Name: Red Hat OpenShift Cluster Manager 
+- Name: Red Hat OpenShift Cluster Manager
   Distros: openshift-enterprise
   File: ocm-overview-ocp
 - Name: Control plane architecture
@@ -3506,8 +3506,6 @@ Topics:
     File: serverless-custom-domains
   - Name: Using a custom TLS certificate for domain mapping
     File: serverless-custom-tls-cert-domain-mapping
-  - Name: Security configuration for Knative Kafka
-    File: serverless-kafka-security
 # Functions
 - Name: Functions
   Dir: functions
diff --git a/_topic_maps/_topic_map_osd.yml b/_topic_maps/_topic_map_osd.yml
@@ -313,8 +313,6 @@ Topics:
     File: serverless-custom-domains
   - Name: Using a custom TLS certificate for domain mapping
     File: serverless-custom-tls-cert-domain-mapping
-  - Name: Security configuration for Knative Kafka
-    File: serverless-kafka-security
 - Name: Functions
   Dir: functions
   Topics:
diff --git a/_topic_maps/_topic_map_rosa.yml b/_topic_maps/_topic_map_rosa.yml
@@ -386,14 +386,14 @@ Topics:
     File: serverless-using-brokers
   - Name: Triggers
     File: serverless-triggers
-  - Name: Knative Kafka
+  - Name: Using Knative Kafka
     File: serverless-kafka-developer
 - Name: Administer
   Dir: admin_guide
   Topics:
   - Name: Global configuration
     File: serverless-configuration
-  - Name: Knative Kafka
+  - Name: Configuring Knative Kafka
     File: serverless-kafka-admin
   - Name: Serverless components in the Administrator perspective
     File: serverless-admin-perspective
@@ -424,8 +424,6 @@ Topics:
     File: serverless-custom-domains
   - Name: Using a custom TLS certificate for domain mapping
     File: serverless-custom-tls-cert-domain-mapping
-  - Name: Security configuration for Knative Kafka
-    File: serverless-kafka-security
 - Name: Functions
   Dir: functions
   Topics:
diff --git a/modules/serverless-getting-support.adoc b/modules/serverless-getting-support.adoc
diff --git a/modules/serverless-kafka-broker-sasl-default-config.adoc b/modules/serverless-kafka-broker-sasl-default-config.adoc
@@ -6,33 +6,18 @@
 [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. You can set up SASL for Kafka brokers by modifying the `KnativeKafka` custom resource (CR).
+_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
 
-// OCP
-ifdef::openshift-enterprise[]
-* You have cluster administrator permissions on {product-title}.
-endif::[]
-
-// OSD and ROSA
-ifdef::openshift-dedicated,openshift-rosa[]
 * You have cluster or dedicated administrator permissions on {product-title}.
-endif::[]
-
-// universal
 * The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` CR are installed on your {product-title} cluster.
 * 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 username and password for a Kafka cluster.
 * You have chosen the SASL mechanism to use, for example `PLAIN`, `SCRAM-SHA-256`, or `SCRAM-SHA-512`.
 * If TLS is enabled, you also need the `ca.crt` certificate file for the Kafka cluster.
 * Install the OpenShift CLI (`oc`).
 
-[NOTE]
-====
-It is recommended to enable TLS in addition to SASL.
-====
-
 .Procedure
 
 . Create the certificate files as a secret in the `knative-eventing` namespace:
@@ -46,11 +31,17 @@ $ oc create secret -n knative-eventing generic <secret_name> \
   --from-literal=password="SecretPassword" \
   --from-literal=user="my-sasl-user"
 ----
+** Use the key names `ca.crt`, `password`, and `sasl.mechanism`. Do not change them.
+** If you want to use SASL with public CA certificates, you must use the `tls.enabled=true` flag, rather than the `ca.crt` argument, when creating the secret. For example:
 +
-[IMPORTANT]
-====
-Use the key names `ca.crt`, `password`, and `sasl.mechanism`. Do not change them.
-====
+[source,terminal]
+----
+$ oc create secret -n <namespace> generic <kafka_auth_secret> \
+  --from-literal=tls.enabled=true \
+  --from-literal=password="SecretPassword" \
+  --from-literal=saslType="SCRAM-SHA-512" \
+  --from-literal=user="my-sasl-user"
+----
 
 . Edit the `KnativeKafka` CR and add a reference to your secret in the `broker` spec:
 +
diff --git a/modules/serverless-kafka-broker-tls-default-config.adoc b/modules/serverless-kafka-broker-tls-default-config.adoc
@@ -6,21 +6,11 @@
 [id="serverless-kafka-broker-tls-default-config_{context}"]
 = Configuring TLS authentication for Kafka brokers
 
-_Transport Layer Security_ (TLS) is used by Apache Kafka clients and servers to encrypt traffic between Knative and Kafka, as well as for authentication. You can set up TLS for Kafka brokers by modifying the `KnativeKafka` custom resource (CR).
+_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.
 
 .Prerequisites
 
-// OCP
-ifdef::openshift-enterprise[]
-* You have cluster administrator permissions on {product-title}.
-endif::[]
-
-// OSD and ROSA
-ifdef::openshift-dedicated,openshift-rosa[]
 * You have cluster or dedicated administrator permissions on {product-title}.
-endif::[]
-
-// universal
 * The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` CR are installed on your {product-title} cluster.
 * 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.
diff --git a/modules/serverless-kafka-sasl-channels.adoc b/modules/serverless-kafka-sasl-channels.adoc
@@ -1,42 +1,46 @@
 // Module included in the following assemblies:
 //
-// * serverless/security/serverless-kafka-security.adoc
+// * serverless/admin_guide/serverless-kafka-admin.adoc
 
 :_content-type: PROCEDURE
-[id="serverless-kafka-sasl_{context}"]
-= Configuring SASL authentication
+[id="serverless-kafka-sasl-channels_{context}"]
+= Configuring SASL authentication for Kafka channels
 
-You can use the following procedure to configure SASL authentication for a Kafka channel.
+_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
 
-* You have a username and password for the Kafka cluster.
+* You have cluster or dedicated administrator permissions on {product-title}.
+* The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` CR are installed on your {product-title} cluster.
+* 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 username and password for a Kafka cluster.
 * You have chosen the SASL mechanism to use, for example `PLAIN`, `SCRAM-SHA-256`, or `SCRAM-SHA-512`.
 * If TLS is enabled, you also need the `ca.crt` certificate file for the Kafka cluster.
 * Install the OpenShift CLI (`oc`).
 
-[NOTE]
-====
-Red Hat recommends to enable TLS in addition to SASL.
-====
-
 .Procedure
 
 . Create the certificate files as secrets in your chosen namespace:
 +
 [source,terminal]
 ----
-$ oc create secret --namespace <namespace> generic <kafka_auth_secret> \
+$ oc create secret -n <namespace> generic <kafka_auth_secret> \
   --from-file=ca.crt=caroot.pem \
   --from-literal=password="SecretPassword" \
   --from-literal=saslType="SCRAM-SHA-512" \
   --from-literal=user="my-sasl-user"
 ----
+** Use the key names `ca.crt`, `password`, and `sasl.mechanism`. Do not change them.
+** If you want to use SASL with public CA certificates, you must use the `tls.enabled=true` flag, rather than the `ca.crt` argument, when creating the secret. For example:
 +
-[IMPORTANT]
-====
-Use the key names `ca.crt`, `password`, and `saslType`. Do not change them.
-====
+[source,terminal]
+----
+$ oc create secret -n <namespace> generic <kafka_auth_secret> \
+  --from-literal=tls.enabled=true \
+  --from-literal=password="SecretPassword" \
+  --from-literal=saslType="SCRAM-SHA-512" \
+  --from-literal=user="my-sasl-user"
+----
 
 . Start editing the `KnativeKafka` custom resource:
 +
diff --git a/modules/serverless-kafka-sasl-public-certs.adoc b/modules/serverless-kafka-sasl-public-certs.adoc
diff --git a/modules/serverless-kafka-tls-channels.adoc b/modules/serverless-kafka-tls-channels.adoc
@@ -1,18 +1,21 @@
 // Module included in the following assemblies:
 //
-// * serverless/security/serverless-kafka-security.adoc
+// * serverless/admin_guide/serverless-kafka-admin.adoc
 
 :_content-type: PROCEDURE
-[id="serverless-configuring-tls-authentication-against-an-apache-kafka_{context}"]
-= Configuring TLS authentication
+[id="serverless-kafka-tls-channels_{context}"]
+= Configuring TLS authentication for Kafka channels
 
-You can use the following procedure to configure TLS authentication for a Kafka channel.
+_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.
 
 .Prerequisites
 
+* You have cluster or dedicated administrator permissions on {product-title}.
+* The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` CR are installed on your {product-title} cluster.
+* 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.
-* Install the OpenShift CLI (`oc`).
+* Install the OpenShift (`oc`) CLI.
 
 .Procedure
 
diff --git a/modules/support-knowledgebase-about.adoc b/modules/support-knowledgebase-about.adoc
@@ -3,6 +3,7 @@
 // * support/getting-support.adoc
 // * support/index.adoc
 // * service_mesh/v2x/ossm-troubleshooting-istio.adoc
+// * serverless/serverless-support.adoc
 
 :_content-type: CONCEPT
 [id="support-knowledgebase-about_{context}"]
diff --git a/modules/support-knowledgebase-search.adoc b/modules/support-knowledgebase-search.adoc
@@ -3,6 +3,7 @@
 // * support/getting-support.adoc
 // * support/index.adoc
 // * service_mesh/v2x/ossm-troubleshooting-istio.adoc
+// * serverless/serverless-support.adoc
 
 :_content-type: PROCEDURE
 [id="support-knowledgebase-search_{context}"]
diff --git a/modules/support-submitting-a-case.adoc b/modules/support-submitting-a-case.adoc
@@ -3,6 +3,7 @@
 // * support/getting-support.adoc
 // * support/index.adoc
 // * service_mesh/v2x/ossm-troubleshooting-istio.adoc
+// * serverless/serverless-support.adoc
 
 :_content-type: PROCEDURE
 [id="support-submitting-a-case_{context}"]
@@ -19,12 +20,12 @@
 
 . Log in to the link:http://access.redhat.com[Red Hat Customer Portal] and select *SUPPORT CASES* -> *Open a case*.
 
-. Select the appropriate category for your issue (such as *Defect / Bug*), product (*{product-title}*), and product version 
+. Select the appropriate category for your issue (such as *Defect / Bug*), product (*{product-title}*), and product version
 ifndef::openshift-dedicated[]
-(*{product-version}*, 
+(*{product-version}*,
 endif::openshift-dedicated[]
 ifdef::openshift-dedicated[]
-(*{product-title}*, 
+(*{product-title}*,
 endif::openshift-dedicated[]
 if this is not already autofilled).
 
diff --git a/serverless/admin_guide/serverless-kafka-admin.adoc b/serverless/admin_guide/serverless-kafka-admin.adoc
@@ -32,10 +32,23 @@ The `KnativeKafka` CR provides users with additional options, such as:
 
 include::modules/serverless-install-kafka-odc.adoc[leveloffset=+1]
 
-include::modules/serverless-kafka-broker-tls-default-config.adoc[leveloffset=+1]
-include::modules/serverless-kafka-broker-sasl-default-config.adoc[leveloffset=+1]
+[id="serverless-kafka-admin-security"]
+== Security configuration for Knative Kafka
+
+Kafka clusters are generally secured by using the TLS or SASL authentication methods. You can configure a Kafka broker or channel to work against a protected Red Hat AMQ Streams cluster by using TLS or SASL.
+
+[NOTE]
+====
+Red Hat recommends that you enable both SASL and TLS together.
+====
+
+include::modules/serverless-kafka-broker-tls-default-config.adoc[leveloffset=+2]
+include::modules/serverless-kafka-broker-sasl-default-config.adoc[leveloffset=+2]
+include::modules/serverless-kafka-tls-channels.adoc[leveloffset=+2]
+include::modules/serverless-kafka-sasl-channels.adoc[leveloffset=+2]
 
 [id="additional-resources_serverless-kafka-admin"]
 [role="_additional-resources"]
 == Additional resources
 * link:https://access.redhat.com/documentation/en-us/red_hat_amq/7.6/html/amq_streams_on_openshift_overview/kafka-concepts_str#kafka-concepts-key_str[Red Hat AMQ Streams documentation]
+* link:https://access.redhat.com/documentation/en-us/red_hat_amq/7.5/html-single/using_amq_streams_on_rhel/index#assembly-kafka-encryption-and-authentication-str[TLS and SASL on Kafka]
diff --git a/serverless/security/serverless-kafka-security.adoc b/serverless/security/serverless-kafka-security.adoc
diff --git a/serverless/serverless-support.adoc b/serverless/serverless-support.adoc
@@ -6,20 +6,24 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-include::modules/serverless-getting-support.adoc[leveloffset=+1]
+If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at http://access.redhat.com. You can use the Red Hat Customer Portal to search or browse through the Red Hat Knowledgebase of technical support articles about Red Hat products. You can also submit a support case to Red Hat Global Support Services (GSS), or access other product documentation.
 
-[id="serverless-support-gather-info"]
-== Gathering diagnostic information for support
+If you have a suggestion for improving this guide or have found an error, you can submit a Bugzilla report at http://bugzilla.redhat.com against *Product* for the *Documentation* component. Provide specific details, such as the section number, guide name, and {ServerlessProductName} version so we can easily locate the content.
+// TODO: Update once https://issues.redhat.com/browse/OSDOCS-3730 is done to update this to Jira
+
+// Generic help topics
+ifdef::openshift-enterprise,openshift-dedicated[]
 
-When opening a support case, it is helpful to provide debugging
-information about your cluster to Red Hat Support.
+include::modules/support-knowledgebase-about.adoc[leveloffset=+1]
+include::modules/support-knowledgebase-search.adoc[leveloffset=+1]
+include::modules/support-submitting-a-case.adoc[leveloffset=+1]
 
-The `must-gather` tool enables you to collect diagnostic information about your
-{product-title} cluster, including data related to
-{ServerlessProductName}.
+endif::openshift-enterprise,openshift-dedicated[]
+
+[id="serverless-support-gather-info"]
+== Gathering diagnostic information for support
 
-For prompt support, supply diagnostic information for both {product-title}
-and {ServerlessProductName}.
+When you open a support case, it is helpful to provide debugging information about your cluster to Red Hat Support. The `must-gather` tool enables you to collect diagnostic information about your {product-title} cluster, including data related to {ServerlessProductName}. For prompt support, supply diagnostic information for both {product-title} and {ServerlessProductName}.
 
 include::modules/about-must-gather.adoc[leveloffset=+2]
 include::modules/serverless-about-collecting-data.adoc[leveloffset=+2]
