collibra-governance-automation
Collibra Governance Automation
Automatiza el paso desde metadatos técnicos procedentes de varias fuentes hasta un modelo de gobierno común que puede revisarse, analizarse y sincronizarse con Collibra de forma controlada.
Qué problema resuelve
PostgreSQL, ODCS, dbt y OpenLineage describen partes distintas del mismo ecosistema. El problema no es simplemente reunir esos metadatos, sino darles una identidad común, conservar de dónde proceden y entender cómo se relacionan antes de llevarlos a una plataforma de gobierno.
Cómo lo he planteado
El proyecto construye primero un modelo de gobierno neutral e independiente de Collibra. Sobre ese modelo se pueden comprobar reglas, analizar el impacto de los cambios y preparar acciones revisables. Collibra queda al final del flujo como destino de sincronización, no como la fuente de verdad del modelo.
Ver cómo funciona el proyecto
Cómo funciona el proyecto
Este proyecto automatiza dos recorridos distintos que comparten principios de gobierno, revisión y determinismo, pero no el mismo modelo interno. El primero parte de PostgreSQL, construye un GovernanceModel y controla qué cambios pueden prepararse y sincronizarse con Collibra. El segundo compone ODCS, dbt y OpenLineage en un GovernanceGraph para conservar procedencia, construir linaje y analizar qué activos pueden verse afectados por un cambio.
Separar ambos recorridos es una decisión importante de la arquitectura actual: PostgreSQL no alimenta el grafo de impacto y el grafo multi-source no alimenta la sincronización con Collibra. El portfolio debe mostrar esa separación tal como existe en el código, sin convertirla en un único pipeline que hoy no existe.
POSTGRESQL → GOVERNANCEMODEL → COLLIBRA
ODCS + DBT + OPENLINEAGE → GOVERNANCEGRAPH → IMPACTO
Dos recorridos, dos modelos
GovernanceModel y GovernanceGraph son dos núcleos vendor-neutral diferentes. GovernanceModel representa la metadata física descubierta en PostgreSQL y es la base del camino de políticas y sincronización con Collibra. GovernanceGraph representa nodos, relaciones y procedencia procedentes de ODCS, dbt y OpenLineage y es la base del análisis de impacto.
No existe actualmente una conversión GovernanceModel → GovernanceGraph. Esta separación evita atribuir al proyecto una integración end-to-end que todavía no está implementada y permite explicar con precisión qué problema resuelve cada recorrido.
ROOT
CONTROL Y SINCRONIZACIÓN
CONTEXTO E IMPACTO
RECORRIDO A
Control y sincronización con Collibra
Este recorrido responde a una pregunta operativa: qué metadata física existe en PostgreSQL, si cumple unas comprobaciones básicas de gobierno y qué cambios habría que preparar para que el estado gestionado de Collibra la represente sin aplicar escrituras por defecto.
EJEMPLO EN CURSO · commerce.orders
Descubrimiento de PostgreSQL
El recorrido empieza observando directamente los catálogos de PostgreSQL. El scanner trabaja en una transacción REPEATABLE READ y READ ONLY para obtener una fotografía consistente de la estructura sin modificar la base de datos.
QUÉ ENTRA
Una conexión PostgreSQL y los catálogos del database configurado.
QUÉ HACE PYTHON
Python ejecuta cinco consultas de catálogo y reconstruye databases, schemas de usuario, tablas, columnas, tipos, nullability, primary keys, foreign keys, comentarios y ownership. Las views, los índices y las CHECK constraints no forman parte del discovery implementado actualmente.
RESULTADO
Un GovernanceModel con una jerarquía Data Source → Database → Schema → Table → Column y relaciones estructurales derivadas de las foreign keys.
EVIDENCIA EN CÓDIGO
PostgresMetadataScanner.scan · build_governance_model
commerce
orders
order_id
customer_id
…
orders.customer_idcustomers.customer_id
En la demo commerce, Python observa la tabla orders y la foreign key orders.customer_id → customers.customer_id. La relación se conserva dentro del GovernanceModel como metadata estructural.
Modelo e identidades estables
La metadata descubierta no se conserva como filas sueltas de catálogo. Python la convierte en objetos de dominio con identidades estables para que el mismo activo pueda reconocerse de forma reproducible entre ejecuciones.
QUÉ ENTRA
Las filas normalizadas obtenidas por el scanner de PostgreSQL.
QUÉ HACE PYTHON
Python construye IDs canónicos para cada nivel del modelo, valida la integridad de las referencias y ordena las colecciones de forma determinista. El host y el puerto de PostgreSQL no forman parte de la identidad de tablas y columnas, por lo que mover la conexión no cambia por sí solo la identidad lógica del activo.
RESULTADO
Un GovernanceModel vendor-neutral, estable y revisable que puede utilizarse sin depender todavía de Collibra.
EVIDENCIA EN CÓDIGO
GovernanceModel · make_table_id · make_column_id · make_relationship_id
RAW CATALOG ROWS
CANONICAL IDS
GOVERNANCEMODEL
La tabla del ejemplo queda identificada como tbl:governance-demo/governance_demo/commerce/orders y la columna customer_id como col:governance-demo/governance_demo/commerce/orders/customer_id.
Comprobaciones de gobierno
Antes de preparar cambios hacia Collibra, el proyecto puede aplicar un conjunto pequeño y explícito de reglas sobre el GovernanceModel. No es un motor genérico de políticas: actualmente existen tres tipos de comprobación definidos por el proyecto.
QUÉ ENTRA
El GovernanceModel y las reglas declaradas en la configuración Governance-as-Code.
QUÉ HACE PYTHON
Python evalúa si los activos seleccionados tienen owner, descripción y relaciones cuando las reglas require_owner, require_description o require_relationship lo exigen. Las violaciones se ordenan y se reportan; una violación con severidad de error puede bloquear check o la generación del plan.
RESULTADO
Un informe de violaciones que permite separar problemas de gobierno de la fase de sincronización.
EVIDENCIA EN CÓDIGO
evaluate_policies · NormalizedPolicySet
GovernanceModel
require_owner · exige ownership
require_description · exige descripción
require_relationship · exige al menos una relación
report
Estado deseado y plan revisable
Collibra aparece al final del modelo, no al principio. Python traduce el GovernanceModel neutral a una representación específica de Collibra y compara ese estado deseado con el estado remoto gestionado antes de decidir qué operaciones serían necesarias.
QUÉ ENTRA
GovernanceModel + mapping de Collibra + estado remoto gestionado.
QUÉ HACE PYTHON
Python transforma databases, schemas, tablas, columnas y relaciones FK en CollibraAssetSpec y CollibraRelationshipSpec, incluyendo referencias de dominio, tipos y atributos configurados. Después calcula un SyncPlan con CREATE, UPDATE, UNCHANGED y REMOTE_ONLY, y puede guardar las acciones en un .gplan junto con identidades de configuración, snapshot, políticas, mapping, target context y remote state.
RESULTADO
Un plan revisable que combina una lista ordenada de operaciones con un contrato de integridad. REMOTE_ONLY se reporta, pero no se convierte en una operación de borrado.
El .gplan no es solo una descripción: conserva las acciones y las identidades necesarias para detectar si el contexto ha cambiado antes de aplicar.
EVIDENCIA EN CÓDIGO
map_to_desired_state · build_sync_plan · build_saved_plan · SavedGovernancePlan
- 01
GovernanceModel
- 02
CollibraDesiredState
- 03
SyncPlan
- 04
.gplan
CREATE
UPDATE
UNCHANGED
REMOTE_ONLY
El .gplan no es solo una descripción: conserva las acciones y las identidades necesarias para detectar si el contexto ha cambiado antes de aplicar.
Sincronización segura
Tener un plan no autoriza una escritura. El flujo mantiene dry-run como comportamiento por defecto, exige opt-in explícito para aplicar y añade comprobaciones adicionales antes de permitir operaciones contra un adapter real.
QUÉ ENTRA
Un SyncPlan o .gplan revisado, la configuración actual y un adapter Collibra mock o live.
QUÉ HACE PYTHON
Python ejecuta dry-run sin escrituras por defecto. Para aplicar es necesario habilitar --apply y, si el adapter es live, confirmar además con --confirm-live. Antes de escribir, el flujo de .gplan comprueba que las identidades relevantes sigan coincidiendo; si el plan está stale, se bloquea antes de la primera escritura. Durante apply, los errores de escritura detienen la secuencia.
RESULTADO
CREATE y UPDATE pueden ejecutarse cuando se solicita explícitamente. El proyecto no implementa DELETE, borrado automático, rollback ni un motor de retries demostrado.
El LiveCollibraAdapter está contract-tested contra HTTP simulado. El repositorio no demuestra validación contra un tenant comercial real de Collibra.
EVIDENCIA EN CÓDIGO
execute_sync_plan · plans/stale.py · MockCollibraAdapter · LiveCollibraAdapter
.gplan
DRY-RUN · DEFAULT
--apply ?
NO → 0 WRITES
YES
LIVE ADAPTER ?
NO → continue
YES → --confirm-live
STALE ?
YES → BLOCK · 0 WRITES
NO → CREATE / UPDATE
RESULT
En el lifecycle local con MockCollibraAdapter, un remoto vacío produce creaciones y una segunda sincronización contra el nuevo estado no vuelve a crear los mismos activos.
El LiveCollibraAdapter está contract-tested contra HTTP simulado. El repositorio no demuestra validación contra un tenant comercial real de Collibra.
Collibra no tiene un único fixture que una PostgreSQL, ODCS, dbt y OpenLineage en una ejecución end-to-end. El recorrido PostgreSQL → Collibra y el recorrido ODCS/dbt/OpenLineage → impacto se muestran con ejemplos reales diferentes para no atribuir al proyecto una integración que todavía no existe.
RECORRIDO B
Contexto, linaje e impacto
Este recorrido responde a otra pregunta: si cambia un activo, qué dependencias, contratos y consumidores quedan dentro de su radio de impacto. Para responderla, Python compone metadata declarada, transformacional y observada procedente de ODCS, dbt y OpenLineage.
EJEMPLO EN CURSO · orders → downstream
Fuentes de contexto
Las tres fuentes no aportan lo mismo. ODCS describe contratos y contexto declarado, dbt describe modelos y dependencias de transformación y OpenLineage aporta observaciones de ejecución y linaje. El valor aparece al conservar esas diferencias en lugar de reducirlas a un único formato sin procedencia.
QUÉ ENTRA
Documentos ODCS v3.1.0, un subset de dbt Manifest v12 y eventos OpenLineage core 2-0-2.
QUÉ HACE PYTHON
Python valida y mapea cada fuente de forma específica. ODCS crea nodos contract, dataset y column con relaciones governs y contains. dbt convierte models, sources, columns y parent_map en estructura física y relaciones depends_on. OpenLineage compone RunEvent, JobEvent y DatasetEvent, datasets de entrada y salida y, cuando existe, columnLineage.
RESULTADO
Tres conjuntos de nodos, relaciones y procedencia preparados para componerse en un GovernanceGraph.
ODCS puede expresar quality, SLA y servers en el standard, pero este proyecto no los mapea actualmente al GovernanceGraph.
EVIDENCIA EN CÓDIGO
load_odcs_graph · load_dbt_graph · load_openlineage_graph
ODCS · contrato y contexto declarado
contract → governs → dataset → contains → column
dbt · modelos y dependencias declaradas
source/model → depends_on
OpenLineage · ejecución observada y column lineage
input → run/job → output
+ columnLineage
ODCS puede expresar quality, SLA y servers en el standard, pero este proyecto no los mapea actualmente al GovernanceGraph.
Identidad y procedencia
Para componer varias fuentes, el proyecto necesita decidir cuándo dos observaciones pueden representar el mismo activo y conservar de dónde procedió cada hecho. Esa unión no se basa en elegir silenciosamente una fuente ganadora.
QUÉ ENTRA
Nodos y relaciones producidos por los mappers de ODCS, dbt y OpenLineage.
QUÉ HACE PYTHON
Python construye GraphNodeIdentity con namespace, kind, logical_id y, cuando corresponde, parent. Las observaciones con la misma identidad y el mismo payload material pueden fusionar su ProvenanceRecord. Si dos observaciones con la misma identidad contienen atributos materiales incompatibles, la composición falla en lugar de escoger una fuente de forma arbitraria.
RESULTADO
Activos con identidad canónica y procedencia declarada, observada o derivada, preparados para formar parte del mismo grafo cuando sus identidades son compatibles.
dbt y OpenLineage pueden converger en la misma identidad física cuando coinciden namespace, database, schema y table.
ODCS solo converge automáticamente con otros activos si sus logical IDs han sido alineados. PostgreSQL no participa en este esquema de identidad porque pertenece al recorrido GovernanceModel.
El proyecto conserva procedencia, pero todavía no implementa un motor de authority o conflict resolution. Un conflicto material se rechaza.
EVIDENCIA EN CÓDIGO
GraphNodeIdentity · ProvenanceRecord · GovernanceGraph.from_parts
dbt observation
OpenLineage observation
SAME IDENTITY
ONE NODE
CONFLICT · STOP
dbt y OpenLineage pueden converger en la misma identidad física cuando coinciden namespace, database, schema y table.
ODCS solo converge automáticamente con otros activos si sus logical IDs han sido alineados. PostgreSQL no participa en este esquema de identidad porque pertenece al recorrido GovernanceModel.
El proyecto conserva procedencia, pero todavía no implementa un motor de authority o conflict resolution. Un conflicto material se rechaza.
GovernanceGraph
La composición produce un grafo de gobierno in-memory formado por dataclasses inmutables. No utiliza una graph database ni NetworkX: el propio dominio define cómo se normalizan, validan y ordenan nodos y relaciones.
QUÉ ENTRA
Los nodos, relaciones e información de procedencia ya normalizados por cada integración.
QUÉ HACE PYTHON
Python fusiona observaciones compatibles, comprueba que los parents existan, rechaza dangling edges, canonicaliza atributos y ordena nodos y relaciones. El grafo utiliza contains para jerarquía, depends_on para dependencias y governs para asociar contratos con los activos que gobiernan.
RESULTADO
Un GovernanceGraph determinista con content identity propia y suficiente estructura para construir linaje y recorrer dependencias.
depends_on se almacena como derived → dependency. Para calcular impacto downstream, el recorrido utiliza esa relación en sentido inverso.
EVIDENCIA EN CÓDIGO
GovernanceGraph · GraphNode · GraphEdge · canonical_json_bytes
GovernanceGraph
contains
depends_on
governs
depends_on se almacena como derived → dependency. Para calcular impacto downstream, el recorrido utiliza esa relación en sentido inverso.
Linaje y contratos
Dentro del grafo, las dependencias pueden proceder de fuentes diferentes y conservar distinto nivel de detalle. dbt aporta dependencias declaradas entre modelos y sources; OpenLineage aporta dependencias observadas en ejecución y puede materializar linaje entre columnas; ODCS aporta contratos asociados a datasets.
QUÉ ENTRA
parent_map de dbt, inputs/outputs y columnLineage de OpenLineage y relaciones governs de ODCS.
QUÉ HACE PYTHON
Python materializa relaciones depends_on con dirección derived → dependency. En dbt esas relaciones son de nivel table o transformation. En OpenLineage también pueden existir entre columnas mediante ColumnLineageAssertion. Los contratos ODCS permanecen como nodos contract conectados mediante governs y se incorporan como contexto del impacto.
RESULTADO
Un grafo capaz de representar dependencias dataset-level y column-level junto con el contexto contractual disponible.
dbt no genera column-level lineage en este proyecto. Esa capacidad está demostrada mediante OpenLineage.
Los contratos ODCS son contexto informativo dentro del análisis de impacto; actualmente no bloquean cambios ni sustituyen las reglas require_* del recorrido PostgreSQL.
EVIDENCIA EN CÓDIGO
materialize_column_lineage_edges · ColumnLineageAssertion · GraphEdge
- DATASETdownstreamorders
- COLUMNoutput columninput column
- CONTRACTcontractdataset
dbt no genera column-level lineage en este proyecto. Esa capacidad está demostrada mediante OpenLineage.
Los contratos ODCS son contexto informativo dentro del análisis de impacto; actualmente no bloquean cambios ni sustituyen las reglas require_* del recorrido PostgreSQL.
Los tests demuestran que una identidad física construida desde OpenLineage puede ser compatible con el activo físico equivalente de dbt y que el linaje de columnas se materializa como output column → depends_on → input column.
Análisis de impacto
Cuando se declara un activo modificado, el proyecto utiliza el GovernanceGraph para calcular qué consumidores quedan aguas abajo. El análisis es completamente read-only y no ejecuta políticas ni realiza escrituras remotas.
QUÉ ENTRA
GovernanceGraph + uno o varios changed roots definidos mediante governance-impact-changes/v1.
QUÉ HACE PYTHON
Python valida los roots, construye una adjacency efectiva, recorre depends_on en sentido inverso y ejecuta un BFS multi-source por distancia. Distingue impacto directo y transitivo, evita bucles sobre los roots, selecciona un camino mínimo canónico cuando existen rutas equivalentes y recoge relaciones, contratos y contexto de gobierno dentro del closure afectado.
RESULTADO
Un governance-impact-result/v1 determinista con los activos afectados, sus distancias, caminos y contexto relevante. El comando governance impact devuelve un estado impacted cuando encuentra consumidores afectados y no realiza ninguna mutación remota.
El ejemplo CLI principal es dataset-level. El column-level lineage está demostrado por tests específicos de OpenLineage y debe mostrarse como evidencia técnica complementaria, no como si formara parte del mismo fixture CLI.
EVIDENCIA EN CÓDIGO
analyze_downstream_impact · GovernanceImpactResult · _path_sort_key
orders
↓ reverse traversal over depends_on
downstream
TRANSITIVE · distance ≥2
En el fixture real utilizado por governance impact, orders es el changed root y downstream aparece como consumidor afectado. Ese recorrido está probado por CLI y por la GitHub Action read-only.
El ejemplo CLI principal es dataset-level. El column-level lineage está demostrado por tests específicos de OpenLineage y debe mostrarse como evidencia técnica complementaria, no como si formara parte del mismo fixture CLI.
Qué hemos conseguido automatizar con Python
Python no actúa aquí como una única cadena de scripts. En el recorrido operativo descubre metadata de PostgreSQL, construye identidades estables, evalúa comprobaciones, traduce el modelo a Collibra y prepara planes revisables con dry-run y protección frente a planes obsoletos. En el recorrido de impacto ingiere ODCS, dbt y OpenLineage, compone identidades y procedencia, materializa linaje y recorre el GovernanceGraph para calcular impacto downstream de forma determinista.
- DESCUBRIRPostgresMetadataScanner.scan
- IDENTIFICARGovernanceModel
- COMPROBARevaluate_policies
- MAPEARmap_to_desired_state
- PLANIFICARbuild_saved_plan
- PROTEGERexecute_sync_plan
- COMPONERGovernanceGraph.from_parts
- TRAZAR LINAJEmaterialize_column_lineage_edges
- CALCULAR IMPACTOanalyze_downstream_impact
- EVIDENCIARContentIdentity
Identidades, ordenación, artefactos y caminos de impacto se canonicalizan para que una misma entrada produzca una representación revisable y reproducible.
Arquitectura completa
COLLIBRA GOVERNANCE AUTOMATION
DOS MODELOS · SIN CONVERSIÓN DIRECTA ACTUAL
POSTGRESQL
GOVERNANCEMODEL
- CHECKSCOLLIBRA DESIRED STATE
SYNCPLAN / .GPLAN
DRY-RUN
APPLY
COLLIBRA
- ODCSDBTOPENLINEAGE
GOVERNANCEGRAPH
- PROVENANCELINEAGECONTRACTSIMPACT ANALYSIS
IMPACT RESULT
PR / REVIEW
Madurez y evolución
El polígono refleja el estado funcional documentado. El anillo exterior representa el perfil completo.
Lo más consolidado
El discovery read-only de PostgreSQL, el GovernanceModel, la composición ODCS/dbt/OpenLineage, el GovernanceGraph, el column-level lineage mediante OpenLineage, el análisis de impacto determinista y la planificación segura hacia Collibra forman capacidades demostradas por código y tests.
Lo que está evolucionando
La integración live de Collibra está contract-tested, pero no validada contra un tenant comercial real. PostgreSQL y el GovernanceGraph siguen siendo recorridos separados, y el proyecto todavía no implementa un motor de authority o resolución de conflictos entre fuentes.
Siguientes áreas
El repositorio documenta como áreas pendientes el hardening de la integración con Collibra, la gestión de authority, conflictos y drift y una mayor extensibilidad de providers. Se presentan como evolución futura, no como capacidades implementadas ni como un roadmap versionado cerrado.
Madurez y evolución
- ACTUAL · v1.2.0
- ÁREAS SIGUIENTESCollibra hardeningFUTURE
- ÁREAS SIGUIENTESAuthority / conflicts / driftFUTURE
- ÁREAS SIGUIENTESProvider extensibilityFUTURE
Qué puedes revisar en GitHub
El repositorio permite comprobar por separado el discovery y la sincronización con Collibra, la composición multi-source del GovernanceGraph, el linaje, el análisis de impacto y los controles de seguridad de los planes.
Descubrimiento y modelos
Scanner PostgreSQL, GovernanceModel, GovernanceGraph e identidades canónicas.
Fuentes, procedencia y linaje
Ingesta ODCS, dbt y OpenLineage, ProvenanceRecord y materialización de column-level lineage.
Impacto, planes y seguridad
BFS downstream, impact artifacts, .gplan, stale-plan checks, dry-run y no-delete.
Integración y pruebas
Mapping a Collibra, adapters mock/live contract-tested, lifecycle local y GitHub Action read-only.