openstack team mailing list archive

[Jorge Williams <jorge.williams@xxxxxxxxxxxxx>]

Additional comments inline:

On Feb 14, 2011, at 4:59 PM, Paul Voccio wrote:

Thoughts below:

From: Justin Santa Barbara <justin@xxxxxxxxxxxx<mailto:justin@xxxxxxxxxxxx>>
Date: Mon, 14 Feb 2011 14:32:52 -0800
To: <openstack@xxxxxxxxxxxxxxxxxxx<mailto:openstack@xxxxxxxxxxxxxxxxxxx>>
Subject: Re: [Openstack] OpenStack Compute API 1.1

Some thoughts...

General:


  *   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.

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.

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.

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.




Metadata:


  *   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

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.

The idea for the metadata here is that it's user defined metadata.  Hints should  be defined using another mechanism.


  *   What is the behaviour of the metadata collection update when metadata is already present (merge or replace)?

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.


  *   Can this return the new metadata values instead of no-return-value?

That's a great idea. I'll add that.


  *   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)

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.


  *   Are duplicate metadata keys allowed?

I'm leaning towards no.  But I could probably be convinced otherwise.


  *   Can we please reserve the openstack: prefix, just like AWS reserves the aws: prefix


Again, metadata items are for user's only.   We should have a prefix defined for extensions.

IP Addresses:


  *   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

This could be a good idea. This way if someone doesn't return a private network or additional management networks.


I like this idea as well, let me work this into the spec.



  *   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.

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.



  *   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.

Netmask makes sense.



Extensions:


  *   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?



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) :

    <xs:complexType name="RateLimit">
        <xs:sequence>
            <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
        </xs:sequence>
        <xs:attribute name="verb" type="limits:HttpMethod" use="required" />
        <xs:attribute name="value" type="xs:int" use="required" />
        <xs:attribute name="remaining" type="xs:int" use="required" />
        <xs:attribute name="unit" type="limits:TimeUnit" use="required" />
        <xs:attribute name="next-available" type="xs:dateTime" use="required"/>
        <xs:anyAttribute namespace="##other" processContents="lax"/>
    </xs:complexType>

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.


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...

    <xs:complexType name="RateLimit">
        <xs:sequence>
            <xs:element name="extension" type="rs-ext:extension" minOccurs="0" />
            <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
        </xs:sequence>
        <xs:attribute name="verb" type="limits:HttpMethod" use="required" />
        <xs:attribute name="value" type="xs:int" use="required" />
        <xs:attribute name="remaining" type="xs:int" use="required" />
        <xs:attribute name="unit" type="limits:TimeUnit" use="required" />
        <xs:attribute name="next-available" type="xs:dateTime" use="required"/>
        <xs:anyAttribute namespace="##other" processContents="lax"/>
    </xs:complexType>


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:

  <xs:complexType name="RateLimit">
        <xs:sequence>
            <xs:element name="extension" type="rs-ext:extension" minOccurs="0"  vc:minVersion="1.1"/>
            <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"  vc:minVersion="1.0" vc:maxVersion="1.1" />
        </xs:sequence>
        <xs:attribute name="verb" type="limits:HttpMethod" use="required" />
        <xs:attribute name="value" type="xs:int" use="required" />
        <xs:attribute name="remaining" type="xs:int" use="required" />
        <xs:attribute name="unit" type="limits:TimeUnit" use="required" />
        <xs:attribute name="next-available" type="xs:dateTime" use="required"/>
        <xs:anyAttribute namespace="##other" processContents="lax"/>
    </xs:complexType>

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.


Volumes:


  *   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.)

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.


Right the APIs should be separate in the future.

-jOrGe W.