Configura la conexión entre nubes para Databricks Unity Catalog

Una conexión multinube a un catálogo de Databricks Unity Catalog te permite consultar datos de ese catálogo directamente en Google Cloud. Esta función unifica tu análisis de datos integrando tus fuentes de datos externas con tu entorno deGoogle Cloud existente.

Después de configurar la conexión, puedes administrar el acceso a tus datos federados en Lakehouse sin límites.

Antes de comenzar

  1. Revisa la descripción general de Lakehouse para comprender cómo Lakehouse administra el acceso a los datos.
  2. Lee Acerca del acceso a los datos multinube para comprender cómo funciona.
  3. Revisa los catálogos compatibles para verificar las configuraciones compatibles.
  4. Comprender cómo usar los secrets regionales de Secret Manager Esto es necesario para configurar un Lakehouse con Databricks Unity Catalog con autenticación basada en secretos.
  5. Opcional: Si planeas enrutar consultas a través de una interconexión privada entre tu VPC de Google Cloud y la VPC de tu proveedor de servicios en la nube remoto (por ejemplo, AWS), asegúrate de tener una cuenta activa con tu proveedor remoto, aprovisiona una Cross-Cloud Interconnect dedicada o una Cross-Cloud Interconnect para socios, establece sesiones de BGP con tu Cloud Router y verifica que tengas los permisos de IAM necesarios en ambos entornos de nube.
  6. Opcional: Si planeas usar la federación de identidades de usuario para propagar las identidades de los usuarios finales en las consultas, asegúrate de lo siguiente:
  7. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the BigLake, Secret Manager APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  10. Verify that billing is enabled for your Google Cloud project.

  11. Enable the BigLake, Secret Manager APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    12.

Roles obligatorios

Para obtener los permisos que necesitas para configurar el acceso multinube, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Limitaciones y consideraciones

En esta sección, se enumeran las limitaciones y consideraciones para acceder a los datos multinube.

  • Proveedores de servicios en la nube compatibles con Cross‑Cloud Interconnect: El uso de una interconexión privada para acceder a datos multinube es compatible con los siguientes proveedores de servicios en la nube remotos: Amazon Web Services (AWS). Puedes usar una Cross-Cloud Interconnect dedicada o una Cross-Cloud Interconnect para socios.
  • Enrutamiento de red: Si no se configura una interconexión privada (como CCI dedicada o CCI de socio), las consultas se enrutan a través de la Internet pública. Esto puede generar tarifas de salida más altas de tu proveedor de servicios en la nube remoto y un rendimiento menos predecible.
  • Configuración de Databricks Unity Catalog:
  • Solo lectura: Los catálogos federados en Lakehouse son vistas de solo lectura del catálogo remoto. No se admite la manipulación de recursos (como crear, actualizar o borrar recursos) y se debe realizar directamente en el catálogo remoto.
  • Actualidad de los datos: La marca --refresh-interval para un catálogo federado determina la frecuencia con la que se sincronizan los metadatos. El valor debe ser 0s (inhabilitado) o, al menos, 300s (5 minutos). La actualización de metadatos en segundo plano de un catálogo puede tardar más tiempo según la cantidad de recursos de espacio de nombres y tablas que haya. Si la actualización anterior se excede, se omitirá la actualización actual, pero la siguiente se programará para el intervalo posterior. Las consultas usan los metadatos del catálogo sincronizados más recientemente, por lo que los cambios realizados en el catálogo remoto, como tablas nuevas, actualizaciones de esquemas o datos confirmados recientemente, no son visibles en Lakehouse hasta que se complete la siguiente actualización de metadatos en segundo plano.
  • Almacenamiento en caché de Lakehouse: El almacenamiento en caché de Lakehouse se habilita automáticamente para todas las consultas multinube para ahorrar costos de salida almacenando bloques de datos de forma local en Google Cloud. Las claves de encriptación administradas por el cliente (CMEK) no se admiten para el almacenamiento en caché; los datos almacenados en caché se encriptan con Google-owned and Google-managed encryption keys. Si se aplica la restricción de la política de la organización constraints/gcp.restrictNonCmekServices en cualquier tabla de la consulta, el almacenamiento en caché se inhabilita automáticamente para esa consulta. Para obtener más información, consulta Almacenamiento en caché inteligente.
  • Residencia de datos y cumplimiento: Cuando creas un catálogo o una conexión federados en una región de Google Cloud , se almacenan los datos almacenados en caché en reposo en esa región de destino. Si tus datos de nube remotos residen en una jurisdicción diferente, asegúrate de que el almacenamiento en caché entre regiones cumpla con los requisitos de residencia de datos y cumplimiento de reglamentaciones de tu organización.

Flujo de trabajo general

