Compartir vía

Túnel SSH de Databricks

Importante

El túnel SSH de Databricks está en beta.

El túnel SSH de Databricks permite conectar tu IDE a la capacidad de cálculo de Databricks. Es fácil de configurar, le permite ejecutar y depurar código de forma interactiva en el clúster, reduce los errores de coincidencia del entorno y mantiene todo el código y los datos seguros en el área de trabajo de Databricks.

Requisitos

Para usar el túnel SSH, debe tener:

  • La CLI de Databricks versión 0.269 o posterior instalada en la máquina local, con la autenticación configurada. Consulte Instalación.
  • Computa en el área de trabajo de Databricks con el modo de acceso dedicado (usuario único). Consulte Introducción al proceso dedicado.
    • El proceso debe usar Databricks Runtime 17.0 y versiones posteriores.
    • El catálogo de Unity debe estar habilitado.
    • Si existe una directiva de cómputo, no debe prohibir la ejecución de trabajos.

Configuración del túnel SSH

En primer lugar, configure el túnel SSH mediante el comando databricks ssh setup. Reemplace <connection-name> por el nombre del túnel, por ejemplo, my-tunnel.

databricks ssh setup --name <connection-name>

La CLI le pide que elija un clúster o puede proporcionar un identificador de clúster pasando --cluster <cluster-id>.

Nota:

Para IntelliJ, Databricks recomienda incluir –-auto-start-cluster=false en el comando de instalación. Al iniciar un IDE de JetBrains, se inician automáticamente todos los clústeres, lo que puede dar lugar a costos de proceso no deseados. Si establece esta opción, debe iniciar el clúster en el área de trabajo para iniciar el túnel SSH.

Conexión a Databricks

A continuación, conéctese a Databricks mediante un IDE o un terminal.

Conexión mediante Visual Studio Code o cursor

  1. Para Visual Studio Code, instale la extensión SSH remota. El cursor incluye una extensión SSH remota.

  2. En el menú principal del IDE, haga clic en Ver>paleta de comandos. Seleccione Remote-SSH: Settings. Como alternativa, seleccione Preferencias: abra Configuración de usuario (JSON) para modificar settings.json directamente.

  3. En Remote.SSH: Extensiones predeterminadas (o remote.SSH.defaultExtensions en settings.json), agregue ms-Python.Python y ms-toolsai.jupyter.

    Si está modificando settings.json:

    "remote.SSH.defaultExtensions": [
    "ms-Python.Python",
    "ms-toolsai.jupyter"
]

    Nota:

    Opcionalmente, aumente el valor de Remote.SSH: Tiempo de espera de conexión (o remote.SSH.connectTimeout en settings.json) para reducir aún más la posibilidad de errores de tiempo de espera. El tiempo de espera predeterminado es 360.

  4. En la paleta de comandos, seleccione Remote-SSH: Connect to Host (Remote-SSH: Connect to Host).

  5. En la lista desplegable, seleccione el túnel que configuró en el primer paso. El IDE continúa con la conexión en una nueva ventana.

    Nota:

    Si el recurso de computación no se está ejecutando, se iniciará. Sin embargo, si tarda más tiempo de espera en iniciarse el proceso, se producirá un error en el intento de conexión SSH.

  6. Seleccione Linux cuando se le solicite el tipo de servidor.

Conexión mediante IDE de IntelliJ

  1. Siga el tutorial desarrollo remoto para configurarlo.

  2. En la pantalla nueva conexión, escriba lo siguiente:

    Nombre de usuario: rootHost:<connection-name>

Conexión mediante terminal

Para conectarse a Databricks desde la línea de comandos, proporcione el ssh nombre del comando de la conexión, por ejemplo:

ssh my-tunnel

Abrir proyectos

  1. La conexión inicial abre una ventana de IDE vacía sin ninguna carpeta abierta. En Visual Studio Code, use el comando Abrir carpeta de la paleta comandos para abrir un proyecto deseado.
  2. Use el montaje del área de trabajo (/Workspace/Users/<your-username>) para el almacenamiento persistente.

