[Reporting/Docs] Add clarity to reporting concepts (#125175) (#125412)

* discourage setting enabled:false

* mark xpack.reporting.kibanaServer as experimental

* move kibanaServer section down

* add kibana privileges with reporting options screenshot

* rephrase why reporting.roles is depreccated

* screenshot for how to define a custom role the grants reporting privileges

* Apply suggestions from code review

Co-authored-by: Kaarina Tungseth <[email protected]>

* Apply suggestions from code review

Co-authored-by: Kaarina Tungseth <[email protected]>

* Update docs/settings/reporting-settings.asciidoc

Co-authored-by: Kaarina Tungseth <[email protected]>

* Apply suggestions from code review

Co-authored-by: Kaarina Tungseth <[email protected]>

* Update docs/settings/reporting-settings.asciidoc

Co-authored-by: Kibana Machine <[email protected]>
Co-authored-by: Kaarina Tungseth <[email protected]>
(cherry picked from commit 1095208)

docs/settings/reporting-settings.asciidoc

@@ -1,4 +1,4 @@
-[role="xpack"]
+role="xpack"]
 [[reporting-settings-kb]]
 === Reporting settings in {kib}
 ++++
@@ -11,18 +11,27 @@ You can configure `xpack.reporting` settings in your `kibana.yml` to:
 
 * <<general-reporting-settings,Enable the {report-features}>>
 * <<encryption-keys,Configure the encryption key>>
-* <<reporting-kibana-server-settings,Control how the {report-features} communicate with the {kib} server>>
 * <<reporting-job-queue-settings,Manage background jobs>>
 * <<reporting-capture-settings,Capture screenshots>>
 * <<reporting-network-policy,Restrict requests with a Reporting network policy>>
 * <<reporting-csv-settings,Increase the byte limit for CSV exports>>
+* <<reporting-kibana-server-settings,Control how the {report-features} communicate with the {kib} server>>
 
 [float]
 [[general-reporting-settings]]
 ==== Enable reporting
 
 [[xpack-enable-reporting]]`xpack.reporting.enabled` {ess-icon}::
-When `true`, enables the {report-features}. The {report-features} are automatically enabled in {kib}. The default is `true`.
+When `true`, enables the {report-features}. Set this to `false` to disable {report-features} entirely. The default is `true`.
+
+[NOTE]
+============
+Disabling the {report-features} is discouraged. If you need to turn off the ability to generate reports,
+configure the roles and spaces in the <<grant-user-access, {kib} application privileges>>.
+
+If needed, you can also prevent a {kib} instance from claiming reporting work by setting
+<<xpack-reportingQueue-pollEnabled, `xpack.reporting.queue.pollEnabled: false`>>.
+============
 
 [float]
 [[encryption-keys]]
@@ -46,39 +55,6 @@ The static encryption key for reporting. Use an alphanumeric text string that is
 xpack.reporting.encryptionKey: "something_secret"
 --------------------------------------------------------------------------------
 
-[float]
-[[reporting-kibana-server-settings]]
-==== {kib} server settings
-
-Reporting opens the {kib} web interface in a server process to generate
-screenshots of {kib} visualizations. In most cases, the default settings
-work and you don't need to configure the {report-features} to communicate with {kib}.
-
-If your {kib} instance requires a reverse proxy (such as NGINX, Apache, etc.) for
-access, because of rewrite rules or special headers being added by the proxy,
-you must configure the `xpack.reporting.kibanaServer` settings to make
-the headless browser process connect to the proxy.
-
-[NOTE]
-============
-If a reverse proxy carries encrypted traffic from user
-clients back to a {kib} server, the proxy port, protocol, and hostname
-in `xpack.reporting.kibanaServer` must be valid for the encryption that the Reporting
-browser receives. Encrypted communications fail if there are
-mismatches in the host information between the request and the certificate on the server.
-
-Configuring the `xpack.reporting.kibanaServer` settings to point to a
-proxy host requires that the {kib} server has network access to the proxy.
-============
-
-`xpack.reporting.kibanaServer.port`:: The port for accessing {kib}, if different from the <<server-port, `server.port`>> value.
-
-`xpack.reporting.kibanaServer.protocol`::
-The protocol for accessing {kib}, typically `http` or `https`.
-
-[[xpack-kibanaServer-hostname]] `xpack.reporting.kibanaServer.hostname`::
-The hostname for accessing {kib}, if different from the <<server-host, `server.host`>> value.
-
 [float]
 [[reporting-job-queue-settings]]
 ==== Background job settings
@@ -90,8 +66,11 @@ reports, you might need to change the following settings.
 `xpack.reporting.queue.indexInterval`::
 How often the index that stores reporting jobs rolls over to a new index. Valid values are `year`, `month`, `week`, `day`, and `hour`. Defaults to `week`.
 
