Docs: deprecate loading dashboards and index pattern.

Add deprecation notes to apm-server.yml and docs for loading dashboards and index patterns via Kibana. Add deprecation note for setting up Kibana endpoint as it won't be needed any more. implements elastic#1135
simitt · Jul 17, 2018 · ddb5458 · ddb5458
1 parent f4875ed
commit ddb5458
Show file tree

Hide file tree

Showing 14 changed files with 252 additions and 289 deletions.
diff --git a/_meta/beat.yml b/_meta/beat.yml
@@ -141,7 +141,51 @@ setup.template.settings:
     #number_of_routing_shards: 30
 
 
-#============================== Dashboards =====================================
+#============================== Template =====================================
+
+# A template is used to set the mapping in Elasticsearch
+# By default template loading is enabled and the template is loaded.
+# These settings can be adjusted to load your own template or overwrite existing ones.
+
+# Set to false to disable template loading.
+#setup.template.enabled: true
+
+# Template name. By default the template name is "apm-%{[beat.version]}"
+# The template name and pattern has to be set in case the elasticsearch index pattern is modified.
+#setup.template.name: "apm-%{[beat.version]}"
+
+# Template pattern. By default the template pattern is "apm-%{[beat.version]}-*" to apply to the default index settings.
+# The first part is the version of the beat and then -* is used to match all daily indices.
+# The template name and pattern has to be set in case the elasticsearch index pattern is modified.
+#setup.template.pattern: "apm-%{[beat.version]}-*"
+
+# Path to fields.yml file to generate the template
+#setup.template.fields: "${path.config}/fields.yml"
+
+# Overwrite existing template
+#setup.template.overwrite: false
+
+# Elasticsearch template settings
+#setup.template.settings:
+
+  # A dictionary of settings to place into the settings.index dictionary
+  # of the Elasticsearch template. For more details, please check
+  # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html
+  #index:
+    #number_of_shards: 1
+    #codec: best_compression
+    #number_of_routing_shards: 30
+
+  # A dictionary of settings for the _source field. For more details, please check
+  # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html
+  #_source:
+    #enabled: false
+
+
+#============================== Deprecated: Dashboards =====================================
+#
+# Deprecated: Loading dashboards from the APM Server into Kibana is deprecated from 6.4 on.
+#             We suggest to use the Kibana UI to load APM Server dashboards and index pattern instead.
 #
 # These settings control loading the sample dashboards to the Kibana index. Loading
 # the dashboards are disabled by default and can be enabled either by setting the
@@ -183,51 +227,14 @@ setup.template.settings:
 #setup.dashboards.retry.maximum: 0
 
 
-#============================== Template =====================================
-
-# A template is used to set the mapping in Elasticsearch
-# By default template loading is enabled and the template is loaded.
-# These settings can be adjusted to load your own template or overwrite existing ones.
+#============================== Deprecated: Kibana =====================================
 
-# Set to false to disable template loading.
-#setup.template.enabled: true
-
-# Template name. By default the template name is "apm-%{[beat.version]}"
-# The template name and pattern has to be set in case the elasticsearch index pattern is modified.
-#setup.template.name: "apm-%{[beat.version]}"
-
-# Template pattern. By default the template pattern is "apm-%{[beat.version]}-*" to apply to the default index settings.
-# The first part is the version of the beat and then -* is used to match all daily indices.
-# The template name and pattern has to be set in case the elasticsearch index pattern is modified.
-#setup.template.pattern: "apm-%{[beat.version]}-*"
-
-# Path to fields.yml file to generate the template
-#setup.template.fields: "${path.config}/fields.yml"
-
-# Overwrite existing template
-#setup.template.overwrite: false
-
-# Elasticsearch template settings
-#setup.template.settings:
-
-  # A dictionary of settings to place into the settings.index dictionary
-  # of the Elasticsearch template. For more details, please check
-  # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html
-  #index:
-    #number_of_shards: 1
-    #codec: best_compression
-    #number_of_routing_shards: 30
-
-  # A dictionary of settings for the _source field. For more details, please check
-  # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html
-  #_source:
-    #enabled: false
-
-
-#============================== Kibana =====================================
+# Deprecated: Starting with APM Server version 6.4, loading dashboards and index pattern 
+#             from the APM Server into Kibana is deprecated.
+#             We suggest to use the Kibana UI to load APM Server dashboards and index pattern instead.
+#
+#             Setting up a Kibana endpoint is not necessary when loading the index pattern and dashboards via the UI.
 
-# Starting with Beats version 6.0.0, the dashboards are loaded via the Kibana API.
-# This requires a Kibana endpoint configuration.
 #setup.kibana:
 
   # Kibana Host

