Linux ベースのエミュレータ (プレビュー)

次世代の Azure Cosmos DB エミュレータは、完全に Linux ベースであり、Docker コンテナーとして使用できます。 さまざまなプロセッサとオペレーティング システムでの実行をサポートしています。

前提条件

• Docker

インストール

docker pull を使用して Docker コンテナー イメージを取得します。 コンテナー イメージは、 として mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-previewに公開されます。

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

ランニング

コンテナーを実行するには、docker run を使用します。 その後、docker ps を使用して、コンテナーが実行されていることを検証します。

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

docker ps

CONTAINER ID   IMAGE                                                             COMMAND                  CREATED         STATUS         PORTS                                                                                  NAMES
c1bb8cf53f8a   mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview  "/bin/bash -c /home/…"   5 seconds ago   Up 5 seconds   0.0.0.0:1234->1234/tcp, :::1234->1234/tcp, 0.0.0.0:8081->8081/tcp, :::8081->8081/tcp   <container-name>

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

Docker コマンド

次の表は、エミュレータを構成するために使用できる Docker コマンドをまとめています。 この表では、対応する引数、環境変数、使用できる値、既定の設定、および各コマンドの説明について詳しく説明します。

機能のサポート

このエミュレータは開発が進められ、プレビュー段階です。 その結果、すべての Azure Cosmos DB 機能がサポートされるわけではありません。 一部の機能は、今後もサポートされません。 この表には、さまざまな機能の状態とそのサポート レベルが記載されています。

制限事項

次の一覧には、まだサポートされていない機能や計画されていない機能に加えて、エミュレータの現在の制限事項が記載されています。

• Azure Cosmos DB 用の .NET SDK では、エミュレータでの一括実行はサポートされていません。
• .NET および Java SDK でエミュレータの HTTP モードはサポートされていません。

Java SDK の証明書をインストールする

このバージョンのエミュレータで Azure Cosmos DB 用の Java SDK を https モードで使用する場合は、その証明書をローカルの Java 信頼ストアにインストールする必要があります。

証明書を取得する

bash ウィンドウで、以下を実行します。

# If the emulator was started with /AllowNetworkAccess, replace localhost with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH

証明書のインストール

cacerts ファイルがある Java インストールのディレクトリに移動します (以下を正しいディレクトリで置き換えます)。

cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin"

証明書をインポートします (パスワードの入力を求められる場合があります。既定値は "changeit" です)。

keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

エイリアスが既に存在しているためにエラーが発生した場合は、削除してから、上記をもう一度実行します。

keytool -cacerts -delete -alias cosmos_emulator

継続的インテグレーション ワークフローでの使用

CI/CD パイプラインで Docker コンテナーを使用すると、特にデータベースなどのステートフル システムに対して多くの利点があります。 これは、テスト スイートのコスト効率、パフォーマンス、信頼性、一貫性の観点から考えられます。

エミュレーターは、CI/CD パイプラインの一部として組み込むことができます。 この GitHub リポジトリ を参照すると、 x64 アーキテクチャと ARM64 アーキテクチャの両方で 、.NET、Python、Java、Go アプリケーションの GitHub Actions CI ワークフローの一部としてエミュレーターを使用する方法の例を示します ( ubuntu を使用した Linux ランナーの場合に示されています)。

GitHub Actions CI ワークフローの例を次に示します。このワークフローでは、エミュレーターを GitHub Actions サービス コンテナー としてワークフロー内のジョブの一部として構成する方法を示します。 GitHub は Docker コンテナーの起動を処理し、ジョブの完了時に破棄します。これには手動の介入（docker run コマンドの使用など）は必要ありません。

name: CI demo app

on:
  push:
    branches: [main]
    paths:
      - 'java-app/**'
  pull_request:
    branches: [main]
    paths:
      - 'java-app/**'

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    services:
      cosmosdb:
        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
        ports:
          - 8081:8081
        env:
          PROTOCOL: https
        
    env:
      COSMOSDB_CONNECTION_STRING: ${{ secrets.COSMOSDB_CONNECTION_STRING }}
      COSMOSDB_DATABASE_NAME: ${{ vars.COSMOSDB_DATABASE_NAME }}
      COSMOSDB_CONTAINER_NAME: ${{ vars.COSMOSDB_CONTAINER_NAME }}

    steps:

      - name: Set up Java
        uses: actions/setup-java@v3
        with:
          distribution: 'microsoft'
          java-version: '21.0.0'

      - name: Export Cosmos DB Emulator Certificate
        run: |

          sudo apt update && sudo apt install -y openssl

          openssl s_client -connect localhost:8081 </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cosmos_emulator.cert

          cat cosmos_emulator.cert

          $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file cosmos_emulator.cert -storepass changeit -noprompt
      
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run tests
        run: cd java-app && mvn test

このジョブは Ubuntu ランナーで実行され、 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview Docker イメージをサービス コンテナーとして使用します。 環境変数を使用して、接続文字列、データベース名、コンテナー名を構成します。 この場合、ジョブは GitHub Actions ランナー コンピューターで直接実行されるため、ジョブ内の テストの実行 ステップは、 localhost:8081 を使用してエミュレーターにアクセスできます (8081 はエミュレーターによって公開されるポートです)。

Azure Cosmos DB Java SDK は現在、エミュレーターのHTTP モードをサポートしていないため、Cosmos DB Emulator 証明書のエクスポート手順は Java アプリケーションに固有です。 PROTOCOL環境変数は services セクションでhttpsに設定され、この手順ではエミュレーター証明書をエクスポートして Java キーストアにインポートします。 .NET にも同じことが当てはまります。

問題の報告

このバージョンのエミュレータの使用で問題が発生した場合は、GitHub のリポジトリ (https://github.com/Azure/azure-cosmos-db-emulator-docker) で問題を開き、ラベル cosmosEmulatorVnextPreview を使用してタグ付けします。