Use o Azure Cosmos DB como um Contêiner Docker em Pipelines de CI/CD

Existem muitos benefícios em usar contêineres Docker em pipelines de CI/CD, especialmente para sistemas com estado como bancos de dados. Por exemplo, ao executar testes de integração, cada trabalho de CI pode iniciar o banco de dados em um contêiner isolado com um estado limpo, prevenindo conflitos entre testes. Isso resulta em um ambiente de teste confiável, consistente e econômico. Essa abordagem também reduz a latência e melhora o desempenho geral da pipeline de CI/CD, pois o banco de dados é localmente acessível.

O emulador do Azure Cosmos DB baseado em Linux está disponível como um contêiner Docker e pode ser executado em várias plataformas, incluindo arquiteturas ARM64 como o Apple Silicon. Ele permite o desenvolvimento e teste local de aplicações sem a necessidade de uma assinatura Azure ou custos de serviço. Você pode facilmente executá-lo como um contêiner Docker e usá-lo para desenvolvimento e teste local:

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

Azure Cosmos DB com GitHub Actions

Vamos passar por um exemplo para entender melhor como usar o emulador Azure Cosmos DB com GitHub Actions, que é uma plataforma de integração contínua e entrega contínua (CI/CD) que permite automatizar sua pipeline de build, teste e implantação usando fluxos de trabalho. Um fluxo de trabalho é um processo automatizado configurável que pode executar um ou mais trabalhos. É definido por um arquivo YAML inserido em seu repositório e é executado quando acionado por um evento em seu repositório, ou pode ser acionado manualmente ou em um cronograma definido.

Exemplo: Fluxo de trabalho CI para uma aplicação .NET

Este fluxo de trabalho do GitHub Actions configura o emulador Azure Cosmos DB baseado em Linux como um contêiner de serviço do GitHub Actions como parte de um trabalho. O GitHub se encarrega de iniciar o contêiner Docker e destruí-lo quando o trabalho é concluído – nenhuma intervenção manual é necessária (como a execução do comando docker run).

name: .NET App CI

on:
  push:
    branches: [main]
    paths:
      - 'dotnet-app/**'
  pull_request:
    branches: [main]
    paths:
      - 'dotnet-app/**'

jobs:
  build-and-test:
    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        os: [ubuntu-latest, ubuntu-24.04-arm]

    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: Checkout repository
        uses: actions/checkout@v4

      - name: Set up .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '8.0.x'

      - 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

          sudo cp cosmos_emulator.cert /usr/local/share/ca-certificates/
          sudo update-ca-certificates

      - name: Install dependencies
        run: cd dotnet-app && dotnet restore

      - name: Build
        run: cd dotnet-app && dotnet build --no-restore

      - name: Run tests
        run: cd dotnet-app && dotnet test --no-build --verbosity normal

Este trabalho está configurado para ser executado em um runner Ubuntu e usa a imagem docker mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview como um contêiner de serviço. A string de conexão, nome do banco de dados e nome do contêiner são configurados como variáveis de ambiente. Como o trabalho é executado diretamente em um runner hospedado no GitHub Actions, a etapa “Executar testes” pode acessar o emulador usando localhost:8081.

A etapa Exportar Certificado do Emulador Cosmos DB é específica para aplicações .NET (bem como Java) porque, no momento da escrita, os SDKs .NET e Java não suportam o modo HTTP no emulador. A variável de ambiente PROTOCOL é definida como https na seção services e esta etapa exporta o certificado do emulador e os adiciona ao repositório de certificados confiáveis do sistema operacional.

Experimente!

Este repositório do GitHub fornece exemplos de como configurar o emulador Linux como parte de um fluxo de trabalho CI do GitHub Actions para aplicações .NET, Python, Java e Go em ambas as arquiteturas x64 e ARM64 (demonstrado para runner Linux usando Ubuntu).

Faça um fork do repositório

Navegue até o repositório no GitHub e clique no botão Fork no canto superior direito da página do repositório para criar uma cópia do repositório em sua própria conta do GitHub.

Em sua conta do GitHub, abra o repositório e certifique-se de habilitar os fluxos de trabalho nas configurações do repositório.

Adicione a string de conexão do emulador do Cosmos DB (COSMOSDB_CONNECTION_STRING) como um segredo do repositório. Use o seguinte valor:

AccountEndpoint=http://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

Adicione o nome do banco de dados (COSMOSDB_DATABASE_NAME) e o nome do contêiner (COSMOSDB_CONTAINER_NAME) como variáveis do repositório:

Clone o repositório forkado para sua máquina local (certifique-se de usar seu nome de usuário do GitHub):

git clone https://github.com/<your-username>/cosmosdb-linux-emulator-github-actions.git

cd cosmosdb-linux-emulator-github-actions

Acione o Fluxo de Trabalho

Para acionar o fluxo de trabalho, faça uma pequena alteração em todo o código (.NET, Java, Python ou Go), adicione e confirme suas alterações. Para facilitar o entendimento, fluxos de trabalho separados são usados para cada linguagem.

Envie suas alterações para seu repositório forkado no GitHub:

git add . 
git commit -m "Your commit message" 
git push origin main

Depois de fazer o push das alterações, o GitHub Actions executará automaticamente o fluxo de trabalho. Vá para a aba “Actions” em seu repositório para ver o status e os resultados dos fluxos de trabalho. Analise quaisquer logs ou saídas para garantir que os fluxos de trabalho estejam sendo executados corretamente.

Considerações sobre o GitHub Actions Runner

O repositório de exemplo demonstrou executores baseados em ubuntu (para arquiteturas x64 e ARM64). Isso deve funcionar também para executores baseados em Windows ARM. Se estiver considerando executores Windows x64, observe que no momento da escrita, os contêineres de serviço do GitHub Actions não são suportados em executores não-Linux. Mas é possível contornar isso adicionando passos para instalar o Docker e gerenciar seu ciclo de vida, incluindo iniciar e parar o contêiner.

Conclusão

Como mencionado anteriormente, há muitos benefícios em usar contêineres Docker em pipelines de CI. O GitHub Actions foi utilizado como plataforma de CI/CD neste caso, mas esses conceitos se aplicam a outras soluções também. Experimente e nos diga o que você acha!