Resolve overlapping index templates for namespace customization

Learn how to interpret and resolve warnings about overlapping index templates when you enable namespace index templates for a Fleet integration. This page helps you decide whether to keep your existing customizations, switch to Fleet-managed namespace index templates, or combine both approaches.

If you previously duplicated an integration's base data stream index template (priority 200), narrowed the index pattern to one namespace, and raised the copy's priority (often to 250 or higher), that copy can overlap with a Fleet-managed namespace index template. For example, you might have copied logs-nginx.error into logs-nginx.error-production-custom with pattern logs-nginx.error-production* and priority 280.

When you enable namespace index templates for that same namespace, Fleet tries to create a managed template such as logs-nginx.error@namespace.production at priority 250 for the same index pattern. Elasticsearch applies only one winning index template per index creation, so those templates overlap. The result depends on the existing template's priority, as described in How Fleet detects and reports overlaps.

The same can happen with any pre-existing index template whose index patterns match the namespace's data streams, not only copies with a custom suffix in the name.

When you enable namespace index templates for a namespace on an integration, Fleet runs a preflight check for each (data stream, namespace) pair. The check uses the Elasticsearch simulate index API (POST _index_template/_simulate_index/<index>) to see which existing template would win for that data stream, then compares priorities with the planned namespace index template.

Fleet reports overlaps in the UI before changes are applied, and in API responses as warnings. Each overlap falls into one of these cases:

Elasticsearch does not merge overlapping index templates. The highest-priority matching template wins as a whole. Component templates are merged only within that winning template's composed_of list.

Pick the path that matches your goal.

Use this path when you want <namespace>@custom and related Fleet namespace features to apply.

1. Identify overlapping templates in Index Management → Index Templates. Look for templates whose index patterns match the same data streams as the planned @namespace.<namespace> templates.

2. If any overlapping template has priority 250, lower that priority (for example to 200 or less) or remove the template before enabling. Same-priority templates block creation of the Fleet-managed namespace index template.

   How to change an index template's priority

   1. Go to the Index Management page using the navigation menu or the global search field, and open the Index Templates tab.
   2. Find and select the index template you want to change, then select Manage → Edit.
   3. On the Logistics step, update the Priority value.
   4. Continue to the Review step, then save the template.

   For more about creating and managing index templates, refer to Index templates.

3. Enable namespace index templates for the namespace. For UI and API steps, refer to Customize data streams with namespace index templates.

4. Confirm the managed templates exist (for example, search index templates for @namespace.<namespace>).

5. Create or update the <namespace>@custom component template with the settings you still need. Copy useful settings from your older custom index templates into <namespace>@custom or into the data stream @custom templates when they should stay data-stream-specific.

6. Optionally delete or further lower the priority of unused custom index templates that no longer win, if you don't need them as a fallback.

7. Roll over each affected data stream so new backing indices use the managed templates.

Use this path when your custom index templates already do what you need.

1. Cancel enabling if the warning appears in the UI, or leave the namespace out of Namespaces with dedicated index templates.
2. If you already enabled namespace index templates for the namespace, remove it from Namespaces with dedicated index templates on the integration's Settings tab, or turn off Use dedicated index templates for this namespace in the integration policy editor. Fleet deletes the managed namespace index templates; your existing templates remain.
3. Continue managing customization through your existing index templates and component templates.

Use this path only when you understand which template should win for each data stream.

1. Review every overlapping template's priority against the namespace index template priority (250 for most integrations; refer to the preceding note).

2. For data streams where your custom template must win, set its priority higher than the namespace index template priority. For data streams where the Fleet-managed namespace index template must win, set your custom template's priority lower (but not equal, which blocks creation), or remove the template.

   How to change an index template's priority

   1. Go to the Index Management page using the navigation menu or the global search field, and open the Index Templates tab.
   2. Find and select the index template you want to change, then select Manage → Edit.
   3. On the Logistics step, update the Priority value.
   4. Continue to the Review step, then save the template.

   For more about creating and managing index templates, refer to Index templates.

3. Enable namespace index templates and read the warning list to confirm the expected winners.

4. Verify a sample of new backing indices (settings, mappings, and lifecycle) after rollover.

Leaving overlapping templates at priority 250 or higher means some or all namespace index template customization might be unused or incomplete, even after you enable the feature.

• Customize data streams with namespace index templates
• Edit the Elasticsearch index template
• Best practices for copying an integration index template
• Tutorials: Customize data retention policies