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

[Ken Gaillot]

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.

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.

> 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:
> 
> 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.

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.

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)

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.
-- 
Ken Gaillot <kgaillot at redhat.com>