Minutes from Aug 24th Cloudstack meeting


Mike MacIsaac
 

Hi everyone,
 
Here are the minutes I took:
 
August 24, 2018  Open Mainframe Project Cloudstack meeting  11:00AM EDT
 
 
Attendees:  Mike F, Paul N, Bill B, Neale, Emily,  John M, Alex
 
Agenda:
1. File format of working document
 
We agreed to use GitHub.
Format may be .md (markdown) or .rtf (Rich text)
 
2. Review of RESTful API document:
 
Is 'Rebuild Guest' (clone to existing virtual machine) missing?
==> Describe Clone to existing VM vs. Clone to new.
 
Questions for zCC team:
 
-) Why are there 5 calls re: NICs?  Are all 5 needed?
1.4.12. Create Guest NIC        
1.4.13. Create network interface               
1.4.14. Delete network interface       
1.4.28. Update Guest NIC               
1.4.29. Delete Guest NIC        
 
-) 1.4.16. Stop guest - does this do a z/VM #CP LOG and crash the OS?
If so, should it be named better to imply that it is dangerous?
 
-) 1.4.20. Reboot guest - Is this a 'soft reboot' (Linux init 6)?
1.4.21. Reset guest - Is this is a hard reboot => 'Reset' is not intuitive.  Should hard reboot be an option to Reset?
 
-) 1.4.23. Live resize CPUs of guest and 1.4.24. Resize CPUs of guest
Should these be combined into a single call?   
 
In discussion, Alex K asked: Is there a standard format for server status?
=> up/down is most common.  zoom now implements tri-state as a preference:
up     : system pings
noping : system does not ping but VM is logged on
down   : VM is logged off
 
Next meeting - Septmber 7th, 11 AM EDT
-) Mike F will do a GitHub demo
-) More discussion on RESTful API document
 
Thanks.
 
    -Mike MacIsaac, z/VM and z/Linux engineering, 862-308-5089 (cell)
 
 
 

This message and any attachments are intended only for the use of the addressee and may contain information that is privileged and confidential. If the reader of the message is not the intended recipient or an authorized representative of the intended recipient, you are hereby notified that any dissemination of this communication is strictly prohibited. If you have received this communication in error, notify the sender immediately by return email and delete the message and any attachments from your system.


John Arwe
 

> -) Why are there 5 calls re: NICs?  Are all 5 needed?

Fair disclosure: I'm not on/in the zCC team.

On the surface, it may be that your summary answers the question: i.e., "NIC" != "network interface", so zCC does not have 5 NIC-related calls, it has 3 NIC- and 2 "network interface"- calls.  In that view, "NIC" is a name for the NICDEF directory entry statement's parameters, and "network interface" is a name for all the Linux-y ifcfg information that's exposed through the API.

This is another form of the general comments I made 2 and 5-ish meetings ago.
- What are the first-class "objects" in your model.  Here: NIC + network interface, or some mashup of them.
- If a single representation contains properties from >1 first-class objects, how does a client know which are authoritative?
- Relationships ... are they first class or not.  Usually "not", and that has certain implications (no identifier, cardinality 1, no properties), but sometimes people make the other choice for defensible reasons.
 
> -) 1.4.16. Stop guest - does this do a z/VM #CP LOG and crash the OS?
> -) 1.4.20. Reboot guest - Is this a 'soft reboot' (Linux init 6)?

A purist REST-y answer to this would be along the lines of: both questions above represent different "desired" states for the guest, so you update the guest's representation with the desired state, fin.  The "command-y" POSTs are then just an alternative (shorter, presumably) syntax to accomplish the same semantic.  Separating syntax from semantics is an important choice.

Discovery of the POSTs (how generic do you want your client to be?) is another potential question lurking.  HTTP's ability to support a RESTful architecture includes discovery features, despite many folks (API designers especially) ignoring them.
 
> -) 1.4.23. Live resize CPUs of guest and 1.4.24. Resize CPUs of guest

