Skip to content

[DOCS] Add deprecation notice for system indices #80028

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

[DOCS] Add deprecation notice for system indices #80028

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b4cae0b
[DOCS] Add deprecation notice for system indices
Oct 28, 2021
4c1dd7b
Add guidance about contacting Support
Oct 28, 2021
fa6029e
Updates based on reviewer feedback
Oct 29, 2021
95009d4
Incorporate review feedback
Feb 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/reference/migration/migrate_8_0/indices.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,23 @@
//Installation and Upgrade Guide

//tag::notable-breaking-changes[]
[[deprecation-system-indices]]
.Direct access to system indices is deprecated.
[%collapsible]
====
*Details* +
Directly accessing system indices is deprecated, and will be prevented by
default in a future major version. System indices are reserved only for internal
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

future major version

Is this true? I'm not sure what I can even say publicly about this?

In another way, access is already prevented by default in 8.0, unless you have the right bits on your index privileges (specifically allow_restricted_indices).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was going based on the warnings from #79633:

deprecationLogger.warn(DeprecationCategory.API, "open_system_index_access",
                "this request accesses system indices: {}, but in a future major version, direct access to system " +
                    "indices will be prevented by default", systemIndicesNames);

If 8.0 is the major version, then I think that we need two deprecation messages; one for 7.16 and one for 8.0.

7.16

Directly accessing system indices is deprecated, and will be prevented by default in Elasticsearch 8.0.

8.0

You cannot directly access system indices starting in Elasticsearch 8.0.

I'm unsure whether we want to mention allow_restricted_indices for accessing system indices, which is why I indicated that "you should only do so with the guidance of Elastic Support." cc: @bytebilly for input.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

7.16
Directly accessing system indices is deprecated, and will be prevented by default in Elasticsearch 8.0.

I'm not sure that the above sentence for 7.16 is correct. You could argue that, by default, users will not get the allow_restricted_indices flag set, but I would counter-argue that elastic, the default user account everybody knows and uses, has it set and so it can access by default 🙂
If we want to help users to migrate correctly, we should call out the solution explicitly.
Something along those lines:

"Directly accessing system indices is deprecated, and it will require the allow_restricted_indices permission flag in Elasticsearch 8.0."

What do you think?

8.0
You cannot directly access system indices starting in Elasticsearch 8.0.

Here we probably want to mention something related to possible future changes, but we still don't know details.
So, something generic, to keep the deprecation flag but without assuming what the final conclusion will be.

"Directly accessing system indices is deprecated, and may be prevented in a future version."
(I'm not sure we can talk about "next major versions" anymore, given Make it Minor — keeping it generic would let us tune as required)

Emitted deprecation messages and what's in the docs should be consistent where possible.

use by Elastic products and should not be accessed directly. While it's still
possible to access system indices, you should only do so with the guidance of
Elastic Support.
*Impact* +
Accessing system indices directly results in warnings in the deprecation logs.
Use {kib} or the associated feature's {es} APIs to manage the data that you
want to access.
====

.The deprecated `_upgrade` API has been removed.
[%collapsible]
====
Expand Down