Emulador baseado em Linux – vNext (versão prévia)

A próxima geração do emulador do Azure Cosmos DB é inteiramente baseada em Linux e está disponível como um contêiner do Docker. Ele dá suporte à execução em uma ampla variedade de processadores e sistemas operacionais.

Prerequisites

• Docker

Installation

Obter a imagem de contêiner do Docker usando docker pull. A imagem do contêiner é publicada no Registro de Artefato da Microsoft como mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

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

Em execução

Para executar o contêiner, use docker run. Posteriormente, 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 interativamente os dados no emulador. Por padrão, esse componente é executado na porta 1234.
• Azure Cosmos DB emulador – uma versão local do serviço de banco de dados Azure Cosmos DB. Por padrão, esse componente é executado na porta 8081.

O ponto de extremidade do gateway do emulador usa a porta 8081 no endereço http://localhost:8081. Para navegar até o Data Explorer, use o endereço http://localhost:1234 no navegador da Web. O ponto de extremidade do gateway normalmente está disponível imediatamente, mas o Data Explorer pode levar alguns segundos para iniciar.

Sonda de saúde

O emulador expõe um endpoint de verificação de integridade na porta 8080. Use esse ponto de extremidade para determinar quando o emulador está totalmente inicializado e pronto para aceitar solicitações.

Os seguintes endpoints estão disponíveis:

• http://localhost:8080/alive – Investigação de vida.
• http://localhost:8080/ready — Verificação de prontidão.
• http://localhost:8080/status — Status detalhado.

Modo HTTPS

Os SDKs .NET e Java não suportam o modo HTTP no emulador. Como essa 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 SDK Java, 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 você usa HTTPS com volumes de dados persistentes, o emulador regenera automaticamente certificados SSL na inicialização, portanto, você não precisa gerenciar a renovação do certificado.

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

Esse emulador está em desenvolvimento ativo e versão prévia. Como resultado, nem todos os recursos do Azure Cosmos DB têm suporte. Alguns recursos também não terão suporte no futuro. Esta tabela inclui o estado de vários recursos e seu nível de suporte.

Limitações

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

• O SDK do .NET para Azure Cosmos DB não dá suporte à execução em massa no emulador.
• Se você receber erros HTTP 500 em resultados de consultas grandes, aumente o tamanho do buffer de consulta com o --query-buffer-size flag 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 essa versão do emulador no modo https, é necessário instalar seus certificados no repositório de confiança Java local.

Obter certificado

Em uma janela bash, 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 da instalação do Java onde o arquivo cacerts 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 solicitada uma senha, o valor padrão é "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 procedimento acima novamente:

keytool -cacerts -delete -alias cosmos_emulator

Suporte ao OpenTelemetry

O OpenTelemetry é uma estrutura de observabilidade de software livre que fornece uma coleção de ferramentas, APIs e SDKs para instrumentar, gerar, coletar e exportar dados de telemetria. O Protocolo OpenTelemetry (OTLP) é o protocolo usado pelo OpenTelemetry para transmitir dados de telemetria entre componentes.

Você pode usar OpenTelemetry com o emulador para monitorar e rastrear seu aplicativo. O emulador dá suporte a opções de telemetria, que podem ser configuradas por meio de variáveis de ambiente ou sinalizadores de linha de comando ao executar o contêiner do Docker.

O emulador exporta as métricas a seguir. Eles estão disponíveis por meio de qualquer back-end de métricas que dê suporte ao OTLP e fornece insights valiosos sobre o desempenho e a integridade do banco de dados:

• Taxas de Solicitação: mostra os padrões de tráfego para diferentes tipos de operação
• Tempos de execução de consulta: mede o tempo necessário para executar consultas diferentes
• Utilização de recursos: CPU, uso de memória e métricas do pool de conexões
• Taxas de erro: acompanhamento de erros por tipo e ponto de extremidade

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

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

Há muitos benefícios em usar contêineres do Docker em pipelines de CI/CD, especialmente para sistemas com estado, como bancos 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 de pipelines de CI/CD. Você pode consultar este repositório GitHub que fornece exemplos de como usar o emulador como parte de um fluxo de trabalho de CI do GitHub Actions para aplicativos .NET, Python, Java e Go em arquiteturas x64 e ARM64 (demonstrado para executor no Linux usando ubuntu).

Aqui está um exemplo de um fluxo de trabalho de CI do GitHub Actions que mostra como configurar o emulador como um contêiner de serviço do GitHub Actions como parte de um trabalho no fluxo de trabalho. GitHub cuida de iniciar o contêiner do Docker e o destrói quando o trabalho é concluído, sem a 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

Esse trabalho é executado em um executor 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 nesse caso o trabalho está sendo executado diretamente na máquina do executor do GitHub Actions, a etapa Executar testes no trabalho pode acessar o emulador, que está acessível usando localhost:8081 (8081 é a porta exposta pelo emulador).

A etapa Export Cosmos DB Emulator Certificate é específica para Java aplicativos, pois o SDK do Azure Cosmos DB Java atualmente não dá suporte ao modo HTTP no emulador. A variável de ambiente PROTOCOL é definida como https na seção services e essa etapa exporta o certificado do emulador e o importa para o repositório de chaves Java. O mesmo também se aplica ao .NET.

Problemas de relatórios

Se você encontrar problemas com o uso desta versão do emulador, abra um problema no repositório GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) e marque-o com o rótulo cosmosEmulatorVnextPreview.