Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Knowledge Catalog 통합

이 문서에서는 Cortex Framework가 조직 전반의 엔터프라이즈 데이터 제품의 거버넌스 계층 역할을 하는 Knowledge Catalog와 통합되는 방법을 설명합니다. 또한 Google Cloud Cortex Framework Knowledge Catalog 동기화 도구가 Google Cloud Cortex Framework 데이터 제품을 Knowledge Catalog에 등록하고 동기화하여 검색 및 보안 공유를 간소화하는 방법을 설명합니다.

이 통합을 사용 설정하면 풍부한 비즈니스 설명, 소유권 메타데이터, 기본 물리적 BigQuery 데이터 세트 및 테이블을 비롯한 배포된 Cortex Framework 데이터 제품이 자동으로 카탈로그화되고 Knowledge Catalog에서 검색 가능하게 됩니다.

주요 이점

Cortex Framework를 Knowledge Catalog와 통합하면 다음과 같은 주요 이점을 얻을 수 있습니다.

자동화된 데이터 검색 가능성: 사용자는 Knowledge Catalog 사용자 인터페이스 내에서 직접 표준화된 엔터프라이즈 데이터 제품을 찾아보고 검색할 수 있으므로 수동 카탈로그 항목이 필요하지 않습니다.
풍부한 비즈니스 컨텍스트: manifest.yaml 파일에서 Knowledge Catalog로 표시 이름, 상세 비즈니스 설명, 문서 URL을 직접 자동으로 가져옵니다.
통합된 애셋 연결: 개별적으로 일치하는 보고 기본 테이블을 해당 Knowledge Catalog 데이터 제품에 직접 연결합니다. 이를 통해 데이터 소비자는 특정 비즈니스 도메인을 지원하는 물리적 데이터 객체를 즉시 확인할 수 있습니다.
자동화된 수명 주기 및 드리프트 조정: 엔터프라이즈 데이터 모델이 발전함에 따라 동기화 도구를 실행하면 메타데이터와 애셋 링크가 자동으로 조정됩니다. 새 테이블을 등록하고, 수정된 정의를 업데이트하고, 더 이상 사용되지 않는 링크를 삭제하는 동시에 비관리형 사용자 생성 카탈로그 항목을 보호합니다.
시스템 관리 안전: 전용 시스템 라벨 (cortex-framework-created 및 cortex-framework-version)을 사용하여 Cortex Framework에서 만든 리소스만 식별하고 관리하므로 기존 고객 관리 Knowledge Catalog 애셋이 실수로 덮어쓰이지 않습니다.

통합 작동 방식

Knowledge Catalog 통합은 cortex-kc-sync (tools.dataplex.kc_sync) 동기화 도구로 구동됩니다. 실행되면 동기화 도구가 다음과 같은 다단계 워크플로를 실행합니다.

1. 구성 및 manifest 추출

동기화 도구는 전역 config/config.yaml 구성 파일을 파싱하여 사용 설정된 모든 데이터 제품 모듈 (data.modules.products)과 대상 BigQuery 데이터 세트 (data.targets)를 식별합니다.

사용 설정된 각 모듈에 대해 동기화 도구는 작업공간 모듈 제공업체를 사용하여 모듈의 manifest.yaml에서 설명 메타데이터를 추출합니다.

displayName: 데이터 제품의 사람이 읽을 수 있는 제목입니다.
description: 모듈의 비즈니스 요약입니다.
documentation: 내부 또는 외부 모듈 문서를 가리키는 URL입니다.

2. BigQuery 애셋 검색

cortex-kc-sync는 테이블 정의의 정적 목록을 확인하는 대신 BigQuery (list_dataset_tables)를 쿼리하여 대상 데이터 세트에 이미 배포된 테이블과 뷰를 동적으로 검색합니다.

배포 중에 적용된 특정 추적 라벨을 찾아 테이블을 확인하고 필터링합니다.

정규화된 모듈 경로 (예: cortex.sap.products.sales_performance)와 일치하는 cortex-framework-namespaced-module-type 또는
표준 모듈 유형 이름 (예: sales_performance)과 일치하는 cortex-framework-module-type

BigQuery에서 이러한 라벨을 포함하는 구체화된 테이블과 뷰만 카탈로그화되고 데이터 제품의 애셋으로 연결됩니다.

3. 관리형 리소스 조정 및 라벨 지정

동기화 도구는 dataplex_v1 API (DataProductClient)와 통신하여 target Google Cloud location에서 검색된 각 데이터 제품을 조정합니다.

생성 (NEEDS_CREATION): 데이터 제품이 없으면 동기화 도구가 추출된 manifest 메타데이터로 채워진 새 Knowledge Catalog 데이터 제품을 만들고 확인된 BigQuery 애셋을 연결합니다. 리소스에 두 개의 시스템 라벨을 태그합니다.
- cortex-framework-created: "true"로 설정
- cortex-framework-version: "7-0-0"으로 설정
비관리형 리소스 보호 (NOT_MANAGED): 동일한 ID의 Knowledge Catalog 데이터 제품이 이미 카탈로그에 있지만 이러한 시스템 라벨 (is_managed_data_product == False)이 누락된 경우 동기화 도구는 사용자 생성 또는 기존 카탈로그 애셋을 보호하기 위해 건너뜁니다.
업데이트 (NEEDS_UPDATE): 관리형 데이터 제품이 있고 메타데이터 또는 테이블 구성에 변경사항이 있는 경우 동기화 도구는 Knowledge Catalog 데이터 제품 정의를 업데이트하고 연결된 BigQuery 애셋 (BigQueryAssetLinks)을 조정합니다. 새로 추가된 테이블에 대한 새 DataAsset 링크를 자동으로 만들고 더 이상 사용되지 않는 링크를 삭제하는 동시에 변경되지 않은 링크는 그대로 둡니다.

