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:
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 TCP443, 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
443dari 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 istimewaEXTERNAL USE SCHEMApada 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-namecocok 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-accountkatalog gabungan (bukan alamat emailnya).
- Subject: ID Unik numerik akun layanan
- Audiens:
https://accounts.cloud.databricks.com
- URL Penerbit:
- Izin Secret Manager: jika menggunakan autentikasi berbasis secret, pastikan secret ada di lokasi regional yang ditentukan dan
biglake-service-accountmemiliki 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 klaimaudience(databricks-METASTORE_ID) cakupan metastore yang diambil dari katalog gabungan Anda. Setiap perbedaan huruf besar atau kecil (misalnya, dalam awalandatabricks-atau UUID metastore) akan menyebabkan validasi token Databricks menolak kueri dengan401 Unauthorized. - URL Penerbit: verifikasi bahwa URL Penerbit sama persis dengan klaim
issuer-urldari katalog gabungan:https://www.gstatic.com/biglake/federation/organizations/ORGANIZATION_ID. - Ketersediaan audiens metastore: klaim
audienceyang 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. Jalankangcloud biglake iceberg catalogs describeuntuk memverifikasi bahwa klaimaudiencepada 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-nameuntuk menyinkronkan metadata melalui Cross-Cloud Interconnect menggunakan AWS PrivateLink atau Azure Private Link, pastikan--snowflake-account-identifiermenentukan ID akun.privatelinkSnowflake 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.jsondisertakan 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-identifiermenggunakan ID akun.privatelinkAnda (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, menggunakancurlataunc). - 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 errorPermission 'servicedirectory.services.resolve' denied, pastikan ID akun layanan unik katalog gabungan (kolombiglake-service-account) memiliki peranroles/servicedirectory.viewerdanroles/servicedirectory.pscAuthorizedServicedi 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
443antara rentang CIDR VPC Google Cloud Anda (termasuk rentang CIDR subnet khusus proxy) dan endpoint pribadi jarak jauh Anda.