Infra · Templates Dataflow (despliegue unificado)

Sistema único para construir y publicar templates de Apache Beam/Dataflow a GCS. Los jobs de Dataflow que ves en los procesos de ingesta (invoices, carta porte, shinkansen, buro…) se ejecutan a partir de estos templates.

¿Qué es?

templates-dataflow es un repositorio de infraestructura (no es un proceso de datos en sí). Reúne en un solo lugar el código Beam de varios pipelines y un script unificado (deploy_templates.sh) que compila cada template con DataflowRunner y lo sube como plantilla versionada a Google Cloud Storage. Esa plantilla en GCS es lo que después arranca como job de Dataflow en solvento-data-prod.

Campo	Valor
Tipo	Infraestructura (build + deploy de templates Beam)
Salida	Templates `.py` compilados en GCS (`gs://…/template/{JOB_NAME}-{TIMESTAMP}`)
Consumido por	Jobs de Dataflow de la ingesta (invoices, items, carta porte, shinkansen, buro, insights, tax-compliance…)
Cómo se usa	`./deploy_templates.sh <template> <env>` (manual, desde CLI)
Dueño	Martin (data eng)

Estructura del repo

Una carpeta por template. Cada carpeta es autocontenida:

templates-dataflow/
├── deploy_templates.sh              # script único de despliegue
├── invoices-webhook/
│   ├── dataflow_template.py         # código Beam del pipeline
│   ├── prod.env                     # config de producción
│   └── dev.env                      # config de desarrollo
├── invoices-api/
├── items-api/
├── cp-api-multischema/              # carta porte
├── buro/
├── insights/  ·  network-insights/
├── tax-compliance/
├── background-checks/
└── shinkansen-metadata-webhook/  ·  shinkansen-payout-results-webhook/  ·  shinkansen-treasury-api/

dataflow_template.py (o un nombre custom vía TEMPLATE_SCRIPT_NAME): el pipeline Beam.
<env>.env (dev.env, prod.env): configuración por ambiente. Define las 5 variables obligatorias del sistema de despliegue y, debajo, los parámetros del template.

El archivo `.env`

# VARIABLES DEL SISTEMA DE DESPLIEGUE (obligatorias)
PROJECT_ID=solvento-data-prod
REGION=us-central1
GCS_BUCKET=syntage-ingestion
JOB_NAME=invoices-webhook-prod
TEMPLATE_SCRIPT_NAME=dataflow_template.py
TEMPLATE_GCS_PATH=gs://artifacts-bucket-solvento-data-prod/syntage/dataflow_templates/invoices-webhook-prod

# PARÁMETROS DEL TEMPLATE (opcionales — se vuelven argumentos del pipeline)
OUTPUT_TABLE=solvento-data-prod:syntage.invoices
INPUT_SUBSCRIPTION=projects/solvento-data-prod/subscriptions/invoices-webhook-subscription
DLQ_TOPIC=projects/solvento-data-prod/topics/invoices-dlq
SCHEMA_NAME=invoices

Las variables que no son del sistema se convierten automáticamente de UPPER_CASE a argumento --lower_case del comando Dataflow (OUTPUT_TABLE → --output_table).

`deploy_templates.sh`

Script en Bash; uso: ./deploy_templates.sh <template_name> <environment>.

# Ejemplos
./deploy_templates.sh invoices-webhook prod
./deploy_templates.sh cp-api-multischema prod

Flujo del script:

Valida que existan la carpeta del template y el archivo <env>.env.
Carga y exporta las variables del .env.
Verifica las obligatorias: PROJECT_ID, REGION, GCS_BUCKET, TEMPLATE_GCS_PATH, JOB_NAME, TEMPLATE_SCRIPT_NAME.
Construye el comando: python3 <template>.py --runner=DataflowRunner --project --region --temp_location --template_location … + los parámetros opcionales del .env + --requirements_file si hay requirements.txt.
Pide confirmación (y/N) y ejecuta: Beam compila y deja la plantilla en GCS.

Versionado en GCS

El template se publica con timestamp, así que no se sobrescribe la versión en uso:

gs://{GCS_BUCKET}/template/{JOB_NAME}-{YYYYMMDD-HHMMSS}
# p.ej. .../invoices-webhook-prod-20251203-154624

Esto permite rollback (apuntar el job a una versión anterior) y trazabilidad.

Diagrama

graph LR
    DEV["👩‍💻 Ingeniero<br/>edita dataflow_template.py + prod.env"]
    SH["deploy_templates.sh<br/><i>compila con DataflowRunner</i>"]
    GCS[("GCS<br/>template/{JOB_NAME}-{TIMESTAMP}")]
    DF["Job Dataflow<br/>invoices-webhook-prod-…"]
    RAW[("solvento-data-prod<br/>syntage.invoices · RAW")]

    DEV --> SH --> GCS
    GCS -->|"gcloud dataflow jobs run / consola"| DF --> RAW

    classDef store fill:#bfdbfe,stroke:#1e40af,color:#000;
    class GCS,RAW store;

Relación con los procesos de ingesta

Cuando en una ficha (Syntage Invoices, Carta Porte, Shinkansen…) ves un job de Dataflow como invoices-webhook-prod-… o cp-api-multischema-prod-…, su plantilla salió de aquí:

Job Dataflow (en ingesta)	Carpeta en `templates-dataflow`	Repo "individual" relacionado
`invoices-webhook-prod-…`	`invoices-webhook/`	`template-invoices`
`items-api-prod-…`	`items-api/`	—
`cp-api-multischema-prod-…` (carta porte)	`cp-api-multischema/`	`template-cp`
Buró	`buro/`	`template-buro`
Insights	`insights/`, `network-insights/`	`template-insights`
Tax compliance	`tax-compliance/`	—
Shinkansen (metadata / payout results / treasury)	`shinkansen-*`	—

Repos "individuales" de templates

Existen además repos separados por template (template-invoices, template-cp, template-buro, template-insights). Son las versiones de trabajo/iteración de cada pipeline (con sus propias guías de deploy, migración, CI). La carpeta correspondiente dentro de templates-dataflow es la copia consolidada que se publica con el sistema unificado. (Confirmar la convención exacta de cuál es la fuente de verdad por template: la práctica vista es iterar en el repo individual y desplegar desde templates-dataflow.)

Si falla 🛠️

Impacto: un despliegue fallido no tira la ingesta en vivo (los jobs siguen usando la plantilla anterior). El riesgo es publicar una plantilla nueva con bug y arrancar un job con ella.

Síntoma	Dónde mirar	Acción
`deploy_templates.sh` falla en validación	Mensaje `[ERROR]` del script	Faltan carpeta/`<env>.env` o variables obligatorias
Compila pero el job nuevo se comporta mal	Logs del job Dataflow	Rollback: apuntar el job a la versión GCS anterior (timestamp previo)
Duda sobre qué versión está corriendo	`gsutil ls gs://{bucket}/template/{job_name}-*`	Listar versiones y comparar timestamps

Escalación: Dataflow / templates → Martin.

Enlaces

📊 Estado de los jobs Dataflow: dashboard "Data Processes" (Cloud Monitoring) → ver infra-dashboard-monitoreo
📦 Repo: templates-dataflow
📦 Templates individuales: template-invoices · template-cp · template-buro · template-insights

Última actualización: 2026-06-21 · Si cambia un template o el sistema de despliegue, actualizar esta ficha en el mismo MR.