fleetflow

name	fleetflow
description	FleetFlow（KDLベースのコンテナオーケストレーションツール）を効果的に使用するためのガイド
version	0.15.0

FleetFlow スキル

You are an expert agent utilizing this skill.

FleetFlowをプロジェクトで効果的に活用するための包括的なガイドです。

概要

FleetFlowは、KDL（KDL Document Language）をベースにしたコンテナオーケストレーションツールです。

コンセプト: 環境構築は、対話になった。伝えれば、動く。

主要な特徴

特徴	説明
超シンプル	Docker Composeと同等以下の記述量
可読性	YAMLより読みやすいKDL構文
ステージ管理	local/dev/pre/live を統一管理
AIネイティブ	CLIをそのまま使える設計（Bash経由で操作）
OrbStack連携	macOSローカル開発に最適化
Dockerビルド	Dockerfileからのビルドをサポート
イメージプッシュ	ビルド後のレジストリプッシュを自動化
クロスビルド	--platform でマルチアーキテクチャ対応
サービスマージ	複数ファイルでの設定オーバーライド
再起動ポリシー	ホスト再起動時のコンテナ自動復旧
依存サービス待機	Exponential Backoffで堅牢な起動順序制御
クラウド対応	さくらのクラウド、Cloudflareなど複数プロバイダー
DNS自動管理	Cloudflare DNSとの自動連携
CI/CDデプロイ	deployコマンドによる自動デプロイ
Fleet Registry	複数fleetとサーバーの統合管理・SSHリモートデプロイ
Control Plane	常駐デーモン + WebUI Dashboard + Auth0 認証
Fleet Agent	サーバー常駐エージェント（デプロイ実行・ヘルス監視・アラート）
Dashboard Actions	WebUI から再デプロイ・再起動・アラート確認・ログ閲覧
LogRouter	コンテナログの topic ベース Pub/Sub 配信
include	KDLファイルの分割・再利用（glob対応）
変数展開	{{ VAR }} によるテンプレート変数
セルフアップデート	最新バージョンへの自動更新

クイックスタート

インストール

# Homebrew (macOS)
brew install chronista-club/tap/fleetflow

# curl
curl -sSf https://raw.githubusercontent.com/chronista-club/fleetflow/main/install.sh | sh

# Cargo
cargo install --git https://github.com/chronista-club/fleetflow

最小構成

// flow.kdl
project "myapp"

stage "local" {
    service "db"
}

service "db" {
    image "postgres:16"  // image は必須
    ports {
        port host=5432 container=5432
    }
    environment {
        POSTGRES_PASSWORD "postgres"
    }
}

基本操作

fleet up local       # 起動
fleet ps             # コンテナ一覧・状態表示
fleet logs           # ログ表示
fleet down local     # 停止・削除
fleet --version      # バージョン表示

グローバルフラグ

フラグ	説明
-v / --verbose	デバッグレベルの詳細出力
-q / --quiet	エラー以外の出力を抑制

環境変数

変数	説明
FLEET_STAGE	ステージ名を指定（local, dev, pre, live）
FLEETFLOW_CONFIG_PATH	設定ファイルの直接パス指定
FLEETFLOW_NO_UPDATE_CHECK	設定するとセルフアップデートチェックをスキップ
GHCR_TOKEN	GitHub Container Registry認証トークン（プライベートGHCRからのpull用）
GITHUB_TOKEN	GitHubトークン（GHCR_TOKEN未設定時のフォールバック）
CLOUDFLARE_API_TOKEN	Cloudflare APIトークン（DNS自動管理用）
CLOUDFLARE_ZONE_ID	Cloudflare Zone ID（DNS自動管理用）

環境変数ファイル

.fleetflow/
├── .env           # グローバル（共通）
├── .env.local     # local 固有
├── .env.dev       # dev 固有
└── .env.live      # live 固有

CLIコマンド一覧

ステージは位置引数または -s フラグで指定。環境変数 FLEET_STAGE でも指定可能。

Daily（日常操作）

