Guia do usuário do Data Mesh

A estrutura Data Mesh para Cortex Framework estende a base de dados para permitir governança, capacidade de descoberta e controle de acesso de dados usando os metadados do BigQuery e o Dataplex. Isso é implementado fornecendo um conjunto básico de recursos de metadados e anotações de recursos do BigQuery que podem ser personalizadas e implantadas opcionalmente com a base de dados. Essas especificações básicas fornecem uma configuração personalizada que é a base de metadados para complementar a base de dados do Cortex Framework. Consulte os conceitos de Data Mesh antes de continuar com este guia.

As etapas descritas nesta página foram projetadas especificamente para configurar a Data Mesh para o Cortex Framework. Encontre os arquivos de configuração do Data Mesh nas pastas específicas de cada carga de trabalho na seção de diretórios do Data Mesh.

Aviso: este guia sobre a malha de dados pode mudar com o tempo. Entre em contato com a equipe do Cortex para enviar feedback ou relatar problemas relacionados.

Figura 1. Arquitetura de malha de dados para o Cortex Framework.

Design

A malha de dados do Cortex foi projetada de forma semelhante à base de dados geral e consiste de três fases com diferentes subcomponentes gerenciados pelo Cortex ou pelos usuários:

1. Atualização das especificações de recursos básicos: a cada versão, o Cortex atualiza as especificações de recursos básicos, fornecendo uma base de metadados padronizada para a malha de dados.
2. Personalização das especificações de recursos: antes da implantação, os usuários podem adaptar as especificações de recursos para alinhar com os casos de uso e requisitos específicos.
3. Implantação e atualizações da malha de dados:os usuários podem ativar a malha de dados no arquivo de configuração do Cortex. Ele é implantado após os recursos de dados durante a implantação do Cortex. Além disso, os usuários têm a flexibilidade de implantar a malha de dados de forma independente para outras atualizações.

Figura 2. Design de malha de dados para o Cortex Framework.

Diretórios do Data Mesh

Encontre os arquivos de configuração de base da malha de dados para cada carga de trabalho e fonte de dados nos seguintes locais. Os diretórios têm estruturas de arquivo diferentes, mas todas as especificações são localizadas de maneira semelhante na pasta config.

Carga de trabalho	Fonte de dados	Caminho do diretório
Operacional	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 (com o DV360)	src/marketing/src/DV360/config
	Google Analytics 4	src/marketing/src/GA4/config

Observação: a malha de dados não é compatível com dados da LiveRamp ou da Dun & Bradstreet (ESG).

Os recursos de metadados são definidos no nível da fonte de dados com um único arquivo YAML por projeto Google Cloud e contêm uma lista de todos os recursos. Os usuários podem estender o arquivo atual ou criar outros arquivos YAML com especificações de recursos adicionais nesse diretório, se necessário.

As anotações de recursos são definidas no nível do recurso e contêm muitos arquivos YAML no diretório com uma única anotação por arquivo.

Ativar APIs e verificar permissões

Modificar os valores padrão da malha de dados permite implementar recursos além das descrições. Se você precisar modificar os valores padrão da malha de dados em config.json para implementar recursos além das descrições, verifique se as APIs necessárias e as permissões de confirmação estão definidas conforme descrito na tabela a seguir. Ao implantar a Data Mesh com a base de dados, conceda permissões ao usuário que está fazendo a implantação ou à conta do Cloud Build. Se a implantação envolver projetos de origem e de destino diferentes, verifique se essas APIs e permissões estão ativadas nos dois projetos onde esses recursos são usados.

Recurso	Papéis de permissão	Documentação
Acesso a linhas e recursos do BigQuery	Proprietário de dados do BigQuery	Para mais informações, consulte Papéis necessários para os papéis de recurso e Permissões necessárias para os papéis de linha.
Acesso à coluna do BigQuery	Administrador de tag de política	Para mais informações, consulte Papéis usados com o controle de acesso no nível da coluna e Restrição de acesso com o controle de acesso no nível da coluna.
Tags do catálogo	Proprietário do Data Catalog TagTemplate	Para mais informações, consulte Como marcar uma tabela do BigQuery usando o Data Catalog e a documentação do Data Catalog IAM.
Lakes do Dataplex	Editor do Dataplex	Para mais informações, consulte a documentação Criar um lago.

Observação: a Cortex Data Mesh não exige a integração das APIs Dataproc e Dataproc Metastore.

