Émulateur Linux - vNext (préversion)

La nouvelle génération de l’émulateur Azure Cosmos DB est entièrement basée sur Linux et est disponible sous forme de conteneur Docker. Il prend en charge l’exécution sur une grande variété de processeurs et de systèmes d’exploitation.

Prerequisites

• Docker

Installation

Obtenez l’image du conteneur Docker en utilisant docker pull. L'image du conteneur est publiée dans le Registre des artefacts Microsoft sous le nom mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

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

Course à pied

Pour exécuter le conteneur, utilisez docker run. Ensuite, utilisez docker ps pour valider que le conteneur est en cours d'exécution.

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>

L’émulateur comprend deux composants :

• Data Explorer : explorez de manière interactive les données dans l’émulateur. Par défaut, ce composant s’exécute sur le port 1234.
• Azure Cosmos DB émulateur : version locale du service de base de données Azure Cosmos DB. Par défaut, ce composant s’exécute sur le port 8081.

Le point de terminaison de passerelle de l’émulateur utilise le port 8081 à l’adresse http://localhost:8081. Pour accéder au Data Explorer, utilisez l’adresse http://localhost:1234 dans votre navigateur web. Le point de terminaison de passerelle est généralement disponible immédiatement, mais Data Explorer peut prendre quelques secondes pour démarrer.

Sonde de santé

L’émulateur expose un point de terminaison de sonde d’intégrité sur le port 8080. Utilisez ce point de terminaison pour déterminer quand l’émulateur est entièrement initialisé et prêt à accepter les demandes.

Les points de terminaison suivants sont disponibles :

• http://localhost:8080/alive — Sonde Liveness.
• http://localhost:8080/ready — Sonde de préparation.
• http://localhost:8080/status — État détaillé.

Mode HTTPS

Les Kits de développement logiciel (SDK) .NET et Java ne prennent pas en charge le mode HTTP dans l'émulateur. Étant donné que cette version de l’émulateur commence par HTTP par défaut, vous devez activer explicitement HTTPS lors du démarrage du conteneur (voir ci-dessous). Pour le SDK Java, vous devez également installer des certificats.

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

Lorsque vous utilisez HTTPS avec des volumes de données persistants, l’émulateur régénère automatiquement les certificats SSL au démarrage. Vous n’avez donc pas besoin de gérer le renouvellement des certificats.

Commandes Docker

Le tableau suivant résume les commandes Docker disponibles pour configurer l'émulateur. Ce tableau détaille les arguments correspondants, les variables d'environnement, les valeurs autorisées, les paramètres par défaut et les descriptions de chaque commande.

Support des fonctionnalités

Cet émulateur est en développement actif et en aperçu. Par conséquent, toutes les fonctionnalités d’Azure Cosmos DB ne sont pas prises en charge. Certaines fonctionnalités ne seront pas non plus prises en charge à l’avenir. Ce tableau comprend l'état des différentes fonctionnalités et leur niveau de support.

Limitations

En plus des fonctionnalités non encore prises en charge ou non prévues, la liste suivante inclut les limitations actuelles de l'émulateur.

• Le SDK .NET pour Azure Cosmos DB ne prend pas en charge l’exécution en masse dans l’émulateur.
• Si vous obtenez des erreurs HTTP 500 sur des résultats de requête volumineux, augmentez la taille de la mémoire tampon de requête avec l’indicateur --query-buffer-size ou la QUERY_BUFFER_SIZE_KB variable d’environnement. La valeur par défaut est 4096 Ko (4 Mo) et la valeur maximale est 65536 Ko (64 Mo).

Installation de certificats pour le SDK Java

Lorsque vous utilisez le Kit de développement logiciel (SDK) Java pour Azure Cosmos DB avec cette version de l’émulateur en mode https, il est nécessaire d’installer ses certificats dans votre magasin d’approbation Java local.

Obtention de certificat

Dans une fenêtre bash, exécutez ce qui suit :

# 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

Installer le certificat

