[Upgrade Assistant] Announce Kibana Plugin Deprecations

[jloleysens]

Description

At the moment, the Upgrade Assistant (UA) is used to guide users through upgrading the Elastic stack with a special focus on upgrading Elasticsearch (indices that need to be re-indexed, node versions that mismatch). As Kibana plugins have grown in complexity and end users have started consuming public endpoints directly (e.g., #52866) changes to these endpoints should be announced to empower users to update other services as they upgrade the Elastic stack (and Kibana with it).

In all cases of Kibana deprecations, the main idea is to give users a way to address the problems in Kibana by sending them to the relevant UI from Upgrade Assistant.

Kinds of deprecations

There are two kinds of deprecations - checked from current Kibana data and checked by querying functionality used in the past.

Current Kibana Data

Certain deprecations (like #42853) can be checked by UA at runtime. We would want to give plugins a way to register checkers that would emit deprecation objects (like those described below).

Another instance is use of deprecated Kibana config.

Functionality used in the past

Similar to ES, this would be a log of instances where functionality was used that will be deprecated. This functionality is envisioned as probably belonging in core since it should be widely accessible.

Proposed Changes

UI

In UA, we need to create a space for Kibana specific changes to be announced/listed in a user friendly way. One idea is to create a new tab specific to Plugins and then have a subsection for Kibana there (draft #54388).

Integrations

It would be best if individual plugins can specify deprecations via a well-defined interface and maintain these lists. The deprecations could look something like:

interface PluginDeprecationsData {
  pluginName: string;
  euiLogo: string;
  deprecations: Array<{
    title: string;                        // i18n friendly title
    description: string;                  // i18n friendly description
    since: string;                        // SemVer compliant string
    level: 'info' | 'warning' | 'danger'; // Would this be useful?
    link?: string;
    // In future we could add embeddable actions?
  }>;
}

Note: This functionality may need to reside in OSS (not necessarily in UA) because all plugins should be able to depend on it. It could be its own deprecations plugin with 0 other dependencies.

Need more info

• Given that UA is in legacy, what mechanism can we use for sharing functionality described here to NP plugins (same for vice versa if UA moves to NP proper) UA has been migrated to NP 🎉

CC
@cjcenizal
@azasypkin

Addtional

• PoC [Draft][Upgrade Assistant] Show Kibana Deprecations #54388

[elasticmachine]

Pinging @elastic/es-ui (Team:Elasticsearch UI)

[tylersmalley]

One thing which is not clear to me, are these alerts for things which are actionable? Or are there general notices? The upgrade assistant currently raises items which would effect or prevent the user from upgrading. Otherwise, this would begin to overlap with general documentation.

[jloleysens]

@tylersmalley That is a great question!

Given the original context in which the issue was raised it seems as though an announcement (not necessarily actionable from within Kibana) is what was under consideration.

This was an instance where, as part of upgrading, the user would need to make changes to their external integrations with Kibana. Perhaps if we can see a specific integration is being used, we could raise a notice to the user (perhaps just linking them to docs if they exist). In other cases perhaps an action could be attached to the notice - that's where we need some more information from plugins and plugin owners.

[tylersmalley]

@jloleysens, that makes sense and I am fully on-board with that! It's early, and when I originally read the issue I thought the proposal was for the deprecation to be a constant on the plugin, not an interface which plugins could use. So that's great!

Another topic for discussion is should the registry be in OSS or X-Pack? One thought is that if it were in OSS we could have it expose the deprecations over an endpoint which could be consumed in the Upgrade Assistant, similar to how we consume Elasticsearch deprecation Info API. For Elasticsearch, I see that API is in X-Pack. @gwbrown, do you recall the reasoning behind that?

[Bamieh]

We did work on something similar to this in the Pulse POC! Basically Pulse provided elastic relevant data about the kibana deployment and pulse returned upgrade instructions tailored to the specific deployment in addition to the generic upgrade instructions.

We should be demo-ing it in the next demo day if we get a spot. CC @elastic/pulse

[gwbrown]

For Elasticsearch, I see [the Deprecation Info] API is in X-Pack. @gwbrown, do you recall the reasoning behind that?

It was in x-pack before I started working on it, so I don't know for sure. I do know that we make sure to also write deprecation messages to the deprecation log in OSS, so the Deprecation Info API is more of a convenience than something that's necessary to know about deprecated functionality.

[alisonelizabeth]

I think this issue can be closed now that the core team has implemented a deprecations service (#94845). The related UI will be implemented in #97159.