Quden Dev Doc

Appearance

ADR-005: Terraform採用（Infrastructure as Code） ​

ステータス ​

採用済み

意思決定者 ​

  • 太田裕貴（CTO）
  • インフラチーム

決定日 ​

2021年頃（プロジェクト初期）

背景（Context） ​

QudenはAWS上で動作するSaaSであり、以下のインフラリソースを管理する必要があります：

  • ECS（Elastic Container Service）でのコンテナ実行
  • RDS（MongoDB Atlas）、S3、CloudFront、Lambda等の各種AWSサービス
  • VPC、セキュリティグループ等のネットワーク設定

現状の課題 ​

  • AWSコンソールでの手動設定は、ヒューマンエラーのリスクが高い
  • インフラの変更履歴が不明瞭で、誰がいつ何を変更したのかわからない
  • 環境（開発、ステージング、本番）ごとにインフラを構築するのが手間
  • チームメンバー間でインフラ知識が共有されない
  • インフラの現状把握が困難

解決したいこと ​

  • インフラのコード化（Infrastructure as Code）
  • 変更履歴の記録（Gitでのバージョン管理）
  • 環境ごとのインフラ構築の自動化
  • インフラ構成の可視化・ドキュメント化
  • チーム全体でのインフラ知識の共有

要件（Requirements） ​

機能要件 ​

  • AWSリソースの定義・構築・変更が可能
  • 環境（dev、staging、production）ごとのインフラ管理
  • インフラの差分確認（変更前のプレビュー）
  • 複数メンバーでの同時作業が可能

非機能要件 ​

  • 再現性: 同じコードから同じインフラが構築できる
  • 可視性: インフラ構成がコードで可視化されている
  • 保守性: インフラの変更が安全に行える
  • 学習コスト: 許容範囲内

制約条件 ​

  • 技術的制約: AWSサービスを網羅的にサポートしている
  • ビジネス的制約: 無料または低コストで利用可能
  • 時間的制約: 早期のMVPリリースに対応可能

検討した選択肢 ​

選択肢1: AWSコンソール（手動設定） ​

概要 ​

AWSマネジメントコンソールでリソースを手動作成・設定。

メリット ​

  • 学習コストがゼロ（GUIで直感的）
  • 初期セットアップが高速

デメリット ​

  • ヒューマンエラーのリスクが高い
  • 変更履歴が残らない
  • 環境の複製が困難
  • チーム間での知識共有が難しい
  • インフラの現状把握が困難

実装コスト ​

  • 初期実装: 最低
  • 学習コスト: ゼロ
  • 保守コスト: 極めて高い

選択肢2: AWS CloudFormation ​

概要 ​

AWSが提供するIaCツール。YAML/JSONでAWSリソースを定義。

メリット ​

  • AWS公式ツールで、AWS統合が完璧
  • AWS CloudFormation Stackでリソースのライフサイクル管理
  • 無料で利用可能

デメリット ​

  • YAML/JSONの記述が冗長で可読性が低い
  • AWSのみに特化（他のクラウドに移行できない）
  • エラーメッセージが不親切
  • ステート管理が複雑

実装コスト ​

  • 初期実装: 中
  • 学習コスト: 中
  • 保守コスト: 中

選択肢3: Terraform（HashiCorp製） ​

概要 ​

HashiCorp製のオープンソースIaCツール。HCL（HashiCorp Configuration Language）でインフラを定義。

メリット ​

  • HCLの可読性: YAML/JSONより読みやすく、書きやすい
  • マルチクラウド対応: AWS、GCP、Azureすべてに対応
  • 強力なモジュールシステム: 再利用可能なモジュールで効率化
  • 豊富なエコシステム: Terraform Registry でモジュールが充実
  • 差分確認: terraform plan で変更内容を事前確認
  • ステート管理: tfstate ファイルで現在のインフラ状態を管理

デメリット ​

  • 学習コストが若干高い
  • ステートファイル（tfstate）の管理が必要
  • AWS固有の最新機能への対応が若干遅い場合がある

実装コスト ​

  • 初期実装: 中
  • 学習コスト: 中
  • 保守コスト: 低（可読性・保守性が高い）