Entender as especificações de recursos básicas

A interface principal para configurar a malha de dados para Cortex é feita pelas especificações de recursos básicos, que são um conjunto de arquivos YAML fornecidos prontos para uso que definem os recursos de metadados e as anotações que são implantadas. As especificações básicas fornecem recomendações iniciais e exemplos de sintaxe, mas podem ser personalizadas para atender às necessidades do usuário. Essas especificações se enquadram em duas categorias:

• Recursos de metadados que podem ser aplicados em vários recursos de dados. Por exemplo, modelos de tags do Data Catalog que definem como os recursos podem ser marcados com domínios de negócios.
• Anotações que especificam como os recursos de metadados são aplicados a um recurso de dados específico. Por exemplo, uma tag de catálogo que associa uma tabela específica ao domínio de vendas.

As seções a seguir orientam você com exemplos básicos de cada tipo de especificação e explicam como personalizá-los. As especificações básicas são marcadas com ## CORTEX-CUSTOMER, onde precisam ser modificadas para se ajustar a uma implantação se a opção de implantação associada estiver ativada. Para usos avançados, consulte a definição canônica desses esquemas de especificação em src/common/data_mesh/src/data_mesh_types.py.

Recursos de metadados

Os recursos de metadados são entidades compartilhadas que existem em um projeto e podem ser aplicadas a muitos recursos de dados. A maioria das especificações inclui um campo display_name sujeito aos seguintes critérios:

• Contém apenas letras Unicode, números (0 a 9), sublinhados (_), hifens (-) e espaços ( ).
• Não pode começar ou terminar com espaços.
• O tamanho máximo é de 200 caracteres.

Em alguns casos, o display_name também é usado como um ID, o que pode introduzir requisitos adicionais. Nesses casos, são incluídos links para a documentação canônica.

Se a implantação referenciar recursos de metadados em diferentes projetos de origem e de destino, será necessário definir uma especificação para cada projeto. Por exemplo, o Cortex Salesforce (SFDC) contém duas especificações do Lake. Uma para as zonas brutas e CDC e outra para relatórios.

Lakes do Dataplex

Os lakes, zonas e recursos do Dataplex são usados para organizar os dados de uma perspectiva de engenharia. Os lakes têm um region e as zonas têm um location_type. Ambos estão relacionados ao local do Cortex (config.json > location). O local do Cortex define onde os conjuntos de dados do BigQuery são armazenados e pode ser uma única região ou multirregião. A zona location_type precisa ser definida como SINGLE_REGION | MULTI_REGION para corresponder a ela. No entanto, as regiões do Lake precisam ser sempre uma única região. Se o local do Cortex e a zona location_type forem multirregionais, selecione uma única região nesse grupo para a região do Lake.

• Requisitos
  • O display_name do lago é usado como lake_id e precisa obedecer aos requisitos oficiais. O mesmo acontece com a zona e o recurso display_name. Os IDs de zona precisam ser exclusivos em todos os Lakes do projeto.
  • As especificações do lake precisam estar associadas a uma única região.
  • O asset_name precisa corresponder ao ID do conjunto de dados do BigQuery, mas o display_name pode ser um rótulo mais fácil de usar.
• Limitações
  • O Dataplex só oferece suporte ao registro de conjuntos de dados do BigQuery, e não de tabelas individuais, como recursos do Dataplex.
  • Um recurso só pode ser registrado em uma única zona.
  • O Dataplex só está disponível em determinados locais. Para mais informações, consulte Locais do Dataplex.

Confira o exemplo a seguir em lakes.yaml.

Esses recursos são definidos em arquivos YAML que especificam data_mesh_types.Lakes.

Modelos de tag do catálogo

Os modelos de tag do Data Catalog podem ser usados para adicionar contexto a tabelas ou colunas individuais do BigQuery. Eles ajudam a categorizar e entender seus dados de uma perspectiva técnica e comercial de maneira integrada às ferramentas de pesquisa do Dataplex. Eles definem os campos específicos que podem ser usados para rotular os dados e o tipo de informações que cada campo pode conter (por exemplo, texto, número, data). As tags do catálogo são instâncias dos modelos com valores de campo reais.

O campo de modelo display_name é usado como o ID do campo e precisa seguir os requisitos de TagTemplate.fields especificados em Class TagTemplate. Para mais informações sobre os tipos de campo aceitos, consulte Tipos de campo do Data Catalog.

