[Documentation] Update doc to include missing API attribute

[RobsonSutton]

• Identified as missing through investigation into [Bug] Unable to use the option allow_restricted_indices when creating security role terraform-provider-elasticstack#125

[RobsonSutton]

Related to #81400 - requirement for setting this may increase now that these permissions have been removed from the superuser role

[elasticsearchmachine]

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

[elasticsearchmachine]

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

[abdonpijpelink]

Would someone in the @elastic/es-security team mind taking a look at this proposed description for the allow_restricted_indices field of the Create or update roles API?

For example, in the Has privileges API docs we describe allow_restricted_indices as pasted below. I wonder if we should use that description instead.

(Boolean) This needs to be set to true (default is false) if using wildcards or regexps for patterns that cover restricted indices. Implicitly, restricted indices do not match index patterns because restricted indices usually have limited privileges and including them in pattern tests would render most such tests false. If restricted indices are explicitly included in the names list, privileges will be checked against them regardless of the value of allow_restricted_indices.

[ywangd]

There is no good reason to manually write to any system indices. If read permission is needed, the superuser role is available. I suspect it might be intentional that this paramater is not documented. I don't have all the history context for it, but I slightly prefer leaving it out as is. If we do want to document it, some form of warning like what's proposed in the PR is helpful.

[RobsonSutton]

@ywangd - For a bit of context, the support of this setting was requested by a consumer in the elasticstack terraform provider (elastic/terraform-provider-elasticstack#125) off the back of elastic support advice by the looks of it (I think this may be the ref. - ITSI-17455). The setting has been added to the provider and the TF docs updated accordingly (elastic/terraform-provider-elasticstack#126).

Just figured I'd add to the API docs too for clarity is all so it was consistent across different sources of documentation 👍

[ywangd]

@RobsonSutton I am not familiar with the elastic stack terraform provider code. But why would the code want to provision a role that has write permission to system indices? As commented earlier, it is generally not recommended unless for adhoc emergency recovery. I suspect this is not the case for the terraform provider? Is the designated service account (e.g. elastic/fleet-server) not helpful in the use case? If so, this might be considered a bug in itself instead of trying to create a separate roles.

[RobsonSutton]

@ywangd - Apologies I'm not too sure of what the specific reasoning was for enabling this setting, it just appears that the user that raised the issue was advised to raise an issue to enable this setting by elastic support. I don't work for elastic so unfortunately don't have access to look into the support case for the consumer that raised the initial issue (elastic/terraform-provider-elasticstack#125), is this something you are able to view for more context?

[leemthompo]

Important

Elastic documentation is migrating to Markdown for version 9.0+. See the migration guide for details.

ℹ️ What's happening?

• Starting January 29, we will start closing all unmerged documentation PRs targeting main/master
• We're migrating from AsciiDoc to Markdown for 9.0+
• 9.0 docs will be frozen from January 29 until February 20 2024
• NOTE: PRs that include both code and documentation changes will remain open

What do I need to do?

For <=8.x docs:

1. Rebase your PR to target the relevant 8.x branch instead
2. The content can remain in AsciiDoc format

For 9.0+ docs:

Option 1:

• Draft docs in Markdown
• Once migration freeze ends, find the relevant page in the new docs system and use the edit options to submit your changes

Option 2:

• Open an issue in elastic/docs-content

💡 Need help?

1. For Elasticians: Ask in #docs Slack channel
2. For external contributors: Open an issue in elastic/docs-content