クロスクラウド データアクセスのトラブルシューティング

Lakehouse でクロスクラウド データにアクセスすると、バックグラウンド メタデータの更新、Cross-Cloud Interconnect 経由のルーティング、Service Directory エンドポイントの解決に関する問題を診断して解決できます。これらの問題を解決すると、連携テーブルのメタデータが最新の状態に保たれ、プライベート クロスクラウド クエリの実行が復元されます。

データとリソースが古いか、更新されていない

Lakehouse 連携カタログは、更新間隔に基づいてリモート クラウドからメタデータを同期します。連携カタログに多数のリソース(共有、スキーマ、名前空間、テーブル)が含まれている場合、連携カタログのバックグラウンド メタデータの更新に時間がかかることがあります。以前の更新がオーバーランした場合、現在の更新はスキップされ、次の更新は次のスケジュールされた間隔で実行されます。

クエリされたデータが古くなっているように見える場合は、連携カタログのバックグラウンド メタデータの更新がオーバーランしているか、失敗している可能性があります。リモート クラウドでリソースを削除すると、次のバックグラウンド メタデータの更新が完了したときに Lakehouse から削除されます。

Google Cloud コンソールの [Lakehouse] ページで、または 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"

AWS Glue Data Catalog のトラブルシューティング

Lakehouse ランタイム カタログの AWS Glue 連携カタログで --metadata-service-directory-name を構成した後に、バックグラウンド メタデータの更新が失敗した場合は、次の点を確認してください。

  • プライベート カタログ エンドポイント マッピングを確認する: バックグラウンド メタデータ更新用のハイブリッド接続ネットワーク エンドポイント グループ(NEG)または Service Directory エンドポイントが、Amazon S3 インターフェース VPC エンドポイントではなく、TCP ポート 443 の AWS Glue インターフェース VPC エンドポイント(com.amazonaws.AWS_REGION.glue)のプライベート IP アドレスを指していることを確認します。
  • IAM ロールの信頼ポリシーと権限を確認する: Amazon Web Services(AWS)IAM ロールの信頼ポリシーで、連携カタログのGoogle Cloud サービス アカウント(biglake-service-account)がロール(sts:AssumeRoleWithWebIdentity)を引き受けることが許可されていること、およびロールに AWS Glue データベースとテーブルのメタデータを読み取る権限(glue:GetDatabase、glue:GetDatabases、glue:GetTable、glue:GetTables)があることを確認します。
  • VPC エンドポイントのセキュリティ グループ ルールを確認する: AWS Glue Interface VPC エンドポイントに接続されている AWS セキュリティ グループが、Google Cloud Virtual Private Cloud(VPC)サブネットとプロキシ専用サブネットの CIDR 範囲から TCP ポート 443 でインバウンド HTTPS トラフィックを許可していることを確認します。

Databricks Unity Catalog のトラブルシューティング

テーブルが空であるか、バックグラウンド メタデータの更新中に検出されない

連携カタログのバックグラウンド メタデータの更新が完了している(Refresh successfully completed など)にもかかわらず、連携カタログのテーブルが表示されない、またはテーブルの一覧表示で 0 個のアイテムが返される場合は、次の点を確認してください。

  • EXTERNAL USE SCHEMA 権限: Databricks Unity Catalog のターゲット スキーマまたはカタログで、Databricks サービス プリンシパルに EXTERNAL USE SCHEMA 権限が付与されていることを確認します。この権限がないと、バックグラウンド メタデータの更新とクエリの認証情報の提供が失敗します。
  • 外部データアクセスの設定: Databricks Unity Catalog metastore で外部データアクセスが有効になっていることを確認します。
  • 外部ロケーション: Databricks Unity Catalog とテーブルが、デフォルトのストレージではなく、外部ストレージ ロケーション(Amazon S3、Microsoft Azure Data Lake Storage Gen2、Cloud Storage など)を使用していることを確認します。

Cross-Cloud Interconnect でバックグラウンド メタデータの更新が失敗する

