ILM docs: improve @Custom component template usage/details (elastic#3511)

In the ILM docs, the [Customize built-in
policies](https://www.elastic.co/docs/manage-data/lifecycle/index-lifecycle-management/tutorial-customize-built-in-policies#example-using-index-lifecycle-policy-apply-policy)
tutorial mentions `@custom` component 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 `@custom`
component 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: elastic#1557

---------

Co-authored-by: Edu González de la Herrán <[email protected]>

Author: 2 people

manage-data/images/elasticsearch-reference-tutorial-custom-policies-otel-template.png

@@ -11,6 +11,8 @@ products:
 
 {{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.
+
 [{{agent}}](/reference/fleet/index.md) uses the following set of built-in {{ilm-init}} policies to manage backing indices for its data streams:
 
 * `logs@lifecycle`
@@ -27,9 +29,11 @@ This tutorial covers customizing the way ingested logging data is managed. Rathe
  3. [Apply the new policy to your log data using a `logs@custom` component template](#example-using-index-lifecycle-policy-apply-policy).
 
 :::{tip}
-If you're using [Elastic integrations](https://docs.elastic.co/en/integrations) and are not yet familiar with which data streams are associated with them, refer to [Manage the lifecycle policy for integrations data](/manage-data/lifecycle/index-lifecycle-management/manage-lifecycle-integrations-data.md).
+* If you're using [Elastic integrations](https://docs.elastic.co/en/integrations) and are not yet familiar with which data streams are associated with them, refer to [Manage the lifecycle policy for integrations data](/manage-data/lifecycle/index-lifecycle-management/manage-lifecycle-integrations-data.md).
+
+* If you're looking for a more advanced use case, such as customizing an ILM policy for a selected set of data streams in one or more integrations or namespaces, check the set of tutorials in [Customize data retention policies](/reference/fleet/data-streams-ilm-tutorial.md) in the {{fleet}} and {{agent}} reference documentation.
 
-If you're looking for a more advanced use case, such as customizing an ILM policy for a selected set of data streams in one or more integrations or namespaces, check the set of tutorials in [Customize data retention policies](/reference/fleet/data-streams-ilm-tutorial.md) in the {{fleet}} and {{agent}} reference documentation.
+    These tutorials go into greater depth about creating and using `@custom` component templates. For example, the tutorial [Apply an ILM policy to all data streams generated from {{fleet}} integrations across all namespaces](/reference/fleet/data-streams-scenario1.md) shows how to create and use the `logs@custom` and `metrics@custom` component templates to customize {{ilm-init}} policies associated with data streams in integrations.
 :::
 
 ## Scenario [example-using-index-lifecycle-policy-scenario]
@@ -140,7 +144,20 @@ Copies of managed {{ilm-init}} policies are also marked as **Managed**. You can
 
 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).
+
+:::::{admonition} Using @custom component templates
+A `@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.
+
+Many {{es}} managed index templates include one or more `@custom` component templates. A `@custom` component template must first be created before it can be used, and its name must exactly match the name specified in the managed index template in order to be applied automatically to indices as they're created.
+
+For example, if you're ingesting OpenTelemetry (OTel) logs, any OTel log data streams and their backing indices are configured by the `logs-otel@template` managed index template. That index template automatically applies settings defined in the `logs@custom` and the `logs-otel@custom` template when they exist.
+
+Go to **Index Management > Index Templates** and select any managed index to view the `@custom` component templates associated with it. 
+
+:::{image} /manage-data/images/elasticsearch-reference-tutorial-custom-policies-otel-template.png
+:alt: A screenshot showing the logs@custom and logs-otel@custom component templates associated with the logs-otel@template index template.
+:::
+:::::
 
 :::{tip}
 If you want your {{ilm-init}} changes to apply only to specific indices, you can create a custom index template directly instead of modifying the custom component template. Use the **Index management** page in {{kib}} or the [index template](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-index-template) API to create a new template.