[apm] Clarify how to create/use API keys (#4670) (#4740)

* add information on beats api key * add section to common problems section of the apm config page * apply suggestions from code review Co-authored-by: Edu González de la Herrán <[email protected]> * fix typp --------- Co-authored-by: Edu González de la Herrán <[email protected]> (cherry picked from commit 0fee5c3) Co-authored-by: Colleen McGinnis <[email protected]>
elastic · Jan 3, 2025 · 829181c · 829181c
1 parent 710595d
commit 829181c
Show file tree

Hide file tree

Showing 5 changed files with 43 additions and 16 deletions.
diff --git a/docs/en/observability/apm/configure/agent-config.asciidoc b/docs/en/observability/apm/configure/agent-config.asciidoc
@@ -28,8 +28,10 @@ You can specify APM agent configuration options in the `apm-server.agent.config`
 [source,yaml]
 ----
 apm-server.agent.config.cache.expiration: 45s
-apm-server.agent.config.elasticsearch.api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA
+apm-server.agent.config.elasticsearch.api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA <1>
 ----
+<1> {blank}
+include::./outputs/elasticsearch.asciidoc[tag=configure-beats]
 
 [float]
 [[apm-agent-config-cache]]
@@ -52,6 +54,9 @@ use these {es} options to provide {es} access.
 [float]
 === Common problems
 
+[float]
+==== HTTP 403 errors
+
 You may see either of the following HTTP 403 errors from APM Server when it attempts to fetch
 the APM agent central configuration:
 
@@ -74,3 +79,10 @@ This occurs because the user or API key set in either `apm-server.agent.config.e
 
 To fix this error, ensure that APM Server has all the required privileges. For more details, refer to
 <<apm-privileges-agent-central-config-server,Create a _central configuration management_ role>>.
+
+[float]
+==== HTTP 401 errors
+
+If you get an HTTP 401 error from APM Server, make sure that you're using
+an API key that is configured to *Beats*. For details on how to create and configure a compatible
+API key, refer to <<apm-beats-api-key-publish>>.
diff --git a/docs/en/observability/apm/configure/outputs/elasticsearch.asciidoc b/docs/en/observability/apm/configure/outputs/elasticsearch.asciidoc
@@ -46,8 +46,10 @@ output.elasticsearch:
 ----
 output.elasticsearch:
   hosts: ["https://myEShost:9200"]
-  api_key: "ZCV7VnwBgnX0T19fN8Qe:KnR6yE41RrSowb0kQ0HWoA"
+  api_key: "ZCV7VnwBgnX0T19fN8Qe:KnR6yE41RrSowb0kQ0HWoA" <1>
 ----
+<1> {blank}
+include::elasticsearch.asciidoc[tag=configure-beats]
 
 *PKI certificate authentication:*
 
@@ -128,7 +130,13 @@ The default value is `false`.
 Instead of using a username and password, you can use API keys to secure communication
 with {es}. The value must be the ID of the API key and the API key joined by a colon: `id:api_key`.
 
-See <<apm-beats-api-keys>> for more information.
+// tag::configure-beats[]
+You _must_ set the API key to be configured to *Beats*.
+Base64 encoded API keys are not currently supported in this configuration.
+For details on how to create and configure a compatible API key, refer to <<apm-beats-api-key-publish>>.
+// end::configure-beats[]
+
+image::images/apm-api-key-beats.png[API key dropdown highlighting the Beats option]
 
 [float]
 ==== `username`

diff --git a/docs/en/observability/apm/https.asciidoc b/docs/en/observability/apm/https.asciidoc
@@ -37,7 +37,7 @@ output.elasticsearch:
   api_key: "KnR6yE41RrSowb0kQ0HWoA" <1>
 ----------------------------------------------------------------------
 <1> This API key must have the privileges required to publish events to {es}.
-To create an API key like this, see <<apm-beats-api-keys>>.
+include::./configure/outputs/elasticsearch.asciidoc[tag=configure-beats]
 --
 
 [[apm-beats-tls]]

diff --git a/docs/en/observability/apm/images/apm-api-key-beats.png b/docs/en/observability/apm/images/apm-api-key-beats.png
diff --git a/docs/en/observability/apm/security/elastic-stack/access-api-keys.asciidoc b/docs/en/observability/apm/security/elastic-stack/access-api-keys.asciidoc
@@ -17,15 +17,17 @@ You can create as many API keys per user as necessary.
 [[apm-beats-api-key-publish]]
 == Create an API key for writing events
 
-To open **API keys**, find **Stack Management** in the main menu or use the {kibana-ref}/introduction.html#kibana-navigation-search[global search field].
-Click **Create API key**.
+To create an API key:
 
+. Go to **Stack Management** in the main menu and find **API Keys** or use the {kibana-ref}/introduction.html#kibana-navigation-search[global search field].
+. Click **Create API key**.
++
 [role="screenshot"]
 image::images/server-api-key-create.png[API key creation]
-
-Enter a name for your API key and select **Restrict privileges**.
++
+. Enter a name for your API key and select **Restrict privileges**.
 In the role descriptors box, assign the appropriate privileges to the new API key. For example:
-
++
 [source,json,subs="attributes,callouts"]
 ----
 {
@@ -57,16 +59,21 @@ In the role descriptors box, assign the appropriate privileges to the new API ke
     }
 }
 ----
-
++
 NOTE: This example only provides privileges for **writing data**.
 See <<apm-feature-roles>> for additional privileges and information.
-
-To set an expiration date for the API key, select **Expire after time**
++
+. To set an expiration date for the API key, select **Expire after time**
 and input the lifetime of the API key in days.
-
-Click **Create API key**. In the dropdown, switch to **{beats}** and copy the API key.
-
-You can now use this API key in your +apm-server.yml+ configuration file:
+. Click **Create API key**.
+. You _must_ set the API key to be configured to {beats}.
+Immediately after the API key is generated and while it is still being displayed, click the
+**Encoded** button next to the API key and select **Beats** from the list in the tooltip.
+Base64 encoded API keys are not currently supported in this configuration.
++
+image::images/apm-api-key-beats.png[API key dropdown highlighting the Beats option]
+
+You can now use this API key in your `apm-server.yml` configuration file:
 
 ["source","yml",subs="attributes"]
 --------------------