Red Hat Training
A Red Hat training course is available for Red Hat OpenStack Platform
第2章 Heat テンプレートの理解
本ガイドのカスタム設定では、Heat テンプレートと環境ファイルを使用して、オーバークラウドの特定の機能を定義します。本項には、Red Hat OpenStack Platform director に関連した Heat テンプレートの構造や形式を理解するための基本的な説明を記載します。
2.1. Heat テンプレート
director は、Heat Orchestration Template (HOT) をオーバークラウドデプロイメントプランのテンプレート形式として使用します。HOT 形式のテンプレートの多くは、YAML 形式で表現されます。テンプレートの目的は、Heat が作成するリソースのコレクションと、リソースの設定が含まれる スタック を定義して作成することです。リソースとは、コンピュートリソース、ネットワーク設定、セキュリティーグループ、スケーリングルール、カスタムリソースなどの OpenStack のオブジェクトを指します。
Heat テンプレートは、3 つの主要なセクションで構成されます。
- parameters
-
prameters は Heat に渡される設定で、値を指定せずにパラメーターのデフォルト値やスタックをカスタマイズする方法を提供します。これらは、テンプレートの
parameters
セクションで定義されます。 - resources
-
resources はスタックの一部として作成/設定する固有のオブジェクトです。OpenStack には全コンポーネントに対応するコアのリソースセットが含まれています。これらの設定は、テンプレートの
resources
セクションで定義されます。 - output
-
output は、スタックの作成後に Heat から渡される値です。これらの値には、Heat API またはクライアントツールを使用してアクセスすることができます。これらは、テンプレートの
output
セクションで定義されます。
以下に、基本的な 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 がテンプレートを処理する際には、テンプレートのスタックとリソーステンプレートの子スタックセットを作成します。これにより、テンプレートで定義したメインのスタックに基づいたスタックの階層が作成されます。以下のコマンドを使用して、スタック階層を表示することができます。
$ heat stack-list --show-nested
2.2. 環境ファイル
環境ファイルとは、Heat テンプレートをカスタマイズする特別な種類のテンプレートです。このファイルは、3 つの主要な部分で構成されます。
- resource registry
-
このセクションでは、他の Heat テンプレートに関連付けられたカスタムのリソース名を定義します。これは実質的に、コアリソースコレクションに存在しないカスタムのリソースを作成する方法を提供します。この設定は、環境ファイルの
resource_registry
セクションで定義されます。 - parameters
-
これらは、最上位のテンプレートのパラメーターに適用する共通の設定です。たとえば、リソースレジストリーマッピングなどのネストされたスタックをデプロイするテンプレートがある場合には、パラメーターは最上位のテンプレートにのみ適用され、ネストされたリソースのテンプレートには適用されません。パラメーターは、環境ファイルの
parameters
セクションで定義されます。 - parameter defaults
-
これらのパラメーターは、すべてのテンプレートのパラメーターのデフォルト値を変更します。たとえば、リソースレジストリーマッピングなどのネストされたスタックをデプロイするテンプレートがある場合には、パラメーターのデフォルト値は、最上位のテンプレートとすべてのネストされたリソースを定義するテンプレートなどすべてのテンプレートに適用されます。パラメーターのデフォルト値は環境ファイルの
parameter_defaults
セクションで定義されます。
オーバークラウドのカスタムの環境ファイルを作成する場合には、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 テンプレートにのみパラメーターを適用します。上記の例では、my_template.yaml
のパラメーターにのみ適用されます。
NetworkName
はメインの Heat テンプレート (上記の例では my_template.yaml
) とメインのテンプレートに関連付けられたテンプレート (上記の例では OS::Nova::Server::MyServer
リソースとその myserver.yaml
テンプレート) の両方に適用されます。
2.3. オーバークラウドのコア Heat テンプレート
director には、オーバークラウドのコア Heat テンプレートコレクションが含まれます。このコレクションは、/usr/share/openstack-tripleo-heat-templates
に保存されています。
このテンプレートコレクションには、多数の Heat テンプレートおよび環境ファイルが含まれますが、注意すべき主要なファイルおよびディレクトリーは以下のとおりです。
overcloud.j2.yaml
- これは、オーバークラウド環境の作成に使用されるメインのテンプレートファイルです。このファイルでは、Jinja2 構文を使用してテンプレートの特定のセクションを反復し、カスタムロールを作成します。Jinja2 形式はオーバークラウドのデプロイメント処理中に YAML にレンダリングされます。
overcloud-resource-registry-puppet.j2.yaml
- これは、オーバークラウド環境の作成に使用する主要な環境ファイルで、オーバークラウドイメージ上に保存される Puppet モジュールの設定セットを提供します。director により各ノードにオーバークラウドのイメージが書き込まれると、Heat は環境ファイルに登録されているリソースを使用して各ノードに Puppet の設定を開始します。このファイルでは、Jinja2 構文を使用してテンプレートの特定のセクションを反復し、カスタムロールを作成します。Jinja2 形式はオーバークラウドのデプロイメント処理中に YAML にレンダリングされます。
roles_data.yaml
- オーバークラウド内のロールを定義して、サービスを各ロールにマッピングするファイル。
network_data.yaml
-
サブネット、割り当てプール、IP ステータスなどのオーバークラウド内のネットワークとそれらのプロパティーを定義するファイル。デフォルトの
network_data
ファイルにはデフォルトのネットワークのみ (External、Internal Api、Storage、Storage Management、Tenant、Management) が含まれます 。カスタムのnetwork_data
ファイルを作成して、openstack overcloud deploy
コマンドに-n
オプションで追加することができます。 plan-environment.yaml
- オーバークラウドプランのメタデータを定義するファイル。これには、プラン名、使用するメインのテンプレート、オーバークラウドに適用する環境ファイルが含まれます。
capabilities-map.yaml
-
オーバークラウドプラン用の環境ファイルのマッピング。director の Web UI で環境ファイルを記述および有効化するには、このファイルを使用します。オーバークラウドプラン内の
environments
ディレクトリーで検出されるカスタムの環境ファイルの中で、capabilities-map.yaml
では定義されていないファイルは、Web UI の 2 デプロイメントの設定の指定 > 全体の設定 の Other サブタブに一覧表示されます。 environments
-
オーバークラウドの作成に使用可能な Heat 環境ファイルが追加で含まれます。これらの環境ファイルは、作成された OpenStack 環境の追加の機能を有効にします。たとえば、ディレクトリーには Cinder NetApp のバックエンドストレージ (
cinder-netapp-config.yaml
) を有効にする環境ファイルが含まれています。capabilities-map.yaml
ファイルでは定義されていない、このディレクトリーで検出される環境ファイルはいずれも、 director の Web UI の 2 デプロイメントの設定の指定 > 全体の設定 の Other サブタブにリストされます。 network
- 分離ネットワークおよびポートを作成しやすくする Heat テンプレートセット
puppet
-
大部分は Puppet を使用した設定によって動作するテンプレート。前述した
overcloud-resource-registry-puppet.j2.yaml
環境ファイルは、このディレクトリーのファイルを使用して、各ノードに Puppet の設定が適用されるようにします。 puppet/services
- コンポーザブルサービスアーキテクチャー内の全サービス用の Heat テンプレートが含まれたディレクトリー。
extraconfig
-
追加の機能を有効化するために使用するテンプレート。たとえば、director が提供する
extraconfig/pre_deploy/rhel-registration
は、ノードの Red Hat Enterprise Linux オペレーティングシステムを Red Hat コンテンツ配信ネットワークまたは Red Hat Satelite サーバーに登録できるようにします。 firstboot
-
ノードを最初に作成する際に director が使用する
first_boot
スクリプトを提供します。
2.4. プランの環境メタデータ
プランの環境メタデータファイルにより、オーバークラウドプランに関するメタデータを定義することができます。この情報は、オーバークラウドプランのインポートとエクスポートに使用されるのに加えて、プランからオーバークラウドを作成する際にも使用されます。
プランの環境ファイルメタデータファイルには、以下のパラメーターが含まれます。
- version
- テンプレートのバージョン
- name
- オーバークラウドプランと、プランファイルの保管に使用する OpenStack Object Storage (swift) 内のコンテナーの名前
- template
-
オーバークラウドのデプロイメントに使用するコアの親テンプレート。これは、大半の場合は
overcloud.yaml
(overcloud.yaml.j2
テンプレートをレンダリングしたバージョン) です。 - 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/docker.yaml - path: environments/docker-ha.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
openstack overcloud deploy
コマンドに -p
オプションを使用して、プランの環境メタデータファイルを指定することができます。以下に例を示します。
(undercloud) $ openstack overcloud deploy --templates \ -p /my-plan-environment.yaml \ [OTHER OPTIONS]
以下のコマンドを使用して、既存のオーバークラウドプラン用のプランメタデータを確認することもできます。
(undercloud) $ openstack object save overcloud plan-environment.yaml --file -
2.5. ケイパビリティーマップ
ケイパビリティーマップは、プラン内の環境ファイルとそれらの依存関係のマッピングを提供します。director の Web UI で環境ファイルを記述および有効化するには、このファイルを使用します。オーバークラウドプランで検出されるカスタムの環境ファイルの中で、capabilities-map.yaml
にリストされていないファイルは、Web UI の 2 デプロイメントの設定の指定 > 全体の設定 の Other サブタブに一覧表示されます。
デフォルトのファイルは、/usr/share/openstack-tripleo-heat-templates/capabilities-map.yaml
にあります。
ケイパビリティーマップの構文の例を以下に示します。
topics: 1 - title: My Parent Section description: This contains a main section for different environment files environment_groups: 2 - name: my-environment-group title: My Environment Group description: A list of environment files grouped together environments: 3 - file: environment_file_1.yaml title: Environment File 1 description: Enables environment file 1 requires: 4 - dependent_environment_file.yaml - file: environment_file_2.yaml title: Environment File 2 description: Enables environment file 2 requires: 5 - dependent_environment_file.yaml - file: dependent_environment_file.yaml title: Dependent Environment File description: Enables the dependent environment file
- 1
topics
パラメーターには、UI のデプロイメント設定内のセクションの一覧が含まれます。各トピックは、環境オプションの単一画面として表示され、複数の環境グループが含まれます。これは、environment_groups
パラメーターで定義することができます。各トピックには、プレーンテキストのtitle
とdescription
を記述することができます。- 2
environment_groups
パラメーターには、UI のデプロイメント設定内の環境ファイルのグループを一覧表示します。たとえば、ストレージトピックでは、Ceph 関係の環境ファイルの環境グループがある可能性があります。各環境グループには、プレーンテキストのtitle
とdescription
を記述することができます。- 3
environments
パラメーターには、環境グループに属する環境ファイルがすべて表示されます。file
パラメーターは、環境ファイルの場所です。各環境エントリーには、プレーンテキストでtitle
とdescription
を記述することができます。- 4 5
requires
パラメーターは、環境ファイルの依存関係の一覧です。この例では、environment_file_1.yaml
とenvironment_file_2.yaml
にはいずれもdependent_environment_file.yaml
を有効化する必要もあります。
Red Hat OpenStack Platform は、このファイルを使用して director UI の機能へのアクセスを追加します。Red Hat OpenStack Platform のバージョンが新しくなると、このファイルは上書きされる可能性があるため、編集しないことを推奨します。
2.6. オーバークラウド作成時の環境ファイルの追加
デプロイメントのコマンド (openstack overcloud deploy
) で -e
オプションを使用して、オーバークラウドをカスタマイズするための環境ファイルを追加します。必要に応じていくつでも環境ファイルを追加することができますが、後で実行される環境ファイルで定義されているパラメーターとリソースが優先されることになるため、環境ファイルの順序は重要です。以下の一覧は、環境ファイルの順序の例です。
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
この例では、両環境ファイルに共通のリソース種別 (OS::TripleO::NodeExtraConfigPost
) と共通のパラメーター (TimeZone
) が含まれています。openstack overcloud deploy
コマンドは、以下のプロセスを順に実行します。
-
--template
オプションで指定したコア 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
に設定されます。 -
environment-file-2.yaml
で指定されている通りに、TimeZone
パラメーターはHongkong
に設定されます。 -
environment-file-1.yaml
で指定されているとおりに、RabbitFDLimit
パラメーターは65536
に設定されます。この値は、environment-file-2.yaml
によっては変更されません。
この設定は、複数の環境ファイルによって競合が発生することなくカスタム設定を定義する手段を提供します。
2.7. カスタムのコア Heat テンプレートの使用
オーバークラウドの作成時に、director は /usr/share/openstack-tripleo-heat-templates
にある Heat テンプレートのコアセットを使用します。このコアテンプレートコレクションをカスタマイズするには、git ワークフローで変更をトラッキングして更新をマージしてください。以下の git プロセスを使用すると、カスタムテンプレートコレクションの管理に役立ちます。
カスタムテンプレートコレクションの初期化
以下の手順に従って、テンプレートコレクションを格納する初期 git リポジトリーを作成します。
テンプレートコレクションを
stack
ユーザーディレクトリーにコピーします。以下の例では、コレクションを~/templates
ディレクトリーにコピーします。$ cd ~/templates $ cp -r /usr/share/openstack-tripleo-heat-templates .
カスタムテンプレートのディレクトリーに移動して git リポジトリーを初期化します。
$ cd openstack-tripleo-heat-templates $ git init .
初期コミットに向けて全テンプレートをステージします。
$ 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 で競合が発生した場合には、以下の手順を実行します。
どのファイルで競合が発生しているかを確認します。
$ 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章設定フック」に記載の方法を使用することを推奨します。