DEV Community

Cover image for Construir y desplegar una app NoSQL con Azure Cosmos DB, Terraform y GitHub Actions
MILTON H FLORES CHINO
MILTON H FLORES CHINO

Posted on AI-assisted

Construir y desplegar una app NoSQL con Azure Cosmos DB, Terraform y GitHub Actions

En el curso de Base de Datos II (Universidad Privada de Tacna) nos pidieron construir y desplegar una aplicación con una base de datos NoSQL, sin usar Redis, MongoDB, Neo4j ni Prometheus. Con mi compañero Yerry Tarqui elegimos Azure Cosmos DB (API NoSQL), una base de documentos JSON administrada, y armamos una app de tareas que se despliega sola en Azure cada vez que hacemos push.

¿Por qué Cosmos DB?

  • Es NoSQL de documentos: cada tarea se guarda como un JSON, sin esquema fijo.
  • Tiene nivel gratuito (1000 RU/s y 25 GB), suficiente para un proyecto académico.
  • Se consulta con una sintaxis parecida a SQL (SELECT * FROM c), así que la curva de aprendizaje es corta.
  • Se crea completamente desde Terraform, lo que nos permitió automatizar todo.

Arquitectura

Navegador -> Azure App Service (ASP.NET Core .NET 10) -> Azure Cosmos DB (API NoSQL)
                     ^
GitHub Actions: ci.yml (build + validate), infra.yml (Terraform), deploy.yml (dotnet publish)
Enter fullscreen mode Exit fullscreen mode
Pieza Tecnología
Backend y página web ASP.NET Core minimal API (.NET 10)
Base de datos Azure Cosmos DB, base tareasdb, contenedor tareas, partición /id
Infraestructura como código Terraform (azurerm 4.x) con estado remoto en Azure Storage
Automatización GitHub Actions
Nube pública Azure App Service (plan F1 gratuito)

1. El modelo de datos

Un documento es una tarea. Cosmos DB necesita un id y una clave de partición; usamos el mismo id como partición porque cada tarea se lee y se escribe de forma independiente.

public class Tarea
{
    public string Id { get; set; } = Guid.NewGuid().ToString();
    public string Titulo { get; set; } = "";
    public bool Hecha { get; set; }
    public DateTime Fecha { get; set; } = DateTime.UtcNow;
}
Enter fullscreen mode Exit fullscreen mode

En Cosmos DB queda así:

{ "id": "3f2c...", "titulo": "Desplegar con GitHub Actions", "hecha": false, "fecha": "2026-11-13T..." }
Enter fullscreen mode Exit fullscreen mode

2. Conexión con el SDK de Cosmos DB

Instalamos el paquete Microsoft.Azure.Cosmos y, al arrancar, la app crea la base y el contenedor si no existen. El endpoint y la llave llegan por variables de entorno (Cosmos__Endpoint, Cosmos__Key), nunca están en el código.

var cfg = b.Configuration.GetSection("Cosmos");
var cli = new CosmosClient(cfg["Endpoint"], cfg["Key"], opt);
var db  = (await cli.CreateDatabaseIfNotExistsAsync(cfg["Database"] ?? "tareasdb")).Database;
var con = (await db.CreateContainerIfNotExistsAsync(cfg["Container"] ?? "tareas", "/id")).Container;
Enter fullscreen mode Exit fullscreen mode

El repositorio usa las operaciones nativas de Cosmos DB:

public async Task<List<Tarea>> Listar()
{
    var q = c.GetItemQueryIterator<Tarea>("SELECT * FROM c ORDER BY c.fecha DESC");
    var r = new List<Tarea>();
    while (q.HasMoreResults)
        r.AddRange(await q.ReadNextAsync());
    return r;
}

public async Task<Tarea> Crear(Tarea t) =>
    (await c.CreateItemAsync(t, new PartitionKey(t.Id))).Resource;
Enter fullscreen mode Exit fullscreen mode

3. La API

Método Ruta Qué hace
GET /health estado y cantidad de tareas
GET /api/tareas lista las tareas
POST /api/tareas crea { "titulo": "..." }
PUT /api/tareas/{id} actualiza título o estado
DELETE /api/tareas/{id} elimina

