超訳: Heat Orchestration Template (HOT) Guide

Heatがさっぱりわからなかったので、ひとまずテンプレートガイドを読んでみたついでに和訳してみました(オリジナルはこちら)。

Heat Orchestration Template (HOT) Guide

  • 原文
    HOT is a new template format meant to replace the Heat CloudFormation-compatible format (CFN) as the native format supported by the Heat over time. This guide is targeted towards template authors and explains how to write HOT templates based on examples. A detailed specification of HOT can be found at Heat Orchestration Template (HOT) Specification.

  • 和訳
    HOTはHeatが利用するネイティブフォーマットをHeat CloudFormation互換フォーマット(CFN)から置き換えることを意図した新たなテンプレートフォーマットです。
    このガイドはテンプレート作成者を対象として、用例を交えつつHOTテンプレートの作成方法を説明します。

Status

  • 原文
    HOT support is still under development and needs more work to provide access to all functionality currently available via the CFN compatible template interface. This guide will be updated periodically whenever new features get implemented for HOT.

  • 和訳
    HOTサポートは現在も開発中で、全ての機能に対してCFN互換フォーマットのテンプレートインターフェイス経由でアクセスするために多くの作業を必要としています。
    このガイドはHOTに新機能が実装される毎に更新されます。

Writing a hello world HOT template

  • 原文
    This section gives an introduction on how to write HOT templates, starting from very basic steps and then going into more and more detail by means of examples.

  • 和訳
    このセクションでは、HOTテンプレートの記述方法の基本的から始めて、続いてより詳細な部分について用例を用いて紹介していきます。

A most basic template

  • 原文
    The most basic template you can think of may contain only a single resource definition using only predefined properties (along with the mandatory Heat template version tag). For example, the template below could be used to simply deploy a single compute instance.

  • 和訳
    あなたが考えることのできる、最も基本的なテンプレートは、前定義されたプロパティを利用した単一のリソース定義でしょう(Heatテンプレートの必須タグであるversionも加える必要があります)。

heat_template_version: 2013-05-23

description: Simple template to deploy a single compute instance

resources:
  my_instance:
    type: OS::Nova::Server
    properties:
      key_name: my_key
      image: F18-x86_64-cfntools
      flavor: m1.small
  • 原文
    Each HOT template has to include the heat_template_version key with value ‘2013-05-23’ (the current version of HOT). While the description is optional, it is good practice to include some useful text that describes what users can do with the template. In case you want to provide a longer description that does not fit on a single line, you can provide multi-line text in YAML, for example:

  • 和訳
    それぞれのHOTテンプレートには、heat_template_versionキーと、その値として現在のHOTのバージョン番号である'2013-05-23'を含める必要があります。
    descriptionキーはオプションですが、利用者がそのテンプレートを利用して何ができるのか、など幾つかの有用な情報を記載することを推奨します。単一の行に収まらない長い説明を提供したい場合は、YAML形式で複数行のテキストを記載することが可能です。
    ※'>'は改行を半角スペースに置き換える、ただし最終行の改行は保存される

description: >
  This is how you can provide a longer description
  of your template that goes over several lines.
  • 原文
    The resources section is required and must contain at least one resource definition. In the example above, a compute instance is defined with fixed values for the ‘key_name’, ‘image’ and ‘flavor’ parameters.

    Note that all those elements, i.e. a key-pair with the given name, the image and the flavor have to exist in the OpenStack environment where the template is used. Typically a template is made more easily reusable, though, by defining a set of input parameters instead of hard-coding such values.

  • 和訳
    resourcesセクションは必須で、少なくとも1つのリソース定義が含まれている必要があります。上記の例では、nova-computeの仮想マシンインスタンスの固定値としてkey_name , image , flavor の値が定義されています。
    ※テンプレートで利用するキーペアの名称(key_name)、imageで指定するイメージID、flavorで指定するフレーバ名が全てOpenStack環境上に登録済みである必要があります。典型的なテンプレートは、このような値をハードコードする代わりに入力パラーメタとすることで再利用しやすいよう構成されています。

Template input parameters

  • 原文
    Input parameters defined in the parameters section of a HOT template (see also Parameters Section) allow users to customize a template during deployment. For example, this allows for providing custom key-pair names or image IDs to be used for a deployment. From a template author’s perspective, this helps to make a template more easily reusable by avoiding hardcoded assumptions.

    Sticking to the example used above, it makes sense to allow users to provide their custom key-pairs, provide their own image, and to select a flavor for the compute instance. This can be achieved by extending the initial template as follows:

  • 和訳
    利用者は、HOTテンプレートのparametersセクションで定義(参照: Parameters Section)された入力パラメータの値を、テンプレート適用時にカスタマイズすることができます。
    例えば、展開時にキーペア名(key_name)やイメージID(image)をカスタマイズして指定することを可能となり、テンプレート作成者視点ではキーの値を想定してハードコードすることを回避することで、より再利用しやすいテンプレートを作るために役立ちます。

    上記の例のように、利用者が自身のキーペアやイメージ、仮想マシンインスタンスのフレーバを選択して展開できるようにすることは合理的といえます。 以下のように初期テンプレートを拡張することにより設定することができます。

heat_template_version: 2013-05-23

description: Simple template to deploy a single compute instance

parameters:
  key_name:
    type: string
    label: Key Name
    description: Name of key-pair to be used for compute instance
  image_id:
    type: string
    label: Image ID
    description: Image to be used for compute instance
  instance_type:
    type: string
    label: Instance Type
    description: Type of instance (flavor) to be used

