Memecahkan masalah akses data lintas cloud

Saat mengakses data lintas cloud dengan Lakehouse, Anda dapat mendiagnosis dan menyelesaikan masalah terkait pemuatan ulang metadata latar belakang, pemilihan rute melalui Cross-Cloud Interconnect, dan resolusi endpoint Direktori Layanan. Menyelesaikan masalah ini akan membantu menjaga metadata tabel gabungan tetap aktual dan memulihkan eksekusi kueri lintas cloud pribadi.

Data dan resource sudah usang atau tidak diperbarui

Katalog gabungan lakehouse menyinkronkan metadata dari cloud jarak jauh berdasarkan interval refresh. Pemuatan ulang metadata latar belakang katalog gabungan dapat memerlukan waktu lebih lama jika katalog gabungan berisi banyak resource (pembagian, skema, namespace, dan tabel). Jika pemuatan ulang sebelumnya melebihi batas, pemuatan ulang saat ini akan dilewati dan pemuatan ulang berikutnya akan berjalan pada interval terjadwal berikutnya.

Jika data yang dikueri tampak usang, pemuatan ulang metadata latar belakang katalog gabungan mungkin mengalami kelebihan beban atau gagal. Jika Anda menghapus resource di cloud jarak jauh, resource tersebut akan dihapus dari Lakehouse pada pembaruan metadata latar belakang berikutnya yang selesai.

Periksa status pemuatan ulang metadata latar belakang pada katalog gabungan di halaman Lakehouse di konsol Google Cloud , atau menggunakan Google Cloud CLI:

Buka Lakehouse

gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID"

gcloud biglake delta-sharing catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID"

Pemecahan masalah AWS Glue Data Catalog

Jika pemuatan ulang metadata latar belakang gagal setelah Anda mengonfigurasi --metadata-service-directory-name di katalog gabungan AWS Glue di katalog runtime Lakehouse, periksa hal berikut:

  • Verifikasi pemetaan endpoint katalog pribadi: pastikan bahwa grup endpoint jaringan (NEG) konektivitas hybrid atau endpoint Direktori Layanan untuk refresh metadata latar belakang mengarah ke alamat IP pribadi Endpoint VPC Antarmuka AWS Glue (com.amazonaws.AWS_REGION.glue) di port TCP 443, bukan Endpoint VPC Antarmuka Amazon S3 Anda.
  • Verifikasi kebijakan kepercayaan dan izin peran IAM: pastikan bahwa kebijakan kepercayaan peran IAM Amazon Web Services (AWS) Anda mengizinkanGoogle Cloud akun layanan (biglake-service-account) katalog gabungan untuk mengasumsikan peran (sts:AssumeRoleWithWebIdentity), dan bahwa peran tersebut memiliki izin untuk membaca database AWS Glue dan metadata tabel Anda (glue:GetDatabase, glue:GetDatabases, glue:GetTable, glue:GetTables).
  • Periksa aturan grup keamanan endpoint VPC: pastikan bahwa Grup Keamanan AWS yang terpasang ke Endpoint VPC Antarmuka AWS Glue Anda mengizinkan traffic HTTPS masuk di port TCP 443 dari Google Cloud rentang CIDR subnet Virtual Private Cloud (VPC) dan subnet khusus proxy Anda.

Pemecahan masalah Databricks Unity Catalog

Tabel kosong atau tidak ditemukan selama pemuatan ulang metadata latar belakang

Jika pemuatan ulang metadata latar belakang katalog gabungan menunjukkan penyelesaian (seperti Refresh successfully completed), tetapi tabel dalam katalog gabungan tidak muncul atau tabel listingan menampilkan item 0, periksa hal berikut:

  • Hak istimewa EXTERNAL USE SCHEMA: pastikan bahwa Akun Layanan Databricks telah diberi hak istimewa EXTERNAL USE SCHEMA pada skema atau katalog target di Databricks Unity Catalog. Tanpa hak istimewa ini, refresh metadata latar belakang dan penyediaan kredensial untuk kueri akan gagal.
  • Setelan akses data eksternal: verifikasi bahwa External data access diaktifkan di metastore Databricks Unity Catalog.
  • Lokasi eksternal: pastikan Databricks Unity Catalog dan tabel Anda menggunakan lokasi penyimpanan eksternal (seperti Amazon S3, Microsoft Azure Data Lake Storage Gen2, atau Cloud Storage), bukan penyimpanan default.

Pemuatan ulang metadata latar belakang gagal melalui Cross-Cloud Interconnect

Jika refresh metadata latar belakang gagal saat --metadata-service-directory-name dikonfigurasi untuk Databricks Unity Catalog di katalog runtime Lakehouse, verifikasi hal berikut:

  • Target endpoint pribadi Workspace: pastikan endpoint Direktori Layanan metadata atau backend Load Balancer Jaringan proxy internal regional Anda menargetkan alamat IP pribadi endpoint antarmuka AWS PrivateLink atau Azure Private Endpoint di port TCP 443, bukan endpoint penyimpanan jarak jauh Anda, dan --unity-instance-name cocok dengan nama host ruang kerja Anda.
  • Setelan akses pribadi Workspace: jika ruang kerja Databricks Anda menerapkan setelan akses pribadi atau daftar akses IP, pastikan permintaan yang masuk melalui endpoint pribadi dari jaringan VPC Google Cloud Anda diizinkan.

Pemuatan ulang metadata latar belakang gagal atau menampilkan 401 Unauthorized

Jika status pembaruan metadata latar belakang melaporkan error (seperti 401 Unauthorized) atau tidak dapat menemukan skema, verifikasi hal berikut:

  • Kebijakan penggabungan Service Principal: di Databricks Account Console (Account settings > Security > Identity provider setup > Federation policies), pastikan kebijakan penggabungan Service Principal dikonfigurasi sebagai berikut:
    • URL Penerbit: https://accounts.google.com
      • Subject: ID Unik numerik akun layanan biglake-service-account katalog gabungan (bukan alamat emailnya).
    • Audiens: https://accounts.cloud.databricks.com
  • Izin Secret Manager: jika menggunakan autentikasi berbasis secret, pastikan secret ada di lokasi regional yang ditentukan dan biglake-service-account memiliki peran Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) yang diberikan.
  • Izin Service Principal: pastikan Service Principal Databricks memiliki akses baca ke ruang kerja target dan Databricks Unity Catalog.

Kueri interaktif gagal dengan error 401 Unauthorized atau error validasi token

Jika penggabungan identitas pengguna diaktifkan, kueri interaktif akan membuat token identitas pengguna akhir secara dinamis dan memvalidasinya berdasarkan kebijakan penggabungan di seluruh Akun di Databricks. Jika kueri gagal dengan error validasi token atau 401 Unauthorized saat pemuatan ulang metadata latar belakang berjalan dengan baik, periksa hal berikut:

  • Kebijakan penggabungan di seluruh akun dikonfigurasi: pastikan Kebijakan penggabungan di seluruh akun (berbeda dengan kebijakan Service Principal) dibuat di Databricks Account Console di bagian Setelan akun > Keamanan > Penyiapan penyedia identitas > Kebijakan penggabungan.
  • Pencocokan audiens peka huruf besar/kecil: Databricks memvalidasi klaim aud (audiens) secara ketat dengan peka huruf besar/kecil. Pastikan kolom Audiences dalam kebijakan federasi Databricks Account-wide cocok dengan huruf besar/kecil yang sama persis dari klaim audience (databricks-METASTORE_ID) cakupan metastore yang diambil dari katalog gabungan Anda. Setiap perbedaan huruf besar atau kecil (misalnya, dalam awalan databricks- atau UUID metastore) akan menyebabkan validasi token Databricks menolak kueri dengan 401 Unauthorized.
  • URL Penerbit: verifikasi bahwa URL Penerbit sama persis dengan klaim issuer-url dari katalog gabungan: https://www.gstatic.com/biglake/federation/organizations/ORGANIZATION_ID.
  • Ketersediaan audiens metastore: klaim audience yang tercakup dalam metastore hanya diisi setelah siklus refresh metadata latar belakang pertama selesai (biasanya dalam waktu 5 menit). Jika Anda mengonfigurasi kebijakan dengan nilai placeholder atau sebelum siklus refresh pertama selesai, kueri akan gagal. Jalankan gcloud biglake iceberg catalogs describe untuk memverifikasi bahwa klaim audience pada katalog gabungan telah diisi sebelum mengonfigurasi kebijakan.

Pemecahan masalah Snowflake Horizon Catalog

Pemuatan ulang metadata latar belakang gagal dengan Kode 16 (Tidak Diautentikasi)

Jika pemuatan ulang metadata latar belakang untuk Snowflake Horizon Catalog gagal dengan status Code 16 (UNAUTHENTICATED), verifikasi hal berikut:

  • Pemformatan payload secret: pastikan token rahasia di Secret Manager berisi struktur JSON yang diperlukan ({"client_secret": "SNOWFLAKE_PAT_TOKEN", "scope": "session:role:SNOWFLAKE_ROLE"}), bukan string token akses terprogram (PAT) mentah.
  • Masa berlaku dan izin token: verifikasi bahwa PAT Snowflake valid dan bahwa pengguna serta peran terkait memiliki hak istimewa untuk membaca katalog dan database target.
  • ID akun PrivateLink atau Private Link: jika Anda mengonfigurasi --metadata-service-directory-name untuk menyinkronkan metadata melalui Cross-Cloud Interconnect menggunakan AWS PrivateLink atau Azure Private Link, pastikan --snowflake-account-identifier menentukan ID akun .privatelink Snowflake Anda (misalnya, myorg-myaccount.privatelink), bukan ID akun publik Anda.
  • Kebijakan jaringan: jika pemuatan ulang metadata latar belakang terhubung melalui internet publik dan kebijakan jaringan Snowflake aktif, pastikan rentang alamat IP egress Google dari goog.json disertakan dalam daftar IP yang diizinkan kebijakan jaringan Anda.

Pemuatan ulang metadata latar belakang gagal melalui Cross-Cloud Interconnect

Jika pemuatan ulang metadata latar belakang gagal saat --metadata-service-directory-name dikonfigurasi untuk Snowflake Horizon Catalog di katalog runtime Lakehouse, verifikasi hal berikut:

  • Target endpoint pribadi Snowflake: pastikan endpoint Direktori Layanan metadata atau backend Load Balancer Jaringan proxy internal regional Anda mengarah ke alamat IP pribadi endpoint antarmuka PrivateLink AWS Snowflake atau Endpoint Pribadi Azure di port TCP 443, bukan endpoint penyimpanan objek jarak jauh Anda.
  • ID akun pribadi: konfirmasi bahwa --snowflake-account-identifier menggunakan ID akun .privatelink Anda (misalnya, myorg-myaccount.privatelink).

Masalah konektivitas atau pemilihan rute

Jika Anda mengalami kegagalan pemuatan ulang metadata latar belakang atau pengiriman kueri saat merutekan traffic melalui Cross-Cloud Interconnect, verifikasi hal berikut:

  • Verifikasi penyebaran rute: periksa Cloud Router di Google Cloud untuk memverifikasi bahwa Cloud Router telah mempelajari awalan AWS VPC atau Azure Virtual Network (VNet) Anda. Periksa tabel rute AWS atau Azure Anda untuk memastikan bahwa tabel tersebut memiliki rute kembali ke jaringan VPC Google CloudAnda. Jika Anda menggunakan Load Balancer Jaringan proxy internal regional, pastikan Cloud Router memberitahukan rentang CIDR subnet khusus proxy Anda melalui pemberitahuan rute BGP kustom.
  • Periksa kondisi load balancer internal: di konsol Google Cloud , buka Network Services > Load balancing, dan pastikan backend grup endpoint jaringan (NEG) konektivitas hybrid untuk layanan backend transport dan metadata Anda responsif. Jika backend tidak responsif, periksa konektivitas Cross-Cloud Interconnect dan aturan keamanan jarak jauh.
  • Uji konektivitas dari Google Cloud: buat instance VM pengujian di jaringan dan subnet VPC Google Cloud yang sama dengan load balancer internal atau endpoint Direktori Layanan, dan uji konektivitas ke alamat IP AWS Elastic Network Interface (ENI) atau antarmuka jaringan (NIC) Endpoint Pribadi Azure di port TCP 443 (misalnya, menggunakan curl atau nc).
  • Verifikasi konfigurasi dan izin Direktori Layanan: pastikan layanan Direktori Layanan yang dikonfigurasi di --service-directory-name (untuk transportasi kueri) dan --metadata-service-directory-name (untuk refresh metadata latar belakang) berada di region Google Cloud yang sama dengan katalog gabungan Anda. Jika pemuatan ulang metadata latar belakang untuk katalog gabungan gagal dengan error Permission 'servicedirectory.services.resolve' denied, pastikan ID akun layanan unik katalog gabungan (kolom biglake-service-account) memiliki peran roles/servicedirectory.viewer dan roles/servicedirectory.pscAuthorizedService di setiap project yang menghosting layanan Direktori Layanan.
  • Periksa grup keamanan dan aturan firewall: pastikan aturan firewallGoogle Cloud , AWS Security Groups, dan Azure Network Security Groups (NSG) mengizinkan traffic TCP di port 443 antara rentang CIDR VPC Google Cloud Anda (termasuk rentang CIDR subnet khusus proxy) dan endpoint pribadi jarak jauh Anda.