A Cortex Data Mesh cria todos os modelos de tag como legíveis publicamente. Ele também apresenta um conceito level adicional para especificações de modelos de tags, que define se uma tag precisa ser aplicada a um recurso inteiro, campos individuais em um recurso ou ambos, com os valores possíveis: ASSET | FIELD | ANY. Embora isso não seja aplicado estritamente agora, verificações de validação futuras podem garantir que as tags sejam aplicadas no nível adequado durante a implantação.

Confira o exemplo abaixo.

Os modelos são definidos em arquivos YAML que especificam data_mesh_types.CatalogTagTemplates.

As tags de catálogo são instâncias dos modelos e são discutidas abaixo nas anotações de recursos.

Controle de acesso no nível de recurso e coluna com modelos de tag

O Cortex Framework permite ativar o controle de acesso aos recursos ou colunas em todos os artefatos associados a um modelo de tag de catálogo. Por exemplo, se os usuários quiserem conceder acesso a recursos com base na linha de negócios, eles podem criar asset_policies para o modelo de tag de catálogo line_of_business com diferentes princípios especificados para cada domínio de negócios. Cada política aceita filters, que pode ser usado para corresponder apenas tags com valores específicos. Nesse caso, podemos corresponder aos valores de domain. Esses filters só oferecem suporte à correspondência de igualdade e a nenhum outro operador. Se vários filtros estiverem listados, os resultados precisarão atender a todos os filtros (por exemplo, filter_a AND filter_b). O conjunto final de políticas de recursos é a união das definidas diretamente nas anotações e das políticas de modelo.

O controle de acesso no nível da coluna com tags de catálogo se comporta de maneira semelhante ao aplicar tags de políticas em campos correspondentes. No entanto, como apenas uma tag de política pode ser aplicada a uma coluna, a precedência é:

1. Tag de política direta:se uma tag de política for definida diretamente na anotação da coluna, ela terá prioridade.
2. Política de correspondência de modelo de tag: caso contrário, o acesso é determinado pela primeira política de correspondência definida em um campo no modelo de tag de catálogo associado.

Ao usar esse recurso, recomendamos ativar ou desativar a implantação de tags de catálogo e listas de controle de acesso (ACLs) juntos. Isso garante que as ACLs sejam implantadas corretamente.

Para entender as especificações desse recurso avançado, consulte as definições dos parâmetros asset_policies e field_policies em data_mesh_types.CatalogTagTemplate.

Glossário do catálogo

O glossário é uma ferramenta que pode ser usada para fornecer um dicionário de termos usados por colunas específicas em recursos de dados que podem não ser universalmente compreendidos. Os usuários podem adicionar termos manualmente no console, mas não há suporte nas especificações de recursos.

Taxonomias e tags de política

As taxonomias e tags de políticas permitem o controle de acesso no nível da coluna a recursos de dados sensíveis de maneira padronizada. Por exemplo, pode haver uma taxonomia para tags que controlam dados de PII em uma linha de negócios específica, em que apenas determinados grupos podem ler dados mascarados, dados não mascarados ou não têm acesso de leitura.

Para mais detalhes sobre as classificações e tags de políticas, consulte a documentação Introdução à máscara de dados de colunas. As seções a seguir são particularmente relevantes:

• As funções interagem
• Herança de autorização
• Regras de mascaramento e hierarquia
• Práticas recomendadas para tags de política

O Cortex Framework fornece tags de política de exemplo para demonstrar como elas são especificadas e possíveis usos. No entanto, os recursos que afetam o controle de acesso não são ativados na implantação da malha de dados por padrão.

Confira o exemplo a seguir.

As taxonomias de políticas são definidas em arquivos YAML que especificam data_mesh_types.PolicyTaxonomies.

Anotações de recursos

As anotações especificam metadados aplicáveis a um recurso específico e podem fazer referência aos recursos de metadados compartilhados que foram definidos. As anotações incluem:

• Descrições de recursos
• Descrições de campo
• Tags do catálogo
• Controle de acesso no nível do recurso, da linha e da coluna

Observação: se você modificar um arquivo de anotação, considere que o console renderiza apenas novas linhas nas descrições como um espaço em branco.

A base de dados do Cortex Framework oferece anotações predefinidas (descrições) para as seguintes cargas de trabalho.

