Heat/htr

= Heat Template Repository (Heater) = Heat Template Repository (Heater) is a service for the storage, management, and versioning of "known good" templates. Its goal is to allow an organization to encode and then easily share architectural knowledge via a library of templates. Envisioned features include indexing, tagging and search, versioning, configurable back-end storage, and extended metadata composition.

Heater's primary function is as a centralized template library. It should be installable and manageable outside of any particular OpenStack enclave and have no affinity for any one installation of Heat. Many different organizations should be able to easily stand up Heater and define their own policies around publishing and storage.

Use Cases

 * 1) As a client user I want to be able to query a service which contains a list of curated/supported templates in order to take advantage of my service providers expertise in various application architectures.
 * 2) A user of the catalog wants to be able to search the templates by keywords.
 * 3) A service maintainer would like to have a repository in which he can manage Heat templates and maintain associated keywords and metadata.
 * 4) Associating keywords with a template allows a Service Provider to categorize templates for easy grouping and searching templates with related themes or features.
 * 5) Similar to Nova and other Openstack projects, allowing for key/value metadata allows a Service Provider to associate contextualized keywords not covered in the base schema.
 * 6) As a service provider, I want to have a centralized repository in which I can share institutional systems architecture knowledge encoded in Heat templates.
 * 7) As a service provider, I should control access to this centralized repository and determine who can and cannot create new, remove or revise existing Heat templates.
 * 8) As a service provider, I need to be able to tag templates with searchable, indexable keywords.
 * 9) A Service Provider wants to be able to restrict a template's visibility by user role in order to support different SLAs by user role.

Authentication/Access control
Handled via Keystone as usual

API
(Spec forthcoming - just a basic overview of the possible endpoints/operations)
 * Submit a template and optional metadata and tags

POST /templates

template-type: Application keystone-roles: - admin - demo application: name: Wordpress version: 3.6.1 flavor: Single Linux server with WordPress 3.6.1 and MySQL 5.5 weight: 3 icons: - href: https://600861890ddb34a8670a-744765205721eed93c384dae790e86aa.ssl.cf2.rackcdn.com/wordpress-tattoo.png type: default - href: https://600861890ddb34a8670a-744765205721eed93c384dae790e86aa.ssl.cf2.rackcdn.com/wordpress-icon-20x20.png type: small keywords: - wordpress - mysql meta: some-junk: junk color: sadness template: documentation: abstract: some abstract... guide: This blueprint includes a single server running Wordpress with Varnish. This blueprint's performance has not been measured. instructions: If you're new to WordPress, the documentation will step you through the process of logging into the admin panel, customizing your blog, and changing your theme.


 * Retrieve a list of templates

GET /templates?limit=100


 * Retrieve a version of a template (Published version by default, with/without metadata)

GET /templates/:id?meta=horizon&meta=documentation&version=b6059

GET /templates/:id/history {   current: b6059, b6059: { version: b6059, submitted: ... a date ...       ref: ... resource uri to the actual version details ...., },   985a4: { version: 985a4, submitted: ... a date ....       ref: ...resource uri to the actual version details .... } }
 * View a template version history

GET /templates/:id/history/:rev {   version: ref, submitted: .. a date .. comment: "A description of the change/difference" published: Not present if not published, otherwise the publish date }
 * Publish a template version version as LKG (admin)
 * Reject a template version (admin)
 * Add metadata to an existing template version
 * Promote metadata to the LKG version of the template (admin)
 * add/remove tags from a template

Associated metadata
Users should be able to associate metadata with a template to facilitate integration with other tooling like Horizon. This metadata will be kept separate from the raw template so as to ensure that a templates usefulness isn't deluded by the requirements of any given tool. The user should always be able to retrieve a template without the associated metadata. This service should, however, allow the user to retrieve a template "package" that includes the template as well as its metadata (or sub-set thereof). Examples of some types of metadata include:
 * Hints for displaying template resources in a GUI (positioning, size, etc)
 * Associative icons
 * Documentation extensions
 * Alternative versions
 * Changelogs

Versioning and Publishing
Heater should support a very simple (and optional) publishing model in which designated users may review revisions of a template as well as metadata and publish it as the "official" or Last Known Good (LKG) version of the template. It is desired that this publishing model be kept very simple and avoid complex review workflow. When a template is requested, it is this published version that is returned unless a specific version is requested.

Storage Backend
The storage backend for Heater should be configurable, but support basic CRUD as well as versioning. Possible reference implementations would include Git and Swift.

Initial Implementation
Some work on a similar service has already been done at Rackspace as a POC. While the general storage, versioning, publishing, and metadata concepts are there, the current software needs to be brought up to OpenStack standards WRT api implementation, code formatting, and authentication. It also lacks configurability of the data store and tagging, however, the existing code can be brought in line with this spec with very little effort.

Heater is NOT:

 * a proxy to Heat
 * a complete CMS for templates
 * a template design tool
 * designed for one and only one consumer use case