diff --git a/docs/en/observability/apm/configure/agent-config.asciidoc b/docs/en/observability/apm/configure/agent-config.asciidoc index 2550290cd1..e0dbc3203c 100644 --- a/docs/en/observability/apm/configure/agent-config.asciidoc +++ b/docs/en/observability/apm/configure/agent-config.asciidoc @@ -21,8 +21,10 @@ Here's a sample configuration: [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 configuration options @@ -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 APM agent configuration: APM agent log: @@ -72,3 +77,10 @@ This occurs because the user or API key set in either `apm-server.agent.config.e (if `apm-server.agent.config.elasticsearch` is not set) does not have adequate permissions to read source maps from {es}. To fix this error, ensure that APM Server has all the required privileges. See <> for more details. + +[float] +==== HTTP 401 errors + +If you get an HTTP 401 errors 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 <>. diff --git a/docs/en/observability/apm/configure/outputs/elasticsearch.asciidoc b/docs/en/observability/apm/configure/outputs/elasticsearch.asciidoc index 6cb626fbbe..4aaf55a54e 100644 --- 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 <> 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 <>. +// 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 index a73c37445a..2bb9b3469f 100644 --- 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 <>. +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 new file mode 100644 index 0000000000..8b7a76952c Binary files /dev/null and b/docs/en/observability/apm/images/apm-api-key-beats.png differ 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 index d763055fd0..4626e997f9 100644 --- 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 <> 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"] --------------------