FleetFlow(KDLベースのコンテナオーケストレーションツール)を効果的に使用するためのガイド
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 固有
ステージは位置引数または -s フラグで指定。環境変数 FLEET_STAGE でも指定可能。
| コマンド | 説明 |
|---|---|
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] | コンテナ内でコマンド実行 |
| コマンド | 説明 |
|---|---|
build [stage] [-n svc] [--push] [--tag] | イメージをビルド(--pushでレジストリへ) |
deploy [stage] [-n svc] --yes [--dry-run] | CI/CD向けデプロイ |
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 管理 |
| コマンド | 説明 |
|---|---|
mcp | MCPサーバーを起動 |
self-update | FleetFlow自体を最新版に更新 |
--version | バージョン表示(フラグ) |
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
}
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> | 両方をマージ(後の定義が優先) |
規約ベースの自動検出と明示的指定の両方に対応:
// 規約ベース: ./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
認証方式(優先順):
~/.docker/config.json(auths セクション)GHCR_TOKEN → GITHUB_TOKEN、GHCR専用)DOCKER_CONFIG でパスをカスタマイズ可能config.json がない環境でも環境変数だけでプライベートGHCRからpull可能対応レジストリ:
タグ解決の優先順位:
--tag CLIオプションimage フィールドのタグ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 | 明示的に停止されない限り再起動(推奨) |
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秒(上限)で待機。
デフォルト設定での動作:
wait_forのみ指定でデフォルト値が適用される// デフォルト設定を使用
service "api" {
depends_on "db"
wait_for // 全てデフォルト値で待機
}
KDLファイルを分割して管理できます:
// flow.kdl
project "myapp"
include "services/*.kdl" // glob パターンで複数ファイルを読み込み
include "redis.kdl" // 単一ファイルの読み込み
特徴:
*.kdl, services/*.kdl 等)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 ブロックで定義した値が環境変数より優先複数の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レコードを自動管理:
{service}-{stage}.{domain} のAレコードを自動追加dns_aliasesでCNAMEエイリアスも自動作成必要な環境変数:
CLOUDFLARE_API_TOKEN: Cloudflare APIトークンCLOUDFLARE_ZONE_ID: ドメインのZone IDCI/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向け) |
デプロイフロー:
# 手動でアップデート
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)
このスキルは以下の場合に参照してください:
flow.kdl / fleet-registry.kdl 設定ファイルを作成・編集する際FleetFlow - シンプルに、統一的に、環境を構築する。