Using Parameters with a Template

Parameters allow you to customize your template to avoid hard-coded values and accept input during deployment. The parameters: section of the template contains a definition that includes type, label, and description for each parameter. You can also include default values and constraints.

Use Case: Require the key pair as an input parameter

The basic example in Creating an Orchestration Template contains a key_name property. Instead of hard-coding the key_name as a property of the instance, you can require the key_name as an input parameter.

  1. Add the parameters: section with a definition for key_name type to the template.

     parameters:
       key_name:
         type: string
         label: Key Pair
         description: Name of key pair to use for launching an instance
    
  2. Update the instance key_name property with the { get_param: key_name } variable.

     heat_template_version: 2015-04-30
        
     description: Template to launch an instance
        
     resources:
     # instances
       sample_instance:
         type: OS::Nova::Server
         properties:
           flavor: m1.small
           image: ubuntu-16.04.1-server-amd64
           name: sampleStackInstance
           key_name: { get_param: key_name }
           networks: 
              - network: sampleStackNetwork
        
     parameters:
       key_name:
         type: string
         label: Key Pair
         description: Name of key pair to use for launching an instance
    
  3. Create the stack using the --parameter option to specify a key pair.

    $ openstack stack create sampleStackInstance -t sampleTemplate.yaml \
       --parameter "key_name=my_key"
    +---------------------+--------------------------------------+
    | Field               | Value                                |
    +---------------------+--------------------------------------+
    | id                  | <stack-id>                           |
    | stack_name          | sampleStackInstance                  |
    | description         | Template to launch an instance       |
    | creation_time       | 2017-06-09T18:34:52                  |
    | updated_time        | None                                 |
    | stack_status        | CREATE_IN_PROGRESS                   |
    | stack_status_reason | Stack CREATE started                 |
    +---------------------+--------------------------------------+
    

Providing a Default Value for a Parameter

If you neglect to provide an expected input parameter during deployment using the CLI, you receive the following error message:

ERROR: The Parameter (key_name) was not provided.

If you are using the Dashboard, the parameter is a required value in the Launch Stack dialog. Notice the label and the pop-up help for the KEY PAIR field is the same as the label and description properties from the parameter definition in your template.

Launch Stack Required Parameter

It is useful to provide a default parameter value in case a user does not provide one. For example, if a key pair is required for launching an instance, then add a default key pair.

parameters:
  key_name:
    type: string
    label: Key Pair
    description: Name of key pair to use for launching an instance
    default: default_key

Defining a Parameter Constraint

You can restrict parameter values to ensure valid input using the constraints property. For example, the following adds a new parameter for flavor with a constraint to select one of three possible sizes.

parameters:
  key_name:
    type: string
    label: Key Pair
    description: Name of key pair to use for launching an instance
    default: default_key
  flavor:
    type: string
    label: Instance Type
    description: Choose a hardware configuration
    constraints:
      - allowed_values: [ m1.small, m1.medium, m1.large ]
        description: Choose an available flavor of m1.small, m1.medium, or m1.large.

If you provide a flavor that is not included in the parameter constraint, you receive the following error message that includes your constraint description:

ERROR: Parameter 'flavor' is invalid: Choose an available flavor of m1.small, m1.medium, or m1.large.

In the Dashboard, the flavor constraint appears as a drop-down list:

Launch Stack Constraints