Эмулятор на основе Linux (предварительная версия)

Следующее поколение эмулятора Azure Cosmos DB полностью основано на Linux и доступно в качестве контейнера Docker. Он поддерживает работу в различных процессорах и операционных системах.

Предварительные условия

• Docker

Установка

Получение образа контейнера Docker с помощью docker pull. Образ контейнера публикуется в Реестр артефактов Microsoft как 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. Некоторые функции также не будут поддерживаться в будущем. Эта таблица включает состояние различных функций и их уровень поддержки.

Ограничения

Помимо функций, которые еще не поддерживаются или не запланированы, в следующем списке содержатся текущие ограничения эмулятора.

• Пакет SDK для .NET для Azure Cosmos DB не поддерживает массовое выполнение в эмуляторе.
• Пакеты SDK для .NET и Java не поддерживают режим HTTP в эмуляторе.

Установка сертификатов для пакета SDK для Java

При использовании пакета SDK Java для Azure Cosmos DB с этой версией эмулятора в режиме 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

Установка сертификата

Перейдите в каталог установки java, где cacerts находится файл (замените ниже правильным каталогом):

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

Использование в рабочем процессе непрерывной интеграции

Существует множество преимуществ использования контейнеров Docker в конвейерах CI/CD, особенно для систем с отслеживанием состояния, таких как базы данных. Это может быть с точки зрения экономичности, производительности, надежности и согласованности наборов тестов.

Эмулятор может быть включен в составе конвейеров CI/CD. Вы можете обратиться к этому репозиторию GitHub , который содержит примеры использования эмулятора в рамках рабочего процесса CI GitHub Actions для .NET, Python, Java и Go приложений в обоих x64 и ARM64 архитектурах (демонстрируется для запуска Linux с помощью ubuntu).

Ниже приведен пример рабочего процесса CI GitHub Actions, который показывает, как настроить эмулятор в качестве контейнера службы 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 в качестве контейнера службы. Он использует переменные среды для настройки строки подключения, имени базы данных и имени контейнера. Так как в этом случае задание выполняется непосредственно на компьютере runner GitHub Actions, шаг выполнения тестов в задании, может получить доступ к эмулятору, который доступен через localhost:8081 (8081 является портом, предоставляемым эмулятором).

Шаг "Экспорт сертификата эмулятора Cosmos DB " зависит от приложений Java, так как пакет SDK Java для Azure Cosmos DB в настоящее время не поддерживает HTTP режим в эмуляторе. Переменная PROTOCOL среды задана https в services разделе, и этот шаг экспортирует сертификат эмулятора и импортирует его в хранилище ключей Java. Это же относится и к .NET.

Создание отчетов о проблемах

При возникновении проблем с использованием этой версии эмулятора откройте проблему в репозитории GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) и пометьте ее меткой cosmosEmulatorVnextPreview.