Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[apm] Update APM feature roles docs #4193

Merged
merged 19 commits into from
Oct 7, 2024
Merged

[apm] Update APM feature roles docs #4193

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
b5818d5
initial attempt
colleenmcginnis Aug 22, 2024
c2eb01b
restructure
colleenmcginnis Aug 23, 2024
ed83d71
fix build
colleenmcginnis Aug 23, 2024
671382f
address initial feedback
colleenmcginnis Aug 28, 2024
ae55f4e
Merge branch 'main' into issue-3980
colleenmcginnis Sep 20, 2024
90e213e
deprecate api key role
colleenmcginnis Sep 20, 2024
8cdb6cb
fix typo
colleenmcginnis Sep 20, 2024
571a58c
add use cases
colleenmcginnis Sep 20, 2024
c8fb50d
reframe what we mean by users
colleenmcginnis Sep 20, 2024
e0be572
fix redirect
colleenmcginnis Sep 23, 2024
0e65820
add monitor privilege
colleenmcginnis Sep 25, 2024
9a23532
clean up structure
colleenmcginnis Sep 25, 2024
21ed200
Update docs/en/observability/apm/feature-roles.asciidoc
colleenmcginnis Oct 2, 2024
10ba5c9
update docs/en/observability/apm/feature-roles.asciidoc
colleenmcginnis Oct 3, 2024
03fbafd
Update feature-roles.asciidoc
colleenmcginnis Oct 3, 2024
9ba0f02
update docs/en/observability/apm/feature-roles.asciidoc
colleenmcginnis Oct 3, 2024
d3f19ba
use roles api in central config section
colleenmcginnis Oct 4, 2024
440d2ce
Merge branch 'main' into issue-3980
colleenmcginnis Oct 7, 2024
72c3693
apply suggestions from code review
colleenmcginnis Oct 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/en/apm-server/redirects.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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-feature-roles.html#apm-privileges-api-key[Create an _API key_ user].

