Actionable error message when attempting to enroll an unprivileged Agent as a privileged user

[kaanyalti]

Version: 8.14.0
Operating System: Ubuntu 24.04 LTS
Platform: arm64

While working on this issue comparing root and unprivileged elastic agents, I encountered an error with the enroll command when using unprivileged agent.

Steps to Reproduce:

1. Deploy ESS v8.14.0
2. Create agent policy with system integration
3. Install fleet managed agent with the unprivileged flag sudo ./elastic-agent install --unprivileged --url=<fleet url> --enrollment-token=<token>
4. Unenroll the agent
5. Enroll the agent sudo elastic-agent enroll --url=<fleet url> --enrollment-token=<token>
6. Agent enrollment gets confirmed, but incoming data does not get confirmed
7. Agent status in fleet ui is stuck in updating
8. Running sudo elastic-agent status we get the following error

Error: failed to communicate with Elastic Agent daemon: rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing: dial unix /opt/Elastic/Agent/elastic-agent.sock: connect: connection refused"
For help, please see our troubleshooting guide at https://www.elastic.co/guide/en/fleet/8.14/fleet-troubleshooting.html

Definition of Done

Based on discussion in the comments:

• When a user installs an Agent using --unprivileged, then tries to enroll this Agent with a privileged user, an error message with the suggestions in Actionable error message when attempting to enroll an unprivileged Agent as a privileged user #4889 (comment) is shown to the user.

[kaanyalti]

cc: @ycombinator @cmacknz

[elasticmachine]

Pinging @elastic/elastic-agent-control-plane (Team:Elastic-Agent-Control-Plane)

[blakerouse]

If you installed the Elastic Agent with --unprivileged then running sudo elastic-agent enroll should fail as you are seeing. sudo is trying to run the command as root, but your Elastic Agent is not running as root.

You have a few options to make this work:

1. sudo -u elastic-agent-user elastic-agent enroll ...
2. Add your user to the elastic-agent group, create a new shell or use newgrp to ensure that the system knows that your user is now in that group. Then you can just call elastic-agent enroll.

[cmacknz]

When we are unprivileged, can we put that suggestion directly in the error here? I don't think this is the last time we'll see this problem from users otherwise.

[blakerouse]

Updating the error message to have a standard message about permissions would be helpful. Pointing to documentation with more information on permissions in this mode would also be helpful.

[pierrehilbert]

I have the same feeling than @cmacknz here.
In the same way we are having a warning message when we are not using sudo in privileged mode we should have a warning message when we are using sudo in unprivileged.
And of course, we should make it obvious in the unprivileged doc.

[ycombinator]

I updated the title of this issue and added a Definition of Done to reflect the discussion about improving the error message. As for documentation, I've brought that to @kilfoyle's attention via elastic/ingest-docs#1087 (comment).