Integração do Knowledge Catalog

Este documento explica como o Cortex Framework se integra ao Knowledge Catalog, que atua como a camada de governança para produtos de dados corporativos em toda a organização. Ele também explica como a ferramenta de sincronização do Knowledge Catalog do Google Cloud Cortex Framework ajuda a registrar e sincronizar produtos de dados do Google Cloud Cortex Framework com o Knowledge Catalog, simplificando a descoberta e o compartilhamento seguro deles.

Ao ativar essa integração, os produtos de dados do Cortex Framework implantados, incluindo as descrições comerciais enriquecidas, os metadados de propriedade e os conjuntos de dados e tabelas físicos do BigQuery, são catalogados automaticamente e disponibilizados para descoberta no Knowledge Catalog.

Principais vantagens

A integração do Cortex Framework com o Knowledge Catalog oferece os seguintes benefícios principais:

  • Descoberta automatizada de dados: os usuários podem navegar e pesquisar produtos de dados corporativos padronizados diretamente na interface do Knowledge Catalog sem precisar de entrada manual do catálogo.
  • Contexto comercial enriquecido: importa automaticamente nomes de exibição, descrições comerciais detalhadas e URLs de documentação diretamente de arquivos manifest.yaml para o Knowledge Catalog.
  • Vinculação unificada de recursos: conecta tabelas de base de relatórios conformes individuais diretamente aos produtos de dados correspondentes do Knowledge Catalog. Isso oferece aos consumidores de dados visibilidade imediata sobre quais objetos de dados físicos alimentam domínios comerciais específicos.
  • Reconciliação automatizada do ciclo de vida e da variação: à medida que os modelos de dados corporativos evoluem, a execução da ferramenta de sincronização reconcilia automaticamente os metadados e os links de recursos. Ela registra novas tabelas, atualiza definições modificadas e remove links obsoletos, protegendo itens de catálogo não gerenciados e criados pelo usuário.
  • Segurança do gerenciamento do sistema: usa rótulos de sistema dedicados (cortex-framework-created e cortex-framework-version) para identificar e gerenciar apenas os recursos criados pelo Cortex Framework, evitando substituições acidentais de recursos do Knowledge Catalog gerenciados pelo cliente.

Como a integração funciona

Principais componentes da solução do Google Cloud Cortex Framework

A integração do Knowledge Catalog é feita pela ferramenta de sincronização cortex-kc-sync (tools.dataplex.kc_sync). Quando executado, o sincronizador realiza o seguinte fluxo de trabalho de várias etapas:

Sincronização do Google Cloud Cortex Framework com o Knowledge Catalog

1. Extração de configuração e manifesto

O sincronizador analisa o arquivo de configuração global config/config.yaml para identificar todos os módulos de produtos de dados ativados (data.modules.products) e os conjuntos de dados de destino do BigQuery (data.targets).

Para cada módulo ativado, o sincronizador extrai metadados descritivos do manifest.yaml do módulo (usando o provedor de módulos do espaço de trabalho):

  • displayName: o título legível do produto de dados.
  • description: o resumo comercial do módulo.
  • documentation: URL que aponta para a documentação do módulo interno ou externo.

2. Descoberta de recursos do BigQuery

Em vez de verificar uma lista estática de definições de tabela, cortex-kc-sync consulta o BigQuery (list_dataset_tables) para descobrir dinamicamente quais tabelas e visualizações já estão implantadas no conjunto de dados de destino.

Ele resolve e filtra tabelas procurando rótulos de rastreamento específicos aplicados durante a implantação:

  • cortex-framework-namespaced-module-type que corresponde ao caminho do módulo totalmente qualificado (por exemplo, cortex.sap.products.sales_performance) ou
  • cortex-framework-module-type que corresponde ao nome canônico do tipo de módulo (por exemplo, sales_performance).

Somente as tabelas e visualizações materializadas que contêm esses rótulos no BigQuery serão catalogadas e vinculadas como recursos no produto de dados.

3. Reconciliação e rotulagem de recursos gerenciados