diff --git a/apm-server.yml b/apm-server.yml
@@ -141,7 +141,51 @@ setup.template.settings:
     #number_of_routing_shards: 30
 
 
-#============================== Dashboards =====================================
+#============================== Template =====================================
+
+# A template is used to set the mapping in Elasticsearch
+# By default template loading is enabled and the template is loaded.
+# These settings can be adjusted to load your own template or overwrite existing ones.
+
+# Set to false to disable template loading.
+#setup.template.enabled: true
+
+# Template name. By default the template name is "apm-%{[beat.version]}"
+# The template name and pattern has to be set in case the elasticsearch index pattern is modified.
+#setup.template.name: "apm-%{[beat.version]}"
+
+# Template pattern. By default the template pattern is "apm-%{[beat.version]}-*" to apply to the default index settings.
+# The first part is the version of the beat and then -* is used to match all daily indices.
+# The template name and pattern has to be set in case the elasticsearch index pattern is modified.
+#setup.template.pattern: "apm-%{[beat.version]}-*"
+
+# Path to fields.yml file to generate the template
+#setup.template.fields: "${path.config}/fields.yml"
+
+# Overwrite existing template
+#setup.template.overwrite: false
+
+# Elasticsearch template settings
+#setup.template.settings:
+
+  # A dictionary of settings to place into the settings.index dictionary
+  # of the Elasticsearch template. For more details, please check
+  # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html
+  #index:
+    #number_of_shards: 1
+    #codec: best_compression
+    #number_of_routing_shards: 30
+
+  # A dictionary of settings for the _source field. For more details, please check
+  # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html
+  #_source:
+    #enabled: false
+
+
+#============================== Deprecated: Dashboards =====================================
+#
+# Deprecated: Loading dashboards from the APM Server into Kibana is deprecated from 6.4 on.
+#             We suggest to use the Kibana UI to load APM Server dashboards and index pattern instead.
 #
 # These settings control loading the sample dashboards to the Kibana index. Loading
 # the dashboards are disabled by default and can be enabled either by setting the
@@ -183,51 +227,14 @@ setup.template.settings:
 #setup.dashboards.retry.maximum: 0
 
 
-#============================== Template =====================================
-
-# A template is used to set the mapping in Elasticsearch
-# By default template loading is enabled and the template is loaded.
-# These settings can be adjusted to load your own template or overwrite existing ones.
+#============================== Deprecated: Kibana =====================================
 
-# Set to false to disable template loading.
-#setup.template.enabled: true
-
-# Template name. By default the template name is "apm-%{[beat.version]}"
-# The template name and pattern has to be set in case the elasticsearch index pattern is modified.
-#setup.template.name: "apm-%{[beat.version]}"
-
-# Template pattern. By default the template pattern is "apm-%{[beat.version]}-*" to apply to the default index settings.
-# The first part is the version of the beat and then -* is used to match all daily indices.
-# The template name and pattern has to be set in case the elasticsearch index pattern is modified.
-#setup.template.pattern: "apm-%{[beat.version]}-*"
-
-# Path to fields.yml file to generate the template
-#setup.template.fields: "${path.config}/fields.yml"
-
-# Overwrite existing template
-#setup.template.overwrite: false
-
-# Elasticsearch template settings
-#setup.template.settings:
-
-  # A dictionary of settings to place into the settings.index dictionary
-  # of the Elasticsearch template. For more details, please check
-  # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html
-  #index:
-    #number_of_shards: 1
-    #codec: best_compression
-    #number_of_routing_shards: 30
-
-  # A dictionary of settings for the _source field. For more details, please check
-  # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html
-  #_source:
-    #enabled: false
-
-
-#============================== Kibana =====================================
+# Deprecated: Starting with APM Server version 6.4, loading dashboards and index pattern 
+#             from the APM Server into Kibana is deprecated.
+#             We suggest to use the Kibana UI to load APM Server dashboards and index pattern instead.
+#
+#             Setting up a Kibana endpoint is not necessary when loading the index pattern and dashboards via the UI.
 
-# Starting with Beats version 6.0.0, the dashboards are loaded via the Kibana API.
-# This requires a Kibana endpoint configuration.
 #setup.kibana:
 
   # Kibana Host

diff --git a/docs/configuring.asciidoc b/docs/configuring.asciidoc
@@ -12,8 +12,8 @@ The following topics describe how to configure APM Server:
 * <<configuration-ssl>>
 * <<configuration-template>>
 * <<configuration-logging>>
