[ClusterLabs] Antw: Re: Proposal for machine-friendly output from Pacemaker tools

[Ulrich Windl]

>>> Ken Gaillot <kgaillot at redhat.com> schrieb am 08.01.2019 um 18:28 in
Nachricht
<2ecefc63baa56a76a6eeca7c696fc7a1653eb620.camel at redhat.com>:
> On Tue, 2019-01-08 at 17:23 +0100, Kristoffer Grönlund wrote:
>> On Tue, 2019-01-08 at 10:07 -0600, Ken Gaillot wrote:
>> > On Tue, 2019-01-08 at 10:30 +0100, Kristoffer Grönlund wrote:
>> > > On Mon, 2019-01-07 at 17:52 -0600, Ken Gaillot wrote:
>> > > > 
>> > > 
>> > > Having all the tools able to produce XML output like cibadmin and
>> > > crm_mon would be good in general, I think. So that seems like a
>> > > good
>> > > proposal to me.
>> > > 
>> > > In the case of an error, at least in my experience just getting a
>> > > return code and stderr output is enough to make sense of it -
>> > > getting
>> > > XML on stderr in the case of an error wouldn't seem like
>> > > something
>> > > that
>> > > would add much value to me.
>> > 
>> > There are two benefits: it can give extended information (such as
>> > the
>> > text string that corresponds to a numeric exit status), and because
>> > it
>> > would also be used by any future REST API (which won't have
>> > stderr),
>> > API/CLI output could be parsed identically.
>> > 
>> 
>> Hm, am I understanding you correctly:
>> 
>> My sort-of vision for implementing a REST API has been to move all of
>> the core functionality out of the command line tools and into the C
>> libraries (I think we discussed something like a libpacemakerclient
>> before) - the idea is that the XML output would be generated on that
>> level?
>> 
>> If so, that is something that I am all for :)
> 
> Yes :) but this would not be an implementation, just an output format
> that a future implementation could use.
> 
> The idea for the future is that a C library would contain all the
> functionality, and the CLI tools and REST API daemon would just be thin
> wrappers for that. Both the CLI (with XML output option) and REST API
> would return identical output, so scripts/tools could be written that
> could easily use one or the other.

If the REST API should implement a reliable interface, the output (actually
the data being returned) must be formalized ("machine readable"). One part
could be a clear-text message intended for humans, but there must be more than
that.

(Recently I learned some commercial REST API interface that seemed to be
"knitted with a hot needle": It is highly inconsistent on parameter names, on
parameter passing methods, on parameter and response formats. Also the methods
used (GET/POST/DELETE) are used inconsitently. I mean this is exactly what we
DO NOT want).

> 
> But at this point, we're just talking about the output format, and
> implementing it for a few CLI commands as a demonstration. The first
> step in the journey.

One point not discussed so far (but important): How would authentication
between CLI tools and the REST API work? With authentication, none of the
user-side tools would have to run as root.

> 
>> Right now, we are experimenting with a REST API based on taking what
>> we
>> use in Hawk and moving that into an API server written in Go, and
>> just
>> calling crm_mon --as-xml to get status information that can be
>> exposed
>> via the API. Having that available in C directly and not having to
>> call
>> out to command line tools would be great and a lot cleaner:

Before going that way, I would revalidate the API with some of the criteria
mentioned above. A consistent, reliable and secure API is very much desired.

>> 
>> https://github.com/krig/hawk-apiserver 
>> https://github.com/hawk-ui/hawk-web-client 
>> 
>> Cheers,
>> Kristoffer
> 
> So it looks like you're using JSON for the results returned by an API
> query? That's part of the question here. I think we're more likely to
> go with XML, but you're already parsing XML from crm_mon, so that
> shouldn't pose any problems if you want to parse and reformat the CLI
> output.

Actually a long as XML is used just to represent nested data (without a clean
DTD), JSON is preferrable, because it's easier to parse. Maybe the client could
specify in the accept header with format it wants to receive...

> 
> I envision a future pacemaker API server offering multiple output
> formats based on request extension, e.g. /GET/resources/my-rsc-id.xml
> would return XML whereas my-rsc-id.json would return JSON, optionally
> with an additional .bz2 extension to compress the result. But that's
> all just dreaming at this point, and there are no concrete plans to
> implement it.

No: HTTP has a standard mechanism for the returned data type; don't add
multiple URIs to specify the data type to return. That'll be the start of a
mess otherwise.

> 
> The questions at this point are:
> 
> 1. What output format(s) should we offer? (likely just XML for now,
> with a design allowing for alternatives just as JSON in the future)
> 
> 2. What should the command-line interface be? (e.g. --output-as=xml --
> output-file=result.xml)

Command-line interface for what? The output of the command-line tools should
be plain text unless you provide a generic REST API wrapper to use any REST
function.


> 
> 3. What should the output schema look like? For example, how should we
> represent the output of "stonith_admin --history" and "crm_resource --
> list-operations"? The goal will be to have something general enough
> that it can be easily adapted to any command, yet consistent enough to
> be easily parsed.

Please don't make a generic "one size fits all XML"; instead make specific
DTDs for the individual result types. As a counter-example, the most useless
XML format would be:
<output>...any output...</output>

On theother hand, wrapping X structs in XML is just as bad.

Summary: making a clean design is worth it!

Regards,
Ulrich