[[configuration-template]]

== Configure Elasticsearch index template loading

++++
<titleabbrev>Elasticsearch index template</titleabbrev>
++++

The `setup.template` section of the +{beatname_lc}.yml+ config file specifies
the {ref}/indices-templates.html[index template] to use for setting
mappings in Elasticsearch. If template loading is enabled (the default),
{beatname_uc} loads the index template automatically after successfully
connecting to Elasticsearch.

ifndef::no-output-logstash[]

NOTE: A connection to Elasticsearch is required to load the index template. If
the configured output is not Elasticsearch (or {ess}), you must
<<load-template-manually,load the template manually>>.

endif::[]

You can adjust the following settings to load your own template or overwrite an
existing one.

*`setup.template.enabled`*:: Set to false to disable template loading. If this is set to false,
you must <<load-template-manually,load the template manually>>.

ifndef::apm-server[]
*`setup.template.type`*:: The type of template to use. Available options: `legacy` (default), index templates
before Elasticsearch v7.8. Use this to avoid breaking existing deployments. New options are `component`
and `index`. Selecting `component` loads a component template which can be included in new index templates.
The option `index` loads the new index template.
endif::[]

*`setup.template.name`*:: The name of the template. The default is
+{beatname_lc}+. The {beatname_uc} version is always appended to the given
name, so the final name is +{beatname_lc}-%{[{beat_version_key}]}+.

// Maintainers: a backslash character is required to escape curly braces and
// asterisks in inline code examples that contain asciidoc attributes. You'll
// note that a backslash does not appear before the asterisk
// in +{beatname_lc}-%{[{beat_version_key}]}-*+. This is intentional and formats
// the example as expected.

*`setup.template.pattern`*:: The template pattern to apply to the default index
settings. The default pattern is +{beat_default_index_prefix}-\*+. The {beatname_uc} version is always
included in the pattern, so the final pattern is
+{beat_default_index_prefix}-%{[{beat_version_key}]}-*+. The wildcard character `-*` is used to
match all daily indices.
+
Example:
+
["source","yaml",subs="attributes"]
----------------------------------------------------------------------
setup.template.name: "{beatname_lc}"
setup.template.pattern: "{beat_default_index_prefix}-*"
----------------------------------------------------------------------

*`setup.template.fields`*:: The path to the YAML file describing the fields. The default is +fields.yml+. If a
relative path is set, it is considered relative to the config path. See the <<directory-layout>>
section for details.

*`setup.template.overwrite`*:: A boolean that specifies whether to overwrite the existing template. The default
is false. Do not enable this option if you start more than one instance of {beatname_uc} at the same time. It
can overload {es} by sending too many template update requests.

*`setup.template.settings`*:: A dictionary of settings to place into the `settings.index` dictionary of the
Elasticsearch template. For more details about the available Elasticsearch mapping options, please
see the Elasticsearch {ref}/mapping.html[mapping reference].
+
Example:
+
["source","yaml",subs="attributes"]
----------------------------------------------------------------------
setup.template.name: "{beatname_lc}"
setup.template.fields: "fields.yml"
setup.template.overwrite: false
setup.template.settings:
  index.number_of_shards: 1
  index.number_of_replicas: 1
----------------------------------------------------------------------

*`setup.template.settings._source`*:: A dictionary of settings for the `_source` field. For the available settings,
please see the Elasticsearch {ref}/mapping-source-field.html[reference].
+
Example:
+
["source","yaml",subs="attributes"]
----------------------------------------------------------------------
setup.template.name: "{beatname_lc}"
setup.template.fields: "fields.yml"
setup.template.overwrite: false
setup.template.settings:
  _source.enabled: false
----------------------------------------------------------------------

*`setup.template.append_fields`*:: A list of fields to be added
to the template and {kib} index pattern. This setting adds new fields. It does
not overwrite or change existing fields.
+
This setting is useful when your data contains fields that {beatname_uc} doesn't
know about in advance.
ifeval::["{beatname_lc}"=="metricbeat"]
For example, you might want to append fields to the template when you're using
a metricset, such as the <<metricbeat-metricset-http-json>>, and the full data
structure is not known in advance.
endif::[]
+
If `append_fields` is specified along with `overwrite: true`, {beatname_uc}
overwrites the existing template and applies the new template when creating new
indices. Existing indices are not affected. If you're running multiple
instances of {beatname_uc} with different `append_fields` settings, the last one
writing the template takes precedence.
+
Any changes to this setting also affect the {kib} index pattern.
+
Example config:
+
[source,yaml]
----
setup.template.overwrite: true
setup.template.append_fields:
- name: test.name
  type: keyword
- name: test.hostname
  type: long
----

*`setup.template.json.enabled`*:: Set to `true` to load a
JSON-based template file. Specify the path to your {es} index template file and
set the name of the template.
+
["source","yaml",subs="attributes"]
----------------------------------------------------------------------
setup.template.json.enabled: true
setup.template.json.path: "template.json"
setup.template.json.name: "template-name
----------------------------------------------------------------------

NOTE: If the JSON template is used, the `fields.yml` is skipped for the template
generation.
