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

* 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) Co-authored-by: Colleen McGinnis <[email protected]>
elastic · Oct 7, 2024 · 8b10538 · 8b10538
1 parent 7f6d0b0
commit 8b10538
Show file tree

Hide file tree

Showing 5 changed files with 429 additions and 368 deletions.
diff --git a/docs/en/apm-server/redirects.asciidoc b/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

diff --git a/docs/en/observability/apm/configure/advanced-setup/command-reference.asciidoc b/docs/en/observability/apm/configure/advanced-setup/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.