コマンド	説明
up [stage] [--pull] [--dry-run]	ステージを起動（--dry-runで設定検証・計画表示）
down [stage] [--remove]	ステージを停止
restart [stage] [-n svc]	サービスまたはステージ全体を再起動
ps [stage] [--all] [--global]	コンテナ一覧・状態表示
logs [stage] [-n svc] [-f] [--since 5m]	ログ表示
exec [stage] -n <svc> [-it] [-- cmd]	コンテナ内でコマンド実行

Ship（ビルド・デプロイ）

コマンド	説明
build [stage] [-n svc] [--push] [--tag]	イメージをビルド（--pushでレジストリへ）
deploy [stage] [-n svc] --yes [--dry-run]	CI/CD向けデプロイ

Admin（Control Plane — fleet cp 配下）

コマンド	説明
cp login / logout / auth	認証管理
cp daemon start / stop / status	デーモン管理
cp tenant list / create / status	テナント管理
cp project list / create / show	プロジェクト管理
cp server list / register / status / check / ping	サーバー管理
cp cost list / summary / record	コスト管理
cp dns list / create / delete / sync	DNS 管理
cp remote deploy / history	リモートデプロイ
cp registry list / status / sync / deploy	Fleet Registry 管理

Util

コマンド	説明
mcp	MCPサーバーを起動
self-update	FleetFlow自体を最新版に更新
--version	バージョン表示（フラグ）

詳細: reference/cli-commands.md

設定ファイル構造

project "name"              // プロジェクト名（必須）

stage "local" {             // ステージ定義
    service "db"
    service "web"
}

service "db" {              // サービス定義
    image "postgres:16"     // 必須
    restart "unless-stopped" // 再起動ポリシー
    depends_on "other"      // 依存サービス
    wait_for { ... }        // 依存サービス待機設定
    ports { ... }
    environment { ... }
    volumes { ... }
    build { ... }           // Dockerビルド設定
    healthcheck { ... }     // ヘルスチェック設定
}

// クラウドインフラ（オプション）
providers {
    sakura-cloud { zone "tk1a" }
    cloudflare { account-id env="CF_ACCOUNT_ID" }
}

server "app-server" {       // クラウドサーバー定義
    provider "sakura-cloud"
    plan core=4 memory=4
}

詳細: reference/kdl-syntax.md

重要な仕様

imageフィールドは必須

imageフィールドは必須です。省略するとエラーになります：

// 正しい定義
service "db" {
    image "postgres:16"
}

// エラー: imageが必須
service "db" {
    version "16"  // これだけではダメ
}
// Error: サービス 'db' に image が指定されていません

サービスマージ機能

複数ファイルで同じサービスを定義すると、設定がマージされます：

// flow.kdl（ベース設定）
service "api" {
    image "myapp:latest"
    ports { port host=8080 container=3000 }
    environment { NODE_ENV "production" }
}

// flow.local.kdl（ローカルオーバーライド）
service "api" {
    environment { DATABASE_URL "localhost:5432" }
}

// 結果:
// - image: "myapp:latest" (保持)
// - ports: [8080:3000] (保持)
// - env: { NODE_ENV: "production", DATABASE_URL: "localhost:5432" } (マージ)

マージルール:

フィールドタイプ	ルール
Option<T>	後の定義がSomeなら上書き、Noneなら保持
Vec<T>	後の定義が空でなければ上書き、空なら保持
HashMap<K, V>	両方をマージ（後の定義が優先）

Dockerビルド機能

規約ベースの自動検出と明示的指定の両方に対応：

// 規約ベース: ./services/api/Dockerfile を自動検出
service "api" {
    image "myapp/api:latest"
    build_args {
        NODE_VERSION "20"
    }
}

// 明示的指定
service "worker" {
    image "myapp/worker:latest"
    dockerfile "./backend/worker/Dockerfile"
    context "./backend"
    target "production"  // マルチステージビルド
}

イメージプッシュ機能

ビルドしたイメージをレジストリにプッシュ：

# ビルドのみ
fleet build local -n api

