Missing documentation: Reporting generation URL now requires kbn-version header to be set

[elasticmachine]

Original comment by @ppf2:

Something we changed recently in the reporting plugin now requires an additional header to be set when using the generation URL via a POST, but we failed to document this in the reporting guide. This results in Watcher-reporting integration failing with Http status 400 because of the missing header.

Not sure when we introduced this but I happen to be using reporting 2.4.2 plugin and I have to set the kbn-version to match the version (example below is for a Kibana instance running 4.6.0) of Kibana as an additional header for it to work:

                "headers": {
                  "kbn-xsrf": "reporting",
                  "kbn-version": "4.6.0"
                }

This is missed in our documentation: https://www.elastic.co/guide/en/reporting/current/getting-started.html#automating-report-generation

We should update the example watch + reporting release notes in the documentation accordingly if this is an intended change.

[elasticmachine]

Original comment by @ppf2:

@w33ble @tbragin is this an intentional change? If so, we will want to update our documentation.

[elasticmachine]

Original comment by @ppf2:

Probably 4.6.0 specific. I am guessing 4.6.1 is not an issue because of some changes in this area (#8152)? Should this be documented as a breaking change between patch release?

[elasticmachine]

Original comment by @w33ble:

You shouldn't need both the kbn-xsrf and kbn-version headers. But if you are running 4.6.0 with 2.4.1+, then you may. It's not a configuration we intended to work, 2.4.1 and 4.6.1 were released together, both with the required header change.

It was definitely a breaking change in Reporting 2.4.1, but not really a break in Kibana, since you can use the kbn-version header to achieve the same effect (the kbn-xsrf header didn't exist until 4.6.1, but the version header effectively did the job of both).

I'm not sure the best course of action here. Adding something to the docs is probably a good idea, but is it simply saying the 2.4.1 is meant to work with 4.6.1 or newer? And what does this mean for support... do we support the 4.6.0/2.4.1+ combo, or tell users they need to update Kibana?

[elasticmachine]

Original comment by @ppf2:

I will suggest the following

• We will want to add it as a breaking change since it is not there right now (LINK REDACTED)
• We will also want to update our support matrix (https://www.elastic.co/support/matrix#show_compatibility) accordingly @mcmesser @tbragin
  • Also, this type of breaking change is inconsistent with our other products - we generally don't have breaking changes in patch versions which is why for all the products today, our support matrix has the versions noted as 2.4.x with no specification of a patch version. It seems like we may want to avoid introducing breaking changes in patch versions moving forward? :)

[elasticmachine]

Original comment by @w33ble:

It seems like we may want to avoid introducing breaking changes in patch versions moving forward? :)

Would have loved to. It was a negative side effect of giving Reporting a hard deadline and trying to get it out the door ASAP without a whole lot of input or review from others. 😢

[elasticmachine]

Original comment by @debadair:

The doc update is merged. @mcmesser @tbragin What's the process for getting the support matrix updated?

[elasticmachine]

Original comment by @ppf2:

@debadair We are tracking the support matrix update on the public website LINK REDACTED.

[elasticmachine]

Original comment by @tsullivan:

@debadair @w33ble @kobelb can someone confirm if this issue is still valid?

[elasticmachine]

Original comment by @kobelb:

@tsullivan the API call still requires this header; however, now that we have the new reporting attachment type I don't know if this is still relevant.

[elasticmachine]

Original comment by @tsullivan:

@kobelb if you don't mind, can you track down if there still are documentation needs? We have a lot of old issues in this repo, and a lot of them are irrelevant. That makes finding important stuff harder.

[elasticmachine]

Original comment by @w33ble:

AFAIK, you shouldn't need both headers. If you use kbn-xsrf, you don't need kbn-version. There may have been a window in the 2.4/4.6 versions where you did need both, but I don't recall that being true.

In 5.1, all the header stuff was replaced by the reporting type in Watcher.

[tsullivan]

There are a few related issues to this:

• Update "Automatic Report Generation" docs with CSV report info #37706
• [Phase 2] Usage of "Generation URL" should be made clear by UI #17920

[tsullivan]

Close via #40931