To split some hairs:
- HTTP doesn't have anything to say about this, so our WG's definition of RESTful would be silent.
- A more purist RESTful answer would be: in both cases, you update the state of the guest, so the default answer is that you can update any combination of states (including but not limited to those you cited) in a single update, although the server is free to constrain that (and our API spec might constrain "compliant" servers to require both on a single update, or not, as the WG sees fit).
 
> => up/down is most common.  zoom now implements tri-state as a preference:

IBM Wave's existing guest status separates the two; active/not and connectable/not.  Computing others from those is easy enough.

If certain combinations (ex: logged off and connectable) are logically incoherent, a more limited enumeration like zoom's can make sense.  The specification issue with enumerations tends to be setting the correct server and client expectations for extending them.  If you say the list of states is extensible, clients and servers need code to handle unexpected/unknown values.  If the list is fixed, you tend to proliferate state fields (if your spec requires compatible evolution of the API) as you discover new existing states not covered by the original values (or covered but not well enough), and as new states get added.
 


Best Regards, John

Voice US 845-435-9470  BluePages
z/VM System Management http://xkcd.com/1695/


jichenjc@...
 

some comments for the questions below in blue:

overall those APIs are mostly provide more granularity control on the VM side (user direct) and OS side (linux settings)

1.4.12. Create Guest NIC :
create a nic directory entry statement in the user direct or in the active virtual machine, not set Linux network interface configuration
1.4.13. Create network interface:
create a nic directory entry statement in the user direct or in the active virtual machine, and also set Linux network interface configuration, including IP, gateway ..

1.4.14. Delete network interface:
delete the nic directory entry statement in the user direct or in the active virtual machine, and also delete the Linux network interface configuration, including IP, gateway ..
1.4.28. Update Guest NIC:
couple/uncouple the NIC with the vswitch
1.4.29. Delete Guest NIC:
delete the nic directory entry statement from the user direct or from the active virtual machine

Generally, user could use " Create network interface" and " Delete network interface" to manage the network configuration for Linux on Z, but we also provide calls "Create Guest NIC" and "Delete Guest NIC" for the user who want to manage the network configuration by himself, "Create Guest NIC" and "Delete Guest NIC" help to set the VM configuration, and user could do the Linux configuration manually


-) 1.4.16. Stop guest - does this do a z/VM #CP LOG and crash the OS?
If so, should it be named better to imply that it is dangerous?

Stop guest will do a z/VM #CP FORCE IMME, we can specify it as 'dangerous'
we plan to update the doc rename it to "force stop"

if we want to gracefully shutdown, we recommend to use 'softstop guest' in the REST API


-) 1.4.20. Reboot guest - Is this a 'soft reboot' (Linux init 6)?

Those concept are comes from openstack
Reboot = soft reboot, which is shutdown -r

1.4.21. Reset guest - Is this is a hard reboot => 'Reset' is not intuitive. Should hard reboot be an option to Reset?

reset is "hard reboot". so basically it will logoff (first send signal to VM to indicate shutdown )then logon the VM again

-) 1.4.23. Live resize CPUs of guest and 1.4.24. Resize CPUs of guest
Should these be combined into a single call?

Live resize CPUs will change both user direct and active vcpu numbers.
Resize CPUs will change only user direct.

The two APIs are for different use cases, combine the two will make one single API too complicated.
 
>>In discussion, Alex K asked: Is there a standard format for server status?
=> up/down is most common. zoom now implements tri-state as a preference:
up : system pings
noping : system does not ping but VM is logged on
down : VM is logged off
zCC also has a call GET /guests/{userid}/info to indicate whether the vm is online ('on') or offline ('off') but no pingable status existing, we can add it accordingly

Best Regards!

Kevin (Chen) Ji 纪 晨

Engineer, zVM Development, CSTL
Notes: Chen CH Ji/China/IBM@IBMCN Internet: jichenjc@...
Phone: +86-10-82451493
Address: 3/F Ring Building, ZhongGuanCun Software Park, Haidian District, Beijing 100193, PRC

"Mike MacIsaac via Lists.Openmainframeproject.Org" ---08/27/2018 07:32:22 PM---Hi everyone, Here are the minutes I took:

