Integración de Knowledge Catalog

En este documento, se explica cómo Cortex Framework se integra con Knowledge Catalog, que actúa como la capa de administración para los productos de datos empresariales en toda tu organización. También se explica cómo la herramienta de sincronización de Knowledge Catalog de Google Cloud Cortex Framework ayuda a registrar y sincronizar los productos de datos de Google Cloud Cortex Framework con Knowledge Catalog, lo que simplifica su descubrimiento y uso compartido seguro.

Cuando habilitas esta integración, los productos de datos de Cortex Framework implementados, incluidas sus descripciones empresariales enriquecidas, los metadatos de propiedad y los conjuntos de datos y las tablas de BigQuery físicos subyacentes, se catalogan automáticamente y se pueden descubrir en Knowledge Catalog.

Ventajas clave

La integración de Cortex Framework con Knowledge Catalog proporciona los siguientes beneficios clave:

  • Capacidad de descubrimiento de datos automatizada: Los usuarios pueden explorar y buscar productos de datos empresariales estandarizados directamente en la interfaz de usuario de Knowledge Catalog sin necesidad de ingresar el catálogo de forma manual.
  • Contexto empresarial enriquecido: Importa automáticamente nombres visibles, descripciones empresariales detalladas y URLs de documentación directamente desde manifest.yaml archivos a Knowledge Catalog.
  • Vinculación de recursos unificada: Conecta tablas base de informes conformes individuales directamente a sus productos de datos de Knowledge Catalog correspondientes. Esto les brinda a los consumidores de datos visibilidad inmediata de qué objetos de datos físicos impulsan dominios empresariales específicos.
  • Reconciliación automatizada del ciclo de vida y la desviación: A medida que evolucionan tus modelos de datos empresariales, la ejecución de la herramienta de sincronización reconcilia automáticamente los metadatos y los vínculos de recursos. Registra tablas nuevas, actualiza las definiciones modificadas y quita los vínculos obsoletos mientras protege los elementos de catálogo no administrados creados por el usuario.
  • Seguridad de la administración del sistema: Usa etiquetas de sistema dedicadas (cortex-framework-created y cortex-framework-version) para identificar y administrar solo los recursos creados por Cortex Framework, lo que evita la sobreescritura accidental de los recursos de Knowledge Catalog existentes administrados por el cliente.

Cómo funciona la integración

Componentes clave de la solución de Google Cloud Cortex Framework

La integración de Knowledge Catalog funciona con la herramienta de sincronización cortex-kc-sync (tools.dataplex.kc_sync). Cuando se ejecuta, el sincronizador realiza el siguiente flujo de trabajo de varios pasos:

Sincronización de Google Cloud Cortex Framework con Knowledge Catalog

1. Configuración y extracción de manifiesto

El sincronizador analiza tu archivo de configuración global config/config.yaml para identificar todos los módulos de productos de datos habilitados (data.modules.products) y sus conjuntos de datos de BigQuery de destino (data.targets).

Para cada módulo habilitado, el sincronizador extrae metadatos descriptivos del manifest.yaml del módulo (con el proveedor de módulos del espacio de trabajo):

  • displayName: Es el título legible del producto de datos.
  • description: Es el resumen empresarial del módulo.
  • documentation: Es la URL que apunta a la documentación del módulo interno o externo.

2. Descubrimiento de recursos de BigQuery

En lugar de verificar una lista estática de definiciones de tablas, cortex-kc-sync consulta BigQuery (list_dataset_tables) para descubrir de forma dinámica qué tablas y vistas ya se implementaron en tu conjunto de datos de destino.

Resuelve y filtra las tablas buscando etiquetas de seguimiento específicas aplicadas durante la implementación:

  • cortex-framework-namespaced-module-type que coincida con la ruta de acceso al módulo completamente calificada (p.ej., cortex.sap.products.sales_performance) o
  • cortex-framework-module-type que coincida con el nombre canónico del tipo de módulo (p.ej., sales_performance).

Solo las tablas y vistas materializadas que tengan estas etiquetas en BigQuery se catalogarán y se vincularán como recursos en el producto de datos.

3. Reconciliación y etiquetado de recursos administrados

El sincronizador se comunica con la API de dataplex_v1 (DataProductClient) para reconciliar cada producto de datos descubierto en el target Google Cloud location:

  • Creación (NEEDS_CREATION): Si el producto de datos no existe, el sincronizador crea un nuevo producto de datos de Knowledge Catalog propagado con los metadatos del manifiesto extraídos y vincula los recursos de BigQuery resueltos. Etiqueta el recurso con dos etiquetas del sistema:

    • cortex-framework-created: configurado como "true"
    • cortex-framework-version: configurado como "7-0-0"

  • Protección de recursos no administrados (NOT_MANAGED): Si ya existe un producto de datos de Knowledge Catalog con el mismo ID en el catálogo, pero faltan estas etiquetas del sistema (is_managed_data_product == False), el sincronizador lo omite para proteger los recursos de catálogo creados por el usuario o preexistentes.

  • Actualizaciones (NEEDS_UPDATE): Si existe un producto de datos administrado y tiene cambios en sus metadatos o composición de tablas, el sincronizador actualiza la definición del producto de datos de Knowledge Catalog y reconcilia sus recursos de BigQuery vinculados (BigQueryAssetLinks). Crea automáticamente vínculos DataAsset nuevos para las tablas recién agregadas y borra los obsoletos, mientras deja intactos los vínculos sin cambios.

