Guía del usuario de la malla de datos

Data Mesh para Cortex Framework amplía la base de datos para habilitar la gobernanza, la visibilidad y el control de acceso de los datos mediante los metadatos de BigQuery y Dataplex Universal Catalog. Para ello, se proporciona un conjunto básico de recursos de metadatos y anotaciones de activos de BigQuery que se pueden personalizar y, opcionalmente, implementar junto con la base de datos. Estas especificaciones básicas proporcionan una configuración personalizada que es la base de los metadatos para complementar Data Foundation de Cortex Framework. Consulta los conceptos de Data Mesh antes de seguir esta guía.

Los pasos que se describen en esta página están diseñados específicamente para configurar Data Mesh en Cortex Framework. Busca los archivos de configuración de Data Mesh en las carpetas específicas de cada carga de trabajo en la sección de directorios de Data Mesh.

Advertencia: Esta guía de Data Mesh puede cambiar con el tiempo. Ponte en contacto con el equipo de Cortex si tienes alguna duda o problema.

Imagen 1. Arquitectura de malla de datos para Cortex Framework.

Diseño

La malla de datos de Cortex se ha diseñado de forma similar a la base de datos general y consta de tres fases con diferentes subcomponentes gestionados por Cortex o por los usuarios:

1. Actualización de las especificaciones de recursos base: con cada lanzamiento, Cortex actualiza las especificaciones de recursos base, lo que proporciona una base de metadatos estandarizada para la malla de datos.
2. Personalización de las especificaciones de los recursos: antes de la implementación, los usuarios pueden adaptar las especificaciones de los recursos para que se ajusten a sus casos prácticos y requisitos específicos.
3. Implementación y actualizaciones de Data Mesh: los usuarios pueden habilitar Data Mesh en el archivo de configuración de Cortex. Se implementa después de los recursos de datos durante la implementación de Cortex. Además, los usuarios pueden implementar la malla de datos de forma independiente para recibir más actualizaciones.

Imagen 2. Diseño de malla de datos para Cortex Framework.

Directorios de malla de datos

Encuentra los archivos de configuración base de Data Mesh de cada carga de trabajo y fuente de datos en las siguientes ubicaciones. Ten en cuenta que los directorios contienen una estructura de archivos diferente, pero todas las especificaciones se encuentran en la carpeta config.

Carga de trabajo	Fuente de datos	Ruta del directorio
Gastos	SAP ECC	src/SAP/SAP_REPORTING/config/ecc
	SAP S/4 HANA	src/SAP/SAP_REPORTING/config/s4
	Salesforce Sales Cloud (SFDC)	src/SFDC/config
	Oracle EBS	src/OracleEBS/config
Marketing	CM360	src/marketing/src/CM360/config
	Google Ads	src/marketing/src/GoogleAds/config
	Meta	src/marketing/src/Meta/config
	Salesforce Marketing Cloud (SFMC)	src/marketing/src/SFMC/config
	TikTok	src/marketing/src/TikTok/config
	YouTube (con DV360)	src/marketing/src/DV360/config
	Google Analytics 4	src/marketing/src/GA4/config

Nota: Data Mesh no admite datos de LiveRamp ni de Dun & Bradstreet (ESG).

Los recursos de metadatos se definen a nivel de fuente de datos con un solo archivo YAML por proyecto Google Cloud y contienen una lista de todos los recursos. Si es necesario, los usuarios pueden ampliar el archivo o crear archivos YAML adicionales que contengan especificaciones de recursos adicionales en ese directorio.

Las anotaciones de recursos se definen a nivel de recurso y contienen muchos archivos YAML en el directorio, con una sola anotación por archivo.

Habilitar APIs y verificar permisos

Modificar los valores predeterminados de Data Mesh te permite implementar funciones que van más allá de las descripciones. Si necesitas modificar los valores predeterminados de Data Mesh en config.json para implementar funciones que vayan más allá de las descripciones, asegúrate de que las APIs necesarias y los permisos se hayan configurado tal como se indica en la siguiente tabla. Cuando despliegue Data Mesh con la base de datos, conceda permisos al usuario que realiza el despliegue o a la cuenta de Cloud Build. Si la implementación implica proyectos de origen y de destino diferentes, asegúrate de que estas APIs y permisos estén habilitados en ambos proyectos siempre que se utilicen esas funciones.

