elasticsearch
elasticsearch copied to clipboard
elastic
Mention internal user `_security_profile` in docs
This PR will add internal user _security_profile to the 8.x docs.
Internal user _security_profile was added in v8.3 by https://github.com/elastic/elasticsearch/pull/86026.
Doc previews are available for a short time after a build
- https://elasticsearch_89100.docs-preview.app.elstc.co/diff
-
#89050 -- Include internal user
_async_searchfrom 7.7 into Elasticsearch docs. -- Targeted doc versions: 8.5, 8.4, 8.3, 7.17 -
#89100 -- Include internal user
_security_profilefrom 8.3 into Elasticsearch docs. -- Targeted doc versions: 8.5, 8.4, 8.3
Historically this paragraph exists in the docs because there are some rare occasions where the user names might appear in logs/error messages. This is almost exclusively true for _system because you can get yourself into a state where you get authorization errors for the _system user, typically because of plugins that don't set up security contexts correctly.
It was disturbing for people to get log messages about users that were never mentioned in the docs, so we documented it with as little detail as possible. I don't know what that implies about trying to keep the list of usernames in-sync with the implementation, but I don't think we want to turn it into an internal only doc.
@tvernum Thanks for the context. It's a valid reason to not have it internally only. That said, I suspect it does not belong to general public documentation either because it mostly concerns very advanced users such as plugin developers. But we don't have developer docs either or a developer portal (this was something brought up before at a much higher level, but I am not sure whether there is any movement in this space).
We talked about having more specialized internal users and tentatively agreed it being the right direction. We made effort to not blocking people from creating native users with internal usernames because we believe people should not be concerned with these internal uesrs (most of the time at least). But documenting them feels somewhat going the opposite way. For example, if people create its a ntiave user named _xpack and wonder how it is related to the internal _xpack user, should we expand this documentation to explain more about how internal users work? If in the future, we do add many more internal users, listing all of them here feels off to me. Maybe this shows that we should move away from named internal users similar to how we sometimes want privileges instead of named roles (it's a bigger topic and should be kept separate).
In summary, I don't want to block this PR because so far we only have 5 internal users. But long term, I am not in favour of keeping adding to the list.
Ideally this page should be removed entirely from public documentation. But it is still useful internally and I don't know whereelse we can relocate it to. @lockewritesdocs Do you have any insights on where we are at for having this sort of internal documentation?
@ywangd, we can add a notice that this information is for internal use only, similar to the notice that we have on this autoscaling policy API page. We can change the verbiage if necessary based on the context, but indicate that these users aren't really something that external users should think about or tinker with.
@lockewritesdocs @ywangd Have a look at the note I added. I copied it from the top of the content of the other page, and changed the word feature to users.
https://elasticsearch_89100.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/internal-users.html