[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
Expand Down
222 changes: 131 additions & 91 deletions docs/en/observability/apm/feature-roles.asciidoc
View file
Open in desktop
colleenmcginnis marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ NOTE: This documentation only applies to the APM Server binary.

Use role-based access control or API keys to grant APM Server users access to secured resources.

* <<apm-feature-roles>>
* <<apm-beats-api-keys>>.
* <<apm-feature-roles,Create and assign feature roles to users>>
* <<apm-beats-api-keys>>

After privileged users have been created, use authentication to connect to a secured Elastic cluster.

Expand All @@ -29,23 +29,43 @@ APM Server exposes an HTTP endpoint, and as with anything that opens ports on yo
you should be careful about who can connect to it.
Firewall rules are recommended to ensure only authorized systems can connect.

[float]
[[apm-feature-roles]]
=== Feature roles
=== Create and assign feature roles to users

++++
<titleabbrev>Use feature roles</titleabbrev>
++++

You can use role-based access control to grant users access to secured
resources. The roles that you set up depend on your organization's security
requirements and the minimum privileges required to use specific features.
It's recommended that you only grant users the minimum privileges required to use specific features. One approach to managing access on a feature-by-feature basis is to create several feature-related _roles_ and assign one or more of these roles to each _user or group_ based on which features the user needs to access.

Typically, you need to create the following separate roles:
[TIP]
====
A _role_ identifies a set of permissions that translate to privileges on resources. You can associate a _user or group_ with an arbitrary number of roles. The total set of permissions that a user has is defined by the union of the permissions in all its roles.
====

* <<apm-privileges-to-publish-events,Writer role>>: To publish events collected by APM Server.
* <<apm-privileges-to-publish-monitoring,Monitoring role>>: One for sending monitoring
information, and another for viewing it.
* <<apm-privileges-api-key,API key role>>: To create and manage API keys.
* <<apm-privileges-agent-central-config,Central configuration management role>>: To view
APM Agent central configurations.
* <<apm-privileges-rum-source-mapping,RUM source mapping role>>: To read RUM source maps.
Below are some common tasks that users in your organization might need to do and links to more information on creating roles that provides access to the right resources:

* <<apm-privileges-agent-central-config,*Central configuration management role*>>:
Allows a user to view APM Agent central configurations, which is *required* when
<<apm-agent-configuration,central configuration management>> is enabled (it is enabled by default).
* <<apm-privileges-to-publish-events,*Writer role*>>:
colleenmcginnis marked this conversation as resolved.
Show resolved Hide resolved
Allows a user to publish events collected by APM Server.
* <<apm-privileges-to-publish-monitoring,*Monitoring role*>>: Allows a user to publish monitoring data,
view monitoring data, or both.
* <<apm-privileges-api-key,*API key role*>>: Allow a user to create and manage API keys.
colleenmcginnis marked this conversation as resolved.
Show resolved Hide resolved
* <<apm-privileges-rum-source-mapping,*RUM source mapping role*>>: Allows a user to read RUM source maps.

// Is "deployment" the right word?
colleenmcginnis marked this conversation as resolved.
Show resolved Hide resolved
.Example: Assigning multiple roles to a user
*****
For example, if you have a user in your organization who needs to be able to <do something> in a deployment where
central configuration management is enabled and <<apm-configuration-rum,real user monitoring>> is enabled,
you would need to assign three of the roles listed above to the user:

* <<apm-privileges-agent-central-config,Central configuration management role>>
* <<apm-privileges-to-publish-events,Writer role>>
* <<apm-privileges-to-publish-events,RUM source mapping role>>
*****

{es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a
subset of the privileges needed by APM users.
Expand All @@ -62,18 +82,60 @@ In general, there are three types of privileges you'll work with:
*********************************** ***********************************
////

[[apm-privileges-to-publish-events]]
=== Grant privileges and roles needed for writing events
[float]
[[apm-privileges-agent-central-config]]
=== Create a _central config_ role

++++
<titleabbrev>Create a _writer_ user</titleabbrev>
++++
[[apm-central-config-role-note]]
[IMPORTANT]
====
The privileges included in this role are *required* for all users when <<apm-agent-configuration,central configuration management>> is enabled (it is enabled by default). You do _not_ need the _Central configuration management_ role only if central configuration management has been explicitly disabled in the APM UI.
====

APM users that publish events to {es} need privileges to write to APM data streams.
[[apm-privileges-agent-central-config-server]]
APM Server acts as a proxy between your APM agents and the APM UI.
The APM UI communicates any changed settings to APM Server so that your agents only need to poll the Server
to determine which central configuration settings have changed.

To grant an APM Server user with the required privileges for managing central configuration in {es} without {kib},
assign the user the following privileges:

[options="header"]
|====
|Type | Privilege | Purpose

| Index
|`read` on `.apm-agent-configuration` index, `allow_restricted_indices: true`
|Allow APM Server to manage central configurations in {es}
colleenmcginnis marked this conversation as resolved.
Show resolved Hide resolved
|====

The above privileges should be sufficient for APM agent central configuration to work properly
as long as APM Server communicates with {es} successfully.
If it fails, it may fallback to read agent central configuration via {kib} if configured,
which requires the following privileges:

[options="header"]
|====
|Type | Privilege | Purpose

| Spaces
|`Read` on APM UI
|Allow APM Server to manage central configurations via the APM UI
|====

TIP: Looking for privileges and roles needed to use central configuration from the APM UI or APM UI API?
See <<apm-app-central-config-user,APM UI central configuration user>>.

////
*********************************** ***********************************
*********************************** ***********************************
////

[float]
==== General writer role
[[apm-privileges-to-publish-events]]
=== Create a _writer_ role

APM users that publish events to {es} need privileges to write to APM data streams.
colleenmcginnis marked this conversation as resolved.
Show resolved Hide resolved
To grant an APM user the required privileges for writing events to {es}:

. Create a *general writer role*, called something like `apm_writer`,
Expand All @@ -93,20 +155,22 @@ that has the following privileges:
|====
colleenmcginnis marked this conversation as resolved.
Show resolved Hide resolved

. Assign the *general writer role* to users who need to publish APM data.
. Assign <<apm-feature-roles,additional APM feature roles>> to users as needed
(including the _Central configuration management role_, which is <<apm-central-config-role-note,required in most cases>>).

. If <<apm-configuration-rum,real user monitoring>> is enabled, create a separate <<apm-privileges-rum-source-mapping,RUM source mapping role>>.
[NOTE]
====
If <<apm-configuration-rum,real user monitoring>> is enabled, create a separate <<apm-privileges-rum-source-mapping,RUM source mapping role>>.
====

////
*********************************** ***********************************
*********************************** ***********************************
////

[float]
[[apm-privileges-to-publish-monitoring]]
=== Grant privileges and roles needed for monitoring

++++
<titleabbrev>Create a _monitoring_ user</titleabbrev>
++++
=== Create a _monitoring_ role

{es-security-features} provides built-in users and roles for publishing and viewing monitoring data.
The privileges and roles needed to publish monitoring data
Expand All @@ -133,8 +197,14 @@ Monitoring on {ecloud} is enabled by clicking the *Enable* button in the *Monito
===== Internal collection

If you're using <<apm-monitoring-internal-collection,internal collection>> to
collect metrics about APM Server, {security-features} provides
the +apm_system+ {ref}/built-in-users.html[built-in user] and
collect metrics about APM Server, you can either:

* Use the built-in `apm_system` user or role
* Create a custom role

*Use a built-in user or role*

{security-features} provides the +apm_system+ {ref}/built-in-users.html[built-in user] and
+apm_system+ {ref}/built-in-roles.html[built-in role] to send
monitoring information. You can use the built-in user, if it's available in your
environment, or create a user who has the built-in role assigned,
Expand All @@ -144,7 +214,9 @@ information.
If you use the built-in +apm_system+ user,
make sure you set the password before using it.

If you don't use the +apm_system+ user:
*Create a custom role*

If you don't use the +apm_system+ user, you can create a custom role:

--
. Create a *monitoring role*, called something like
Expand All @@ -164,6 +236,8 @@ If you don't use the +apm_system+ user:
|====
+
. Assign the *monitoring role* to users who need to write monitoring data to {es}.
. Assign <<apm-feature-roles,additional APM feature roles>> to users as needed
(including the _Central configuration management role_, which is <<apm-central-config-role-note,required in most cases>>).
colleenmcginnis marked this conversation as resolved.
Show resolved Hide resolved
--

[float]
Expand All @@ -176,7 +250,14 @@ See <<apm-monitoring-metricbeat-collection>>
for complete details on setting up {metricbeat} collection.

If you're <<apm-monitoring-metricbeat-collection,using {metricbeat}>> to collect
metrics about APM Server, {security-features} provides the `remote_monitoring_user`
metrics about APM Server, you can either:

* Use the built-in `remote_monitoring_user` user or role
* Create a custom user

*Use a built-in user or role*

{security-features} provides the `remote_monitoring_user`
{ref}/built-in-users.html[built-in user], and the `remote_monitoring_collector`
and `remote_monitoring_agent` {ref}/built-in-roles.html[built-in roles] for
collecting and sending monitoring information. You can use the built-in user, if
Expand All @@ -186,7 +267,9 @@ needed to collect and send monitoring information.
If you use the built-in `remote_monitoring_user` user,
make sure you set the password before using it.

If you don't use the `remote_monitoring_user` user:
*Create a custom user*

If you don't use the `remote_monitoring_user` user, you can create a custom user:

--
. Create a *monitoring user* on the production cluster who will collect and send monitoring
Expand All @@ -202,6 +285,9 @@ information. Assign the following roles to the *monitoring user*:
|`remote_monitoring_agent`
|Send monitoring data to the monitoring cluster
|====

. Assign <<apm-feature-roles,additional APM feature roles>> to the *monitoring user* as needed
(including the _Central configuration management role_, which is <<apm-central-config-role-note,required in most cases>>).
--

[float]
Expand Down Expand Up @@ -236,20 +322,20 @@ need to view monitoring data for APM Server:
|`monitoring_user`
|Grants access to monitoring indices for APM Server
|====
. Assign <<apm-feature-roles,additional APM feature roles>> to users as needed
(including the _Central configuration management role_, which is <<apm-central-config-role-note,required in most cases>>).

////
*********************************** ***********************************
*********************************** ***********************************
////

[float]
[[apm-privileges-api-key]]
=== Grant privileges and roles needed for API key management

++++
<titleabbrev>Create an _API key_ user</titleabbrev>
++++
=== Create an _API key_ role
colleenmcginnis marked this conversation as resolved.
Show resolved Hide resolved

You can configure <<apm-api-key,API keys>> to authorize requests to APM Server.

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`,
Expand All @@ -269,13 +355,14 @@ 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`.

. Assign the **API key role** to users that need to create and manage API keys.
Users with this role can only create API keys that have the same or lower access rights.
. Assign <<apm-feature-roles,additional APM feature roles>> to users as needed
(including the _Central configuration management role_, which is <<apm-central-config-role-note,required in most cases>>).

[float]
[[apm-privileges-api-key-example]]
=== Example API key role
==== Example API key role

The following example assigns the required cluster privileges,
and the ingest agent data `apm` API key application privileges to a role named `apm_api_key`:
Expand Down Expand Up @@ -310,61 +397,11 @@ PUT _security/role/apm_api_key <1>
*********************************** ***********************************
////

[[apm-privileges-agent-central-config]]
=== Grant privileges and roles needed for APM Agent central configuration

++++
<titleabbrev>Create a _central config_ user</titleabbrev>
++++

[float]
[[apm-privileges-agent-central-config-server]]
==== APM Server agent central configuration management

APM Server acts as a proxy between your APM agents and the APM UI.
The APM UI communicates any changed settings to APM Server so that your agents only need to poll the Server
to determine which central configuration settings have changed.

To grant an APM Server user with the required privileges for managing central configuration in {es} without {kib},
assign the user the following privileges:

[options="header"]
|====
|Type | Privilege | Purpose

| Index
|`read` on `.apm-agent-configuration` index, `allow_restricted_indices: true`
|Allow APM Server to manage central configurations in {es}
|====

The above privileges should be sufficient for APM agent central configuration to work properly
as long as APM Server communicates with {es} successfully.
If it fails, it may fallback to read agent central configuration via {kib} if configured,
which requires the following privileges:

[options="header"]
|====
|Type | Privilege | Purpose

| Spaces
|`Read` on APM UI
|Allow APM Server to manage central configurations via the APM UI
|====

TIP: Looking for privileges and roles needed to use central configuration from the APM UI or APM UI API?
See <<apm-app-central-config-user,APM UI central configuration user>>.

[[apm-privileges-rum-source-map]]
=== Grant privileges and roles needed for reading source maps

++++
<titleabbrev>Create a _source map_ user</titleabbrev>
++++
=== Create a _source map_ role

[float]
[[apm-privileges-rum-source-mapping]]
==== APM Server RUM source mapping

If <<apm-configuration-rum,real user monitoring>> is enabled, additional privileges are required to read source maps.

To grant an APM Server user with the required privileges for reading RUM source maps from {es} directly without {kib},
Expand All @@ -379,6 +416,9 @@ assign the user the following privileges:
|Allow APM Server to read RUM source maps from {es}
|====

Then assign <<apm-feature-roles,additional APM feature roles>> to users as needed
(including the _Central configuration management role_, which is <<apm-central-config-role-note,required in most cases>>).

The above privileges should be sufficient for RUM source mapping to work properly
as long as APM Server communicates with {es} successfully.
If it fails, it may fallback to read source maps via {kib} if configured,
Expand Down