설정 및 구성

이 섹션에서는 Cortex Framework와 Knowledge Catalog 간의 동기화를 설정하고 실행하는 데 필요한 기본 요건, 메타데이터 구성, 실행 단계를 설명합니다.

기본 요건

Knowledge Catalog 동기화를 실행하기 전에 다음 요구사항을 충족했는지 확인하세요.

서비스 사용 설정 Google Cloud

이 섹션에서는 프로젝트에서 다음 Google Cloud 서비스를 사용 설정합니다 Google Cloud .

Cloud Dataplex API (dataplex.googleapis.com)

터미널에서 다음 명령어를 실행하여 Cloud Shell을 사용하여 이 Google Cloud 서비스를 사용 설정합니다.

gcloud config set project PROJECT_ID

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

대상 프로젝트의 역할

Knowledge Catalog를 동기화하는 데 필요한 권한을 얻으려면 관리자에게 대상 프로젝트에 대해 다음 IAM 역할을 부여해 달라고 요청하세요.

Dataplex 편집자 (roles/dataplex.editor)
Dataplex 데이터 제품 편집자 (roles/dataplex.dataProductsEditor)
Dataplex 항목 소유자 (roles/dataplex.entryOwner)
BigQuery 메타데이터 뷰어 (roles/bigquery.metadataViewer)
BigQuery 데이터 뷰어 (roles/bigquery.dataViewer)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 dataplex.dataProducts.create, dataplex.dataProducts.update, dataplex.dataAssets.create, dataplex.dataAssets.delete Knowledge Catalog를 동기화하는 데 필요한 권한이 포함되어 있습니다.

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

사용자에게 요청된 역할을 부여하려면 다음 스크립트를 사용하면 됩니다.

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"

실행된 Dataform 파이프라인

Knowledge Catalog와 동기화하기 전에 배포 가이드에 설명된 대로 먼저 cortex-build-and-deploy 또는 cortex-deploy를 실행하고 Dataform 파이프라인 작업을 실행하여 BigQuery 테이블과 뷰를 구체화해야 합니다. 변환 실행에 관한 단계별 안내는 배포 후 단계를 참조하세요.

참고: 애셋 한도: Dataplex는 데이터 제품당 최대 100개의 애셋 (테이블)을 지원합니다. 데이터 제품에 50개가 넘는 테이블이 포함되어 있으면 cortex-kc-sync가 오류와 함께 실패합니다.

데이터 제품 메타데이터 구성

각 데이터 제품 모듈 디렉터리 (예: src/data_modules/cortex/sap/products/accounts_payable/manifest.yaml) 내에 있는 manifest.yaml 파일을 수정하여 Knowledge Catalog에 표시되는 비즈니스 메타데이터를 맞춤설정할 수 있습니다.

다음 예에서는 모듈 manifest에서 displayName, description, documentation을 정의하는 방법을 보여줍니다.

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

동기화 명령어 실행

데이터 제품이 BigQuery에 배포되고 구체화된 후 uv를 사용하여 cortex-kc-sync CLI 도구를 실행합니다.

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

사용 가능한 플래그와 인수의 전체 목록은 CLI KC 동기화 (uv run cortex-kc-sync) 참조를 확인하세요.

Knowledge Catalog 동기화 확인

Google Cloud Cortex Framework 애셋과 Knowledge Catalog 간의 동기화가 성공했는지 확인하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Knowledge Catalog를 엽니다.
선택사항: 검색 대화상자에서 Data Products 또는 Tables와 같은 빠른 필터 중 하나를 사용할 수 있습니다.
Knowledge Catalog의 기본 화면의 검색 필드에서 Filters를 클릭합니다.
열린 Filters 뷰의 Project 드롭다운에서 Google Cloud Cortex Framework 데이터 제품을 동기화하는 데 사용하는 프로젝트를 선택합니다.
동기화가 완료되면 게시된 모든 메타데이터를 비롯하여 Google Cloud Cortex Framework에서 노출하는 데이터 애셋을 선택하거나 검색할 수 있습니다.

워크플로 자동화

프로덕션 환경에서는 Dataform 파이프라인 실행이 완료된 직후 CI/CD 오케스트레이션 파이프라인 또는 Knowledge Catalog (Airflow) DAG 내에서 후처리 단계로 cortex-kc-sync를 자동으로 실행하는 것이 좋습니다.

빌드 및 배포: cortex-deploy (uv run cortex-deploy --config config/config.yaml)를 실행하여 구성을 컴파일하고 Dataform에 스테이징합니다.
변환 실행: Dataform 실행을 트리거하여 BigQuery에서 데이터 기반 레이어와 일치하는 보고 테이블을 구체화합니다.
카탈로그 동기화: cortex-kc-sync (uv run cortex-kc-sync --config config/config.yaml)를 실행하여 테이블 생성을 확인하고 업데이트된 모든 데이터 제품, 설명, 계보 링크를 Knowledge Catalog에 직접 동기화합니다.

다음 단계

커스텀 데이터 제품 만들기: 새 데이터 제품을 만들거나 스키마를 확장하려면 확장성 가이드: 데이터 제품 모듈 만들기를 참조하세요.