Azure Cosmos DB エミュレーターを開発・CIで使う方法と確認ポイント

Azure Cosmos DB エミュレーターを開発やCIで使うポイントは、本番用のAzure Cosmos DBを置き換えることではなく、ローカル開発・統合テスト・CIの再現性を高めることです。公式情報では、エミュレーターを開発用データベースとして使い、同じテストをローカル環境と継続的インテグレーション環境で実行する使い方が整理されています。(Microsoft Learn)

特に確認すべきなのは、Docker版とWindowsローカル版で対応APIが異なること、TLS/SSL証明書の扱い、CIでの起動方法、そして本番移行時にエンドポイントやキーだけでなく、スループット・整合性・リージョン構成などを別途検証する必要がある点です。この記事では、Azure Cosmos DB エミュレーターの変更点、影響範囲、開発者・管理者が確認すべき設定、移行・展開時の注意点を実務目線で整理します。

Azure Cosmos DB エミュレーターで何が変わるのか

今回の公式情報で重要なのは、Azure Cosmos DB エミュレーターが「開発PCで少し試すためのツール」だけではなく、CIに組み込んで統合テストを自動化する前提の開発基盤として扱われている点です。

エミュレーターを使うと、Azureサブスクリプションやサービス利用料金を発生させずに、データベース作成、コンテナー作成、アイテム登録、クエリ、SDK接続などをローカルで検証できます。ただし、Azure Cosmos DBクラウドサービスのすべてを再現するわけではありません。公式ドキュメントでも、エミュレーターは開発目的のローカル環境であり、運用ワークロードには推奨されていません。(Microsoft Learn)

実務上の変化は、次のように捉えると分かりやすいです。

観点	これまで起こりがちだった運用	今回確認すべき運用
ローカル開発	各開発者が個別にクラウド上の開発DBへ接続	エミュレーターを使い、ローカルで基本動作を検証
CI	単体テストのみ実行し、DB操作は手元で確認	GitHub Actionsなどでエミュレーターを起動し、DB操作を含むテストを自動化
接続情報	localhost や固定キーをコードに直書き	環境変数や設定ファイルでエンドポイント・キーを切り替え
証明書	SSLエラー時に検証を無効化して放置	Docker版では証明書を取り込み、TLS検証を維持
本番移行	エミュレーターで動けば本番も同じと判断	RU、整合性、リージョン、サーバーレス可否などを本番環境で追加検証

影響を受ける対象者

Azure Cosmos DB エミュレーターの開発・CI利用で影響を受けるのは、主に次の担当者です。

対象者	確認すべきポイント
アプリ開発者	SDKの接続先、TLS/SSL証明書、コンテナー作成、パーティションキー、テストデータの初期化
CI/CD担当者	GitHub ActionsやAzure DevOpsでの起動方法、Windowsランナー・Dockerランナーの選定、ポート競合
インフラ管理者	開発端末の要件、Docker Desktopの利用可否、ファイアウォール、ネットワークアクセス設定
セキュリティ担当者	既定キーの扱い、証明書検証の無効化禁止、接続情報のシークレット管理
アーキテクト	エミュレーターと本番Azure Cosmos DBの差分、サーバーレス・マルチリージョン・整合性の検証範囲

特に注意したいのは、CIでテストが成功しても、本番性能や可用性まで保証されるわけではない点です。エミュレーターはデータモデルやSDK接続、基本的なCRUD処理の確認には有効ですが、グローバル分散、スケールアウト、実際のRU消費、障害時の挙動までは本番相当の検証環境で確認する必要があります。

利用形態はDocker版とWindowsローカル版で選ぶ

Azure Cosmos DB エミュレーターには複数の利用形態があります。選定を誤ると、使いたいAPIが動かない、CIで起動できない、証明書エラーが解消できないといったトラブルにつながります。

利用形態	向いているケース	主な注意点
Docker Linuxコンテナー	CIや開発環境をコンテナーで統一したい場合	API対応範囲を事前確認。証明書の取り込みが必要になる
Docker Windowsコンテナー	Windowsベースのコンテナー運用に合わせたい場合	MongoDB用APIはサポートされない
Windowsローカル版	Windows開発PCで幅広いAPIを試したい場合	管理者権限、ローカル証明書、ファイアウォール設定を確認
Linuxベース vNextプレビュー	LinuxランナーやARM64環境で新しい構成を検証したい場合	プレビューであり、NoSQL用APIのゲートウェイモードなど対応範囲が限定される

