Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
johnarwe opened this issue Dec 30, 2021 · 2 comments
Open

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

johnarwe opened this issue Dec 30, 2021 · 2 comments

Comments

@johnarwe
Copy link
Member

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
Copy link
Member Author

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
Copy link
Collaborator

jichenjc commented Jan 12, 2022

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants