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

Christopher Armstrong chris.armstrong at rackspace.com
Thu Nov 14 18:53:26 UTC 2013

Thanks for the comments, Zane.

On Thu, Nov 14, 2013 at 9:56 AM, Zane Bitter <zbitter at redhat.com> wrote:

> 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.
I'm a little unclear as to what point you're making here. Right now, the
"launch configuration" is specified in the scaling group by the "resources"
property of the request json body. It's not a full template, but just a
"snippet" of a set of resources you want scaled.

As an aside, maybe we should replace this with a singlular "resource" and
allow people to use a Stack resource if they want to represent multiple

I guess we can have a simpler API for using an old-style, server-specific
"launch configuration", but I am skeptical of the benefit, since specifying
a single Instance resource is pretty simple.

> Successful creates should return 201 Created, not 200 OK.

Okay, I'll update that. I think I also forgot to specify some success
responses for things that need them.

> 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 guess we could get rid of the ID and only have a name, what do other
people think?

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

Mostly because it's unnecessary. The idea was to generate a secret, opaque,
revokable ID that maps to the specific policy.

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

Policies represent ways to change a group ("add +5% to this group").
Webhooks execute policies.

A "capability URI" is a URI which represents a capability to do something
all by itself. capability_uri would be the webhook-exec thing. The regular
URI would be the thing under
/groups/{group_id}/policies/{policy_id}/webhooks. That URI needs to exist
so you can perform the DELETE operation on it. (but you can't DELETE the
capability_uri, only POST to it to execute the policy).

I'll think more about webhooks vs notifications.

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

Yeah, I do. Thanks for reminding me :)

IRC: radix
Christopher Armstrong
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20131114/3813f560/attachment.html>

More information about the OpenStack-dev mailing list