En este artículo cuento cómo mi compañero Kevin Hinojosa y yo construimos y desplegamos TacnaGo, una guía de lugares turísticos de Tacna (Perú) que guarda sus datos en Azure Cosmos DB for NoSQL. Yo me encargué sobre todo de la infraestructura y del despliegue automatizado, así que me enfoco en esa parte: con un solo git push se crea la infraestructura, se cargan los datos, se construye la imagen Docker y la app queda publicada en Azure.
👉 App publicada: https://app-tacnago-geraldzvallos.azurewebsites.net
👉 Repositorio: https://github.com/Geraldzvallos/tacnago-cosmosdb
¿Qué es TacnaGo?
Es una API REST en .NET 9 con una página web sencilla. Cada lugar (la Catedral, los Petroglifos de Miculla, la playa Boca del Río, las picanterías de Pocollay…) es un documento JSON en Cosmos DB, y la categoría del lugar es la clave de partición. La app permite filtrar por categoría, buscar por etiqueta, agregar y eliminar lugares, y muestra cuántas Request Units (RU) costó cada operación.
¿Por qué Azure Cosmos DB for NoSQL?
La actividad pedía una base NoSQL que no fuera Redis, MongoDB, Neo4j ni Prometheus. Elegí Azure Cosmos DB for NoSQL (la API nativa de Cosmos DB, no la compatible con MongoDB) por tres razones:
- Costo cero: tiene una capa gratuita de 1000 RU/s y 25 GB por cuenta, y la usamos con una suscripción Azure for Students, sin tarjeta.
-
Se automatiza con Terraform: el proveedor
azurermcrea la base y el contenedor con su clave de partición. -
Se integra con el resto: la app corre en Azure App Service, en la misma nube y región (
westus3).
Arquitectura
Un git push dispara GitHub Actions. Terraform crea la base de datos en Cosmos DB y el App Service en Azure; la imagen Docker se publica en GitHub Container Registry y App Service la descarga y la ejecuta. La app se conecta a Cosmos DB con el SDK oficial de .NET.
| Pieza | Servicio | Costo |
|---|---|---|
| Base de datos NoSQL | Azure Cosmos DB for NoSQL (capa gratuita) | 0 |
| Backend y página web | Azure App Service Linux, plan F1, con contenedor | 0 |
| Imagen Docker | GitHub Container Registry (ghcr.io) | 0 |
| Estado de Terraform | Azure Storage Account | céntimos |
Infraestructura como código con Terraform
Todo está en infra/main.tf. La parte de Cosmos DB crea una base de 400 RU/s y el contenedor Lugares con la clave de partición /categoria:
resource "azurerm\_cosmosdb\_sql\_database" "db" {
name = "TacnaGo"
resource\_group\_name = data.azurerm\_cosmosdb\_account.cosmos.resource\_group\_name
account\_name = data.azurerm\_cosmosdb\_account.cosmos.name
throughput = 400
}
resource "azurerm\_cosmosdb\_sql\_container" "lugares" {
name = "Lugares"
resource\_group\_name = data.azurerm\_cosmosdb\_account.cosmos.resource\_group\_name
account\_name = data.azurerm\_cosmosdb\_account.cosmos.name
database\_name = azurerm\_cosmosdb\_sql\_database.db.name
partition\_key\_paths = \["/categoria"]
partition\_key\_version = 2
}
El App Service ejecuta la imagen publicada en GitHub Packages. Lo más importante es que la clave de Cosmos DB va directo de Terraform a la configuración de la app: nunca aparece en el código ni en GitHub.
app\_settings = {
"WEBSITES\_PORT" = "8080"
"Cosmos\_\_Endpoint" = data.azurerm\_cosmosdb\_account.cosmos.endpoint
"Cosmos\_\_Key" = data.azurerm\_cosmosdb\_account.cosmos.primary\_key
"Cosmos\_\_Database" = azurerm\_cosmosdb\_sql\_database.db.name
"Cosmos\_\_Container" = azurerm\_cosmosdb\_sql\_container.lugares.name
}
ASP.NET Core lee Cosmos\_\_Endpoint como Cosmos:Endpoint, así que la misma imagen funciona en local y en Azure. El estado de Terraform se guarda en una Storage Account de Azure, que el propio workflow crea si no existe.
El pipeline: 4 workflows de GitHub Actions
| Workflow | Cuándo corre | Qué hace |
|---|---|---|
infra.yml |
push en infra/
|
terraform init, plan y apply
|
deploydb.yml |
cuando infra.yml termina bien |
carga data/lugares.json con el SDK de Python |
buildimage.yml |
push en el código o el Dockerfile | construye la imagen y la publica en ghcr.io |
deployimage.yml |
cuando buildimage.yml termina bien |
despliega la imagen en App Service y prueba la URL |
Los workflows se encadenan con el evento workflow\_run. Por ejemplo, la carga de datos espera a la infraestructura:
on:
workflow\_run:
workflows: \[ "Infraestructura (Terraform)" ]
types: \[ completed ]
branches: \[ "main" ]
Azure exige verificación en dos pasos (MFA) para iniciar sesión con usuario y contraseña, así que los workflows usan un service principal con rol Contributor. Sus datos, junto con un token de GitHub de solo lectura para descargar la imagen, están guardados como secrets del repositorio; los creé con gh secret set para no copiarlos a mano.
La carga de datos usa upsert, así que se puede repetir sin duplicar nada:
for lugar in lugares:
container.upsert\_item(lugar)
Problemas que encontré y cómo los resolví
-
La capa gratuita de Cosmos DB ya estaba usada. Azure permite solo una cuenta gratuita por suscripción y ya tenía una de otro proyecto. Crear otra cuenta se iba a cobrar. La solución fue que Terraform lea esa cuenta con un
data sourcey cree dentro una base nueva de 400 RU/s. La otra base usaba 400, así que el total queda en 800 de los 1000 RU/s gratis. -
Región bloqueada. La suscripción Azure for Students solo deja desplegar en algunas regiones, así que todo va en
westus3. -
El primer despliegue falló con
Resource app-tacnago-geraldzvallos of type Microsoft.Web/Sites doesn't exist. La Web App se acababa de crear y la acción de despliegue todavía no la veía. Volví a lanzar el job y agregué una espera de 60 segundos después de detectar la Web App. -
La carga de datos corrió antes que la infraestructura. En el primer push,
deploydb.ymltambién se disparó por los cambios endata/y falló porque la base todavía no existía. La ejecución encadenada ainfra.ymlsí funcionó.
Resultado
La app quedó publicada en https://app-tacnago-geraldzvallos.azurewebsites.net y se actualiza sola con cada push. Se puede filtrar por categoría (la consulta va a una sola partición), buscar por etiqueta, agregar lugares y ver el costo de cada operación en RU. La API también se puede probar desde Swagger: https://app-tacnago-geraldzvallos.azurewebsites.net/swagger
Conclusiones
- Con Terraform y GitHub Actions, la infraestructura y el despliegue quedan en el repositorio y se repiten igual cada vez.
- La capa gratuita de Cosmos DB alcanza de sobra para una app pequeña, pero hay que vigilar el total de RU/s de la cuenta.
- Encadenar workflows con
workflow\_runordena el proceso, pero hay que tener en cuenta los tiempos de Azure al crear recursos nuevos.
Enlaces
- Repositorio: https://github.com/Geraldzvallos/tacnago-cosmosdb
- App publicada: https://app-tacnago-geraldzvallos.azurewebsites.net
- API (Swagger): https://app-tacnago-geraldzvallos.azurewebsites.net/swagger
- Despliegue automatizado (GitHub Actions): https://github.com/Geraldzvallos/tacnago-cosmosdb/actions
- Video (grabado con Kevin): https://youtu.be/ofNwCJyyc8I
Top comments (0)