Para acceder a los datos multinube, sigue estos pasos generales:

  • Configura Cross-Cloud Interconnect (opcional): Configura una conexión privada entre tu VPC de Google Cloud y tu proveedor de servicios en la nube remoto.
  • Configura la federación: Configura la autenticación y crea un catálogo federado en Lakehouse.
    • Autenticación base (obligatoria): Configura la autenticación de OpenID Connect (OIDC) (recomendada) o la autenticación basada en secretos para permitir que Lakehouse realice la sincronización de esquemas y metadatos en segundo plano con la cuenta de servicio del catálogo.
    • Federación de identidades de usuario (opcional): Habilita la federación de identidades de usuario (--federated-catalog-identity-mode="user-identity-federation") para permitir que las consultas se ejecuten con la identidad del usuario final autenticado. Esto permite que Databricks Unity Catalog atribuya consultas a los usuarios finales, aplique permisos y genere registros de auditoría.
  • Verifica la conexión: Verifica que Lakehouse pueda conectarse correctamente a tu catálogo remoto.
  • Consulta datos: Ejecuta consultas en tus datos federados con BigQuery o Managed Service para Apache Spark. El almacenamiento en caché de Lakehouse se habilita automáticamente para las consultas con el objetivo de ahorrar costos de salida. Para obtener más información, consulta Consulta datos remotos.
  • Configura permisos: Usa Identity and Access Management (IAM) para administrar quién puede ver y consultar los datos federados.

Configura Cross‑Cloud Interconnect (opcional)

De forma predeterminada, las consultas a tu catálogo remoto se envían a través de la Internet pública. Para ayudar a mejorar la seguridad y el cumplimiento, proporcionar un rendimiento predecible y reducir los costos de transferencia de datos, usa una interconexión privada. Esto establece una conexión de red privada y dedicada entre tu nube privada virtual (VPC) de Google Cloud y la red de tu proveedor de servicios en la nube remoto (por ejemplo, AWS).

Puedes aprovisionar y configurar cualquiera de las siguientes opciones de interconexión privada entre tu VPC de Google Cloud y la VPC de tu proveedor de servicios en la nube remoto (por ejemplo, AWS):

Establece sesiones de BGP entre tu Cloud Router en Google Cloud y la VPC de tu proveedor de servicios en la nube remoto para garantizar el intercambio de rutas.

Para habilitar las consultas privadas, debes configurar una ruta de acceso desde Lakehouse hasta tu bucket de almacenamiento remoto (por ejemplo, un bucket de Amazon S3 de AWS) a través de tu interconexión privada. Existen dos flujos de arquitectura que puedes seguir para configurar este enrutamiento:

  • Enrutamiento del balanceador de cargas de red del proxy regional interno: Este flujo usa un balanceador de cargas de red del proxy regional interno deGoogle Cloud para distribuir las solicitudes entre los grupos de extremos de red (NEG) de conectividad híbrida que apuntan a varias interfaces de red elásticas (ENI) de AWS. Este flujo es esencial para el balanceo de cargas, la escalabilidad y la alta disponibilidad. Es obligatorio para CCI de socio y se recomienda para CCI dedicada para el balanceo de cargas, la escalabilidad y la alta disponibilidad.
  • Enrutamiento directo de extremos: Este flujo conecta el Directorio de servicios directamente a una sola dirección IP de extremo de VPC de interfaz de AWS. Este flujo solo funciona para CCI dedicada y no se admite para CCI de socio.

Selecciona el flujo de configuración que coincida con tus requisitos de arquitectura:

Balanceador de cargas de red del proxy interno regional

Para configurar un balanceador de cargas de red del proxy regional interno que distribuya las solicitudes entre varias ENI de AWS para lograr alta disponibilidad y balanceo de cargas, sigue estos pasos:

Configura las redes de AWS

Primero, crea un extremo de interfaz de VPC de Amazon S3 (AWS PrivateLink):

  1. En la consola de VPC de AWS, crea un extremo de interfaz para Amazon S3.
  2. Para el nombre del servicio, especifica com.amazonaws.AWS_REGION.s3.
  3. Selecciona la VPC y las subredes que están conectadas a través de Direct Connect a tu VPC de Google Cloud .
  4. Adjunta grupos de seguridad al extremo para controlar el acceso entrante.
  5. Esto aprovisiona interfaces de red elásticas (ENI) en cada subred seleccionada. Anota las direcciones IP privadas de estas ENI.

A continuación, configura los grupos de seguridad:

  • Asegúrate de que el grupo o los grupos de seguridad conectados a las ENI de extremo de Amazon S3 permitan el tráfico TCP entrante en el puerto 443 desde tu VPC de Google Cloud . Esto debe incluir el rango CIDR de tu Google Cloud subred de solo proxy para permitir las verificaciones de estado y el tráfico reenviado.

Configura las redes de Google Cloud