Función	Roles de permisos	Documentación
Acceso a recursos y filas de BigQuery	Propietario de datos de BigQuery	Para obtener más información, consulta los roles obligatorios de los roles de recursos y los permisos obligatorios de los roles de filas.
Acceso a columnas de BigQuery	Administrador de etiquetas de política	Para obtener más información, consulta los artículos Roles utilizados con el control de acceso a nivel de columna y Restringir el acceso con el control de acceso a nivel de columna.
Etiquetas de catálogo	Propietario de valores TagTemplate de Data Catalog	Para obtener más información, consulta los artículos Etiquetar una tabla de BigQuery con Data Catalog y Gestión de identidades y accesos de Data Catalog.
Lagos de Dataplex Universal Catalog	Editor de Dataplex	Para obtener más información, consulta la documentación sobre crear un lake.

Nota: Cortex Data Mesh no requiere la integración de las APIs Dataproc y Dataproc Metastore.

Información sobre las especificaciones de los recursos base

La interfaz principal para configurar Data Mesh para Cortex es a través de las especificaciones de recursos base, que son un conjunto de archivos YAML que se proporcionan de forma predeterminada y que definen los recursos de metadatos y las anotaciones que se implementan. Las especificaciones básicas proporcionan recomendaciones iniciales y ejemplos de sintaxis, pero se pueden personalizar para adaptarlas a las necesidades de los usuarios. Estas especificaciones se dividen en dos categorías:

• Recursos de metadatos que se pueden aplicar a varios recursos de datos. Por ejemplo, plantillas de etiquetas de catálogo que definen cómo se pueden etiquetar los recursos con dominios empresariales.
• Anotaciones que especifican cómo se aplican los recursos de metadatos a un recurso de datos concreto. Por ejemplo, una etiqueta de catálogo que asocia una tabla específica al dominio Ventas.

En las siguientes secciones se muestran ejemplos básicos de cada tipo de especificación y se explica cómo personalizarlos. Las especificaciones básicas se etiquetan con ## CORTEX-CUSTOMER para indicar dónde se deben modificar para que se ajusten a una implementación si la opción de implementación asociada está habilitada. Para usos avanzados, consulta la definición canónica de estos esquemas de especificación en src/common/data_mesh/src/data_mesh_types.py.

Recursos de metadatos

Los recursos de metadatos son entidades compartidas que se encuentran en un proyecto y que se pueden aplicar a muchos recursos de datos. La mayoría de las especificaciones incluyen un campo display_name que debe cumplir los siguientes criterios:

• Contiene solo letras Unicode, números (0-9), guiones bajos (_), guiones (-) y espacios ( ).
• No pueden empezar ni terminar con espacios.
• La longitud máxima es de 200 caracteres.

En algunos casos, el display_name también se usa como ID, lo que puede conllevar requisitos adicionales. En esos casos, se incluyen enlaces a la documentación canónica.

Si la implementación hace referencia a recursos de metadatos de proyectos de origen y de destino diferentes, debe haber una especificación definida para cada proyecto. Por ejemplo, Cortex Salesforce (SFDC) contiene dos especificaciones de Lake. Una para las zonas sin procesar y de los CDC, y otra para los informes.

Lagos de Dataplex Universal Catalog

Los lagos, las zonas y los recursos de Dataplex Universal Catalog se usan para organizar los datos desde una perspectiva de ingeniería. Los lagos tienen un region y las zonas tienen un location_type. Ambos están relacionados con la ubicación de Cortex (config.json > location). La ubicación de Cortex define dónde se almacenan los conjuntos de datos de BigQuery y puede ser una sola región o varias. La zona location_type debe ser SINGLE_REGION | MULTI_REGION para que coincida. Sin embargo, las regiones de tipo Lake siempre deben ser una sola región. Si la ubicación y la zona de Cortex location_type son multirregión, selecciona una sola región de ese grupo para la región de Lake.

• Requisitos
  • El lago display_name se usa como lake_id y debe cumplir los requisitos oficiales. Lo mismo ocurre con la zona y el recurso display_name. Los IDs de las zonas deben ser únicos en todos los lagos del proyecto.
  • Las especificaciones de los lagos deben estar asociadas a una sola región.
  • El asset_name debe coincidir con el ID del conjunto de datos de BigQuery, pero el display_name puede ser una etiqueta más intuitiva.
