Skip to content

Commit e9d7782

Browse files
eedugoneedugon
committed
configure kibana reporting initial refinement
1 parent c278b91 commit e9d7782

File tree

3 files changed

+265
-260
lines changed

3 files changed

+265
-260
lines changed

‎deploy-manage/deploy/kibana-reporting-configuration.md‎

Lines changed: 265 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,281 @@
11
---
2+
navigation_title: Configure Kibana reporting
23
mapped_urls:
34
- https://www.elastic.co/guide/en/kibana/current/secure-reporting.html
4-
- https://www.elastic.co/guide/en/kibana/current/reporting-production-considerations.html
5+
applies_to:
6+
deployment:
7+
self: all
8+
ece: all
9+
eck: all
10+
ess: all
511
---
612

7-
# Configure reporting
13+
% this anchor belongs to `kibana reporting production considerations doc`
14+
$$$reporting-chromium-sandbox$$$
815

9-
% What needs to be done: Refine
16+
# Configure Kibana reporting [secure-reporting]
1017

11-
% GitHub issue: ??? PENDING TO ADD THE TASK TO AN ISSUE
18+
{{kib}}'s reporting functionality offers multiple ways to share **Discover** sessions, dashboards, **Visualize Library** visualizations, and **Canvas** workpads.
1219

13-
% Scope notes: Reporting documentation will be a bit spread: - how to use reporting in Explore and Analyze - how to configure reporting in Kibana configuration. - Reporting troubleshooting in troubleshooting. - All reporting settings in reference. The content linked is applicable to all deployment types but certaion parts are only valid for self-managed, so we need to find the best way to present this in the new IA.
20+
This section covers the necessary configuration to ensure reporting works correctly in your deployment. For guidance on using {{report-features}} effectively, refer to [](/explore-analyze/report-and-share.md).
1421

15-
% Use migrated content from existing pages that map to this page:
22+
::::{admonition} Note for self-managed deployments
23+
Kibana PNG/PDF reporting uses a custom binary of headless Chromium, and support comes with special caveats:
1624

17-
% - [ ] ./raw-migrated-files/kibana/kibana/secure-reporting.md
18-
% - [ ] ./raw-migrated-files/kibana/kibana/reporting-production-considerations.md
25+
* The functionality requires special OS dependencies which may not be available for all distributions and configurations of Linux.
26+
* It is subject to system resource configurations such as the limited number of file descriptors, allowed processes, and types of processes.
27+
* Linux versions that are in end-of-life phase are not supported.
28+
* Linux systems with `SELinux` or `fapolicyd` are not supported.
1929