Para simplificar la configuración, ejecuta los siguientes comandos para configurar el balanceador de cargas interno. Para obtener parámetros de configuración avanzados o más detalles, consulta Configura un balanceador de cargas de red de proxy regional interno para extremos híbridos.

gcloud compute networks subnets create PROXY_SUBNET_NAME \
    --purpose=REGIONAL_MANAGED_PROXY \
    --role=ACTIVE \
    --region=REGION \
    --network=VPC_NETWORK \
    --range=PROXY_SUBNET_RANGE

Reemplaza lo siguiente:

  • PROXY_SUBNET_NAME: Es un nombre para la subred de solo proxy.
  • PROXY_SUBNET_RANGE: Es un rango CIDR sin usar dentro de tu red de VPC (por ejemplo, 10.129.0.0/23).

  1. Crea una verificación de estado regional:

    gcloud compute health-checks create tcp HEALTH_CHECK_NAME \
    --region=REGION \
    --port=443

    Reemplaza lo siguiente:

    • HEALTH_CHECK_NAME: Es un nombre para la verificación de estado.
    • REGION: Es la región de Google Cloud (por ejemplo, us-east4).

  2. Crea grupos de extremos de red (NEG) de conectividad híbrida y agrega extremos:

    Crea un NEG híbrido (NON_GCP_PRIVATE_IP_PORT) para cada zona:

    gcloud compute network-endpoint-groups create NEG_NAME \
    --network-endpoint-type=NON_GCP_PRIVATE_IP_PORT \
    --zone=ZONE \
    --network=VPC_NETWORK

    Agrega la dirección IP privada de tu ENI de AWS al NEG híbrido correspondiente:

    gcloud compute network-endpoint-groups update NEG_NAME \
    --zone=ZONE \
    --add-endpoint="ip=AWS_S3_IP,port=443"

    Reemplaza lo siguiente:

    • NEG_NAME: Es un nombre para el NEG híbrido.
    • ZONE: Es la zona de Google Cloud (por ejemplo, us-east4-a). Esta zona debe residir dentro de la región de tu adjunto de VLAN de Cross‑Cloud Interconnect.
    • VPC_NETWORK: Es el nombre de tu red de VPC.
    • AWS_S3_IP: Es la dirección IP privada del extremo de VPC de Amazon S3 de AWS (ENI) en esa zona.

    Repite estos comandos para crear NEG y agregar extremos para otras zonas si tus ENI de AWS están distribuidas en varias zonas.

  3. Crea y configura el servicio de backend:

    Crea un servicio de backend regional con balanceo de cargas administrado interno:

    gcloud compute backend-services create BACKEND_SERVICE_NAME \
    --load-balancing-scheme=INTERNAL_MANAGED \
    --protocol=TCP \
    --region=REGION \
    --health-checks=HEALTH_CHECK_NAME \
    --health-checks-region=REGION

    Agrega tus NEG híbridos al servicio de backend:

    gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
    --region=REGION \
    --network-endpoint-group=NEG_NAME \
    --network-endpoint-group-zone=ZONE \
    --balancing-mode=CONNECTION \
    --max-connections=MAX_CONNECTIONS

    Reemplaza lo siguiente:

    • BACKEND_SERVICE_NAME: Es un nombre para el servicio de backend.
    • NEG_NAME: Es el nombre del NEG híbrido que creaste en el paso anterior.
    • ZONE: la zona de Google Cloud (por ejemplo, us-east4-a).
    • MAX_CONNECTIONS: Es la cantidad máxima de conexiones simultáneas que debe controlar el backend (por ejemplo, 100).

    Repite el comando add-backend para cada NEG híbrido que hayas creado.

  4. Configura el frontend del balanceador de cargas:

    Crea un proxy TCP de destino:

    gcloud compute target-tcp-proxies create TARGET_PROXY_NAME \
    --backend-service=BACKEND_SERVICE_NAME \
    --region=REGION

    Crea una regla de reenvío para enrutar el tráfico al proxy de destino:

    gcloud compute forwarding-rules create FORWARDING_RULE_NAME \
    --load-balancing-scheme=INTERNAL_MANAGED \
    --network=VPC_NETWORK \
    --subnet=VPC_SUBNET \
    --ports=443 \
    --region=REGION \
    --target-tcp-proxy=TARGET_PROXY_NAME \
    --target-tcp-proxy-region=REGION \
    --allow-global-access

    Reemplaza lo siguiente:

    • TARGET_PROXY_NAME: Es un nombre para el proxy de destino.
    • FORWARDING_RULE_NAME: un nombre para la regla de reenvío.
    • VPC_SUBNET: Es el nombre de la subred de tu VPC.

Después de crear la regla de reenvío para el balanceador de cargas, toma nota de la dirección IP interna que se le asignó. Este es tu ILB_IP_ADDRESS.

Configura el Directorio de servicios

