iii-engine-config

エンジン設定

比較対象：Infrastructure as code、Docker Compose の設定

主な概念

タスクに適した概念を使用してください。すべてのデプロイで、すべてのモジュールやアダプターが必要になるわけではありません。

• iii-config.yaml では、エンジンのポート、モジュール、ワーカー、アダプター、キューの設定を定義します
• 環境変数 には ${VAR:default} 構文を使用します（デフォルト値は省略可能です）
• モジュール は構成要素です。それぞれが API、状態、キュー、cron などの機能を有効にします
• ワーカー は外部バイナリモジュールです。iii.toml と iii worker CLI コマンドで管理します
• アダプター を使うと、モジュールごとにストレージのバックエンドを切り替えられます：in_memory、file_based、Redis、RabbitMQ
• キューの設定 では、名前付きキューごとに再試行回数、同時実行数、順序、バックオフを制御します
• エンジンは、SDK／ワーカー接続用にポート 49134（WebSocket）でリッスンします

アーキテクチャ

iii-config.yaml ファイルは、起動時に iii エンジンバイナリによって読み込まれます。モジュールは順番に初期化され、アダプターはそれぞれのバックエンドに接続し、エンジンはポート 49134 の WebSocket 経由でワーカー接続の受け入れを開始します。workers セクションで定義された外部ワーカーは、自動的に子プロセスとして起動されます。

使用する iii プリミティブ

プリミティブ	用途
modules::api::RestApiModule	HTTP API サーバー（ポート 3111）
modules::stream::StreamModule	WebSocket ストリーム（ポート 3112）
modules::state::StateModule	永続的なキー・バリュー形式の状態ストレージ
modules::queue::QueueModule	再試行機能を備えたバックグラウンドジョブ処理
modules::pubsub::PubSubModule	プロセス内のイベント配信
modules::cron::CronModule	時間ベースのスケジューリング
modules::observability::OtelModule	OpenTelemetry のトレース、メトリクス、ログ
modules::http_functions::HttpFunctionsModule	外部 HTTP 呼び出しのセキュリティ
modules::shell::ExecModule	外部プロセスの起動
modules::bridge_client::BridgeClientModule	エンジン間の分散呼び出し
modules::telemetry::TelemetryModule	匿名の製品分析
iii-config.yaml の workers セクション	外部バイナリワーカー（ワーカーモジュール）
iii.toml	ワーカーマニフェスト（名前 → バージョン）
iii worker add NAME[@VERSION]	レジストリからワーカーをインストール
iii worker remove NAME	ワーカーをアンインストール
iii worker list	インストール済みワーカーを一覧表示
iii worker info NAME	ワーカーのレジストリ情報を表示

リファレンス実装

すべてのモジュール、アダプター、キューの設定、環境変数のパターンを含む完全なエンジン設定例については、../references/iii-config.yaml を参照してください。

一般的なパターン

このパターンを使用するコードには、該当する場合、一般に次のものが含まれます。

• iii --config ./iii-config.yaml — 設定ファイルを使用してエンジンを起動する
• docker pull iiidev/iii:latest — Docker イメージを取得する
• 開発用ストレージ：store_method: file_based と file_path: ./data/...
• 本番用ストレージ：redis_url: ${REDIS_URL} を指定した Redis アダプター
• 本番用キュー：amqp_url: ${AMQP_URL} と queue_mode: quorum を指定した RabbitMQ アダプター
• キューの設定：キュー名ごとに max_retries、concurrency、type、backoff_ms を指定する queue_configs
• フォールバック付き環境変数：port: ${III_PORT:49134}
• ヘルスチェック：curl http://localhost:3111/health
• ポート：3111（API）、3112（ストリーム）、49134（エンジン WS）、9464（Prometheus）

Worker モジュールシステム

外部 Worker は CLI からインストールし、iii-config.yaml で設定します。

• iii worker add [email protected] — レジストリから Worker バイナリをインストールします
• iii worker add（名前を指定しない場合）— iii.toml に記載されているすべての Worker をインストールします
• iii worker remove pdfkit — バイナリ、マニフェストのエントリ、設定ブロックを削除します
• iii worker list — iii.toml に記載されているインストール済み Worker とバージョンを表示します

Worker はバージョンマニフェストとして iii.toml に表示されます。

[workers]
pdfkit = "1.0.0"
image-processor = "2.3.1"

iii-config.yaml の Worker 設定ブロックでは、自動管理用のマーカーコメントを使用します。

workers:
  # === iii:pdfkit BEGIN ===
  - class: workers::pdfkit::PdfKitWorker
    config:
      output_dir: ./output
  # === iii:pdfkit END ===

起動時に、エンジンは各 Worker クラスを解決し、iii_workers/ 内のバイナリを見つけて、子プロセスとして起動します。Worker バイナリは iii_workers/ ディレクトリに保存されます。

このパターンの適用

タスクに当てはまる場合は、以下の適用方法を使用してください。

• 開発では file_based アダプターから始め、本番環境では Redis/RabbitMQ に切り替えます
• ワークロードごとにキュー設定を定義します。並列ジョブには高並行性、順序どおりの処理には FIFO を使用します
• デプロイ環境に依存するすべての値（URL、ポート、認証情報）には、デフォルト値を設定した環境変数を使用します
• 必要なモジュールのみを有効にします。使用しないモジュールは設定から省略できます
• iii worker add を使って外部 Worker をインストールし、設定ブロックを自動生成します
• 障害許容度と SLA 要件に基づいて max_retries と backoff_ms を設定します
• 可観測性のために、コレクターのエンドポイントとサンプリング比率を指定して OtelModule を設定します

パターンの適用範囲

• HTTP ハンドラーのロジック（リクエスト／レスポンス、パスパラメーター）には、iii-http-endpoints を優先してください。
• キュー処理のパターン（エンキュー、FIFO、並行性）には、iii-queue-processing を優先してください。
• cron スケジューリングの詳細（式、タイムゾーン）には、iii-cron-scheduling を優先してください。
• OpenTelemetry SDK の統合（スパン、メトリクス、トレース）には、iii-observability を優先してください。
• リアルタイムストリームのパターンには、iii-realtime-streams を優先してください。
• 主な課題がエンジン自体の設定またはデプロイである場合は、iii-engine-config を使用してください。

使用する場合

• タスクの主な内容が、iii エンジンにおける iii-engine-config である場合に、このスキルを使用してください。
• リクエストでこのパターン、または同等の実装が直接求められている場合に適用します。

適用範囲

• このスキルを、無関係なタスクに対する汎用的な代替手段として使用しないでください。
• より具体的な iii スキルが適している場合は、このスキルを適用しないでください。
• このスキルの例を適用する前に、環境と安全性の制約を必ず確認してください。