[7.x] Add template simulation API for simulating template composition (#56842)

client/rest-high-level/src/test/java/org/elasticsearch/client/RestHighLevelClientTests.java

@@ -803,7 +803,8 @@ public void testApiNamingConventions() throws Exception {
             "scripts_painless_execute",
             "indices.create_data_stream",
             "indices.get_data_stream",
-            "indices.delete_data_stream"
+            "indices.delete_data_stream",
+            "indices.simulate_template"
         };
         //These API are not required for high-level client feature completeness
         String[] notRequiredApi = new String[] {

docs/reference/indices/index-templates.asciidoc

@@ -96,7 +96,7 @@ PUT _index_template/template_1
 
 [source,console]
 --------------------------------------------------
-DELETE _index_template/template_*
+DELETE _index_template/*
 DELETE _component_template/*
 --------------------------------------------------
 // TEARDOWN
@@ -291,6 +291,135 @@ PUT /_index_template/template_1
 In this case, an index matching `t*` will have three primary shards. If the order of composed
 templates were reversed, the index would have two primary shards.
 
+
+[[simulating-templates]]
+===== Simulating template composition
+
+Since templates can be composed not only of multiple component templates, but also the index
+template itself, there are two simulation APIs to determine what the resulting index settings will
+be.
+
+To simulate the settings that would be applied to a matching index name:
+
+[source,console]
+--------------------------------------------------
+POST /_index_template/_simulate_index/myindex
+--------------------------------------------------
+
+To simulate the settings that would be applied from a particular template:
+
+[source,console]
+--------------------------------------------------
+POST /_index_template/_simulate/template_1
+
+POST /_index_template/_simulate
+{
+  "index_patterns": ["foo"],
+  "template": {
+    "settings": {
+      "number_of_replicas": 0
+    }
+  }
+}
+--------------------------------------------------
+
+
+Here's an example demonstrating simulating both an index name and template name:
+
+[source,console]
+--------------------------------------------------
+PUT /_component_template/ct1 <1>
+{
+  "template": {
+    "settings": {
+      "index.number_of_shards": 2
+    }
+  }
+}
+
+PUT /_component_template/ct2 <2>
+{
+  "template": {
+    "settings": {
+      "index.number_of_replicas": 0
+    },
+    "mappings": {
+      "properties": {
+        "@timestamp": {
+          "type": "date"
+        }
+      }
+    }
+  }
+}
+
+PUT /_index_template/final-template <3>
+{
+  "index_patterns": ["logdata-*"],
+  "composed_of": ["ct1", "ct2"],
+  "priority": 5
+}
+
+POST /_index_template/_simulate_index/logdata-2019-02-01 <4>
+
+POST /_index_template/_simulate/final-template <5>
+
+POST /_index_template/_simulate <6>
+{
+  "index_patterns": ["logdata-*"],
+  "composed_of": ["ct2"],
+  "priority": 10,
+  "template": {
+    "settings": {
+      "index.number_of_replicas": 1
+    }
+  }
+}
+--------------------------------------------------
+<1> Creating a component template (ct1) setting the number of shards to two
+<2> Creating another component template (ct2) setting the number of replicas to zero with mappings
+<3> Creating an index template called "final" template using ct1 and ct2
+<4> Simulate the settings that would be applied for a new index "logdata-2019-02-01"
+<5> Simulate the settings composed using the "final-template" index template
+<6> Simulate the settings composed using a custom specified template
+
+The output of the simulate API from the last example call looks like:
+
+[source,console-result]
+---------------------------------------------------------
+{
+  "template" : {
+    "settings" : {
+      "index" : {
+        "number_of_replicas" : "1" <1>
+      }
+    },
+    "mappings" : {
+      "properties" : {
+        "@timestamp" : { <2>
+          "type" : "date"
+        }
+      }
+    },
+    "aliases" : { }
+  },
+  "overlapping" : [ <3>
+    {
+      "name" : "final-template",
+      "index_patterns" : [
+        "logdata-*"
+      ]
+    }
+  ]
+}
+---------------------------------------------------------
+<1> The number of replicas from the simulated template body
+<2> The `@timestamp` field inherited from the "ct2" component template
+<3> Any overlapping templates that would have matched, but have lower priority
+
+When simulating a template and specifying a template in the body of the request, the simulated
+template is not added to the existing templates, it is only used for the simulation.
+
 ===== Index template with index aliases
 
 You can include <<indices-aliases,index aliases>> in an index template.

rest-api-spec/src/main/resources/rest-api-spec/api/indices.simulate_template.json

@@ -0,0 +1,51 @@
+{
+  "indices.simulate_template":{
+    "documentation":{
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-templates.html",
+      "description": "Simulate resolving the given template name or body"
+    },
+    "stability":"stable",
+    "url":{
+      "paths":[
+        {
+          "path":"/_index_template/_simulate",
+          "methods":[
+            "POST"
+          ]
+        },
+        {
+          "path":"/_index_template/_simulate/{name}",
+          "methods":[
+            "POST"
+          ],
+          "parts":{
+            "name":{
+              "type":"string",
+              "description":"The name of the index template"
+            }
+          }
+        }
+      ]
+    },
+    "params":{
+      "create":{
+        "type":"boolean",
+        "description":"Whether the index template we optionally defined in the body should only be dry-run added if new or can also replace an existing one",
+        "default":false
+      },
+      "cause":{
+        "type":"string",
+        "description":"User defined reason for dry-run creating the new template for simulation purposes",
+        "default":false
+      },
+      "master_timeout":{
+        "type":"time",
+        "description":"Specify timeout for connection to master"
+      }
+    },
+    "body":{
+      "description":"New index template definition to be simulated, if no index template name is specified",
+      "required":false
+    }
+  }
+}

rest-api-spec/src/main/resources/rest-api-spec/test/indices.simulate_index_template/10_basic.yml

@@ -1,8 +1,8 @@
 ---
 "Simulate index template without new template in the body":
   - skip:
-      version: " - 7.7.99"
-      reason: "simulate index template API unavailable before 7.8"
+      version: " - 7.8.99"
+      reason: "simulate index template API format changed in 7.9 to drop _doc"
       features: ["default_shards"]
 
   - do:
@@ -25,14 +25,14 @@
 
   - match: {template.settings.index.number_of_shards: "1"}
   - match: {template.settings.index.number_of_replicas: "0"}
-  - match: {template.mappings._doc.properties.field.type: "keyword"}
+  - match: {template.mappings.properties.field.type: "keyword"}
   - match: {overlapping: []}
 
 ---
 "Simulate index template specifying a new template":
   - skip:
-      version: " - 7.7.99"
-      reason: "simulate index template API unavailable before 7.8"
+      version: " - 7.8.99"
+      reason: "simulate index template API format changed in 7.9 to drop _doc"
       features: ["default_shards"]
 
   - do:
@@ -77,7 +77,7 @@
 
   - match: {template.settings.index.blocks.write: "true"}
   - match: {template.settings.index.number_of_replicas: "2"}
-  - match: {template.mappings._doc.properties.ct_field.type: "keyword"}
+  - match: {template.mappings.properties.ct_field.type: "keyword"}
   - match: {overlapping.0.name: existing_test}
   - match: {overlapping.0.index_patterns: ["te*"]}
   - length: {template.aliases: 1}
@@ -86,8 +86,8 @@
 ---
 "Simulate index template with index not matching any template":
   - skip:
-      version: " - 7.7.99"
-      reason: "simulate index template API unavailable before 7.8"
+      version: " - 7.8.99"
+      reason: "simulate index template API format changed in 7.9 to drop _doc"
       features: allowed_warnings
 
   - do:
@@ -116,8 +116,8 @@
 ---
 "Simulate index matches overlapping V1 and V2 templates":
   - skip:
-      version: " - 7.7.99"
-      reason: "simulate index template API unavailable before 7.8"
+      version: " - 7.8.99"
+      reason: "simulate index template API format changed in 7.9 to drop _doc"
       features: ["allowed_warnings", "default_shards"]
 
   - do:
@@ -170,7 +170,7 @@
 
   - match: {template.settings.index.number_of_shards: "1"}
   - match: {template.settings.index.number_of_replicas: "0"}
-  - match: {template.mappings._doc.properties.field.type: "keyword"}
+  - match: {template.mappings.properties.field.type: "keyword"}
   - match: {overlapping.0.name: v1_template}
   - match: {overlapping.0.index_patterns: ["t*", "t1*"]}
   - match: {overlapping.1.name: v2_template}