Infrastructure as Code (IaC) 実装ガイド

[!NOTE] 最新の実装状況は機能実装ステータス (Remaining Functionality) を参照してください。

実装ノート（アーティファクト）: トレーニングスクリプトが出力する artifact_manifest.json と推奨CLIフラグについては docs/implementation/ARTIFACT_MANIFESTS.md を参照してください。

実装日: 2025年12月20日 バージョン: v0.1.0 著者: 青木雅弘

概要

EvoSpikeNetの環境管理をInfrastructure as Code (IaC)化し、環境再現性100%を実現しました。Terraform、Ansible、Kubernetes、Docker Composeを統合した包括的なIaCシステムを実装しています。

実装内容

1. Terraform統合

1.1 主要ファイル

terraform/main.tf: メイン設定ファイル
Dockerプロバイダー設定
ネットワーク、ボリューム、コンテナ管理
環境変数の自動生成
ヘルスチェックスクリプト生成
terraform/terraform.tfvars: 環境別変数
開発環境（CPU、ポート8000/8050）
ステージング環境（GPU、ポート8100/8150）
本番環境（GPU、ポート8200/8250）
terraform/templates/: テンプレートファイル
env.tpl: 環境変数テンプレート
docker-compose-override.tpl: Docker Composeオーバーライド
health_check.tpl: ヘルスチェックスクリプト

1.2 使用方法

# Terraformの初期化
cd terraform
terraform init

# 実行計画の確認
terraform plan

# 環境のデプロイ（dev）
terraform apply -var-file=terraform.tfvars

# 環境の削除
terraform destroy

1.3 変数のカスタマイズ

# terraform.tfvars
environment            = "dev"
device                 = "cpu"
enable_gpu             = false
api_port               = 8000
frontend_port          = 8050
postgres_password      = "secure_password"
api_keys               = "key1,key2,key3"

2. Ansible統合

2.1 主要ファイル

ansible/playbook.yml: メインプレイブック
システム依存関係のインストール
Docker、Docker Compose、Terraformのセットアップ
プロジェクトのクローンと設定
Python環境のセットアップ
データディレクトリの作成
ansible/inventory.ini: インベントリ定義
ローカル環境
開発サーバー
ステージングサーバー
本番サーバー
ansible/ansible.cfg: Ansible設定

2.2 使用方法

# ローカル環境のセットアップ
cd ansible
ansible-playbook -i inventory.ini playbook.yml --limit local

# リモートサーバーのセットアップ
ansible-playbook -i inventory.ini playbook.yml --limit development

# 本番環境のセットアップ（要注意！）
ansible-playbook -i inventory.ini playbook.yml --limit production

2.3 インベントリのカスタマイズ

[development]
dev-server ansible_host=YOUR_IP ansible_user=YOUR_USER

[production]
prod-server-1 ansible_host=YOUR_IP ansible_user=YOUR_USER
prod-server-2 ansible_host=YOUR_IP ansible_user=YOUR_USER

3. Kubernetes統合

3.1 主要コンポーネント

k8s/deployment.yamlに定義:

Namespace: 専用のevospikenetネームスペース
ConfigMap: 環境変数の設定
Secret: 機密データの管理
PostgreSQL StatefulSet: データベースの永続化
API Deployment: 3レプリカ、オートスケーリング対応
Frontend Deployment: 2レプリカ
Services: 内部/外部通信
HorizontalPodAutoscaler: CPU/メモリベースのオートスケーリング
Ingress: 外部アクセス制御

3.2 使用方法

# Kubernetesへのデプロイ
kubectl apply -f k8s/deployment.yaml

# ステータス確認
kubectl get all -n evospikenet

# ログ確認
kubectl logs -n evospikenet -l app=api

# スケーリング
kubectl scale deployment api -n evospikenet --replicas=5

# 削除
kubectl delete namespace evospikenet

3.3 オートスケーリング設定

# HPA設定例
minReplicas: 3
maxReplicas: 10
metrics:
  - CPU: 70%
  - Memory: 80%

4. 環境セットアップスクリプト

4.1 `scripts/setup_environment.sh`

包括的な環境セットアップと検証を行うスクリプト。

機能: - 依存関係チェック（Python、Docker、Gitなど） - Pythonバージョン検証（≥3.9） - 必要ファイルの存在確認 - ディスク容量チェック（≥10GB） - 仮想環境の作成と依存関係インストール - .envファイルの生成 - pre-commitフックのセットアップ - Dockerネットワークの作成 - 環境レポートの生成

4.2 使用方法

# フルセットアップ（対話式）
./scripts/setup_environment.sh dev

# 検証のみ
./scripts/setup_environment.sh dev true

# ステージング環境
./scripts/setup_environment.sh staging

4.3 検証項目

✅ Python ≥3.9 ✅ Dockerデーモン起動中 ✅ Docker Compose利用可能 ✅ Gitインストール済み ✅ 必要ファイル存在 ✅ 十分なディスク容量（≥10GB） ✅ 必要なポート利用可能

5. Makefile統合

5.1 IaC関連コマンド

# 環境セットアップ
make env-setup

# 検証のみ
make env-validate

# Terraform操作
make terraform-init      # 初期化
make terraform-plan      # 実行計画表示
make terraform-apply     # 適用
make terraform-destroy   # 破棄

# Ansibleセットアップ
make ansible-setup

# Kubernetesデプロイ
make k8s-deploy

