[Reporting/Documentation] Fix Reporting+Reverse Proxy documentation

[tsullivan]

Documentation for the xpack.reporting.kibanaServer.* settings has a sentence:

However, if you use a reverse-proxy to access Kibana, you must set the proxy port, protocol, and hostname.

That recommends that users to use the xpack.reporting.kibanaServer.* when doing so may cause more problems than solutions.

The sentence should say something like:

If you use a reverse-proxy to access Kibana, you can set the proxy port, protocol, and hostname to have Reporting use the proxy. In most cases, that is only required if the proxy is responsible for modifying requests to make them work with Kibana; for example a reverse proxy can remove a base from requests so Kibana will properly serve the requests.

[tsullivan]

@kobelb can you check my facts and comment about this?

[cjcenizal]

Would it make sense to elaborate on what you mean by "have Reporting use the proxy"? For example, "have Reporting use the proxy to... (do something)".

[tsullivan]

Would it make sense to elaborate on what you mean by "have Reporting use the proxy"? For example, "have Reporting use the proxy to... (do something)".

The xpack.reporting.kibanaServer.* settings exist to configure a proxy URL: hostname, protocol and port.

When you change the settings, it tells the Reporting headless browser to open a URL other than the default localhost URL that Kibana server listens on. The reason you would want to do this is to make the headless browser talk to a proxy, which an administrator has configured as a gateway for talking to the actual Kibana server.

You would want to do that when the Kibana server requires a gateway between it and outside connections. The best example of that being the case is if the proxy has rewrite rules to make Kibana appear to have a base path. For example, if users to access Kibana at https://my-host/my-kibana/app/kibana then you'd need a proxy to take off my-kibana from the path before the Kibana server can understand how to handle requests.

"have Reporting use the proxy to... (do something)".

have Reporting use the proxy to load Kibana URLs

[cjcenizal]

Thanks @tsullivan! That clears things up for me. Reporting works by loading up Kibana in a headless browser and essentially taking screenshots. It loads up Kibana the same way that users do, so if users access Kibana through a reverse proxy, Reporting will need to do that as well.

have Reporting use the proxy to load Kibana URLs

Sounds good to me.

[kobelb]

I think the new wording is fine. There are likely other situations outside of a "base path" that require the traffic be routed through the reverse proxy as opposed to hitting Kibana directly (custom auth at the reverse proxy comes to mind) but we can expand this recommendation if need be.

[tsullivan]

if users access Kibana through a reverse proxy, Reporting will need to do that as well.

Not necessarily. I filed this issue mainly to take the word must out of the documentation for these settings. Instead of saying:

if you use a reverse-proxy to access Kibana, you must set the proxy port, protocol, and hostname

we should say

if you have a reverse-proxy to access Kibana, you can set the proxy port, protocol, and hostname

meaning: if it helps you, you can do it. You will only have to do it if Kibana doesn't work without it.

There are likely other situations outside of a "base path" that require the traffic be routed through the reverse proxy as opposed to hitting Kibana directly (custom auth at the reverse proxy comes to mind) but we can expand this recommendation if need be.

Another situation: if the proxy is responsible for logging all the Kibana requests. In that case, have Reporting use the proxy so the logs will include the requests made by the headless browser.

[tsullivan]

The basic point here is, Kibana server must be able to make a connection to itself for Reporting to work. That goes for:

• With a reverse proxy, if connections must go through the proxy first, then Kibana server must be able to make a connection to the proxy
• With encryption, if Kibana server communications are encrypted with a PKI where a client needs a certificate distributed from a key server, then the Kibana server must be able to make a connection to the key server.

The 2nd point came up recently in a customer case, but I am really not familiar with the terminology here to add documentation for this.

[tsullivan]

cc @lucabelluccini would you feel ok taking ownership of this?

[lucabelluccini]

👍 I'll try to submit a PR associated to this issue.

[KOTungseth]

@lucabelluccini did you still want to address this one?

[KOTungseth]

Related to:

• https://github.com/elastic/support-knowledge-articles/issues/1525
• Add a new documentation page on Load Balancing Across Multiple Kibana Instances #9129