docs(operators): updates to the operator overviews

[PaulRMellor]

Documentation

Update and refactor of the operator overviews in the Overview and Deploying guide.
Incorporates Access Operator in the Overview and introduces the operators earlier in the guide, with separate sections describing each.
The operators overview in the Overview guide describes the operators
The operators overview in the Deploying guide is more deployment-specific.

As discussed for strimzi/kafka-access-operator#71 (comment)

Checklist

Please go through this checklist and make sure all applicable tasks have been done

• Write tests
• Make sure all tests pass
• Update documentation
• Check RBAC rights for Kubernetes / OpenShift roles
• Try your changes from Pod inside your Kubernetes and OpenShift cluster, not just locally
• Reference relevant issue(s) and close them after merging
• Update CHANGELOG.md
• Supply screenshots for visual changes, such as Grafana dashboards

[scholzj]

TBH, for me the Access Operator does not fit here:

• The way you added it here is very forced.
• It fails to properly explain what it does, why and how to use it, and who should use it. This will just lead to many questions from confused people asking Why do I need it?. While in reality 99% of users will never need it.
• While the Access Operator has its first release, it is largely unfinished. The actual value will be added only once it has cross cluster support. Until then, copying the Secrets using existing tools is likely better choice.
• If you want to include the Access Operator more prominently in the docs, you should do it in the places which cover the use cases it handles. Such as in the detailed sections about User Operator and how it handles namespaces.

The strimzi/kafka-access-operator#71 issue needs to be interpreted in the right context. Drain Cleaner is indeed something what everyone using Strimzi to run Kafka brokers should be aware of. And if users are not, that is something to improve. But the Access Operator is not - and will not be even once it is feature complete. It is a tool in the same level as for example the Configuration Providers - it has some use-cases and it has value for some users. But not everyone needs to be aware of it and not everyone needs it. So its presence in the documentation should correspond to it.

[scholzj]

If we want to list the Access Operator and Drain Cleaner in the introduction in sich a prominent way, we should probably also cover here how they are installed.

[ppatierno]

+1

[ppatierno]

+1

[ppatierno]

Suggested change

	If you are using the Cluster Operator to manage your Kafka cluster, you can deploy and use the Access Operator to manage the distribution of connection details
	If you are using the Cluster Operator to manage your Kafka cluster, you can deploy and use the Access Operator to manage the distribution of connection details.

[PaulRMellor]

TBH, for me the Access Operator does not fit here:

• The way you added it here is very forced.
• It fails to properly explain what it does, why and how to use it, and who should use it. This will just lead to many questions from confused people asking Why do I need it?. While in reality 99% of users will never need it.
• While the Access Operator has its first release, it is largely unfinished. The actual value will be added only once it has cross cluster support. Until then, copying the Secrets using existing tools is likely better choice.
• If you want to include the Access Operator more prominently in the docs, you should do it in the places which cover the use cases it handles. Such as in the detailed sections about User Operator and how it handles namespaces.

The strimzi/kafka-access-operator#71 issue needs to be interpreted in the right context. Drain Cleaner is indeed something what everyone using Strimzi to run Kafka brokers should be aware of. And if users are not, that is something to improve. But the Access Operator is not - and will not be even once it is feature complete. It is a tool in the same level as for example the Configuration Providers - it has some use-cases and it has value for some users. But not everyone needs to be aware of it and not everyone needs it. So its presence in the documentation should correspond to it.

Thanks @scholzj. I see your point and the risk of confusion for users who don’t require the access operator, but I do think it belongs in the Strimzi Operators section for completeness. Would it help to adjust the description to make it clear that it's an advanced, optional tool with specific use cases? We can refine the explanation so that it’s not just listed but gives a clearer picture of when and why users might consider it.

We can also look into adding more detail on covering multi-namespace setups, where its value becomes clearer.

[scholzj]

Thanks @scholzj. I see your point and the risk of confusion for users who don’t require the access operator, but I do think it belongs in the Strimzi Operators section for completeness. Would it help to adjust the description to make it clear that it's an advanced, optional tool with specific use cases? We can refine the explanation so that it’s not just listed but gives a clearer picture of when and why users might consider it.

Why do you think it belongs there? It is a separate project targeting a niche use-case. Moreover as I said, it is still under development and missing major features which were the main motivation for it.

If you think it should be here, than as I said, so should be the Config Providers for example. And you have to make sure the meaning, value and use-cases of each of these are properly explained.