make template required when template_api is provided

Author: yaauie

docs/index.asciidoc

@@ -1084,18 +1084,14 @@ 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.
-
-NOTE: The format of template provided to <<plugins-{type}s-{plugin}-template>> needs to match the template API being used.
+  * 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`
+
+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