• Limitaciones
  • El catálogo universal de Dataplex solo admite el registro de conjuntos de datos de BigQuery, no de tablas individuales, como recursos del catálogo universal de Dataplex.
  • Un recurso solo puede registrarse en una zona.
  • Dataplex Universal Catalog solo está disponible en determinadas ubicaciones. Para obtener más información, consulta las ubicaciones de Dataplex Universal Catalog.

Consulta el siguiente ejemplo en lakes.yaml.

Estos recursos se definen en archivos YAML que especifican data_mesh_types.Lakes.

Plantillas de etiquetas de Catalog

Las plantillas de etiquetas de Data Catalog se pueden usar para añadir contexto a tablas de BigQuery o a columnas concretas. Te ayudan a categorizar y comprender tus datos desde una perspectiva técnica y empresarial de forma integrada con las herramientas de búsqueda de Dataplex Universal Catalog. Definen los campos específicos que puedes usar para etiquetar tus datos y el tipo de información que puede contener cada campo (por ejemplo, texto, número o fecha). Las etiquetas de catálogo son instancias de las plantillas con valores de campo reales.

El campo de plantilla display_name se usa como ID de campo y debe cumplir los requisitos de TagTemplate.fields especificados en Class TagTemplate. Para obtener más información sobre los tipos de campos admitidos, consulta Tipos de campos de Data Catalog.

Cortex Data Mesh crea todas las plantillas de etiquetas como de lectura pública. También introduce un concepto adicional level en las especificaciones de las plantillas de etiquetas, que define si una etiqueta debe aplicarse a todo un recurso, a campos concretos de un recurso o a ambos. Los valores posibles son: ASSET | FIELD | ANY. Aunque no se aplique estrictamente ahora, las comprobaciones de validación futuras podrían asegurar que las etiquetas se apliquen en el nivel adecuado durante la implementación.

Consulta el siguiente ejemplo.

Las plantillas se definen en archivos YAML que especifican data_mesh_types.CatalogTagTemplates.

Las etiquetas de catálogo son instancias de las plantillas y se describen más abajo en la sección Anotaciones de recursos.

Control de acceso a nivel de recurso y de columna con plantillas de etiqueta

Cortex Framework permite habilitar el control de acceso a nivel de recurso o de columna en todos los artefactos asociados a una plantilla de etiqueta de catálogo. Por ejemplo, si los usuarios quieren conceder acceso a los recursos en función de la línea de negocio, pueden crear asset_policies para la plantilla de etiqueta de catálogo line_of_business con diferentes principales especificados para cada dominio empresarial. Cada política acepta filters que se puede usar para que solo coincidan las etiquetas con valores específicos. En este caso, podríamos hacer coincidir los valores de domain. Ten en cuenta que estos filterssolo admiten coincidencias de igualdad y ningún otro operador. Si se indican varios filtros, los resultados deben cumplir todos los filtros (por ejemplo, filter_a AND filter_b). El conjunto final de políticas de recursos es la unión de las definidas directamente en las anotaciones y las de las políticas de plantilla.

El control de acceso a nivel de columna con etiquetas de catálogo funciona de forma similar aplicando etiquetas de política a los campos coincidentes. Sin embargo, como solo se puede aplicar una etiqueta de política a una columna, el orden de prioridad es el siguiente:

1. Etiqueta de política directa: si se define una etiqueta de política directamente en la anotación de la columna, tiene prioridad.
2. Política de plantilla de etiqueta coincidente: de lo contrario, el acceso se determina mediante la primera política coincidente definida en un campo de la plantilla de etiqueta de catálogo asociada.

Cuando uses esta función, te recomendamos que habilites o inhabilites la implementación de etiquetas de catálogo y listas de control de acceso (LCA) al mismo tiempo. De esta forma, se asegura de que las ACLs se implementen correctamente.

Para conocer las especificaciones de esta función avanzada, consulta las definiciones de los parámetros asset_policies y field_policies en data_mesh_types.CatalogTagTemplate.

Glosario de catálogos