• SAP ECC (bruto, CDC e relatórios)
• SAP S/4HANA (bruto, CDC e relatórios)
• SFDC (somente relatórios)
• Oracle EBS (somente relatórios)
• CM360 (somente relatórios)
• Google Ads (somente relatórios)
• Meta (somente relatórios)
• SFMC (somente relatórios)
• TikTok (somente relatórios)
• YouTube (com o DV360) (somente relatórios)
• Google Analytics 4 (somente relatórios)

Confira o exemplo a seguir.

As anotações são definidas em arquivos YAML que especificam data_mesh_types.BqAssetAnnotation.

Tags do catálogo

As tags de catálogo são instâncias dos modelos definidos, em que os valores de campo são atribuídos e se aplicam ao recurso específico. Atribua valores que correspondam aos tipos de campo declarados no modelo associado.

Os valores de TIMESTAMP precisam estar em um dos seguintes formatos:

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

Confira o exemplo a seguir.

Consulte a definição de especificação em data_mesh_types.CatalogTag.

Como especificar leitores e principais de políticas de acesso

Controle o acesso aos seus dados do BigQuery no Cortex Framework usando políticas de acesso. Essas políticas definem quem (principais) pode acessar recursos de dados específicos, linhas em um recurso ou até mesmo colunas individuais. Os participantes precisam seguir um formato específico definido pelo membro da vinculação de políticas do IAM.

Acesso no nível do recurso

É possível conceder acesso a recursos inteiros do BigQuery com várias permissões:

• READER: visualizar dados no recurso.
• WRITER: modifique e adicione dados ao recurso.
• OWNER : controle total sobre o recurso, incluindo o gerenciamento de acesso.

Essas permissões são equivalentes à instrução GRANT DCL no SQL.

Ao contrário do comportamento da maioria dos recursos e anotações, a flag de substituição não remove os principais existentes com o papel OWNERS. Ao adicionar novos proprietários com a substituição ativada, eles são anexados aos proprietários existentes. Essa é uma medida de segurança para evitar a perda acidental de acesso. Para remover proprietários de recursos, use o console. A substituição remove os participantes existentes com o papel READER ou WRITER.

Confira o exemplo a seguir.

Consulte a definição de especificação em data_mesh_types.BqAssetPolicy.

Acesso no nível da linha

É possível conceder acesso a conjuntos de linhas com base em determinados filtros de valor de coluna. Ao especificar a política de acesso de linha, a string de filtro fornecida será inserida em um CREATE DDL statement. Se a flag overwrite estiver ativada, todas as políticas de acesso de linha atuais serão descartadas antes da aplicação de novas.

Considere o seguinte sobre o acesso de nível de linha:

• Adicionar políticas de acesso de linha significa que os usuários que não forem especificados nessas políticas não terão acesso às linhas.
• As políticas de linha só funcionam com tabelas, não visualizações.
• Evite usar colunas particionadas nos filtros da política de acesso de linha. Consulte o arquivo YAML das configurações de relatórios associado para informações sobre o tipo de recurso e as colunas particionadas.

Para mais informações sobre políticas de acesso no nível da linha, consulte Práticas recomendadas de segurança no nível da linha.

Confira o exemplo abaixo.

Consulte a definição de especificação em data_mesh_types.BqRowPolicy.

Acesso no nível da coluna

Para ativar o acesso no nível da coluna, anote campos individuais com uma tag de política identificada pelo nome da tag de política e da taxonomia. Atualize o recurso de metadados da tag de política para configurar o controle de acesso.

Confira o exemplo abaixo.

Consulte a definição de especificação em data_mesh_types.PolicyTagId.

Como implantar a malha de dados

A malha de dados pode ser implantada como parte da implantação da base de dados ou separadamente. Em ambos os casos, ele usa o arquivo config.json do Cortex para determinar variáveis relevantes, como nomes de conjuntos de dados do BigQuery e opções de implantação. Por padrão, a implantação da malha de dados não remove nem substitui recursos ou anotações existentes para evitar perdas não intencionais. No entanto, também é possível substituir recursos existentes quando implantados por conta própria.

Opções de implantação

As opções de implantação a seguir podem ser ativadas ou desativadas com base nas necessidades e nas restrições de gastos do usuário em config.json > DataMesh.

Observação: recomendamos que o controle de acesso seja feito apenas por essas especificações de recursos se o deployACLs estiver ativado. Isso evita a adição ou remoção não intencional de acesso.

