Openstack Heat Template 模板定义说明(一)

本文为openstack 官方wiki的翻译，略有增删 

http://docs.openstack.org/user-guide/content/hot-spec.html

heat 模板结构

以YAML格式定义的HOT模板使用如下结构：

heat_template_version: 2013-05-23
 
description:
  # description of the template
 
parameter_groups:
  # declaration of input parameter groups and order
 
parameters:
  # declaration of input parameters
 
resources:
  # declaration of template resources
 
outputs:
  # declaration of output parameters

  
1. heat_template_version

heat 模板版本号：heat 模板的版本号不仅代表模板的格式，也包含所支持的特性，目前heat版本号支持如下两个值：
 2013-05-23 
 提示： 该版本包含icehouse及以前的heat特性
 2014-10-16
 提示： 该版本包含juno及以前的heat特性，即包含新添加的，也存在删除一些旧特性

 
2.description

该部分是针对当前模板功能的详细描述

3.parameter_groups

这是模板的可选部分，该部分定义应该如何组织输入参数

4.parameters

这是模板的可选部分，该部分定义在初始化模板时必须提供的输入参数

5.resources

该部分包含模板资源的声明，在任何模板中该部分中都应至少包含一个资源类型，否则模板实际上将不会做任何事情

6.outputs

这是模板的可选部分，该部分描述在模板初始化后，对用户可见的输出参数

Parameter groups section

待补充

Parameters section

该部分定义在初始化模板时必须提供的输入参数,例如在每次部署模板时，自定义每次部署的参数值或者绑定到不同环境，例如特定的镜像


每个参数都由嵌套的模块定义，参数名称在第一行定义，而附加属性例如类型或者默认值作为嵌套元素
典型的参数定义如下格式：

parameters:
  <param name>:
    type: <string | number | json | comma_delimited_list | boolean>
    label: <human-readable name of the parameter>
    description: <description of the parameter>
    default: <default value for parameter>
    hidden: <true | false>
    constraints:
      <parameter constraints>

格式中每个嵌套元素的含义如下：

param name: 参数的名称
type:参数的类型，支持的类型如string, number,json,comma_delimited_list,boolean
label: 可选属性，便于阅读的参数名称/标签
description:可选属性，便于阅读的参数描述
default:可选属性，参数的默认值，当用户没有在部署时定义特定值时将使用默认值来部署栈(stack，下同)
hidden:可选属性，规定当用户使用模板创建栈时,该参数是否应该隐藏，这个属性可以用来隐藏密码类型的参数
constraints:可选属性，对参数的约束，heat引擎部署栈时将使用该约束来检查用户的输入参数是否满足要求

下面是参数定义的简单示例：

parameters:
  user_name:
    type: string
    label: User Name
    description: User name to be configured for the application
  port_number:
    type: number
    label: Port Number
    description: Port number to be configured for the web server

 Parameter constraints

 针对参数的约束有多种约束类型：

 length
 range
 allowed_values
 allowed_pattern
 custom_constraint

 
 参数约束按如下列表形式进行定义：

 constraints:
  - <constraint type>: <constraint definition>

    description: <constraint description>

constraint type：约束类型
constraint definition：约束定义，实际定义约束的地方，每个约束类型的具体语法后面会介绍。
description:约束的描述，是可选属性，该文字将在用户提供了不满足于参数要求的值时显示给用户。


如下示例显示了带两个约束的参数定义：

parameters:
  user_name:
    type: string
    label: User Name
    description: User name to be configured for the application
    constraints:
      - length: { min: 6, max: 8 }
        description: 用户名必须是6到8个字符长度
      - allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
        description: 用户名必须以大写字母开头

length 长度

长度约束可应用于字符串(string)类型的参数，它定义了该字符串类型参数的最小和最大长度，语法如下：
length: { min: <下限>, max: <上限> }
可以只定义上限或者下限，但是二者至少要有一个，不可以都不提供

range 范围

范围约束可应用于数值(number)类型的参数，它定义了一个数值类型参数的最小和最大值，语法如下：
range: { min: <下限>, max: <上限> }
可以只定义上限或者下限，但是二者至少要有一个，不可以都不提供

allowed_values 有效值

有效值约束可应用于数值或字符串类型的参数，它指定了一个参数可能出现的参数值集合，在部署时，用户提供的值必须匹配有效值列表中的某个元素
语法如下：
allowed_values: [ <值1>, <值2>, ... ]
或者如下格式：
allowed_values:
  - <值1>
  - <值2>
  - ...

例如：
parameters:
  instance_type:
    type: string
    label: Instance Type
    description: Instance type for compute instances
    constraints:
      - allowed_values:
        - m1.small
        - m1.medium
        - m1.large

allowed_pattern 有效模式

有效模式约束可应用于字符串类型的参数，它指定了一个正则表达式用来检查用户提供的参数值，语法如下：
allowed_pattern: <正则表达式>

例如：
parameters:
  user_name:
    type: string
    label: User Name
    description: User name to be configured for the application
    constraints:
      - allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
        description: 用户名必须以大写字母开头

custom_constraint 自定义约束

自定义约束增加了校验时的额外检查项，通常同来检查后端的特定资源是否存在，一般自定义约束由插件实现，以提供一些高级的检验逻辑
例如：
parameters:
  key_name
    type: string
    description: SSH key pair
    constraints:
      - custom_constraint: nova.keypair

Pseudo Parameters 伪参数

除了模板作者定义的参数，heat模块也为每个栈创建了两个参数来引用栈的名称和id，这两个参数被定义为OS::stack_name 和OS::stack_id
它们的值可以通过get_param 内置方法来获得。