O sincronizador se comunica com a API dataplex_v1 (DataProductClient) para reconciliar cada produto de dados descoberto no target Google Cloud location:

  • Criação (NEEDS_CREATION): se o produto de dados não existir, o sincronizador criará um novo produto de dados do Knowledge Catalog preenchido com os metadados do manifesto extraídos e vinculará os recursos resolvidos do BigQuery. Ele marca o recurso com dois rótulos de sistema:

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

  • Proteção de recursos não gerenciados (NOT_MANAGED): se um produto de dados do Knowledge Catalog com o mesmo ID já existir no catálogo, mas estiver faltando esses rótulos de sistema (is_managed_data_product == False), o sincronizador vai ignorá-lo para proteger os recursos de catálogo criados pelo usuário ou pré-existentes.

  • Atualizações (NEEDS_UPDATE): se um produto de dados gerenciado existir e tiver mudanças nos metadados ou na composição da tabela, o sincronizador atualizará a definição do produto de dados do Knowledge Catalog e reconciliará os recursos vinculados do BigQuery (BigQueryAssetLinks). Ele cria automaticamente novos links DataAsset para tabelas recém-adicionadas e exclui os obsoletos, deixando os links inalterados intactos.

Configuração

Esta seção descreve os pré-requisitos, a configuração de metadados e as etapas de execução necessárias para configurar e executar a sincronização entre o Cortex Framework e o Knowledge Catalog.

Pré-requisitos

Antes de executar a sincronização do Knowledge Catalog, verifique se você atende aos seguintes requisitos:

Ativar Google Cloud serviços

Nesta seção, vamos ativar os serviços a seguir no seu projetoGoogle Cloud : Google Cloud

  • API Cloud Dataplex (dataplex.googleapis.com)

Ative este Google Cloud serviço usando o Cloud Shell executando o seguinte comando no terminal:

gcloud config set project PROJECT_ID

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

Papéis para o projeto de destino

Para receber a permissão necessária para sincronizar o Knowledge Catalog, peça que o administrador conceda a você os seguintes papéis do IAM no projeto de destino:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a dataplex.dataProducts.create, dataplex.dataProducts.update, dataplex.dataAssets.create, dataplex.dataAssets.delete permissão, que é necessária para sincronizar o Knowledge Catalog.

Também é possível conseguir essa permissão com papéis personalizados ou outros papéis predefinidos.

Para conceder os papéis solicitados a um usuário, use o 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 do Dataform executado

Primeiro, execute cortex-build-and-deploy ou cortex-deploy, conforme descrito no guia de implantação, e execute as ações do pipeline do Dataform para materializar as tabelas e visualizações do BigQuery antes de tentar sincronizar com o Knowledge Catalog. Para instruções detalhadas sobre como executar transformações, consulte Etapas pós-implantação.

Como configurar metadados de produtos de dados

É possível personalizar os met0/ados comerciais exibidos no Knowledge Catalog modificando o arquivo manifest.yaml localizado dentro de cada diretório de módulo de produto de dados (por exemplo, src/data_modules/cortex/sap/products/accounts_payable/manifest.yaml).

O exemplo a seguir demonstra como definir displayName, description e documentation em um manifesto 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

Como executar o comando de sincronização

Depois que os produtos de dados forem implantados e materializados no BigQuery, execute a ferramenta de CLI cortex-kc-sync usando uv:

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

Para uma lista completa de flags e argumentos disponíveis, consulte a referência de sincronização da CLI KC (uv run cortex-kc-sync).

Verificação da sincronização do Knowledge Catalog

Para verificar a sincronização bem-sucedida entre os recursos do Google Cloud Cortex Framework e o Knowledge Catalog, siga estas etapas:

  • No Google Cloud console, abra o Knowledge Catalog.
  • Opcional: na caixa de diálogo de pesquisa, você pode usar um dos filtros rápidos, como Data Products ou Tables.
  • No campo de pesquisa da tela principal do Knowledge Catalog, clique em Filters.
  • Na visualização Filters aberta, selecione na lista suspensa Project o projeto que você está usando para sincronizar os produtos de dados do Google Cloud Cortex Framework.
  • Após uma sincronização bem-sucedida, você pode selecionar ou pesquisar um recurso de dados exposto pelo Google Cloud Cortex Framework, incluindo todos os metadados publicados.

Como automatizar o fluxo de trabalho

Em ambientes de produção, recomendamos executar cortex-kc-sync automaticamente como uma etapa de pós-processamento no pipeline de orquestração de CI/CD ou no DAG do Knowledge Catalog (Airflow) imediatamente após a execução bem-sucedida do pipeline do Dataform:

  1. Criar e implantar: execute cortex-deploy (uv run cortex-deploy --config config/config.yaml) para compilar e preparar configurações para o Dataform.
  2. Executar transformações: acione execuções do Dataform para materializar camadas de base de dados e tabelas de relatórios conformes no BigQuery.
  3. Sincronização do catálogo: execute cortex-kc-sync (uv run cortex-kc-sync --config config/config.yaml) para verificar a criação de tabelas e sincronizar todos os produtos de dados, descrições e links de linhagem atualizados diretamente no Knowledge Catalog.

Próximas etapas