[openstack-dev] [Heat] rough draft of Heat autoscaling API

Zane Bitter zbitter at redhat.com
Thu Nov 14 17:56:22 UTC 2013

On 14/11/13 17:19, Christopher Armstrong wrote:
> http://docs.heatautoscale.apiary.io/
> I've thrown together a rough sketch of the proposed API for autoscaling.
> It's written in API-Blueprint format (which is a simple subset of
> Markdown) and provides schemas for inputs and outputs using JSON-Schema.
> The source document is currently atÂ
> https://github.com/radix/heat/raw/as-api-spike/autoscaling.apibp
> Things we still need to figure out:
> - how to scope projects/domains. put them in the URL? get them from the
> token?
> - how webhooks are done (though this shouldn't affect the API too much;
> they're basically just opaque)

My 2c: the way I designed the Heat API was such that extant stacks can 
be addressed uniquely by name. Humans are pretty good with names, not so 
much with 128 bit numbers. The consequences of this for the design were:
  - names must be unique per-tenant
  - the tenant-id appears in the endpoint URL

However, the rest of OpenStack seems to have gone in a direction where 
the "name" is really just a comment field, everything is addressed only 
by UUID. A consequence of this is that it renders the tenant-id in the 
URL pointless, so many projects are removing it.

Unfortunately, one result is that if you create a resource and e.g. miss 
the Created response for any reason and thus do not have the UUID, there 
is now no safe, general automated way to delete it again. (There are 
obviously heuristics you could try.) To solve this problem, there is a 
proposal floating about for clients to provide another unique ID when 
making the request, which would render a retry of the request 
idempotent. That's insufficient, though, because if you decide to roll 
back instead of retry you still need a way to delete using only this ID.

So basically, that design sucks for both humans (who have to remember 
UUIDs instead of names) and machines (Heat). However, it appears that I 
am in a minority of one on this point, so take it with a grain of salt.

> Please read and comment :)

A few comments...

#1 thing is that the launch configuration needs to be somehow 
represented. In general we want the launch configuration to be a 
provider template, but we'll want to create a shortcut for the obvious 
case of just scaling servers. Maybe we pass a provider template (or URL) 
as well as parameters, and the former is optional.

Successful creates should return 201 Created, not 200 OK.

Responses from creates should include the UUID as well as the URI. 
(Getting into minor details here.)

Policies are scoped within groups, so do they need a unique id or would 
a name do?

I'm not sure I understand the webhooks part... webhook-exec is the thing 
that e.g. Ceilometer will use to signal an alarm, right? Why is it not 
called something like /groups/{group_id}/policies/{policy_id}/alarm ? 
(Maybe because it requires different auth middleware? Or does it?)

And the other ones are setting up the notification actions? Can we call 
them notifications instead of webhooks? (After all, in the future we 
will probably want to add Marconi support, and maybe even Mistral 
support.) And why are these attached to the policy? Isn't the 
notification connected to changes in the group, rather than anything 
specific to the policy? Am I misunderstanding how this works? What is 
the difference between 'uri' and 'capability_uri'?

You need to define PUT/PATCH methods for most of these also, obviously 
(I assume you just want to get this part nailed down first).


More information about the OpenStack-dev mailing list