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 パラメーターで定義することができます。各トピックには、プレーンテキストの titledescription を記述することができます。
2
environment_groups パラメーターには、UI のデプロイメント設定内の環境ファイルのグループを一覧表示します。たとえば、ストレージトピックでは、Ceph 関係の環境ファイルの環境グループがある可能性があります。各環境グループには、プレーンテキストの titledescription を記述することができます。
3
environments パラメーターには、環境グループに属する環境ファイルがすべて表示されます。file パラメーターは、環境ファイルの場所です。各環境エントリーには、プレーンテキストで titledescription を記述することができます。
4 5
requires パラメーターは、環境ファイルの依存関係の一覧です。この例では、environment_file_1.yamlenvironment_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 コマンドは、以下のプロセスを順に実行します。

  1. --template オプションで指定したコア Heat テンプレートからデフォルト設定を読み込みます。
  2. environment-file-1.yaml の設定を適用します。この設定により、デフォルト設定と共通している設定は上書きされます。
  3. 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 リポジトリーを作成します。

  1. テンプレートコレクションを stack ユーザーディレクトリーにコピーします。以下の例では、コレクションを ~/templates ディレクトリーにコピーします。

    $ cd ~/templates
    $ cp -r /usr/share/openstack-tripleo-heat-templates .
  2. カスタムテンプレートのディレクトリーに移動して git リポジトリーを初期化します。

    $ cd openstack-tripleo-heat-templates
    $ git init .
  3. 初期コミットに向けて全テンプレートをステージします。

    $ git add *
  4. 初期コミットを作成します。

    $ git commit -m "Initial creation of custom core heat templates"

最新のコアテンプレートコレクションを格納する初期 master ブランチを作成します。このブランチは、カスタムブランチのベースとして使用し、新規テンプレートバージョンをこのブランチにマージします。

カスタムブランチの作成と変更のコミット

カスタムブランチを使用して、コアテンプレートコレクションの変更を保管します。以下の手順に従って my-customizations ブランチを作成し、カスタマイズを追加します。

  1. my-customizations ブランチを作成して、そのブランチに切り替えます。

    $ git checkout -b my-customizations
  2. カスタムブランチ内のファイルを編集します。
  3. 変更を git にステージします。

    $ git add [edited files]
  4. カスタムブランチに変更をコミットします。

    $ git commit -m "[Commit message for custom changes]"

このコマンドにより、変更がコミットとして my-customizations ブランチに追加されます。master ブランチを更新するには、master から my-customizations にリベースすると、git はこれらのコミットを更新されたテンプレートに追加します。これは、カスタマイズをトラッキングして、今後テンプレートが更新された際にそれらを再生するのに役立ちます。

カスタムテンプレートコレクションの更新

アンダークラウドの更新時には、openstack-tripleo-heat-templates パッケージも更新される可能性があります。このような場合には、以下の手順に従ってカスタムテンプレートコレクションを更新してください。

  1. openstack-tripleo-heat-templates パッケージのバージョンを環境変数として保存します。

    $ export PACKAGE=$(rpm -qv openstack-tripleo-heat-templates)
  2. テンプレートコレクションのディレクトリーに移動して、更新されたテンプレート用に新規ブランチを作成します。

    $ cd ~/templates/openstack-tripleo-heat-templates
    $ git checkout -b $PACKAGE
  3. そのブランチの全ファイルを削除して、新しいバージョンに置き換えます。

    $ git rm -rf *
    $ cp -r /usr/share/openstack-tripleo-heat-templates/* .
  4. 初期コミットに全テンプレートを追加します。

    $ git add *
  5. パッケージ更新のコミットを作成します。

    $ git commit -m "Updates for $PACKAGE"
  6. このブランチを master にマージします。git 管理システム (例: GitLab) を使用している場合には、管理ワークフローを使用してください。git をローカルで使用している場合には、master ブランチに切り替えてから git merge コマンドを実行してマージします

    $ git checkout master
    $ git merge $PACKAGE

master ブランチに最新のコアテンプレートコレクションが含まれるようになりました。これで、my-customization ブランチを更新されたコレクションからリベースできます。

カスタムブランチのリベース

以下の手順に従って my-customization ブランチを更新します。

  1. my-customizations ブランチに切り替えます。

    $ git checkout my-customizations
  2. このブランチを master からリベースします。

    $ git rebase master

これにより、my-customizations ブランチが更新され、このブランチに追加されたカスタムコミットが再生されます。

リベース中に git で競合が発生した場合には、以下の手順を実行します。

  1. どのファイルで競合が発生しているかを確認します。

    $ git status
  2. 特定したテンプレートファイルで競合を解決します。
  3. 解決したファイルを追加します。

    $ git add [resolved files]
  4. リベースを続行します。

    $ git rebase --continue

カスタムテンプレートのデプロイメント

以下の手順に従って、カスタムテンプレートコレクションをデプロイします。

  1. my-customization ブランチに切り替わっていることを確認します。

    git checkout my-customizations
  2. 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章設定フック」に記載の方法を使用することを推奨します。