docs(refactor): updates the cruise control rebalance concepts

[PaulRMellor]

Documentation

Refactor and refresh of Cruise Control concepts

• Adds new optimization proposal process flow description and diagram, including description of partition reassignment commands
• Less verbose and more direct intro and concepts
• Removes three overview files to create a single "components and features" file for goals and proposals concepts
• Consolidates related conceptual information (goals, proposals) into single sections
• Retitled sections to provide more direction to readers from ToC

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

[fvaleri]

Hi @PaulRMellor, thanks. I must say that our CC doc is quite good :)

I left some comments for your consideration.

[PaulRMellor]

Thanks for the reviews @fvaleri and @kyguy
I've addressed all the comments except the suggestion to change "user-defined goals" to something else.
I agree it's not clear, but I'm not sure changing to "KafkaRebalance goals" is the way:
#10810 (comment)

[fvaleri]

LGTM. Thanks.

[ppatierno]

maybe it's just my luck of knowledge here, can we really change the priority order? @kyguy ?

[kyguy]

To my understanding, this is true for the Kafka resource default.goal and KafkaRebalance goals lists but not for Kafka goals list

[ppatierno]

Ok. So I think we should clarify here (and everywhere goals priority is mentioned) that the priority is based on the order. Not sure if "priority order" is used for this purpose but it's not clear to me.

[fvaleri]

We have to admit that CC naming doesn't help much here.

IMO, this is the default inter-broker goals priority list:

https://github.com/linkedin/cruise-control/blob/main/cruise-control/src/main/java/com/linkedin/kafka/cruisecontrol/config/constants/AnalyzerConfig.java#L312-L327

To change it, the user can configure Kafka default.goals or KafkaRebalance goals with a different order. Kafka goals priority is irrelevant, but only goals listed there can be used in the previous configurations (DEFAULT_DEFAULT_GOALS is a subset of DEFAULT_GOALS).

• Do you agree?
• Are we exposing Kafka goals because we intend to eventually support custom goals?

[PaulRMellor]

Thanks for the latest comments @kyguy and @ppatierno
I've updated the diagram and addressed all comments apart from this #10810 (comment)
Looking for guidance

[PaulRMellor]

Thanks for the latest @kyguy and @ppatierno
I've changed "main" to "supported" goals. (Much better)
Diagram now shows "Rebalance" as flow towards CC

[ppatierno]

LGTM.

[PaulRMellor]

Thanks for latest comments @kyguy
I've addressed them all as suggested.

Regarding the summary of Cruise Control components. Previously, we mentioned some but not all them without any context. I thought it would be useful at least to mention them all in summary and show how they operate within a Strimzi context, how requests are made and proposals generated etc. I think the diagram is useful (and good for SEO and user experience).

[PaulRMellor]

Thanks for the comments @kyguy
All pretty straightforward and addressed.
Doc is shaping up nicely

[kyguy]

Hi @PaulRMellor, was the commit with the changes pushed here?

[PaulRMellor]

Hi @PaulRMellor, was the commit with the changes pushed here?

There now: d47f53a

[kyguy]

Looks great @PaulRMellor, well done

[PaulRMellor]

Looks great @PaulRMellor, well done

Thanks for your help and applying your knowledge, @kyguy