Docs: Add docs for using external secrets in Kafka Connect

[scholzj]

Type of change

• Documentation

Description

This PR adds the documentation related to the changes in #1182

Checklist

• Update documentation

[ppatierno]

I added few comments, one more is about using "ConfigMaps" instead of "Config Maps"

[d-laing]

Review comments are inline.

[d-laing]

Please reword as follows:

Kafka Connect connectors include built-in configuration using REST. The connector configuration is transferred to Kafka Connect whenever an HTTP request to the connector is made.

Alternatively, the configuration of a Kafka Connect connector can be stored externally as ConfigMaps or Secrets. ConfigMaps and Secrets are standard {ProductPlatformName} resources used for Pod configuration and authentication. This method applies especially to confidential data, such as usernames, passwords, or certificates.

[scholzj]

@laidan6000 I fixed all the other comments as you suggested. But I'm a bit unsure about this one as I don't think it is correct and makes really sense.

• The REST and HTTP are the same interface. Technically it should be probably HTTP REST interface
• The way this works is that the configuration is stored inside Kafka. And the user creates / modifies / deletes the connector and its configuration using the HTTP REST interface.
• After this PR the connector configuration is not really stored in the config maps or secrets. But the configuration in the HTTP REST commands can reference the values from them and that way to keep them separate and more secure if needed.

I think especially the first paragraph in your suggestion is wrong and confusing. The second could be probably used.

[d-laing]

Thanks for the additional information in the bullet points. In my eagerness to use the verb "store" rather than "externalize", I changed the meaning of the sentence. To be honest, I am struggling to fully understand the approach here. I've edited the first paragraph based on your bullet points -- does it work for you? Please tweak the wording as needed.

==

Kafka Connect connectors are configured using an HTTP REST interface. The connector configuration is stored within Kafka itself and passed to Kafka Connect as part of an HTTP request.

Alternatively, the configuration of a Kafka Connect connector can be externalized as ConfigMaps or Secrets. You can then reference the configuration values in HTTP REST commands (this keeps the configuration separate and more secure, if needed). This method applies especially to confidential data, such as usernames, passwords, or certificates.

ConfigMaps and Secrets are standard {ProductPlatformName} resources used for Pod configuration and authentication.

[scholzj]

@laidan6000 I did some additional changes to this to make it (hopefully) a bit more clear. Especially to make it more clear that it doesn't store the whole configuration but just some pieces (I think this was probably written incorrectly already by me on the beginning). It would be great if you could have another review. The other comments should be incorporated as you suggested.

[d-laing]

It reads very well and makes sense to me. Happy for you to merge the PR.

[d-laing]

Added further, minor comments after a second read-through. I've had another try at the assembly introduction -- please tweak the wording if you still think it's confusing.

[d-laing]

Approved.