[
https://issues.apache.org/jira/browse/MESOS-5379?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15282572#comment-15282572
]
Benjamin Bannier commented on MESOS-5379:
-----------------------------------------
What I personally like about the current {{AUTHENTICATION}} function is that it
leaves little room to deviate from a standard format. This makes the resulting
output extremely easy to parse and e.g., allows confirming expected behavior
automatically. Sadly, this also is the reason it has problems with the this use
case in libprocess.
It would be great if we could integrate a fix here into a larger story of
enabling generation of a machine-parseble REST API spec (like swagger/RAML/...)
in addition to the text representation for our human friends.
> Authentication documentation for libprocess endpoints can be misleading.
> ------------------------------------------------------------------------
>
> Key: MESOS-5379
> URL: https://issues.apache.org/jira/browse/MESOS-5379
> Project: Mesos
> Issue Type: Bug
> Components: documentation, libprocess
> Affects Versions: 0.29.0
> Reporter: Benjamin Bannier
> Priority: Blocker
> Labels: mesosphere, tech-debt
> Fix For: 0.29.0
>
>
> Libprocess exposes a number of endpoints (at least: {{/logging}},
> {{/metrics}}, and {{/profiler}}). If libprocess was initialized with some
> realm these endpoints require authentication, and don't if not.
> To generate endpoint help we currently use the also function
> {{AUTHENTICATION}} which injects the following into the help string,
> {code}
> This endpoints requires authentication iff HTTP authentication is enabled.
> {code}
> with {{iff}} documenting a coupling stronger between required authentication
> and enabled authentication which might not be true for above libprocess
> endpoints -- it is e.g., true when these endpoints are exposed through mesos
> masters/agents, but possibly not if exposed through other executables.
> It seems for libprocess endpoint a less strong formulation like e.g.,
> {code}
> This endpoints supports authentication. If HTTP authentication is enabled,
> this endpoint may require authentication.
> {code}
> might make the generated help strings more reusable.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
