第2章 heat テンプレートの概要
本章のカスタム設定では、heat テンプレートおよび環境ファイルを使用して、オーバークラウドの特定の機能を定義します。本項には、Red Hat OpenStack Platform director に関連した heat テンプレートの構造や形式を理解するための基本的な説明を記載します。
2.1. heat テンプレート
director は、Heat Orchestration Template (HOT) をオーバークラウドデプロイメントプランのテンプレート形式として使用します。HOT 形式のテンプレートは、通常 YAML 形式で表現されます。テンプレートの目的は、OpenStack Orchestration (heat) が作成するリソースのコレクションであるスタックを定義および作成し、リソースを設定することです。リソースとは、コンピュートリソース、ネットワーク設定、セキュリティーグループ、スケーリングルール、カスタムリソースなどの Red Hat OpenStack Platform (RHOSP) のオブジェクトを指します。
heat テンプレートは、3 つの主要なセクションで構成されます。
- パラメーター
-
これらは、heat に渡される設定 (スタックのカスタマイズが可能) およびパラメーターのデフォルト値 (値を渡さない場合) です。これらの設定がテンプレートの
parameters
セクションで定義されます。 - リソース
-
resources
セクションを使用して、このテンプレートを使用してスタックをデプロイする際に作成することができるリソース (コンピュートインスタンス、ネットワーク、ストレージボリューム等) を定義します。Red Hat OpenStack Platform (RHOSP) には、全コンポーネントに対応するコアリソースのセットが含まれています。これらは、スタックの一部として作成/設定する固有のオブジェクトです。RHOSP には、全コンポーネントに対応するコアリソースのセットが含まれています。これらがテンプレートのresources
セクションで定義されます。 - アウトプット
-
outputs
セクションを使用して、スタックの作成後にクラウドユーザーがアクセスできるアウトプットパラメーターを宣言します。クラウドユーザーはこれらのパラメーターを使用して、デプロイしたインスタンスの IP アドレスやスタックの一部としてデプロイされた Web アプリケーションの URL 等のスタックの詳細を要求することができます。
基本的な heat テンプレートの例:
heat_template_version: 2013-05-23 description: > A very basic Heat template. parameters: key_name: type: string default: lars description: Name of an existing key pair to use for the instance flavor: type: string description: Instance type for the instance to be created default: m1.small image: type: string default: cirros description: ID or name of the image to use for the instance resources: my_instance: type: OS::Nova::Server properties: name: My Cirros Instance image: { get_param: image } flavor: { get_param: flavor } key_name: { get_param: key_name } output: instance_name: description: Get the instance's name value: { get_attr: [ my_instance, name ] }
このテンプレートは、リソース種別 type: OS::Nova::Server
を使用して、クラウドユーザーが指定する特定のフレーバー、イメージ、およびキーで my_instance
というインスタンスを作成します。このスタックは、My Cirros Instance
という instance_name
の値を返すことができます。
heat がテンプレートを処理する際には、テンプレートのスタックとリソーステンプレートの子スタックセットを作成します。これにより、テンプレートで定義するメインのスタックを最上位とするスタックの階層が作成されます。以下のコマンドを使用して、スタックの階層を表示することができます。
$ openstack stack list --nested
2.2. 環境ファイル
環境ファイルとは特別な種類のテンプレートで、これを使用して heat テンプレートをカスタマイズすることができます。コアの heat テンプレートに加えて、環境ファイルをデプロイメントコマンドに追加することができます。環境ファイルには、3 つの主要なセクションが含まれます。
- resource_registry
- このセクションでは、他の heat テンプレートにリンクしたカスタムのリソース名を定義します。これにより、コアリソースコレクションに存在しないカスタムのリソースを作成することができます。
- parameters
- これらは、最上位のテンプレートのパラメーターに適用する共通設定です。たとえば、入れ子状のスタックをデプロイするテンプレートの場合には (リソースレジストリーマッピング等)、パラメーターは最上位のテンプレートにのみ適用され、入れ子状のリソースのテンプレートには適用されません。
- parameter_defaults
- これらのパラメーターは、全テンプレートのパラメーターのデフォルト値を変更します。たとえば、入れ子状のスタックをデプロイする heat テンプレートの場合には (リソースレジストリーマッピングなど)、パラメーターのデフォルト値がすべてのテンプレートに適用されます。
パラメーターがオーバークラウドのすべてのスタックテンプレートに適用されるように、オーバークラウド用にカスタムの環境ファイルを作成する場合には、parameters
ではなく parameter_defaults
を使用します。
基本的な環境ファイルの例:
resource_registry: OS::Nova::Server::MyServer: myserver.yaml parameter_defaults: NetworkName: my_network parameters: MyIP: 192.168.0.1
特定の heat テンプレート (my_template.yaml
) からスタックを作成する際に、この環境ファイル (my_env.yaml
) を追加します。my_env.yaml
ファイルにより、OS::Nova::Server::MyServer
という新しいリソース種別が作成されます。myserver.yaml
ファイルは、このリソース種別を実装する heat テンプレートファイルで、このファイルでの設定が元の設定よりも優先されます。my_template.yaml
ファイルに OS::Nova::Server::MyServer
リソースを含めることができます。
MyIP
は、この環境ファイルと共にデプロイを行うメインの heat テンプレートにしかパラメーターを適用しません。この例では、MyIP
は my_template.yaml
のパラメーターにのみ適用されます。
NetworkName
は、メインの heat テンプレート my_template.yaml
とメインのテンプレートに含まれるリソースに関連付けられたテンプレート (上記の例では OS::Nova::Server::MyServer
リソースおよびその myserver.yaml
テンプレート) の両方に適用されます。
RHOSP が heat テンプレートファイルをカスタムテンプレートリソースとして使用するには、ファイルの拡張子を .yaml または .template のいずれかにする必要があります。
2.3. オーバークラウドのコア heat テンプレート
director には、オーバークラウド用のコア heat テンプレートコレクションおよび環境ファイルコレクションが含まれます。このコレクションは、/usr/share/openstack-tripleo-heat-templates
に保存されています。
このテンプレートコレクションの主なファイルおよびディレクトリーは、以下のとおりです。
overcloud.j2.yaml
- オーバークラウド環境を作成するのに director が使用するメインのテンプレートファイル。このファイルでは Jinja2 構文を使用してテンプレートの特定セクションを繰り返し、カスタムロールを作成します。Jinja2 フォーマットは、オーバークラウドのデプロイメントプロセス中に YAML にレンダリングされます。
overcloud-resource-registry-puppet.j2.yaml
- オーバークラウド環境を作成するのに director が使用するメインの環境ファイル。このファイルは、オーバークラウドイメージ上に保存される Puppet モジュールの設定セットを提供します。director により各ノードにオーバークラウドのイメージが書き込まれると、heat はこの環境ファイルに登録されているリソースを使用して各ノードの Puppet 設定を開始します。このファイルでは Jinja2 構文を使用してテンプレートの特定セクションを繰り返し、カスタムロールを作成します。Jinja2 フォーマットは、オーバークラウドのデプロイメントプロセス中に YAML にレンダリングされます。
roles_data.yaml
- このファイルにはオーバークラウド内のロールの定義が含まれ、サービスを各ロールにマッピングします。
network_data.yaml
-
このファイルには、オーバークラウド内のネットワーク定義、およびそれらのサブネット、割り当てプール、仮想 IP のステータス等の属性が含まれます。デフォルトの
network_data.yaml
ファイルにはデフォルトのネットワーク (External、Internal Api、Storage、Storage Management、Tenant、Management) が含まれます。カスタムのnetwork_data.yaml
ファイルを作成して、openstack overcloud deploy
コマンドに-n
オプションで追加することができます。 plan-environment.yaml
- このファイルには、オーバークラウドプランのメタデータの定義が含まれます。具体的には、プラン名、使用するメインのテンプレート、オーバークラウドに適用する環境ファイル等です。
capabilities-map.yaml
- このファイルには、オーバークラウドプランの環境ファイルのマッピングが含まれます。
deployment
-
このディレクトリーには、heat テンプレートが含まれます。
overcloud-resource-registry-puppet.j2.yaml
環境ファイルは、このディレクトリーのファイルを使用して、各ノードに Puppet の設定が適用されるようにします。 environments
-
このディレクトリーには、オーバークラウドの作成に使用可能なその他の heat 環境ファイルが含まれます。これらの環境ファイルは、作成された Red Hat OpenStack Platform (RHOSP) 環境の追加の機能を有効にします。たとえば、ディレクトリーには Cinder NetApp のバックエンドストレージを有効にする環境ファイル (
cinder-netapp-config.yaml
) が含まれています。 network
- このディレクトリーには、分離ネットワークおよびポートを作成するための heat テンプレートのセットが含まれます。
puppet
-
このディレクトリーには、Puppet 設定を制御するテンプレートが含まれます。
overcloud-resource-registry-puppet.j2.yaml
環境ファイルは、このディレクトリーのファイルを使用して、各ノードに Puppet の設定が適用されるようにします。 puppet/services
-
このディレクトリーには、全サービス設定用のレガシー heat テンプレートが含まれます。
puppet/services
ディレクトリー内のほとんどのテンプレートが、deployment
ディレクトリーのテンプレートに置き換えられています。 extraconfig
- このディレクトリーには、追加機能を有効にするためのテンプレートが含まれます。
firstboot
-
このディレクトリーには、ノードの初回作成時に director が使用する
first_boot
スクリプトの例が含まれています。
2.4. プランの環境メタデータ
プランの環境メタデータファイルで、オーバークラウドプランのメタデータを定義することができます。director は、オーバークラウドの作成時およびオーバークラウドプランのインポート/エクスポート時にメタデータを適用します。
プランの環境ファイルを使用して、OpenStack Workflow (Mistral) サービスを介して director が実行可能なワークフローを定義します。プランの環境メタデータファイルには、以下のパラメーターが含まれます。
- version
- テンプレートのバージョン
- name
- オーバークラウドプランおよびプランのファイルを保管するのに使用する OpenStack Object Storage (swift) 内のコンテナーの名前
- template
-
オーバークラウドのデプロイメントに使用するコアの親テンプレート。これは、大半の場合は
overcloud.yaml.j2
テンプレートをレンダリングしたバージョンのovercloud.yaml
です。 - environments
-
使用する環境ファイルの一覧を定義します。各環境ファイルの名前および相対位置を
path
サブパラメーターで指定します。 - parameter_defaults
-
オーバークラウドで使用するパラメーターのセット。これは、標準の環境ファイルの
parameter_defaults
セクションと同じように機能します。 - passwords
-
オーバークラウドのパスワードに使用するパラメーターのセット。これは、標準の環境ファイルの
parameter_defaults
セクションと同じように機能します。通常、このセクションは director が無作為に生成したパスワードにより自動的に設定されます。 - workflow_parameters
- このパラメータを使用して、OpenStack Workflow (mistral) の名前空間にパラメーターのセットを指定します。このパラメーターを使用して、特定のオーバークラウドパラメーターを自動生成することができます。
プランの環境ファイルの構文の例を、以下のスニペットに示します。
version: 1.0 name: myovercloud description: 'My Overcloud Plan' template: overcloud.yaml environments: - path: overcloud-resource-registry-puppet.yaml - path: environments/containers-default-parameters.yaml - path: user-environment.yaml parameter_defaults: ControllerCount: 1 ComputeCount: 1 OvercloudComputeFlavor: compute OvercloudControllerFlavor: control workflow_parameters: tripleo.derive_params.v1.derive_parameters: num_phy_cores_per_numa_node_for_pmd: 2
-p
オプションを使用して、openstack overcloud deploy
コマンドにプランの環境メタデータファイルを追加することができます。
(undercloud) $ openstack overcloud deploy --templates \ -p /my-plan-environment.yaml \ [OTHER OPTIONS]
以下のコマンドを使用して、既存のオーバークラウドプラン用のプランメタデータを確認することもできます。
(undercloud) $ openstack object save overcloud plan-environment.yaml --file -
2.5. オーバークラウド作成時の環境ファイルの追加
-e
オプションを使用して、デプロイメントコマンドに環境ファイルを追加します。必要に応じていくつでも環境ファイルを追加することができます。ただし、後で指定する環境ファイルで定義されるパラメーターとリソースが優先されることになるため、環境ファイルの順番は重要です。以下の例では、2 つの環境ファイルに共通のリソース種別 OS::TripleO::NodeExtraConfigPost
と共通のパラメーター TimeZone
が含まれます。
environment-file-1.yaml
resource_registry: OS::TripleO::NodeExtraConfigPost: /home/stack/templates/template-1.yaml parameter_defaults: RabbitFDLimit: 65536 TimeZone: 'Japan'
environment-file-2.yaml
resource_registry: OS::TripleO::NodeExtraConfigPost: /home/stack/templates/template-2.yaml parameter_defaults: TimeZone: 'Hongkong'
デプロイメントコマンドに両方の環境ファイルを含めます。
$ openstack overcloud deploy --templates -e environment-file-1.yaml -e environment-file-2.yaml
openstack overcloud deploy
コマンドは、以下のプロセスを順に実行します。
- コア heat テンプレートコレクションからデフォルト設定を読み込みます。
-
environment-file-1.yaml
の設定を適用します。この設定により、デフォルト設定と共通している設定は上書きされます。 -
environment-file-2.yaml
の設定を適用します。この設定により、デフォルト設定およびenvironment-file-1.yaml
と共通している設定は上書きされます。
これにより、オーバークラウドのデフォルト設定が以下のように変更されます。
-
OS::TripleO::NodeExtraConfigPost
リソースは、environment-file-2.yaml
で定義されるとおりに/home/stack/templates/template-2.yaml
に設定されます。 -
TimeZone
パラメーターは、environment-file-2.yaml
で定義されるとおりにHongkong
に設定されます。 -
RabbitFDLimit
パラメーターは、environment-file-1.yaml
で定義されるとおりに65536
に設定されます。この値は、environment-file-2.yaml
によっては変更されません。
この手法を使用して、複数の環境ファイルの値が競合することなく、オーバークラウドのカスタム設定を定義することができます。
2.6. カスタムのコア heat テンプレートの使用
オーバークラウドの作成時に、director は /usr/share/openstack-tripleo-heat-templates
にある heat テンプレートのコアセットを使用します。このコアテンプレートコレクションをカスタマイズする場合は、以下の git ワークフローを使用してカスタムテンプレートコレクションを管理します。
カスタムテンプレートコレクションの初期化
heat テンプレートコレクションが含まれる初期 git リポジトリーを作成します。
テンプレートコレクションを
/home/stack/templates
ディレクトリーにコピーします。$ cd ~/templates $ cp -r /usr/share/openstack-tripleo-heat-templates .
カスタムテンプレートのディレクトリーに移動して git リポジトリーを初期化します。
$ cd ~/templates/openstack-tripleo-heat-templates $ git init .
Git のユーザー名およびメールアドレスを設定します。
$ git config --global user.name "<USER_NAME>" $ git config --global user.email "<EMAIL_ADDRESS>"
<USER_NAME>
を使用するユーザー名に置き換えます。<EMAIL_ADDRESS>
をご自分のメールアドレスに置き換えます。初期コミットに向けて全テンプレートをステージします。
$ git add *
初期コミットを作成します。
$ git commit -m "Initial creation of custom core heat templates"
これで、最新のコアテンプレートコレクションを格納する初期 master
ブランチが作成されます。このブランチは、カスタムブランチのベースとして使用し、新規テンプレートバージョンをこのブランチにマージします。
カスタムブランチの作成と変更のコミット
カスタムブランチを使用して、コアテンプレートコレクションの変更を保管します。以下の手順に従って、my-customizations
ブランチを作成してカスタマイズを追加します。
my-customizations
ブランチを作成して、そのブランチに切り替えます。$ git checkout -b my-customizations
- カスタムブランチ内のファイルを編集します。
変更を git にステージします。
$ git add [edited files]
カスタムブランチに変更をコミットします。
$ git commit -m "[Commit message for custom changes]"
このコマンドにより、変更がコミットとして my-customizations
ブランチに追加されます。master
ブランチを更新するには、master
から my-customizations
にリベースすると、git はこれらのコミットを更新されたテンプレートに追加します。これは、カスタマイズをトラッキングして、今後テンプレートが更新された際にそれらを再生するのに役立ちます。
カスタムテンプレートコレクションの更新
アンダークラウドを更新する際に、openstack-tripleo-heat-templates
パッケージも更新を受け取る可能性があります。このような場合には、カスタムテンプレートコレクションも更新する必要があります。
openstack-tripleo-heat-templates
パッケージのバージョンを環境変数として保存します。$ export PACKAGE=$(rpm -qv openstack-tripleo-heat-templates)
テンプレートコレクションのディレクトリーに移動して、更新されたテンプレート用に新規ブランチを作成します。
$ cd ~/templates/openstack-tripleo-heat-templates $ git checkout -b $PACKAGE
そのブランチの全ファイルを削除して、新しいバージョンに置き換えます。
$ git rm -rf * $ cp -r /usr/share/openstack-tripleo-heat-templates/* .
初期コミット用にすべてのテンプレートを追加します。
$ git add *
パッケージ更新のコミットを作成します。
$ git commit -m "Updates for $PACKAGE"
このブランチを master にマージします。git 管理システム (例: GitLab) を使用している場合には、管理ワークフローを使用してください。git をローカルで使用している場合には、
master
ブランチに切り替えてからgit merge
コマンドを実行してマージします。$ git checkout master $ git merge $PACKAGE
master
ブランチに最新のコアテンプレートコレクションが含まれるようになりました。これで、my-customization
ブランチを更新されたコレクションからリベースできます。
カスタムブランチのリベース
以下の手順に従って my-customization
ブランチを更新します。
my-customizations
ブランチに切り替えます。$ git checkout my-customizations
このブランチを
master
からリベースします。$ git rebase master
これにより、my-customizations
ブランチが更新され、このブランチに追加されたカスタムコミットが再生されます。
また、リベース中に発生した競合を解決する必要もあります。
どのファイルで競合が発生しているかを確認します。
$ git status
- 特定したテンプレートファイルで競合を解決します。
解決したファイルを追加します。
$ git add [resolved files]
リベースを続行します。
$ git rebase --continue
カスタムテンプレートのデプロイメント
以下の手順に従って、カスタムテンプレートコレクションをデプロイします。
必ず
my-customization
ブランチに切り替えた状態にします。git checkout my-customizations
openstack overcloud deploy
コマンドに--templates
オプションを付けて、ローカルのテンプレートディレクトリーを指定して実行します。$ openstack overcloud deploy --templates /home/stack/templates/openstack-tripleo-heat-templates [OTHER OPTIONS]
ディレクトリーの指定をせずに --templates
オプションを使用すると、director はデフォルトのテンプレートディレクトリー (/usr/share/openstack-tripleo-heat-templates
) を使用します。
Red Hat は、heat テンプレートコレクションを変更する代わりに「4章設定フック」に記載の方法を使用することを推奨します。
2.7. Jinja2 構文のレンダリング
/usr/share/openstack-tripleo-heat-templates
のコア heat テンプレートには、j2.yaml
のファイル拡張子を持つファイルが多数含まれています。これらのファイルには Jinja2 テンプレート構文が含まれ、director はこれらのファイルを .yaml
拡張子を持つ等価な静的 heat テンプレートにレンダリングします。たとえば、メインの overcloud.j2.yaml
ファイルは overcloud.yaml
にレンダリングされます。director はレンダリングされた overcloud.yaml
ファイルを使用します。
Jinja2 タイプの heat テンプレートでは、Jinja2 構文を使用して反復値のパラメーターおよびリソースを作成します。たとえば、overcloud.j2.yaml
ファイルには以下のスニペットが含まれます。
parameters: ... {% for role in roles %} ... {{role.name}}Count: description: Number of {{role.name}} nodes to deploy type: number default: {{role.CountDefault|default(0)}} ... {% endfor %}
director が Jinja2 構文をレンダリングする場合、director は roles_data.yaml
ファイルで定義されるロールを繰り返し処理し、{{role.name}}Count
パラメーターにロール名を代入します。デフォルトの roles_data.yaml
ファイルには 5 つのロールが含まれ、ここでの例からは以下のパラメーターが作成されます。
-
ControllerCount
-
ComputeCount
-
BlockStorageCount
-
ObjectStorageCount
-
CephStorageCount
レンダリング済みバージョンのパラメーターの例を以下に示します。
parameters: ... ControllerCount: description: Number of Controller nodes to deploy type: number default: 1 ...
director がレンダリングするのは、コア heat テンプレートディレククトリー内からの Jinja2 タイプのテンプレートおよび環境ファイルだけです。Jinja2 テンプレートをレンダリングする際の正しい設定方法を、以下のユースケースで説明します。
ユースケース 1: デフォルトのコアテンプレート
テンプレートのディレクトリー: /usr/share/openstack-tripleo-heat-templates/
環境ファイル: /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.j2.yaml
director はデフォルトのコアテンプレートの場所を使用し (--templates
)、network-isolation.j2.yaml
ファイルを network-isolation.yaml
にレンダリングします。openstack overcloud deploy
コマンドの実行時には、-e
オプションを使用してレンダリングした network-isolation.yaml
ファイルの名前を指定します。
$ openstack overcloud deploy --templates \ -e /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.yaml ...
ユースケース 2: カスタムコアテンプレート
テンプレートのディレクトリー: /home/stack/tripleo-heat-templates
環境ファイル: /home/stack/tripleo-heat-templates/environments/network-isolation.j2.yaml
director はカスタムコアテンプレートの場所を使用し (--templates /home/stack/tripleo-heat-templates
)、カスタムコアテンプレート内の network-isolation.j2.yaml
ファイルを network-isolation.yaml
にレンダリングします。openstack overcloud deploy
コマンドの実行時には、-e
オプションを使用してレンダリングした network-isolation.yaml
ファイルの名前を指定します。
$ openstack ovecloud deploy --templates /home/stack/tripleo-heat-templates \ -e /home/stack/tripleo-heat-templates/environments/network-isolation.yaml ...
ユースケース 3: 誤った設定
テンプレートのディレクトリー: /usr/share/openstack-tripleo-heat-templates/
環境ファイル: /home/stack/tripleo-heat-templates/environments/network-isolation.j2.yaml
director はカスタムコアテンプレートの場所を使用します (--templates /home/stack/tripleo-heat-templates
)。しかし、選択した network-isolation.j2.yaml
はカスタムコアテンプレート内に存在しないので、network-isolation.yaml
にはレンダリングされません。この設定ではデプロイメントに失敗します。
Jinja2 構文の静的テンプレートへの処理
process-templates.py
スクリプトを使用して、openstack-tripleo-heat-templates
の Jinja2 構文を静的テンプレートセットにレンダリングします。process-templates.py
スクリプトで openstack-tripleo-heat-templates
コレクションのコピーをレンダリングするには、openstack-tripleo-heat-templates
ディレクトリーに移動します。
$ cd /usr/share/openstack-tripleo-heat-templates
静的コピーを保存するカスタムディレクトリーを定義する -o
オプションを指定して、tools
ディレクトリーにある process-templates.py
スクリプトを実行します。
$ ./tools/process-templates.py -o ~/openstack-tripleo-heat-templates-rendered
これにより、すべての Jinja2 テンプレートがレンタリング済みの YAML バージョンに変換され、結果が ~/openstack-tripleo-heat-templates-rendered
に保存されます。