[Release 3.0] Planned Breaking Changes for 3.0 in OpenSearch-Dashboards

[virajsanghvi]

This is a meta issue which lists down all breaking changes in OpenSearch-Dashboards 3.0. This will continue to be updated as we learn more.

Major updates

• [Proposed] [RFC] Clarifying Semantic Versioning for OpenSearch Dashboards #9491
• [Proposed] Defaulting to "New Home Page" and Discover experience
• [Proposed] Defaulting to workspaces enabled
• [Impact][OpenSearch Breaking Change] Existing index patterns that use removed painless scripting OpenSerch APIs will fail
  • [Remove] Remove deprecated methods from JodaCompatibleZonedDateTime which are called by scripts OpenSearch#3346
  • Painless APIs removed:
• Upgrading to Node.js 20
  • [Proposed] Removing support for older versions of Node.js
  • [Node.js v20] Plugin Verification Meta Issue #9459

Breaking behavior in 3.0+

• Bump opensearch client and opensearch-next will be removed: (#3469)

Removed code in 3.0+

Code from the following deprecations will be removed:

• remove deprecated CssDistFilename for 3.0 remove deprecated CssDistFilename for 3.0 #9446
• Remove data enhancements config and readonly flag. Removes dead url link, (#7291)
• Rename withLongNumerals to withLongNumeralsSupport in HttpFetchOptions #5592
• Remove timeline application (#3971)
• [CVE-2020-36632] [REQUIRES PLUGIN VALIDATION] Bump flat from 4.1.1 to 5.0.2 (#3419). To the best of our knowledge, this is a non-breaking change, but if your plugin relies on mocha tests, validate that they still work correctly (and plan to migrate them to jest in preparation for mocha deprecation.
• Remove non-inclusive language
  • server.xsrf.whitelist --> server.xsrf.allowlist
  • server.compression.referrerWhitelist --> server.compression.referrerAllowlist
  • opensearch.requestHeadersWhitelist --> opensearch.requestHeadersAllowlist
  • opensearch.requestHeadersWhitelistConfigured --> opensearch.requestHeadersAllowlistConfigured

Misc

• [BUG] EOL of Node.js version 18.x used in Opensearch-dashboards #8463
  • Switch to NodeJS LTS 20 "Iron" #9171

[kavilla]

Will gather links but brain dumping now:

• 3.0 we bump opensearch js client to a breaking change version. For 2.x we alias that package as opensearch-next, plugins that use the dependency opensearch js client could have issues if they do not update properly

[virajsanghvi]

Will gather links but brain dumping now:

• 3.0 we bump opensearch js client to a breaking change version. For 2.x we alias that package as opensearch-next, plugins that use the dependency opensearch js client could have issues if they do not update properly

@kavilla Is this planned work for 3.0? If so, can we add to list of breaking changes above so plugins are aware.

[zhongnansu]

@kavilla fyi, opensearch js client 3.x is also officially released, could this be a chance we skip 2.x, bump to 3.x to bring the latest client experience to community? https://github.com/opensearch-project/opensearch-js/releases/tag/3.0.0

https://github.com/opensearch-project/opensearch-js/blob/main/UPGRADING.md

[kavilla]

@virajsanghvi, this work has been done and for 2.x sake we aliased the next version to be a breaking change version of the dependency. i have updated the issue.

@zhongnansu we could but currently unplanned. i see a draft open here #9139

It might be too risky to bump up to 3.x as of right now. Worth tracking as an issue for 4.0 and perhaps introducing the alias of opensearch-next point to the 3.0 client

[kavilla]

This one will be little bit hard @virajsanghvi:

#1600

Example, users can create an index pattern with a painless script that is removed in 3.0. Since the index pattern is a saved object and the script is user entered replacing the script with migrations would be difficult. but will fail for the user. For example:

#1607, our tests were failing. Something that got de-prioritized in communicating to users that the script they are using is deprecated and removed in OpenSearch 3.0.0 and wont work. But it might appear as a failure on OSD side.

[kavilla]

@virajsanghvi is there a plan to make OpenSearch Dashboards 4.0.0 compatible with legacy version 7.10.2?

[kavilla]

Also is this still planned: #4713 ?

[kavilla]

We also have a number of deprecated configs that we marked deprecated for a while.

OpenSearch has removed in 3.0 the whitelist I think we should too but we still allow it (with a warning on start up to the host) . For example, #1467

[peterzhuamazon]

Hi @virajsanghvi @kavilla ,

We also might need to focus on this:

• Switch to NodeJS LTS 20 "Iron" #9171

As node18 will be eol very soon.

Thanks.

[angle943]

I began some investigations for the remove non-inclusive language for 3.0 task. Firstly, there is a draft PR that does a is an attempt at removing the term whitelist from the OSD codebase. While it is a poor attempt, it highlights all locations of the word whitelist so i will leave it open for now as a reference.

1. server.xsrf.whitelist -> server.xsrf.allowlist:

• This PR deprecates it: Deprecates non-inclusive config names #1467

• According to the PR description, this change is allowing the user to use allowlist version of the config names but under the hood, we're mapping the new value back to the old value used in code so that we don't have breaking changes for plugins. . Unless some additional work has been done, it seems like the app still relies on the server.xsrf.whitelist term. I think someone more knowledgeable in the domain should decide whether this can safely be removed

• Furthermore, there is a similar http.xsrf.whitelist throughout the codebase. Here is an example. This comment at the top of this file makes me think these are somehow related, but it looks like this one does has not been properly deprecated beforehand? Or perhaps when the author of the above deprecation PR mentions that we are using the old values under the hood, this is what he/she is referring to?

2. server.compression.referrerWhitelist -> server.compression.referrerAllowlist:

• Same PR as above: Deprecates non-inclusive config names #1467
• This one also has an http counterpart

3. opensearch.requestHeadersWhitelist --> opensearch.requestHeadersAllowlist

• Same PR as above: Deprecates non-inclusive config names #1467

4. opensearch.requestHeadersWhitelistConfigured --> opensearch.requestHeadersAllowlistConfigured

• This one is from a different PR: [Deprecation] Deprecate the Blacklist / Whitelist nomenclature #1808
• I am not entirely sure, but it looks like the deprecation strategy was the same as the other ones (ie rename under the hood but still use the old one)

Other ones not mentioned in the list

• There's some other references to whitelist other than the four:

1. viz_type_timeseries - I think these can be safely removed

2. osd_react markdown - I think these can also be safely removed

• There might be more? Again, this PR has the full list: https://github.com/opensearch-project/OpenSearch-Dashboards/pull/9455/files . The other ones seem maybe they are related to any of the ones I've listed in this comment, but that is just my educated(?) guess 🤷

TLDR

• I am not sure if we can safely remove the 4 mentioned in this issue. But I think there are 2 not mentioned in this list that we can remove. But I will await further guidance on someone more experienced with the app

[virajsanghvi]

• According to the PR description, this change is allowing the user to use allowlist version of the config names but under the hood, we're mapping the new value back to the old value used in code so that we don't have breaking changes for plugins. . Unless some additional work has been done, it seems like the app still relies on the server.xsrf.whitelist term. I think someone more knowledgeable in the domain should decide whether this can safely be removed

If this is true (we should validate), sounds like it should be safe to make turn these to the allowlist variant in code.

It appears this was the same approach for other items - so I'm okay changing those if we validate (basically, we can identify where allow* defines white* in code)

• Furthermore, there is a similar http.xsrf.whitelist throughout the codebase. Here is an example. This comment at the top of this file makes me think these are somehow related, but it looks like this one does has not been properly deprecated beforehand? Or perhaps when the author of the above deprecation PR mentions that we are using the old values under the hood, this is what he/she is referring to?

If this hasn't been properly deprecated, we should not make this change yet

Other ones not mentioned in the list

• There's some other references to whitelist other than the four:

1. viz_type_timeseries - I think these can be safely removed
2. osd_react markdown - I think these can also be safely removed

Can you state why these are safe to remove?

• There might be more? Again, this PR has the full list: https://github.com/opensearch-project/OpenSearch-Dashboards/pull/9455/files . The other ones seem maybe they are related to any of the ones I've listed in this comment, but that is just my educated(?) guess 🤷

Can we list these out specifically?

[angle943]

Can you state why these are safe to remove?

for those two mentioned, we offer both the whitelist and allowlist options as props, with the whitelist variant being already marked as deprecated. The usage of those decides whether to use the whitelist or allowlist variant depending on what has been used.

[angle943]

I have also marked "discover:newExperience" as deprecated and will remove it for 3.0. More info here: #9511