docs: create kafka instance settings guide and in-app help content (#553

)

docs/kafka/kafka-instance-settings/README.adoc

@@ -0,0 +1,156 @@
+////
+START GENERATED ATTRIBUTES
+WARNING: This content is generated by running npm --prefix .build run generate:attributes
+////
+
+//All OpenShift Application Services
+:org-name: Application Services
+:product-long-rhoas: OpenShift Application Services
+:community:
+:imagesdir: ./images
+:property-file-name: app-services.properties
+:samples-git-repo: https://github.com/redhat-developer/app-services-guides
+:base-url: https://github.com/redhat-developer/app-services-guides/tree/main/docs/
+:sso-token-url: https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
+:cloud-console-url: https://console.redhat.com/
+:service-accounts-url: https://console.redhat.com/application-services/service-accounts
+
+//OpenShift Application Services CLI
+:base-url-cli: https://github.com/redhat-developer/app-services-cli/tree/main/docs/
+:command-ref-url-cli: commands
+:installation-guide-url-cli: rhoas/rhoas-cli-installation/README.adoc
+:service-contexts-url-cli: rhoas/rhoas-service-contexts/README.adoc
+
+//OpenShift Streams for Apache Kafka
+:product-long-kafka: OpenShift Streams for Apache Kafka
+:product-kafka: Streams for Apache Kafka
+:product-version-kafka: 1
+:service-url-kafka: https://console.redhat.com/application-services/streams/
+:getting-started-url-kafka: kafka/getting-started-kafka/README.adoc
+:kafka-bin-scripts-url-kafka: kafka/kafka-bin-scripts-kafka/README.adoc
+:kafkacat-url-kafka: kafka/kcat-kafka/README.adoc
+:quarkus-url-kafka: kafka/quarkus-kafka/README.adoc
+:nodejs-url-kafka: kafka/nodejs-kafka/README.adoc
+:getting-started-rhoas-cli-url-kafka: kafka/rhoas-cli-getting-started-kafka/README.adoc
+:topic-config-url-kafka: kafka/topic-configuration-kafka/README.adoc
+:consumer-config-url-kafka: kafka/consumer-configuration-kafka/README.adoc
+:access-mgmt-url-kafka: kafka/access-mgmt-kafka/README.adoc
+:metrics-monitoring-url-kafka: kafka/metrics-monitoring-kafka/README.adoc
+:service-binding-url-kafka: kafka/service-binding-kafka/README.adoc
+:message-browsing-url-kafka: kafka/message-browsing-kafka/README.adoc
+
+//OpenShift Service Registry
+:product-long-registry: OpenShift Service Registry
+:product-registry: Service Registry
+:registry: Service Registry
+:product-version-registry: 1
+:service-url-registry: https://console.redhat.com/application-services/service-registry/
+:getting-started-url-registry: registry/getting-started-registry/README.adoc
+:quarkus-url-registry: registry/quarkus-registry/README.adoc
+:getting-started-rhoas-cli-url-registry: registry/rhoas-cli-getting-started-registry/README.adoc
+:access-mgmt-url-registry: registry/access-mgmt-registry/README.adoc
+:content-rules-registry: https://access.redhat.com/documentation/en-us/red_hat_openshift_service_registry/1/guide/9b0fdf14-f0d6-4d7f-8637-3ac9e2069817[Supported Service Registry content and rules]
+:service-binding-url-registry: registry/service-binding-registry/README.adoc
+
+//OpenShift Connectors
+:connectors: Connectors
+:product-long-connectors: OpenShift Connectors
+:product-connectors: Connectors
+:product-version-connectors: 1
+:service-url-connectors: https://console.redhat.com/application-services/connectors
+:getting-started-url-connectors: connectors/getting-started-connectors/README.adoc
+:getting-started-rhoas-cli-url-connectors: connectors/rhoas-cli-getting-started-connectors/README.adoc
+
+//OpenShift API Designer
+:product-long-api-designer: OpenShift API Designer
+:product-api-designer: API Designer
+:product-version-api-designer: 1
+:service-url-api-designer: https://console.redhat.com/application-services/api-designer/
+:getting-started-url-api-designer: api-designer/getting-started-api-designer/README.adoc
+
+//OpenShift API Management
+:product-long-api-management: OpenShift API Management
+:product-api-management: API Management
+:product-version-api-management: 1
+:service-url-api-management: https://console.redhat.com/application-services/api-management/
+
+////
+END GENERATED ATTRIBUTES
+////
+
+[id="chap-configuring-kafka-instance-settings"]
+= Configuring Kafka instance settings in {product-long-kafka}
+ifdef::context[:parent-context: {context}]
+:context: configuring-kafka-instance-settings
+
+// Purpose statement for the assembly
+[role="_abstract"]
+--
+As a developer of applications and services, you can review and modify settings for your Kafka instances. By modifying these settings, you can configure your Kafka instances to suit your particular environment.
+--
+
+
+[id="proc-editing-kafka-instance-settings_{context}"]
+== Reviewing and editing Kafka instance settings in {product-kafka}
+
+[role="_abstract"]
+Use the {product-long-kafka} web console to review and adjust settings for a Kafka instance.
+
+As an alternative to using the {product-kafka} web console, you can use the `rhoas` command-line interface (CLI) to update certain Kafka instance settings, as shown in the following example command:
+
+.Example CLI command to disable connection reauthentication
+[source]
+----
+rhoas kafka update --reauthentication false
+----
+
+For a list of Kafka instance settings that you can update using the CLI, see the `rhoas kafka update` entry in the {base-url-cli}{command-ref-url-cli}[CLI command reference (rhoas)^].
+
+.Prerequisites
+* You have created a Kafka instance. To learn how to do this, see {base-url}{getting-started-url-kafka}[Getting started with {product-long-kafka}^].
+
+.Procedure
+. In the {product-kafka} {service-url-kafka}[web console^], click *Kafka Instances* and select a Kafka instance.
+. Select the *Settings* tab.
+. Adjust any of the settings as needed.
+
+[role="_additional-resources"]
+.Additional resources
+* {base-url}{getting-started-url-kafka}[Getting started with {product-long-kafka}^]
+* {base-url}{getting-started-rhoas-cli-url-kafka}[Getting started with the rhoas CLI for OpenShift Streams for Apache Kafka^]
+* {base-url-cli}{command-ref-url-cli}[CLI command reference (rhoas)^]
+
+
+[id="ref-kafka-instance-settings_{context}"]
+== Kafka instance settings in {product-kafka}
+
+[role="_abstract"]
+You can edit the following Kafka instance settings in {product-long-kafka}.
+
+Connection re-authentication::
++
+--
+When a client connects to a Kafka instance, the session lasts for five minutes. 
+At that point, the client must reauthenticate to stay connected.
+Many Kafka clients automatically reauthenticate to remain connected,
+but some Kafka clients do not.
+
+If you use a Kafka client that does not support connection reauthentication,
+the client is disconnected when the five-minute session expires.
+To prevent the client from being disconnected every five minutes,
+disable the `Connection re-authentication` setting.
+
+Before disabling connection re-authentication,
+you should be aware of the security risks.
+If you disable connection re-authentication,
+and then an attacker obtains credentials to your Kafka instance,
+they will be able to stay connected indefinitely.
+Deactivating the user account or service account will not close the connections that the attacker has opened.
+In this scenario, you would need to add Access Control List rules (ACLs) to prevent the unauthorized connections from performing any operations
+(see {base-url}{access-mgmt-url-kafka}[Managing account access in OpenShift Streams for Apache Kafka^]).
+ifndef::community[]
+You could also contact Red Hat Support for assistance.
+endif::[]
+
+NOTE: Disabling connection re-authentication will restart your Kafka instance.
+--