Lakehouse ランタイム カタログで Databricks Unity Catalog に --metadata-service-directory-name が構成されているときに、バックグラウンド メタデータの更新が失敗した場合は、次の点を確認します。

  • Workspace プライベート エンドポイント ターゲット: メタデータ Service Directory エンドポイントまたはリージョン内部プロキシ ネットワーク ロードバランサ バックエンドが、リモート ストレージ エンドポイントではなく、TCP ポート 443 の Databricks ワークスペース AWS PrivateLink インターフェース エンドポイントまたは Azure プライベート エンドポイントのプライベート IP アドレスをターゲットにしていること、および --unity-instance-name がワークスペースのホスト名と一致していることを確認します。
  • ワークスペースのプライベート アクセス設定: Databricks ワークスペースでプライベート アクセス設定または IP アクセスリストが適用されている場合は、 Google CloudVPC ネットワークからプライベート エンドポイントを介して到着するリクエストが許可されていることを確認します。

バックグラウンド メタデータの更新が失敗するか、401 Unauthorized が返される

バックグラウンド メタデータの更新ステータスでエラー(401 Unauthorized など)が報告された場合、またはスキーマを検出できない場合は、次の点を確認します。

  • サービス プリンシパル連携ポリシー: Databricks アカウント コンソール([アカウント設定] > [セキュリティ] > [ID プロバイダの設定] > [連携ポリシー])で、サービス プリンシパル連携ポリシーが次のように構成されていることを確認します。
    • 発行元 URL: https://accounts.google.com
      • サブジェクト: 連携カタログの biglake-service-account サービス アカウントの数値形式の一意の ID(メールアドレスではありません)。
    • 対象者: https://accounts.cloud.databricks.com
  • Secret Manager の権限: シークレットベースの認証を使用している場合は、指定されたリージョン ロケーションにシークレットが存在し、biglake-service-account に Secret Manager のシークレット アクセサー(roles/secretmanager.secretAccessor)ロールが付与されていることを確認します。
  • サービス プリンシパルの権限: Databricks サービス プリンシパルに、ターゲット ワークスペースと Databricks Unity Catalog への読み取りアクセス権があることを確認します。

インタラクティブ クエリが 401 Unauthorized またはトークン検証エラーで失敗する

ユーザー ID 連携が有効になっている場合、インタラクティブ クエリはエンドユーザー ID トークンを動的に作成し、Databricks のアカウント全体の連携ポリシーに照らして検証します。バックグラウンド メタデータの更新が正常なときに、クエリが 401 Unauthorized またはトークン検証エラーで失敗する場合は、次の点を確認します。

  • アカウント全体の連携ポリシーが構成されている: アカウント全体の連携ポリシー(サービス プリンシパル ポリシーとは異なる)が、Databricks アカウント コンソールの [アカウント設定] > [セキュリティ] > [ID プロバイダの設定] > [連携ポリシー] で作成されていることを確認します。
  • 大文字と小文字を区別するオーディエンスの一致: Databricks は、aud(オーディエンス)クレームを大文字と小文字を区別して厳密に検証します。Databricks のアカウント全体の連携ポリシーの [Audiences] フィールドが、連携カタログから取得したメタストア スコープの audience クレーム(databricks-METASTORE_ID)の大文字と小文字が完全に一致していることを確認します。大文字と小文字の不一致(databricks- 接頭辞や metastore UUID など)があると、Databricks トークン検証でクエリが 401 Unauthorized で拒否されます。
  • 発行元 URL: 発行元 URL が、連携カタログの issuer-url クレームと完全に一致していることを確認します。https://www.gstatic.com/biglake/federation/organizations/ORGANIZATION_ID
  • Metastore オーディエンスの可用性: metastore スコープの audience クレームは、最初のバックグラウンド メタデータ更新サイクルが完了した後にのみ入力されます(通常は 5 分以内)。プレースホルダの値を使用してポリシーを設定した場合、または最初の更新サイクルが完了する前にポリシーを設定した場合、クエリは失敗します。gcloud biglake iceberg catalogs describe を実行して、ポリシーを構成する前に、連携カタログの audience クレームが入力されていることを確認します。

Snowflake Horizon カタログのトラブルシューティング

バックグラウンド メタデータの更新がコード 16(未認証)で失敗する

