make template required when template_api is provided

Author: yaauie

docs/index.asciidoc

@@ -1077,25 +1077,22 @@ the *$JDK_HOME/conf/security/java.security* configuration file. That is, `TLSv1.
 
   * Value type is <<path,path>>
   * There is no default value for this setting.
+  * When a `template` is provided, you may also configure <<plugins-{type}s-{plugin}-template_api>> as a hint about the format of the provided template.
 
 You can set the path to your own template here, if you so desire.
 If not set, the included template will be used.
 
 [id="plugins-{type}s-{plugin}-template_api"]
 ===== `template_api`
 
-  * Value can be any of: `auto`, `legacy`, `composable`
-  * Default value is `auto`
-
-The default setting of `auto` will use
-{ref}/index-templates.html[index template API] to create index template, if the
-Elasticsearch cluster is running Elasticsearch version `8.0.0` or higher,
-and use {ref}/indices-templates-v1.html[legacy template API] otherwise.
-
-Setting this flag to `legacy` will use legacy template API to create index template.
-Setting this flag to `composable` will use index template API to create index template.
+  * Value can be any of:
+  ** `composable`: maps to composable {ref}/index-templates.html[index template API]
+  ** `legacy`: maps to the {ref}/indices-templates-v1.html[legacy template API]
+  * The default value is determined based on which version of Elasticsearch we are connected to:
+  ** for {es} 7.x or older, the default is `legacy`
+  ** for {es} 8.0+, the default is `composable`
 
-NOTE: The format of template provided to <<plugins-{type}s-{plugin}-template>> needs to match the template API being used.
+This is a hint for the format of the provided <<plugins-{type}s-{plugin}-template>>.
 
 [id="plugins-{type}s-{plugin}-template_name"]
 ===== `template_name`

lib/logstash/outputs/elasticsearch.rb

@@ -279,6 +279,8 @@ class LogStash::Outputs::ElasticSearch < LogStash::Outputs::Base
   def initialize(*params)
     super
     setup_ecs_compatibility_related_defaults
+
+    raise LogStash::ConfigurationError("`template_api` is not allowed unless a `template` is also provided") if original_params.include?('template_api') && !original_params.include?('template')
   end
 
   def register

lib/logstash/outputs/elasticsearch/template_manager.rb

@@ -7,15 +7,15 @@ class TemplateManager
     def self.install_template(plugin)
       return unless plugin.manage_template
 
-      if plugin.maximum_seen_major_version < 8 && plugin.template_api == 'auto'
-        plugin.logger.warn("`template_api => auto` resolved to `legacy` since we are connected to " + "Elasticsearch #{plugin.maximum_seen_major_version}, " +
-                           "but will resolve to `composable` the first time it connects to Elasticsearch 8+. " +
-                           "We recommend either setting `template_api => legacy` to continue providing legacy-style templates, " +
-                           "or migrating your template to the composable style and setting `template_api => composable`. " +
-                           "The legacy template API is slated for removal in Elasticsearch 9.")
-      end
-
       if plugin.template
+        if plugin.maximum_seen_major_version < 8 && plugin.template_api == 'auto'
+          plugin.logger.warn("`template_api => auto` resolved to `legacy` since we are connected to " + "Elasticsearch #{plugin.maximum_seen_major_version}, " +
+                               "but will resolve to `composable` the first time it connects to Elasticsearch 8+. " +
+                               "We recommend either setting `template_api => legacy` to continue providing legacy-style templates, " +
+                               "or migrating your template to the composable style and setting `template_api => composable`. " +
+                               "The legacy template API is slated for removal in Elasticsearch 9.")
+        end
+
         plugin.logger.info("Using mapping template from", :path => plugin.template)
         template = read_template_file(plugin.template)
       else
@@ -82,12 +82,11 @@ def self.read_template_file(template_path)
     end
 
     def self.template_endpoint(plugin)
-      if plugin.template_api == 'auto'
-        plugin.maximum_seen_major_version < 8 ? LEGACY_TEMPLATE_ENDPOINT : INDEX_TEMPLATE_ENDPOINT
-      elsif plugin.template_api.to_s == 'legacy'
-        LEGACY_TEMPLATE_ENDPOINT
+      case plugin.template_api.to_s
+      when 'composable' then INDEX_TEMPLATE_ENDPOINT
+      when 'legacy'     then LEGACY_TEMPLATE_ENDPOINT
       else
-        INDEX_TEMPLATE_ENDPOINT
+        plugin.maximum_seen_major_version < 8 ? LEGACY_TEMPLATE_ENDPOINT : INDEX_TEMPLATE_ENDPOINT
       end
     end