Intégration de Knowledge Catalog

Ce document explique comment Cortex Framework s'intègre à Knowledge Catalog, qui sert de couche de gouvernance pour les produits de données d'entreprise dans votre organisation. Il explique également comment l'outil de synchronisation Google Cloud Cortex Framework Knowledge Catalog permet d'enregistrer et de synchroniser les produits de données Google Cloud Cortex Framework avec Knowledge Catalog, ce qui simplifie leur découverte et leur partage sécurisé.

En activant cette intégration, les produits de données Cortex Framework déployés, y compris leurs descriptions commerciales enrichies, leurs métadonnées de propriété et les ensembles de données et tables BigQuery physiques sous-jacents, sont automatiquement catalogués et rendus détectables dans Knowledge Catalog.

Principaux avantages

L'intégration de Cortex Framework à Knowledge Catalog offre les avantages clés suivants :

  • Découvrabilité automatisée des données : les utilisateurs peuvent parcourir et rechercher des produits de données d'entreprise standardisés directement dans l'interface utilisateur de Knowledge Catalog, sans avoir à saisir manuellement le catalogue.
  • Contexte commercial enrichi : importe automatiquement les noms à afficher, les descriptions commerciales détaillées et les URL de documentation directement à partir des fichiers manifest.yaml dans Knowledge Catalog.
  • Association unifiée des éléments : connecte directement les tables de base de rapports conformes individuelles à leurs produits de données Knowledge Catalog correspondants. Les utilisateurs de données peuvent ainsi voir immédiatement quels objets de données physiques alimentent des domaines d'activité spécifiques.
  • Réconciliation automatisée du cycle de vie et de la dérive : à mesure que vos modèles de données d'entreprise évoluent, l'exécution de l'outil de synchronisation réconcilie automatiquement les métadonnées et les liens d'éléments. Il enregistre les nouvelles tables, met à jour les définitions modifiées et supprime les liens obsolètes tout en protégeant les éléments de catalogue non gérés créés par l'utilisateur.
  • Sécurité de la gestion du système : utilise des libellés système dédiés (cortex-framework-created et cortex-framework-version) pour identifier et gérer uniquement les ressources créées par Cortex Framework, ce qui évite les écrasements accidentels des éléments Knowledge Catalog existants gérés par le client.

Fonctionnement de l'intégration

Composants clés de la solution Google Cloud Cortex Framework

L'intégration de Knowledge Catalog est alimentée par l'outil de synchronisation cortex-kc-sync (tools.dataplex.kc_sync). Lorsqu'il est exécuté, le synchroniseur effectue le workflow en plusieurs étapes suivant :

Synchronisation de Google Cloud Cortex Framework avec le Knowledge Catalog

1. Configuration et extraction du fichier manifeste

Le synchroniseur analyse votre fichier de configuration config/config.yaml global pour identifier tous les modules de produits de données activés (data.modules.products) et leurs ensembles de données BigQuery cibles (data.targets).

Pour chaque module activé, le synchroniseur extrait les métadonnées descriptives du manifest.yaml du module (à l'aide du fournisseur de module d'espace de travail) :

  • displayName : titre lisible du produit de données.
  • description : résumé commercial du module.
  • documentation : URL pointant vers la documentation interne ou externe du module.

2. Découverte des éléments BigQuery

Au lieu de vérifier une liste statique de définitions de table, cortex-kc-sync interroge BigQuery (list_dataset_tables) pour découvrir de manière dynamique les tables et les vues déjà déployées dans votre ensemble de données cible.

Il résout et filtre les tables en recherchant des libellés de suivi spécifiques appliqués lors du déploiement :

  • cortex-framework-namespaced-module-type correspondant au chemin d'accès complet du module (par exemple, cortex.sap.products.sales_performance), ou
  • cortex-framework-module-type correspondant au nom canonique du type de module (par exemple, sales_performance).

Seules les tables et les vues matérialisées qui comportent ces libellés dans BigQuery seront cataloguées et liées en tant qu'éléments sous le produit de données.

3. Réconciliation et libellisation des ressources gérées

Le synchroniseur communique avec l'API dataplex_v1 (DataProductClient) pour réconcilier chaque produit de données découvert dans le target Google Cloud location :

  • Création (NEEDS_CREATION) : si le produit de données n'existe pas, le synchroniseur crée un produit de données Knowledge Catalog rempli avec les métadonnées du fichier manifeste extraites et lie les éléments BigQuery résolus. Il ajoute deux libellés système à la ressource :

    • cortex-framework-created : défini sur "true"
    • cortex-framework-version : défini sur "7-0-0"

  • Protection des ressources non gérées (NOT_MANAGED) : si un produit de données Knowledge Catalog portant le même ID existe déjà dans le catalogue, mais qu'il ne comporte pas ces libellés système (is_managed_data_product == False), le synchroniseur l'ignore pour protéger les éléments de catalogue créés par l'utilisateur ou préexistants.

  • Mises à jour (NEEDS_UPDATE) : si un produit de données géré existe et que sa composition de métadonnées ou de tables a été modifiée, le synchroniseur met à jour la définition du produit de données Knowledge Catalog et réconcilie ses éléments BigQuery liés (BigQueryAssetLinks). Il crée automatiquement des liens DataAsset pour les tables nouvellement ajoutées et supprime les liens obsolètes, tout en laissant intacts les liens inchangés.