Registra la dirección IP del ILB en el Directorio de servicios para que Lakehouse pueda descubrirla.

  1. Crea un espacio de nombres para tu nube remota:

    gcloud service-directory namespaces create NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION

    Reemplaza lo siguiente:

    • NAMESPACE: Es un identificador único para tu espacio de nombres.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • REGION: La Google Cloud región Por ejemplo: us-east4. Debe ser la misma región que la del catálogo federado.

  2. Crea un servicio en el espacio de nombres del Directorio de servicios:

    gcloud service-directory services create SERVICE_NAME \
    --namespace=NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION

    Reemplaza lo siguiente:

    • SERVICE_NAME: Es un identificador único para tu servicio.

  3. Crea un extremo para el ILB en el servicio:

    gcloud service-directory endpoints create ENDPOINT_NAME \
    --project=PROJECT_ID \
    --namespace=NAMESPACE \
    --service=SERVICE_NAME \
    --location=REGION \
    --network=projects/PROJECT_NUMBER/global/networks/VPC_NETWORK \
    --address=ILB_IP_ADDRESS \
    --port=443

    Reemplaza lo siguiente:

    • ENDPOINT_NAME: Es un identificador único para tu extremo.
    • PROJECT_NUMBER: Es el número del proyecto de Google Cloud. Usa el número de tu proyecto en la marca --network.
    • ILB_IP_ADDRESS: Es la dirección IP interna de tu regla de reenvío del ILB.

Extremo directo

Para configurar el Directorio de servicios de modo que enrute el tráfico directamente a una sola dirección IP del extremo de VPC de la interfaz de AWS, sigue estos pasos:

  1. Crea un extremo de VPC de interfaz para Amazon S3 dentro de tu VPC de AWS. Toma nota de la dirección IP y el puerto de este extremo.

  2. Crea un espacio de nombres para tu nube remota:

    gcloud service-directory namespaces create NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION

    Reemplaza lo siguiente:

    • NAMESPACE: Es un identificador único para tu espacio de nombres.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • REGION: La Google Cloud región Por ejemplo: us-east4. Debe ser la misma región que la del catálogo federado.

  3. Crea un servicio en el espacio de nombres del Directorio de servicios:

    gcloud service-directory services create SERVICE_NAME \
    --namespace=NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION

    Reemplaza lo siguiente:

    • SERVICE_NAME: Es un identificador único para tu servicio.

  4. Crea un extremo en el servicio que contenga la información de enrutamiento para tu extremo de VPC de interfaz de Amazon S3:

    gcloud service-directory endpoints create ENDPOINT_NAME \
    --service=SERVICE_NAME \
    --namespace=NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION \
    --address=S3_VPCE_IP_ADDRESS \
    --port=S3_VPCE_PORT \
    --network=projects/PROJECT_NUMBER/global/networks/VPC_NETWORK

    Reemplaza lo siguiente:

    • ENDPOINT_NAME: Es un identificador único para tu extremo.
    • S3_VPCE_IP_ADDRESS: la dirección IP de tu extremo de VPC de la interfaz de Amazon S3. Por ejemplo, 10.0.1.45
    • S3_VPCE_PORT: Es el número de puerto del extremo de VPC de la interfaz de Amazon S3. Por ejemplo, 443
    • PROJECT_NUMBER: Es el número del proyecto de Google Cloud. Usa el número de tu proyecto en la marca --network.
    • VPC_NETWORK: Es el nombre de la red de VPC de Google Cloud asociada con tu interconexión privada.

Configura la federación

Para consultar tus datos, debes configurar un catálogo federado de Lakehouse que se conecte a tu Databricks Unity Catalog remoto.

Configura la autenticación

La federación requiere autenticarse en el catálogo remoto como una principal de servicio de Databricks. Elige una de las siguientes opciones de autenticación:

OIDC

OpenID Connect (OIDC) permite la autenticación sin secretos a través de la federación de tokens de OAuth de Databricks.

  1. Crea una principal de servicio en tu cuenta de Databricks que tenga acceso de lectura al Unity Catalog de destino y el privilegio EXTERNAL USE SCHEMA en el catálogo y sus recursos.
  2. Guarda el ID de aplicación (UUID) de la entidad de servicio. Lo necesitarás para un paso posterior.

Basado en secretos