Opção	Observações
deployDescriptions	Essa é a única opção ativada por padrão e implanta anotações do BigQuery com descrições de recursos e colunas. Não é necessário ativar outras APIs ou permissões.
deployLakes	Implanta lakes e zonas.
deployCatalog	Implanta recursos de modelo de catálogo e as tags associadas nas anotações de recursos.
deployACLs	Implanta recursos da taxonomia de políticas e políticas de controle de acesso no nível do recurso, da linha e da coluna usando anotações de recursos. Os registros contêm mensagens indicando como as políticas de acesso foram alteradas.

Implantação com a base de dados

Por padrão, config.json > deployDataMesh permite a implantação das descrições de recursos do Data Mesh no final de cada etapa de build de carga de trabalho. Essa configuração padrão não exige a ativação de APIs ou funções adicionais. Outros recursos da malha de dados podem ser implantados com a base de dados ativando as opções de implantação, as APIs e funções necessárias e modificando as especificações de recursos associadas.

Implantação individual

Para implantar a malha de dados sozinha, os usuários podem usar o arquivo common/data_mesh/deploy_data_mesh.py. Esse utilitário é usado durante os processos de build para implantar a malha de dados uma carga de trabalho por vez, mas, quando chamado diretamente, também pode ser usado para implantar várias cargas de trabalho de uma só vez. As cargas de trabalho para as especificações a serem implantadas precisam ser ativadas no arquivo config.json. Por exemplo, verifique se deploySAP=true se você estiver implantando a malha de dados para SAP.

Para garantir que você está implantando com os pacotes e versões necessários, execute o utilitário usando a mesma imagem usada pelo processo de implantação do Cortex com os seguintes 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 receber ajuda com os parâmetros disponíveis e o uso deles, execute o seguinte comando:

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

Confira a seguir um exemplo de invocação para o 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

Consulte a seção Diretórios da Data Mesh para informações sobre locais de diretórios.

Substituir

Aviso: leia esta seção com atenção antes de usar a opção de substituição.

Por padrão, a implantação da malha de dados não substitui recursos ou anotações existentes. No entanto, a flag --overwrite pode ser ativada ao implantar a Data Mesh sozinha para mudar a implantação das seguintes maneiras.

A substituição de recursos de metadados, como lagos, modelos de tags de catálogo e tags de política, exclui todos os recursos que compartilham os mesmos nomes, mas não modifica os recursos com nomes diferentes. Isso significa que, se uma especificação de recurso for removida inteiramente do arquivo YAML e a malha de dados for reimplantada com a substituição ativada, essa especificação de recurso não será excluída porque não haverá colisão de nome. Isso evita que a implantação do Cortex Data Mesh afete os recursos em uso.

Para recursos aninhados, como lagos e zonas, a substituição de um recurso remove todos os filhos dele. Por exemplo, a substituição de um lake também remove as zonas e referências de recursos existentes. Para modelos de tag do catálogo e tags de política que são substituídos, as referências de anotação associadas também são removidas dos recursos. A substituição de tags de catálogo em uma anotação de recurso substitui apenas as instâncias atuais de tags de catálogo que compartilham o mesmo modelo.

As substituições de descrição de recurso e de campo só entram em vigor se houver uma nova descrição válida e não vazia que entre em conflito com a descrição atual.

Por outro lado, as ACLs se comportam de maneira diferente. A substituição de ACLs remove todos os participantes existentes (com exceção dos proprietários no nível do recurso). Isso ocorre porque os participantes omitidos das políticas de acesso são igualmente importantes para os participantes que recebem acesso.

Como conhecer a malha de dados

Depois de implantar a malha de dados, os usuários podem pesquisar e acessar os recursos de dados com o Data Catalog. Isso inclui a capacidade de descobrir recursos com base nos valores da tag do catálogo que foram aplicados. Os usuários também podem criar e aplicar manualmente os termos do glossário do catálogo, se necessário.

As políticas de acesso implantadas podem ser visualizadas na página do esquema do BigQuery para conferir as políticas aplicadas a um recurso específico em cada nível.

Linhagem de dados

Talvez seja útil para os usuários ativar e visualizar a linhagem entre os recursos do BigQuery. A linhagem também pode ser acessada de maneira programática pela API. A linhagem de dados só é compatível com a linhagem no nível do recurso. A linhagem de dados não está relacionada à malha de dados do Cortex, mas novos recursos que usam a linhagem podem ser introduzidos no futuro.

Para qualquer solicitação do Cortex Data Mesh ou do Cortex Framework, acesse a seção suporte.