El glosario es una herramienta que se puede usar para proporcionar un diccionario de términos usados por columnas específicas de los recursos de datos que quizás no se entiendan de forma universal. Los usuarios pueden añadir términos manualmente en la consola, pero no se admiten especificaciones de recursos.

Taxonomías y etiquetas de políticas

Las taxonomías y las etiquetas de política permiten controlar el acceso a nivel de columna a los recursos de datos sensibles de forma estandarizada. Por ejemplo, podría haber una taxonomía de etiquetas que controle los datos personales de una línea de negocio concreta, en la que solo determinados grupos puedan leer datos anonimizados, datos sin anonimizar o no tengan acceso de lectura.

Para obtener más información sobre las taxonomías y las etiquetas de las políticas, consulta la introducción al enmascaramiento de datos de columnas. Las siguientes secciones son especialmente relevantes:

• Interacción entre roles
• Herencia de autorizaciones
• Reglas de enmascaramiento y jerarquía
• Prácticas recomendadas para las etiquetas de políticas

Cortex Framework proporciona etiquetas de política de ejemplo para mostrar cómo se especifican y los posibles usos. Sin embargo, los recursos que afectan al control de acceso no están habilitados de forma predeterminada en la implementación de Data Mesh.

Consulta el siguiente ejemplo.

Las taxonomías de políticas se definen en archivos YAML que especifican data_mesh_types.PolicyTaxonomies.

Anotaciones de recursos

Las anotaciones especifican los metadatos aplicables a un recurso concreto y pueden hacer referencia a los recursos de metadatos compartidos que se hayan definido. Las anotaciones incluyen lo siguiente:

• Descripciones de los recursos
• Descripciones de los campos
• Etiquetas de catálogo
• Control de acceso a nivel de recurso, fila y columna

Nota: Si modificas un archivo de anotaciones, ten en cuenta que la consola solo renderiza las líneas nuevas de las descripciones como espacios en blanco.

La base de datos de Cortex Framework ofrece anotaciones preconfiguradas (descripciones) para las siguientes cargas de trabajo.

• SAP ECC (sin procesar, CDC e informes)
• SAP S4 HANA (sin procesar, CDC e informes)
• SFDC (solo informes)
• Oracle EBS (solo informes)
• CM360 (solo informes)
• Google Ads (solo informes)
• Meta (solo para informes)
• SFMC (solo informes)
• TikTok (solo informes)
• YouTube (con DV360) (solo informes)
• Google Analytics 4 (solo informes)

Consulta el siguiente ejemplo.

Las anotaciones se definen en archivos YAML que especifican data_mesh_types.BqAssetAnnotation.

Etiquetas de catálogo

Las etiquetas de catálogo son instancias de las plantillas definidas, donde se asignan valores de campo que se aplican al recurso específico. Asegúrate de asignar valores que coincidan con los tipos de campo declarados en la plantilla asociada.

Los valores de TIMESTAMP deben tener uno de los siguientes formatos:

  "%Y-%m-%d %H:%M:%S%z"
  "%Y-%m-%d %H:%M:%S"
  "%Y-%m-%d"

Consulta el siguiente ejemplo.

Consulta la definición de Spec en data_mesh_types.CatalogTag.

Especificar lectores y principales de la política de acceso

Controla el acceso a tus datos de BigQuery en Cortex Framework mediante políticas de acceso. Estas políticas definen quiénes (las entidades) pueden acceder a recursos de datos específicos, a filas de un recurso o incluso a columnas concretas. Las entidades deben seguir un formato específico definido por miembro de enlace de política de IAM.

Acceso a nivel de recurso

Puede conceder acceso a recursos de BigQuery completos con varios permisos:

• READER: ver los datos del recurso.
• WRITER: modifica y añade datos al recurso.
• OWNER : control total sobre el recurso, incluida la gestión del acceso.

Estos permisos equivalen a la instrucción GRANT DCL en SQL.

A diferencia del comportamiento de la mayoría de los recursos y las anotaciones, la marca overwrite no elimina las entidades de seguridad que ya tengan el rol OWNERS. Cuando se añaden nuevos propietarios con la opción de sobrescribir habilitada, solo se añaden a los propietarios que ya había. Es una medida de protección para evitar la pérdida de acceso accidental. Para quitar propietarios de recursos, usa la consola. Al sobrescribir, se eliminan las entidades de seguridad que tengan el rol READER o WRITER.

