Integrazione di Knowledge Catalog

Questo documento spiega come Cortex Framework si integra con Knowledge Catalog, che funge da livello di governance per i prodotti di dati aziendali in tutta l'organizzazione. Spiega anche come lo strumento di sincronizzazione di Knowledge Catalog di Google Cloud Cortex Framework aiuta a registrare e sincronizzare i prodotti di dati di Google Cloud Cortex Framework con Knowledge Catalog, semplificandone il rilevamento e la condivisione sicura.

Se abiliti questa integrazione, i prodotti di dati di Cortex Framework di cui hai eseguito il deployment, inclusi le descrizioni aziendali arricchite, i metadati di proprietà e i set di dati e le tabelle BigQuery fisici sottostanti, vengono catalogati automaticamente e resi rilevabili in Knowledge Catalog.

Vantaggi principali

L'integrazione di Cortex Framework con Knowledge Catalog offre i seguenti vantaggi principali:

• Rilevabilità automatica dei dati: gli utenti possono sfogliare e cercare i prodotti di dati aziendali standardizzati direttamente nell'interfaccia utente di Knowledge Catalog senza richiedere l'inserimento manuale nel catalogo.
• Contesto aziendale arricchito: importa automaticamente i nomi visualizzati, le descrizioni aziendali dettagliate e gli URL della documentazione direttamente dai file manifest.yaml in Knowledge Catalog.
• Collegamento unificato degli asset: collega le singole tabelle di base dei report conformi direttamente ai prodotti di dati di Knowledge Catalog corrispondenti. In questo modo, i consumatori di dati hanno una visibilità immediata degli oggetti dati fisici che alimentano domini aziendali specifici.
• Riconciliazione automatica del ciclo di vita e della deriva: man mano che i modelli di dati aziendali si evolvono, l'esecuzione dello strumento di sincronizzazione riconcilia automaticamente i metadati e i link agli asset. Registra nuove tabelle, aggiorna le definizioni modificate e rimuove i link obsoleti proteggendo al contempo gli elementi del catalogo non gestiti creati dall'utente.
• Sicurezza della gestione del sistema: utilizza etichette di sistema dedicate (cortex-framework-created e cortex-framework-version) per identificare e gestire solo le risorse create da Cortex Framework, impedendo la sovrascrittura accidentale degli asset di Knowledge Catalog esistenti gestiti dal cliente.

Come funziona l'integrazione

L'integrazione di Knowledge Catalog è basata sullo strumento di sincronizzazione cortex-kc-sync (tools.dataplex.kc_sync). Quando viene eseguito, il sincronizzatore esegue il seguente flusso di lavoro in più passaggi:

1. Configurazione ed estrazione del manifest

Il sincronizzatore analizza il file di configurazione config/config.yaml globale per identificare tutti i moduli di prodotti di dati abilitati (data.modules.products) e i relativi set di dati BigQuery di destinazione (data.targets).

Per ogni modulo abilitato, il sincronizzatore estrae i metadati descrittivi da manifest.yaml del modulo (utilizzando il provider di moduli dello spazio di lavoro):

• displayName: il titolo leggibile del prodotto di dati.
• description: il riepilogo aziendale del modulo.
• documentation: l'URL che rimanda alla documentazione del modulo interna o esterna.

Nota: Proprietà del prodotto di dati: i metadati dell'email di proprietà non vengono estratti da manifest.yaml. Vengono invece configurati a livello globale durante la sincronizzazione utilizzando l'argomento della riga di comando --owner-email.

2. Rilevamento degli asset BigQuery

Anziché verificare un elenco statico di definizioni di tabelle, cortex-kc-sync esegue query su BigQuery (list_dataset_tables) per scoprire dinamicamente quali tabelle e viste sono già di cui è stato eseguito il deployment nel set di dati di destinazione.

Risolve e filtra le tabelle cercando etichette di monitoraggio specifiche applicate durante il deployment:

• cortex-framework-namespaced-module-type che corrisponde al percorso del modulo completo (ad es. cortex.sap.products.sales_performance) oppure
• cortex-framework-module-type che corrisponde al nome del tipo di modulo canonico (ad es. sales_performance).

Solo le tabelle e le viste materializzate che contengono queste etichette in BigQuery verranno catalogate e collegate come asset nel prodotto di dati.

3. Riconciliazione ed etichettatura delle risorse gestite

Il sincronizzatore comunica con l'API dataplex_v1 (DataProductClient) per riconciliare ogni prodotto di dati rilevato nella destinazione di destinazione Google Cloud :

• Creazione (NEEDS_CREATION): se il prodotto di dati non esiste, il sincronizzatore crea un nuovo prodotto di dati di Knowledge Catalog compilato con i metadati del manifest estratti e collega gli asset BigQuery risolti. Assegna alla risorsa due etichette di sistema:

  • cortex-framework-created: impostato su "true"
  • cortex-framework-version: impostato su "7-0-0"

• Protezione delle risorse non gestite (NOT_MANAGED): se nel catalogo esiste già un prodotto di dati di Knowledge Catalog con lo stesso ID, ma mancano queste etichette di sistema (is_managed_data_product == False), il sincronizzatore lo salta per proteggere gli asset del catalogo creati dall'utente o preesistenti.

