On the state of documentation

[Stewart Smith]

Brad Bishop <bradleyb at fuzziesquirrel.com> writes:
>> On Nov 16, 2017, at 10:03 PM, Stewart Smith <stewart at linux.vnet.ibm.com> wrote:
>> 
>> "Tanous, Ed" <ed.tanous at intel.com> writes:
>>> I believe that the lack of good documentation is a symptom of a larger
>>> issue:  OpenBMC is not targeting a public specification with its REST
>>> interface.  This has led to certain engineering flexibilities with the
>>> interface that, while useful for short term to "get something that
>>> works", make it very difficult to target openbmc an evolving platform.
>>> In the current model, DBus specifications are pushed directly to the
>>> end user, which means (nearly) every DBus spec change results in a
>>> change to end user interfaces.  I don't believe this is sustainable in
>>> the long run, given the number of platforms that this is targeting and
>>> the need for reproducible APIs between systems.
>
> No disagreement here.  The project could really could use a Redfish
> and full IPMI implementation.

>>> that middle to long term we should transition away from
>>> these interfaces for end-user facing functionality, and move toward
>
> Words like 'transition away' and 'move toward' are kind of freaking me out
> a little.  Are you suggesting that OpenBMC can _only_ have a Redfish
> implementation?  Any other REST API implementation would be…banned from
> the project?  Or am I reading into it too much?

I'd support multiple interfaces (after all, IPMI and RedFish are
multiple ones anyway, and IPMI is probably going to take a few more
years to disappear)

> Like I said, I too agree we need a Redfish and IPMI implementation
> in OpenBMC.
>
> That said, what reason is there to get rid of the existing DBus<->REST
> translation server?  It’s not as if its a maintenance burden.  It isn’t
> as if anyone is making people use it in their products.  Its there.
> You can use it or not use it.  When we have an IPMI or Redfish
> implementation, I’ll be the first in line (well maybe second after
> Stewart) to tell my employer to turn it off in their products.
> That isn’t the same thing as removing it from the project altogether.

It might be useful for debug to keep around "forever"?

>>> Some important key points that I think should be driven by the new model:
>>> 1. Rest interfaces should not be driven by the underlying DBus interfaces, nor the backend implementation language.
>
> This reads like policy for someone using OpenBMC to build a BMC stack.
>
> I would rephrase it to:
>
> XYZ corp cannot use any REST implementations provided by OpenBMC that are
> driven by the underlying DBus interfaces in XYZ corp products making use
> of OpenBMC.
>
> Do you see the difference?

I'd say "The OpenBMC REST API is not meant to be a stable API to be
consumed. It exists exclusively for debug and development efforts of
OpenBMC. It may, in future, completely change or disappear."

>From someone consuming it, that's certainly been the experience at least :)

>>> 2. Interfaces should not contain any "backdoor" type APIs that allow white box style access to internal APIs.  Anything breaking the black box model should be done in a machine specific layer or configuration.
>>> 3. APIs should give the minimum required amount of information to fulfill the end user use case.
>>> 4. Interfaces should be backed by the system level security policy (PAM users in the current model).
>>> 5. Where possible, the implementations should follow an existing specification.  In the cases where the requirements are not supported, the api should follow the style of the supporting interface  (Think redfish OEM command support)
>
> I have the same reaction to 2-6 as I did for 1.  These are policies on _use_
> of OpenBMC.  Right?  Not what the contributors to the project are allowed to do.
>
> My worldview is that each one of these bullet points would cost the project a
> potential contributor.  Somewhere, someone is going to want to do one of
> those things.  Why not let them, when the only thing you have to do is not use
> their code?

Maybe guidelines more than rules?

I'm sure there's exceptions, but there's unlikely to be anything really
exist beyond RedFish and IPMI... If there is, I'd say it's up to you if
you want to include it in the base/reference distribution and if this
will create value or just more work :)


-- 
Stewart Smith
OPAL Architect, IBM.