-`xpack.reporting.queue.pollEnabled` {ess-icon}::
-Set to `true` (default) to enable the {kib} instance to poll the index for pending jobs and claim them for execution. Setting this to `false` allows the {kib} instance to only add new jobs to the reporting queue, list jobs, and provide the downloads to completed report through the UI.
+[[xpack-reportingQueue-pollEnabled]] `xpack.reporting.queue.pollEnabled` {ess-icon}::
+When `true`, enables the {kib} instance to poll {es} for pending jobs and claim them for
+execution. When `false`, allows the {kib} instance to only add new jobs to the reporting queue, list
+jobs, and provide the downloads to completed reports through the UI. This requires a deployment where at least
+one other {kib} instance in the Elastic cluster has this setting to `true`. The default is `true`.
 
 NOTE: Running multiple instances of {kib} in a cluster for load balancing of
 reporting requires identical values for <<xpack-reporting-encryptionKey, `xpack.reporting.encryptionKey`>> and, if
@@ -258,11 +237,34 @@ With Security enabled, Reporting has two forms of access control: each user can
 
 [NOTE]
 ============================================================================
-The `xpack.reporting.roles` settings are for a deprecated system of access control in Reporting. It does not allow API Keys to generate reports, and it doesn't allow {kib} application privileges. We recommend you explicitly turn off reporting's deprecated access control feature by adding `xpack.reporting.roles.enabled: false` in kibana.yml. This will enable you to create custom roles that provide application privileges for reporting, as described in <<grant-user-access, granting users access to reporting>>.
+The `xpack.reporting.roles` settings are for a deprecated system of access control in Reporting. Turning off this feature allows API Keys to generate reports, and allows reporting access through {kib} application privileges. We recommend you explicitly turn off reporting's deprecated access control feature by adding `xpack.reporting.roles.enabled: false` in kibana.yml. This will enable you to create custom roles that provide application privileges for reporting, as described in <<grant-user-access, granting users access to reporting>>.
 ============================================================================
 
 [[xpack-reporting-roles-enabled]] `xpack.reporting.roles.enabled`::
 deprecated:[7.14.0,The default for this setting will be `false` in an upcoming version of {kib}.] Sets access control to a set of assigned reporting roles, specified by `xpack.reporting.roles.allow`. Defaults to `true`.
 
 `xpack.reporting.roles.allow`::
 deprecated:[7.14.0] In addition to superusers, specifies the roles that can generate reports using the {ref}/security-api.html#security-role-apis[{es} role management APIs]. Requires `xpack.reporting.roles.enabled` to be `true`. Defaults to `[ "reporting_user" ]`.
+
+[float]
+[[reporting-kibana-server-settings]]
+==== {kib} server settings
+
+To generate screenshots for PNG and PDF reports, Reporting opens the {kib} web interface using a local
+connection on the server. In most cases, using a local connection to the {kib} server presents no issue. If
+you prefer the headless browser to connect to {kib} using a specific hostname, there are a number of
+settings that allow the headless browser to connect to {kib} through a proxy, rather than directly.
+
+[NOTE]
+============
+The `xpack.reporting.kibanaServer` settings are optional. Take caution when editing these settings. Adding
+these settings can cause the {report-features} to fail. If report fail,
+inspect the server logs. The full {kib} URL that Reporting is attempting to
+  open is logged during report execution.
+============
+
+`xpack.reporting.kibanaServer.port`:: The port for accessing {kib}.port`>> value.
+
+`xpack.reporting.kibanaServer.protocol`:: The protocol for accessing {kib}, typically `http` or `https`.
+
+[[xpack-kibanaServer-hostname]] `xpack.reporting.kibanaServer.hostname`:: The hostname for accessing {kib}.

docs/setup/configuring-reporting.asciidoc

@@ -41,7 +41,7 @@ To troubleshoot the problem, start the {kib} server with environment variables t
 [float]
 [[grant-user-access]]
 === Grant users access to reporting
-When security is enabled, you grant users access to generate reports with <<kibana-privileges, {kib} application privileges>>, which allow you to create custom roles that control the spaces and applications where users generate reports.
+When security is enabled, you grant users access to {report-features} with <<kibana-privileges, {kib} application privileges>>, which allow you to create custom roles that control the spaces and applications where users generate reports.
 
 . Enable application privileges in Reporting. To enable, turn off the default user access control features in `kibana.yml`:
 +
@@ -60,7 +60,6 @@ NOTE: If you use the default settings, you can still create a custom role that g
 
 . Specify the role settings.
 
-
 .. Enter the *Role name*. For example, `custom_reporting_user`.
 
 .. Specify the *Indices* and *Privileges*.
@@ -77,9 +76,14 @@ For more information, refer to {ref}/security-privileges.html[Security privilege
 
 .. Click *Customize*, then click *Analytics*.
 
-.. Next to the applications you want to grant reporting privileges, click *All*.
+.. Next each application listed, click *All* or click *Read*. You will need to enable the *Customize sub-feature
+privileges* checkbox to grant reporting privileges if you select *Read*.
++
+If you’ve followed the example above, you should end up on a screen defining your customized privileges that looks like this:
+[role="screenshot"]
+image::user/reporting/images/kibana-privileges-with-reporting.png["Kibana privileges with Reporting options"]
 +
-If the *Reporting* option is unavailable, contact your administrator, or <<reporting-advanced-settings,enable the option in kibana.yml>>. 
+NOTE: If *Reporting* options for application features are not available, contact your administrator, or <<reporting-advanced-settings,check that xpack.reporting.roles.enabled is set to false in kibana.yml>>. 
 
 .. Click *Add {kib} privilege*.