Floci - AWS互換APIをlocalhostで再現するエミュレーターの実装方式と互換範囲
Flociは、開発・テスト・CI向けのMITライセンスのJava製ローカルAWSエミュレーターである。AWS SDK・CLI・Terraform・CDK・OpenTofuの接続先を http://localhost:4566 に向けるだけで、アカウントも認証トークンも使わずにAWS形のサービスを動かせる。単一のHTTPルーターがAWSワイヤプロトコルを受け、S3・SQS・DynamoDBなどはプロセス内で実装し、Lambda・RDS・ElastiCache・ECS・EC2・EKSなど実エンジンの挙動が重要なサービスはDocker APIで本物のコンテナを起動して再現する。 主な注意点は、互換範囲と性能の根拠がほぼREADMEの自己申告にとどまることだ。サービス名が対応一覧にあっても、実コンテナで動くものからダミー応答や「保存のみ」のものまで、忠実度には幅がある。本記事はREADME、リポジトリメタデータ、リリース記録に基づき、ソースコードとAPI単位の対応表は未確認だ。
ポッドキャスト形式で聴く
約4分AI生成の会話音声です。記事の要点を短くまとめています。
なぜ注目されているか
2026年11月4日(日次)のGitHub Trendingで8位に入り、同日に+482スター(累計28,853、フォーク3,209)を集めている。10月31日(UTC)に2.4.0が公開され、観測直前の11月4日01:53(UTC)にもpushがあるなど開発も続いている。一方、当日増加数÷累計スターは0.017で急騰判定はnone。Hacker Newsなど外部コミュニティの議論は取得データになく、観測できる注目はGitHub上の指標に限られる。これらは注目度の指標であり、技術的主張の根拠ではない。
なぜ重要なのか
論点は、「AWS互換」を一枚岩の品質として扱わず、サービスごとに忠実度と起動コストを選び分ける設計にある。軽いサービスはプロセス内で即応させ、DBやコンピュートは本物のエンジンに任せる。この分担が実用範囲で成り立つなら、AWS向けコードの統合テストをアカウント・課金・トークンから切り離し、開発機とCIで使い捨てにできる。その場合、テスト環境の責任は共有のクラウド環境から、各パイプラインのDockerホストへ移る。
ただし条件がつく。READMEが掲げる「LocalStack Communityの置き換え」は、今回の資料では互換範囲を検証できていない。Dockerソケット前提の構成はCIランナーの権限設計に響き、ローカルで通っても本番AWSでの動作は保証されない。
この記事に出てくる言葉(6語)
- 単一エンドポイント
全AWSサービスを http://localhost:4566 の一つのHTTP入口で受ける方式。クライアントは接続先と資格情報を差し替えるだけで済む。
- インプロセス実装
外部プロセスを起動せず、Flociのコード内でサービスを処理する方式。
- 実Docker実装
Docker APIで本物のエンジンのコンテナを起動し、前段にAWS形の入口を置く方式。Dockerソケットが要る。
- プロトコルプロキシ
実コンテナの前に置く、AWSのプロトコルに合わせた中継口。ElastiCache向けのRESPプロキシ、Neptune向けのSigV4プロキシなど。
- StorageBackend
状態の保存層。memory/hybrid/persistent/walの4モードから、耐久性と速度のバランスを選ぶ。
- サイドカー
Flociが補助的に起動する別コンテナ。AthenaのDuckDB、Verified PermissionsのCedar、AppSyncのgraphql-javaなど。
1. 読む前に知っておきたいこと
再現の粒度という難所
AWS向けのSDK・CLI・IaCコードを開発機とCIで繰り返し実行するには、実アカウントや課金、認証トークンに依存せず、AWSワイヤプロトコルを話すバックエンドをローカルに置く必要がある。難所は、S3やSQSのような軽量サービスだけでなく、RDS・ElastiCache・Lambda・ECSのように実エンジンの挙動が重要なサービスまで、起動の速さと忠実度を両立させる点だ。READMEは、浅いインプロセスのモックではステートフルDB、接続数の多いプロトコル、ランタイム、ビルド系がずれやすいと述べ、それを実Dockerコンテナを使う理由に挙げている。
従来の選択肢
READMEが比較対象に据えるのはLocalStack Communityだ。イメージを起動して接続先をローカルへ向ける方式で、Flociと同型である。READMEは、LocalStackのcommunity editionが2026年3月にsunsetし、認証トークン必須・セキュリティ更新凍結になったと主張し、Flociをイメージ差し替えで移行できる代替として示す。この経緯はREADMEの記述で、LocalStack側の一次情報は確認していない。もう一つの選択肢はクラウドアカウント上の環境での検証だが、これは編集部の整理であり、READMEの記述ではない。
READMEが挙げる痛みは、有償機能やトークンを前提にした配布の制約、起動時間・メモリ・イメージサイズに由来するCIの起動待ちとリソース消費、共有エミュレーターでの状態共有とポート衝突である。
プロジェクトの現況と名称
リポジトリはfloci-io/floci。主言語はJava、ライセンスはMIT、作成は2026-02-18で、取得時点(2026-11-04)で作成から258日、オープンIssueは170件だった。最新は2.4.0(2026-10-31 UTC)で、2.3.0(10-15)、2.2.0(10-06)が続く。READMEは安定版を毎月15日と末日に切ると書くが、2.2.0の日付はこれと合わない。日次GitHub Trendingでは8位(+482スター、累計28,853)だが、増加率は急騰判定に達せず、注目度は互換性の証拠にならない。
名称は混ざりやすい。製品名がFloci、公式CLIのコマンドがfloci(floci start/floci env)、リリース同梱の単体バイナリがfloci-aws、Dockerイメージがfloci/flociで、旧イメージhectorvent/flociは更新されない。Azure・GCP・OCI向けの姉妹エミュレーターもあるが、本記事はAWS版に限る。
2. どう動くのか
入口と接続先の差し替え
起動は、公式CLIの floci start、floci/floci イメージの docker run/Docker Compose、リリース同梱の単体バイナリ floci-aws のいずれかで、ポート4566で待ち受ける。単体バイナリはDockerなしでも使えるとされるが、Dockerバックのサービスがどこまで動くかはREADMEに明記がない。
クライアント側の変更は接続設定だけだ。CLI経路では eval $(floci env) がAWS環境変数を設定し、手動なら AWS_ENDPOINT_URL=http://localhost:4566、リージョン、ダミーの資格情報を渡す。資格情報は、サービス固有の厳格な認証チェックを有効にしない限り任意の非空値でよく、リージョンも公開済みのものなら使える。
リクエストはJAX-RS/Vert.xのルーターが受け、READMEの構成図ではStateless Services、Stateful Services(S3・DynamoDB・DynamoDB Streams)、Container Servicesの3グループへ振り分けられる。「Stateless/Stateful」は図のラベルで、SQSやSNSもStateless側に描かれ、両グループが同じStorageBackendに接続されている。字義どおりには読まないほうがよい。
サービスごとの実装戦略
中心になるのは、サービスごとに実装方式を使い分ける点だ。READMEの詳細表の区別を、編集部で4種に整理する。
まずインプロセス実装。S3・SQS・SNS・DynamoDB・IAM/STS・KMS・Secrets Managerなどで、Floci内のコードが処理し、状態をStorageBackendに読み書きする。次に実Dockerコンテナ。Lambda・RDS・ElastiCache・ECS・EC2・EKS・MSKなどが該当し、READMEは浅いモックでなく実コンテナで動かすと述べる。三つ目はサイドカー委譲で、AthenaはDuckDBサイドカー(floci-duck)がS3とGlue由来のビューに対してSQLを実行し、Verified PermissionsはCedar、AppSyncはgraphql-javaを使う。最後がスタブ・固定応答・「保存のみ」である。
Aurora DSQL・Timestream for InfluxDB・DocumentDB・EKS・MWAAは、実Dockerに加えてmock modeも選べる。同じサービス名でも、方式によって忠実度が変わる。
Docker型の前段にあるプロトコル口
Docker型では、FlociがDocker API経由でDocker Engineを操作して実コンテナを起動・管理する。そのためdocker.sockのマウントが必須で、READMEの例は -u root も指定している。既定イメージの例は、ElastiCacheがvalkey/valkey:8、RDSがpostgres:16-alpine・mysql:8.0・mariadb:11、DocumentDBがmongo:7.0、Lambdaがpublic.ecr.aws/lambdaのランタイム別イメージで、FLOCI_SERVICES_系の環境変数で上書きできる。
要点は、コンテナを素のまま出さず、前段にプロトコル固有の口を置くことだ。MemoryDBはElastiCacheのRESPプロキシを再利用し、Neptuneはポート8182のSigV4プロキシ、DocumentDBはポート27017のMongoDBワイヤプロトコルを提供し、MWAAはWeb/CLIのプロキシを持つ。AWS形の入口をFlociが用意し、中身の挙動は本物のエンジンが担う分担と読める。LambdaやECSの呼び出し・配置の具体的な実現方式は、取得資料からは確認できない。
状態保持・アカウント分離・返却URL
状態はStorageBackendが持つ。FLOCI_STORAGE_MODEの既定はmemoryで、すべてRAM上にあり停止で消える。persistentは起動時にロードして書き込みごとに即時flushし、hybridは5秒ごとに非同期でflushし、walは応答前に変更を先行ログへ記録する。サービス単位の上書きもでき、耐久性と速度をモードで選ぶ設計だ。
アカウントはAWS_ACCESS_KEY_IDで決まる。ちょうど12桁ならそれをアカウントIDとしてリソースを分離し、そうでなければSTS一時セッションを照会し、最後にFLOCI_DEFAULT_ACCOUNT_ID(既定000000000000)へ落ちる。AssumeRoleを使うクロスアカウント構成もローカルで再現できる。
返却URLはFLOCI_BASE_URL(既定 http://localhost:4566)を基に組み立てられる。アプリが別コンテナにある場合は、FLOCI_HOSTNAMEにFlociのサービス名を設定しないと、SQSのQueueUrlなどがlocalhostを指して届かない。
3. 使いどころと限界
向いている構成
相性がよいのは、SDK・CLI・Terraform/OpenTofu/CDKで書いたAWS向けコードを、アカウントや課金なしにローカルとCIで繰り返し検証する用途だ。S3・SQS・DynamoDB・SNSなど主要サービス中心の統合テストが典型で、Terraformは標準のHashiCorp AWSプロバイダーで使える。
テストごとに隔離したインスタンスが欲しいなら、Testcontainersモジュールがある。READMEによれば、共有状態、手動のデーモン設定、ポート衝突を避けられる。Testcontainersはコンテナのライフサイクルを管理するライブラリで、Flociの代替でなく補完関係にある。RDS・ElastiCache・MSK・EKS(k3s)の実エンジンを、Dockerソケットを使えるローカルやCIで試す構成にも向く。
LocalStack Communityとの関係と数値の読み方
競合はLocalStack Communityだ。READMEは「drop-in replacement」を掲げ、imageをlocalstack/localstackからfloci/floci:latestへ替えれば、LocalStack環境変数の自動翻訳、/etc/localstack/init/のinitスクリプト、/_localstack/health、「Ready.」ログ行も引き継げるとする。ただし自動翻訳の例として挙がるのは5例のみで、それ以外の設定の扱いは書かれていない。LocalStackの有償機能に依存する構成は、置き換えられない可能性がある。
比較表の数値は作者の報告として読む。READMEは起動時間をFloci約24 ms対LocalStack Community約3.3秒、アイドルメモリを約13 MiB対約143 MiB、Dockerイメージを約90 MB対約1.0 GB(ネイティブバイナリは約40 MB)と示すが、ハードウェア、イメージ種別、LocalStackのバージョン、計測方法の記載はなく、独立した再現測定もない。「ネイティブイメージはミリ秒で起動する」という説明も同じ扱いで、ネイティブ化の手段は資料に記載がない。RDSやECS/EC2/EKSなどでLocalStack Communityを「No」とする機能比較も、LocalStack側の現行機能とは照合されていない。2,576件の互換性テスト(Java 1,326件、Node.js 449件など)も件数の申告で、合否やAPIカバレッジは分からない。
忠実度の限界と本番との差
対応サービス名の一覧は挙動の同等性を示さない。READMEは自ら制約を記している。Bedrock Runtimeはダミーのconverse/InvokeModel応答、Textractはダミーのブロックデータ、Transcribeはジョブが即時完了して音声処理なし、Bedrock AgentCoreのInvokeAgentRuntimeは固定応答だ。Application Auto Scalingのポリシーは保存のみ、Data Lifecycle Managerはスナップショットを作らず、AWS FISは障害を注入しない制御プレーンのシミュレーション、Service Quotasは寛大な固定値(実クォータコードを持つのはCodeBuildとLambda同時実行のみ)とされる。
認証も既定では緩い。資格情報は任意の非空値で通り、S3の公開/非公開読み取り制御や未知の署名済みアクセスキーの拒否は、FLOCI_SERVICES_S3_ENFORCE_AUTH(既定false)を有効にして初めて行われる。本番IAMと同じ評価かはREADMEから確認できない。READMEのサービス表もサービス名と主な機能の一覧で、API単位の互換性は公式ドキュメントのServices Overviewに委ねられており、今回は未確認だ。したがって、ローカルでテストが通っても本番AWSでの動作は保証されない。IAM評価、整合性、料金、サービス制限、スタブや保存のみのサービスで差が出うる。
運用上のリスクと成熟度
Dockerソケットを渡すと、Flociはホスト上でコンテナを起動・操作できる。共有CIランナーや信頼できないコードを扱う環境では権限の扱いに注意が必要だ(編集部の指摘)。ソケットを渡せない環境では、Dockerバックのサービスを使うテストは不向きだ。Webコンソールも初回アクセス時にサイドカーを起動するため同じソケットを要し、FLOCI_SERVICES_UI_BIND_ADDRESSが未設定だとコンソールのポート(既定4500)は全インターフェースに公開される。
再現性にも注意点がある。MSKのredpandadata/redpanda:latestとEKSのrancher/k3s:latestは:latestタグで、固定には既定イメージの環境変数での上書きが要る。Testcontainersモジュールの成熟度も言語で差があり、Javaが1.14.0(2.x用は2.15.0)なのに対し、Node.jsは0.1.0、Pythonは0.1.1、Goは作業中だ。
プロジェクトは作成から258日でオープンIssueが170件の急成長期にあり、互換性バグや破壊的変更の頻度は資料から判断できない。READMEはスポンサー資金による独立OSSで、スポンサーは機能・優先度・ロードマップに影響しないと述べるが、運営体制の詳細は不明だ。リリースはmainのみで保守ブランチがなく、nightlyはmainを追跡するため、旧バージョンに固定した場合の修正提供は期待しにくい。
このツールから考える
ここからは、一次情報と限界を踏まえた編集上の考察です。
観察した仕組みは、一つのエンドポイントの背後に、インプロセス実装、実Dockerコンテナ、サイドカー、スタブという異なる忠実度の層が同居していることだ。クライアントからは全部が「localhost:4566のAWS」に見えるが、実体は一様ではなく、サービス名が一覧にあることは本番同等の挙動を意味しない。
この構造は、テストの責任分界を見直す材料になりうる。S3やSQSのような軽量サービスは使い捨てのエミュレーターに、DBやコンピュートはコンテナに任せ、IAM評価・整合性・サービス制限・料金は実AWSで確かめる、という層ごとの線引きが明示しやすくなる。同時に、環境の責任は共有のクラウド環境から各CIのDockerホストへ移り、Dockerソケットという強い権限の扱いが新しい論点になる。
この見立てには未確認事項が残る。API単位の対応表、READMEの数値の独立した再現測定、互換性テストの合否、LocalStackの現行機能との照合は、今回の資料にない。急成長期のプロジェクトとして、互換性バグや破壊的変更の頻度、運営の継続性も見ておきたい。採用の入口としては、自分たちが使うAPIの範囲を小さなテストで確かめ、その範囲がどの実装方式に当たるかを把握するのが現実的だろう。
検証に使用した一次情報
DevTool Lensでは、第三者の二次情報やREADMEの宣伝文句に依存せず、以下の公式リポジトリ・ドキュメント・リリース情報を精査して記事を作成しています。
- [readme]floci-io/floci README
- [repo]floci-io/floci GitHub Repository
- [release]floci-io/floci Releases
- [github_trending]GitHub Trending Daily (2026-11-04)