データ活用基盤を作ってみたその４(詳細設計)

## はじめに

こんにちは、NTTデータ先端技術の白木です。
本記事はデータ活用基盤を作ってみた連載記事のその4(詳細設計)です。
本シリーズの取り組みの内容については[その1(構成シナリオ)](https://qiita.com/kamein/private/81df29ef9d32bf0a0810)をご覧ください。
前の記事は、[その3(基本設計)](https://qiita.com/shiraki_ils/items/86c40a8c4676572650ab)からご覧ください。
今回は、詳細設計の考え方・進め方について記載します。

## 目次
- 前提
- 詳細設計の考え方
- 詳細設計で実施したこと
- 詳細設計で注意したこと

## 前提
設計工程の前提については、前記事にて記載しておりますのでそちらをご覧ください。

## 詳細設計の考え方
今回のPJでは、設計工程は基本設計→詳細設計（パラメータ設計）の二段階で進めることとしました。

そのうえで、今回のPJにおける詳細設計は、
「基本設計の内容を実現するために製品・サービスに設定するパラメータを表現するフェーズ」
と定義しました。

加えて、本PJではInfrastructure as Code（以下IaCと記載）として、Terraformを採用する方針としていたこともあり、詳細設計に大きく影響しています。詳細は後述します。

## 詳細設計で実施したこと
今回のPJにおいて、詳細設計における成果物は **IaCのコード（Terraformの.tfファイル）** としました。
これが意味することは以下の二点です。
1. 今回のPJでは「詳細設計書」の成果物を作成しないこと。
2. 今回のPJでは「パラメータシート」の成果物を作成せず、IaCのコードで代替すること。

### 1. 詳細設計書について
システムのインフラ面の設計においては、詳細設計の工程が実質的にパラメータ設計と同一になるケースも多く、その場合詳細設計書の作成工程を省いてパラメータシートのみを成果物とするケースも多いかと思います。
これはPJの規模や特性・メンバーのスキルレベルにもよると思いますので一概には言えない部分ではありますが、今回のPJにおいてはチーム内で議論の上、ドキュメントとしての詳細設計書作成は割愛し、基本設計の次工程はパラメータ設計とする方針としました。

### 2. パラメータシートについて
IaCを採用する場合には、IaCのコード（今回であればTerraformの.tfファイル）がパラメータを記載したドキュメントになるため、パラメータシートに求める情報量を具備した成果物となります。
この点についても、IaCを採用しながらパラメータシートを作成するような進め方もあり得るかと思います。
こちらもPJの規模や特性・メンバーのスキルレベルなどを考慮して判断が必要かと思いますが、今回のPJではIaCのコードをパラメータシートの代わりとすることで、ドキュメントとしてのパラメータシート作成は割愛する方針としました。
今回のPJを通じて感じた、パラメータシートを作成せずにIaCのコードで代用する場合のメリット・デメリットについて以下記載させていただきます。

#### IaCのコードでパラメータシートを代用するメリット
- 二重管理をしないことによる工数の削減

パラメータシートとIaCのコードを両方作成・管理する場合、単純に作成する資料が二つになることによる工数増のほか、パラメータの変更などがあった際には修正箇所が二か所になってしまったり、双方の資料に差分が発生してしまった場合にどちらが正しいのか判断が必要になったりと、工数上の影響が発生します。

- 実際の環境とドキュメントの差分の解消

パラメータシートを手作業で作成する場合には、パラメータシートと実機との差分が発生することも対応する必要があります。
これは、パラメータシートの更新→実機への設定反映 もしくは、実機の設定変更→パラメータシートの更新 のどちらかの対応によって同期をとりますが、この作業は工数への負担及び、ミスの温床になります。
一方でIaCのコードを利用する場合、最新版のIaCのコードを環境に適用することで、IaCのコードと実機の設定値が同じになることが保証できます。
これにより、工数面及び品質面でメリットがあります。

#### IaCのコードでパラメータシートを代用するデメリット
- 技術的ハードルの高さ

IaCという技術自体が初心者には難しい概念であるため、扱うチームメンバーのスキルレベルによっては導入までのハードルの高さが課題になるかと思います。
Terraformを使った構築作業における技術的課題の詳細は後続の記事にて記載予定ですのでこの記事では割愛しますが、特に若手メンバーを中心に学習に苦労していた印象です。

- 視認性の低さ

この点は一つ上の点と被る部分もありますが、IaCのコードの成果物はコードになるため、コードを読み慣れていないメンバーにとっては視認性が低いものとなります。
例えば、TerraformであればインフラはHCL(HashiCorp Configuration Language)というJsonに近い文法の言語で記載されます。
普段からJsonを読み慣れていないようなメンバーは、コードを解読する部分にも負荷が発生してしまいます。
また、ExcelやMarkdownであれば表形式や赤字強調など、人が見やすくするための工夫なども柔軟に対応できるかと思いますが、コードでは難しいため、例えば同じようなリソースをたくさん作成する部分（例：IAM、S3バケット 等）ではコードが縦に伸びて見づらい、というような部分でも視認性には若干のデメリットがあります。
※ちなみに、これらが課題となった場合にはモジュール化などによってコードを構造化し見通しを良くする対応が有効化と思いますので、そちらをご検討ください。

以上がIaCのコードでパラメータシートを代用するメリット・デメリットでした。
端的に言えば、IaC化は技術的な高難易度化と引き換えにQCDのメリットを享受しようというものです。PJやメンバーの状況に応じて、どのような進め方とするべきかご検討いただければと思います。

## 詳細設計で注意したこと
Terraformを利用した作業の技術的な注意点などについては、後続の記事にて別途記載予定ですので割愛し、この記事ではファイル分割の方針についてのみ記載させていただきます。

### IaCコードの分割方針

一般に、詳細設計書（パラメータシート）は構築作業のインプットになることから、目次構成は構築が進めやすいように製品・サービスカットになりやすいと思います。
今回のPJではIaCを活用しましたが、コードがパラメータシートの代わりになっている以上、視認性や管理性の観点から、分割の方針は製品・サービスカットで進めるのが良いと考えました。
※この辺りは、構築するシステムの規模（=コード量）や、ドキュメント管理のルールなどにも依存すると思うので、一概にこの方法が正解であるとは考えていません。
今回試行錯誤をしながら、以下のようなファイルに分割する方針としました。

| ファイル名 | 用途 |
|:-:|:-:|
| backend.tf  | Terraform Backend を定義したファイル |
| provider.tf  | Terraform Provider を定義したファイル  |
| iam-admin.tf  | 主に管理者向けのIAMコンポーネント（例：構築用のユーザー 等）を定義したファイル  |
| iam-analyst.tf  | 主に利用者向けのIAMコンポーネント（例：分析用のユーザー 等）を定義したファイル  |
| iam-securityservice.tf  | 主にセキュリティ系サービスが利用するIAMロール（例：SecurityHub用IAMロール 等）を定義したファイル  |
| iam-service-role.tf  | 主に分析系サービスが利用するIAMロール（例：Glue用IAMロール 等）を定義したファイル  |
| jobs.tf  | 主にジョブ用AWSサービス（例：Glueジョブ 等）を定義したファイル  |
| security.tf  | 主にセキュリティサービス（例：SecurityHub 等）を定義したファイル  |
| storage.tf  |  主にストレージサービス（例：S3バケット 等）を定義したファイル |

詳細については、個々の技術要素についての記事を別途作成予定のため、そちらにてご説明させていただきます。

## 最後に
今回は、詳細設計工程についてご紹介しました。
IaCによるインフラ構築を検討している方に少しでも参考になれば幸いです。
次章は、[その5(試験)]()についてです。
ここまでお読みいただきありがとうございました。