公式情報では、Docker版のエミュレーターはAPI for Apache Cassandra、API for Apache Gremlin、API for Tableをサポートしないとされています。また、Docker WindowsコンテナーはAPI for MongoDBをサポートしません。(Microsoft Learn)

一方、Windowsローカル版のコマンドラインリファレンスでは、NoSQL、MongoDB、Cassandra、Gremlin、Table向けの起動パラメーターが整理されています。複数APIを扱うプロジェクトでは、Dockerで済ませるのか、Windowsローカル版を使うのかを最初に決めておくべきです。(Microsoft Learn)

開発環境で確認すべき前提条件

公式ドキュメントでは、開発に使う言語環境として .NET 6以降、Node.js v20以降、Python 3.7以降が前提として示されています。Windowsローカル版では64bitのWindows Server 2019、Windows 10、Windows 11が対象で、最低要件として2GB RAMと10GBの空きディスク容量が示されています。Docker版ではDocker Desktopが前提です。(Microsoft Learn)

開発チームでは、次の項目を標準化しておくとトラブルを減らせます。

項目	推奨する確認内容
実行方式	Windowsローカル版かDocker版かをプロジェクトで統一する
SDKバージョン	使用言語ごとにサポート対象のSDKを明記する
接続先	localhost:8081 を直接書かず、環境変数で管理する
テストデータ	テスト開始時にDB・コンテナーを作成し、終了時に削除する
証明書	Docker版ではエミュレーター証明書を開発PCやCIに取り込む
ポート	8081やDirect接続用ポートが他サービスと競合しないか確認する

Docker版エミュレーターを使う場合の設定ポイント

Docker版を使う場合、最初にMicrosoft Container Registryからイメージを取得します。NoSQL向けの基本的な流れは、イメージをpullし、必要なポートを公開してコンテナーを起動する形です。

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

NoSQL用APIでDockerコンテナーを起動する場合は、少なくともエミュレーターのゲートウェイで使う8081番ポートを公開します。Direct接続を使う構成では、10250〜10255番台のポート公開も確認が必要です。

docker run \
  --publish 8081:8081 \
  --publish 10250-10255:10250-10255 \
  --name cosmos-emulator \
  --detach \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

MongoDB用APIを使う場合は、MongoDB向けのタグや環境変数を確認します。公式情報では、MongoDBエンドポイントのバージョンとして3.2、3.6、4.0が示されています。(Microsoft Learn)

docker run \
  --publish 8081:8081 \
  --publish 10250:10250 \
  --env AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0 \
  --name cosmos-mongodb-emulator \
  --detach \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

Docker版で特に重要なのは、次の環境変数です。

設定	用途	確認ポイント
AZURE_COSMOS_EMULATOR_PARTITION_COUNT	パーティション数の指定	テストで作るコンテナー数が多い場合に確認
AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE	エミュレーター停止後もデータを保持	CIでは通常無効、ローカル検証では必要に応じて有効
AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE	IPアドレスの上書き	コンテナー外から接続する場合に確認
AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT	MongoDBエンドポイントの有効化	MongoDB用APIを使う場合のみ設定

CIではデータの永続化を避け、毎回クリーンな状態でテストを開始するのが基本です。逆にローカル開発で画面確認や手動検証を繰り返す場合は、データ永続化を有効にすると作業効率が上がります。

Windowsローカル版を使う場合の設定ポイント

Windowsローカル版は、インストーラーを管理者権限で実行すると、開発者証明書やファイアウォール規則が自動で構成されます。公式ドキュメントでも、WindowsローカルインストールではTLS/SSL証明書が自動的にインポートされるため、追加操作は不要とされています。(Microsoft Learn)

起動はスタートメニューから行うか、次のように実行ファイルを使います。

Microsoft.Azure.Cosmos.Emulator.exe

ポートを変更したい場合は、/Port を指定します。

Microsoft.Azure.Cosmos.Emulator.exe /Port=65000

APIごとの起動例は次の通りです。

API	起動例
Cassandra	Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint /CassandraPort=65200
Gremlin	Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint /GremlinPort=65400
Table	Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint /TablePort=65500
MongoDB	Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=4.0 /MongoPort=65200

