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

Existem muitos benefícios em utilizar contêineres Docker em pipelines de CI/CD, especialmente para sistemas stateful 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 do pipeline de CI/CD, pois o banco de dados é localmente acessível.

O emulador Azure Cosmos DB baseado em Linux está disponível como um contêiner Docker e pode ser executado em diversas plataformas, incluindo arquiteturas ARM64 como 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 utilizá-lo para desenvolvimento e testes locais:

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

Azure Cosmos DB com GitHub Actions

Vamos percorrer um exemplo para entender melhor como utilizar o emulador do Azure Cosmos DB com as GitHub Actions, que é uma plataforma de integração contínua e entrega contínua (CI/CD) que permite automatizar seu 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 jobs. É definido por um arquivo YAML incluído no seu repositório e é executado quando acionado por um evento no seu repositório, ou pode ser acionado manualmente ou em um cronograma definido.

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

Este fluxo de trabalho do GitHub Actions configura o emulador do Azure Cosmos DB baseado em Linux como um contêiner de serviço do GitHub Actions como parte de um job. O GitHub se encarrega de iniciar o contêiner Docker e destruí-lo quando o job é concluído – nenhuma intervenção manual é necessária (como executar o 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 utiliza a imagem docker mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview como um container 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 do 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 de CI do GitHub Actions para aplicações .NET, Python, Java e Go em ambas as arquiteturas x64 e ARM64 (demonstrado para o runner Linux usando Ubuntu).

Faça o fork do repositório

Acesse 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 qualquer parte do código (.NET, Java, Python ou Go), adicione e comprometa 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 enviar as 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. Revise 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 runners baseados em ubuntu (para arquiteturas x64 e ARM64). Isso deve funcionar também para os runners baseados em Windows ARM. Se você estiver considerando runners Windows x64, observe que no momento da escrita, os containers de serviço do GitHub Actions não são suportados em runners não-Linux. Mas você pode contornar isso adicionando passos para instalar o Docker e gerenciar seu ciclo de vida, incluindo iniciar e parar o container.

Conclusão

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