From: "Mike MacIsaac via Lists.Openmainframeproject.Org" <michael.macisaac=adp.com@...>
To: "omp-wg-cloudstack@..." <omp-wg-cloudstack@...>
Date: 08/27/2018 07:32 PM
Subject: [omp-wg-cloudstack] Minutes from Aug 24th Cloudstack meeting
Sent by: omp-wg-cloudstack@...





Hi everyone,

Here are the minutes I took:

August 24, 2018 Open Mainframe Project Cloudstack meeting 11:00AM EDT

Home page: https://lists.openmainframeproject.org/g/omp-wg-cloudstack/wiki/Home

Attendees: Mike F, Paul N, Bill B, Neale, Emily, John M, Alex

Agenda:
1. File format of working document

We agreed to use GitHub.
Format may be .md (markdown) or .rtf (Rich text)

2. Review of RESTful API document:

Is 'Rebuild Guest' (clone to existing virtual machine) missing?
==> Describe Clone to existing VM vs. Clone to new.

Questions for zCC team:

-) Why are there 5 calls re: NICs? Are all 5 needed?
1.4.12. Create Guest NIC
1.4.13. Create network interface
1.4.14. Delete network interface
1.4.28. Update Guest NIC
1.4.29. Delete Guest NIC

-) 1.4.16. Stop guest - does this do a z/VM #CP LOG and crash the OS?
If so, should it be named better to imply that it is dangerous?

-) 1.4.20. Reboot guest - Is this a 'soft reboot' (Linux init 6)?
1.4.21. Reset guest - Is this is a hard reboot => 'Reset' is not intuitive. Should hard reboot be an option to Reset?

-) 1.4.23. Live resize CPUs of guest and 1.4.24. Resize CPUs of guest
Should these be combined into a single call?

In discussion, Alex K asked: Is there a standard format for server status?
=> up/down is most common. zoom now implements tri-state as a preference:
up : system pings
noping : system does not ping but VM is logged on
down : VM is logged off

Next meeting - Septmber 7th, 11 AM EDT
-) Mike F will do a GitHub demo
-) More discussion on RESTful API document

Thanks.

-Mike MacIsaac, z/VM and z/Linux engineering, 862-308-5089 (cell)




This message and any attachments are intended only for the use of the addressee and may contain information that is privileged and confidential. If the reader of the message is not the intended recipient or an authorized representative of the intended recipient, you are hereby notified that any dissemination of this communication is strictly prohibited. If you have received this communication in error, notify the sender immediately by return email and delete the message and any attachments from your system.




John Arwe
 

Kudos to JM's listserv operators, it groks the blue formatting against all my expectations https://lists.openmainframeproject.org/g/omp-wg-cloudstack/message/87

-) 1.4.16. Stop guest - does this do a z/VM #CP LOG and crash the OS?
If so, should it be named better to imply that it is dangerous?

Stop guest will do a z/VM #CP FORCE IMME, we can specify it as 'dangerous'
JA: changing the name is a good idea.  IMO "dangerous" should take at least the form of a strong warning that using it against Linux guests is likely to result in loss of data.  Linux aggressively buffers writes, after all.  In a permissioned system, one hopes that it would have stronger controls for this reason.

Should these be combined into a single call?
The two APIs are for different use cases, combine the two will make one single API too complicated.

JA: while that seems fair, the original question should also lead you to ask whether or not the difference(s) are clear enough in the existing doc.  If they were, fine ... can't force people to read; but if the differences are not clearly articulated today, that's an opportunity to do so.


The "combine?" question could also, if generalized, be the "batch requests" camel poking its nose into this tent.  I'd counsel substantial caution before going there; the ACID issues, as well as results-matching and decisions like try-all or fast-fail, are things that HTTP gives you essentially no help with.  It's more doable (assuming the various API clients agree on their requirements) if you're only talking about a single implementation, but I haven't heard that to be the goal of this working group.  A spec detailed enough to "guarantee" that compliance equates to interoperability will have a hard time admitting multiple implementations, from what I've seen of similar past efforts in multiple standards bodies.


Best Regards, John

Voice US 845-435-9470  BluePages
z/VM System Management http://xkcd.com/1695/