管理者が確認すべきなのは、開発者が勝手にポートを変更してチーム内の手順が分岐しないようにすることです。接続エラーの多くは、SDK側のエンドポイント、エミュレーター側のポート、ファイアウォール設定の不一致で発生します。

SDK接続ではエンドポイントとキーを環境変数で切り替える

エミュレーターの既定エンドポイントは一般的に https://localhost:8081/ です。公式ドキュメントでは、各SDKからエミュレーターの資格情報を使って接続する例が示されています。(Microsoft Learn)

ただし、実務では接続情報をコードに直書きしないでください。次のように環境変数で切り替える構成にしておくと、本番移行やCI実行が安全になります。

COSMOS_ENDPOINT=https://localhost:8081/
COSMOS_KEY=local-emulator-key
COSMOS_DATABASE=app-dev
COSMOS_CONTAINER=items

アプリ側では、ローカル、CI、Azure上の開発環境、本番環境で同じコードを使い、設定だけを差し替える形にします。

ローカル開発: COSMOS_ENDPOINT=https://localhost:8081/
CI:          COSMOS_ENDPOINT=https://localhost:8081/
検証環境:    COSMOS_ENDPOINT=https://<dev-account>.documents.azure.com:443/
本番環境:    COSMOS_ENDPOINT=https://<prod-account>.documents.azure.com:443/

この設計にしておくと、エミュレーターからAzure Cosmos DBアカウントへ移行するときに、アプリケーションコードの修正を最小限にできます。

TLS/SSL証明書エラーは「無効化して終わり」にしない

Docker版エミュレーターでSDK接続すると、TLS/SSL証明書エラーが出ることがあります。公式情報では、エミュレーターの証明書を取り込む手順が案内されており、Windowsローカル版では証明書が自動インポートされます。(Microsoft Learn)

Docker版では、次のように証明書を取得します。

curl --insecure https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

Linux環境では証明書ストアへ配置し、証明書バンドルを更新します。

sudo cp ~/emulatorcert.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

Windows環境では証明書ストアに取り込みます。

Import-Certificate `
  -FilePath emulatorcert.crt `
  -CertStoreLocation Cert:\CurrentUser\Root

開発中に一時的な回避策として証明書検証を無効化する例はありますが、その設定を本番コードや共有ライブラリに残すのは危険です。特にNode.jsの NODE_TLS_REJECT_UNAUTHORIZED=0 や、.NETの証明書検証無効化設定は、ローカル検証用に限定し、CIや本番向け設定とは明確に分離してください。

CIで使う場合はGitHub Actionsのランナーと起動方法を確認する

公式情報では、GitHub Actionsの windows-latest ランナーにAzure Cosmos DB エミュレーターがプレインストールされていることが示されており、PowerShellモジュールでエミュレーターを起動してからテストを実行する例が紹介されています。(Microsoft Learn)

.NETの例としては、次のような流れになります。

name: Continuous Integration

on:
  push:
    branches:
      - main

jobs:
  unit_tests:
    runs-on: windows-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Start Azure Cosmos DB emulator
        shell: powershell
        run: |
          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
          Start-CosmosDbEmulator

      - name: Run tests
        run: dotnet test

Pythonなら pytest、Node.jsなら mocha など、使用するテストランナーに置き換えます。重要なのは、テスト実行前にエミュレーターが起動し、接続を受け付けられる状態になっていることです。

CIでは次の点を必ず確認してください。

確認項目	理由
ランナーOS	Windowsローカル版を使うならWindowsランナーが必要
起動完了待ち	起動直後にテストを走らせると接続エラーになる
ポート競合	8081番が他プロセスに使われていないか確認
テストデータ初期化	前回実行のデータに依存しないようにする
接続情報	GitHub Secretsや環境変数で管理する
証明書	DockerやLinuxランナーでは証明書取り込みが必要になる場合がある

なお、Azure DevOpsで古いWindows 2016ホストランナーを前提にしたエミュレーター利用手順は、現在の環境ではそのまま使えない場合があります。公式情報でも、Windows 2016ホストランナー削除に伴い、従来のAzure DevOpsビルドタスク方式がサポートされなくなった旨が説明されています。Azure DevOpsを使う場合は、Windows 2019以降のエージェント、セルフホステッドエージェント、またはDockerベースの構成を検討してください。(Microsoft Learn)