• Aggiornamenti (NEEDS_UPDATE): se esiste un prodotto di dati gestito e sono state apportate modifiche ai metadati o alla composizione della tabella, il sincronizzatore aggiorna la definizione del prodotto di dati di Knowledge Catalog e riconcilia gli asset BigQuery collegati (BigQueryAssetLinks). Crea automaticamente nuovi link DataAsset per le tabelle appena aggiunte ed elimina quelli obsoleti, lasciando intatti i link invariati.

Installazione e configurazione

Questa sezione descrive i prerequisiti, la configurazione dei metadati e i passaggi di esecuzione necessari per configurare ed eseguire la sincronizzazione tra Cortex Framework e Knowledge Catalog.

Prerequisiti

Prima di eseguire la sincronizzazione di Knowledge Catalog, assicurati di aver soddisfatto i seguenti requisiti:

Abilita Google Cloud servizi

In questa sezione abiliteremo i seguenti Google Cloud servizi nel tuo Google Cloud progetto:

• API Cloud Dataplex (dataplex.googleapis.com)

Abilita questo Google Cloud servizio utilizzando Cloud Shell eseguendo il seguente comando nel terminale:

gcloud config set project PROJECT_ID

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

Ruoli per il progetto di destinazione

Per ottenere l'autorizzazione necessaria per sincronizzare Knowledge Catalog, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto di destinazione:

• Editor Dataplex (roles/dataplex.editor)
• Editor di prodotti di dati Dataplex (roles/dataplex.dataProductsEditor)
• Proprietario della voce Dataplex (roles/dataplex.entryOwner)
• Visualizzatore di metadati BigQuery (roles/bigquery.metadataViewer)
• Visualizzatore dati BigQuery (roles/bigquery.dataViewer)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l' dataplex.dataProducts.create, dataplex.dataProducts.update, dataplex.dataAssets.create, dataplex.dataAssets.delete autorizzazione, necessaria per sincronizzare Knowledge Catalog.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Per concedere i ruoli richiesti a un utente, puoi utilizzare lo script:

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 eseguita

Prima di tentare la sincronizzazione con Knowledge Catalog, devi prima eseguire cortex-build-and-deploy o cortex-deploy come descritto nella guida al deployment ed eseguire le azioni della pipeline Dataform per materializzare le tabelle e le viste BigQuery. Per istruzioni dettagliate sull'esecuzione delle trasformazioni, consulta Passaggi post-deployment.

Nota: se vuoi utilizzare Knowledge Catalog con il deployment demo, crea il file di configurazione config/config.yaml come descritto in Configurazione del deployment.

Nota: Limiti degli asset: Dataplex supporta un massimo di 100 asset (tabelle) per prodotto di dati. Se un prodotto di dati contiene più di 50 tabelle, cortex-kc-sync non riuscirà a eseguire l'operazione e verrà visualizzato un errore.

Configurazione dei metadati del prodotto di dati

Puoi personalizzare i metadati aziendali visualizzati in Knowledge Catalog modificando il file manifest.yaml che si trova all'interno di ogni directory del modulo del prodotto di dati (ad esempio, src/data_modules/cortex/sap/products/accounts_payable/manifest.yaml).

L'esempio seguente mostra come definire displayName, description e documentation in un manifest del modulo:

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

Esecuzione del comando di sincronizzazione

Dopo che è stato eseguito il deployment e la materializzazione dei prodotti di dati in BigQuery, esegui lo strumento CLI cortex-kc-sync utilizzando uv:

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

Per un elenco completo dei flag e degli argomenti disponibili, consulta la documentazione di riferimento della sincronizzazione CLI KC (uv run cortex-kc-sync).

Verifica della sincronizzazione di Knowledge Catalog

Per verificare la corretta sincronizzazione tra gli asset di Google Cloud Cortex Framework e Knowledge Catalog, segui questi passaggi:

• In Google Cloud console, apri Knowledge Catalog
• (Facoltativo) Nella finestra di dialogo di ricerca puoi utilizzare uno dei filtri rapidi, ad esempio Data Products o Tables.
• Nel campo di ricerca della schermata principale di Knowledge Catalog, fai clic su Filters.
• Nella visualizzazione Filters aperta, seleziona dal menu a discesa Project il progetto che stai utilizzando per sincronizzare i prodotti di dati di Google Cloud Cortex Framework.
• Dopo una sincronizzazione riuscita, puoi selezionare o cercare un asset di dati esposto da Google Cloud Cortex Framework, inclusi tutti i metadati pubblicati.

Automatizzazione del flusso di lavoro

Negli ambienti di produzione, ti consigliamo di eseguire cortex-kc-sync automaticamente come passaggio di post-elaborazione all'interno della pipeline di orchestrazione CI/CD o del DAG di Knowledge Catalog (Airflow) immediatamente dopo l'esecuzione corretta della pipeline Dataform:

1. Crea ed esegui il deployment: esegui cortex-deploy (uv run cortex-deploy --config config/config.yaml) per compilare e preparare le configurazioni per Dataform.
2. Esegui le trasformazioni: attiva le esecuzioni di Dataform per materializzare i livelli di base dei dati e le tabelle di report conformi in BigQuery.
3. Sincronizzazione del catalogo: esegui cortex-kc-sync (uv run cortex-kc-sync --config config/config.yaml) per verificare la creazione delle tabelle e sincronizzare tutti i prodotti di dati, le descrizioni e i link di derivazione aggiornati direttamente in Knowledge Catalog.

Passaggi successivi

• Crea prodotti di dati personalizzati: consulta la guida all'estensibilità: creazione di moduli di prodotti di dati per creare nuovi prodotti di dati o estendere gli schemi.