-* <<setup-kibana-endpoint>>
-* <<configuration-dashboards>>
+* <<setup-kibana-endpoint, Set up the Kibana endpoint (deprecated)>>
+* <<configuration-dashboards, Load the Kibana dashboards (deprecated)>>
 * <<configuration-frontend>>
 * <<using-environ-vars>>
 * <<configuration-path>>

diff --git a/docs/copied-from-beats/command-reference.asciidoc b/docs/copied-from-beats/command-reference.asciidoc
@@ -20,12 +20,23 @@
 :modules-command-short-desc: Manages configured modules
 :run-command-short-desc: Runs {beatname_uc}. This command is used by default if you start {beatname_uc} without specifying a command
 
+ifndef::deprecate_dashboard_loading[] 
+
 ifdef::has_ml_jobs[]
 :setup-command-short-desc: Sets up the initial environment, including the index template, Kibana dashboards (when available), and machine learning jobs (when available)
 endif::[]
 
 ifndef::has_ml_jobs[]
-:setup-command-short-desc: Sets up the initial environment, including the index template, Kibana dashboards (when available)
+:setup-command-short-desc: Sets up the initial environment, including the index template and Kibana dashboards (when available)
+endif::[]
+
+endif::[]
+
+ifdef::deprecate_dashboard_loading[] 
+
+:setup-command-short-desc: Sets up the initial environment, 
+including the ES index template and Kibana dashboards (deprecated).
+
 endif::[]
 
 :test-command-short-desc: Tests the configuration
@@ -39,9 +50,17 @@ endif::[]
 <titleabbrev>Command reference</titleabbrev>
 ++++
 
+ifndef::deprecate_dashboard_loading[] 
 {beatname_uc} provides a command-line interface for starting {beatname_uc} and
-performing common tasks, like testing configuration files and loading
-dashboards. The command-line also supports <<global-flags,global flags>>
+performing common tasks, like testing configuration files and loading dashboards. 
+endif::[]
+
+ifdef::deprecate_dashboard_loading[] 
+{beatname_uc} provides a command-line interface for starting {beatname_uc} and
+performing common tasks, like testing configuration files and loading dashboards (deprecated).
+endif::[]
+
+The command-line also supports <<global-flags,global flags>>
 for controlling global behaviors.
 
 ifeval::["{beatname_lc}"!="winlogbeat"]
@@ -390,9 +409,24 @@ the end of the file is reached. By default harvesters are closed after
 
 endif::[]
 
-*`--setup`*::
-Loads the sample Kibana dashboards. If you want to load the dashboards without
-running {beatname_uc}, use the <<setup-command,`setup`>> command instead.
+ifndef::deprecate_dashboard_loading[] 
+*`--setup`*:: 
+endif::[]
+
+ifdef::deprecate_dashboard_loading[] 
+*`--setup (deprecated)`*:: 
+endif::[]
+
+ifdef::has_ml_jobs[]
+Loads the initial setup, including Elasticsearch template, Kibana index pattern, 
+Kibana dashboards and Machine learning jobs.
+endif::[]
+
+ifndef::has_ml_jobs[]
+Loads the initial setup, including Elasticsearch template, Kibana index pattern and Kibana dashboards.
+endif::[]
+
+If you want to use the command without running {beatname_uc}, use the <<setup-command,`setup`>> command instead.
 
 ifeval::["{beatname_lc}"=="metricbeat"]
 
@@ -434,10 +468,17 @@ Or:
 {setup-command-short-desc}.
 
 * The index template ensures that fields are mapped correctly in Elasticsearch.
+
 * The Kibana dashboards make it easier for you to visualize {beatname_uc} data
 in Kibana.
+ifdef::deprecate_dashboard_loading[] 
+(deprecated)
+endif::[]
+
+ifdef::has_ml_jobs[]
 * The machine learning jobs contain the configuration information and metadata
 necessary to analyze data for anomalies.
+endif::[]
 
 Use this command instead of `run --setup` when you want to set up the
 environment without actually running {beatname_uc} and ingesting data.
@@ -452,15 +493,25 @@ environment without actually running {beatname_uc} and ingesting data.
 
 *FLAGS*
 
+ifndef::deprecate_dashboard_loading[] 
 *`--dashboards`*::
+endif::[]
+ifdef::deprecate_dashboard_loading[] 
+*`--dashboards` (deprecated)*::
+endif::[]
+
 Sets up the Kibana dashboards only.
 
 *`-h, --help`*::
 Shows help for the `setup` command.
 
+ifdef::has_ml_jobs[]
+
 *`--machine-learning`*::
 Sets up machine learning job configurations only.
 
+endif::[]
+
 ifeval::["{beatname_lc}"=="filebeat"]
 
 *`--modules MODULE_LIST`*::