LinuxベースvNextプレビューを使う場合の注意点

LinuxベースのAzure Cosmos DB エミュレーター vNextは、Dockerコンテナーとして利用でき、さまざまなプロセッサやOSでの実行を想定したプレビュー版です。ただし、公式情報ではNoSQL用APIのゲートウェイモードと一部機能のみがサポート対象とされています。(Microsoft Learn)

起動例は次の通りです。

docker run --detach \
  --publish 8081:8081 \
  --publish 8080:8080 \
  --publish 1234:1234 \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

vNextプレビューでは、ヘルスプローブのエンドポイントが用意されています。

エンドポイント	用途
http://localhost:8080/alive	Liveness Probe
http://localhost:8080/ready	Readiness Probe
http://localhost:8080/status	詳細ステータス

CIで使う場合は、ログメッセージだけを見て起動完了と判断するより、/ready を使って準備完了を確認する方が安定します。公式情報でも、従来の準備完了ログは今後削除される可能性があり、ヘルスプローブの利用が推奨されています。(Microsoft Learn)

ただし、プレビュー版は本番相当の検証基盤として固定するには慎重な判断が必要です。対応機能、SDKとの相性、CIでの再現性を確認したうえで、正式版のエミュレーターやWindowsローカル版と使い分けてください。

エミュレーターと本番Azure Cosmos DBの違い

Azure Cosmos DB エミュレーターは便利ですが、クラウドサービスの完全な複製ではありません。公式情報では、エミュレーターはサーバーレススループットをサポートしないこと、複数リージョンや複数インスタンスへのレプリケーションができないこと、スケールアウトできないことなどが説明されています。(Microsoft Learn)

本番移行前に、次の差分を確認してください。

項目	エミュレーターで確認できること	本番環境で追加確認すべきこと
データモデル	パーティションキー、JSON構造、基本CRUD	実データ量でのホットパーティション、RU消費
クエリ	SQLクエリやSDK経由の取得処理	インデックス、クエリコスト、ページング性能
スループット	プロビジョニング前提の基本動作	サーバーレス、オートスケール、RU制限
整合性	設定値の扱い、SDK動作	複数リージョン時の整合性、レイテンシ
可用性	ローカル単一環境での動作	フェールオーバー、リージョン障害、冗長化
セキュリティ	キー認証、TLS接続	Microsoft Entra ID、RBAC、ネットワーク制限
運用監視	基本的な接続・例外確認	メトリック、ログ、アラート、コスト監視

エミュレーターで合格にしてよいのは、主に「アプリケーションコードが期待通りにDB操作できるか」です。性能、可用性、コスト、セキュリティポリシーの最終判断は、Azure上の検証環境で行う必要があります。

管理者が確認すべき設定チェックリスト

開発者にエミュレーター利用を任せきりにすると、チームごとに環境がばらつきます。管理者やリードエンジニアは、次のチェックリストを用意しておくと展開がスムーズです。

チェック項目	判断基準
利用方式	Docker版、Windowsローカル版、vNextプレビューのどれを標準にするか
対応API	NoSQL、MongoDB、Cassandra、Gremlin、Tableのどれを使うか
OS要件	Windows 10/11、Windows Server、Docker Desktopの要件を満たすか
証明書	Docker版で証明書を取り込む手順を文書化しているか
ポート	8081、10250〜10255などの利用可否を確認しているか
接続情報	.env、ユーザーシークレット、CIのSecretsで管理しているか
テストデータ	テストごとに初期化できるか
CI起動	エミュレーター起動後にテストが走る構成になっているか
本番差分	RU、整合性、リージョン、サーバーレスを別途検証しているか
セキュリティ	TLS検証無効化や固定キーの扱いをルール化しているか

このチェックリストは、開発環境構築手順書やCIテンプレートに組み込むのがおすすめです。個人のメモではなく、リポジトリ内の docs/ や README.md に残しておくと、新規メンバーの立ち上がりも早くなります。

開発者が失敗しやすいポイント

Azure Cosmos DB エミュレーターの導入でよくある失敗は、機能不足ではなく「前提の認識違い」です。

