[occi-wg] Syntax of OCCI API

[Richard Davies]

Sam Johnston wrote:
> Here's a first pass at flattening the Atom into INI file format
> (basically what you had but with "=" for human & computer readability):

Great stuff - I think this is a big step forward to be able to express
everything as a simple list of objects, each specified by simple key-value
pairs. Hopefully we can also similarly add a JSON version using the same
simple data structures, e.g.:

{"category":"server", "title":"Debian...", "mc.state":"running", ... }


I've got two specific comments on the example you give:


1) I'm not sure INI format is actually the best text format for key-value.
I'd prefer something easier to parse from Unix shell, which is where I
imagine most simple scripts will be written. ElasticHosts went with

  "key" (without spaces), <space>, "value" (any characters including spaces)

since this can be parsed with

  cat file | while read key value ; do ... ; done


2) Going through the keys and values in detail:

>  [decca5a5-8952-4004-9793-cdbbf05c3c63]

I like UUIDs and ElasticHosts also uses them, but I might loosen the
requirement to any unique string of hex and dashes (since other vendors may
prefer to number sequentially, etc.)

>  category = server
>  title = Debian GNU/Linux 5.0 Virtual Appliance
>  summary = Base installation of Debian GNU/Linux 5.0

Do we need both a title ('name' with ElasticHosts at present) and a summary
or can we just have one of these?

>  content.cpu = 2
>  content.memory = 4Gb

We need to agree units here! Presumably memory would be specified in 'GB' or
alternatively 'MB', 'kB' or nothing. Is CPU the speed quota or the number of
virtual cores? I recommend cores=<integer> and an additional key for speed
quota (ElasticHosts uses cpu=<total MHz to divide across all cores>)

Can we cut the namespace and just write:

cores = 2
cpu = 4000MHz
mem = 4GB

>  link.disk[0].id = 4696b561-a253-42b4-bd27-7aa4950e0a60
>  link.disk[0].dev = sda
>  link.network[0].id = 45a73b80-c957-4ae1-97c6-b70652eba1d1
>  link.network[0].dev = eth0

This is good - a mapping between hardware devices and uuids of the storage
or network objects.

We don't need the [0] indices, since the 'dev' specifiers are already fully
unique. Taking those out and cutting the namespace gives something like:

disk.sda = 4696b561-a253-42b4-bd27-7aa4950e0a60
network.eth0 = 45a73b80-c957-4ae1-97c6-b70652eba1d1

>  mc.state = RUNNING
>  br.meter.rate = 0.10
>  br.meter.currency = USD
>  br.meter.unit = hours
>  br.meter.total = 35.27
>  pm.monitor.cpu = 75.2
>  pm.monitor.mem = 1059374258

All look reasonable, but again I would cut the namespaces:

state = RUNNING
br.rate = 0.10
br.currency = SD
br.unit = hours
br.total = 35.27
pm.cpu = 75.2
pm.mem = 1059374258

>  mc.ops.start = http://example.com/decca5a5-8952-4004-9793-cdbbf05c3c63/ops/start
>  mc.ops.stop = http://example.com/decca5a5-8952-4004-9793-cdbbf05c3c63/ops/stop
>  mc.ops.restart = http://example.com/decca5a5-8952-4004-9793-cdbbf05c3c63/ops/restart
>  mc.ops.suspend = http://example.com/decca5a5-8952-4004-9793-cdbbf05c3c63/ops/suspend

Do we need these at all? Surely these will always be the operations which
are possible on a RUNNING server, and so can always be constructed based on
the UUID.

Also, why have 'ops' in the URLs? Why not just

http://example.com/decca5a5-8952-4004-9793-cdbbf05c3c63/start


>  [4696b561-a253-42b4-bd27-7aa4950e0a60]

I guess storage needs a 'title' (or 'name') too?

>  category = storage
>  content.size = 148251374

Why not just 'size'?

>  link.self = virtual-disk.vmdk

Not sure what this is?


>  [45a73b80-c957-4ae1-97c6-b70652eba1d1]

Again, maybe a 'name'?

>  category = network
>  content.vlan = 4095
>  content.dhcp = true
>  content.subnet = 192.168.0.0
>  content.netmask = 255.255.0.0
>  content.gateway = 192.168.0.1

Once again, I'd take the 'content' prefix off all of these.

The keys you list here work when the network interface is on a private VLAN,
but are the wrong set when it is on the public internet.

On the public internet, the cloud vendor, not the user, defines most of
these parameters and need to be able to control the customer VM from
"stealing" IPs from other customers.

The customer has access to a defined set of static IPs which they have
purchased or alternatively a free dynamic IP assigned at boot, and all they
should be able to specify is which of these they want on this particular
interface, and whether they want to receive a DHCP for it.

For instance, ElasticHosts currently specifies as:

ip = <specified static IP address or 'auto' to assign dynamically at boot>
dhcp = <ip address to send by dhcp or 'auto'; no dhcp if not present>

Given that the customer will have a set of static IPs which they have
purchased (common concept across Amazon, ElasticHosts, GoGrid, etc.), the
API also needs an ability for them to list what these are!

>  av.com.cisco.cdp = true