Ejecutar código (Visual Studio Code)

  • Si abre un proyecto de Python, la extensión de Python puede detectar automáticamente entornos virtuales, pero todavía necesita activar manualmente el correcto. Seleccione el comando Intérprete en la paleta Comandos y elija el entorno pythonEnv-xxx. Esto tiene acceso a todas las bibliotecas integradas de Databricks Runtime o a todo lo que haya instalado globalmente en el clúster.
  • En algunos casos, la extensión de Python no puede detectar automáticamente entornos virtuales (venv), como cuando se abre una carpeta que no se puede reconocer como un proyecto de Python. Para corregirlo, abra un terminal y ejecute echo $DATABRICKS_VIRTUAL_ENVy, a continuación, copie la ruta de acceso y úsela en el comando Python: Seleccionar intérprete .

Una vez seleccionado el venv, los archivos o cuadernos de Python se pueden ejecutar con acciones de ejecución o depuración normales proporcionadas por las extensiones de Python o Jupyter.

Administración de dependencias de Python

La manera más sencilla de instalar las dependencias necesarias es usar la interfaz de usuario del área de trabajo. Consulte Bibliotecas con ámbito de cómputo. Con este enfoque, se instalan dependencias globalmente para el clúster. No es necesario volver a instalar bibliotecas cada vez que se reinicie el clúster.

Sin embargo, para una configuración más programática que se limita a un proyecto específico, use una instalación de ámbito de cuaderno.

Cuaderno de instalación específico del proyecto

Para administrar las dependencias de un proyecto específico:

  1. Cree un archivo setup.ipynb en tu proyecto.

  2. La CLI ssh crea un entorno de Python (pythonEnv-xxx), que ya tiene bibliotecas integradas de Databricks Runtime o bibliotecas de ámbito de proceso. Conecte el cuaderno a este pythonEnv-xxx entorno.

  3. Utilice %pip install comandos para instalar sus dependencias.

    • %pip install . si tiene pyproject.toml (%pip install .<group> para acotar el ámbito)
    • %pip install -r dependencies.txt si tiene dependencies.txt
    • %pip install /Volumes/your/wheel.whl (o /Workspace rutas de acceso) si creó y cargó una biblioteca personalizada como rueda

    %pip los comandos tienen lógica específica de Databricks con límites de protección adicionales. La lógica también garantiza que las dependencias estén disponibles para todos los nodos del ejecutor de Spark, no solo el nodo de controlador al que está conectado. Esto permite funciones definidas por el usuario (UDF) con dependencias personalizadas.

    Para obtener más ejemplos de uso, consulte Administración de bibliotecas con %pip comandos.

Ejecute este cuaderno cada vez que establezca una nueva sesión ssh. No es necesario volver a instalar las dependencias si se quita una sesión ssh existente y se vuelve a conectar al clúster en menos de 10 minutos. (La hora se puede configurar con la opción -shutdown-delay=10m en la configuración de ssh local).

Nota:

Si tiene varias sesiones ssh conectadas al mismo clúster al mismo tiempo, usan el mismo entorno virtual.

Limitaciones

El túnel SSH de Databricks tiene las siguientes limitaciones:

  • La extensión de Databricks para Visual Studio Code y el túnel SSH de Databricks aún no son compatibles y no deben usarse juntos.
  • Cualquier carpeta de Git que haya creado en el área de trabajo a través de la interfaz de usuario del área de trabajo de Databricks no se reconocerá como un repositorio git por parte de la CLI de Git y las integraciones de Git IDE, ya que estas carpetas carecen de metadatos .git. Para solucionar esto, consulte ¿Cómo uso Git con el túnel SSH?.
  • Los montajes principal y raíz del clúster al que se conecta son efímeros. No se conserva ningún contenido del clúster cuando se reinicia el clúster.

Diferencias entre los notebooks de Databricks