resources:
  my_instance:
    type: OS::Nova::Server
    properties:
      key_name: { get_param: key_name }
      image: { get_param: image_id }
      flavor: { get_param: instance_type }
  • 原文
    In the example above, three input parameters have been defined that have to be provided by the user upon deployment. The fixed values for the respective resource properties have been replaced by references to the corresponding input parameters by means of the get_param function (see also Intrinsic Functions).

    You can also define default values for input parameters which will be used in case the user does not provide the respective parameter during deployment. For example, the following definition for the instance_type parameter would select the ‘m1.small’ flavor unless specified otherwise be the user.

  • 和訳
    上記の例には、3つの入力パラメータが展開時に利用者から指定されなければならないことが定義されています。それぞれのリソースプロパティの値は、get_param関数(参照: Intrinsic Functions) を利用してキー(key_name , image , flavor)に対応する入力パラメータへの参照に置き換えられています。

    利用者が展開時に入力パラメータを指定しなかった場合に使用されるデフォルト値も定義することができます。
    以下の例ではflavorキーの値が参照する入力パラメータ(instance_type)を利用者が指定しなかった場合は'm1.small'がフレーバとして選択されることになります。

parameters:
  instance_type:
    type: string
    label: Instance Type
    description: Type of instance (flavor) to be used
    default: m1.small
  • 原文
    Another option that can be specified for a parameter is to hide its value when users request information about a stack deployed from a template. This is achieved by the hidden attribute and useful, for example when requesting passwords as user input:

  • 和訳
    また、パラメータのオプションで、利用者がテンプレートに関する情報を要求した場合に、その値を非表示にできます。これは利用者にユーザ情報入力を要求するような場合にパスワード情報を隠し属性として隠蔽することを可能にします。

parameters:
  database_password:
    type: string
    label: Database Password
    description: Password to be used for database
    hidden: true
Restricting user input
  • 原文
    In some cases you might want to restrict the values of input parameters that users can supply. For example, you might know that the software running in a compute instance needs a certain amount of resources so you might want to restrict the instance_type parameter introduced above. Parameters in HOT templates can be restricted by adding a constraints section (see also Parameter Constraints). For example, the following would allow only three values to be provided as input for the instance_type parameter:

  • 和訳
    場合によっては、入力パラメータとして利用者が指定する値を制限したい場合があるかもしれません。例えば、nova-compute上の仮想マシンインスタンスで実行されるソフトウェアが利用するリソースの量を予め把握しており、上記のinstance_typeパラメータの値に制約を儲けたい場合などです。
    HOTテンプレート内の各パラメータはconstraintsセクション(参照: Parameter Constraints)で制限することができます。例えば以下の例では、instance_typeの入力パラメータとして3つの値(m1.medium , m1.large , m1.xlarge)のみを許可します。

parameters:
  instance_type:
    type: string
    label: Instance Type
    description: Type of instance (flavor) to be used
    constraints:
      - allow_values: [ m1.medium, m1.large, m1.xlarge ]
        description: Value must be one of m1.medium, m1.large or m1.xlarge.
  • 原文
    The constraints section allows for defining a list of constraints that must all be fulfilled by user input. For example, the following list of constraints could be used to clearly specify format requirements on a password to be provided by users:

  • 和訳
    constraintsセクションには、利用者がパラメータ入力時に満たさなければならない全ての制約のリストを定義することができます。例えば、次の制約のリストにより利用者が入力するパスワード要件を明示的に指定することができます。

parameters:
  database_password:
    type: string
    label: Database Password
    description: Password to be used for database
    hidden: true
    constraints:
      - length: { min: 6, max: 8 }
        description: Password length must be between 6 and 8 characters.
      - allowed_pattern: "[a-zA-Z0-9]+"
        description: Password must consist of characters and numbers only.
      - allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
        description: Password must start with an uppercase character.
  • 原文
    Note that you can define multiple constraints of the same type. Especially in the case of allowed patterns this not only allows for keeping regular expressions simple and maintainable, but also for keeping error messages to be presented to users precise.

  • 和訳
    同じタイプの制約を複数定義することが可能であることに注意してください。特に、上記のようなケースでは正規表現をシンプルに記述できることによるメンテナンス性の向上だけでなく、利用者に的確なエラーメッセージを提示することも可能にしています。

Providing template outputs

  • 原文
    In addition to template customization through input parameters, you will typically want to provide outputs to users, which can be done in the outputs section of a template (see also Outputs Section). For example, the IP address by which the instance defined in the example above can be accessed should be provided to users. Otherwise, users would have to look it up themselves. The definition for providing the IP address of the compute instance as an output is shown in the following snippet:

  • 和訳
    入力パラメータによるテンプレートのカスタマイズに加えて、通常はテンプレートのoutputsセクション(参照: Outputs Section)でカスタマイズされた出力を利用者に提供することになるでしょう。
    例えば、ここまでの例で作成した仮想マシンインスタンスにアクセスするためのIPアドレス情報は出力情報として利用者に提供されるべきでしょう。そうでなければ、利用者自身がアクセスするための情報を探さなければなりません。以下は、仮想マシンインスタンスIPアドレス情報を出力するためのテンプレート定義部分です。

outputs:
  instance_ip:
    description: The IP address of the deployed instance
    value: { get_attr: [my_instance, first_address] }
  • 原文
    Output values are typically resolved using intrinsic function such as the get_attr function in the example above (see also Intrinsic Functions).

  • 和訳
    出力される値は、通常、上記の例にある通りget_attr関数のような組み込み関数(参照: Outputs Section)を利用して出力されます。

用語

  • CFN: Heat CloudFormation-compatible format
  • HOT: Heat Orchestration Template