Exastro Playbook Collection 活用事例 (ITA readme)

# 1. はじめに

Exastro IT Automation （以降、ITAと表記）を使用したシステム構築を行う際に Exastro Playbook Collection を使用することで、 Ansible Playbook を一から作成する作業を省くことが可能です。

本記事では、Playbook Collection で公開されている Ansible-Role のうち、以下のロールを使用してみます。

- OS環境構築（Windowsのコンピュータ名変更など）
- IISのインストール

また、ITAの代入値管理機能で重要な役割を持つ ITA Readme についても取り上げます。


# 2. 構成

本記事では以下の構成で作業を行います。

- ITAホストサーバ（CentOS 8.3 + Exastro ITA Server 1.6.2）
- ターゲットサーバ（Windows Server 2016）
- Webブラウザを使用可能なクライアントPC

![compose.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/a4af938a-c9f2-c2b0-5cc6-8679f2a22d08.png)

# 3. ITA readme

## 3.1. ITA readme の役割

ITAに Ansible-Role を登録すると、Ansible-Role に含まれる Playbook から変数を抜き出します。もしロールに defaults/main.yml が存在していれば、この中に記述されている、"VAR_"で始まる変数が自動的に抜き出され、ITA の代入値管理機能において変数名の候補として表示されます。

しかし、defaults/main.yml がないか、または存在している場合でも変数定義が記述されていない（コメントアウト状態も含む）場合は ITA は当該変数を認識できません。そのような場合は、ITA readme を作成しその中で当該変数の定義を記述することで、defaults/main.yml を変更することなしに ITA に認識させることができます。

defaults/main.yml に存在する変数を、ITA readme で上書き定義することもできます。これによって ITA の「代入値自動登録」において ITA readme に記述した型で値を登録することができます。

ITA readme ファイルは代入値管理機能に変数情報を与えるためだけに使用され、ITA readmeに定義した変数および、変数の値は Ansible 実行には影響を与えません。

![ita_readme1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/c00fd5ca-097a-245c-1e1a-b9fb0a8aa715.png)

## 3.2. ITA readme のファイル名

ITA readme のファイル名は以下の命名規則となります。<br>

ita_readme_[ロール名].yml

[ロール名] のディレクトリ階層が深い場合は、ロール名に含まれる / を % に置換する必要があります。

```
例）
   ロール名が "mysql"のときのファイル名： ita_readme_mysql.yml
   ロール名が "mysql/install"のときのファイル名： ita_readme_mysql%install.yml
```

ロールが複数ある場合はロール毎にファイルを分けて定義します。<br>
あるロールについて、対応する ITA readme ファイルがない場合でもエラーにはなりません。

## 3.3. ITA readme の書式

書式はYAML形式で、文字コードは UTF-8（BOMなし）で記述します。<br>

ITA readme に次のように記述すると、"VAR_AAA"という変数が文字列型として定義されます。

```
VAR_AAA: a
```

次の記述はいずれも同様に文字列型として定義されます。
また、"＃"以降はコメントとして無視されます。

```
VAR_AAA: "a"
VAR_BBB: true
VAR_CCC: 0
VAR_DDD:        # 値の記述がない場合も文字列型とみなされる。
```

次の記述は配列型、辞書型の定義例です。<br>辞書型のメンバ変数は"VAR_"で始まっている必要はありません。

```
VAR_BBB: []     # 配列型
VAR_CCC:        # 配列型
  - abc
  - def
VAR_DDD:        # 辞書型
  xxx:          # 変数VAR_DDDのメンバ変数"xxx"として認識されます。
  yyy:
  zzz:
```

defaults/main.yml と ITA readmeとで型の定義が異なっている場合は、ITA readmeの定義が使用されます。


# 4. ロールパッケージの作成

ITA のロールパッケージ管理でアップロードするためのロールパッケージを用意します。基本的にはロールファイルを所定の構成で配置し、zipファイルに固めて作成することができます。

## 4.1. Ansible-Roleのダウンロード