Existen algunas diferencias en los cuadernos al usar el túnel SSH:

  • Los archivos de Python no definen ningún global de Databricks (como spark o dbutils). Debe importarlos explícitamente con from databricks.sdk.runtime import spark.
  • En el caso de los cuadernos de ipynb, estas características están disponibles:
    • Datos globales de Databricks: display, displayHTML, dbutils, table, sql, udf, getArgument, sc, sqlContext, spark
    • %sql comando mágico para ejecutar celdas SQL

Para trabajar con "cuadernos" de origen de Python:

  • Busque jupyter.interactiveWindow.cellMarker.codeRegex y establézcalo en:

    ^# COMMAND ----------|^# Databricks notebook source|^(#\\s*%%|#\\s*\\<codecell\\>|#\\s*In\\[\\d*?\\]|#\\s*In\\[ \\])

  • Busque jupyter.interactiveWindow.cellMarker.default y establézcalo en:

    # COMMAND ----------

Solución de problemas

Esta sección contiene información sobre cómo resolver problemas comunes.

Se produce un error en la conexión SSH o se agota el tiempo de espera

  • Asegúrese de que el clúster se está ejecutando en la interfaz de usuario de Databricks y no solo se detiene ni se inicia.
  • Compruebe que el puerto de salida 22 está abierto y permitido en su portátil, red o VPN.
  • Aumente el tiempo de espera de conexión SSH en el IDE. Consulte Conexión mediante Visual Studio Code o Cursor.
  • Si ve errores de coincidencia de clave pública o privada, intente eliminar la ~/.databricks/ssh-tunnel-keys carpeta.
  • Si ve errores de "la identificación remota del host ha cambiado", compruebe el ~/.ssh/known_hosts archivo y elimine las entradas relacionadas con el clúster.
  • Si la sesión SSH se cierra después de 1 hora, se trata de una limitación conocida. Consulte limitaciones de .
  • No se permiten más de 10 conexiones ssh a un único clúster.

Errores de autenticación de la CLI

  • Confirme que el perfil de la CLI de Databricks es válido y autenticado (databricks auth login).
  • Asegúrese de que tiene los permisos de clúster adecuados, como CAN MANAGE.

Los archivos desaparecen o se restablecen el entorno después del reinicio del clúster

  • Solo /Workspacelos montajes , /Volumesy /dbfs son persistentes. Todos los datos de /home, /root, etc. se borran después de un reinicio.
  • Use la administración de bibliotecas de clústeres para las dependencias persistentes. Automatice la reinstalación mediante scripts de inicialización si es necesario. Consulte ¿Qué son los scripts de inicialización?.

Error "No es un repositorio de Git" o faltan características de Git en el IDE

Git solo funciona si clonas en /Workspace/Users/<your-username> usando el terminal. Las carpetas creadas por web no tienen metadatos .git. Consulte ¿Cómo uso Git con el túnel SSH?.

Mi código no funciona

  • Asegúrese de seleccionar el intérprete de Python adecuado que tenga acceso a todas las dependencias de Databricks Runtime.
    • Si abre un proyecto de Python, la extensión de Python puede detectar automáticamente entornos virtuales, pero todavía necesita activar manualmente el correcto. Ejecute el comando Python: Seleccionar Intérprete y elija el entorno pythonEnv-xxx. Tendrá acceso a todas las bibliotecas integradas de Databricks Runtime o a todo lo que haya instalado globalmente en el clúster.
    • En algunos casos, la extensión de Python no puede detectar automáticamente entornos virtuales, como cuando se abre una carpeta que no se puede reconocer como un proyecto de Python. Puede abrir un terminal y ejecutar echo $DATABRICKS_VIRTUAL_ENVy, a continuación, copiar la ruta de acceso y usarla en el comando Python: Seleccionar intérprete .
  • Los cuadernos IPYNB y *.py los cuadernos de Databricks tienen acceso a las variables globales de Databricks, pero los archivos Python *.py no. Consulte Diferencias de cuadernos de Databricks.

No se puede configurar la conexión ssh en Windows en WSL

Databricks recomienda realizar la configuración de SSH directamente en Windows. Si la configura en el lado de WSL, pero después usa una versión de Windows de Visual Studio Code, no encontrará configuraciones ssh necesarias.

