Documentation for operator privileges

[ywangd]

Add documentation for operator privilegs. The docs cover features delivered by phase 1 (#65256) and 2 (#66684).

Please preview the changes at: https://elasticsearch_68964.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/operator-privileges.html

PS: Since the operator privileges feature is mainly for Elastic Cloud and is being worked on, I'd like the docs to be internal only. I didn't find any formal directives to use for "internal" docs. So I just put up a disclaimer in the beginning of the overview, similar to how autoscaling is documented.

Relates:
#66684
#65256

[elasticmachine]

Pinging @elastic/es-docs (Team:Docs)

[elasticmachine]

Pinging @elastic/es-security (Team:Security)

[ywangd]

This is not yet true for autoscaling policies, which currently do not get restored regardless whether operator privileges are enabled or not. However, I do not want to go into this difference here because this will be the ultimate behaviour that we want once Cloud enables operator privileges.

[ywangd]

@elasticmachine run elasticsearch-ci/2

[bytebilly]

LGTM, I just left a couple of comments

[tvernum]

Two thoughts on the top level warning:

The operator privileges feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

1. I think Direct use is not supported is good for now, but we should revisit in a few releases to determine whether we're ready to support it for customers on Enterprise licenses with their own orchestration layers. @bytebilly should we think about this in 2-3 months?
2. Should we have this warning, or a lighter version on every page? (@lcawl, do you have a view?)

[tvernum]

I think there's a section missing here. You'll probably want to clean up the words a bit, but roughly:

When operator privileges are enabled on a cluster, specific functionality is restricted so that it may only be executed by those used who have been explicitly designated as operators.

That just makes the flow of thought a little more clear - it walks the reader through the process of

• turn on the setting,
• what did that do?
• okay now how do I how do I designate which users are intended to be operators?

[ywangd]

Added two sentences to make the transition smoother as suggested.

[tvernum]

I think we want to rethink this sentence. It's not problematic, because we made it do the right thing.

I think you want to restructure this whole section to say:

• We do this
• Because the infrastructure owners want this
• So we avoid this bad stuff

[ywangd]

You are right. It reads a bit negative for the restore process which isn't true. I reworded a bit and added some context.

[bytebilly]

1. I think Direct use is not supported is good for now, but we should revisit in a few releases to determine whether we're ready to support it for customers on Enterprise licenses with their own orchestration layers. @bytebilly should we think about this in 2-3 months?

Agreed. This is an option we can consider in the future if we are comfortable.
Do we have telemetry for this feature to support our future decisions based on the usage?

2. Should we have this warning, or a lighter version on every page? (@lcawl, do you have a view?)

I'd like to see it as users may reach the page directly via links or searches. That's not the same for autoscaling docs, so we may want to be consistent whatever we'll decide.

[ywangd]

Do we have telemetry for this feature to support our future decisions based on the usage?

Yes we do have it (#65867)

1. Should we have this warning, or a lighter version on every page? (@lcawl, do you have a view?)

I'd like to see it as users may reach the page directly via links or searches. That's not the same for autoscaling docs, so we may want to be consistent whatever we'll decide.

The warning header is now added to almost every page of autoscaling doc with #67202. I think it is reasonable for me to do the same here.

[lcawl]

I've added a commit with some minor doc edits, now it LGTM

[bytebilly]

I'd like to see it as users may reach the page directly via links or searches. That's not the same for autoscaling docs, so we may want to be consistent whatever we'll decide.

The warning header is now added to almost every page of autoscaling doc with #67202. I think it is reasonable for me to do the same here.

Oh I see it is included in API docs, but it's not included in autoscaling subpages here (except this first one): https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-autoscaling.html

However, +1 to have the banner everywhere.

[lockewritesdocs]

@ywangd, I was doing a drive-by view of these docs and am curious if we want to make these instructions more Cloud-first, since operator privileges apply only to our Elastic Cloud services. For example, we mention the elasticsearch.yml file but don't tell users where to find it. Users need to edit their deployment, navigate to Elasticsearch, and then choose to edit that file.

Similarly, we mention the operator_users.yml file, but don't inform users of its location. Saying that the file " is located in the config directory (as defined by the ES_PATH_CONF environment variable)" makes sense for on-prem deployments, but how will Cloud users access this file? Can they access it from their deployment (like elasticsearch.yml), or do they have to SSH into each node to modify that file? Does an operator user have privileges to SSH into nodes and copy files, or would they need an administrator user to make those changes?

[tvernum]

@lockewritesdocs Thanks for the suggestions - drive by is a great way to find out how the docs land on someone without much existing knowledge of the feature.

They missing piece here is that operator privileges are (actually will be because it's turned on yet) enabled automatically in Cloud and cannot be configured by the customer. The point of the feature is that it's something we enable to reduce the number of ways that deployments can be broken/destabilized/etc by end users (by stopping them from being able to affect the parts of the system that are managed by the cloud platform itself).

We probably need to prepare a separate PR (because it's not live in ESS yet) that changes these docs to explain that this setting is always on in cloud, and if cloud customers are running into "you need to be an operator to do this" errors, that means the platform is intentionally stopping them from doing something, and they can't change it.

[ywangd]

Thanks @lockewritesdocs As Tim said, this feature is not meant for end users on Cloud. But your comment did prompt me to think that we should state the fact that Cloud manages this feature exclusively. I will raise another PR to add it once it is implemented by Cloud as Tim suggested.

[lockewritesdocs]

Thank you for the context and explanation @tvernum! I agree that we need to inform users that this setting is always on in Cloud, and what interaction they should anticipate as an operator user.

The point of the feature is that it's something we enable to reduce the number of ways that deployments can be broken/destabilized/etc by end users (by stopping them from being able to affect the parts of the system that are managed by the cloud platform itself).

Further explaining this use case would also help distinguish why users would enable operator privileges for on-prem deployments. Essentially, we're providing users a way to implement guardrails that restrict permissions and keep other users from doing potentially damaging things. I added a comment with a suggestion to expand this explanation.

I'm happy to help with the follow-up PR @ywangd -- just ping me whenever it's ready 👍

[tvernum]

If @lcawl is happy, I am. I don't think I need to do another full pass on it.