[openstack-dev] [Heat] naming of provider template for docs

Zane Bitter zbitter at redhat.com
Fri Sep 19 23:03:16 UTC 2014


On 19/09/14 01:10, Mike Spreitzer wrote:
> Angus Salkeld <asalkeld at mirantis.com> wrote on 09/18/2014 09:33:56 PM:
>
>> Hi
>
>> I am trying to add some docs to openstack-manuals hot_guide about
>> using provider templates : https://review.openstack.org/#/c/121741/
>
>> Mike has suggested we use a different term, he thinks "provider" is
>> confusing.
>> I agree that at the minimum, it is not very descriptive.
>
>> Mike has suggested "nested stack", I personally think this means
> something a
>> bit more general to many of us (it includes the concept of aws stacks)
> and may
>> I suggest "template resource" - note this is even the class name for
>> this exact functionality.
>>
>> Thoughts?
>
>> Option 1) stay as is "provider templates"
>> Option 2) "nested stack"
>> Option 3) "template resource"
>
> Thanks for rising to the documentation challenge and trying to get good
> terminology.
>
> I think your intent is to describe a category of resources, so your option
> 3 is superior to option 1 --- the thing being described is not a template,
> it is a resource (made from a template).
>
> I think
>
> Option 4) "custom resource"

"Custom resource" has a specific and very different meaning in 
CloudFormation that is likely to come back to bite us if we overload it.

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cfn-customresource.html

> would be even better.  My problem with "template resource" is that, to
> someone who does not already know what it means, this looks like it might
> be a kind of resource that is a template (e.g., for consumption by some
> other resource that does something with a template), rather than itself
> being something made from a template.  If you want to follow this
> direction to something perfectly clear, you might try "templated resource"
> (which is a little better) or "template-based resource" (which I think is
> pretty clear but a bit wordy) --- but an AWS::CloudFormation::Stack is
> also based on a template.  I think that if you try for a name that really
> says all of the critical parts of the idea, you will get something that is
> too wordy and/or awkward.  It is true that "custom resource" begs the
> question of how the user accomplishes her customization, but at least now
> we have the reader asking the right question instead of being misled.
>
> I agree that "nested stack" is a more general concept.  It describes the
> net effect, which the things we are naming have in common with
> AWS::CloudFormation::Stack.  I think it would make sense for our
> documentation to say something like "both an AWS::CloudFormation::Stack
> and a custom resource are ways to specify a nested stack".

It more or less does, but you're welcome to propose a patch to clarify:

http://docs.openstack.org/developer/heat/glossary.html

cheers,
Zane.



More information about the OpenStack-dev mailing list