【AI×GitOps】Docker Composeから始めるRaspberry Pi 5 Kubernetesクラスタへの自動デプロイ設計

現在構築を進めている動画管理システム開発において、いきなりKubernetes（K8s）に展開するのではなく、Docker Composeを中間地点に挟んで段階的にK8s＋Argo CD（GitOps）へ移行するアーキテクチャ設計をまとめました。

Bionic（AIアシスタント）とGemini自動レビューを組み込み
「AIにコードを書かせ、レビューさせ、GitOpsで実機クラスタへ反映する」パイプラインの全体像です。

1. 全体開発ロードマップ

堅牢なシステムを築くため、ローカル開発環境から本番K8sクラスタまで
以下の4段階ステップで進めます。

Bionic（AI実装）
  ↓
ローカルAI / クラウドAI
  ↓
GitHub（Topic Branch / Gemini自動レビュー）
  ↓
① Docker Compose（ローカル開発・動作検証）
  ↓
② サービス分離・コンテナ最適化
  ↓
③ Kubernetes化（マニフェスト定義）
  ↓
④ Raspberry Pi 5 クラスタデプロイ（Argo CD）

2. フェーズ1：Docker Compose によるベース構築

まずはローカルPC上の Docker Compose で基本の構成を立ち上げます。

サービス構成案 (docker-compose.yml)

動画処理・検索機能を踏まえ、以下の4コンテナ構成からスタートします。

                  ┌───────┐
                  │  Web                │
                  └───┬───┘
                                │
                  ┌───▼───┐
                  │  API                 │
                  └───┬───┘
              ┌────┴────┐
              ▼                                 ▼
          PostgreSQL                  Worker
                               │
                            ffmpeg

K8s化を見据えた Compose 設計のポイント

Compose 段階から以下のルールを徹底しておくことで、スムーズに K8s マニフェストへ移行できます。

• 責務の分離: 1コンテナ1プロセスを徹底する。

• 環境変数の切り出し: 設定値や秘密情報は .env や環境変数に逃がす。

• 永続化データの分離: DBや動画ストレージはコンテナ外部（Volume）へ切り離す。

• パスの動的化: ファイルパスをコード内にハードコードしない。

• サービス名による通信: DB等の接続先指定は localhost ではなく Compose のサービス名を使用する。

• ステートレス設計: アプリケーション本体は極力状態を持たせない。

• 可視性と監視: ログはすべて stdout / stderr へ出し、ヘルスチェックエンドポイントを用意する。

3. フェーズ2：Kubernetes マニフェストへの置き換え

Compose で動作確認が取れたコンテナ群を、K8s のリソースオブジェクトへ落とし込みます。

Docker Compose	Kubernetes Resource
web / api / worker	Deployment / Job
ポート公開 / 内部通信	Service / Ingress
.env / 接続情報	ConfigMap / Secret
Volume 永続化	PersistentVolumeClaim (PVC)

4. 最終形：AI ＋ Argo CD による GitOps パイプライン

最終的なプロダクション環境（Raspberry Pi 5 クラスタ）では、Argo CD を投入して「GitHubの状態を唯一の正（Single Source of Truth）」とする GitOps を運用します。

全体アーキテクチャ図

                                           Bionic
                                               │
        ┌──────────┴──────────┐
        │                                                                           │
    ローカルAI                                                         クラウドAI
        │                                                                           │
        └──────────┬──────────┘
                                                ▼
                                        topic branch
                                               │
                                           commit
                                              │
                                              ▼
                                           GitHub
                                              │
                                       Gemini Review
                                              │
                                              ▼
                                           merge
                                              │
                                              ▼
          ┌─────────────────┐
          │    GitHub                                              │
          │  manifests                                            │
          └────────┬────────┘
                                          │
                        Argo CD (Pull型同期)
                                         │
                                          ▼
        ┌─────────────────────┐
        │ Raspberry Pi K8s                                               │
        │                                                                            │
        │ Web / API                                                           │
        │ Worker (ffmpeg)                                                 │
        │ PostgreSQL / Search                                         │
        └─────────────────────┘

リポジトリ構成案

アプリコードと K8s マニフェストを同一または適切なディレクトリ階層で管理します。

## Bash ####

project-root/
├── app/                  # アプリケーションソース
│   ├── src/
│   └── Dockerfile
└── k8s/                  # Kubernetes 定義
    ├── namespace.yaml
    ├── deployment.yaml
    ├── service.yaml
    ├── ingress.yaml
    └── pvc.yaml

実機クラスタ基盤 (Raspberry Pi 5)

既に構築・稼働している以下のネットワーク・ストレージ基盤上に展開します。

• CNI: Cilium

• Load Balancer: MetalLB

• Storage: local-path-storage

• CD Engine: Argo CD

まとめ：AI ＋ GitOps 開発工場の確立

この構成が完成すると、日々の開発フローは以下のようになります。

1. Bionic に機能追加や修正を依頼する。

2. AIがトピックブランチを作成し、コードを実装して GitHub へ Push。

3. Gemini が自動でコードレビューを実施。

4. 問題がなければ Main ブランチへ Merge。

5. Argo CD が変更を検知し、Raspberry Pi 5 クラスタへ自動同期・デプロイ。

単に「動画管理システムを作る」にとどまらず、「AIにコードを書かせ、AIにレビューさせ、GitOpsでコンテナクラスタへ自動デプロイする仕組みそのものを育てる」 というエキサイティングなプロジェクトになりました。ローカル Compose で検証しつつ、段階的に進めていきます。