失敗例	原因	対策
Docker版でCassandraやGremlinを使おうとして動かない	Docker版の対応APIを確認していない	Windowsローカル版の利用を検討する
CIでテストがたまに失敗する	エミュレーター起動完了前にテストが始まる	起動待ち、ヘルスチェック、リトライを入れる
ローカルでは動くが本番で失敗する	localhost や既定キーをコードに直書き	環境変数で接続情報を切り替える
SSLエラーを無理に回避している	証明書を正しく取り込んでいない	エミュレーター証明書を信頼ストアへインポートする
本番性能を過信する	エミュレーターでRUや分散構成を再現できない	Azure上の検証環境で負荷・コストを確認する
テストがデータ順序に依存する	前回実行のデータが残っている	テスト開始時にDBを作り直す
ポート競合で起動しない	8081などが別サービスに使われている	ポート変更とSDK設定をセットで管理する

特にCIでは、テストの独立性が重要です。エミュレーターにデータを永続化してしまうと、前回のテストデータが残り、成功・失敗が実行順に依存することがあります。CIでは原則として、毎回クリーンなエミュレーターを起動し、テスト内で必要なデータを作成する設計にしましょう。

本番移行時に確認すべきこと

エミュレーターからAzure Cosmos DBアカウントへ移行するときは、接続先を変えるだけでは不十分です。次の順序で確認すると、手戻りを減らせます。

手順	確認内容
接続情報の切り替え	エンドポイント、キー、データベース名、コンテナー名を環境変数で差し替える
コンテナー設計	パーティションキー、インデックス、TTL、ユニークキーを確認する
スループット	プロビジョニング、オートスケール、サーバーレスのどれを使うか決める
クエリ性能	代表的なクエリのRU消費とレイテンシを測る
認証	キー認証だけでよいか、Microsoft Entra IDやRBACを使うか検討する
ネットワーク	ファイアウォール、プライベートエンドポイント、許可IPを確認する
監視	Azure Monitor、ログ、アラート、コスト監視を設定する
障害対応	リージョン冗長化、バックアップ、復旧手順を確認する

実務では、エミュレーターを「開発の最初の関門」、Azure上の開発環境を「本番前の検証関門」として使い分けるのが安全です。エミュレーターだけでリリース判断を完結させないようにしましょう。

導入時のおすすめ構成

小規模な開発チームなら、次のような構成から始めると無理がありません。

用途	推奨構成
個人開発	Docker版エミュレーターまたはWindowsローカル版
チーム開発	Docker Composeで起動手順を統一
CI	GitHub ActionsのWindowsランナーでエミュレーター起動、またはDockerサービスとして起動
本番前検証	実際のAzure Cosmos DBアカウントでRU、整合性、ネットワーク、監視を確認
ドキュメント	READMEに起動手順、接続情報、証明書、テスト実行方法を記載

ローカル開発で最初に整えるべきファイルは、docker-compose.yml、.env.example、テストデータ初期化スクリプト、CIワークフローの4つです。これらをリポジトリに入れておけば、開発者ごとの差分を抑えられます。

services:
  cosmos-emulator:
    image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest
    container_name: cosmos-emulator
    ports:
      - "8081:8081"
      - "10250-10255:10250-10255"

このような最小構成から始め、必要に応じてMongoDB用API、データ永続化、証明書インポート、CI用のヘルスチェックを追加していくと、導入の負担を抑えられます。

まず何をすべきか

Azure Cosmos DB エミュレーターを開発・CIに取り入れるなら、最初にやるべきことは明確です。

1つ目は、プロジェクトで使うAPIを確認し、Docker版で足りるのか、Windowsローカル版が必要なのかを決めることです。2つ目は、SDKの接続情報を環境変数化し、ローカル・CI・Azure環境で同じコードを使えるようにすることです。3つ目は、CIでエミュレーターを起動し、データベース操作を含むテストを毎回自動実行することです。

エミュレーターは、Azure Cosmos DBの本番環境を完全に再現するものではありません。しかし、開発初期のデータモデル検証、SDK接続、CRUD処理、統合テスト、CIの品質向上には非常に有効です。ローカルで素早く試し、CIで自動検証し、本番前にAzure上で性能と運用要件を確認する。この3段階で使い分けることが、Azure Cosmos DB エミュレーターを安全かつ効果的に活用するポイントです。