Esta opción usa un ID de cliente de OAuth y un secreto del cliente almacenados de forma segura con secretos regionales de Secret Manager.

  1. Crea una principal de servicio en tu cuenta de Databricks que tenga acceso de lectura al Unity Catalog de destino y el privilegio EXTERNAL USE SCHEMA en el catálogo y sus recursos.

  2. Genera un secreto de OAuth para la cuenta principal de servicio.

  3. Crea un archivo JSON llamado credentials.json con tu carga útil:

    {
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET"
}

    Reemplaza lo siguiente:

    • CLIENT_ID: Es el ID de cliente de OAuth para tu principal de servicio de Databricks.
    • CLIENT_SECRET: Es el secreto del cliente de OAuth para tu principal de servicio de Databricks.

  4. Configura el extremo regional para Secret Manager:

    De forma predeterminada, Secret Manager usa un extremo global. Sin embargo, Lakehouse requiere que tus secretos se almacenen en la misma región que tu catálogo de Lakehouse. Para interactuar con los secretos regionales con la CLI de gcloud, debes anular el extremo de la API predeterminado para tu sesión o perfil actual. Por ejemplo, secretmanager.us-east4.rep.googleapis.com.

    gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/

    Reemplaza lo siguiente:

    • REGION: Es la región de Google Cloud en la que se almacena tu secreto de Secret Manager. Por ejemplo, us-east4. Para evitar problemas de conectividad, el secreto y el catálogo deben crearse en la misma región.

  5. Sube la carga útil a Secret Manager:

    gcloud secrets create DATABRICKS_SECRET_NAME \
  --location="REGION" \
  --project="PROJECT_ID" \
  --data-file=credentials.json

    Reemplaza lo siguiente:

    • DATABRICKS_SECRET_NAME: Es un nombre para tu secreto de Databricks.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .

Crea un catálogo federado

Crea el catálogo federado con la consola de Google Cloud o la CLI de gcloud.

Consideraciones:

Console

Para crear un catálogo federado, haz lo siguiente:

  1. En la consola de Google Cloud , ve a Lakehouse.

    Ir a Lakehouse

  2. Haz clic en Crear catálogo.

  3. Haz clic en Catálogo federado.

    Aparecerá la sección Configuración del catálogo.

  4. En Fuente de catálogo federado, selecciona Databricks (Unity).

  5. En Ubicación de los datos, selecciona la región de Lakehouse en la que deseas crear el catálogo federado. Por ejemplo, us-east4 Para minimizar la latencia (incluso en la Internet pública), haz lo siguiente cuando selecciones una región:

    • Si tu Unity Catalog está en AWS, selecciona la región deGoogle Cloud más cercana a tu región de AWS.
    • Si tu Unity Catalog está en Google Cloud, selecciona exactamente la misma región.

  6. Haz clic en Continuar.

    Aparecerá la sección Detalles de la conexión.

  7. En la sección Detalles del catálogo remoto, en el campo Nombre de la instancia de Unity, ingresa el nombre de la instancia de Databricks de destino. Por ejemplo: abcd.cloud.databricks.com.

  8. En el campo Nombre del catálogo de Unity, ingresa el nombre del catálogo de Unity de Databricks de destino con el que se federará.

  9. Selecciona una opción para Método de autenticación:

    • En OIDC, ingresa el ID de aplicación de la entidad de servicio.
    • En Secreto, ingresa el nombre de tu secreto. Usa el siguiente formato: projects/PROJECT_ID/locations/REGION/secrets/DATABRICKS_SECRET_NAME.

  10. Opcional: En la sección Modo de identidad, selecciona una opción:

    • Identidad de servicio (predeterminada): Las consultas se ejecutan como la cuenta de servicio de Lakehouse.
    • Identidad del usuario: Las consultas se ejecutan con la identidad del usuario final autenticado y se propagan al catálogo remoto. La federación de identidades debe configurarse en el catálogo remoto.

  11. Opcional: En el campo Nombre del directorio de servicios, ingresa la ruta de acceso a tu servicio del Directorio de servicios. Por ejemplo: projects/PROJECT_ID/locations/REGION/namespaces/SERVICE_DIRECTORY_NAMESPACE/services/SERVICE_NAME. Esto solo es necesario si configuras una interconexión privada (Cross‑Cloud Interconnect).

  12. Haz clic en Crear.

gcloud

OIDC

Si usas OIDC, debes especificar --unity-service-principal-application-id.

Internet público (sin CCI)

Si no configuras CCI, la conexión se realiza de forma segura a través de la Internet pública.

gcloud biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="unity" \
    --unity-service-principal-application-id="UNITY_SERVICE_PRINCIPAL_APPLICATION_ID" \
    --unity-instance-name="UNITY_INSTANCE_NAME" \
    --unity-catalog-name="UNITY_CATALOG_NAME" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --federated-catalog-identity-mode="IDENTITY_MODE"

Propiedad del cliente (CCI)

Si configuraste una interconexión privada (como CCI dedicada o CCI de socio), proporciona la referencia del servicio del Directorio de servicios para que Lakehouse enrute el tráfico de forma privada.

