Browse Source

[DOCS] Add admon for built-in index templates (#61063)

Adds an important admonition for the built-in `metrics-*-*` and `logs-*-*` index
templates.

Updates several put index template snippets to include a priority.
James Rodewig 5 years ago
parent
commit
cd6304ae6b

+ 5 - 0
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": {

+ 17 - 0
docs/reference/data-streams/set-up-a-data-stream.asciidoc

@@ -106,6 +106,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 <<date,`date`>> or <<date_nanos,`date_nanos`>> field
 data type by the stream's index template. This mapping can include other
@@ -146,6 +161,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"
@@ -163,6 +179,7 @@ PUT /_index_template/my-data-stream-template
 {
   "index_patterns": [ "my-data-stream*" ],
   "data_stream": { },
+  "priority": 200,
   "template": {
     "mappings": {
       "properties": {

+ 13 - 0
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
 <<indices-templates,index templates>>.
 
+[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

+ 14 - 1
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.
@@ -80,7 +93,7 @@ PUT _index_template/template_1
       "mydata": { }
     }
   },
-  "priority": 10,
+  "priority": 200,
   "composed_of": ["component_template1", "other_component_template"],
   "version": 3,
   "_meta": {

+ 13 - 0
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)