From 6a248aea07eee3a397e8dd1272e14b0b032ba89c Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Mon, 17 Aug 2020 12:48:34 -0400 Subject: [PATCH] [DOCS] Add admon for built-in index templates (#61063) (#61220) Adds an important admonition for the built-in `metrics-*-*` and `logs-*-*` index templates. Updates several put index template snippets to include a priority. --- .../change-mappings-and-settings.asciidoc | 5 +++++ .../data-streams/set-up-a-data-stream.asciidoc | 17 +++++++++++++++++ docs/reference/docs/index_.asciidoc | 13 +++++++++++++ docs/reference/indices/index-templates.asciidoc | 15 ++++++++++++++- .../indices/put-index-template.asciidoc | 13 +++++++++++++ 5 files changed, 62 insertions(+), 1 deletion(-) diff --git a/docs/reference/data-streams/change-mappings-and-settings.asciidoc b/docs/reference/data-streams/change-mappings-and-settings.asciidoc index 6bb6ebcef41..6ff4737ad08 100644 --- a/docs/reference/data-streams/change-mappings-and-settings.asciidoc +++ b/docs/reference/data-streams/change-mappings-and-settings.asciidoc @@ -102,6 +102,7 @@ PUT /_index_template/my-data-stream-template { "index_patterns": [ "my-data-stream*" ], "data_stream": { }, + "priority": 200, "template": { "mappings": { "properties": { @@ -184,6 +185,7 @@ PUT /_index_template/my-data-stream-template { "index_patterns": [ "my-data-stream*" ], "data_stream": { }, + "priority": 200, "template": { "mappings": { "properties": { @@ -288,6 +290,7 @@ PUT /_index_template/my-data-stream-template { "index_patterns": [ "my-data-stream*" ], "data_stream": { }, + "priority": 200, "template": { "settings": { "index.refresh_interval": "30s" <1> @@ -341,6 +344,7 @@ PUT /_index_template/my-data-stream-template { "index_patterns": [ "my-data-stream*" ], "data_stream": { }, + "priority": 200, "template": { "settings": { "sort.field": [ "@timestamp"], <1> @@ -442,6 +446,7 @@ PUT /_index_template/new-data-stream-template { "index_patterns": [ "new-data-stream*" ], "data_stream": { }, + "priority": 200, "template": { "mappings": { "properties": { diff --git a/docs/reference/data-streams/set-up-a-data-stream.asciidoc b/docs/reference/data-streams/set-up-a-data-stream.asciidoc index ddfc60fa50d..8f8e7c8621d 100644 --- a/docs/reference/data-streams/set-up-a-data-stream.asciidoc +++ b/docs/reference/data-streams/set-up-a-data-stream.asciidoc @@ -109,6 +109,21 @@ template for a data stream must specify: * That the template is used exclusively for data streams. +* A priority for the template. + +[IMPORTANT] +==== +{es} has built-in index templates for the `metrics-*-*` and `logs-*-*` index +patterns. {ingest-guide}/ingest-management-overview.html[{agent}] uses these +templates to create data streams. If you use {agent}, assign your index +templates a priority lower than `100` to avoid an override of the built-in +templates. + +Otherwise, to avoid accidentally applying the built-in templates, use a +non-overlapping index pattern, or assign your templates a `priority` higher or +lower than `100`. +==== + Every document indexed to a data stream must have a `@timestamp` field. This field can be mapped as a <> or <> field data type by the stream's index template. This mapping can include other @@ -149,6 +164,7 @@ PUT /_index_template/my-data-stream-template { "index_patterns": [ "my-data-stream*" ], "data_stream": { }, + "priority": 200, "template": { "settings": { "index.lifecycle.name": "my-data-stream-policy" @@ -166,6 +182,7 @@ PUT /_index_template/my-data-stream-template { "index_patterns": [ "my-data-stream*" ], "data_stream": { }, + "priority": 200, "template": { "mappings": { "properties": { diff --git a/docs/reference/docs/index_.asciidoc b/docs/reference/docs/index_.asciidoc index bd68c5d0acd..720b1492e5c 100644 --- a/docs/reference/docs/index_.asciidoc +++ b/docs/reference/docs/index_.asciidoc @@ -169,6 +169,19 @@ If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching <>. +[IMPORTANT] +==== +{es} has built-in index templates for the `metrics-*-*` and `logs-*-*` index +patterns. {ingest-guide}/ingest-management-overview.html[{agent}] uses these +templates to create data streams. If you use {agent}, assign your index +templates a priority lower than `100` to avoid an override of the built-in +templates. + +Otherwise, to avoid accidentally applying the built-in templates, use a +non-overlapping index pattern, or assign your templates a `priority` higher or +lower than `100`. +==== + If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed. For more information about field diff --git a/docs/reference/indices/index-templates.asciidoc b/docs/reference/indices/index-templates.asciidoc index 5a47f3cd9a0..df352fafdcf 100644 --- a/docs/reference/indices/index-templates.asciidoc +++ b/docs/reference/indices/index-templates.asciidoc @@ -20,6 +20,19 @@ specify settings, mappings, and aliases. If a new data stream or index matches more than one index template, the index template with the highest priority is used. +[IMPORTANT] +==== +{es} has built-in index templates for the `metrics-*-*` and `logs-*-*` index +patterns. {ingest-guide}/ingest-management-overview.html[{agent}] uses these +templates to create data streams. If you use {agent}, assign your index +templates a priority lower than `100` to avoid an override of the built-in +templates. + +Otherwise, to avoid accidentally applying the built-in templates, use a +non-overlapping index pattern, or assign your templates a `priority` higher or +lower than `100`. +==== + When a composable template matches a given index it always takes precedence over a legacy template. If no composable template matches, a legacy template may still match and be applied. @@ -77,7 +90,7 @@ PUT _index_template/template_1 "mydata": { } } }, - "priority": 10, + "priority": 200, "composed_of": ["component_template1", "other_component_template"], "version": 3, "_meta": { diff --git a/docs/reference/indices/put-index-template.asciidoc b/docs/reference/indices/put-index-template.asciidoc index 5f84c1e1527..3afa263f3ea 100644 --- a/docs/reference/indices/put-index-template.asciidoc +++ b/docs/reference/indices/put-index-template.asciidoc @@ -83,6 +83,19 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout] (Required, array of strings) Array of wildcard (`*`) expressions used to match the names of data streams and indices during creation. ++ +[IMPORTANT] +==== +{es} has built-in index templates for the `metrics-*-*` and `logs-*-*` index +patterns. {ingest-guide}/ingest-management-overview.html[{agent}] uses these +templates to create data streams. If you use {agent}, assign your index +templates a priority lower than `100` to avoid an override of the built-in +templates. + +Otherwise, to avoid accidentally applying the built-in templates, use a +non-overlapping index pattern, or assign your templates a `priority` higher or +lower than `100`. +==== [xpack]#`data_stream`#:: (Optional, object)