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

[Ken Gaillot]

On Wed, 2019-01-09 at 08:39 +0100, Ulrich Windl wrote:
> > > > 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.

Exactly, formalizing it is what I would like to do now.

The CLI tools would be able to generate output in a selectable format,
defaulting to human-friendly plain text, but optionally something
machine-readable like XML instead. crm_mon already does this; it offers
options for plain-text, curses, HTML, CGI, nagios, or XML output.

My plan is that CLI tool XML output (to begin being implemented now)
would be identical to (theoretical future) REST API XML output.
Scripts/tools could be written now to parse CLI XML output, and if we
ever proceed with a REST API, all of that code will be reusable as-is.

> (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).

Definitely, that's why I'm raising the visibility on this :)

But at the moment we are solely concerned with the result format, not
the API itself.

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

Yes, that is an open question, but we're nowhere near that stage yet,
just defining the result format. To be clear, a REST API is not a
priority and there are no plans to implement one. But there are plans
to implement machine-readable CLI output, and I'd like to make sure it
can be reused identically for any future API.

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

Oh right, I don't know why I forgot that.

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

The API is vaporware :) while the CLI is real, so we're starting with
that. The question is what command-line options should be used to
select the output format (defaulting to plain text).

> > 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!

Yes, that's the question! :)
-- 
Ken Gaillot <kgaillot at redhat.com>