ILM docs: improve @custom component template usage/details #3511
Conversation
🔍 Preview links for changed docs |
There was a problem hiding this comment.
Looks great, and the doc in general looks great, I didn't know it!
Also the referenced tutorials for customizing integrations through custom component templates, awesome!
I've shared a suggestion for the *@custom sentence, as I think the * there could be misleading as we don't really mean any string, but the name of the default managed index templates.
|
|
||
| {{es}} includes a set of built-in {{ilm-init}} policies that govern how managed indices transition as they age. This guide demonstrates how you can customize the lifecycle of a managed index, to adjust how the index transitions across [data tiers](/manage-data/lifecycle/data-tiers.md) and what [actions](/manage-data/lifecycle/index-lifecycle-management/index-lifecycle.md#ilm-phase-actions), such as downsampling or shrinking, are performed on the index during each lifecycle phase. | ||
|
|
||
| Setting a custom {{ilm-init}} policy is useful when you have a specific set of indices, for example a set of Kubernetes logs which can grow to be quite large in volume, for which you don't want to use the default data retention duration and other {{ilm-init}} settings. |
| To apply your new {{ilm-init}} policy to the `logs` index template, create or edit the `logs@custom` component template. | ||
|
|
||
| A `*@custom` component template allows you to customize the mappings and settings of managed index templates, without having to override managed index templates or component templates. This type of component template is automatically picked up by the index template. [Learn more](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-component-template). | ||
| A `*@custom` component template allows you to customize the mappings and settings of managed index templates, without having to override managed index templates or component templates. This type of component template is automatically picked up by the index template. |
There was a problem hiding this comment.
The sentence with *@custom component template feels a bit weird.
Apparently it implies that any random *@custom component template will be magically picked up by an index template. So if I create mydata@custom it will be picked up by a template.
I think what we want to mean here is that we can create logs@custom, metrics@custom, traces@custom, and others (but not any), and those will be picked because they belong to the default index templates created by the stack, right?
Maybe we can convert this list into a table and include for each ILM policy the associated stack index template that uses it?
And then in this section we can explain that we can create any *@custom component template where * is any of the default index templates, but not any random string....
There was a problem hiding this comment.
Sorry, maybe an easier solution just with a text suggestion :) Let me know your thoughts.
| A `*@custom` component template allows you to customize the mappings and settings of managed index templates, without having to override managed index templates or component templates. This type of component template is automatically picked up by the index template. | |
| A `<name-of-managed-index-template>@custom` component template allows you to customize the mappings and settings of the managed index templates, without having to override them or their main component templates. This type of component template, which doesn't exist by default, is already included in all managed index templates to allow customizations. |
Not sure if my goal is clear, if you understand it and you think there's a better way please go ahead!
There was a problem hiding this comment.
@eedugon, thanks for this! I think this is such a difficult concept so I tried to really clear it up. What do you think of this?
By the way, I didn't use <name-of-managed-index-template>@custom because (as I just learned) many managed index templates have more than one associated custom component template. Also, I've found that only the main managed index templates have a @custom component template associated with them. So complicated! :-)
There was a problem hiding this comment.
Awesome!
Probably we need to include hints about @Custom component templates in more places.
Great explanation and solution! Thanks for digging into this.
kilfoyle
changed the title
manage-data/lifecycle/index-lifecycle-management/tutorial-customize-built-in-policies.md
Outdated
Show resolved
Hide resolved
…omize-built-in-policies.md Co-authored-by: Edu González de la Herrán <[email protected]>
2 participants
In the ILM docs, the Customize built-in policies tutorial mentions
@customcomponent templates with a "learn more" link that points to the "Create or update component template" API docs. Not super helpful, since those API docs don't mention the@customcomponent templates.Those templates are discussed in more detail in the Fleet docs, with lengthy examples of using them. This PR adds a link to that content and removes the API link.
I've also added a sentence at the top giving an example of creating a custom policy for K8s logs, since we're told that those can be giant.
Closes: #1557