# Docker操作
make docker-build        # イメージビルド
make docker-up           # サービス起動
make docker-down         # サービス停止
make docker-logs         # ログ表示

# ヘルスチェック
make health-check

6. 100%再現性の実現

6.1 再現性100%を支える要素

バージョン固定:
Pythonパッケージ: requirements.txt
Dockerイメージ: 明示的なタグ指定
Terraformプロバイダー: バージョン制約
システムパッケージ: Ansible管理
設定の一元管理:
Terraform: インフラ設定
Ansible: システム設定
Docker Compose: サービス設定
ConfigMap/Secret: アプリケーション設定
自動化:
環境検証スクリプト
セットアップスクリプト
ヘルスチェック
CI/CD統合
ドキュメント化:
自己文書化されたIaC設定
テンプレートのコメント
詳細なREADME

6.2 環境タイプ

環境	用途	GPU	APIポート	フロントエンドポート
開発	開発	CPU	8000	8050
ステージング	検証	GPU	8100	8150
本番	本番運用	GPU	8200	8250

7. デプロイフロー

7.1 新規環境構築

# 1. リポジトリクローン
git clone https://github.com/your-org/EvoSpikeNet.git
cd EvoSpikeNet

# 2. 環境検証
make env-validate

# 3. 環境セットアップ
make env-setup

# 4. Terraform初期化
make terraform-init

# 5. Terraform適用
make terraform-apply

# 6. サービス起動
make docker-up

# 7. ヘルスチェック
make health-check

7.2 既存環境更新

# 1. コード更新
git pull

# 2. 依存関係更新
pip install -r requirements.txt

# 3. インフラ更新
make terraform-plan
make terraform-apply

# 4. サービス再起動
make docker-down
make docker-up

# 5. ヘルスチェック
make health-check

8. トラブルシューティング

問題: Terraform applyが失敗

原因: Dockerネットワークの競合

解決策:

# 既存ネットワークの削除
docker network rm evospikenet_dev_network

# Terraformの再適用
make terraform-apply

問題: ポート競合

原因: ポートが既に使用中

解決策:

# terraform.tfvarsでポート変更
api_port = 8001
frontend_port = 8051

問題: Python依存関係エラー

原因: 仮想環境の不整合

解決策:

# 仮想環境の再作成
rm -rf venv
make env-setup

9. セキュリティ考慮事項

9.1 機密データ管理

# .envファイルをGit除外
echo ".env*" >> .gitignore

# Terraformステートも除外
echo "*.tfstate*" >> .gitignore

# シークレットの暗号化（本番）
ansible-vault encrypt ansible/secrets.yml

9.2 アクセス制御

# Kubernetes Secretで管理
apiVersion: v1
kind: Secret
metadata:
  name: evospikenet-secrets
type: Opaque
stringData:
  EVOSPIKENET_API_KEYS: "encrypted_keys"

10. CI/CD統合

10.1 GitHub Actions例

name: Deploy Infrastructure

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2

      - name: Terraform Init
        run: cd terraform && terraform init

      - name: Terraform Plan
        run: cd terraform && terraform plan

      - name: Terraform Apply
        run: cd terraform && terraform apply -auto-approve

11. メトリクスとモニタリング

11.1 環境ヘルスメトリクス

API応答時間
サービス起動時間
リソース使用率
エラー率
デプロイ成功率

11.2 ヘルスチェック項目

✅ APIヘルス (http://localhost:8000/api/health) ✅ フロントエンドヘルス (http://localhost:8050/) ✅ PostgreSQL接続 ✅ Milvus接続 ✅ Elasticsearch接続 ✅ Zenoh Router接続

まとめ

IaC実装により、EvoSpikeNetは以下を達成しました:

✅ 環境再現性100%: どの環境でも同じ構成を再現可能
✅ 自動化: ワンコマンドでセットアップと検証
✅ マルチ環境対応: Dev/Staging/Productionの明確な分離
✅ スケーラビリティ: Kubernetes対応で大規模展開可能
✅ セキュリティ: 機密データの適切な管理
✅ ドキュメント化: 自己文書化されたIaC設定
✅ CI/CD対応: 自動デプロイ統合準備完了
✅ モニタリング統合: ヘルスチェックとメトリクス収集

これにより、開発者は環境セットアップに煩わされることなく、機能開発に集中できます。

Infrastructure as Code (IaC) 実装ガイド

概要

実装内容

1. Terraform統合

1.1 主要ファイル

1.2 使用方法

1.3 変数のカスタマイズ

2. Ansible統合

2.1 主要ファイル

2.2 使用方法

2.3 インベントリのカスタマイズ

3. Kubernetes統合

3.1 主要コンポーネント

3.2 使用方法

3.3 オートスケーリング設定

4. 環境セットアップスクリプト

4.1 scripts/setup_environment.sh

4.2 使用方法

4.3 検証項目

5. Makefile統合

5.1 IaC関連コマンド

6. 100%再現性の実現

6.1 再現性100%を支える要素

6.2 環境タイプ

7. デプロイフロー

7.1 新規環境構築

7.2 既存環境更新

8. トラブルシューティング

問題: Terraform applyが失敗

問題: ポート競合

問題: Python依存関係エラー

9. セキュリティ考慮事項

9.1 機密データ管理

9.2 アクセス制御

10. CI/CD統合

10.1 GitHub Actions例

11. メトリクスとモニタリング

11.1 環境ヘルスメトリクス

11.2 ヘルスチェック項目

まとめ

4.1 `scripts/setup_environment.sh`