20-
% Internal links rely on the following IDs being on this page (e.g. as a heading ID, paragraph ID, etc):
30+
Before upgrading Kibana in a production environment, we encourage you to test your screenshotting use cases in a pre-production environment to make sure your hosts support our latest build of Chromium. For the most reliable configuration of PDF/PNG {{report-features}}, consider installing {{kib}} using [Docker](../../../deploy-manage/deploy/self-managed/install-kibana-with-docker.md), or using [Elastic Cloud](https://cloud.elastic.co).
31+
::::
2132

22-
$$$reporting-chromium-sandbox$$$
33+
## Configuration overview
34+
35+
To secure {{report-features}}, you must grant users access to reporting functionality and protect the reporting endpoints with TLS/SSL encryption. Additionally, you can install graphical packages on the operating system to enable screenshot capabilities in the {{kib}} server.
36+
37+
Configuring reporting in your environment involves two main areas:
38+
39+
### Granting users access to {{report-features}}
40+
41+
Depending on your license, the type of users, and whether you prefer using the {{kib}} UI or API, there are multiple ways to grant access to reporting functionality. Choose the method that best fits your use case:
42+
43+
* [Grant users access using {{kib}} UI](#grant-user-access)
44+
* [Grant access with the role API](#reporting-roles-user-api)
45+
* [Grant users access with a Basic license](#grant-user-access-basic)
46+
* [Grant access using an external provider](#grant-user-access-external-provider)
47+
48+
### Applying system configuration
49+
50+
The following configurations are required at {{es}}, {{kib}}, and OS levels to support {{report-features}}.
51+
52+
::::{important}
53+
These settings apply only to **self-managed deployments**. Orchestrated deployments include this configuration by default.
54+
::::
55+
56+
* [Secure the reporting endpoints](#securing-reporting)
57+
* [Install the dependencies for the headless browser](#install-reporting-packages)
58+
* [Set the `server.host` for the headless browser](#set-reporting-server-host)
59+
* [Ensure {{es}} allows built-in templates](#reporting-elasticsearch-configuration)
60+
61+
## Grant users access to reporting [grant-user-access]
62+
```yaml {applies_to}
63+
deployment:
64+
self: all
65+
ece: all
66+
eck: all
67+
ess: all
68+
```
69+
70+
### Grant users access using {{kib}} UI
71+
72+
When security is enabled, you grant users access to {{report-features}} with [{{kib}} application privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md), which allow you to create custom roles that control the spaces and applications where users generate reports.
73+
74+
1. Create the reporting role.
75+
76+
1. Go to the **Roles** management page using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md).
77+
2. Click **Create role**.
78+
79+
2. Specify the role settings.
80+
81+
1. Enter the **Role name**. For example, `custom_reporting_user`.
82+
2. Specify the **Indices** and **Privileges**.
83+
84+
Access to data is an index-level privilege. For each index that contains the data you want to include in reports, add a line, then give each index `read` and `view_index_metadata` privileges.
85+
86+
::::{note}
87+
If you use index aliases, you must also grant `read` and `view_index_metadata` privileges to underlying indices to generate CSV reports.
88+
::::
89+
90+
91+
For more information, refer to [Security privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md).
92+
93+
3. Add the {{kib}} privileges.
94+
95+
1. Click **Add Kibana privilege**.
96+
2. Select one or more **Spaces**.
97+
3. Click **Customize**, then click **Analytics**.
98+
4. For each application, select **All**, or to customize the privileges, select **Read** and **Customize sub-feature privileges**.
99+
100+
::::{note}
101+
If you have a Basic license, sub-feature privileges are unavailable. For details, check out [Grant users access with a Basic license](../../../explore-analyze/report-and-share.md#grant-user-access-basic).
102+
::::
103+
104+
105+
:::{image} ../../../images/kibana-kibana-privileges-with-reporting.png
106+
:alt: Kibana privileges with Reporting options, Gold or higher license
107+
:screenshot:
108+
:::
109+
110+
::::{note}
111+
If the **Reporting** options for application features are unavailable, and the cluster license is higher than Basic, contact your administrator.
112+
::::
113+
114+
5. Click **Add {{kib}} privilege**.
115+
116+
4. Click **Create role**.
117+
5. Assign the reporting role to a user.
118+
119+
1. Go to the **Users** management page using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md).
120+
2. Select the user you want to assign the reporting role to.
121+
3. From the **Roles** dropdown, select **custom_reporting_user**.
122+
4. Click **Update user**.
123+
124+
125+
Granting the privilege to generate reports also grants the user the privilege to view their reports in **Stack Management > Reporting**. Users can only access their own reports.
126+
127+
128+
### Grant access with the role API [reporting-roles-user-api]
129+
130+
With [{{kib}} application privileges](../../../explore-analyze/report-and-share.md#grant-user-access), you can use the [role APIs](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-roles) to grant access to the {{report-features}}, using **All** privileges, or sub-feature privileges.
131+
132+
::::{note}
133+
This API request needs to be run against the [Kibana API endpoint](https://www.elastic.co/guide/en/kibana/current/api.html).
134+
::::
135+
136+
```console
137+
PUT <kibana host>:<port>/api/security/role/custom_reporting_user
138+
{
139+
"elasticsearch": {
140+
"cluster": [],
141+
"indices": [],
142+
"run_as": []
143+
},
144+
"kibana": [{
145+
"spaces": ["*"],
146+
"base": [],
147+
"feature": {
148+
"dashboard_v2": ["generate_report", <1>
149+
"download_csv_report"], <2>
150+
"discover_v2": ["generate_report"], <3>
151+
"canvas": ["generate_report"], <4>
152+
"visualize_v2": ["generate_report"] <5>
153+
}
154+
}]
155+
}
156+
```
157+
158+
1. Grants access to generate PNG and PDF reports in **Dashboard**.
159+
2. Grants access to generate CSV reports from saved Discover session panels in **Dashboard**.
160+
3. Grants access to generate CSV reports from saved Discover sessions in **Discover**.
161+
4. Grants access to generate PDF reports in **Canvas**.
162+
5. Grants access to generate PNG and PDF reports in **Visualize Library**.
163+
164+
### Grant users access with a Basic license [grant-user-access-basic]
165+
166+
With a Basic license, you can grant users access with custom roles to {{report-features}} with [{{kib}} application privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md). However, with a Basic license, sub-feature privileges are unavailable. [Create a role](../../../explore-analyze/report-and-share.md#grant-user-access), then select **All** privileges for the applications where users can create reports.
167+
168+
:::{image} ../../../images/kibana-kibana-privileges-with-reporting-basic.png
169+
:alt: Kibana privileges with Reporting options, Basic license
170+
:screenshot:
171+
:::
172+
173+
With a Basic license, sub-feature application privileges are unavailable, but you can use the [role API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role) to grant access to CSV {{report-features}}:
174+
175+
```console
176+
PUT localhost:5601/api/security/role/custom_reporting_user
177+
{
178+
"elasticsearch": { "cluster": [], "indices": [], "run_as": [] },
179+
"kibana": [
180+
{
181+
"base": [],
182+
"feature": {
183+
"dashboard_v2": [ "all" ], <1>
184+
"discover_v2": [ "all" ], <2>
185+
},
186+
"spaces": [ "*" ]
187+
}
188+
],
189+
"metadata": {} <3>
190+
}
191+
```
192+
193+
1. Grants access to generate CSV reports from saved Discover sessions in **Discover**.
194+
2. Grants access to generate CSV reports from saved Discover session panels in **Dashboard**.
195+
3. Optional
196+
197+
### Grant access using an external provider [grant-user-access-external-provider]
198+
199+
If you are using an external identity provider, such as LDAP or Active Directory, you can assign roles to individual users or groups of users. Role mappings are configured in [`config/role_mapping.yml`](../../../deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md).
200+
201+
For example, assign the `kibana_admin` and `reporting_user` roles to the Bill Murray user:
202+
203+
```yaml
204+
kibana_admin:
205+
- "cn=Bill Murray,dc=example,dc=com"
206+
reporting_user:
207+
- "cn=Bill Murray,dc=example,dc=com"
208+
```
209+
210+
## System configuration
211+
```yaml {applies_to}
212+
deployment:
213+
self: all
214+
```
215+
216+
### Secure the reporting endpoints [securing-reporting]
217+
218+
To automatically generate reports with {{watcher}}, you must configure {{watcher}} to trust the {{kib}} server certificate.
219+
220+
1. Enable {{stack-security-features}} on your {{es}} cluster. For more information, see [Getting started with security](/deploy-manage/security.md).
221+
2. Configure TLS/SSL encryption for the {{kib}} server. For more information, see [*Encrypt TLS communications in {{kib}}*](/deploy-manage/security/set-up-basic-security-plus-https.md#encrypt-kibana-http).
222+
3. Specify the {{kib}} server CA certificate chain in `elasticsearch.yml`:
223+
224+
If you are using your own CA to sign the {{kib}} server certificate, then you need to specify the CA certificate chain in {{es}} to properly establish trust in TLS connections between {{watcher}} and {{kib}}. If your CA certificate chain is contained in a PKCS #12 trust store, specify it like so:
225+
226+
```yaml
227+
xpack.http.ssl.truststore.path: "/path/to/your/truststore.p12"
228+
xpack.http.ssl.truststore.type: "PKCS12"
229+
xpack.http.ssl.truststore.password: "optional decryption password"
230+
```
231+
232+
Otherwise, if your CA certificate chain is in PEM format, specify it like so:
233+
234+
```yaml
235+
xpack.http.ssl.certificate_authorities: ["/path/to/your/cacert1.pem", "/path/to/your/cacert2.pem"]
236+
```
237+
238+
For more information, see [the {{watcher}} HTTP TLS/SSL Settings](elasticsearch://reference/elasticsearch/configuration-reference/watcher-settings.md#ssl-notification-settings).
239+
240+
4. Add one or more users who have access to the {{report-features}}.
241+
242+
Once you’ve enabled SSL for {{kib}}, all requests to the reporting endpoints must include valid credentials.
243+
244+
245+
For more information on sharing reports, direct links, and more, refer to [Reporting and sharing](../../../explore-analyze/report-and-share.md).
246+
247+
248+
### Install the dependencies for the headless browser [install-reporting-packages]
249+
250+
If using PNG/PDF {{report-features}}, make sure the {{kib}} server operating system has the appropriate packages installed for the distribution.
251+
252+
If you are using RHEL operating systems, install the following packages:
253+
254+
* `xorg-x11-fonts-100dpi`
255+
* `xorg-x11-fonts-75dpi`
256+
* `xorg-x11-utils`
257+
* `xorg-x11-fonts-cyrillic`
258+
* `xorg-x11-fonts-Type1`
259+
* `xorg-x11-fonts-misc`
260+
* `vlgothic-fonts`
261+
* `fontconfig`
262+
* `freetype`
263+
264+
If you are using Ubuntu/Debian systems, install the following packages:
265+
266+
* `fonts-liberation`
267+
* `libfontconfig1`
268+
* `libnss3`
269+
270+
The screenshotting plugin used for {{report-features}} has a built-in utility to check for common issues, such as missing dependencies. See [Reporting diagnostics](../../../explore-analyze/report-and-share/reporting-troubleshooting-pdf.md#reporting-diagnostics) for more information.
271+
272+
273+
### Set the `server.host` for the headless browser [set-reporting-server-host]
274+
275+
If using PNG/PDF {{report-features}} in a production environment, it is preferred to use the setting of `server.host: 0.0.0.0` in the `kibana.yml` configuration file. This allows the headless browser used for PDF/PNG reporting to reach {{kib}} over a local interface, while also allowing the {{kib}} server to listen on outward-facing network interfaces, as it makes the {{kib}} server accessible from any network interface on the machine. Make sure that no firewall rules or other routing rules prevent local services from accessing this address.
23276

24-
$$$grant-user-access$$$
25277

26-
⚠️ **This page is a work in progress.** ⚠️
278+
### Ensure {{es}} allows built-in templates [reporting-elasticsearch-configuration]
27279

28-
The documentation team is working to combine content pulled from the following pages:
280+
Reporting relies on {{es}} to install a mapping template for the data stream that stores reports. Ensure that {{es}} allows built-in templates to be installed by keeping the `stack.templates.enabled` setting at the default value of `true`. For more information, see [Index management settings](elasticsearch://reference/elasticsearch/configuration-reference/index-management-settings.md#stack-templates-enabled).
29281

30-
* [/raw-migrated-files/kibana/kibana/secure-reporting.md](/raw-migrated-files/kibana/kibana/secure-reporting.md)
31-
* [/raw-migrated-files/kibana/kibana/reporting-production-considerations.md](/raw-migrated-files/kibana/kibana/reporting-production-considerations.md)

0 commit comments

Comments
 (0)