search

openmainframeproject / feilong

Feilong is a open source z/VM cloud connector project under the Open Mainframe Project umbrella that will accelerate the z/VM adoption, extending its ecosystem and its user experience. It provides a set of APIs to operate z/VM including guest, image, network, volume etc.
https://www.openmainframeproject.org/projects/feilong
Apache License 2.0
36 stars 70 forks source link

Clarify GET /guests: dir entries, running guests, both? #569

Open johnarwe opened 2 years ago

johnarwe commented 2 years ago

GET /guests says: List names of all the guests created by Feilong.

This is ambiguous: it ignores the running/not guest distinction, and (possibly) the registered/not one.

Running/not is cross-platform since some of Feilong's guest APIs specifically say they manipulate directory entries (defined domains, in libvirt terms), others specifically say they operate on running guests (active domains), and many like this one leave it up to the reader's imagination whether the guest resource represents a directory entry, running guest, or both.

Registered/not appears to be a Feilong-specific consideration, given that I don't find it in libvirt's concepts or z/VM documentation (but Feilong does document register and deregister APIs). In this specific case, the phrase "created by Feilong" might be intended to cover "registered as Feilong-managed -and- created by Feilong", but other cases certainly exist given the presence of the register API. For example, a guest might be created by Feilong and then later deregistered; under my "might..." reading such a guest should not be returned, but under a strict reading of the existing documentation it should be returned.

I see the same running/not ambiguity in "more than a few" of the current APIs. Would you prefer that I add the list here, or open a separate issue for each one linking here for the full explanation?

johnarwe commented 2 years ago

As a second nearby example, see GET /guests/{userid} and GET /guests/{userid}/user_direct ... absent more words, on the surface they might be read to be two different syntaxes for asking the same question, or for asking subtly different questions.

jichenjc commented 2 years ago

intended to cover "registered as Feilong-managed -and- created by Feilong"

I agree this change ,technically, whenever we create or onboard (recognize and create a db record for a VM existing on z/VM but not aware to feilong) , we will add the name of the VM into db and that /GET API return all of them

we can add a PR in the doc to clarify it