Azure Cosmos DB Linux emulator（vNext）は、Azure Cosmos DB for NoSQLをローカルPCやCI環境で開発・テストするためのDockerベースのエミュレーターです。今回の一般提供により、Linux、macOS、Windowsに加え、x64とARM64の環境で扱いやすくなり、Apple Silicon搭載MacやLinuxベースのCIでも導入しやすくなりました。まず押さえるべき結論は、「本番環境の代替」ではなく、「NoSQL API向けのローカル開発・統合テストを高速化するための開発基盤」として使うべき、という点です。(Microsoft for Developers)
特に、Dockerで同じ環境を再現したい開発チーム、GitHub Actionsなどで統合テストを回したいチーム、Azure Cosmos DBを使ったAI・ベクトル検索アプリをローカルで試したい開発者には大きなメリットがあります。一方で、対応APIや一部機能には制限があるため、既存のエミュレーターやクラウド上のAzure Cosmos DBアカウントを完全に置き換える前に、サポート範囲とSDKごとの注意点を確認しておく必要があります。(Microsoft Learn)
Azure Cosmos DB Linux emulator vNextで何が変わったのか
今回のポイントは、Azure Cosmos DBのローカル開発環境が「特定OSに依存しにくいDockerベースの仕組み」として一般提供されたことです。公式発表では、Azure Cosmos DB vNext emulatorはDockerイメージとして提供され、Linux、macOS、Windows、x64、ARM64で動作すると説明されています。用途としては、ローカルPCでの内側の開発ループ、CIの統合テスト、本物のAzure Cosmos DBアカウントを使いたくない検証環境が挙げられています。(Microsoft for Developers)
| 変更点 | 実務上の意味 |
|---|---|
| Dockerベースで提供 | 開発者ごとの環境差を減らし、CIにも組み込みやすい |
| Linux/macOS/Windows、x64/ARM64に対応 | Apple Silicon MacやARM64環境でも扱いやすい |
vnext-latestイメージを利用 | プレビュー用タグからGA向けのイメージに切り替えられる |
| Health probeを提供 | ログ文字列待ちではなく、HTTPエンドポイントで起動完了を判定できる |
| Azure Cosmos DB Shellを同梱 | 初期データ投入や対話操作をコンテナー内で完結しやすい |
| OpenTelemetryをサポート | ローカル検証でもリクエスト率、クエリ時間、エラー率などを観測しやすい |
| ベクトル検索をサポート | RAGやセマンティック検索のローカル検証に使いやすい |
これまでローカル検証のためにクラウド上の検証用Azure Cosmos DBアカウントを常時用意していたチームでは、単体テストや一部の統合テストをローカルまたはCIのDockerコンテナーに寄せられる可能性があります。ただし、Request Unitsやカスタムインデックスの挙動、ストアドプロシージャなど、本番相当の検証に向かない領域もあるため、クラウド環境での最終確認は引き続き必要です。(Microsoft Learn)
まず試すための基本コマンド
Azure Cosmos DB Linux emulator vNextを試すには、Dockerが必要です。公式ドキュメントでは、Microsoft Artifact Registryに公開されている mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest を取得して実行する手順が示されています。(Microsoft Learn)
docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latestdocker run --detach \
--name cosmos-vnext \
--publish 8081:8081 \
--publish 8080:8080 \
--publish 1234:1234 \
mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest主に使うポートは次の3つです。
| ポート | 用途 | 確認ポイント |
|---|---|---|
| 8081 | Azure Cosmos DB emulator本体のゲートウェイエンドポイント | アプリケーションやSDKから接続する |
| 1234 | Data Explorer | ブラウザーでローカルデータを確認する |
| 8080 | Health probe | CIや起動スクリプトで準備完了を判定する |
エミュレーター本体のゲートウェイエンドポイントは通常 http://localhost:8081、Data Explorerは http://localhost:1234 で利用します。Data Explorerは起動に数秒かかる場合があるため、CIでは画面ではなくHealth probeを使って起動完了を判断するのが安全です。(Microsoft Learn)
起動確認には、次のように /ready を使います。
curl -fsS http://localhost:8080/readyCIでありがちな失敗は、コンテナー起動直後にテストを実行してしまい、SDK接続が不安定になることです。従来のログメッセージ待ちではなく、/alive、/ready、/status のHealth probeを使う構成に変更すると、テストの再現性を高められます。(Microsoft Learn)
影響範囲：誰が対応すべきか
今回の更新はAzure Cosmos DBのクラウド上の本番アカウントを自動的に変更するものではありません。影響を受けるのは主に、ローカル開発、Dockerベースの検証、CI/CD、SDK接続設定、テストデータ投入の仕組みを管理しているチームです。
開発者が確認すべきこと
開発者は、まず自分のアプリがAzure Cosmos DB for NoSQLを利用しているかを確認してください。vNextエミュレーターはNoSQL API向けであり、ゲートウェイモードと一部機能に対応するものです。MongoDB、Cassandra、Gremlin、Table APIの代替として安易に使うのは避けるべきです。(Microsoft Learn)
また、.NET SDKとJava SDKを使う場合はHTTPモードに注意が必要です。公式ドキュメントでは、このバージョンのエミュレーターは既定でHTTPとして起動する一方、.NET SDKとJava SDKはエミュレーターのHTTPモードをサポートしていないため、HTTPSを明示的に有効化する必要があると説明されています。(Microsoft Learn)
docker run --detach \
--name cosmos-vnext \
--publish 8081:8081 \
--publish 8080:8080 \
--publish 1234:1234 \
mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest \
--protocol httpsJavaでは、HTTPS利用時にエミュレーター証明書をJavaのtrust storeへインポートする対応が必要です。ローカルだけだからといってTLS検証を無効化する実装をアプリ本体に混ぜると、本番コードへ混入するリスクがあります。開発専用の設定ファイルや環境変数で明確に分離しておきましょう。(Microsoft Learn)
CI/CD管理者が確認すべきこと
CI/CDでは、エミュレーターをサービスコンテナーとして起動し、テスト前に /ready を確認する構成が基本になります。公式ドキュメントでは、GitHub ActionsのUbuntuランナー上で vnext-latest Dockerイメージをサービスコンテナーとして使い、環境変数で接続文字列、データベース名、コンテナー名を構成する例が示されています。(Microsoft Learn)
管理者が特に確認すべき項目は次の通りです。
| 項目 | 確認内容 | 失敗しやすいポイント |
|---|---|---|
| Dockerイメージ | vnext-latestを利用しているか | プレビュー用タグのまま運用してしまう |
| 起動判定 | /readyで準備完了を確認しているか | コンテナー起動直後にテストを流して失敗する |
| ポート公開 | 8081、8080、1234のうち必要なものを公開しているか | Health probe用の8080を公開し忘れる |
| プロトコル | SDKに応じてHTTP/HTTPSを選んでいるか | .NET/JavaでHTTPのまま接続して失敗する |
| 証明書 | Javaや.NETでHTTPS利用時の証明書を扱えているか | CI環境だけ証明書エラーになる |
| 初期データ | seedスクリプトや永続化方針を決めているか | テストごとにデータ状態が変わる |
| 外部送信 | テレメトリ設定が組織ポリシーに合っているか | 既定設定を確認せず社内ルールに抵触する |
エミュレーターには診断情報をMicrosoftに送信する設定があり、公式ドキュメント上では --enable-telemetry または ENABLE_TELEMETRY が用意され、既定値は true とされています。企業や受託開発の環境では、開発ツールのテレメトリ送信可否もセキュリティ・コンプライアンス確認の対象に含めてください。(Microsoft Learn)
管理者・SREが確認すべきこと
管理者やSREは、vNextエミュレーターを「本番に近い軽量な検証環境」と見なすのではなく、「開発と自動テストを高速化するローカルサービス」と位置付けるのが安全です。Azure Cosmos DB Emulatorは開発目的のローカル環境を提供するものですが、公式ドキュメントでは本番ワークロードでの利用は推奨されていません。(Microsoft Learn)
本番相当の判断が必要な以下の検証は、実際のAzure Cosmos DBアカウントで行うべきです。
| 本物のAzure Cosmos DBで確認すべきこと | 理由 |
|---|---|
| RU消費量とコスト見積もり | vNextではRequest Unitsが未実装とされているため |
| カスタムインデックスによるクエリ最適化 | カスタムインデックスポリシーはNo-op扱いのため |
| グローバル分散、整合性、フェールオーバー | ローカルエミュレーターではクラウドの分散特性を再現できないため |
| ストアドプロシージャ、トリガー、UDF | vNextでは未対応または将来対応予定なしとされているため |
| 本番相当の性能試験 | ローカルDocker環境の性能はクラウドサービスの性能ではないため |
対応機能と制限を整理する
Azure Cosmos DB Linux emulator vNextは、一般的なローカル開発には十分使いやすくなっていますが、すべてのAzure Cosmos DB機能を再現するものではありません。公式ドキュメントでは、Batch API、Bulk API、Change Feed、Patch、集計クエリ、JOIN、ORDER BY、ページング、サブドキュメントクエリなどが対応済みとして整理されています。(Microsoft Learn)
一方で、次のような制限には注意が必要です。
| 区分 | 機能・挙動 | 実務上の注意 |
|---|---|---|
| 対応済み | CRUD、Patch、Batch、Change Feed、JOIN、集計、ORDER BY、TTLなど | 一般的なアプリケーションテストに使いやすい |
| 一部未実装 | パーティション分割コレクションの並列クエリ、Read database feed、Read collection feedなど | SDKやアプリコードが該当APIを呼ぶ場合は事前検証が必要 |
| No-op | カスタムインデックスポリシー、コレクション更新、Offers、Users、Permissions、Client Encryption Keysなど | 成功レスポンスでも実際の動作検証にはならない |
| 未対応・予定なし | ストアドプロシージャ、トリガー、UDF | これらを使う既存アプリでは代替検証環境が必要 |
| 制限事項 | .NET SDKのbulk execution、巨大クエリ結果でのHTTP 500など | SDK別の制限とバッファ設定を確認する |
特にNo-opは見落としやすいポイントです。No-opの機能は、リクエストを受け付けて有効なHTTPステータスを返すものの、内部処理は実行されません。つまり、テストが成功しても「その機能が正しく動いた」とは限りません。カスタムインデックス、権限、暗号化キー、Offers周りを使うアプリでは、クラウド環境での追加テストを必ず残してください。(Microsoft Learn)
また、大きなクエリ結果でHTTP 500が出る場合は、--query-buffer-size または QUERY_BUFFER_SIZE_KB の調整が必要になることがあります。既定値は4MB、最大値は64MBとされているため、大量データを返す統合テストでは先に設定を見直しておくと原因切り分けが早くなります。(Microsoft Learn)
テストデータ投入はAzure Cosmos DB Shellとinitスクリプトを使う
vNextエミュレーターでは、Azure Cosmos DB Shellがコンテナーイメージに同梱されています。これにより、別途CLIをインストールしなくても、起動中のコンテナーに対して対話的に操作できます。(Microsoft for Developers)
docker exec -it cosmos-vnext cosmoshell.sh統合テストでは、初期データの投入をアプリ側のテストコードに書きすぎると、テストの見通しが悪くなります。vNextでは /init に配置した .csh スクリプトを起動時に実行できるため、データベース作成、コンテナー作成、seedデータ投入をコンテナー側に寄せられます。公式ブログでは、ENABLE_INIT_DATA=true を指定し、/init にマウントしたスクリプトを使ってテスト用データを準備する例が紹介されています。(Microsoft for Developers)
docker run --rm \
--name cosmos-vnext \
-e ENABLE_INIT_DATA=true \
-v "$(pwd)/init:/init" \
-p 8081:8081 \
-p 8080:8080 \
-p 1234:1234 \
mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest運用上は、次の2パターンを使い分けると分かりやすくなります。
| 使い方 | 向いている場面 |
|---|---|
--rm と /init で毎回作り直す | CI、再現性重視の統合テスト、バグ再現 |
/data をbind mountして永続化する | ローカル開発、手動検証、デモ環境 |
CIでは毎回クリーンな状態から始めるほうが、テストの失敗原因を追いやすくなります。逆にローカル開発では、毎回データが消えると確認作業が面倒になるため、--data-path とマウントを使って永続化する方針も検討できます。(Microsoft Learn)
AI・ベクトル検索アプリのローカル開発にも使える
今回のGAで注目したいのが、ベクトル検索のローカル検証です。公式ブログでは、Azure Cosmos DB vNext emulatorがベクトル検索をサポートし、ベクトル埋め込みポリシーとベクトルインデックスを定義して、VectorDistance() 関数による類似検索を実行できると説明されています。(Microsoft for Developers)
これにより、RAGアプリやセマンティック検索の開発で、最初からクラウド環境を使わずに次のような検証がしやすくなります。
| 活用シーン | 具体例 |
|---|---|
| RAGの試作 | ローカルモデルで埋め込みを作成し、Cosmos DBエミュレーターに保存して検索する |
| クエリ実装の検証 | VectorDistance() を使った検索結果の並び順やフィルター条件を確認する |
| サンプルアプリの配布 | Dockerとseedデータを含めて、読者やチームメンバーが同じ状態で試せる |
| オフライン開発 | Azure接続が不要な環境で、埋め込み、保存、検索の流れを確認する |
ただし、ベクトル検索の本番性能、レイテンシ、RU消費、インデックス設計の最終判断は、クラウド上のAzure Cosmos DBで確認すべきです。エミュレーターはローカルの機能検証には便利ですが、本番の負荷特性やコストまでは再現しません。
OpenTelemetryでローカル検証の観測性を高める
vNextエミュレーターはOpenTelemetryにも対応しています。公式ドキュメントでは、リクエスト率、クエリ実行時間、CPUやメモリなどのリソース利用、エラー率といったメトリックを、OTLP対応のバックエンドに出力できると説明されています。(Microsoft Learn)
有効化には、コマンドライン引数または環境変数を使います。
docker run --detach \
--name cosmos-vnext \
-e ENABLE_OTLP_EXPORTER=true \
--publish 8081:8081 \
--publish 8080:8080 \
--publish 1234:1234 \
mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latestローカルの統合テストでOpenTelemetryを使うと、「テストは通るがクエリが遅い」「特定の操作だけエラー率が高い」といった問題を早い段階で見つけやすくなります。特にAzure Cosmos DBを使ったアプリでは、データモデルやクエリ条件の設計ミスが後からコストや性能問題につながりやすいため、開発時点で観測の仕組みを入れておく価値があります。
既存環境から移行する手順
既存のAzure Cosmos DB Emulatorやクラウド検証用アカウントからvNextへ移行する場合は、一気に置き換えるのではなく、テストの種類ごとに段階的に移すのが安全です。
| 手順 | 作業内容 |
|---|---|
| 現状の洗い出し | 使っているAPI、SDK、接続モード、ストアドプロシージャ、トリガー、UDF、カスタムインデックスを確認する |
| 移行対象を決める | CRUD、クエリ、Change Feed、Batchなど、vNextで検証しやすいテストから移す |
| Docker構成を追加する | vnext-latestイメージ、ポート、Health probe、必要に応じてHTTPSを設定する |
| 接続設定を分離する | ローカル、CI、クラウド検証、本番の接続文字列を環境変数で切り替える |
| 初期データを整備する | /init の .csh スクリプトや /data 永続化方針を決める |
| SDK別の接続を確認する | .NET、Java、Node.js、PythonなどでTLSや接続設定を検証する |
| クラウド検証を残す | RU、インデックス、本番相当性能、未対応機能は実Azure Cosmos DBで確認する |
移行時に最も危険なのは、「エミュレーターで通ったので本番も問題ない」と判断してしまうことです。特にRequest Units、インデックス、パーティション設計、本番データ量でのクエリ性能は、エミュレーターだけでは判断できません。vNextは開発サイクルを短くするための道具であり、リリース前の最終確認環境ではない、とチーム内で明確にしておきましょう。
導入すべきケースと慎重に判断すべきケース
Azure Cosmos DB Linux emulator vNextは便利ですが、すべてのチームに同じ優先度で導入すべきものではありません。次の基準で判断すると、導入後の手戻りを減らせます。
| 判断 | 条件 |
|---|---|
| すぐ導入しやすい | Azure Cosmos DB for NoSQLを使っている |
| すぐ導入しやすい | Dockerベースの開発環境やCIをすでに使っている |
| すぐ導入しやすい | Apple Silicon Mac、Linux CI、Windows開発者が混在している |
| すぐ導入しやすい | CRUD、クエリ、Change Feed、Batch中心の統合テストを自動化したい |
| すぐ導入しやすい | RAGやベクトル検索のローカル試作を行いたい |
| 慎重に判断 | NoSQL以外のAPIを主に使っている |
| 慎重に判断 | ストアドプロシージャ、トリガー、UDFに依存している |
| 慎重に判断 | RU消費やコストをテストで確認したい |
| 慎重に判断 | カスタムインデックスの効果を検証したい |
| 慎重に判断 | 本番相当の負荷試験や可用性試験を行いたい |
開発初期や日常的な統合テストではvNextを使い、リリース前や性能・コスト判断では実際のAzure Cosmos DBを使う、という役割分担が現実的です。
管理者・開発者が次にやるべきこと
まず、既存アプリがAzure Cosmos DB for NoSQLを使っているか、vNextのサポート範囲に収まるかを確認してください。そのうえで、ローカルまたはCIに vnext-latest イメージを追加し、Health probe、SDKのHTTP/HTTPS設定、証明書、初期データ投入方法を最小構成で検証します。
導入時の優先順位は次の通りです。
| 優先度 | 実施内容 |
|---|---|
| 高 | vnext-latestでローカル起動し、アプリから接続できるか確認する |
| 高 | CIでは /ready を使って起動完了を待つ |
| 高 | .NET/JavaではHTTPSと証明書設定を確認する |
| 高 | 未対応機能やNo-op機能に依存していないか棚卸しする |
| 中 | /init スクリプトでテストデータ投入を自動化する |
| 中 | OpenTelemetryでクエリやエラーを観測できるようにする |
| 中 | ベクトル検索やRAGのローカル検証に使えるか試す |
| 低 | ローカル開発用の永続化ボリュームやデモ用データを整備する |
Azure Cosmos DB Linux emulator vNextのGAは、開発者にとって「Azure接続なしで素早く試す」「CIで同じDB状態を再現する」「AIアプリの検索処理をローカルで検証する」ための選択肢が強化された更新です。導入のコツは、本番相当の検証まで任せないことです。ローカル・CIではvNextで開発速度を上げ、性能・コスト・クラウド固有機能は実際のAzure Cosmos DBで確認する。この分担を守れば、開発効率と品質の両方を高めやすくなります。
コメント