Consulta el siguiente ejemplo.

Consulta la definición de Spec en data_mesh_types.BqAssetPolicy.

Acceso a nivel de fila

Puede conceder acceso a conjuntos de filas en función de determinados filtros de valores de columna. Al especificar la política de acceso a las filas, la cadena de filtro proporcionada se insertará en un CREATE DDL statement. Si la marca overwrite está habilitada, se eliminan todas las políticas de acceso a las filas antes de aplicar las nuevas.

Ten en cuenta lo siguiente sobre el acceso a nivel de fila:

• Si se añaden políticas de acceso a las filas, los usuarios que no se especifiquen en esas políticas no podrán ver ninguna fila.
• Las políticas de filas solo funcionan con tablas, no con vistas.
• No utilice columnas particionadas en los filtros de sus políticas de acceso a las filas. Consulta el archivo YAML de configuración de informes asociado para obtener información sobre el tipo de recurso y las columnas particionadas.

Para obtener más información sobre las políticas de acceso a nivel de fila, consulta las prácticas recomendadas de seguridad a nivel de fila.

Consulta el siguiente ejemplo.

Consulta la definición de Spec en data_mesh_types.BqRowPolicy.

Acceso a nivel de columna

Para habilitar el acceso a nivel de columna, anota los campos individuales con una etiqueta de política identificada por el nombre de la etiqueta de política y el nombre de la taxonomía. Actualiza el recurso de metadatos de la etiqueta de política para configurar el control de acceso.

Consulta el siguiente ejemplo.

Consulta la definición de Spec en data_mesh_types.PolicyTagId.

Desplegar la malla de datos

La malla de datos se puede implementar como parte de la implementación de la base de datos o por sí sola. En ambos casos, se usa el archivo Cortex config.json para determinar las variables relevantes, como los nombres de los conjuntos de datos de BigQuery y las opciones de implementación. De forma predeterminada, al implementar Data Mesh no se eliminarán ni se sobrescribirán los recursos o las anotaciones que ya tengas para evitar pérdidas accidentales. Sin embargo, también se pueden sobrescribir recursos existentes cuando se implementan por sí solos.

Opciones de implementación

Las siguientes opciones de implementación se pueden habilitar o inhabilitar en función de las necesidades del usuario y de las restricciones de gasto en config.json > DataMesh.

Nota: Te recomendamos que el control de acceso se realice únicamente a través de estas especificaciones de recursos si deployACLs está habilitado. De esta forma, se evita que se añada o se quite el acceso de forma accidental.

Opción	Notas
deployDescriptions	Esta es la única opción habilitada de forma predeterminada y despliega anotaciones de BigQuery con descripciones de recursos y columnas. No requiere que se habiliten APIs ni permisos adicionales.
deployLakes	Implementa lagos y zonas.
deployCatalog	Despliega recursos de plantilla de catálogo y sus etiquetas asociadas en anotaciones de recursos.
deployACLs	Despliega recursos de taxonomía de políticas y políticas de control de acceso a nivel de recurso, fila y columna mediante anotaciones de recursos. Los registros contienen mensajes que indican cómo han cambiado las políticas de acceso.

Despliegue con Data Foundation

De forma predeterminada, config.json > deployDataMesh permite desplegar las descripciones de los recursos de la malla de datos al final de cada paso de compilación de la carga de trabajo. Esta configuración predeterminada no requiere que se habiliten APIs ni roles adicionales. Se pueden implementar funciones adicionales de la malla de datos con la base de datos habilitando las opciones de implementación, las APIs y los roles necesarios, y modificando las especificaciones de recursos asociadas.

Despliegue en solitario

Para implementar Data Mesh por sí solo, los usuarios pueden usar el archivo common/data_mesh/deploy_data_mesh.py. Esta utilidad se usa durante los procesos de compilación para desplegar la malla de datos una carga de trabajo a la vez, pero, si se llama directamente, también se puede usar para desplegar varias cargas de trabajo a la vez. Las cargas de trabajo de las especificaciones que se van a implementar deben habilitarse en el archivo config.json. Por ejemplo, asegúrate de que deploySAP=true si vas a implementar Data Mesh para SAP.