gcloud biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="unity" \
    --unity-service-principal-application-id="UNITY_SERVICE_PRINCIPAL_APPLICATION_ID" \
    --unity-instance-name="UNITY_INSTANCE_NAME" \
    --unity-catalog-name="UNITY_CATALOG_NAME" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --federated-catalog-identity-mode="IDENTITY_MODE" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/SERVICE_DIRECTORY_NAMESPACE/services/SERVICE_NAME"

Reemplaza lo siguiente:

  • FEDERATED_CATALOG_NAME: Es un nombre para tu catálogo federado.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • REGION: Es la región de Lakehouse en la que se crea el catálogo federado. Debe ser la misma región que el espacio de nombres del Directorio de servicios y el Secret regional. Para minimizar la latencia, haz lo siguiente:
    • Si tu Unity Catalog está en AWS, selecciona la región deGoogle Cloud más cercana a tu región de AWS.
    • Si tu Unity Catalog está en Google Cloud, selecciona exactamente la misma región.
  • UNITY_SERVICE_PRINCIPAL_APPLICATION_ID: Es el ID de aplicación (UUID) de tu principal de servicio de Databricks.
  • UNITY_INSTANCE_NAME: el nombre de tu instancia de Databricks de destino. Por ejemplo: abcd.cloud.databricks.com.
  • UNITY_CATALOG_NAME: Es el nombre del catálogo de Unity de Databricks de destino con el que se federará.
  • REFRESH_INTERVAL: Especifica la frecuencia con la que se ejecuta la actualización de metadatos en segundo plano. Establece este valor como una duración, por ejemplo, 330s o 5m30s.
  • NAMESPACE_FILTERS: Es opcional y se trata de una lista separada por comas de los espacios de nombres que se federarán. Por ejemplo, ns1,ns2 Si se omite, se incluirán todos los espacios de nombres.
  • IDENTITY_MODE: Opcional: Especifica el modo de identidad para el catálogo. Establece en user-identity-federation para propagar las identidades de los usuarios finales en las consultas o en service-identity para ejecutar consultas como la cuenta de servicio del catálogo. Si se omite, el valor predeterminado es service-identity.
  • Si usas una interconexión privada (CCI), haz lo siguiente:
    • SERVICE_DIRECTORY_NAMESPACE: Es el espacio de nombres del Directorio de servicios que creaste durante la configuración de la interconexión privada.
    • SERVICE_NAME: Es el nombre del servicio del Directorio de servicios que creaste durante la configuración de la interconexión privada.

Basado en secretos

Si usas la autenticación basada en secretos, debes especificar --secret-name.

Internet público (sin CCI)

Si no configuras CCI, la conexión se realiza de forma segura a través de la Internet pública.

gcloud biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="unity" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/DATABRICKS_SECRET_NAME" \
    --unity-instance-name="UNITY_INSTANCE_NAME" \
    --unity-catalog-name="UNITY_CATALOG_NAME" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --federated-catalog-identity-mode="IDENTITY_MODE"

Propiedad del cliente (CCI)

Si configuraste una interconexión privada (como CCI dedicada o CCI de socio), proporciona la referencia del servicio del Directorio de servicios para que Lakehouse enrute el tráfico de forma privada.

gcloud biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="unity" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/DATABRICKS_SECRET_NAME" \
    --unity-instance-name="UNITY_INSTANCE_NAME" \
    --unity-catalog-name="UNITY_CATALOG_NAME" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --federated-catalog-identity-mode="IDENTITY_MODE" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/SERVICE_DIRECTORY_NAMESPACE/services/SERVICE_NAME"

Reemplaza lo siguiente:

  • FEDERATED_CATALOG_NAME: Es un nombre para tu catálogo federado.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • REGION: Es la región de Lakehouse en la que se crea el catálogo federado. Debe ser la misma región que el espacio de nombres del Directorio de servicios y el Secret regional. Para minimizar la latencia, haz lo siguiente:
    • Si tu Unity Catalog está en AWS, selecciona la región deGoogle Cloud más cercana a tu región de AWS.
    • Si tu Unity Catalog está en Google Cloud, selecciona exactamente la misma región.
  • DATABRICKS_SECRET_NAME: Es el nombre de tu secreto de Databricks.
  • UNITY_INSTANCE_NAME: el nombre de tu instancia de Databricks de destino. Por ejemplo: abcd.cloud.databricks.com.
  • UNITY_CATALOG_NAME: Es el nombre del catálogo de Unity de Databricks de destino con el que se federará.
  • REFRESH_INTERVAL: Especifica la frecuencia con la que se ejecuta la actualización de metadatos en segundo plano. Establece este valor como una duración, por ejemplo, 330s o 5m30s.
  • NAMESPACE_FILTERS: Es opcional y se trata de una lista separada por comas de los espacios de nombres que se federarán. Por ejemplo, ns1,ns2 Si se omite, se incluirán todos los espacios de nombres.
  • IDENTITY_MODE: Opcional: Especifica el modo de identidad para el catálogo. Establece en user-identity-federation para propagar las identidades de los usuarios finales en las consultas o en service-identity para ejecutar consultas como la cuenta de servicio del catálogo. Si se omite, el valor predeterminado es service-identity.
  • Si usas una interconexión privada (CCI), haz lo siguiente:
    • SERVICE_DIRECTORY_NAMESPACE: Es el espacio de nombres del Directorio de servicios que creaste durante la configuración de la interconexión privada.
    • SERVICE_NAME: Es el nombre del servicio del Directorio de servicios que creaste durante la configuración de la interconexión privada.

