<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
</head>
<body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; ">
Additional comments inline:
<div><br>
</div>
<div>
<div>
<div>On Feb 14, 2011, at 4:59 PM, Paul Voccio wrote:</div>
<br class="Apple-interchange-newline">
<blockquote type="cite">
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<div>Thoughts below:</div>
<div><br>
</div>
<span id="OLK_SRC_BODY_SECTION">
<div style="font-family:Calibri; font-size:11pt; text-align:left; color:black; BORDER-BOTTOM: medium none; BORDER-LEFT: medium none; PADDING-BOTTOM: 0in; PADDING-LEFT: 0in; PADDING-RIGHT: 0in; BORDER-TOP: #b5c4df 1pt solid; BORDER-RIGHT: medium none; PADDING-TOP: 3pt">
<span style="font-weight:bold">From: </span>Justin Santa Barbara <<a href="mailto:justin@fathomdb.com">justin@fathomdb.com</a>><br>
<span style="font-weight:bold">Date: </span>Mon, 14 Feb 2011 14:32:52 -0800<br>
<span style="font-weight:bold">To: </span><<a href="mailto:openstack@lists.launchpad.net">openstack@lists.launchpad.net</a>><br>
<span style="font-weight:bold">Subject: </span>Re: [Openstack] OpenStack Compute API 1.1<br>
</div>
<div><br>
</div>
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;" type="cite">
<div>Some thoughts...</div>
<div><br>
</div>
<div>General:</div>
<div><br>
</div>
<div>
<ul>
<li>Are we writing the OpenStack API, or are we writing the document for the next version of Cloud Servers?  In my opinion, the two need to be separate.  For example, specifications of resource limits and rate limits, supported compression encodings, timeout
 on persistent connections, pagination, caching, polling and resize confirmation windows don't belong in the core OpenStack API.  These should be put in the CloudServers v1.1 documentation, but a different OpenStack provider will not impose the same limitations
 that Rackspace will.</li></ul>
</div>
</blockquote>
</span>
<div>I think it is fair to say the api comes with default limits. There is nothing in the spec or the code that says you can't alter these limits. </div>
</div>
</blockquote>
<div><br>
</div>
<div>Right,  I'll modify the spec to denote that operators can define their own limits and the limits of the specs are simply sample limits.  You can query limits programmatically and that should be the only way to determine your limits for a particular deployment.</div>
<div><br>
</div>
<div>As for the differences between the OpenStack API and Cloud Servers API.  Moving forward, there is no Cloud Servers API.  This spec covers the OpenStack Compute API.  The API should really stand on its own.  I agree with PVO that the 1.2 spec or other future
 specs will move images out of this API and into the glance API.  There should be a separate API for volume storage etc.  Again images are still part of the 1.1 spec because we don't want to write a complete rewrite.</div>
<br>
<blockquote type="cite">
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<div><br>
</div>
<div><br>
</div>
<span id="OLK_SRC_BODY_SECTION">
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;" type="cite">
<div><br>
</div>
Metadata:
<div><br>
</div>
<div>
<ul>
<li>The 5 item limit will probably need to be raised if we start using the metadata for hints etc, but this is no big deal</li></ul>
</div>
</blockquote>
</span></div>
</blockquote>
<div><br>
</div>
<div>Should the limit be operator specific?  Or should it just be higher?  One of the nice things about the 5 limit today is that it's part of the schema.  That means that as we are parsing the message -- in a stream like fashion -- we can reject messages that
 go over the limit.  This allows us to catch abuse early.  If we make it operator specific we'd likely lose that feature -- not that big of a deal -- but worth mentioning.  Another issue is how to we prevent people from going metadata crazy -- that could add
 a lot of data and we'll need to support pagination of metadata -- again I can totally handle that but worth mentioning that's not a big deal today.</div>
<div><br>
</div>
<div>The idea for the metadata here is that it's user defined metadata.  Hints should  be defined using another mechanism.</div>
<br>
<blockquote type="cite">
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<span id="OLK_SRC_BODY_SECTION">
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;" type="cite">
<div>
<ul>
<li>What is the behaviour of the metadata collection update when metadata is already present (merge or replace)?  </li></ul>
</div>
</blockquote>
</span></div>
</blockquote>
<div><br>
</div>
<div>That's a really good question.  On a server rebuild we will replace metadata if it's specified as part of the rebuild action, otherwise we leave the metadata alone -- this is mentioned in section 4.4.3. I believe an update (4.3.4) should do a merge.  Updates
 will replace individual metadata items with the same key.  Does this make sense?  I'll modify the spec to reflect this.</div>
