はじめに
前編では、詳細設計の役割や基本設計との違い、そして詳細設計の中心となる成果物であるパラメータシートについて解説しました。
インフラエンジニアの詳細設計とは？基本設計との違いやパラメータシートの作り方を解説【前編】
パラメータシートは単に設定値をまとめるだけではなく、構築・テスト・保守までを見据えた重要なドキュメントです。
後編では、実際にパラメータシートを作成する際のポイントや、レビューでよく確認される内容について、現場での経験を交えながら解説します。
パラメータシートは単体テストを意識して作成する
詳細設計を始めたばかりの頃は、「構築担当者が設定できれば十分」と考えてしまいがちです。
しかし、実際のプロジェクトでは、構築が完了した後に単体テストを実施します。
単体テストでは、
- 設計書どおりに設定されているか
- 設定漏れがないか
- 想定した値になっているか
を一つひとつ確認します。
つまり、パラメータシートは構築だけではなく、単体テストでも利用されることを意識して作成する必要があります。
そのため、現場では「テスト担当者が確認しやすいパラメータシート」を作成することが重要になります。
ファイルやコマンドの出力順でパラメータを並べる
パラメータシートを作成する際は、設定ファイルやコマンドの出力順に合わせて記載することをおすすめします。
例えば、Linuxの/etc/sysctl.confを設計する場合を考えてみましょう。
もし設計書の並び順が設定ファイルと同じであれば、
- 設計書を開く
sysctl.confを開く- 上から順番に比較する
だけで確認できます。
一方、設計書の並び順がバラバラになっていると、
- 設計書を探す
- 設定ファイルを探す
- また設計書へ戻る
という作業を繰り返すことになり、確認漏れや確認ミスの原因になります。
これはhttpd.confやsshd_configなど、他の設定ファイルでも同じです。
設計書と設定ファイルの並びを合わせることで、レビューや単体テストの効率を大きく向上させることができます。
コマンドで確認する項目は出力順を意識する
設定ファイルだけではなく、コマンドで確認する項目もあります。
例えば、
hostnamectltimedatectlip addrsystemctldf -hfree -h
などのコマンドを利用して設定を確認することがあります。
このような項目についても、コマンドの出力順に合わせて設計書を作成すると、単体テストが非常に行いやすくなります。
例えば、hostnamectlの出力順と同じ順番で、
- ホスト名
- OS
- カーネル
- アーキテクチャ
を並べておけば、画面を見ながら上から順番にチェックできます。
単体テストでは何十台ものサーバを確認することも珍しくありません。
一つひとつの確認時間を短縮するためにも、設計書の見やすさは非常に重要です。
パラメータシート作成時に意識したいポイント
品質の高いパラメータシートを作成するためには、設定値を書く以外にも意識したいポイントがあります。
① 名称を統一する
項目名を補記する場合に同じ内容でも、
- HostName
- ホスト名
- Server Name
など、表記が混在すると分かりづらくなります。
プロジェクト内で表記ルールを決め、すべての設計書で統一しましょう。
② 単位を省略しない
例えばメモリ容量であれば、
- 8
- 16
- 32
ではなく、
- 8GB
- 16GB
- 32GB
と記載します。
ディスク容量やタイムアウト値なども同様です。
単位を省略すると、レビュー時の誤解につながることがあります。
③ 設定理由を残す
すべての項目に理由を書く必要はありませんが、デフォルト値から大きく変更する項目については、変更理由を記載しておくことをおすすめします。
例えば、
| パラメータ | デフォルト値 | 設定値 | 理由 |
|---|---|---|---|
| vm.swappiness | 60 | 10 | スワップ発生を抑制するため |
このように理由を残しておくことで、レビュー担当者も設計意図を理解しやすくなります。
また、将来設定を見直す際にも、「なぜこの値にしたのか」を確認できます。
詳細設計レビューでよく確認されるポイント
詳細設計書が完成したら、レビューを実施します。
レビューでは、設定値そのものだけではなく、設計書としての品質も確認されます。
私が現場でよく見かける確認項目を紹介します。
設定漏れはないか
変更が必要なパラメータが記載されていないケースです。
特に、過去案件の設計書を流用した場合は注意が必要です。
デフォルト値は正しいか
OSやミドルウェアのバージョンによって、デフォルト値は変わることがあります。
例えば、RHEL 7とRHEL 9ではデフォルト設定が異なる項目もあります。
設計書を流用する際は、対象バージョンの公式ドキュメントを確認するようにしましょう。
設定理由は妥当か
「なぜその設定にしたのか」が説明できるかも重要です。
レビュー担当者から理由を聞かれて答えられない場合は、設計を見直す必要があるかもしれません。
基本設計との整合性は取れているか
例えば、
基本設計では「HTTPSを利用する」となっているにもかかわらず、詳細設計でSSL設定が記載されていない場合は問題です。
基本設計で決めた内容が、詳細設計へ正しく反映されているかを確認します。
よくある失敗例
設計初心者が陥りやすい失敗例も紹介します。
変更した項目だけを書く
前編でも紹介したように、変更項目だけでは保守性が低下します。
全項目を管理することを意識しましょう。
並び順がバラバラ
設定ファイルやコマンドの並びを無視して設計すると、レビューやテストに時間がかかります。
設計書は「読む人」のことも考えて作成することが大切です。
コピーした設計書をそのまま使う
過去案件の設計書を流用すること自体は珍しくありません。
しかし、
- バージョン
- ホスト名
- IPアドレス
- パラメータ
が古いまま残っているケースもあります。
流用する場合は、必ず内容を一つひとつ確認しましょう。
まとめ
詳細設計は、基本設計で決めた内容を実際の設定値へ落とし込む工程です。
そして、その中心となる成果物がパラメータシートです。
品質の高いパラメータシートを作成するためには、
- デフォルト値と設定値を記載する
- 全項目を管理する
- ファイルやコマンドの出力順で整理する
- 単体テストを意識して作成する
ことが重要です。
特に、単体テストでどのように確認するかを考えながら設計するという視点は、設計初心者が身に付けておきたい考え方の一つです。
設計書は構築担当者だけが利用するものではありません。
レビュー担当者、テスト担当者、運用担当者など、多くの人が利用するドキュメントです。
「自分が分かればよい設計書」ではなく、「誰が見ても迷わず構築・確認できる設計書」を目指すことが、品質の高い詳細設計につながります。
コメント