Docs: Add deprecation check for dashboard loading. (#7675)

For APM Server the recommended way of loading dashboards and Kibana index pattern will be through the Kibana UI from 6.4 on. Since the docs are based on the libbeat docs we need to add a deprecation flag for dashboard and index pattern related documentation.

relates to elastic/apm-server#1142

Author: simitt

libbeat/docs/command-reference.asciidoc

@@ -20,12 +20,22 @@
 :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 +49,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"]
@@ -391,8 +409,19 @@ 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.
+ifdef::deprecate_dashboard_loading[]
+deprecated[{deprecate_dashboard_loading}]
+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"]
 
@@ -431,13 +460,17 @@ Or:
 [[setup-command]]
 ==== `setup` command
 
-{setup-command-short-desc}.
+{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::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 +485,32 @@ 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[{deprecate_dashboard_loading}]
++
+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`*::

libbeat/docs/dashboardsconfig.asciidoc

@@ -11,6 +11,11 @@
 
 [[configuration-dashboards]]
 == Load the Kibana dashboards
+ifdef::deprecate_dashboard_loading[]
+
+deprecated[{deprecate_dashboard_loading}]
+
+endif::[]
 
 {beatname_uc} comes packaged with example Kibana dashboards, visualizations,
 and searches for visualizing {beatname_uc} data in Kibana.

libbeat/docs/outputconfig.asciidoc

@@ -216,10 +216,16 @@ 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>>).
 
+If you are using the pre-built Kibana dashboards,
+you also need to set the `setup.dashboards.index` option (see <<configuration-dashboards>>).
+
+ifdef::deprecate_dashboard_loading[]
+
+deprecated[{deprecate_dashboard_loading}]
+
+endif::[]
 
 ===== `indices`
 
@@ -378,7 +384,7 @@ The Logstash output sends events directly to Logstash by using the lumberjack
 protocol, which runs over TCP. Logstash allows for additional processing and routing of
 generated events.
 
-include::../../libbeat/docs/shared-logstash-config.asciidoc[]
+include::./shared-logstash-config.asciidoc[]
 
 ==== Accessing metadata fields
 

libbeat/docs/shared-kibana-config.asciidoc

@@ -11,6 +11,11 @@
 
 [[setup-kibana-endpoint]]
 == Set up the Kibana endpoint
+ifdef::deprecate_dashboard_loading[]
+
+deprecated[{deprecate_dashboard_loading}]
+
+endif::[]
 
 ifeval::["{beatname_lc}" == "apm-server"]
 The Kibana dashboards are loaded into Kibana via the Kibana API.

libbeat/docs/shared-template-load.asciidoc

@@ -94,18 +94,37 @@ that you specify should include the root name of the index plus version and
 date information. You also need to configure the `setup.template.name` and
 `setup.template.pattern` options to match the new name. For example:
 +
+ifndef::deprecate_dashboard_loading[]
+
 ["source","sh",subs="attributes,callouts"]
 -----
 output.elasticsearch.index: "customname-%{[beat.version]}-%{+yyyy.MM.dd}"
 setup.template.name: "customname"
 setup.template.pattern: "customname-*"
 setup.dashboards.index: "customname-*" <1>
 -----
+
 <1> If you plan to
 <<load-kibana-dashboards, set up the Kibana dashboards>>, also set
 this option to overwrite the index name defined in the dashboards and index
 pattern.
 
+endif::[]
+
+ifdef::deprecate_dashboard_loading[]
+
+["source","sh",subs="attributes,callouts"]
+-----
+output.elasticsearch.index: "customname-%{[beat.version]}-%{+yyyy.MM.dd}"
+setup.template.name: "customname"
+setup.template.pattern: "customname-*"
+-----
++
+Also ensure to change the index name accordingly in the Kibana dashboards,
+when loading via the Kibana UI.
+
+endif::[]
+
 See <<configuration-template>> for the full list of configuration options.