La página wwwroot/index.html consume esa API para agregar, marcar y eliminar tareas.

App local

4. Infraestructura como código con Terraform

infra/main.tf crea todo lo necesario en Azure:

resource "azurerm_cosmosdb_account" "db" {
  name              = "cosmos-tg1-yerrytc"
  offer_type        = "Standard"
  kind              = "GlobalDocumentDB"
  free_tier_enabled = true
  consistency_policy { consistency_level = "Session" }
  # ...
}

resource "azurerm_cosmosdb_sql_container" "tareas" {
  name                = "tareas"
  database_name       = azurerm_cosmosdb_sql_database.tareas.name
  partition_key_paths = ["/id"]
  # ...
}

resource "azurerm_linux_web_app" "app" {
  name = "app-tg1-nosql-yerrytc"
  site_config { application_stack { dotnet_version = "10.0" } }
  app_settings = {
    Cosmos__Endpoint = azurerm_cosmosdb_account.db.endpoint
    Cosmos__Key      = azurerm_cosmosdb_account.db.primary_key
  }
}
Enter fullscreen mode Exit fullscreen mode

Lo interesante es que Terraform pasa la llave de Cosmos DB directamente a la configuración de la Web App, así que nadie tiene que copiarla a mano.

5. Despliegue automatizado con GitHub Actions

Tenemos tres flujos:

  • ci.yml: en cada push compila el proyecto y ejecuta terraform validate.
  • infra.yml: cuando cambia infra/, ejecuta terraform init y terraform apply con un service principal guardado en los secretos del repositorio.
  • deploy.yml: cuando cambia src/, publica la app y comprueba que responde.
- run: dotnet publish src/TareasApi/TareasApi.csproj -c Release -o publicar
- uses: azure/login@v2
  with:
    creds: ${{ secrets.AZURE_CREDENTIALS }}
- uses: azure/webapps-deploy@v3
  with:
    app-name: app-tg1-nosql-yerrytc
    package: publicar
- name: probar la aplicacion publicada
  run: |
    for i in 1 2 3 4 5 6 7 8 9 10; do
      if curl -fs https://app-tg1-nosql-yerrytc.azurewebsites.net/health; then exit 0; fi
      sleep 15
    done
    exit 1
Enter fullscreen mode Exit fullscreen mode

El último paso es un smoke test: si /health no responde, el flujo falla y nos enteramos al instante.

Despliegue exitoso

6. Resultado en la nube

Los recursos quedan en un solo grupo de recursos de Azure, y desde el Data Explorer se ven los documentos JSON que guarda la app:

Documentos en Cosmos DB

La app pública funciona en https://app-tg1-nosql-yerrytc.azurewebsites.net y /health responde:

{ "estado": "ok", "base_datos": "Azure Cosmos DB", "tareas": 4 }
Enter fullscreen mode Exit fullscreen mode

App publicada

Lo que aprendimos

  1. Elegir bien la clave de partición es la decisión de diseño más importante en Cosmos DB. Para una app de tareas, /id reparte la carga de forma uniforme.
  2. Los secretos no van en el código: Terraform los entrega a App Service como configuración y GitHub los guarda como secretos cifrados.
  3. Automatizar desde el principio ahorra tiempo: después del primer terraform apply, cada cambio llega a producción con un simple git push.
  4. El plan F1 gratuito se "duerme" tras un rato sin uso, por eso la primera petición puede tardar unos segundos.

Cumplimiento de la actividad

Requisito Dónde
Repositorio público https://github.com/Yerrytc/tg1-nosql-tareas-yerrytc
Despliegue por automatización GitHub Actions (ci.yml, infra.yml, deploy.yml) + Terraform
Nube pública Microsoft Azure (App Service + Cosmos DB)
Video ≤ 5 min https://youtu.be/7J8stjhJkiA
BD NoSQL sin Redis/MongoDB/Neo4j/Prometheus Azure Cosmos DB (API NoSQL)

Equipo: Yerry Maycol Tarqui Collatupa y Milton H. Flores Chino — Base de Datos II, Escuela Profesional de Ingeniería de Sistemas, Universidad Privada de Tacna.

Top comments (0)