Completa la configuración de la autenticación

Completa el proceso de autenticación con el tipo de autenticación que elegiste.

OIDC

Cuando se crea el catálogo, Lakehouse aprovisiona una cuenta de servicio única para él. Debes recuperar el ID numérico único de la cuenta de servicio y usarlo para configurar una política de federación para la principal de servicio de Databricks.

  1. Recupera el ID numérico único de la cuenta de servicio del catálogo de Lakehouse:

    gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --format='value(biglake-service-account-id)'

  2. En tu cuenta de Databricks, configura una política de federación para la principal de servicio que creaste antes. Usa los siguientes valores:

    • URL del emisor: https://accounts.google.com
    • Asunto: Es el ID numérico único de la cuenta de servicio del catálogo de Lakehouse que se recuperó en el paso anterior.
    • Público: https://accounts.cloud.databricks.com

    Asegúrate de que la principal de servicio de Databricks tenga acceso de lectura al catálogo y al espacio de trabajo de destino, así como el privilegio EXTERNAL USE SCHEMA en el catálogo y sus recursos.

Basado en secretos

Cuando se crea el catálogo, Lakehouse aprovisiona una cuenta de servicio única para él (se muestra como biglake-service-account en la descripción del recurso).

Debes otorgar permiso a esta cuenta de servicio para acceder al secreto que creaste antes. Ten en cuenta que la propagación de las políticas de IAM puede tardar unos minutos.

Otorga permiso a la cuenta de servicio del catálogo para acceder al secreto:

gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
gcloud secrets add-iam-policy-binding DATABRICKS_SECRET_NAME \
  --project="PROJECT_ID" \
  --location="REGION" \
  --member="serviceAccount:$(gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
      --project="PROJECT_ID" \
      --format='value(biglake-service-account)')" \
  --role="roles/secretmanager.secretAccessor"

Para verificar que la cuenta de servicio del catálogo federado tenga acceso al secreto, ejecuta el siguiente comando:

gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
gcloud secrets get-iam-policy DATABRICKS_SECRET_NAME \
     --project="PROJECT_ID" \
     --location="REGION"

En el resultado, verifica que la cuenta de servicio biglake-service-account tenga asignado el rol roles/secretmanager.secretAccessor.

Asegúrate de que la principal de servicio de Databricks tenga acceso de lectura al catálogo y al espacio de trabajo de destino, así como el privilegio EXTERNAL USE SCHEMA en el catálogo y sus recursos.

Completa la configuración de la interconexión privada (solo Cross‑Cloud Interconnect)

Si enrutas el tráfico a través de una interconexión privada (CCI dedicada o de socio), debes otorgar permisos a la cuenta de servicio del catálogo de Lakehouse para descubrir y autorizar conexiones a través del Directorio de servicios.

Console

  1. En la consola de Google Cloud , dirígete a la página IAM.

    Ir a IAM

  2. Haz clic en Otorgar acceso (o Agregar).

  3. En el campo Principales nuevas, ingresa la dirección de correo electrónico de la cuenta de servicio del catálogo de Lakehouse. Puedes recuperar esta dirección de correo electrónico describiendo el catálogo (consulta la pestaña gcloud).

  4. En el menú Rol, selecciona Visualizador del Directorio de servicios (roles/servicedirectory.viewer).

  5. Haz clic en Agregar otro rol y selecciona Servicio autorizado de PSC del Directorio de servicios (roles/servicedirectory.pscAuthorizedService).

  6. Haz clic en Guardar.

gcloud

Otorga los roles necesarios a la cuenta de servicio del catálogo:

# Grant Service Directory Viewer
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --format='value(biglake-service-account)')" \
--role="roles/servicedirectory.viewer"

# Grant Service Directory PSC Authorized Service
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --format='value(biglake-service-account)')" \
--role="roles/servicedirectory.pscAuthorizedService"

Verifica la conexión

Verifica que el ciclo de actualización de metadatos en segundo plano del catálogo se haya completado correctamente y que los espacios de nombres estén sincronizados.

  1. Verifica que el estado de actualización indique que se realizó correctamente:

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

  2. Confirma que los espacios de nombres estén sincronizados:

    gcloud biglake iceberg namespaces list \
  --project="PROJECT_ID" \
  --catalog="FEDERATED_CATALOG_NAME"

