Emulatore basato su Linux - vNext (anteprima)

La nuova generazione dell'emulatore Azure Cosmos DB è interamente basata su Linux ed è disponibile come contenitore Docker. Supporta l'esecuzione su un'ampia gamma di processori e sistemi operativi.

Prerequisiti

• Docker

Installazione

Ottenere l'immagine del contenitore Docker usando docker pull. L'immagine del contenitore viene pubblicata nel registro Microsoft Artifact Registry come mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

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

In esecuzione

Per eseguire il contenitore, usare docker run. Successivamente, usare docker ps per verificare che il contenitore sia in esecuzione.

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'emulatore include due componenti:

• Esplora dati - Esplorare in modo interattivo i dati nell'emulatore. Per impostazione predefinita, questo componente viene eseguito sulla porta 1234.
• emulatore Azure Cosmos DB: versione locale del servizio di database Azure Cosmos DB. Per impostazione predefinita, questo componente viene eseguito sulla porta 8081.

L'endpoint del gateway emulatore usa la porta 8081 all'indirizzo http://localhost:8081. Per passare alla Esplora dati, usare l'indirizzo http://localhost:1234 nel Web browser. L'endpoint del gateway è in genere disponibile immediatamente, ma l'avvio di Esplora dati potrebbe richiedere alcuni secondi.

Sonda di diagnostica

L'emulatore espone un endpoint sonda di integrità sulla porta 8080. Usare questo endpoint per determinare quando l'emulatore è completamente inizializzato e pronto per accettare le richieste.

Sono disponibili i seguenti endpoint:

• http://localhost:8080/alive — Probe di liveness.
• http://localhost:8080/ready — Probe di idoneità.
• http://localhost:8080/status — Stato dettagliato.

Modalità HTTPS

Gli SDK .NET e Java non supportano la modalità HTTP nell'emulatore. Poiché questa versione dell'emulatore inizia con HTTP per impostazione predefinita, sarà necessario abilitare in modo esplicito HTTPS all'avvio del contenitore (vedere di seguito). Per Java SDK, è anche necessario installare i certificati.

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

Quando si usa HTTPS con volumi di dati persistenti, l'emulatore rigenera automaticamente i certificati SSL all'avvio, quindi non è necessario gestire il rinnovo del certificato.

Comandi Docker

La tabella seguente riepiloga i comandi Docker disponibili per la configurazione dell'emulatore. Questa tabella illustra in dettaglio gli argomenti corrispondenti, le variabili di ambiente, i valori consentiti, le impostazioni predefinite e le descrizioni di ogni comando.

Supporto delle funzionalità

Questo emulatore è in fase di sviluppo e anteprima attivi. Di conseguenza, non tutte le funzionalità di Azure Cosmos DB sono supportate. Alcune funzionalità non saranno supportate in futuro. Questa tabella include lo stato di varie funzionalità e il relativo livello di supporto.

Limitazioni

Oltre alle funzionalità non ancora supportate o non pianificate, l'elenco seguente include le limitazioni correnti dell'emulatore.

• L'SDK di .NET per Azure Cosmos DB non supporta l'esecuzione in blocco nell'emulatore.
• Se vengono visualizzati errori HTTP 500 in risultati di query di grandi dimensioni, aumentare le dimensioni del buffer di query con il --query-buffer-size flag o la QUERY_BUFFER_SIZE_KB variabile di ambiente. Il valore predefinito è 4096 KB (4 MB) e il valore massimo è 65536 KB (64 MB).

Installazione dei certificati per Java SDK

Quando si usa Java SDK per Azure Cosmos DB con questa versione dell'emulatore in modalità https, è necessario installare i certificati nell'archivio trust locale Java.

Ottenere il certificato

In una finestra bash, eseguire quanto segue:

# 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

Installare il certificato

Passare alla directory dell'installazione java in cui è collocato il file cacerts (sostituire di seguito con la directory corretta):

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

Importare il certificato (è possibile che venga chiesta una password; il valore predefinito è "changeit"):

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

Se viene visualizzato un errore perché l'alias esiste già, eliminarlo e quindi eseguire di nuovo quanto sopra:

keytool -cacerts -delete -alias cosmos_emulator

Supporto di OpenTelemetry

OpenTelemetry è un framework di osservabilità open source che fornisce una raccolta di strumenti, API e SDK per instrumentare, generare, raccogliere ed esportare dati di telemetria. Il protocollo OPENTelemetry Protocol (OTLP) è il protocollo usato da OpenTelemetry per trasmettere i dati di telemetria tra i componenti.

È possibile usare OpenTelemetry con l'emulatore per monitorare e tracciare l'applicazione. L'emulatore supporta le opzioni di telemetria, che possono essere configurate tramite variabili di ambiente o flag della riga di comando durante l'esecuzione del contenitore Docker.

L'emulatore esporta le metriche seguenti. Sono disponibili tramite qualsiasi back-end delle metriche che supporta OTLP e fornisce informazioni utili sulle prestazioni e sull'integrità del database:

• Frequenza delle richieste: mostra i modelli di traffico per diversi tipi di operazione
• Tempi di esecuzione delle query: misura il tempo impiegato per eseguire query diverse
• Utilizzo risorse: metriche cpu, utilizzo della memoria e pool di connessioni
• Frequenza degli errori: rilevamento degli errori per tipo ed endpoint

Le istruzioni dettagliate con esempi sono disponibili nel repository GitHub.

Uso nel flusso di lavoro dell'integrazione continua

L'uso di contenitori Docker nelle pipeline CI/CD offre numerosi vantaggi, soprattutto per sistemi con stato come i database. Questa potrebbe essere in termini di costo-efficacia, prestazioni, affidabilità e coerenza delle suite di test.

L'emulatore può essere incorporato come parte delle pipeline CI/CD. È possibile fare riferimento a questo repository GitHub che fornisce esempi su come usare l'emulatore come parte di un flusso di lavoro CI di GitHub Actions per applicazioni .NET, Python, Java e Go su entrambe le architetture x64 e ARM64 (illustrato per il runner Linux usando ubuntu).

Di seguito è riportato un esempio di flusso di lavoro CI di GitHub Actions che illustra come configurare l'emulatore come un contenitore di servizio di GitHub Actions all'interno di un processo del flusso di lavoro. GitHub si occupa dell'avvio del contenitore Docker e lo elimina al termine del processo, senza la necessità di intervento manuale, ad esempio usando il 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

Questo processo viene eseguito su un runner Ubuntu e usa l'immagine mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview Docker come contenitore di servizio. Usa le variabili di ambiente per configurare la stringa di connessione, il nome del database e il nome del contenitore. Poiché in questo caso il processo viene eseguito direttamente nel computer di esecuzione di GitHub Actions, il passaggio Esegui test nel processo può accedere all'emulatore usando localhost:8081 (8081 è la porta esposta dall'emulatore).

Il passaggio Export Cosmos DB Emulator Certificate (Esporta certificato dell'emulatore Cosmos DB) è specifico per le applicazioni Java poiché l'SDK Java di Azure Cosmos DB attualmente non supporta la modalità HTTP nell'emulatore. La variabile di ambiente PROTOCOL è impostata su https nella sezione services e questo passaggio esporta il certificato dell'emulatore e lo importa nell'archivio chiavi Java. Lo stesso vale anche per .NET.

Segnalazione di problemi

Se si verificano problemi con l'uso di questa versione dell'emulatore, aprire un problema nel repository GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) e contrassegnarlo con l'etichetta cosmosEmulatorVnextPreview.