Snowflake Horizon Catalog のバックグラウンド メタデータ更新がステータス Code 16(UNAUTHENTICATED)で失敗した場合は、次の点を確認します。

  • シークレット ペイロードの形式: Secret Manager のシークレット トークンに、未加工のプログラムによるアクセス トークン(PAT)文字列ではなく、必要な JSON 構造({"client_secret": "SNOWFLAKE_PAT_TOKEN", "scope": "session:role:SNOWFLAKE_ROLE"})が含まれていることを確認します。
  • トークンの有効期限と権限: Snowflake PAT が有効であり、関連付けられたユーザーとロールに、ターゲット カタログとデータベースを読み取る権限があることを確認します。
  • PrivateLink または Private Link アカウント ID: AWS PrivateLink または Azure Private Link を使用して Cross-Cloud Interconnect 経由でメタデータを同期するように --metadata-service-directory-name を構成した場合は、--snowflake-account-identifier に、公開アカウント ID ではなく、Snowflake .privatelink アカウント ID(myorg-myaccount.privatelink など)が指定されていることを確認します。
  • ネットワーク ポリシー: バックグラウンド メタデータの更新がパブリック インターネット経由で接続し、Snowflake ネットワーク ポリシーが有効になっている場合は、goog.json の Google の下り(外向き)IP アドレス範囲がネットワーク ポリシーの許可された IP リストに含まれていることを確認します。

Cross-Cloud Interconnect でバックグラウンド メタデータの更新が失敗する

Lakehouse ランタイム カタログで Snowflake Horizon カタログに --metadata-service-directory-name が構成されているときに、バックグラウンドでのメタデータの更新が失敗する場合は、次の点を確認します。

  • Snowflake プライベート エンドポイント ターゲット: メタデータ Service Directory エンドポイントまたはリージョン内部プロキシ ネットワーク ロードバランサ バックエンドが、リモート オブジェクト ストレージ エンドポイントではなく、TCP ポート 443 の Snowflake AWS PrivateLink インターフェース エンドポイントまたは Azure プライベート エンドポイントのプライベート IP アドレスを指していることを確認します。
  • プライベート アカウント ID: --snowflake-account-identifier が .privatelink アカウント ID(myorg-myaccount.privatelink など)を使用していることを確認します。

接続またはルーティングに関する問題

Cross-Cloud Interconnect 経由でトラフィックをルーティングするときに、クエリ転送またはバックグラウンド メタデータの更新に失敗した場合は、次の点を確認します。

  • ルートの伝播を確認する:Google Cloud の Cloud Router を確認して、AWS VPC または Azure 仮想ネットワーク(VNet)のプレフィックスが学習されていることを確認します。AWS または Azure のルートテーブルをチェックして、 Google CloudVPC ネットワークへのルートがあることを確認します。リージョン内部プロキシ ネットワーク ロードバランサを使用する場合は、Cloud Router がカスタム BGP ルート アドバタイズを介してプロキシ専用サブネットの CIDR の範囲をアドバタイズすることを確認します。
  • 内部ロードバランサの健全性を確認する: Google Cloud コンソールで、[ネットワーク サービス] > [ロード バランシング] に移動し、トランスポート バックエンド サービスとメタデータ バックエンド サービスのハイブリッド接続ネットワーク エンドポイント グループ(NEG)バックエンドが正常であることを確認します。バックエンドが正常でない場合は、Cross-Cloud Interconnect の接続性とリモート セキュリティ ルールを確認します。
  • Google Cloudからの接続をテストする: 内部ロードバランサまたは Service Directory エンドポイントと同じ Google Cloud VPC ネットワークとサブネットにテスト VM インスタンスを作成し、TCP ポート 443 で AWS Elastic Network Interface(ENI)または Azure Private Endpoint ネットワーク インターフェース(NIC)の IP アドレスへの接続をテストします(curl や nc などを使用)。
  • Service Directory の構成と権限を確認する: --service-directory-name(クエリ転送用)と --metadata-service-directory-name(バックグラウンド メタデータ更新用)で構成された Service Directory サービスが、連携カタログと同じ Google Cloud リージョンにあることを確認します。連携カタログのバックグラウンド メタデータ更新が Permission 'servicedirectory.services.resolve' denied エラーで失敗した場合は、連携カタログの一意のサービス アカウント ID(biglake-service-account フィールド)に、Service Directory サービスをホストする各プロジェクトの roles/servicedirectory.viewer ロールと roles/servicedirectory.pscAuthorizedService ロールがあることを確認します。
  • セキュリティ グループとファイアウォール ルールを確認する:Google Cloud ファイアウォール ルール、AWS セキュリティ グループ、Azure ネットワーク セキュリティ グループ(NSG)で、 Google Cloud VPC CIDR の範囲(プロキシ専用サブネットの CIDR の範囲を含む)とリモート プライベート エンドポイント間のポート 443 で TCP トラフィックが許可されていることを確認します。