Open Stack

I've noticed a few code reviews for new Heat resource types - 
particularly Neutron resource types - where folks are struggling to find 
the appropriate way to model the underlying API in Heat. This is a 
really hard problem, and is often non-obvious even to Heat experts, so 
here are a few tips that might help.

Resources are nouns, they model Things. Ideally Things that have UUIDs. 
The main reason to have a resource is so you can reference its UUID (or 
some attribute) and pass it to another resource or to the user via an 
output.

If two resources _have_ to be used together, they're really only one 
resource. Don't split them up - especially if the one whose UUID other 
resources depend on is the first to be created but not the only one 
actually required by the resource depending on it.

Resources are *not* verbs - you don't need or want a separate resource 
type for every API call, only the ones that create a Thing with a UUID.

The foundational principle of orchestration is that it builds workflows 
based on explicit relationships defined in templates. This is the core 
of Heat, and so long as it remains relatively simple it works in 
extremely powerful ways. It is also brittle, in that if the resource 
model does not fit it breaks in a myriad of subtle ways. If you find 
yourself having to hack the workflow in some way not defined in the 
template - by changing the update order, messing around with implicit 
dependencies, &c. - you are probably Doing It Wrong and the problem is 
in the resource modelling.

Some APIs are just particularly hard to model, and in those cases if you 
are a member in good standing of the project in question, you should 
push back and try to get those APIs fixed. It isn't any easier for users 
than it is for us; the only difference is that Heat has a formal model 
to expose the brokenness.

As I said, figuring this all out is really hard to do, and the existing 
resources in Heat are by no means perfect (we even had a session at the 
Design Summit devoted to fixing some of them[1]). If anyone has a 
question about a specific model, feel free to ping me or add me to the 
review and I will do my best to help.

cheers,
Zane.

[1] https://etherpad.openstack.org/p/icehouse-summit-heat-exorcism