# 複数サービスを同時ビルド（-n を繰り返す）
fleet build local -n api -n worker

# ビルド＆プッシュ
fleet build local -n api --push

# タグを指定してビルド＆プッシュ
fleet build local -n api --push --tag v1.0.0

# クロスビルド（linux/amd64向け）
fleet build live -n api --push --platform linux/amd64

認証方式（優先順）:

1. Docker標準の ~/.docker/config.json（auths セクション）
2. credential helper（osxkeychain, desktop など）
3. 環境変数フォールバック（GHCR_TOKEN → GITHUB_TOKEN、GHCR専用）

• 環境変数 DOCKER_CONFIG でパスをカスタマイズ可能
• VPS等で config.json がない環境でも環境変数だけでプライベートGHCRからpull可能

対応レジストリ:

• Docker Hub (docker.io)
• GitHub Container Registry (ghcr.io)
• Amazon ECR (.dkr.ecr..amazonaws.com)
• Google Container Registry (gcr.io)
• プライベートレジストリ (localhost:5000 など)

タグ解決の優先順位:

1. --tag CLIオプション
2. KDL設定の image フィールドのタグ
3. デフォルト: latest

クラウドインフラ管理

複数のクラウドプロバイダーをKDLで宣言的に管理：

providers {
    sakura-cloud { zone "tk1a" }
    cloudflare { account-id env="CF_ACCOUNT_ID" }
}

stage "dev" {
    server "app-server" {
        provider "sakura-cloud"
        plan core=4 memory=4
        disk size=100 os="ubuntu-24.04"
        dns_aliases "app" "api"  // DNSエイリアス
    }
}

再起動ポリシー

ホスト再起動後にコンテナを自動復旧させる：

service "db" {
    image "postgres:16"
    restart "unless-stopped"  // ホスト再起動後も自動起動
}

対応する値:

値	説明
no	再起動しない（デフォルト）
always	常に再起動
on-failure	異常終了時のみ再起動
unless-stopped	明示的に停止されない限り再起動（推奨）

依存サービス待機（Exponential Backoff）

K8sのReadiness Probeコンセプトを取り入れた、依存サービスの準備完了待機機能：

service "api" {
    image "myapp/api:latest"
    depends_on "db" "redis"
    wait_for {
        max_retries 23        // 最大リトライ回数（デフォルト: 23）
        initial_delay 1000    // 初回待機時間ms（デフォルト: 1000）
        max_delay 30000       // 最大待機時間ms（デフォルト: 30000）
        multiplier 2.0        // 待機時間の増加倍率（デフォルト: 2.0）
    }
}

待機時間の計算（Exponential Backoff）:

delay = initial_delay * multiplier^attempt

max_delayで上限を設定。デフォルト設定では1秒→2秒→4秒→8秒→...→30秒（上限）で待機。

デフォルト設定での動作:

• 最大約23回のリトライで約7分間の待機が可能
• wait_forのみ指定でデフォルト値が適用される

// デフォルト設定を使用
service "api" {
    depends_on "db"
    wait_for  // 全てデフォルト値で待機
}

include ディレクティブ

KDLファイルを分割して管理できます：

// flow.kdl
project "myapp"

include "services/*.kdl"   // glob パターンで複数ファイルを読み込み
include "redis.kdl"        // 単一ファイルの読み込み

特徴:

