Autor: Yerry Maycol Tarqui Collatupa
Trabajo: NoSQL App Development
En este artículo se documentan la construcción, el despliegue automatizado y la validación de una aplicación de tareas con Azure Cosmos DB, una base de datos NoSQL, desde el proyecto ASP.NET Core hasta su publicación en Azure con Terraform y GitHub Actions.
Introducción
Las bases de datos NoSQL se utilizan cuando los datos no encajan bien en tablas con un esquema fijo o cuando se necesita escalar con facilidad. En lugar de filas y columnas, guardan documentos, pares clave-valor, grafos o columnas, según el modelo de cada motor. Para entender cómo se integra una de ellas en una aplicación real no basta con instalarla: también hay que conectarla a un servicio, publicarla y automatizar su despliegue.
A partir de ese objetivo se desarrolló NoSQL App Development, un proyecto práctico que construye una aplicación de tareas con ASP.NET Core y Azure Cosmos DB, una base de datos NoSQL de documentos administrada por Microsoft. El proyecto integra la API NoSQL de Cosmos DB, Terraform para describir la infraestructura como código, GitHub Actions para automatizar su creación y su despliegue, y Azure App Service para publicar la aplicación en una nube pública.
La implementación se realizó de forma progresiva. Primero se creó el proyecto y su código; después se ejecutó de manera local contra Cosmos DB, se definió la infraestructura con Terraform y se automatizaron su creación y el despliegue con flujos de GitHub Actions. Finalmente se comprobaron la aplicación publicada y los documentos guardados en la base de datos. Esta publicación documenta las evidencias principales del trabajo.
Arquitectura de la solución
La aplicación sigue un esquema sencillo. El navegador consume una página web y una API REST alojadas en Azure App Service, que ejecuta una aplicación ASP.NET Core sobre .NET 10. La API se conecta a Azure Cosmos DB mediante su SDK y guarda cada tarea como un documento JSON dentro de la colección tareas de la base tareasdb.
Figura 1. Arquitectura de la solución: aplicación ASP.NET Core en App Service, base NoSQL en Cosmos DB e infraestructura automatizada con GitHub Actions y Terraform.
La infraestructura y el despliegue se mantienen separados. Un primer flujo, infra.yml, ejecuta Terraform para crear la cuenta de Cosmos DB, la base, la colección, el plan de App Service y la aplicación web. Un segundo flujo, deploy.yml, publica el código de la aplicación en App Service. El estado de Terraform se guarda en una cuenta de Azure Storage para que las ejecuciones sucesivas sean consistentes.
Creación del proyecto
Se partió de un repositorio de Git ya vinculado a GitHub. Con el SDK de .NET se creó el proyecto web mínimo que contendría la API y la página de tareas.
Figura 2. Creación del proyecto TareasApi con la plantilla web mínima de ASP.NET Core.
Después se agregó el paquete Microsoft.Azure.Cosmos, que permite conectarse a Azure Cosmos DB desde .NET. El SDK requiere también una referencia explícita a Newtonsoft.Json, por lo que se incorporó al proyecto.
Figura 3. Instalación del SDK de Azure Cosmos DB en el proyecto.
Código de la aplicación
En Program.cs se configuró el cliente de Cosmos DB con la conexión de la aplicación, se creó la base y la colección si todavía no existen y se definieron los endpoints: /health para comprobar el estado y /api/tareas para listar, consultar, crear, actualizar y eliminar tareas. La llave de acceso no se escribe en el código, sino que se entrega como configuración.
Figura 4. Endpoints de la API definidos en Program.cs.
El acceso a la base de datos se encapsuló en la clase TareasRepo. Allí se concentran la consulta SQL de Cosmos DB para listar las tareas y las operaciones de lectura, creación, reemplazo y eliminación de documentos, de modo que los endpoints no dependen directamente del SDK. Cada tarea es un documento JSON con identificador, título, estado y fecha.
Figura 5. Clase TareasRepo para el acceso al contenedor de Cosmos DB.
La interfaz es una página HTML en la carpeta wwwroot que consume la API: permite agregar una tarea, marcarla como completada y eliminarla, y muestra al pie el nombre de la base de datos y la cantidad de tareas guardadas.
Figura 6. Página web que consume la API de tareas.
Ejecución local
Antes de publicar la solución se ejecutó en el equipo local con dotnet run. La conexión a Cosmos DB se entregó mediante variables de entorno, de manera que la llave no aparece en el código ni en las capturas.
Figura 7. Aplicación ejecutándose en el puerto 5100.
Al abrir la página se comprobó que se conectaba a Azure Cosmos DB. Se agregaron tres tareas desde la interfaz: cada una se guardó como un documento en la base y el pie de página mostró la cantidad de tareas almacenadas.
Figura 8. Tareas creadas desde la interfaz local y guardadas en Azure Cosmos DB.
Infraestructura como código
La infraestructura se describió con Terraform en el archivo main.tf. Allí se definieron la cuenta de Azure Cosmos DB en nivel gratuito, la base tareasdb, la colección tareas, un plan de App Service gratuito (F1) y la aplicación web con .NET 10. La conexión a Cosmos DB se entrega a la aplicación como configuración, y el estado de Terraform se guarda en una cuenta de Azure Storage. El grupo de recursos se creó previamente y Terraform lo utiliza para crear el resto de los recursos.
Figura 9. Recursos de Azure definidos con Terraform en main.tf.
Automatización con GitHub Actions
El primer flujo, infra.yml, inicializa, valida y aplica la configuración de Terraform. Para autenticarse en Azure utiliza los secretos del repositorio asociados a un service principal.
Figura 10. Flujo infra.yml que ejecuta Terraform.
El segundo flujo, deploy.yml, compila y publica la aplicación con dotnet publish, la despliega en App Service y, al final, consulta el endpoint /health de la aplicación publicada para confirmar que responde.
Figura 11. Flujo deploy.yml que publica la aplicación en App Service.
Las credenciales no se guardan en el repositorio. Con la CLI de GitHub se comprobó que los secretos de Azure estuvieran configurados; la lista muestra únicamente sus nombres, no sus valores.
Figura 12. Secretos de GitHub Actions utilizados por los flujos.
Creación de la infraestructura
Con el código en la rama principal se ejecutó infra.yml. Terraform inició el proceso y comenzó a crear los recursos de Azure.
Figura 13. Ejecución en curso del flujo infra.yml.
El flujo terminó con estado exitoso y creó los cinco recursos definidos en Terraform: la cuenta de Cosmos DB, la base, la colección, el plan de App Service y la aplicación web.
Figura 14. Flujo infra.yml finalizado correctamente.
El detalle del trabajo permite revisar cada paso: la inicialización de Terraform, la validación de la configuración y la aplicación de los cambios.
Figura 15. Detalle de los pasos de infra.yml.
Despliegue de la aplicación
Con la infraestructura lista se ejecutó deploy.yml, que compiló y publicó la aplicación en App Service. El flujo terminó correctamente.
Figura 16. Flujo deploy.yml finalizado correctamente.
El detalle muestra la compilación, el inicio de sesión en Azure, el despliegue y la prueba final de la aplicación publicada.
Figura 17. Detalle de los pasos de deploy.yml.
La lista de ejecuciones de GitHub Actions conserva el historial de ambos flujos. La ejecución en rojo corresponde al primer intento de despliegue, que se lanzó con el push inicial antes de que existiera el código de la aplicación; después de agregar el código, el despliegue se completó con éxito.
Figura 18. Historial de los flujos infra y deploy.
Recursos en Azure
En el portal de Azure se comprobaron los recursos del grupo: la aplicación web, la cuenta de Cosmos DB, el plan de App Service y la cuenta de almacenamiento donde se guarda el estado de Terraform.
Figura 19. Recursos creados en el grupo de recursos de Azure.
Después se abrió el Explorador de datos de Cosmos DB y se consultó la colección tareas de la base tareasdb. Allí se ven los documentos JSON que guarda la aplicación, lo que confirma que la base de datos NoSQL es la que almacena la información.
Figura 20. Documentos JSON almacenados en Azure Cosmos DB.
Aplicación publicada
La aplicación quedó disponible en una URL pública de Azure App Service. Al ingresar se comprobó que se conectaba a Cosmos DB y se agregaron tareas desde la interfaz publicada.
Figura 21. Aplicación publicada en Azure con tareas guardadas en Cosmos DB.
Se marcó una tarea como completada, lo que actualiza su documento en la base de datos, y se eliminó otra, lo que borra su documento.
Figura 22. Actualización de una tarea desde la aplicación publicada.
También se consultó directamente la API. El endpoint /health responde con el estado de la aplicación, el nombre de la base de datos y la cantidad de tareas guardadas.
Figura 23. Respuesta del endpoint /health.
El endpoint /api/tareas devuelve los documentos almacenados en Cosmos DB en formato JSON.
Figura 24. Documentos de Cosmos DB devueltos por /api/tareas.
Repositorio público
Todo el trabajo está en un repositorio público de GitHub que contiene el código de la aplicación, la infraestructura de Terraform, los flujos de GitHub Actions y las capturas del proceso. Las llaves de acceso no forman parte del repositorio.
Figura 25. Repositorio público con el código, la infraestructura y los flujos.
Resultados
La implementación permitió comprobar el recorrido completo de una aplicación con una base de datos NoSQL: desde el código y la ejecución local hasta una aplicación publicada en la nube cuya infraestructura y despliegue se crean de forma automática. Los documentos guardados por la aplicación pudieron verse directamente en el Explorador de datos de Cosmos DB.
La infraestructura se creó con Terraform desde GitHub Actions y la aplicación se despliega con otro flujo que también comprueba su estado, de modo que el proceso puede repetirse sin pasos manuales en el portal de Azure.
| Componente | Validación | Resultado |
|---|---|---|
| API ASP.NET Core | Ejecución local con dotnet run en el puerto 5100 | Tareas guardadas en Cosmos DB |
| Azure Cosmos DB | Colección tareas en el Explorador de datos | Documentos JSON visibles |
| Terraform | Cuenta, base, colección, plan y aplicación web | Cinco recursos creados |
| infra.yml | Ejecución en GitHub Actions | Exitosa |
| deploy.yml | Publicación y prueba de /health | Exitosa |
| App Service | Aplicación en una URL pública | Publicada |
| API REST | /health y /api/tareas | Datos de Cosmos DB |
| Repositorio público | Código, infraestructura y flujos | Publicado |
Conclusiones
Azure Cosmos DB permitió guardar los datos como documentos JSON sin definir un esquema relacional, y su SDK facilitó las operaciones de lectura y escritura desde .NET.
Terraform permitió describir toda la infraestructura como código, de modo que se crea de forma repetible y sin pasos manuales en el portal de Azure.
GitHub Actions automatizó tanto la creación de la infraestructura como el despliegue de la aplicación, y el endpoint /health permitió verificar el resultado de cada despliegue.
Separar la infraestructura y el despliegue en dos flujos facilita repetir cada tarea de manera independiente: crear los recursos una vez y volver a publicar la aplicación cada vez que cambia el código.
El nivel gratuito de Cosmos DB y el plan F1 de App Service permitieron publicar la aplicación en una nube pública sin costo.
Enlaces del proyecto
Repositorio público: tg1-nosql-tareas-yerrytc en GitHub
Aplicación publicada: Abrir la aplicación en Azure
Nota: La aplicación está desplegada en el plan gratuito F1 de Azure App Service, por lo que puede tardar hasta un minuto en responder después de un periodo de inactividad. Una vez iniciada, funciona con normalidad.
Video de demostración: Ver en YouTube (4 min 35 s)
