MENU

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

Azure

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

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

ITtripTOOLS
その「面倒」、無料で解決。 ITtripがつくる、6つの道具。 無料ツール一覧へ すべて無料・追加課金なし
先頭0を守るCSV編集こわさないCSV PDFに直接書き込みかけるPDF 写真＋説明をPDFに写レポ スマホ⇄PCで共有コピペ便 · 文章・写真 みんなの日程を調整日程Fit 匿名質問・投票を集めるKOEQ
目次

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_OVERRIDEIPアドレスの上書きコンテナー外から接続する場合に確認
AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINTMongoDBエンドポイントの有効化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起動例
CassandraMicrosoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint /CassandraPort=65200
GremlinMicrosoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint /GremlinPort=65400
TableMicrosoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint /TablePort=65500
MongoDBMicrosoft.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では次の点を必ず確認してください。

確認項目理由
ランナーOSWindowsローカル版を使うなら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/aliveLiveness Probe
http://localhost:8080/readyReadiness 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プレビューのどれを標準にするか
対応APINoSQL、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で起動手順を統一
CIGitHub 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 エミュレーターを安全かつ効果的に活用するポイントです。

Azure
Azure Cosmos DB CI ローカル開発 エミュレーター

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次