[DOCS] Clarify security requirements for monitoring (#24881) (#25419)

docs/index.asciidoc

@@ -24,7 +24,7 @@ include::introduction.asciidoc[]
 
 include::setup.asciidoc[]
 
-include::monitoring/monitoring-kibana.asciidoc[]
+include::monitoring/configuring-monitoring.asciidoc[]
 
 include::security/securing-kibana.asciidoc[]
 

docs/monitoring/beats-details.asciidoc

@@ -1,6 +1,6 @@
 [role="xpack"]
 [[beats-page]]
-=== Beats Monitoring Metrics
+== Beats Monitoring Metrics
 ++++
 <titleabbrev>Beats Metrics</titleabbrev>
 ++++

docs/monitoring/cluster-alerts.asciidoc

@@ -1,6 +1,6 @@
 [role="xpack"]
 [[cluster-alerts]]
-=== Cluster Alerts
+== Cluster Alerts
 
 The *Monitoring > Clusters* page in {kib} summarizes the status of your Elastic
 stack. You can drill down into the metrics to view more information about your

docs/monitoring/configuring-monitoring.asciidoc

@@ -0,0 +1,26 @@
+[role="xpack"]
+[[configuring-monitoring]]
+== Configuring monitoring in {kib}
+++++
+<titleabbrev>Configuring monitoring</titleabbrev>
+++++
+
+If you enable the Elastic {monitor-features} in your cluster, you can 
+optionally collect metrics about {kib}:
+
+* <<monitoring-kibana>>
+* <<monitoring-metricbeat>>
+
+
+You can also use {kib} to visualize 
+monitoring data from across the {stack}:
+
+* <<monitoring-data>>
+
+To learn about monitoring in general, see 
+{stack-ov}/xpack-monitoring.html[Monitoring the {stack}]. 
+
+include::monitoring-kibana.asciidoc[]
+include::monitoring-metricbeat.asciidoc[]
+include::viewing-metrics.asciidoc[]
+include::{kib-repo-dir}/settings/monitoring-settings.asciidoc[]

docs/monitoring/elasticsearch-details.asciidoc

@@ -1,6 +1,6 @@
 [role="xpack"]
 [[elasticsearch-metrics]]
-=== {es} Monitoring Metrics
+== {es} Monitoring Metrics
 ++++
 <titleabbrev>{es} Metrics</titleabbrev>
 ++++

docs/monitoring/index.asciidoc

@@ -5,24 +5,28 @@
 [partintro]
 --
 
-{monitoring} in {kib} serves two separate purposes:
+The {kib} {monitor-features} serve two separate purposes:
 
-. To visualize monitoring data from across the Elastic Stack. You can view
-health and performance data for {es}, Logstash, and Beats in real time, as well
-as analyze past performance. For more information, see {xpack-ref}/xpack-monitoring.html[Monitoring the Elastic Stack].
+. To visualize monitoring data from across the {stack}. You can view health and 
+performance data for {es}, {ls}, and Beats in real time, as well as analyze past 
+performance. For more information, see 
+{stack-ov}/xpack-monitoring.html[Monitoring the {stack}].
 
 . To monitor {kib} itself and route that data to the monitoring cluster.
 
-If you enable {monitoring} across the Elastic Stack, a monitoring agent runs on
-each {es} node, Logstash node, {kib} instance, and Beat to collect and index
-metrics. Each node and instance is considered unique based on its persistent
+If you enable monitoring across the {stack}, each {es} node, {ls} node, {kib} 
+instance, and Beat is considered unique based on its persistent
 UUID, which is written to the <<settings,`path.data`>> directory when the node
-or instance starts.
+or instance starts. 
 
-* <<monitoring-kibana>>
-* <<monitoring-data>>
+NOTE: Watcher must be enabled to view cluster alerts. If you have a Basic
+license, Top Cluster Alerts are not displayed.
 
 --
 
-include::viewing-metrics.asciidoc[]
+include::beats-details.asciidoc[]
+include::cluster-alerts.asciidoc[]
+include::elasticsearch-details.asciidoc[]
+include::kibana-details.asciidoc[]
+include::logstash-details.asciidoc[]
 include::monitoring-troubleshooting.asciidoc[]

docs/monitoring/kibana-details.asciidoc

@@ -1,6 +1,6 @@
 [role="xpack"]
 [[kibana-page]]
-=== {kib} Monitoring Metrics
+== {kib} Monitoring Metrics
 ++++
 <titleabbrev>{kib} Metrics</titleabbrev>
 ++++

docs/monitoring/logstash-details.asciidoc

@@ -1,6 +1,6 @@
 [role="xpack"]
 [[logstash-page]]
-=== Logstash Monitoring Metrics
+== Logstash Monitoring Metrics
 ++++
 <titleabbrev>Logstash Metrics</titleabbrev>
 ++++

docs/monitoring/monitoring-kibana.asciidoc

@@ -1,11 +1,11 @@
 [role="xpack"]
 [[monitoring-kibana]]
-== Configuring monitoring in {kib}
+=== Collecting {kib} monitoring data
 ++++
-<titleabbrev>Configuring monitoring</titleabbrev>
+<titleabbrev>Collecting monitoring data</titleabbrev>
 ++++
 
-If you enable the collection of monitoring data in your cluster, you can 
+If you enable the Elastic {monitor-features} in your cluster, you can 
 optionally collect metrics about {kib}. 
 
 The following method involves sending the metrics to the production cluster, 
@@ -15,10 +15,34 @@ method, see <<monitoring-metricbeat>>.
 To learn about monitoring in general, see 
 {stack-ov}/xpack-monitoring.html[Monitoring the {stack}]. 
 
-. Enable the collection of monitoring data in {stack}. Set 
-`xpack.monitoring.collection.enabled` to `true` on the production cluster.  +
+. Set the `xpack.monitoring.collection.enabled` setting to `true` on each
+node in the production cluster. By default, it is is disabled (`false`). 
 + 
 --
+NOTE: You can specify this setting in either the `elasticsearch.yml` on each 
+node or across the cluster as a dynamic cluster setting. If {es} 
+{security-features} are enabled, you must have `monitor` cluster privileges to 
+view the cluster settings and `manage` cluster privileges to change them.
+
+--
+
+** To update the cluster settings in {kib}:
+
+... Open {kib} in your web browser. 
++
+--
+By default, if you are running {kib} locally, go to `http://localhost:5601/`. 
+
+If {es} {security-features} are enabled, log in. 
+--
+
+... In the side navigation, click *Monitoring*. If data collection is disabled, 
+you are prompted to turn it on. 
+
+** From the Console or command line, set `xpack.monitoring.collection.enabled` 
+to `true` on the production cluster. +
++
+--
 For example, you can use the following APIs to review and change this setting:
 
 [source,js]
@@ -62,7 +86,7 @@ as `https://<your_production_cluster>:9200` in this setting.
 
 --
 
-. If {security} is enabled on the production cluster:
+. If the Elastic {security-features} are enabled on the production cluster:
 
 .. Verify that there is a
 valid user ID and password in the `elasticsearch.username` and
@@ -95,6 +119,3 @@ For more information, see <<using-kibana-with-security>>.
 . <<start-stop,Start {kib}>>.
 
 . <<monitoring-data,View the monitoring data in {kib}>>. 
-
-include::monitoring-metricbeat.asciidoc[]
-include::{kib-repo-dir}/settings/monitoring-settings.asciidoc[]

docs/monitoring/monitoring-metricbeat.asciidoc

@@ -1,8 +1,13 @@
 [role="xpack"]
 [[monitoring-metricbeat]]
-=== Monitoring {kib} with {metricbeat}
+=== Collecting {kib} monitoring data with {metricbeat}
+++++
+<titleabbrev>Collecting monitoring data with {metricbeat}</titleabbrev>
+++++
 
-beta[] In 6.4 and later, you can use {metricbeat} to collect data about {kib} 
+beta[]
+
+In 6.4 and later, you can use {metricbeat} to collect data about {kib} 
 and ship it to the monitoring cluster, rather than routing it through the 
 production cluster as described in <<monitoring-kibana>>. 
 
@@ -11,9 +16,51 @@ image::monitoring/images/metricbeat.png[Example monitoring architecture]
 To learn about monitoring in general, see 
 {stack-ov}/xpack-monitoring.html[Monitoring the {stack}]. 
 
-. Enable the collection of monitoring data. Set 
-`xpack.monitoring.collection.enabled` to `true` on the production cluster. +
-+ 
+. Disable the default collection of {kib} monitoring metrics. +
++
+--
+Add the following setting in the {kib} configuration file (`kibana.yml`): 
+
+[source,yaml]
+----------------------------------
+xpack.monitoring.kibana.collection.enabled: false
+----------------------------------
+
+Leave the `xpack.monitoring.enabled` set to its default value (`true`). 
+
+For more information, see 
+<<monitoring-settings-kb,Monitoring settings in {kib}>>.
+--
+
+. <<start-stop,Start {kib}>>.
+
+. Set the `xpack.monitoring.collection.enabled` setting to `true` on 
+each node in the production cluster. By default, it is disabled (`false`).
++
+--
+NOTE: You can specify this setting in either the `elasticsearch.yml` on each 
+node or across the cluster as a dynamic cluster setting. If {es} 
+{security-features} are enabled, you must have `monitor` cluster privileges to 
+view the cluster settings and `manage` cluster privileges to change them.
+
+--
+
+** In {kib}:
+
+... Open {kib} in your web browser. 
++
+--
+If you are running {kib} locally, go to `http://localhost:5601/`. 
+
+If the Elastic {security-features} are enabled, log in. 
+--
+
+... In the side navigation, click *Monitoring*. If data collection is disabled, 
+you are prompted to turn it on. 
+
+** From the Console or command line, set `xpack.monitoring.collection.enabled` 
+to `true` on the production cluster. +
++
 --
 For example, you can use the following APIs to review and change this setting:
 
@@ -33,22 +80,6 @@ For more information, see {ref}/monitoring-settings.html[Monitoring settings in
 and {ref}/cluster-update-settings.html[Cluster update settings].
 --
 
-. Disable the default collection of {kib} monitoring metrics. +
-+
---
-Add the following setting in the {kib} configuration file (`kibana.yml`): 
-
-[source,yaml]
-----------------------------------
-xpack.monitoring.kibana.collection.enabled: false
-----------------------------------
-
-Leave the `xpack.monitoring.enabled` set to its default value (`true`). 
-
-For more information, see 
-<<monitoring-settings-kb,Monitoring settings in {kib}>>.
---
-
 . {metricbeat-ref}/metricbeat-installation.html[Install {metricbeat}] on the 
 same server as {kib}.
 
@@ -80,25 +111,21 @@ You must specify the following settings in the `modules.d/kibana.yml` file:
     - stats
   period: 10s
   hosts: ["http://localhost:5601"] <1>
-  xpack.enabled: true
+  xpack.enabled: true <2>
 ----------------------------------
-<1> This setting identifies the host and port number that are used to access {kib}.  
-
+<1> This setting identifies the host and port number that are used to access {kib}. 
+<2> This setting ensures that {kib} can read the monitoring data successfully. 
+That is to say, it's stored in the same location and format as monitoring data 
+that is sent by {ref}/es-monitoring-exporters.html[exporters].  
 --
 
-. If {security} is enabled, you must also provide a user ID and password so that 
-{metricbeat} can collect metrics successfully. 
+. If the Elastic {security-features} are enabled, you must also provide a user 
+ID and password so that {metricbeat} can collect metrics successfully. 
 
-.. Create or identify a user that you want to use to collect the metrics. 
-+
---
-TIP: There is a `remote_monitoring_user` built-in user that grants the privileges 
-necessary for {metricbeat} to monitor {stack} products. See 
-{stack-ov}/built-in-users.html[Built-in users].
-
-Alternatively, you can choose a different user and give them the 
+... Create a user on the production cluster that has the 
 `remote_monitoring_collector` {stack-ov}/built-in-roles.html[built-in role]. 
---
+Alternatively, use the `remote_monitoring_user` 
+{stack-ov}/built-in-users.html[built-in user].
 
 .. Add the `username` and `password` settings to the {kib} module configuration 
 file.
@@ -144,19 +171,14 @@ For more information about these configuration options, see
 
 --
 
-. If {security} is enabled on the monitoring cluster, you must provide a valid 
-user ID and password so that {metricbeat} can send metrics successfully. 
+. If the {es} {security-features} are enabled on the monitoring cluster, you 
+must provide a valid user ID and password so that {metricbeat} can send metrics 
+successfully. 
 
-.. Create or identify a user that you want to use to send the metrics. 
-+
---
-TIP: There is a `remote_monitoring_user` built-in user that grants the privileges 
-necessary for {metricbeat} to monitor {stack} products. See 
-{stack-ov}/built-in-users.html[Built-in users].
-
-Alternatively, you can choose a different user and give them the 
+... Create a user on the monitoring cluster that has the 
 `remote_monitoring_agent` {stack-ov}/built-in-roles.html[built-in role]. 
---
+Alternatively, use the `remote_monitoring_user` 
+{stack-ov}/built-in-users.html[built-in user].
 
 .. Add the `username` and `password` settings to the {es} output information in 
 the {metricbeat} configuration file (`metricbeat.yml`):
@@ -176,8 +198,6 @@ output.elasticsearch:
 HTTPS. For example, use a `hosts` setting like `https://es-mon-1:9200` in the 
 `metricbeat.yml` file. 
 
-. <<start-stop,Start {kib}>>.
-
 . {metricbeat-ref}/metricbeat-starting.html[Start {metricbeat}]. 
 
 . <<monitoring-data,View the monitoring data in {kib}>>. 

docs/monitoring/viewing-metrics.asciidoc

@@ -1,120 +1,105 @@
 [role="xpack"]
 [[monitoring-data]]
-== Viewing monitoring data in {kib}
+=== Viewing monitoring data in {kib}
 ++++
 <titleabbrev>Viewing monitoring data</titleabbrev>
 ++++
 
-You can use {kib} to monitor the health and performance of {es}, {ls}, {kib}, 
-and Beats. 
+After you collect monitoring data for one or more products in the {stack}, you 
+can configure {kib} to retrieve that information and display it in on the 
+*Monitoring* page. 
 
-TIP: If you have a dedicated monitoring cluster, the information is accessible
-even if the {es} cluster you're monitoring is not. You can send data from
-multiple clusters to the same monitoring cluster and view them all through the
-same instance of {kib}. To learn more about typical monitoring architectures 
-with separate production and monitoring clusters, see
-{xpack-ref}/how-monitoring-works.html[How monitoring works].
-
-. Optional: {ref}/configuring-monitoring.html[Configure monitoring in {es}]. If you want
-to use a separate monitoring cluster, see
-{xpack-ref}/monitoring-production.html[Monitoring in a production environment].
-
-. Optional: <<monitoring-kibana,Configure monitoring in {kib}>>.
-
-. Optional: {logstash-ref}/configuring-logstash.html[Configure monitoring in Logstash].
-
-. Optional: Configure monitoring in {auditbeat-ref}/monitoring.html[Auditbeat],
-{filebeat-ref}/monitoring.html[Filebeat],
-{heartbeat-ref}/monitoring.html[Heartbeat],
-{metricbeat-ref}/monitoring.html[Metricbeat],
-{packetbeat-ref}/monitoring.html[Packetbeat], and
-{winlogbeat-ref}/monitoring.html[Winlogbeat].
-
-. Configure {kib} to visualize monitoring data:
-
-.. Verify that `xpack.monitoring.ui.enabled` is set to `true`, which is the
-default value. For more information, see <<monitoring-settings-kb>>.
-
-.. Identify where to retrieve monitoring data from. If you want to use a
-separate _monitoring cluster_, set `xpack.monitoring.elasticsearch.url` in the
-`kibana.yml` file. Otherwise, the monitoring data is stored in the production
-cluster.
+. Identify where to retrieve monitoring data from. 
 +
 --
-TIP: If {security} is enabled on the monitoring cluster, use an HTTPS URL such
-as `https://<your_monitoring_cluster>:9200` in this setting.
+The cluster that contains the monitoring data is referred to 
+as the _monitoring cluster_. 
 
+TIP: If the monitoring data is stored on a *dedicated* monitoring cluster, it is 
+accessible even when the cluster you're monitoring is not. If you have at least 
+a gold license, you can send data from multiple clusters to the same monitoring 
+cluster and view them all through the same instance of {kib}. 
+
+By default, data is retrieved from the cluster specified in the 
+`elasticsearch.url` value in the `kibana.yml` file. If you want to retrieve it 
+from a different cluster, set `xpack.monitoring.elasticsearch.url`. 
+
+To learn more about typical monitoring architectures, 
+see {stack-ov}/how-monitoring-works.html[How monitoring works] and 
+{stack-ov}/monitoring-production.html[Monitoring in a production environment].
 --
 
-.. If {security} is enabled on the monitoring cluster, identify a user ID and 
-password that {kib} can use to retrieve monitoring data. Specify these values in 
-the `xpack.monitoring.elasticsearch.username` and 
+. Verify that `xpack.monitoring.ui.enabled` is set to `true`, which is the
+default value, in the `kibana.yml` file. For more information, see 
+<<monitoring-settings-kb>>.
+
+. If the Elastic {security-features} are enabled on the monitoring cluster, you 
+must provide a user ID and password so {kib} can retrieve the data. 
+
+.. Create a user that has the `monitoring_user` 
+{stack-ov}/built-in-roles.html[built-in role] on the monitoring cluster.
+
+.. Add the `xpack.monitoring.elasticsearch.username` and 
 `xpack.monitoring.elasticsearch.password` settings in the `kibana.yml` file.
 If these settings are omitted, {kib} uses the `elasticsearch.username` and
-`elasticsearch.password` setting values.
+`elasticsearch.password` setting values. For more 
+information, see {kibana-ref}/using-kibana-with-security.html[Configuring security in {kib}].
 
-.. If {security} is enabled on the monitoring cluster, configure {kib} to 
-encrypt communications between the {kib} server and the monitoring cluster. 
-Specify the `xpack.monitoring.elasticsearch.ssl.*` settings in the `kibana.yml` 
-file on the {kib} server.
+. (Optional) Configure {kib} to encrypt communications between the {kib} server 
+and the monitoring cluster. See <<configuring-tls>>. 
+
+. If the Elastic {security-features} are enabled on the {kib} server, only users 
+that have the authority to access {kib} indices and to read the monitoring indices 
+can use the monitoring dashboards. 
 +
 --
-For example, if you are using your own certificate authority to sign
-certificates, specify the location of the PEM file in the `kibana.yml` file:
-
-[source,yaml]
---------------------------------------------------------------------------------
-xpack.monitoring.elasticsearch.ssl.certificateAuthorities: /path/to/your/cacert.pem
---------------------------------------------------------------------------------
+NOTE: These users must exist on the monitoring cluster. If you are accessing a 
+remote monitoring cluster, you must use credentials that are valid on both the 
+{kib} server and the monitoring cluster.
 
 --
 
-. Open {kib} in your web browser and log in. 
+.. Create users that have the `monitoring_user` and `kibana_user` 
+{stack-ov}/built-in-roles.html[built-in roles].
+
+. Open {kib} in your web browser. 
 +
 --
-If you are running {kib} locally, go to `http://localhost:5601/`. 
+By default, if you are running {kib} locally, go to `http://localhost:5601/`. 
 
-If {security} is enabled on the {kib} server, to access {kib} and view the 
-monitoring dashboards, you must log in as a user who has the `kibana_user` and 
-`monitoring_user` roles. These roles have the necessary privileges to view the 
-monitoring dashboards. For more information, see 
-{stack-ov}/built-in-roles.html[Built-in roles].
-
-If you are accessing a remote monitoring cluster, you must log in to {kib}
-with credentials that are valid on both the {kib} server and the monitoring 
-cluster.
+If the Elastic {security-features} are enabled, log in. 
 --
 
-. In the side navigation, click *Monitoring*. The first time you open {kib}
-monitoring, data collection is
-disabled. You will be prompted to turn on data collection.
+. In the side navigation, click *Monitoring*. 
 +
-If you have permission to turn on data collection and there is data in the cluster,
-{kib} displays the monitoring dashboards.  You'll see cluster alerts
+--
+If data collection is disabled, you are prompted to turn on data collection. 
+If {es} {security-features} are enabled, you must have `manage` cluster 
+privileges to turn on data collection. 
+
+NOTE: If you are using a separate monitoring cluster, you do not need to turn on 
+data collection. The dashboards appear when there is data in the monitoring 
+cluster.  
+
+--
+
+You'll see cluster alerts
 that require your attention and a summary of the available monitoring metrics
 for {es}, Logstash, {kib}, and Beats. To view additional information, click the
-Overview, Nodes, Indices, or Instances links.
-+
+Overview, Nodes, Indices, or Instances links.  See <<xpack-monitoring>>. 
+
 [role="screenshot"]
 image::images/monitoring-dashboard.png[Monitoring dashboard]
-+
+
 If {kib} can't activate monitoring, here are some things to do:
-+
+
 * If you don't have permission to activate monitoring,
 contact your system administrator.
-+
+
 * If {kib} can't find monitoring data, set the time filter to
 “Last 1 hour”.  When monitoring data appears in your cluster, the page
 automatically refreshes with the monitoring summary.
-+
+
 * Check your `xpack.monitoring.elasticsearch.url` setting.
 See <<monitoring-settings-kb, Monitoring Settings in Kibana>>.
 
-
-
-include::cluster-alerts-license.asciidoc[]
-include::beats-details.asciidoc[]
-include::cluster-alerts.asciidoc[]
-include::elasticsearch-details.asciidoc[]
-include::kibana-details.asciidoc[]
-include::logstash-details.asciidoc[]

docs/security/securing-communications/index.asciidoc

@@ -58,7 +58,7 @@ For more information, see <<settings,{kib} configuration settings>>.
 +
 --
 NOTE: To perform this step, you must 
-{ref}/configuring-security.html[enable the {security} feature in {es}] or you 
+{ref}/configuring-security.html[enable the {es} {security-features}] or you 
 must have a proxy that provides an HTTPS endpoint for {es}. 
 
 --
@@ -89,3 +89,36 @@ Setting the `certificateAuthorities` property lets you use the default
 
 For more information, see <<settings,{kib} configuration settings>>. 
 --
+
+. (Optional) If the Elastic {monitor-features} are enabled, configure {kib} to 
+connect to the {es} monitoring cluster via HTTPS: 
++
+--
+NOTE: To perform this step, you must 
+{ref}/configuring-security.html[enable the {es} {security-features}] or you 
+must have a proxy that provides an HTTPS endpoint for {es}. 
+
+--
+
+.. Specify the HTTPS URL in the `xpack.monitoring.elasticsearch.url` setting in 
+the {kib} configuration file, `kibana.yml`
++
+--
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.monitoring.elasticsearch.url: "https://<your_monitoring_cluster>:9200"
+--------------------------------------------------------------------------------
+--
+
+.. Specify the `xpack.monitoring.elasticsearch.ssl.*` settings in the 
+`kibana.yml` file.
++
+--
+For example, if you are using your own certificate authority to sign
+certificates, specify the location of the PEM file in the `kibana.yml` file:
+
+[source,yaml]
+--------------------------------------------------------------------------------
+xpack.monitoring.elasticsearch.ssl.certificateAuthorities: /path/to/your/cacert.pem
+--------------------------------------------------------------------------------
+--