SASL mechanisms wrongly referenced for PLAIN and SCRAM

Description of problem:

Our Documentation on Forwarding logs to third party systems refernces sasl.mechanisms in a confusing and wrong way.

The paragraph reads:

sasl.mechanisms: (array) List of allowed SASL mechanism names. If missing or empty, the system defaults are used. 

Where the code clearly indicates that only a string is accepted.

func GetFromSecret(secret *corev1.Secret, name string) string {
        if secret != nil {
                return string(secret.Data[name])
        }
        return ""
} 

Futhermore, we need to make clear that sasl.mechanisms are ment for SCRAM methods only and not for differentiation between PLAIN or SCRAM.

A working example of the three possible configuration (with 4.13 only SCRAM-256 is supported)

SASL PLAIN configuration

data:
   sasl.username: xxx
   sasl.password: xxx
   sasl.enable: True 

SASL SCRAM-256 configuration

data:
   sasl.username: xxx
   sasl.password: xxx
   sasl.enable: True
   sasl.mechanism: sha256 

SASL SCRAM-512 configuration

data:
   sasl.username: xxx
   sasl.password: xxx
   sasl.enable: True
   sasl.mechanism: sha512 

the optional sasl_over_ssl is automatically added with adding SSL fields in the secret.data section.

Version-Release number of selected component (if applicable):

5.x 

How reproducible:

always.

A valid configuration from Red Hat Openshift Logging < 5.7 will break with 5.7 due to the feature SASL-SCRAM-256 added, implemented with LOG-3314 

Steps to Reproduce:

1. install Red Hat Openshift Logging 5.6
2. configure SASL PLAIN 

   1. data: 
        sasl.username: xxx 
        sasl.password: xxx 
        sasl.enable: True 
        sasl.mechanism: PLAIN

1. upgrade Red Hat Openshift Logging to 5.7

Actual results:

2023-08-21 12:53:43 +0000 [error]: unexpected error error_class=Kafka::SaslScramError error="SCRAM mechanism PLAIN is not supported." 

Expected results:

successful authentication

Additional info:

After consulting the Engineering Team, we consider this a Documentation Bug as there's a misunderstandig of the wording sasl.mechanisms. SASL provides multiple methods to authenticate like SASL-PLAIN, SASL-SCRAM-256, SASL-SCRAM-512.

These are wrongly (human) interpreted as mechanisms which are auto determined by the underlying go library instead and mechanism differentiate the SCRAM mechanisms.

We published a KCS to clarify the situation until this BZ is resolved.