Installation et configuration

Cette section décrit les prérequis, la configuration des métadonnées et les étapes d'exécution nécessaires pour configurer et exécuter la synchronisation entre Cortex Framework et Knowledge Catalog.

Prérequis

Avant d'exécuter la synchronisation de Knowledge Catalog, assurez-vous de remplir les conditions suivantes :

Activer Google Cloud les services

Dans cette section, nous allons activer les services suivants Google Cloud dans votre Google Cloud projet :

  • API Cloud Dataplex (dataplex.googleapis.com)

Activez ce Google Cloud service à l'aide de Cloud Shell en exécutant la commande suivante dans votre terminal :

gcloud config set project PROJECT_ID

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

Rôles pour le projet cible

Pour obtenir l'autorisation nécessaire pour synchroniser Knowledge Catalog, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet cible :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l' dataplex.dataProducts.create, dataplex.dataProducts.update, dataplex.dataAssets.create, dataplex.dataAssets.delete autorisation, qui est nécessaire pour synchroniser Knowledge Catalog.

Vous pouvez également obtenir cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour accorder les rôles demandés à un utilisateur, vous pouvez utiliser le script suivant :

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"

Pipeline Dataform exécuté

Vous devez d'abord exécuter cortex-build-and-deploy ou cortex-deploy, comme décrit dans le guide de déploiement, et exécuter les actions de votre pipeline Dataform pour matérialiser les tables et les vues BigQuery avant de tenter la synchronisation avec Knowledge Catalog. Pour obtenir des instructions détaillées sur l'exécution des transformations, consultez la section Étapes post-déploiement.

Configurer les métadonnées du produit de données

Vous pouvez personnaliser les métadonnées commerciales affichées dans Knowledge Catalog en modifiant le fichier manifest.yaml situé dans chaque répertoire de module de produit de données (par exemple, src/data_modules/cortex/sap/products/accounts_payable/manifest.yaml).

L'exemple suivant montre comment définir displayName, description et documentation dans un fichier manifeste de module :

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

Exécuter la commande de synchronisation

Une fois vos produits de données déployés et matérialisés dans BigQuery, exécutez l'outil de CLI cortex-kc-sync à l'aide de uv :

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

Pour obtenir la liste complète des options et arguments disponibles, consultez la documentation de référence sur la synchronisation de la ligne de commande KC (uv run cortex-kc-sync).

Vérification de la synchronisation de Knowledge Catalog

Pour vérifier que la synchronisation entre les éléments Google Cloud Cortex Framework et Knowledge Catalog a réussi, procédez comme suit :

  • Dans la Google Cloud console, ouvrez Knowledge Catalog.
  • Facultatif : dans la boîte de dialogue de recherche, vous pouvez utiliser l'un des filtres rapides, comme Data Products ou Tables.
  • Dans le champ de recherche de l'écran principal de Knowledge Catalog, cliquez sur Filters.
  • Dans la vue Filters qui s'ouvre, sélectionnez dans le menu déroulant Project le projet que vous utilisez pour synchroniser les produits de données Google Cloud Cortex Framework.
  • Une fois la synchronisation réussie, vous pouvez sélectionner ou rechercher un élément de données exposé par Google Cloud Cortex Framework, y compris toutes les métadonnées publiées.

Automatiser le workflow

Dans les environnements de production, nous vous recommandons d'exécuter cortex-kc-sync automatiquement en tant qu'étape de post-traitement dans votre pipeline d'orchestration CI/CD ou votre DAG Knowledge Catalog (Airflow) immédiatement après l'exécution réussie du pipeline Dataform :

  1. Créer et déployer : exécutez cortex-deploy (uv run cortex-deploy --config config/config.yaml) pour compiler et préparer les configurations dans Dataform.
  2. Exécuter les transformations : déclenchez des exécutions Dataform pour matérialiser les couches de base de données et les tables de rapports conformes dans BigQuery.
  3. Synchronisation du catalogue : exécutez cortex-kc-sync (uv run cortex-kc-sync --config config/config.yaml) pour vérifier la création de la table et synchroniser tous les produits de données, descriptions et liens de traçabilité mis à jour directement dans Knowledge Catalog.

Étapes suivantes