DEV Community

Cover image for Respaldo cifrado y restauración verificada para Azure Cosmos DB con GitHub Actions
MILTON H FLORES CHINO
MILTON H FLORES CHINO

Posted on AI-assisted

Respaldo cifrado y restauración verificada para Azure Cosmos DB con GitHub Actions

Actividad Grupal 02-U2: NoSQL Backup Strategy · Base de Datos II (SI-783) · Universidad Privada de Tacna
Autor: Milton H. Flores Chino · Equipo: Yerry Maycol Tarqui Collatupa y Milton H. Flores Chino

Una copia de seguridad solo vale si se puede restaurar. Con esa idea armamos una estrategia de respaldo para una base NoSQL en Azure Cosmos DB: una app de productos en ASP.NET Core, una herramienta propia (BackupTool) que genera respaldos cifrados en Azure Blob Storage, y flujos de GitHub Actions que respaldan todos los días y restauran con verificación. Al final borramos todos los datos a propósito y los recuperamos.

Tres capas de protección

Capa Cómo se implementa Qué cubre
Respaldo nativo Cosmos DB con política Periodic: cada 240 min, retención de 48 h (Terraform) Recuperación administrada por Azure
Respaldo lógico propio BackupTool exporta los documentos, los comprime, los cifra y los sube a Blob Storage Copias bajo control del equipo, restaurables en otro contenedor
Retención Política de ciclo de vida de Storage: borra respaldos con más de 30 días Evita acumular copias viejas

La segunda capa es la que construimos nosotros, y es la que explico en detalle.

El formato del respaldo

BackupTool lee todos los documentos del contenedor productos, les quita los metadatos internos de Cosmos DB (_rid, _self, _etag, _attachments, _ts) y los guarda en un JSON con un manifiesto: versión, fecha, base, contenedor y cantidad de documentos. Antes de comprimir calcula el SHA-256 de ese JSON, que sirve como huella para comparar al restaurar.

Luego comprime con GZip y cifra con AES-256-GCM. La clave no se guarda: se deriva de una frase secreta con PBKDF2-SHA256 (200 000 iteraciones) y una sal aleatoria por archivo.

byte[] Cifrar(byte[] d, string clave)
{
    var sal = RandomNumberGenerator.GetBytes(16);
    var nonce = RandomNumberGenerator.GetBytes(12);
    var k = Rfc2898DeriveBytes.Pbkdf2(clave, sal, 200000, HashAlgorithmName.SHA256, 32);
    var c = new byte[d.Length];
    var tag = new byte[16];
    using var aes = new AesGcm(k, 16);
    aes.Encrypt(nonce, d, c, tag);
    return Encoding.ASCII.GetBytes("TG2B").Concat(sal).Concat(nonce).Concat(tag).Concat(c).ToArray();
}
Enter fullscreen mode Exit fullscreen mode

Así queda cada archivo .json.gz.enc:

Bytes Contenido
0–3 Firma TG2B
4–19 Sal de PBKDF2
20–31 Nonce de AES-GCM
32–47 Etiqueta de autenticación
48 en adelante Datos comprimidos y cifrados

AES-GCM no solo oculta los datos: si alguien modifica un solo byte del archivo, el descifrado falla. Por eso un respaldo alterado nunca se restaura en silencio.

El archivo se sube al contenedor privado backups con la cantidad de documentos y el SHA-256 como metadatos del blob.

Restaurar y verificar

La restauración hace el camino inverso: descarga el respaldo indicado (o el más reciente), lo descifra, lo descomprime, recalcula el SHA-256 y escribe los documentos con UpsertItemAsync. Al final cuenta los documentos del contenedor de destino y lo compara con el manifiesto:

if (docs.Count != esperado || total < esperado)
    throw new Exception("La verificacion fallo: se esperaban " + esperado + " documentos");
Console.WriteLine("VERIFICACION OK: " + esperado + " documentos recuperados");
Enter fullscreen mode Exit fullscreen mode

Si no coincide, el proceso termina con error y el flujo de GitHub Actions queda en rojo. Por defecto restaura en un contenedor nuevo (productos_restaurado), así se puede revisar la copia sin tocar los datos en uso.

Automatización con GitHub Actions

El repositorio tiene seis flujos: ci, infra (Terraform), deploy, backup, restore y desastre. El de respaldo corre solo todos los días:

on:
  schedule:
    - cron: '17 10 * * *'   # 10:17 UTC = 5:17 a. m. en Perú
  workflow_dispatch:
Enter fullscreen mode Exit fullscreen mode

En cada ejecución inicia sesión en Azure, obtiene la llave de Cosmos DB y la cadena de conexión de Storage con la CLI, las enmascara en los registros (::add-mask::) y ejecuta BackupTool. La frase de cifrado es el secreto BACKUP_PASSPHRASE del repositorio, así que ninguna llave está en el código.

Programación diaria del respaldo

La prueba: respaldar, destruir y recuperar

1. Datos iniciales. La app publicada en Azure tenía 6 productos guardados en Cosmos DB.

Seis productos en la app

2. Respaldo. backup.yml terminó en 42 s: 6 documentos, archivo productos-20261026-015040.json.gz.enc de 515 bytes y SHA-256 a719492f…dfdac08.

Registro del respaldo

El archivo cifrado quedó en el contenedor privado backups:

Respaldo cifrado en Blob Storage

3. Desastre simulado. desastre.yml, que solo corre si se escribe la confirmación BORRAR, eliminó todos los productos. La app quedó vacía:

App sin datos

4. Recuperación. restore.yml con el último respaldo y destino productos terminó en 40 s. El SHA-256 coincidió con el del respaldo original y la verificación pasó:

Registro de la restauración

Los 6 productos volvieron a aparecer en la app:

App restaurada

Lo que aprendí

  1. Un respaldo sin prueba de restauración es una suposición. La verificación por cantidad y SHA-256 convierte la recuperación en algo comprobable.
  2. Cifrar antes de subir protege los datos aunque alguien acceda al contenedor, y AES-GCM además detecta archivos alterados.
  3. Dos vías de recuperación (nativa de Azure y lógica propia) evitan depender de una sola.
  4. Automatizar con cron quita el factor humano: el respaldo ocurre aunque nadie se acuerde.
  5. Todo funciona con Cosmos DB serverless, App Service F1 y una cuenta de Storage pequeña, con costo mínimo.

Cumplimiento de la actividad

Requisito Dónde
Base NoSQL Azure Cosmos DB (API NoSQL)
Repositorio público https://github.com/Yerrytc/tg2-nosql-backup-yerrytc
Despliegue por automatización GitHub Actions + Terraform (infra.yml, deploy.yml, backup.yml, restore.yml)
Nube pública Microsoft Azure: App Service, Cosmos DB y Blob Storage
Video ≤ 5 min https://youtu.be/zM_CLWn9cGs

Top comments (0)