Ansible-Role　は、[Exastro Playbook Collection](https://github.com/exastro-suite/playbook-collection-docs/blob/master/README.ja.md) で公開されています。

本記事では、例として以下のロールをダウンロードして使用します。

| 対象製品 | バージョン | 機能 | 備考 |
| :-- | :-- | :-- | :-- |
| OS | WS2016 | 環境構築 & 設定収集 | 本記事では環境構築用ロールのみ使用します。 |
| IIS | WS2016 | 環境構築 | 本記事ではインストール用ロールのみ使用します。 |

Role List にダウンロード可能なロールの一覧が表示されているので、目的のロールについて「ロールリスト」列のリンクをクリックします。

| ![download1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/8cdce745-21bd-8bb1-33b8-8944845feea6.png) |
|:--|

ロールのリポジトリの URL が表示されますので、赤で囲んでいるURL をコピー & ペーストしてアクセスします（gathering.git リポジトリは、OS-Windows2016.gitリポジトリに含まれる設定収集用ロールの実行時に必要とされる依存ロールのため、今回は不要です）。

| ![download2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/c1495575-c1b6-7e0e-3f49-51240c43d832.png) |
|:--|

本記事で使用するロールのリポジトリは以下となります。
* OS (WS2016) 環境設定<br>https://github.com/exastro-playbook-collection/OS-Windows2016.git
* IIS (WS2016) 環境設定<br>https://github.com/exastro-playbook-collection/IIS_Install.git

リポジトリのサイトでは[Code]のリンクをクリックします。

| ![download3.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/0f83679f-e806-bc70-4e76-0f09f8bc3581.png) |
|:--|

[Download ZIP]をクリックします。

| ![download4.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/5c140ac8-3abf-4411-371f-898a9ba5c33a.png) |
|:--|

この結果、以下の２ファイルが取得できますので、適当な場所に展開しておきます。

* OS-Windows2016-master.zip
* IIS_Install-master.zip


## 4.2. Ansible-Roleの内容確認

まず、OS環境構築用ロールの中身を確認します。このzipファイルには含まれるロールが多数あるため、本記事では「コンピュータ設定」ロールを取り上げます。

**WIN_ComputerSetting（OS環境構築 - コンピュータ設定用ロール）**

| ![win_computersetting1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/e0633ab3-1503-5400-19d2-a182f4963d97.png) |
|:--|

tasks フォルダと同じ階層に defaults フォルダが存在しません。<br>次に、IIS環境構築用ロールの中身を確認します。

**IIS_Install（IIS インストール用ロール）**

| ![iis_install1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/9bdeed44-3b86-a928-6dc5-01b23ed545e4.png) |
|:--|

tasksフォルダと同じ階層にdefaultsフォルダが存在し、その配下の main.yml に次の通り複数の変数定義が記述されています。

```
---

# # 共通変数 # #
VAR_IIS_OS_Version: Windows Server 2016                                         # 管理対象マシンのOSバージョン

# # IISサービスインストールの関連変数 # #
# Windows機能のインストールタイプ
VAR_IIS_INSTALLTYPE: DEFAULT                                                    # windows featureのインストール方法（DEFAULT：デフォルトインストール；CUSTOM：カスタムインストール；NONE：IISサービス起動/停止）
# インストールしたいWindows機能の指定（カスタムインストール時のみ有効）
VAR_IIS_FEATURE_NAME: Web-Server,Web-Mgmt-Console
VAR_IIS_SOURCEPATH: "C:\\Windows\\Temp"                                         # IIS ソースファイルのパス（「.NET Framework 3.5 Features」がインストールする必要の場合指定必須）
VAR_Installer_Name: microsoft-windows-netfx3-ondemand-package.cab               # 「.NET Framework 3.5 Features」のインストーラ物件のファイル名（WinodwsServer2016のインストールCDに「sources\sxs」フォルダの下に格納されている）
VAR_Installer_URL:                                                              # インストールパッケージのファイルのWeb格納URL（この値が設定されない場合、win_copyでファイルを転送する）
VAR_IIS_State: START                                                            # Role実行の最後、IISサービスが起動するか停止するか指定する（START：起動（デフォルト）；STOP：停止）、VAR_IIS_INSTALLTYPE＝"NONE"のみ有効
```

OS環境構築用ロールは defaults/main.yml ファイルが含まれていないため、ITAの代入値管理機能用に ITA readme ファイルの作成が必要となります。IISの環境構築用ロールは defaults/main.yml が存在し、ITAで使用する予定の変数が定義されているため、ITA readme を作成する必要はありません（もしもdefaults/main.ymlが存在していてもITAで扱いたい変数定義がないか、コメントアウトされている場合は ITA readme の作成が必要です）。


## 4.3. ITA readmeの作成

OS環境構築用ロール（コンピュータ設定）用の ITA readme を作成します。

まず、OS環境構築用ロール（コンピュータ設定）のリポジトリにある [README.md](https://github.com/exastro-playbook-collection/OS-Windows2016/blob/master/WIN_ComputerSetting/OS_build/README.md) を参照し、ITA readme に記述が必要な変数を確認します。

| ![win_computersetting2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/36cbdbdc-aa0d-ce23-155c-7d48454c704f.png) |
|:--|

このロールの場合はまず VAR_WIN_ComputerSetting という変数があり、その配下に Description など8個のメンバ変数があることがわかります。これらを ITA readme に書いていきます。<br>

```
---
VAR_WIN_ComputerSetting:
  Description: ""
  Name: ""
  DNSDomainSuffixSearchOrder: ""
  SyncDomainWithMembership: 0
  DomainOrWorkgroup: true
  DomainOrWorkgroupName: ""
  DomainUser: ""
  DomainPassword: ""
```

ITA readme に記述したメンバ変数の値が Ansible に渡されることはないため、変数の型さえ正しければ値は何でも構いません。

後述のロールパッケージ作成時において、roles 配下に OS-Windows2016\WIN_ComputerSetting\OS_build のパスで配置する場合、ロール名は "OS-Windows2016/WIN_ComputerSetting/OS_build" となります。そのためファイル名の規則に従い、 ITA readme のファイル名を以下の名前にします。

`ita_readme_OS-Windows2016%WIN_ComputerSetting%OS_build.yml`


## 4.5. ロールパッケージファイル（zipファイル）の作成

ロールパッケージは基本的に roles フォルダを含むファイル群をzip形式でまとめたものとなります。ITA readme も含める場合は以下の構成例となるようにします。

```
<zipファイル>
├─roles/                     ロールを格納するディレクトリ（存在しない場合はアップロード時にエラーとなる）
│   ├─role1/                   role1のディレクトリ
│   │   :
│   └─role2/                   role2のディレクトリ
│       :
├─ita_readme_role1.yml       role1用のITA readme
└─ita_readme_role2.yml       role2用のITA readme
```

他に hosts や host_varsなどのファイル、ディレクトリが含まれていても問題ありませんが、ITAによって上書きされることに注意してください。

OS環境設定用、および、IIS環境設定用のそれぞれのロールパッケージを作成します。

**WIN_ComputerSetting（OS環境構築 - コンピュータ設定用ロール）**

OS-Windows2016-master.zip から取り出した OS-Windows2016\WIN_ComputerSetting、および、あらかじめ作成しておいたita_readme_OS-Windows2016%WIN_ComputerSetting%OS_build.ymlを以下の階層となるようにコピーし、zipファイルにします。

```
OS_Setting.zip
├─roles/
│   └─OS-Windows2016/
│      └─WIN_ComputerSetting/
│          ├─OS_build/
│          │   ├─README.md
│          │   └─tasks/
│          │       ├─build_Description.yml
│          │       ├─build_DNSDomainSuffixSearchOrder.yml
│          │       ├─build_DomainOrWorkgroup.yml
│          │       ├─build_Name.yml
│          │       ├─build_Registry_present.yml
│          │       ├─build_SyncDomainWithMembership.yml
│          │       └─main.yml
│          └─OS_gathering/
│              ├─README.md
│              ├─defaults/
│              │   └─main.yml
│              ├─files/
│              │   └─extracting.py
│              ├─tasks/
│              │   ├─check.yml
│              │   ├─gathering.yml
│              │   ├─generate.yml
│              │   └─main.yml
│              └─vars/
│                  └─gathering_definition.yml
└─ita_readme_OS-Windows2016%WIN_ComputerSetting%OS_build.yml
```

**IIS_Install（IIS インストール用ロール）**

IIS_Install-master.zip から IIS_Install-master を取り出し、IIS_Install にリネームしたうえで以下の階層となるようにコピーし、zipファイルにします。

```
IIS_Install.zip
└─roles/
    └─IIS_Install/
        ├─LICENSE
        ├─README.md
        ├─README_role.md
        ├─defaults/
        │   └─main.yml
        ├─files/
        │   ├─microsoft-windows-netfx3-ondemand-package.cab
        ├─meta/
        │   └─main.yml
        ├─tasks/
        │   └─main.yml
        └─vars/
            └─gathering_definition.yml
```


# 5. ITAへのロールパッケージの適用

ここから ITA に対する準備を行います。<br>

ITAにロールパッケージを適用し、代入値管理でロールの変数を指定できることを確認します。<br>なお、ITA において以下は設定済であるものとし、本章では[Ansible-LegacyRole]および[Conductor]メニューの操作に絞って手順を記述します。

* [基本コンソール]-[機器一覧]
* [基本コンソール]-[投入オペレーション一覧]
* [管理コンソール]-[メニュー作成]

## 5.1. Movementの作成

メニュー：[Ansible-LegacyRole] - [Movement一覧]

![ita_input_movement1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/bb9619e2-5b83-b741-7efb-2e70a60ea13e.png)

以下の内容でMovementを登録します。

| Movement名 | ホスト指定形式 | WinRM接続 | ヘッダーセクション |
| :-- | :-: | :-: | :-- |
| Windowsセットアップ | IP | ・ | - hosts: all<br>&nbsp;&nbsp;remote_user: "{{ \_\_loginuser\_\_ }}"<br>&nbsp;&nbsp;gather_facts: yes |
| IISインストール | IP | ・ | - hosts: all<br>&nbsp;&nbsp;remote_user: "{{ \_\_loginuser\_\_ }}"<br>&nbsp;&nbsp;gather_facts: yes |

「ヘッダーセクション」は、ロール実行時に"gather_facts: no"で問題ない場合は省略可能です。ロールによっては追記が必要な場合がありますので、使用するロールのREADMEをあらかじめ確認しておきます。


## 5.2. ロールパッケージの登録

「4.5. ロールパッケージファイルの作成」で作成したロールパッケージを登録します。

メニュー：[Ansible-LegacyRole] - [ロールパッケージ管理]

![ita_input_rolepackage1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/3520109b-df17-94b9-f168-cc5d6c2737ef.png)

| ロールパッケージ名 | ロールパッケージファイル(ZIP形式) |
| :-- | :-- |
| OS-Setting | OS_Setting.zip |
| IIS-Install | IIS_Install.zip |


## 5.3. Movementとロールパッケージの関連付け
 
作成したMovementと登録したロールパッケージとを紐づけます。

メニュー：[Ansible-LegacyRole] - [Movement詳細]

![ita_input_movement2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/81cfb8b1-8b63-5db0-cd89-6769acd90df2.png)

| Movement | ロールパッケージ名 | ロール名 | インクルード順序 |
| :-- | :-- | :-- | :-: |
| Windowsセットアップ | OS-Setting | OS-Windows2016/WIN_ComputerSetting/OS_build | 1 |
| IISインストール | IIS-Install | IIS_Install | 2 |


## 5.4. メニュー項目と変数の紐づけ
 
メニュー項目とロールの変数とを紐づけます。<br>
変数は、defaults/main.yml または ITA readme で定義されていたものが選択可能であることを確認します。

メニュー：[Ansible-LegacyRole] - [代入値自動登録設定]

![ita_input_variablemapping1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/d49ce6e6-4ebc-b4b7-2b78-61a08c694b91.png)

| メニュー | 項目 | 登録方式 | Movement | 変数名 | メンバー変数名 | 代入順序 | NULL連携 |
| :-- | :-- | :-: | :-- | :-- | :-- | :-: | :-: |
| コンピュータ設定 | コンピュータ名 | Value型 | Windowsセットアップ | VAR_WIN_ComputerSetting | Name | - | - |
| コンピュータ設定 | 説明 | Value型 | Windowsセットアップ | VAR_WIN_ComputerSetting | Description | - | - |
| コンピュータ設定 | プライマリDNSサフィックス | Value型 | Windowsセットアップ | VAR_WIN_ComputerSetting | DNSDomainSuffixSearchOrder | - | - |
| コンピュータ設定 | ドメイン変更時にDNSサフィックスを変更する | Value型 | Windowsセットアップ | VAR_WIN_ComputerSetting | SyncDomainWithMembership | - | - |
| コンピュータ設定 | 所属するグループ | Value型 | Windowsセットアップ | VAR_WIN_ComputerSetting | DomainOrWorkgroup | - | - |
| コンピュータ設定 | ドメイン名／ワークグループ名 | Value型 | Windowsセットアップ | VAR_WIN_ComputerSetting | DomainOrWorkgroupName | - | - |
| コンピュータ設定 | ユーザー名 | Value型 | Windowsセットアップ | VAR_WIN_ComputerSetting | DomainUser | - | - |
| コンピュータ設定 | パスワード | Value型 | Windowsセットアップ | VAR_WIN_ComputerSetting | DomainPassword | - | - |
| IIS設定 | 管理対象マシンのOSバージョン | Value型 | IISインストール | VAR_IIS_OS_Version | - | - | - |

必要な「メニュー」および「項目」がない場合は、メニューの[メニュー作成]-[メニュー定義/作成]で作成します。


## 5.5. Conductorクラスの作成

複数のMovementを組み合わせて一つの処理にします。

メニュー：[Conductor]-[Conductorクラス編集]

以下のようにMovementを配置し連結します。
本記事では名前を「Webサーバセットアップ」とします。

![conductor1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/61470918-b56c-5a63-f456-f8dec5864363.png)


# 6. パラメータの入力

## 6.1. コンピュータ設定のパラメータ
メニュー：[入力用] - [コンピュータ設定]

![ita_input_computersetting1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/71141b81-a225-ad42-5985-7ba433e01cb7.png)

以下のパラメータを登録します。

- ホスト名 (作業対象ホストを選択)
- コンピュータ名
- プライマリDNSサフィックス
- ドメイン変更時にDNSサフィックスを変更する<br>(0:変更する 1:変更しない)
- 所属するグループ<br>(true:ドメイン false:ワークグループ)
- ドメイン名／ワークグループ名
- ユーザー名
- パスワード


## 6.2. IISインストールのパラメータ

メニュー：[入力用] - [IISインストール]

![ita_input_iissetting1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/2d2c6202-5ae3-40b7-7d3b-9531f424b895.png)

以下のパラメータを登録します。

- 管理対象マシンのOSバージョン<br>現時点での対応OSはWS2016のみのため、空欄とします。（defaults/main.ymlで定義されている既定値の"Windows Server 2016"が指定されます）


# 7. 動作確認

設定したConductorが正常に実行できることを確認します。

メニュー：[Conductor]-[Conductor作業実行]

1. Conductor一覧から、「Webサーバセットアップ」を選択します。
1. オペレーション一覧から、適切なオペレーション（メニューの[基本コンソール]-[投入オペレーション一覧]で登録済みのもの）を選択します。
1. 「実行」ボタンをクリックします。

Conductor作業確認画面に切り替わりますので、完了するまで待ちます。

![conductor2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/b116f652-5854-5932-26c1-447000b8159f.png)

正常に完了すると、以下の通りすべて緑色に変わります。

![conductor3.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1210699/f30b36b6-c061-e17e-1bd5-4c227c46ef4a.png)

設定対象サーバにアクセスし、実際に設定が正しく行われていることを確認します。


# 8. 終わりに

今回は主に、Exastro Playbook Collection を例として、ITAでロール変数を扱えるようにするための ITA readme について紹介しました。<br>ITA readme をうまく活用することで、Exastro Playbook Collectionに限らず、任意のロールを ITA に取り込むことも可能となります。利用可能なロールを増やすことでIacの作成工数を減らし、環境構築の効率を上げて行きましょう。


# 7. 参考サイト

* [Exastro-Suite公式サイト](https://exastro-suite.github.io/docs/index_ja.html)
* [Exastro-ITA 利用手順マニュアル Ansible-driver](https://exastro-suite.github.io/it-automation-docs/asset/Documents_ja/Exastro-ITA_%E5%88%A9%E7%94%A8%E6%89%8B%E9%A0%86%E3%83%9E%E3%83%8B%E3%83%A5%E3%82%A2%E3%83%AB_Ansible-driver.pdf)
* [Exastro Playbook Collection](https://github.com/exastro-suite/playbook-collection-docs/blob/master/README.ja.md)
* [Exastro IT Automationインストール(v1.5.0)](https://qiita.com/standsetx/items/c0e4ed7c6a2c34b2f068)
* [Exastro IT Automationを実際に動かしてみた(クイックスタート)](https://qiita.com/standsetx/items/7a96f2286b6d1f3a3524)
* [Exastro IT Automation ver1.5.0のキホンの"キ"](https://qiita.com/wakky0328/items/cf29c22cbf7cb42d462b)
* [Exastro IT Automationの３つのAnsibleモードを使ってみた](https://qiita.com/standsetx/items/6efb0a6bef28c60bc883)
* [Exastro Playbook Collectionを使ってみた
](https://qiita.com/tak_paddy/items/3daa241f8b4b621ea32f)