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

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

Предпосылки

• Docker

Installation

Получение образа контейнера 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 8080:8080 --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>

Эмулятор включает два компонента:

• Data Explorer — интерактивное изучение данных в эмуляторе. По умолчанию этот компонент выполняется через порт 1234.
• эмулятор Azure Cosmos DB — локальная версия службы базы данных Azure Cosmos DB. По умолчанию этот компонент выполняется через порт 8081.

Конечная точка шлюза эмулятора использует порт 8081 по адресу http://localhost:8081. Чтобы перейти к Data Explorer, используйте адрес http://localhost:1234 в веб-браузере. Конечная точка шлюза обычно доступна немедленно, но интерфейс Data Explorer может запуститься через несколько секунд.

Проверка состояния здоровья

Эмулятор предоставляет конечную точку пробы работоспособности через порт 8080. Используйте эту конечную точку, чтобы определить, когда эмулятор полностью инициализирован и готов принимать запросы.

Доступны следующие конечные точки:

• http://localhost:8080/alive — Проверка на работоспособность (liveness).
• http://localhost:8080/ready — проверка готовности.
• http://localhost:8080/status — подробное состояние.

Режим HTTPS

Пакеты SDK для .NET и Java не поддерживают режим HTTP в эмуляторе. Так как эта версия эмулятора начинается с HTTP по умолчанию, необходимо явно включить HTTPS при запуске контейнера (см. ниже). Для Java SDK вам также потребуется установить сертификаты.

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

При использовании HTTPS с сохраненными томами данных эмулятор автоматически создает SSL-сертификаты при запуске, поэтому вам не нужно управлять продлением сертификата.

Команды Docker

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

Поддержка функций

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

Ограничения

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

• Пакет SDK .NET для Azure Cosmos DB не поддерживает массовое выполнение в эмуляторе.
• Если вы получаете ошибки HTTP 500 для больших результатов запроса, увеличьте размер буфера запроса с помощью флага --query-buffer-size или переменной среды QUERY_BUFFER_SIZE_KB. Значение по умолчанию — 4096 КБ (4 МБ), а максимальное — 65536 КБ (64 МБ).

Установка сертификатов для пакета 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

Поддержка OpenTelemetry

OpenTelemetry — это платформа наблюдения с открытым кодом, которая предоставляет набор средств, API и пакетов SDK для инструментирования, создания, сбора и экспорта данных телеметрии. Протокол OpenTelemetry (OTLP) — это протокол, используемый OpenTelemetry для передачи данных телеметрии между компонентами.

С эмулятором можно использовать OpenTelemetry для мониторинга и трассировки приложения. Эмулятор поддерживает параметры телеметрии, которые можно настроить с помощью переменных среды или флагов командной строки при запуске контейнера Docker.

Эмулятор экспортирует следующие метрики. Они доступны через любой бэкенд метрик, который поддерживает OTLP и предоставляет ценные сведения о производительности и состоянии базы данных.

• Тарифы запросов. Отображение шаблонов трафика для различных типов операций
• Время выполнения запроса: измеряет время, затраченное на выполнение различных запросов
• Использование ресурсов: метрики ЦП, использования памяти и пула подключений
• Частота ошибок: отслеживание ошибок по типу и конечной точке

Подробные инструкции с примерами доступны в репозитории GitHub.

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

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

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

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

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

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