[REQUEST]: Document integrations requiring root privileges

[juliaElastic]

Description

With the support of unprivileged agents, users will be warned when packages requiring root are being used together with unprivileged agents.
It would be great to document the list of packages and data streams that require root privileges.
Currently the package level root requirement is being displayed on the Integrations UI - package details, though we don't have it documented yet which data streams require root (in case not all, e.g. system integration).

Resources

elastic/integrations#8642
https://github.com/elastic/ingest-dev/issues/3252

Collaboration

The documentation team will investigate the issue and create the initial content.

Point of contact.

Main contact: @juliaElastic

Stakeholders: @kpollich @nimarezainia

[kilfoyle]

@juliaElastic, @kpollich
I'm not sure where to gather the list of packages and data streams that require root privileges

Currently in the Integrations repo the only instances I see of

agent:
  privileges:
    root: true

are in these five packages:

repos • integrations/packages/auditd_manager/manifest.yml:
  40    privileges:
  41:     root: true

repos • integrations/packages/fim/manifest.yml:
  157    privileges:
  158:     root: true

repos • integrations/packages/network_traffic/manifest.yml:
  44    privileges:
  45:     root: true

repos • integrations/packages/system_audit/manifest.yml:
  31    privileges:
  32:     root: true

repos • integrations/packages/universal_profiling_agent/manifest.yml:
  67    privileges:
  68:     root: true

Is the idea that the root: true will be added to all packages and/or data streams that require root, in which case I should wait for that to happen?

[nimarezainia]

I don't think this can be done at a datastream level, it's a package level designation. update: this can be done at datastream level.
Should the information be updated here: https://docs.elastic.co/integrations/profiler_agent ? and automatically generated like the other stuff? i just don't think we should manually update the docs as they will become stale quickly.

Also I'm surprised Defend is not in the list above.

[juliaElastic]

I think it's good if we add a generic section to the Fleet docs and link to the integrations docs, if we can filter/search on those integrations that require root.
Defend has this setting, it's in a different repo: elastic/endpoint-package#458

This is the Meta issue for marking all integrations requiring root: elastic/integrations#8642

[nimarezainia]

Discussed this with @kilfoyle the action is as follows:

• In the Integrations repo, for each README modify the content to add the root permission requirement (for packages that have this set today).
• Figure out if there's a process that would allow future package developers who modify their packages to add root : true to also update the README
• In Fleet/Agent docs have a section that informs the user they should consult the Integration docs for the latest information on whether the integration requires root priv.
• in Fleet/Agent docs do show an example of which integrations require root priv.

cc: @cmacknz @ycombinator

[kilfoyle]

Quick update, and also a note to self:

The script that generates the integrations docs parses the key:value pairs in the integrations manifest files (whereas I thought the script only pulled in the readme content). Brandon is looking into updating that docs generation script so that the generated docs will automatically indicate that root permissions are required for the integration.

I'll wait for the outcome of Brandon's work, and also Shaunak's open issue to determine the prerequisites for running agent in unprivileged mode, and then I'll update the Fleet & Agent docs accordingly.

[kilfoyle]

I think this can be closed now as the guidance and limitations around using integrations without root or admin access are all covered in the new "Run Elastic Agent without administrative privileges" (see PR).

Details:

In the Integrations repo, for each README modify the content to add the root permission requirement (for packages that have this set today).

The "root permission" requirement shows up at the top of the integration page in Kibana. The integrations docs should reflect this so Brandon is working on that part. In the Fleet & Agent docs we recommend people just check the integrations UI page where the root requirement is indicated up at the top.

Figure out if there's a process that would allow future package developers who modify their packages to add root : true to also update the README

Same as above.

In Fleet/Agent docs have a section that informs the user they should consult the Integration docs for the latest information on whether the integration requires root priv.

The integrations docs don't yet indicate if root privileges are required (see above) so for now I've added a recommendation that users check the integrations UI: any integration that requires Elastic Agent to have root privileges has the requirement indicated at the top of the integration page in Kibana. I've added screen captures so it should be crystal clear for the users.

in Fleet/Agent docs do show an example of which integrations require root priv.

This "Using Elastic integrations" section lists the six integrations that currently require root privileges.