<br>
<blockquote type="cite">
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<span id="OLK_SRC_BODY_SECTION">
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;" type="cite">
<div>
<ul>
<li>Can this return the new metadata values instead of no-return-value?</li></ul>
</div>
</blockquote>
</span></div>
</blockquote>
<div><br>
</div>
<div>That's a great idea. I'll add that.</div>
<div><br>
</div>
<blockquote type="cite">
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<span id="OLK_SRC_BODY_SECTION">
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;" type="cite">
<div>
<ul>
<li>Should we allow custom metadata on all items?  Should we replace some properties with well-known metadata?  e.g. on flavors, should the disk property move to openstack:disk metadata?  This way we don't need to define the exact set of metadata on all items
 for eternity (e.g. authors on extensions)</li></ul>
</div>
</blockquote>
</span></div>
</blockquote>
<div><br>
</div>
<div>I like the idea of adding custom metadata to other items -- especially images (I'll go ahead and add these to the spec) -- but keep in mind these are user defined metadata items.  Operator defined items should probably go through extensions -- the reason
 for this is that you can define these in the schema so you can introspect them and document them correctly, you can also check to see what is available, you can validate the messages, etc.  Lots of advantages for uses if operator metadata is nicely defined
 -- users can manage their own metadata items.</div>
<br>
<blockquote type="cite">
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<span id="OLK_SRC_BODY_SECTION">
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;" type="cite">
<div>
<ul>
<li>Are duplicate metadata keys allowed?</li></ul>
</div>
</blockquote>
</span></div>
</blockquote>
<div><br>
</div>
<div>I'm leaning towards no.  But I could probably be convinced otherwise. </div>
<br>
<blockquote type="cite">
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<span id="OLK_SRC_BODY_SECTION">
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;" type="cite">
<div>
<ul>
<li>Can we please reserve the openstack: prefix, just like AWS reserves the aws: prefix</li></ul>
</div>
<div><br>
</div>
</blockquote>
</span></div>
</blockquote>
<div><br>
</div>
<div>Again, metadata items are for user's only.   We should have a prefix defined for extensions.</div>
<br>
<blockquote type="cite">
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<span id="OLK_SRC_BODY_SECTION">
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;" type="cite">
<div></div>
<div>IP Addresses:</div>
<div><br>
</div>
<div>
<ul>
<li>Instead of just supporting a public and private network, how about specifying <network id="public"> and <network id="private">.  This way we can also support more networks e.g. SAN, private VPN networks, HPC interconnects etc</li></ul>
</div>
</blockquote>
</span>
<div>This could be a good idea. This way if someone doesn't return a private network or additional management networks. </div>
</div>
</blockquote>
<div><br>
</div>
<div><br>
</div>
<div>I like this idea as well, let me work this into the spec.</div>
<br>
<blockquote type="cite">
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<div><br>
</div>
<span id="OLK_SRC_BODY_SECTION">
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;" type="cite">
<div>
<ul>
<li>Is it useful to know which IPV4 addresses and IPV6 addresses map to network cards?  Right now if there are multiple addresses on the same network, the correspondence is undefined.</li></ul>
</div>
</blockquote>
</span>
<div>Not sure we'd know depending on the network topology where the address maps to a particular card. Not sure if I follow. If there are multiple addresses on the same network the addresses could float between them so knowing which nic they were originally
 bound to isn't important but could also be confusing. </div>
<div><br>
</div>
<div><br>
</div>
<span id="OLK_SRC_BODY_SECTION">
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;" type="cite">
<div>
<ul>
<li>What happens when a machine has a block of addresses?  Is each address listed individually?  What happens in IPv6 land where a machine could well have a huge block?  I think we need a netmask.</li></ul>
</div>
</blockquote>
</span>
<div>Netmask makes sense. </div>
<div><br>
</div>
<div><br>
</div>
<span id="OLK_SRC_BODY_SECTION">
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;" type="cite">
<div><br>
</div>
<div>Extensions:</div>
<div><br>
</div>
<div>
<ul>
<li>How are the XML schemas going to work with extension elements?  Right now, it's very free-form, which can cause problems with useful schemas.  Are the proposed schemas available?</li></ul>
</div>
<div><br>
</div>
</blockquote>
</span></div>
</blockquote>
<div><br>
</div>
<div><br>
</div>
<div>Yes, I'll be publishing proposed schemas as soon as I'm done tweaking them :-)  XSD 1.0 allows extensible elements and attributes especially if they are defined in a namespace other than the target namespace...this is why extensions need to define their
 own namespaces.   So for example a rate limits look something like this (I've left out the doc annotations for brevity) :</div>
<div><br>
</div>
<div>
<div><font class="Apple-style-span" face="Courier">    <xs:complexType name="RateLimit"></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:sequence></font></div>
<div><font class="Apple-style-span" face="Courier">            <b><xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" /></b></font></div>
<div><font class="Apple-style-span" face="Courier">        </xs:sequence></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="verb" type="limits:HttpMethod" use="required" /></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="value" type="xs:int" use="required" /></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="remaining" type="xs:int" use="required" /></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="unit" type="limits:TimeUnit" use="required" /></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="next-available" type="xs:dateTime" use="required"/></font></div>
<div><font class="Apple-style-span" face="Courier">        <b><xs:anyAttribute namespace="##other" processContents="lax"/></b></font></div>
<div><font class="Apple-style-span" face="Courier">    </xs:complexType></font></div>
</div>
<div><br>
</div>
<div>Basically that's saying:  here are the set of defined attributes, but we allow additional attributes and elements in another namespace (##other).  I've been doing some tests and there's actually some pretty good support for this even in XML binding tools.
  Core schemas are defined in this manner.</div>
<div><br>
</div>
<div><br>
</div>
<div>The issue with XSD 1.0 comes when we want to specifically define optional extensions.  In this case we may run into the “Unique Particle Attribution” problem in XSD 1.0.  So for example suppose that we define an extension to rate limits like this...</div>
<div><br>
</div>
<div>
<div><font class="Apple-style-span" face="Courier">    <xs:complexType name="RateLimit"></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:sequence></font></div>
<div><font class="Apple-style-span" face="Courier">            <b><xs:element name="extension" type="rs-ext:extension" minOccurs="0" /></b></font></div>
<div><font class="Apple-style-span" face="Courier"><b>            <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" /></b></font></div>
<div><font class="Apple-style-span" face="Courier">        </xs:sequence></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="verb" type="limits:HttpMethod" use="required" /></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="value" type="xs:int" use="required" /></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="remaining" type="xs:int" use="required" /></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="unit" type="limits:TimeUnit" use="required" /></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="next-available" type="xs:dateTime" use="required"/></font></div>
<div><font class="Apple-style-span" face="Courier">        <b><xs:anyAttribute namespace="##other" processContents="lax"/></b></font></div>
<div><font class="Apple-style-span" face="Courier">    </xs:complexType></font></div>
</div>
<div><br>
</div>
<div><br>
</div>
<div>The issue is that in XSD 1.0 this is ambiguous  because it doesn't know if an extension element should fit with "extension" or with "any".  XSD 1.1 solves this issue, so that the above description doesn't cause a problem in XSD 1.1.  Since most tools support
 XSD 1.0 we can write a backward compatible schema like this:  </div>
<div><br>
</div>
<div>
<div><font class="Apple-style-span" face="Courier">  <xs:complexType name="RateLimit"></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:sequence></font></div>
<div><font class="Apple-style-span" face="Courier">            <b><xs:element name="extension" type="rs-ext:extension" minOccurs="0"  vc:minVersion="1.1"/></b></font></div>
<div><font class="Apple-style-span" face="Courier"><b>            <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"  vc:minVersion="1.0" vc:maxVersion="1.1" /></b></font></div>
<div><font class="Apple-style-span" face="Courier">        </xs:sequence></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="verb" type="limits:HttpMethod" use="required" /></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="value" type="xs:int" use="required" /></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="remaining" type="xs:int" use="required" /></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="unit" type="limits:TimeUnit" use="required" /></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:attribute name="next-available" type="xs:dateTime" use="required"/></font></div>
<div><font class="Apple-style-span" face="Courier">        <xs:anyAttribute namespace="##other" processContents="lax"/></font></div>
<div><font class="Apple-style-span" face="Courier">    </xs:complexType></font></div>
</div>
<div><br>
</div>
<div>That's essentially saying ignore the "extension" element in an XSD 1.0 processor, but include it in an XSD 1.1 processor. Modern XSD implementations (1.0 and 1.1) understand the vc:min/maxVersion attributes, for those that don't I've written an  XSLT that
 allows converting the XSDs to version 1.0.  Note that the message can be validated with both XSD 1.0 and 1.1 tools, though 1.1 will be more likely to find errors with the extensions. I realize that there are only a few 1.1 implementations but things seems
 to be moving in this direction and we have good work arounds for the time being.</div>
<div><br>
</div>
<br>
<blockquote type="cite">
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<span id="OLK_SRC_BODY_SECTION">
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;" type="cite">
<div></div>
<div>Volumes:</div>
<div><br>
</div>
<div>
<ul>
<li>Volume support is core to OpenStack (and has been since launch).  This needs therefore to be in the core API, not in an extension.  Or if it is an extension then compute, images and flavors should all be in extensions also (which would be cool, if a little
 complicated.)</li></ul>
</div>
</blockquote>
</span>
<div>I think this is in preparation for the separation of apis in the future. Flavors would always tie to a compute api since they don't really make sense outside of a compute context. Glance is getting the images api, which I think the compute images context
 will eventually go there. </div>
<div><br>
</div>
</div>
</blockquote>
<div><br>
</div>
<div>Right the APIs should be separate in the future. </div>
<div><br>
</div>
<div>-jOrGe W.</div>
</div>
</div>
</body>
</html>