add content from apm-server/docs branch 8.11 (#3434)

docs/en/apm-server/access-api-keys.asciidoc

@@ -0,0 +1,173 @@
+[role="xpack"]
+[[beats-api-keys]]
+=== Grant access using API keys
+
+Instead of using usernames and passwords, you can use API keys to grant
+access to {es} resources. You can set API keys to expire at a certain time,
+and you can explicitly invalidate them. Any user with the `manage_api_key`
+or `manage_own_api_key` cluster privilege can create API keys.
+
+{beatname_uc} instances typically send both collected data and monitoring
+information to {es}. If you are sending both to the same cluster, you can use the same
+API key. For different clusters, you need to use an API key per cluster.
+
+NOTE: For security reasons, we recommend using a unique API key per {beatname_uc} instance.
+You can create as many API keys per user as necessary.
+
+[float]
+[[beats-api-key-publish]]
+==== Create an API key for writing events
+
+In {kib}, navigate to **{stack-manage-app}** > **API keys** and 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**.
+In the role descriptors box, assign the appropriate privileges to the new API key. For example:
+
+[source,json,subs="attributes,callouts"]
+----
+{
+    "{beat_default_index_prefix}_writer": {
+        "index": [
+            {
+                "names": ["{beat_default_index_prefix}-*"],
+                "privileges": ["create_index", "create_doc"]
+            }
+        ]
+    },
+    "{beat_default_index_prefix}_sourcemap": {
+        "index": [
+            {
+                "names": [".apm-source-map"],
+                "privileges": ["read"]
+            }
+        ]
+    },
+    "{beat_default_index_prefix}_agentcfg": {
+        "index": [
+            {
+                "names": [".apm-agent-configuration"],
+                "privileges": ["read"]
+            }
+        ]
+    }
+}
+----
+
+NOTE: This example only provides privileges for **writing data**.
+See <<feature-roles>> for additional privileges and information.
+
+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 +{beatname_lc}.yml+ configuration file:
+
+["source","yml",subs="attributes"]
+--------------------
+output.elasticsearch:
+  api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA <1>
+--------------------
+<1> Format is `id:api_key` (as shown in the {beats} dropdown)
+
+[float]
+[[beats-api-key-monitor]]
+==== Create an API key for monitoring
+
+In {kib}, navigate to **{stack-manage-app}** > **API keys** and 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**.
+In the role descriptors box, assign the appropriate privileges to the new API key.
+For example:
+
+[source,json,subs="attributes,callouts"]
+----
+{
+    "{beat_default_index_prefix}_monitoring": {
+        "index": [
+            {
+                "names": [".monitoring-beats-*"],
+                "privileges": ["create_index", "create_doc"]
+            }
+      ]
+    }
+}
+----
+
+NOTE: This example only provides privileges for **publishing monitoring data**.
+See <<feature-roles>> for additional privileges and information.
+
+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 +{beatname_lc}.yml+ configuration file like this:
+
+["source","yml",subs="attributes"]
+--------------------
+monitoring.elasticsearch:
+  api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA <1>
+--------------------
+<1> Format is `id:api_key` (as shown in the {beats} dropdown)
+
+[float]
+[[beats-api-key-es]]
+==== Create an API key with {es} APIs
+
+You can also use {es}'s {ref}/security-api-create-api-key.html[Create API key API] to create a new API key.
+For example:
+
+[source,console,subs="attributes,callouts"]
+------------------------------------------------------------
+POST /_security/api_key
+{
+  "name": "{beat_default_index_prefix}_host001", <1>
+  "role_descriptors": {
+    "{beat_default_index_prefix}_writer": { <2>
+      "index": [
+        {
+          "names": ["{beat_default_index_prefix}-*"],
+          "privileges": ["create_index", "create_doc"]
+        }
+      ]
+    },
+    "{beat_default_index_prefix}_sourcemap": {
+      "index": [
+        {
+          "names": [".apm-source-map"],
+          "privileges": ["read"]
+        }
+      ]
+    },
+    "{beat_default_index_prefix}_agentcfg": {
+      "index": [
+        {
+          "names": [".apm-agent-configuration"],
+          "privileges": ["read"]
+        }
+      ]
+    }
+  }
+}
+------------------------------------------------------------
+<1> Name of the API key
+<2> Granted privileges, see <<feature-roles>>
+
+See the {ref}/security-api-create-api-key.html[Create API key] reference for more information.
+
+[[learn-more-api-keys]]
+[float]
+==== Learn more about API keys
+
+See the {es} API key documentation for more information:
+
+* {ref}/security-api-create-api-key.html[Create API key]
+* {ref}/security-api-get-api-key.html[Get API key information]
+* {ref}/security-api-invalidate-api-key.html[Invalidate API key]

docs/en/apm-server/agent-server-compatibility.asciidoc

@@ -0,0 +1,51 @@
+[[agent-server-compatibility]]
+=== {apm-agent} compatibility
+
+The chart below outlines the compatibility between different versions of Elastic APM agents and extensions with the APM integration.
+
+[options="header"]
+|====
+|Language |{apm-agent} version |APM integration version
+// APM AWS Lambda extension
+.1+|**APM AWS Lambda extension**
+|`1.x` |≥ `8.2`
+
+// Go
+.2+|**Go agent**
+|`1.x` |≥ `6.5`
+|`2.x` |≥ `6.5`
+
+// iOS
+.1+|**iOS agent**
+|`0.x` |≥ `7.14`
+
+// Java
+.1+|**Java agent**
+|`1.x`|≥ `6.5`
+
+// .NET
+.1+|**.NET agent**
+|`1.x` |≥ `6.5`
+
+// Node
+.1+|**Node.js agent**
+|`3.x` |≥ `6.6`
+
+// PHP
+.1+|**PHP agent**
+|`1.x` |≥ `7.0`
+
+// Python
+.1+|**Python agent**
+|`6.x` |≥ `6.6`
+
+// Ruby
+.2+|**Ruby agent**
+|`3.x` |≥ `6.5`
+|`4.x` |≥ `6.5`
+
+// RUM
+.2+|**JavaScript RUM agent**
+|`4.x` |≥ `6.5`
+|`5.x` |≥ `7.0`
+|====

docs/en/apm-server/anonymous-auth.asciidoc

@@ -0,0 +1,63 @@
+[[anonymous-auth]]
+=== Anonymous authentication
+
+Elastic APM agents can send unauthenticated (anonymous) events to the APM Server.
+An event is considered to be anonymous if no authentication token can be extracted from the incoming request.
+The APM Server's default response to these these requests depends on its configuration:
+
+[options="header"]
+|====
+|Configuration |Default
+|An <<api-key,API key>> or <<secret-token,secret token>> is configured | Anonymous requests are rejected and an authentication error is returned.
+|No API key or secret token is configured | Anonymous requests are accepted by the APM Server.
+|====
+
+In some cases, however, it makes sense to allow both authenticated and anonymous requests.
+For example, it isn't possible to authenticate requests from front-end services as
+the secret token or API key can't be protected. This is the case with the Real User Monitoring (RUM)
+agent running in a browser, or the iOS/Swift agent running in a user application.
+However, you still likely want to authenticate requests from back-end services.
+To solve this problem, you can enable anonymous authentication in the APM Server to allow the
+ingestion of unauthenticated client-side APM data while still requiring authentication for server-side services.
+
+[float]
+[[anonymous-auth-config]]
+=== Configuring anonymous auth for client-side services
+
+[NOTE]
+====
+You can only enable and configure anonymous authentication if an <<api-key,API key>> or
+<<secret-token,secret token>> is configured. If neither are configured, these settings will be ignored.
+====
+
+include::{tab-widget-dir}/anonymous-auth-widget.asciidoc[]
+
+[float]
+[[derive-client-ip]]
+=== Deriving an incoming request's `client.ip` address
+
+The remote IP address of an incoming request might be different
+from the end-user's actual IP address, for example, because of a proxy. For this reason,
+the APM Server attempts to derive the IP address of an incoming request from HTTP headers.
+The supported headers are parsed in the following order:
+
+1. `Forwarded`
+2. `X-Real-Ip`
+3. `X-Forwarded-For`
+
+If none of these headers are present, the remote address for the incoming request is used.
+
+[float]
+[[derive-client-ip-concerns]]
+==== Using a reverse proxy or load balancer
+
+HTTP headers are easily modified;
+it's possible for anyone to spoof the derived `client.ip` value by changing or setting,
+for example, the value of the `X-Forwarded-For` header.
+For this reason, if any of your clients are not trusted,
+we recommend setting up a reverse proxy or load balancer in front of the APM Server.
+
+Using a proxy allows you to clear any existing IP-forwarding HTTP headers,
+and replace them with one set by the proxy.
+This prevents malicious users from cycling spoofed IP addresses to bypass the
+APM Server's rate limiting feature.

docs/en/apm-server/api-config.asciidoc

@@ -0,0 +1,98 @@
+[[api-config]]
+=== Elastic APM agent configuration API
+
+APM Server exposes API endpoints that allow Elastic APM agents to query the APM Server for configuration changes.
+More information on this feature is available in {kibana-ref}/agent-configuration.html[{apm-agent} configuration in {kib}].
+
+[float]
+[[api-config-endpoint]]
+=== Agent configuration endpoints
+
+[options="header"]
+|====
+|Name |Endpoint
+|Agent configuration intake |`/config/v1/agents`
+|RUM configuration intake |`/config/v1/rum/agents`
+|====
+
+The Agent configuration endpoints accepts both `HTTP GET` and `HTTP POST` requests.
+If an <<api-key>> or <<secret-token>> is configured, requests to this endpoint must be authenticated.
+
+[float]
+[[api-config-api-get]]
+==== HTTP GET
+
+`service.name` is a required query string parameter.
+
+[source,bash]
+------------------------------------------------------------
+http(s)://{hostname}:{port}/config/v1/agents?service.name=SERVICE_NAME
+------------------------------------------------------------
+
+[float]
+[[api-config-api-post]]
+==== HTTP POST
+
+Encode parameters as a JSON object in the body.
+`service.name` is a required parameter.
+
+[source,bash]
+------------------------------------------------------------
+http(s)://{hostname}:{port}/config/v1/agents
+{
+  "service": {
+      "name": "test-service",
+      "environment": "all"
+  },
+  "CAPTURE_BODY": "off"
+}
+------------------------------------------------------------
+
+[float]
+[[api-config-api-response]]
+==== Responses
+
+* Successful - `200`
+* APM Server is configured to fetch agent configuration from {es} but the configuration is invalid - `403`
+* APM Server is starting up or {es} is unreachable - `503`
+
+[float]
+[[api-config-api-example]]
+==== Example request
+
+Example Agent configuration `GET` request including the service name "test-service":
+
+["source","sh",subs="attributes"]
+---------------------------------------------------------------------------
+curl -i http://127.0.0.1:8200/config/v1/agents?service.name=test-service
+---------------------------------------------------------------------------
+
+Example Agent configuration `POST` request including the service name "test-service":
+
+["source","sh",subs="attributes"]
+---------------------------------------------------------------------------
+curl -X POST http://127.0.0.1:8200/config/v1/agents \
+  -H "Authorization: Bearer secret_token" \
+  -H 'content-type: application/json' \
+  -d '{"service": {"name": "test-service"}}'
+---------------------------------------------------------------------------
+
+[float]
+[[api-config-api-ex-response]]
+==== Example response
+
+["source","sh",subs="attributes"]
+---------------------------------------------------------------------------
+HTTP/1.1 200 OK
+Cache-Control: max-age=30, must-revalidate
+Content-Type: application/json
+Etag: "7b23d63c448a863fa"
+Date: Mon, 24 Feb 2020 20:53:07 GMT
+Content-Length: 98
+
+{
+    "capture_body": "off",
+    "transaction_max_spans": "500",
+    "transaction_sample_rate": "0.3"
+}
+---------------------------------------------------------------------------