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

CHANGELOG.asciidoc

@@ -24,6 +24,7 @@ https://github.com/elastic/apm-server/compare/6.3\...master[View commits]
 - Add source_mapping.elasticsearch configuration option {pull}1114[1114].
 - Add /v1/metrics endpoint {pull}1000[1000] {pull}1121[1121].
 - Push onboarding doc to separate ES index {pull}1159[1159].
+- Deprecate usage of `apm-server setup` {pull}1142[1142].
 
 
 [[release-notes-6.3]]

_meta/beat.yml

@@ -155,7 +155,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
@@ -197,51 +241,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

apm-server.yml

@@ -155,7 +155,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
@@ -197,51 +241,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

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-rum>>
 * <<using-environ-vars>>
 * <<configuration-path>>

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,18 +493,29 @@ environment without actually running {beatname_uc} and ingesting data.
 
 *FLAGS*
 
+ifndef::deprecate_dashboard_loading[] 
 *`--dashboards`*::
 Sets up the Kibana dashboards only. This option loads the dashboards from the
 {beatname_uc} package. For more options, such as loading customized dashboards,
 see {beatsdevguide}/import-dashboards.html[Importing Existing Beat Dashboards]
 in the _Beats Developer Guide_.
+endif::[]
+
+ifdef::deprecate_dashboard_loading[] 
+*`--dashboards` (deprecated)*::
+Sets up the Kibana dashboards only.
+endif::[]
 
 *`-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`*::

docs/copied-from-beats/dashboardsconfig.asciidoc

@@ -10,7 +10,7 @@
 //////////////////////////////////////////////////////////////////////////
 
 [[configuration-dashboards]]
-== Load the Kibana dashboards
+== Load the Kibana dashboards (deprecated)
 
 {beatname_uc} comes packaged with example Kibana dashboards, visualizations,
 and searches for visualizing {beatname_uc} data in Kibana.

docs/copied-from-beats/outputconfig.asciidoc

@@ -216,10 +216,21 @@ The index name to write events to. The default is
 +"{beatname_lc}-%\{[beat.version]\}-%\{+yyyy.MM.dd\}"+ (for example,
 +"{beatname_lc}-{version}-2017.04.26"+). If you change this setting, you also
 need to configure the `setup.template.name` and `setup.template.pattern` options
-(see <<configuration-template>>). If you are using the pre-built Kibana
-dashboards, you also need to set the `setup.dashboards.index` option (see
-<<configuration-dashboards>>).
+(see <<configuration-template>>). 
 
+ifndef::deprecate_dashboard_loading[] 
+
+If you are using the pre-built Kibana dashboards, 
+you also need to set the `setup.dashboards.index` option (see <<configuration-dashboards>>).
+
+endif::[]
+
+ifdef::deprecate_dashboard_loading[] 
+
+If you are using the pre-built Kibana dashboards, 
+you also need to set the index pattern properly when loading the dashboards via the Kibana UI.
+
+endif::[]
 
 ===== `indices`