Configura la federación de identidades de usuario (opcional)

Si configuraste la federación de identidades de usuario para tu catálogo federado, debes configurar una política de federación para toda la cuenta en Databricks.

Mientras que la actualización de metadatos en segundo plano se ejecuta como la cuenta de servicio del catálogo configurada con autenticación base (OIDC o basada en secretos), la federación de identidades de usuario requiere esta política para toda la cuenta para que Databricks pueda validar los tokens de identidad de los usuarios finales generados por Google Cloud durante las consultas interactivas. Esto permite que Databricks atribuya consultas a los usuarios finales, aplique permisos y genere registros de auditoría.

  1. Actualiza un catálogo existente (opcional):

    Si tienes un catálogo federado existente configurado con el modo de identidad de servicio predeterminado, puedes actualizarlo a la federación de identidades de usuario sin volver a crear el catálogo:

    Console

    1. En la consola de Google Cloud , ve a Lakehouse.

      Ir a Lakehouse

    2. En la lista de catálogos, haz clic en el nombre de tu catálogo federado.

      Aparecerá la página Detalles del catálogo.

    3. Haz clic en Editar catálogo.

    4. En la sección Modo de identidad, selecciona Identidad del usuario.

    5. Haz clic en Guardar.

    gcloud

    Ejecuta el comando gcloud biglake iceberg catalogs update:

    gcloud biglake iceberg catalogs update FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --federated-catalog-identity-mode="user-identity-federation"

  2. Recupera las reclamaciones de OIDC de tu catálogo:

    Ejecuta el siguiente comando para recuperar las reclamaciones de tokens que requiere Databricks:

    gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --format='yaml(federated-catalog-options.user-identity-federation-oidc)'

    El resultado es similar al siguiente:

    federated-catalog-options:
  user-identity-federation-oidc:
    audience: databricks-12345678-abcd-1234-efgh-1234567890ab
    issuer-url: https://www.gstatic.com/biglake/federation/organizations/123456789012

    Ten en cuenta lo siguiente sobre la disponibilidad de los reclamos:

    • issuer-url: Se deriva de tu organización de Google Cloud (https://www.gstatic.com/biglake/federation/organizations/ORGANIZATION_ID) y está disponible de inmediato después de la creación del catálogo.
    • audience: Tiene alcance para tu almacén de metadatos de Databricks de destino (databricks-METASTORE_ID) y se deriva del almacén de metadatos de Unity Catalog. Debido a que este valor se propaga mediante la actualización de metadatos en segundo plano, se debe completar la autenticación base y la actualización de metadatos en segundo plano debe estar activa (no establecida en 0). Consulta Verifica la conexión para comprobar que la actualización de metadatos en segundo plano esté configurada correctamente.

  3. Configura la política de federación para toda la cuenta de Databricks:

    1. En la consola de la cuenta de Databricks, ve a Configuración de la cuenta > Seguridad > Configuración del proveedor de identidad.
    2. En la sección Políticas de federación, haz clic en Crear política.
    3. En el diálogo de configuración de la política, establece los siguientes campos:
      • URL de la entidad emisora: Ingresa el valor issuer-url que recuperaste en el paso anterior (por ejemplo, https://www.gstatic.com/biglake/federation/organizations/ORGANIZATION_ID).
      • Públicos: Ingresa el valor de audience con alcance de almacén de metadatos que recuperaste en el paso anterior (por ejemplo, databricks-METASTORE_ID).
      • Reclamación de asunto: Deja este campo vacío (Databricks usa de forma predeterminada la reclamación sub que contiene la dirección de correo electrónico del usuario). Databricks usa este correo electrónico para compararlo con los usuarios configurados en tu cuenta de Databricks.
    4. Haz clic en Guardar.

  4. Verifica la federación de identidades de los usuarios y el registro de auditoría:

    Para verificar la ejecución de consultas atribuidas al usuario y el registro de auditoría, haz lo siguiente:

    1. Sigue las instrucciones de Consulta datos remotos para ejecutar una consulta en BigQuery en una tabla federada.

    2. En Databricks, verifica que el evento de acceso a la consulta se registre en los registros de auditoría de Databricks. Consulta la tabla del sistema system.access.audit en el editor de SQL de Databricks (consulta la referencia del registro de auditoría de Databricks). Ten en cuenta que los eventos auditables pueden tardar 15 minutos o más en aparecer en los registros de auditoría de Databricks:

      SELECT
  *
FROM
  system.access.audit
WHERE
  service_name = 'accounts'
  AND action_name IN ('oidcTokenAuthorization')
  AND event_time >= NOW() - INTERVAL 30 MINUTE
  AND user_identity.email = 'USER_EMAIL'
ORDER BY
  event_time DESC
LIMIT 10;

¿Qué sigue?