Customize data streams with namespace index templates

Namespace index templates are Fleet-managed index templates scoped to one namespace of an installed integration. When you opt a namespace in, Fleet creates one of these templates for each data stream defined by the integration, and each template references a <namespace>@custom component template that you create and manage.

Use this feature when you want the same custom settings or mappings on every data stream in a specific namespace for a given integration, instead of editing each data stream's @custom component template separately.

Setting up namespace index templates involves these steps:

1. Enable namespace index templates for the namespace, in the UI or with the API.
2. Create the <namespace>@custom component template that holds the custom settings and mappings you want applied to every data stream in the namespace.
3. If you have pre-existing index templates that overlap with the Fleet-managed templates, resolve the overlapping templates.

When you enable namespace index templates for a namespace on an installed integration, Fleet creates one namespace index template for each data stream defined by the integration. The templates are named using the following pattern:

<type>-<dataset>@namespace.<namespace>
		

For example, enabling the production namespace for the System integration creates templates such as logs-system.application@namespace.production.

Each namespace index template is a copy of the integration's base data stream index template, but differs in these ways:

• The index_patterns value is scoped to that namespace (for example, logs-system.application-production*).
• The priority is the base template priority plus 50: 250 for most integrations (base 200), or 200 for integrations with dataset_is_prefix: true data streams (base 150). Because this is higher than the base template priority, Elasticsearch applies the namespace index template for matching data streams. If you change this priority manually, Fleet restores the default the next time the integration's templates are reinstalled or resynchronized.
• The composed_of list includes a <namespace>@custom component template (for example, production@custom) after the type-level and package-level @custom templates, and before the data stream-level @custom template.

Example composed_of list for logs-system.application@namespace.production:

[
  "logs@mappings",
  "logs@settings",
  "logs-system.application@package",
  "logs@custom",
  "system@custom",
  "production@custom",
  "logs-system.application@custom",
  "ecs@mappings",
  ".fleet_globals-1",
  ".fleet_agent_id_verification-1"
]
		

Later component templates in this list take precedence when the same setting or mapping key appears more than once. From highest to lowest precedence among the @custom templates: logs-system.application@custom, then production@custom, then system@custom, then logs@custom.

The namespaces you opt in for an integration are the same across the whole cluster. The index templates and component templates Fleet creates are also shared across the cluster.

If your Kibana space restricts which namespaces are allowed, you can only enable namespace index templates for namespaces that match those restrictions.

You can enable namespace index templates from the integration settings, or while creating or editing an integration policy.

After you save, Fleet creates the namespace index templates asynchronously. You can confirm they exist on the integration's Assets tab, or in the Index Management → Index Templates list by searching for @namespace..

After you opt in, create the <namespace>@custom component template so your customizations take effect.

You can also manage opt-in with the Fleet package APIs. Template create and delete operations run asynchronously after the request succeeds.

To enable one or more namespaces for a single installed package:

				PUT kbn:/api/fleet/epm/packages/system
					{
  "namespace_customization_enabled_for": ["production"]
}
		

To enable namespaces or remove them from the opt-in list across multiple packages in one request:

				POST kbn:/api/fleet/epm/packages/_bulk_namespace_customization
					{
  "packages": ["system", "nginx", "apache"],
  "enable": ["production"],
  "disable": ["staging"]
}
		

The bulk endpoint is additive and subtractive: enable adds namespaces to each package's opt-in list, and disable removes them. It does not replace the full list.

Your customizations only apply after you create the <namespace>@custom component template.

1. Find Index Management in the navigation menu or use the global search field, and open the Component Templates tab.

2. Select Create component template.

3. Name the template using the pattern <namespace>@custom (for example, production@custom).

4. Add the index settings, mappings, or aliases you want applied to every data stream in that namespace for opted-in integrations.

5. Create the component template.

6. Roll over each affected data stream so new backing indices pick up the changes. For example:

   				POST logs-system.application-production/_rollover
   		

You can remove a namespace from the opt-in list in either of these ways:

• On the integration Settings tab, remove the namespace from Namespaces with dedicated index templates, then save.
• In the integration policy editor, turn off Use dedicated index templates for this namespace, then save.

When you remove a namespace from the opt-in list, Fleet deletes the corresponding namespace index templates. The <namespace>@custom component template is left in place so you can reuse it later.

If you previously duplicated a base data stream index template and gave the copy a higher priority, that copy can overlap with the Fleet-managed namespace index template. When you opt a namespace in, Fleet warns you about overlapping templates and what will happen for each one.

For details and resolution steps, refer to Resolve overlapping index templates for namespace customization.

• Elastic Agent data streams for Fleet
• Edit the Elasticsearch index template
• Resolve overlapping index templates for namespace customization