• glob パターン対応（*.kdl, services/*.kdl 等）
• ネスト可能（include先のファイルからさらにinclude）
• 循環参照を自動検出してエラー

変数展開

KDL設定内で {{ VAR }} 構文によるテンプレート変数を使用できます：

variables {
    APP_PORT "3000"
    DB_HOST "localhost"
}

service "api" {
    image "myapp:latest"
    environment {
        DATABASE_URL "postgres://{{ DB_HOST }}:5432/mydb"
    }
    ports {
        port {{ APP_PORT }} 3000
    }
}

• 環境変数からも自動的に変数を取得
• variables ブロックで定義した値が環境変数より優先

Fleet Registry（複数fleet統合管理）

複数のFleetFlowプロジェクトとサーバーを一元管理し、SSHリモートデプロイを実行：

// fleet-registry.kdl
registry "my-org"

fleet "api" {
    path "/opt/apps/fleets/api"
    description "APIサーバー"
}

server "vps-01" {
    provider "sakura-cloud"
    ssh-host "153.x.x.x"
    ssh-user "root"
    deploy-path "/opt/apps"
}

route "api:live" {
    server "vps-01"
}

fleet cp registry list               # fleet・サーバー一覧
fleet cp registry status             # 稼働状態を確認
fleet cp registry deploy api --yes   # SSH経由でリモートデプロイ

DNS自動管理（Cloudflare）

ステージ起動・停止時にDNSレコードを自動管理：

• サーバー作成時: {service}-{stage}.{domain} のAレコードを自動追加
• サーバー削除時: DNSレコードを自動削除
• dns_aliasesでCNAMEエイリアスも自動作成

必要な環境変数:

• CLOUDFLARE_API_TOKEN: Cloudflare APIトークン
• CLOUDFLARE_ZONE_ID: ドメインのZone ID

CI/CDデプロイ（deployコマンド）

CI/CDパイプラインからの自動デプロイに最適化されたコマンド：

# 基本的な使い方（デフォルトでpull）
fleet deploy live --yes

# 特定サービスのみデプロイ
fleet deploy dev -n api --yes

# 複数サービスを同時指定（-n を繰り返す）
fleet deploy dev -n api -n worker --yes

# pullをスキップ
fleet deploy live --no-pull --yes

# GitHub Actionsから
ssh user@vps "cd /app && fleet deploy live --yes"

オプション:

オプション	説明
-n <service>	デプロイ対象サービス（複数指定可）
--no-pull	イメージのpullをスキップ（デフォルトはpull）
--yes / -y	確認なしで実行（CI向け）

デプロイフロー:

1. 既存コンテナを強制停止・削除
2. 最新イメージをpull（--no-pullでスキップ可能）
3. コンテナを依存関係順に作成・起動
4. wait_forによる依存サービス待機

セルフアップデート

# 手動でアップデート
fleet self-update

コンテナ命名規則

FleetFlowは以下の命名規則でコンテナを作成します：

{project}-{stage}-{service}

例: myapp-local-db

OrbStackでは {project}-{stage} でグループ化されます。

プロジェクト構造

fleetflow/
├── crates/
│   ├── fleetflow/              # CLI (bin: fleet)
│   ├── fleetflow-core/         # KDLパーサー
│   ├── fleetflow-config/       # 設定管理
│   ├── fleetflow-container/    # コンテナ操作
│   ├── fleetflow-build/        # Dockerビルド
│   ├── fleetflow-mcp/          # MCPサーバー
│   ├── fleetflow-registry/     # Fleet Registry（複数fleet統合管理）
│   ├── fleetflow-cloud/        # クラウド抽象化
│   ├── fleetflow-cloud-sakura/ # さくらクラウド
│   ├── fleetflow-cloud-cloudflare/ # Cloudflare
│   ├── fleetflow-controlplane/# Control Plane ライブラリ
│   ├── fleetflowd/            # Control Plane デーモン
│   └── fleet-agent/           # Fleet Agent（サーバー常駐エージェント）
├── docs/
│   └── guide/                 # 利用ガイド（Usage）

詳細: reference/architecture.md

スキルの起動タイミング

このスキルは以下の場合に参照してください：

• プロジェクトにFleetFlowを導入する際
• flow.kdl / fleet-registry.kdl 設定ファイルを作成・編集する際
• コンテナ環境の構築・管理を行う際
• ローカル開発環境のセットアップ時
• 複数fleetの統合管理（Fleet Registry）を行う際
• クラウドインフラを宣言的に管理する際

リファレンス

• KDL構文リファレンス
• CLIコマンドリファレンス
• アーキテクチャ
• パターン集

外部リンク

• GitHub Repository
• KDL Document Language
• OrbStack

---

FleetFlow - シンプルに、統一的に、環境を構築する。