docs/kafka/kafka-instance-settings/kafka-instance-settings.yml

@@ -0,0 +1,24 @@
+# Tags to be kept empty for now. Tags will specify where in the app descriptions will be available.
+# Titles are "dictionary" articles titles.
+# Links to be external only. We don't know yet whether referencing to other side panels will be supported but referencing to in-depth docs is expected to be supported.
+
+- name: kafka-connection-reauthentication
+  tags:
+  title: Connection re-authentication
+  content: |-
+    When a client connects to a Kafka instance, the session lasts for five minutes. At that point, the client must reauthenticate to stay connected. Many Kafka clients automatically reauthenticate to remain connected, but some Kafka clients do not.
+
+    If you use a Kafka client that does not support connection reauthentication, the client is disconnected when the five-minute session expires. To prevent the client from being disconnected every five minutes, disable the **Connection re-authentication** setting.
+
+    Before disabling connection re-authentication, you should be aware of the security risks. If you disable connection re-authentication, and then an attacker obtains credentials to your Kafka instance, they will be able to stay connected indefinitely. Deactivating the user account or service account will not close the connections that the attacker has opened. In this scenario, you would need to add Access Control List rules (ACLs) to prevent the unauthorized connections from performing any operations.
+
+    You could also contact Red Hat Support for assistance.
+
+    >**NOTE:** Disabling connection re-authentication will restart your Kafka instance.
+  # This array has currently required due to an internal quickstart bug. It always expect the array to be defined. https://github.com/patternfly/patternfly-quickstarts/pull/162
+  links:
+    - text: 'Managing account access in Red Hat OpenShift Streams for Apache Kafka'
+      href: https://access.redhat.com/documentation/en-us/red_hat_openshift_streams_for_apache_kafka/1/guide/2f4bf7cf-5de2-4254-8274-6bf71673f407
+      isExternal: true
+
+# Add additional kafka instance settings here.

docs/kafka/kafka-instance-settings/metadata.yml

@@ -0,0 +1,2 @@
+kind: HelpTopic
+name: kafka-connection-reauthentication