Configuración

En esta sección, se describen los requisitos previos, la configuración de metadatos y los pasos de ejecución necesarios para configurar y ejecutar la sincronización entre Cortex Framework y Knowledge Catalog.

Requisitos previos

Antes de ejecutar la sincronización de Knowledge Catalog, asegúrate de cumplir con los siguientes requisitos:

Habilitar Google Cloud servicios

En esta sección, habilitaremos los siguientes Google Cloud servicios en tu Google Cloud proyecto:

  • API de Cloud Dataplex (dataplex.googleapis.com)

Habilita este Google Cloud servicio con Cloud Shell ejecutando el siguiente comando en tu terminal:

gcloud config set project PROJECT_ID

gcloud services enable dataplex.googleapis.com \
         --project=PROJECT_ID

Funciones para el proyecto de destino

Para obtener el permiso que necesitas para sincronizar Knowledge Catalog, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto de destino:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el dataplex.dataProducts.create, dataplex.dataProducts.update, dataplex.dataAssets.create, dataplex.dataAssets.delete permiso, que se requiere para sincronizar Knowledge Catalog.

También puedes obtener este permiso con roles personalizados o otros roles predefinidos.

Para otorgar los roles solicitados a un usuario, puedes usar la secuencia de comandos:

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/dataplex.editor"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/dataplex.dataProductsEditor"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/dataplex.entryOwner"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/bigquery.metadataViewer"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/bigquery.dataViewer"

Canalización de Dataform ejecutada

Primero, debes ejecutar cortex-build-and-deploy o cortex-deploy como se describe en la guía de implementación y ejecutar las acciones de tu canalización de Dataform para materializar las tablas y vistas de BigQuery antes de intentar sincronizar con Knowledge Catalog. Para obtener instrucciones paso a paso sobre cómo ejecutar transformaciones, consulta Pasos posteriores a la implementación.

Configura los metadatos del producto de datos

Puedes personalizar los metadatos empresariales que se muestran en Knowledge Catalog modificando el archivo manifest.yaml ubicado dentro de cada directorio de módulos de productos de datos (por ejemplo, src/data_modules/cortex/sap/products/accounts_payable/manifest.yaml).

En el siguiente ejemplo, se muestra cómo definir displayName, description y documentation en un manifiesto de módulo:

displayName: "SAP Accounts Payable"
description: >
  SAP Data Product for Accounts Payable containing conformed vendor invoices, 
  payment aging schedules, and financial accounting documents.
documentation: "https://docs.cloud.google.com/cortex/docs/data-product"

category: foundational_product
type: accounts_payable
dependencies:
  sapModule:
    supportedVersions:
      - ecc
      - s4
    tables:
      ecc:
        - bsik
        - bsak
      s4:
        - acdoca
        - bseg
      common:
        - bkpf
    modulePath: cortex.sap.foundations.sap
builder: sap_product

Ejecuta el comando de sincronización

Después de que se implementen y materialicen tus productos de datos en BigQuery, ejecuta la herramienta de CLI cortex-kc-sync con uv:

uv run cortex-kc-sync --config config/config.yaml --owner-email USER_EMAIL

Para obtener una lista completa de las marcas y los argumentos disponibles, consulta la referencia de la sincronización de KC de la CLI (uv run cortex-kc-sync).

Verificación de la sincronización de Knowledge Catalog

Para verificar la sincronización correcta entre los recursos de Google Cloud Cortex Framework y Knowledge Catalog, sigue estos pasos:

  • En la Google Cloud consola de, abre Knowledge Catalog.
  • Opcional: En el diálogo de búsqueda, puedes usar uno de los filtros rápidos, como Data Products o Tables.
  • En el campo de búsqueda de la pantalla principal de Knowledge Catalog, haz clic en Filters.
  • En la vista Filters abierta, selecciona en el menú desplegable Project el proyecto que usas para sincronizar los productos de datos de Google Cloud Cortex Framework.
  • Después de una sincronización correcta, ahora puedes seleccionar o buscar un recurso de datos expuesto por Google Cloud Cortex Framework, incluidos todos los metadatos publicados.

Automatiza el flujo de trabajo

En los entornos de producción, te recomendamos que ejecutes cortex-kc-sync automáticamente como un paso de procesamiento posterior dentro de tu canalización de orquestación de CI/CD o DAG de Knowledge Catalog (Airflow) inmediatamente después de la ejecución correcta de la canalización de Dataform:

  1. Compila e implementa: Ejecuta cortex-deploy (uv run cortex-deploy --config config/config.yaml) para compilar y organizar las configuraciones en Dataform.
  2. Ejecuta transformaciones: Activa las ejecuciones de Dataform para materializar las capas de la base de datos y las tablas de informes conformes en BigQuery.
  3. Sincronización de catálogos: Ejecuta cortex-kc-sync (uv run cortex-kc-sync --config config/config.yaml) para verificar la creación de tablas y sincronizar todos los productos de datos, las descripciones y los vínculos de linaje actualizados directamente en Knowledge Catalog.

Próximos pasos