Jump to: navigation, search

Difference between revisions of "Heat/UI"

(New API Endpoint for Returning Template Parameters)
Line 80: Line 80:
  
 
=== Specification ===
 
=== Specification ===
   GET /
+
   GET v1/​{tenant_id}​/get_parameters
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Parameter !! Style !! Type !! Description
 +
|-
 +
| tenant_id || URI || String || The unique identifier of the tenant or account.
 +
|-
 +
| template_url || plain || String || The URL of the template to instantiate. This is ignored if the template is supplied inline.
 +
|-
 +
| template || plain || String || A JSON template to instantiate. Takes precedence over the template URL if both are supplied.
 +
|-
 +
| stack_id || plain || String || The unique identifer for an existing stack. Takes precedence if supplied.
 +
|}
  
 
Currently, Heat returns the parameters from the template_validate call but they are formatted for CFN compatibility. This will make
 
Currently, Heat returns the parameters from the template_validate call but they are formatted for CFN compatibility. This will make
 
  
 
== Help Text ==
 
== Help Text ==

Revision as of 19:54, 4 December 2013

Stack Keywords

Summary

This is a proposal for an additional field, "keywords", to be added to the HOT specification. This field will contain a list of keywords related to the Stack that generally describe the purpose of the Stack.

Use Case

Assume that an end-user of Heat has spun up 20 stacks and has now requested help from a Support Operator of heat. In this case, the end-user did not have a solid naming convention for naming his stacks, they are all named "tim1", "tim2", etcŠ And also his request to the Support Operator was really vague, like "My Wordpress stack is broken."

The first thing that the Support Operator would do, would be to pull up end-user's stacks in either Horizon or via the heat client api. In both cases, at the moment, he would then have to either stack-show on each stack to look at the description of the stack or ask the end-user for a stack-id/stack-name. This currently gets the job done but a better experience would be for stack-list to already display some keywords about each stack so the Support Operator would have to do less digging or to allow the Support Operator to query lists of stacks by keyword.

In this case the end-user only has one Wordpress stack so he would have been annoyed if the Support Operator requested more information from him. (Or maybe he has more than one wordpress stack, but only one currently in CREATE_FAILED state).

As a team, we have already encountered this exact situation just doing team testing so I imagine that others would find value in a consistent way to determine at least a general purpose of a stack, from the stack-list page. Putting the stack-description in the stack-list table would take up too much room from a design standpoint.

Specification

 keywords: 
 - wordpress
 - mysql
 - lamp

Implementation

In order for the keywords to be searchable, the ideal implementation would include adding a child table to the stacks table in the heat database, then adding an option to the stacks_list API endpoint to query stacks by keywords and to return all keywords per stack in the stacks_list and stack_show API endpoints.


Parameter Grouping and Ordering

Summary

Currently, Heat returns the parameters from the template in an unorganized manner. This can result in important parameters being randomly pushed towards the bottom as well as logical groupings of parameters being random instead.

Use Case

Grouping and ordering parameters would help the client make intelligent decisions about how to display the parameters to the end-user. If the parameters were returned in organized groups with a consistent order then a much richer interface could be designed to help step the end-user through the process of providing values for these parameters. For example, if I had the following parameters for a database resource: db_name, db_username, and db_password, there is currently not a way to ensure that these parameters get grouped together for the end-user. Instead they may be returned mixed with parameters for other resources like a web node resource: db_name, web_node_instance, web_node_password, db_password, etc...

Specification

 parameter-groups:
 - label: Database Parameters
   description: Configure specifics about Database things.
   parameters:
   - db-username
   - db-password
   - db-instance-name
 - label: Web Server Parameters
   description: Configure specifics about Web Server things.
   parameters:
   - server-name
   - server-password
   - flavor
   - image
   - keyname

Attempting to distill the mailing list conversation into the most correct specification, having the groups and ordering declared explicitly solves the use case from the most perspectives. Declaring the group in the naming convention of the parameter is flawed because the group will need a human-readable label which should not be relied upon for programmatic parsing of the groups. Ordering the parameters explicitly will make it easier for interfaces to understand what the right thing to do with parameter order should be.

Implementation

The implementation can be broken down into 2 separate but dependent blueprints. One blueprint to update the HOT specification and guide for this new top-level field, "parameter-groups" and one blueprint to address the current issues with how template_validate returns parameters (address below "New API Endpoint for Returning Template Parameters").


New API Endpoint for Returning Template Parameters

Summary

In the process of improving the capabilities of Heat to return a more explicit representation of Template Parameters it is becoming apparent that we need a dedicated API endpoint for retrieving parameters in a consistent, single truth representation, way.

Use Case

Any downstream user interface for Heat will need to retrieve information about template parameters from the template, during a Stack Create, and later from the representation of the Stack, during a Stack Update. As a user of Heat, the downstream user interface needs to be able to retrieve these parameters as one representation of truth, regardless of whether the submitted template is a CFN or HOT template. This user interface should be able to rely on this consistency when making various display decisions for parameters based on the data structure returned from Heat.

Specification

 GET v1/​{tenant_id}​/get_parameters
 
Parameter Style Type Description
tenant_id URI String The unique identifier of the tenant or account.
template_url plain String The URL of the template to instantiate. This is ignored if the template is supplied inline.
template plain String A JSON template to instantiate. Takes precedence over the template URL if both are supplied.
stack_id plain String The unique identifer for an existing stack. Takes precedence if supplied.

Currently, Heat returns the parameters from the template_validate call but they are formatted for CFN compatibility. This will make

Help Text

Summary

Currently each parameter in the HOT syntax has a field called "description" that describes the purpose of the parameter. I am proposing an additional field called "help" that can further explain a parameter.

Use Case

Description and help are separate things from a UI perspective. A description might be displayed as a label in a form or in a paragraph somewhere around the input. A help string is typically displayed as hover text when focusing on the input or hovering/clicking on a question mark icon next to the field. We could technically separate these things in the code but because they serve separate purposes I would prefer to have them be defined explicitly.

Example: An example where this use case originated was with Nova Keypairs. The description of a keypair parameter might be something like, "This is the name of a nova key pair that will be used to ssh to the compute instance." A help string for this same parameter would be, "To learn more about nova keypairs visit this help article: http://www.learnsomething.com/keypairs"

Specification

   Parameters:
       <parameter name>:
           description: This is the name of a nova key pair that will be used to ssh to the compute instance.
           help: To learn more about nova key pairs visit this help article: http://www.learnsomething.com/keypairs

Implementation

Adding Help text to the HOT syntax should only require an update to the HOT specification and guide. There are no other known code changes required.