Accédez au répertoire de votre installation Java où se trouve le fichier cacerts (remplacez ci-dessous par le bon répertoire) :

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

Importez le certificat (vous pouvez être invité à indiquer un mot de passe, la valeur par défaut est « changeit ») :

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

Si vous obtenez une erreur parce que l’alias existe déjà, supprimez-le, puis exécutez à nouveau la commande ci-dessus :

keytool -cacerts -delete -alias cosmos_emulator

Prise en charge d’OpenTelemetry

OpenTelemetry est un framework d’observabilité open source qui fournit une collection d’outils, d’API et de kits SDK pour l’instrumentation, la génération, la collecte et l’exportation de données de télémétrie. Le protocole OTLP (OpenTelemetry Protocol) est le protocole utilisé par OpenTelemetry pour transmettre des données de télémétrie entre les composants.

Vous pouvez utiliser OpenTelemetry avec l’émulateur pour surveiller et suivre votre application. L’émulateur prend en charge les options de télémétrie, qui peuvent être configurées via des variables d’environnement ou des indicateurs de ligne de commande lors de l’exécution du conteneur Docker.

L’émulateur exporte les métriques suivantes. Celles-ci sont disponibles via n’importe quel back-end de métriques qui prend en charge OTLP et fournit des insights précieux sur les performances et l’intégrité de la base de données :

• Taux de requête : affiche les modèles de trafic pour différents types d’opérations
• Temps d’exécution des requêtes : mesure le temps nécessaire pour exécuter différentes requêtes
• Utilisation des ressources : métriques de processeur, d’utilisation de la mémoire et de pool de connexions
• Taux d’erreur : suivi des erreurs par type et point de terminaison

Des instructions détaillées avec des exemples sont disponibles dans le référentiel GitHub.

Utiliser dans le flux de travail d’intégration continue

Il existe de nombreux avantages à utiliser des conteneurs Docker dans des pipelines CI/CD, en particulier pour les systèmes avec état comme les bases de données. Cela peut être en termes de rentabilité, de performances, de fiabilité et de cohérence de vos suites de tests.

L’émulateur peut être incorporé dans le cadre de pipelines CI/CD. Vous pouvez vous référer à ce référentiel GitHub qui fournit des exemples d'utilisation de l'émulateur dans le cadre d'un workflow CI GitHub Actions pour les applications .NET, Python, Java et Go sur les architectures x64 et ARM64 (illustré pour un exécuteur Linux utilisant ubuntu).

Voici un exemple de flux de travail CI GitHub Actions qui montre comment configurer l’émulateur en tant que conteneur de service GitHub Actions dans le cadre d’un travail dans le flux de travail. GitHub s’occupe du démarrage du conteneur Docker et le détruit une fois le travail terminé, sans avoir besoin d’intervention manuelle (par exemple, à l’aide de la docker run commande).

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

Ce travail s’exécute sur un exécuteur Ubuntu et utilise l’image mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview Docker en tant que conteneur de service. Il utilise des variables d’environnement pour configurer la chaîne de connexion, le nom de la base de données et le nom du conteneur. Étant donné que, dans ce cas, le travail s’exécute directement sur l’ordinateur exécuteur GitHub Actions, l’étape Exécuter les tests du travail peut accéder à l’émulateur qui est accessible via localhost:8081 (8081 étant le port exposé par l’émulateur).

L'étape ExportEr le certificat de l'émulateur Cosmos DB est spécifique aux applications Java, car le sdk Azure Cosmos DB Java ne prend actuellement pas en charge le mode HTTP dans l'émulateur. La variable d’environnement PROTOCOL est définie sur https dans la section services et cette étape exporte le certificat de l’émulateur et l’importe dans le magasin de clés Java. La même chose s’applique également à .NET.

Signaler des problèmes

Si vous rencontrez des problèmes lors de l’utilisation de cette version de l’émulateur, ouvrez un problème dans le référentiel GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) et étiquetez-le avec l’étiquette cosmosEmulatorVnextPreview.