ECK Elastic Stack configuration policies refinement and restructured

[eedugon]

Summary

Refinement of Elastic Stack configuration policies document, addressing the following improvement areas:

• The feature wasn't explained or introduced in the original doc.
• The links to the API docs in the initial list of features felt odd, without clear motivation or reasoning.
• There are two long bulleted lists with the same elements.
• Syntax of the different settings wasn't completely clear.

Changes:

• New introduction and document structure
• Define policies start with a basic example
• All examples organized under a Examples H2 section
• Features organized in a single table instead of creating two bulleted lists with the same items.
• Different syntax explained with examples.

With the new structure I think future maintenance of this section will be easier, even if we decide to separate all this in a few docs under its own hierarchy.

Closes #3177

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

Tool(s) and model(s) used: Cursor - auto mode

[github-actions]

✅ Vale Linting Results

No issues found on modified lines!

---

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

[github-actions]

🔍 Preview links for changed docs

• deploy-manage/deploy/cloud-on-k8s/elastic-stack-configuration-policies.md
• deploy-manage/users-roles/cluster-or-deployment-auth/manage-authentication-for-multiple-clusters.md

[shainaraskas]

I like it. I do think we should go with more columns even if it's ugly. table is definitely the right thing.

we can maybe resurrect an issue requesting wider tables or this one that collapses the nav and gives us more room (the viewport is kind of small)

edit: looks like dev will have a fix soon #5363

[shainaraskas]

would like to see some sort of api example that's more complex here

[shainaraskas]

one small thing: do you think it would be nice to have a small stack config policy above the fold, so people who just want to copy one quickly don't have to scroll too far?

[eedugon]

one small thing: do you think it would be nice to have a small stack config policy above the fold, so people who just want to copy one quickly don't have to scroll too far?

Great idea, yes! I also think devs will like it.

[pkoutsovasilis]

ty @eedugon for this improvement, overall LGMT left some comments

[pkoutsovasilis]

Suggested change

	The following settings can be configured for {{kib}} under `StackConfigPolicy.spec.elasticsearch`:
	The following settings can be configured for {{kib}} under `StackConfigPolicy.spec.kibana`:

This says spec.elasticsearch but should say spec.kibana, right?

[pkoutsovasilis]

Suggested change

	`composableIndexTemplates` and `componentTemplats` must be defined under the `indexTemplates` field:
	`composableIndexTemplates` and `componentTemplates` must be defined under the `indexTemplates` field:

[pkoutsovasilis]

Suggested change

	- name: my-secret
	mountPath: /etc/secrets
	- name: my-certificate
	mountPath: /usr/share/elasticsearch/config/my-certificate
	- secretName: my-secret
	mountPath: /etc/secrets
	- secretName: my-certificate
	mountPath: /usr/share/elasticsearch/config/my-certificate

these should have secretName right?