[8.15](backport #4193) [apm] Update APM feature roles docs (#4356)

* [apm] Update APM feature roles docs (#4193)

* initial attempt

* restructure

* fix build

* address initial feedback

* deprecate api key role

* fix typo

* add use cases

* reframe what we mean by users

* fix redirect

* add monitor privilege

* clean up structure

* Update docs/en/observability/apm/feature-roles.asciidoc

Co-authored-by: Edoardo Tenani <[email protected]>

* update docs/en/observability/apm/feature-roles.asciidoc

* Update feature-roles.asciidoc

* update docs/en/observability/apm/feature-roles.asciidoc

* use roles api in central config section

* apply suggestions from code review

Co-authored-by: Mike Birnstiehl <[email protected]>

---------

Co-authored-by: Edoardo Tenani <[email protected]>
Co-authored-by: Mike Birnstiehl <[email protected]>
(cherry picked from commit d6a61fd)

# Conflicts:
#	docs/en/observability/apm/feature-roles.asciidoc

* fix conflicts

---------

Co-authored-by: Colleen McGinnis <[email protected]>

docs/en/apm-server/redirects.asciidoc

@@ -1114,35 +1114,35 @@ Refer to {observability-guide}/apm-secure-comms-stack.html[With the Elastic Stac
 
 {move-notice}
 
-Refer to {observability-guide}/apm-privileges-to-publish-events.html[Create a _writer_ user].
+Refer to {observability-guide}/apm-feature-roles.html#apm-privileges-to-publish-events[Create a _writer_ user].
 
 [role="exclude",id="privileges-to-publish-monitoring"]
 === Create a _monitoring_ user
 
 {move-notice}
 
-Refer to {observability-guide}/apm-privileges-to-publish-monitoring.html[Create a _monitoring_ user].
+Refer to {observability-guide}/apm-feature-roles.html#apm-privileges-to-publish-monitoring[Create a _monitoring_ user].
 
 [role="exclude",id="privileges-api-key"]
 === Create an _API key_ user
 
 {move-notice}
 
-Refer to {observability-guide}/apm-privileges-api-key.html[Create an _API key_ user].
+Refer to {observability-guide}/apm-command-line-options.html#apm-apikey-command[`apikey` command].
 
 [role="exclude",id="privileges-agent-central-config"]
 === Create a _central config_ user
 
 {move-notice}
 
-Refer to {observability-guide}/apm-privileges-agent-central-config.html[Create a _central config_ user].
+Refer to {observability-guide}/apm-feature-roles.html#apm-privileges-agent-central-config[Create a _central config_ user].
 
 [role="exclude",id="privileges-rum-source-map"]
 === Create a _source map_ user
 
 {move-notice}
 
-Refer to {observability-guide}/apm-privileges-rum-source-map.html[Create a _source map_ user].
+Refer to {observability-guide}/apm-feature-roles.html#apm-privileges-rum-source-map[Create a _source map_ user].
 
 [role="exclude",id="beats-api-keys"]
 === Grant access using API keys

docs/en/observability/apm/command-reference.asciidoc

@@ -2,7 +2,7 @@
 
 :deploy-command-short-desc: Deploys the specified function to your serverless environment
 
-:apikey-command-short-desc: Manage API Keys for communication between APM agents and server.
+:apikey-command-short-desc: Manage API Keys for communication between APM agents and server
 
 ifndef::serverless[]
 :export-command-short-desc: Exports the configuration, index template, or {ilm-init} policy to stdout
@@ -57,7 +57,9 @@ more information, see https://www.elastic.co/subscriptions and
 [options="header"]
 |=======================
 |Commands |
-|<<apm-apikey-command,`apikey`>> |{apikey-command-short-desc}.
+|<<apm-apikey-command,`apikey`>> a| {apikey-command-short-desc}.
+
+deprecated::[8.6.0, Users should create API Keys through {kib} or the {es} REST API. See <<apm-api-key>>.]
 |<<apm-export-command,`export`>> |{export-command-short-desc}.
 |<<apm-help-command,`help`>> |{help-command-short-desc}.
 ifndef::serverless[]
@@ -101,8 +103,31 @@ apm-server apikey SUBCOMMAND [FLAGS]
 Create an API Key with the specified privilege(s). No required flags.
 +
 The user requesting to create an API Key needs to have APM privileges used by the APM Server.
-A superuser, by default, has these privileges. For other users,
-you can create them. See <<apm-privileges-api-key,create an API key user>> for required privileges.
+A superuser, by default, has these privileges.
++
+.*Expand for more information on assigning these privileges to other users*
+[%collapsible]
+====
+To create an APM Server user with the required privileges for creating and managing API keys:
+
+. Create an **API key role**, called something like `apm_api_key`,
+that has the following `cluster` level privileges:
++
+[options="header"]
+|====
+| Privilege | Purpose
+
+|`manage_own_api_key`
+|Allow APM Server to create, retrieve, and invalidate API keys
+|====
+
+. Depending on what the **API key role** will be used for,
+also assign the appropriate `apm` application-level privileges:
++
+* To **receive Agent configuration**, assign `config_agent:read`.
+* To **ingest agent data**, assign `event:write`.
+* To **upload source maps**, assign `sourcemap:write`.
+====
 
 *`info`*::
 Query API Key(s). `--id` or `--name` required.