- 1 Stack Keywords
- 2 Parameter Grouping and Ordering
- 3 New API Endpoint for Returning Template Parameters
- 4 Help Text
- 5 Parameter Label
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.
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.
keywords: - wordpress - mysql - lamp
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
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.
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...
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.
Adding Parameter Grouping and Ordering to the HOT syntax should only require an update to the HOT specification and guide. There are no other known code changes required.
New API Endpoint for Returning Template Parameters
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.
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.
|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 need to be updated regardless for the dependent blueprint regarding grouping and ordering parameters. Furthermore, the parameters should default to the HOT syntax as the source of truth for data representation instead of CFN and allow for graceful backwards compatibility regarding grouping and ordering parameters if parameter-groups is not present. In this case, still order the parameters using an OrderedDict so that they are displayed in the same order they are represented in the template is a graceful backwards compatibility measure.
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.
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"
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
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.
Horizon is currently parsing the name of each template parameter to use for display purposes in the HTML <label> for each input. Ideally, the template will provide a human-readable label instead.
A downstream user interface that is attempting to build an HTML form would default to the label provided by the template for human consumption. This design would allow the label to be displayed as the template author explicitly intended instead of attempting to derive the label by parse the keyname of the parameter.
Parameters: nova-key_pair: label: Keypair
Adding the label to the HOT syntax should only require an update to the HOT specification and guide. There are no other known code changes required.