決定（Decision） ​

選択した技術: Terraform

選択理由 ​

  1. 要件との適合性

    • HCLの可読性により、インフラの可視化・ドキュメント化を実現
    • terraform plan により、変更前のプレビューが可能で安全性が高い
    • モジュールシステムにより、環境（dev、staging、prod）ごとのインフラ構築が効率化
    • tfstate ファイルにより、インフラの現状把握が容易

  2. 技術的妥当性

    • AWSリソースを網羅的にサポート
    • Terraform Registry により、ベストプラクティスを活用可能
    • GitHubでのバージョン管理により、変更履歴が明確
    • マルチクラウド対応により、将来的な選択肢が広がる

  3. コスト対効果

    • オープンソースで無料
    • 学習コストは若干高いが、長期的な保守コスト削減効果が大きい
    • 公式ドキュメントやコミュニティリソースが充実

  4. 将来性

    • HashiCorpが積極的に開発しており、将来性が高い
    • 業界標準のIaCツールとして広く採用されている

実装方針 ​

  1. Gitリポジトリでの管理

    • toruca-infra リポジトリでTerraformコードを管理
    • 環境ごとにディレクトリを分離（environments/dev, environments/staging, environments/prod）

  2. モジュール化

    • 共通のリソース定義をモジュール化（modules/ecs, modules/vpc等）
    • 環境ごとに変数（variables）を使い分け

  3. ステートファイルの管理

    • S3バックエンドでtfstateファイルを管理
    • DynamoDBでステートロック（同時編集防止）

  4. CI/CDパイプライン

    • GitHub Actionsで terraform plan を自動実行
    • PRマージ時に terraform apply を実行

受け入れたトレードオフ ​

トレードオフ1: 学習コスト ​

  • 影響: HCLとTerraformの概念を学習する必要がある
  • 受け入れ理由: 公式ドキュメント・学習リソースが充実しており、学習コストを上回る長期的なメリットがある
  • 軽減策: チーム内での勉強会、Terraform Registryのモジュール活用

トレードオフ2: ステートファイル管理の複雑さ ​

  • 影響: tfstateファイルの管理が必要
  • 受け入れ理由: S3バックエンド+ DynamoDBによるステートロックで安全に管理可能
  • 軽減策: Terraform Cloud（将来的な選択肢）

トレードオフ3: AWS最新機能への対応遅延 ​

  • 影響: AWS CloudFormationと比べて、最新機能への対応が若干遅い場合がある
  • 受け入れ理由: 多くの場合、数週間〜1ヶ月程度で対応されるため、問題にならない
  • 軽減策: 必要に応じて、AWSコンソールで一時的に設定し、後でTerraformに移行

結果（振り返り） ​

うまくいったこと（Pros） ​

  • インフラの可視化: HCLにより、インフラ構成が明確になった
  • 変更の安全性: terraform plan により、変更前に影響範囲を確認できた
  • 環境構築の効率化: モジュール化により、dev/staging/prod環境を効率的に構築できた
  • 変更履歴の記録: Gitにより、誰がいつ何を変更したのかが明確になった

うまくいかなかったこと（Cons） ​

  • 学習曲線: 新規メンバーがTerraformに慣れるのに時間がかかった
  • ステートファイルの競合: 複数メンバーが同時に作業する際、ステートロックの理解が必要だった
  • 一部リソースの手動設定: AWS最新機能を使う際、一時的に手動設定が必要な場合があった

学び ​

  • モジュール化の重要性: 共通リソースをモジュール化することで、保守性が大幅に向上
  • terraform plan の活用: 変更前のプレビューにより、ヒューマンエラーを防止できた
  • ドキュメントとしてのコード: HCLコード自体がインフラのドキュメントとして機能した

今後の改善点 ​

  • Terraform Cloud の検討: ステート管理・チームコラボレーションの改善
  • モジュールの整理: 共通モジュールをさらに整理・最適化
  • CI/CDパイプラインの強化: terraform apply の自動化をさらに安全に

参考リンク ​

関連ドキュメント ​