Emulador basado en Linux: vNext (versión preliminar)

La próxima generación del emulador de Azure Cosmos DB está totalmente basada en Linux y está disponible como contenedor de Docker. Admite la ejecución en una amplia variedad de procesadores y sistemas operativos.

Prerequisites

• Docker

Instalación

Obtenga la imagen de contenedor de Docker mediante docker pull. La imagen de contenedor se publica en el Registro de artefactos Microsoft como mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

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

Correr

Para ejecutar el contenedor, use docker run. Después, use docker ps para validar que el contenedor se está ejecutando.

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>

El emulador incluye dos componentes:

• Data Explorer: explore interactivamente los datos en el emulador. De forma predeterminada, este componente se ejecuta en el puerto 1234.
• Azure Cosmos DB emulator: una versión local del servicio de base de datos de Azure Cosmos DB. De forma predeterminada, este componente se ejecuta en el puerto 8081.

El punto de conexión de la puerta de enlace del emulador usa el puerto 8081 en la dirección http://localhost:8081. Para ir al Data Explorer, use la dirección http://localhost:1234 en el explorador web. Normalmente, el punto de conexión del gateway está disponible inmediatamente, pero Data Explorer puede tardar unos segundos en iniciarse.

Sondeo de salud

El emulador expone un punto de conexión de sondeo de estado en el puerto 8080. Use este punto de conexión para determinar cuándo se inicializa completamente el emulador y está listo para aceptar solicitudes.

Están disponibles los siguientes puntos de conexión:

• http://localhost:8080/alive — Sondeo de vida.
• http://localhost:8080/ready — Sondeo de preparación.
• http://localhost:8080/status — Estado detallado.

Modo HTTPS

Los SDK de .NET y Java no admiten el modo HTTP en el emulador. Dado que esta versión del emulador comienza con HTTP de forma predeterminada, deberá habilitar explícitamente HTTPS al iniciar el contenedor (consulte a continuación). Para el SDK de Java, también deberá instalar certificados.

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

Cuando se usa HTTPS con volúmenes de datos persistentes, el emulador regenera automáticamente los certificados SSL al iniciarse, por lo que no es necesario administrar la renovación de certificados.

Comandos de Docker

En la tabla siguiente se resumen los comandos de Docker disponibles para configurar el emulador. En esta tabla se detallan los argumentos correspondientes, las variables de entorno, los valores permitidos, la configuración predeterminada y las descripciones de cada comando.

Soporte de funcionalidades

Este emulador está en desarrollo activo y versión preliminar. Como resultado, no se admiten todas las características de Azure Cosmos DB. Algunas características tampoco se admitirán en el futuro. En esta tabla se incluye el estado de varias características y su nivel de compatibilidad.

Limitaciones

Además de las características que aún no se admiten o no están planeadas, la lista siguiente incluye las limitaciones actuales del emulador.

• El SDK de .NET para Azure Cosmos DB no admite la ejecución masiva en el emulador.
• Si obtiene errores HTTP 500 en resultados de consulta de gran tamaño, aumente el tamaño del búfer de consulta con la --query-buffer-size bandera o la variable de entorno QUERY_BUFFER_SIZE_KB. El valor predeterminado es 4096 KB (4 MB) y el máximo es 65536 KB (64 MB).

Instalación de certificados para el SDK de Java

Al usar el SDK de Java para Azure Cosmos DB con esta versión del emulador en modo https, es necesario instalar sus certificados en el almacén de confianza de Java local.

Obtención del certificado

En una ventana bash, ejecute lo siguiente:

# 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

Instalación del certificado

Vaya al directorio de la instalación de Java donde se encuentra el archivo cacerts (reemplace a continuación por el directorio correcto):

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

Importe el certificado (es posible que se le pida una contraseña, el valor predeterminado es "changeit"):

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

Si recibe un error porque el alias ya existe, elimínelo y vuelva a ejecutar lo anterior:

keytool -cacerts -delete -alias cosmos_emulator

Compatibilidad con OpenTelemetry

OpenTelemetry es un marco de observabilidad de código abierto que proporciona una colección de herramientas, API y SDK para instrumentar, generar, recopilar y exportar datos de telemetría. OpenTelemetry Protocol (OTLP) es el protocolo usado por OpenTelemetry para transmitir datos de telemetría entre componentes.

Puede usar OpenTelemetry con el emulador para supervisar y realizar un seguimiento de la aplicación. El emulador admite opciones de telemetría, que se pueden configurar a través de variables de entorno o marcas de línea de comandos al ejecutar el contenedor de Docker.

El emulador exporta las métricas siguientes. Están disponibles a través de cualquier back-end de métricas que admita OTLP y proporcione información valiosa sobre el rendimiento y el estado de la base de datos:

• Tasas de solicitud: muestra los patrones de tráfico para diferentes tipos de operación
• Tiempos de ejecución de consultas: mide el tiempo necesario para ejecutar consultas diferentes.
• Uso de recursos: métricas de uso de CPU, uso de memoria y grupo de conexiones
• Tasas de error: seguimiento de errores por tipo y punto de conexión

Las instrucciones detalladas con ejemplos están disponibles en el repositorio de GitHub.

Uso en el flujo de trabajo de integración continua

Hay muchas ventajas para usar contenedores de Docker en canalizaciones de CI/CD, especialmente para sistemas con estado como bases de datos. Esto podría ser en términos de rentabilidad, rendimiento, confiabilidad y coherencia de los conjuntos de pruebas.

El emulador se puede incorporar como parte de las canalizaciones de CI/CD. Puede consultar este repositorio de GitHub que proporciona ejemplos de cómo utilizar el emulador como parte de un flujo de trabajo de integración continua (CI) de Acciones de GitHub para aplicaciones en .NET, Python, Java y Go en arquitecturas x64 y ARM64 (demostrado para el ejecutor de Linux mediante ubuntu).

Este es un ejemplo de un flujo de trabajo de CI de Acciones de GitHub que muestra cómo configurar el emulador como un contenedor de servicio Acciones de GitHub como parte de un trabajo en el flujo de trabajo. GitHub se encarga de iniciar el contenedor de Docker y lo destruye cuando se completa el trabajo, sin necesidad de intervención manual (por ejemplo, usar el comando 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

Este trabajo se ejecuta en un ejecutor de Ubuntu y usa la mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview imagen de Docker como contenedor de servicios. Usa variables de entorno para configurar la cadena de conexión, el nombre de la base de datos y el nombre del contenedor. Dado que en este caso el trabajo se ejecuta directamente en la máquina del ejecutor de Acciones de GitHub, el paso Run tests del trabajo puede acceder al emulador utilizando localhost:8081 (8081 es el puerto expuesto por el emulador).

El paso Exportar certificado del emulador de Cosmos DB es específico de las aplicaciones Java, ya que el SDK de Java de Azure Cosmos DB no admite HTTP actualmente el modo en el emulador. La variable de entorno PROTOCOL se establece en https en la sección services y este paso exporta el certificado del emulador e impórtelo en el almacén de claves de Java. Lo mismo se aplica también a .NET.

Información sobre los problemas

Si tiene problemas con el uso de esta versión del emulador, abra un problema en el repositorio de GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) y etiquete con la etiqueta cosmosEmulatorVnextPreview.