docs: clarify the usage of the server information endpoint

[rodrigc]

Discussed in case 01501264

Signed-off-by: Craig Rodrigues [email protected]

Motivation/summary

I found the existing documentation for the server information endpoint to be a bit confusing.
I didn't understand that GET and POST behave differently.

Checklist

• Update CHANGELOG.asciidoc
• Update package changelog.yml (only if changes to apmpackage have been made)
• Documentation has been updated

For functional changes, consider:

• Is it observable through the addition of either logging or metrics?
• Is its use being published in telemetry to enable product improvement?
• Have system tests been added to avoid regression?

How to test these changes

Related issues

[mergify]

This pull request does not have a backport label. Could you fix it @rodrigc? 🙏
To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

• backport-7.17 is the label to automatically backport to the 7.17 branch.
• backport-8./d is the label to automatically backport to the 8./d branch. /d is the digit.

NOTE: backport-skip has been added to this pull request.

[axw]

Thanks for sending the PR @rodrigc! I can't see your support case, but I guess there was some miscommunication: the endpoint's response body shouldn't differ based on whether it's a GET or POST method, what matters is whether the client is authorized. This is to minimise leaking information about the service to unauthorized (and potentially malicious) clients.

[axw]

@rodrigc sorry, could you please sign your commit and force push again?

[rodrigc]

Done

[rodrigc]

@axw can you trigger the docs CI? I'm not sure, but I think something like:

@elasticsearchmachine run elasticsearch-ci/docs

is required

[axw]

/run elasticsearch-ci/docs

[axw]

/run elasticsearch-ci/docs

[rodrigc]

@axw Thanks for the review and merge of this PR.

I have one question. Would it be possible to include a default role in the apm-server code which is similar to
the one mentioned here:
https://www.elastic.co/guide/en/apm/guide/current/api-key.html#create-api-key-user

That way, the end user would not need to worry so much about creating a role
to use an API key which works with APM

[axw]

@rodrigc we could predefine a role in Elasticsearch (not in apm-server), but you would still need to create/assign a user that role, so it doesn't seem entirely ideal either.

I think the long-term vision is that this should be built into a standard, but broader, role like "editor". The idea being that you have users that are admins, viewers, or editors; admins and editors should be able to create API Keys for agents, whereas viewers should not. If you wanted a more fine-grained role, then you would still have the option to create one.

Does that sound sensible to you?

[rodrigc]

That seems like a reasonable approach. I agree that more thought needs to be put into this.

[axw]

@rodrigc I've opened elastic/apm#831 to track this