[DOCS] Add deprecation notice for system indices#80028
[DOCS] Add deprecation notice for system indices#80028lockewritesdocs wants to merge 4 commits intoelastic:masterfrom
Conversation
|
Pinging @elastic/es-docs (Team:Docs) |
|
Pinging @elastic/es-core-infra (Team:Core/Infra) |
| ==== | ||
| *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 |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
I spoke with @bytebilly, and we decided to add separate deprecation messages for 7.16 and 8.0. PR #80095 will add a deprecation message for 7.16. For 8.0, we should wait until #79679 is merged so that we can link directly to that documentation from the deprecation message for more details as we develop our approach for system indices access in that version. cc: @debadair for visibility |
williamrandolph
left a comment
There was a problem hiding this comment.
From the dev's perspective, I think this is all accurate, and will be complete once we can link to something that explains what system indices are. I can't speak to the product manager perspective.
bytebilly
left a comment
There was a problem hiding this comment.
I left a suggestion, LGTM otherwise
Co-authored-by: Fabio Busatto <52658645+bytebilly@users.noreply.github.com>
|
@elasticmachine update branch |
|
merge conflict between base and head |
|
After battling with a gnarly rebase, I applied these changes in #83688. |
In 7.16, directly accessing system indices is deprecated. If an application or API directly accesses system indices, we generate warnings in the deprecation log as indicated in #79633. PR #80095 will add a deprecation message for 7.16.
In 8.0, users must add the
allow_restricted_indicespermission set totrueon a user role to accesssystem indices. This PR adds a deprecation notice to the 8.0 migration docs so that we can inform users of this change and link to documentation for guidance.
We should wait until #79679 is merged so that we can link directly to that documentation for more details.
Preview link: https://elasticsearch_80028.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/migrating-8.0.html#breaking_80_indices_changes
Relates to #79679