Preguntas más frecuentes

¿Cómo se protegen los datos y el código?

Todo el código se ejecuta en la nube de Databricks virtual private cloud (VPC). Ningún dato o código deja el entorno seguro. El tráfico SSH está totalmente cifrado.

¿Qué IDE se admiten?

Visual Studio Code y Cursor son compatibles oficialmente, pero el túnel SSH de Databricks es compatible con cualquier IDE con funcionalidades ssh.

¿Están disponibles todas las características del cuaderno de Databricks en el IDE?

Algunas características como display(), dbutilsy %sql están disponibles con limitaciones o configuración manual. Consulte Diferencias de cuadernos de Databricks.

¿Pueden desarrollar varios usuarios en el mismo clúster a la vez?

No.

¿Se iniciará automáticamente mi clúster al conectarse a través de SSH Tunnel?

Sí, pero si tarda más tiempo en iniciar el clúster que el tiempo de espera de conexión, se producirá un error en el intento de conexión.

¿Cómo sé si mi clúster se está ejecutando?

Vaya a Proceso en la interfaz de usuario del área de trabajo de Databricks y compruebe el estado del clúster. El clúster debe mostrar En ejecución para que funcionen las conexiones de túnel SSH.

¿Cómo desconecto mi sesión SSH/IDE?

Para desconectar una sesión, cierre la ventana del IDE, use la opción Desconectar en el IDE, cierre el terminal SSH o ejecute el exit comando en el terminal.

¿La desconexión de SSH detiene automáticamente mi clúster?

No, el servidor ssh tiene un retraso de apagado configurable y seguirá ejecutándose en segundo plano durante una cantidad de tiempo especificada (10 m de forma predeterminada, se puede cambiar en la configuración ssh ProxyCommand modificando -shutdown-delay ). Una vez finalizado el tiempo de espera, el servidor inicia el tiempo de espera de inactividad del clúster (que se configura durante la creación del clúster).

¿Cómo puedo parar el clúster para evitar cargos innecesarios?

Vaya a Proceso en la interfaz de usuario del área de trabajo de Databricks, busque el clúster y haga clic en Finalizar o Detener.

¿Cómo debo controlar las dependencias persistentes?

Las dependencias instaladas durante una sesión se pierden después del reinicio del clúster. Use el almacenamiento persistente (/Workspace/Users/<your-username>) para los requisitos y los scripts de configuración. Use bibliotecas de clústeres o scripts de inicialización para la automatización.

¿Qué métodos de autenticación se admiten?

La autenticación utiliza la CLI de Databricks y el archivo de configuración de perfiles ~/.databrickscfg. El túnel SSH de Databrick controla las claves SSH.

¿Puedo conectarme a bases de datos o servicios externos desde el clúster?

Sí, siempre que la red de clústeres permita conexiones salientes y tenga las bibliotecas necesarias.

¿Puedo usar extensiones de IDE adicionales?

La mayoría de las extensiones funcionan cuando se instalan dentro de la sesión de SSH remota, en función del IDE y el clúster. Visual Studio Code de forma predeterminada no instala extensiones locales en hosts remotos. Puede instalarlos manualmente abriendo el panel de extensiones y habilitando las extensiones locales en el host remoto. También puede configurar Visual Studio Code para instalar siempre determinadas extensiones de forma remota. Consulte Conexión a Databricks.

¿Cómo se usa Git con el túnel SSH?

Actualmente, las carpetas de Git creadas con la interfaz de usuario del área de trabajo de Databricks no se reconocen como repositorios git en los IDE. Para solucionar este problema, clone repositorios usando Git CLI desde su sesión SSH en la carpeta del espacio de trabajo persistente.

  1. Abra un terminal y vaya a un directorio primario deseado (por ejemplo, cd /Workspace/Users/<your-username>).
  2. Clonar tu repositorio en ese directorio.
  3. En Visual Studio Code, abra esta carpeta en una nueva ventana ejecutando code <repo-name> o abra la carpeta en una nueva ventana mediante la interfaz de usuario.
  • Last updated on