Para asegurarte de que la implementación se realiza con los paquetes y las versiones necesarios, puedes ejecutar la utilidad desde la misma imagen que usa el proceso de implementación de Cortex con los siguientes comandos:

  # Run container interactively
  docker container run -it gcr.io/kittycorn-public/deploy-kittycorn:v2.0

  # Clone the repo
  git clone https://github.com/GoogleCloudPlatform/cortex-data-foundation

  # Navigate into the repo
  cd cortex-data-foundation

Para obtener ayuda sobre los parámetros disponibles y su uso, ejecuta el siguiente comando:

  python src/common/data_mesh/deploy_data_mesh.py -h

A continuación, se muestra un ejemplo de invocación para SAP ECC:

  python src/common/data_mesh/deploy_data_mesh.py \
    --config-file config/config.json \
    --lake-directories \
        src/SAP/SAP_REPORTING/config/ecc/lakes \
    --tag-template-directories \
        src/SAP/SAP_REPORTING/config/ecc/tag_templates \
    --policy-directories \
        src/SAP/SAP_REPORTING/config/ecc/policy_taxonomies \
    --annotation-directories \
        src/SAP/SAP_REPORTING/config/ecc/annotations

Consulta la sección Directorios de Data Mesh para obtener información sobre las ubicaciones de los directorios.

Sobrescribir

Advertencia: Lee esta sección detenidamente antes de usar la opción de sobrescribir.

De forma predeterminada, al implementar Data Mesh no se sobrescribirán los recursos ni las anotaciones. Sin embargo, la marca --overwrite se puede habilitar al desplegar Data Mesh por sí solo para cambiar el despliegue de las siguientes formas.

Al sobrescribir recursos de metadatos, como lagos, plantillas de etiquetas de catálogo y etiquetas de políticas, se eliminan los recursos que tengan el mismo nombre, pero no se modifican los recursos que tengan nombres diferentes. Esto significa que, si se elimina por completo una especificación de recurso del archivo YAML y, a continuación, se vuelve a implementar Data Mesh con la opción de sobrescribir habilitada, esa especificación de recurso no se eliminará porque no habrá colisión de nombres. De esta forma, la implementación de Cortex Data Mesh no afectará a los recursos que ya estén en uso.

En el caso de los recursos anidados, como Lakes y Zones, si se sobrescribe un recurso, se eliminan todos sus elementos secundarios. Por ejemplo, si sobrescribes un Lake, también se eliminarán sus zonas y referencias de recursos. En el caso de las plantillas de etiquetas de catálogo y las etiquetas de políticas que se sobrescriben, las referencias de anotación asociadas se quitan de los recursos. Si sobrescribes etiquetas de catálogo en una anotación de un recurso, solo se sobrescribirán las instancias de etiquetas de catálogo que compartan la misma plantilla.

Las sobreescrituras de las descripciones de los recursos y los campos solo se aplican si se proporciona una descripción nueva válida y no vacía que entre en conflicto con la descripción actual.

Por otro lado, las ACLs se comportan de forma diferente. Si se sobrescriben las LCAs, se eliminan todos los principales (excepto los propietarios a nivel de recurso). Esto se debe a que los principales que se omiten en las políticas de acceso son tan importantes como los principales a los que se les concede acceso.

Explorar la malla de datos

Una vez implementada la malla de datos, los usuarios pueden buscar y ver los recursos de datos con Data Catalog. Esto incluye la posibilidad de descubrir recursos en función de los valores de las etiquetas del catálogo que se hayan aplicado. Los usuarios también pueden crear y aplicar manualmente términos del glosario del catálogo si es necesario.

Las políticas de acceso que se han implementado se pueden ver en la página Esquema de BigQuery para consultar las políticas aplicadas a un recurso concreto en cada nivel.

Linaje de datos

Los usuarios pueden habilitar y visualizar la procedencia de los recursos de BigQuery. También se puede acceder al linaje de forma programática a través de la API. Linaje de datos solo admite el linaje a nivel de recurso. Data Lineage no está entrelazado con Cortex Data Mesh, pero es posible que se introduzcan nuevas funciones en el futuro que utilicen Lineage.

Si tienes alguna solicitud relacionada con Cortex Data Mesh o Cortex Framework, ve a la sección de asistencia.