Emulador baseado em Linux - vNext (visualização)

A próxima geração do emulador Azure Cosmos DB é inteiramente baseada em Linux e está disponível como contentor Docker. Ele suporta a execução em uma ampla variedade de processadores e sistemas operacionais.

Pré-requisitos

• Docker

Instalação

Obtenha a imagem do contentor do Docker usando docker pull. A imagem do contêiner é publicada no Microsoft Artifact Registry como mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

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

Running

Para executar o contêiner, use docker run. Depois, use docker ps para validar se o contêiner está em execução.

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>

O emulador inclui dois componentes:

• Data Explorer - Explore de forma interativa os dados no emulador. Por defeito, este componente corre na porta 1234.
• Emulador do Azure Cosmos DB - Uma versão local do serviço de bases de dados do Azure Cosmos DB. Por defeito, este componente corre na porta 8081.

O endpoint do gateway do emulador usa a porta 8081 no endereço http://localhost:8081. Para navegar até à Data Explorer, use o endereço http://localhost:1234 no seu navegador web. O endpoint do gateway está normalmente disponível imediatamente, mas o Data Explorer pode demorar alguns segundos para iniciar.

Sonda de saúde

O emulador expõe um endpoint da sonda de saúde na porta 8080. Use este endpoint para determinar quando o emulador está totalmente inicializado e pronto para aceitar pedidos.

Os seguintes endpoints estão disponíveis:

• http://localhost:8080/alive — Sonda de vivacidade.
• http://localhost:8080/ready — Sonda de prontidão.
• http://localhost:8080/status — Estado detalhado.

Modo HTTPS

Os SDKs .NET e Java não suportam o modo HTTP no emulador. Como esta versão do emulador começa com HTTP por padrão, você precisará habilitar explicitamente o HTTPS ao iniciar o contêiner (veja abaixo). Para o Java SDK, você também precisará 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

Quando usas HTTPS com volumes de dados persistentes, o emulador regenera automaticamente os certificados SSL no arranque, por isso não precisas de gerir a renovação de certificados.

Comandos do Docker

A tabela a seguir resume os comandos do Docker disponíveis para configurar o emulador. Esta tabela detalha os argumentos correspondentes, variáveis de ambiente, valores permitidos, configurações padrão e descrições de cada comando.

Suporte de funcionalidades

Este emulador está em desenvolvimento ativo e em pré-visualização. Como resultado, nem todas as funcionalidades do Azure Cosmos DB são suportadas. No futuro, alguns recursos também deixarão de ser suportados. Esta tabela inclui o estado de vários recursos e seu nível de suporte.

Limitações

Além dos recursos ainda não suportados ou não planejados, a lista a seguir inclui as limitações atuais do emulador.

• O SDK .NET para Azure Cosmos DB não suporta execução em massa no emulador.
• Se aparecerem erros HTTP 500 em resultados da consulta grandes, aumente o tamanho do buffer de consulta com o sinalizador --query-buffer-size ou a variável de ambiente QUERY_BUFFER_SIZE_KB. O padrão é 4096 KB (4 MB), e o máximo é 65536 KB (64 MB).

Instalando certificados para Java SDK

Ao usar o SDK Java para Azure Cosmos DB com esta versão do emulador em modo https, é necessário instalar os seus certificados na sua Java trust store local.

Obter certificado

Em uma bash janela, execute o seguinte:

# 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

Instalar certificado

Navegue até o diretório de sua instalação java onde cacerts o arquivo está localizado (substitua abaixo pelo diretório correto):

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

Importe o certificado (pode ser-lhe pedida uma palavra-passe, o valor predefinido é "changeit"):

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

Se você receber um erro porque o alias já existe, exclua-o e execute o acima novamente:

keytool -cacerts -delete -alias cosmos_emulator

Suporte à OpenTelemetry

OpenTelemetry é uma framework de observabilidade de código aberto que fornece uma coleção de ferramentas, APIs e SDKs para instrumentação, geração, recolha e exportação de dados de telemetria. O Protocolo OpenTelemetry (OTLP) é o protocolo utilizado pela OpenTelemetry para transmitir dados de telemetria entre componentes.

Pode usar o OpenTelemetry com o emulador para monitorizar e rastrear a sua aplicação. O emulador suporta opções de telemetria, que podem ser configuradas através de variáveis de ambiente ou flags de linha de comandos ao executar o contentor Docker.

O emulador exporta as seguintes métricas. Estes estão disponíveis através de qualquer backend de métricas que suportem OTLP e forneçam informações valiosas sobre o desempenho e a saúde da base de dados:

• Taxas de Pedido: Mostra os padrões de tráfego para diferentes tipos de operações
• Tempos de Execução de Consultas: Mede o tempo necessário para executar diferentes consultas
• Utilização de Recursos: Métricas de CPU, utilização de memória e pool de ligações
• Taxas de Erro: Acompanhamento de erros por tipo e ponto final

Instruções detalhadas com exemplos estão disponíveis no repositório do GitHub.

Utilização no fluxo de trabalho de integração contínua

Existem muitos benefícios em usar containers Docker em pipelines CI/CD, especialmente para sistemas com estado como bases de dados. Isso pode ser em termos de custo-benefício, desempenho, confiabilidade e consistência de seus conjuntos de testes.

O emulador pode ser incorporado como parte dos pipelines CI/CD. Pode consultar este repositório GitHub que fornece exemplos de como usar o emulador como parte de um fluxo de trabalho de GitHub Actions CI para aplicações .NET, Python, Java e Go tanto nas arquiteturas x64 como ARM64 (demonstrado para Linux runner usando ubuntu).

Aqui está um exemplo de um fluxo de trabalho de GitHub Actions CI que mostra como configurar o emulador como um contentor de serviço GitHub Actions como parte de um trabalho no fluxo de trabalho. GitHub trata de iniciar o contentor Docker e destrói-o quando o trabalho termina, sem necessidade de intervenção manual (como usar o 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 trabalho é executado num agente do Ubuntu e usa a imagem do mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview Docker como um contêiner de serviço. Ele usa variáveis de ambiente para configurar a cadeia de conexão, o nome do banco de dados e o nome do contêiner. Como neste caso o trabalho está a ser executado diretamente na máquina GitHub Actions runner, a etapa Run tests no trabalho pode aceder ao emulador, que está acessível usando localhost:8081 (com 8081 como a porta exposta pelo emulador).

A etapa Exportar Certificado de Emulador do Cosmos DB é específica para aplicativos Java, já que o SDK Java do Azure Cosmos DB atualmente não oferece suporte ao HTTP modo no emulador. A variável de ambiente PROTOCOL é definida para https na secção services e este passo exporta o certificado do emulador e importa-o para a Java keystore. O mesmo se aplica ao .NET também.

Comunicar problemas

Se encontrar problemas ao usar esta versão do emulador, abra um problema no repositório de GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) e marque-o com a etiqueta cosmosEmulatorVnextPreview.