Aller au contenu principal
Dernière mise à jour le

Connectez-vous à Databricks à l'aide d'un tunnel SSH.

info

Bêta

Cette fonctionnalité est en Bêta.

Le tunnel SSH fourni par Databricks vous permet d'accéder à votre Workspace et d'exécuter interactivement des workloads sur le compute Databricks à partir d'IDEs en utilisant un tunnel SSH. Il est simple à configurer, élimine le besoin de gestion de l'environnement et maintient tout le code et les données sécurisés au sein de votre workspace Databricks.

Exigences​

Pour utiliser le tunnel SSH afin de vous connecter au compute serverless ou classique Databricks, vous devez disposer des éléments suivants :

  • Databricks CLI version 1.5.0 ou supérieure installée sur votre machine locale et authentification configurée. Consultez Installer ou mettre à jour la Databricks CLI.
  • Au choix :
    • Version de Visual Studio Code : 1.110.0 (Universal) ou supérieur et l'extension Remote - SSH (1.0.46+) installée.
    • Version du curseur : 2.6.11 (Universel) ou supérieur.

Pour vous connecter au compute GPU Serverless, la fonctionnalité AI Runtime doit être activée. Voir AI Runtime.

Pour vous connecter au compute classique (dédié, utilisateur unique) :

Connectez-vous au compute serverless​

Pour vous connecter à Serverless compute, exécutez la commande databricks ssh connect à partir d'un terminal dans votre IDE. Aucune étape de configuration séparée n'est requise.

Pour plus d'information sur la commande databricks ssh connect, consultez le groupe de commandesssh.

Bash
databricks ssh connect

Utilisez l'option --accelerator pour vous connecter à AI Runtime :

Bash
databricks ssh connect --accelerator=GPU_1xA10

databricks ssh connect vous offre une session interactive sur un nœud unique. Pour les travaux d'entraînement de longue durée ou l'entraînement distribué multi-nœuds, soumettez plutôt la charge de travail avec l'interface CLI air. Voir AI Runtime CLI.

Après la connexion, terminez la configuration de votre environnement de développement. Voir les projets ouverts.

Pour vous connecter au compute Serverless et start la session dans Visual Studio Code ou Cursor, utilisez l’option --ide. La CLI ouvre une fenêtre IDE qui pointe vers le dossier d’accueil du Workspace.

Bash
databricks ssh connect --ide=vscode

Connectez-vous au compute classique​

Pour vous connecter au compute classique, configurez d'abord la connexion SSH, puis connectez-vous à l'aide de votre IDE ou depuis le terminal.

Configurez la connexion SSH​

remarque

La configuration de la connexion SSH n'est requise que si vous vous connectez à un compute classique.

Tout d'abord, configurez le tunnel SSH à l'aide de la commande databricks ssh setup. Donnez un nom pour la connexion, par exemple, remplacez <connection-name> par my-connection:

Bash
databricks ssh setup --name <connection-name>

La CLI vous invite à sélectionner un cluster. Vous pouvez également en spécifier un directement avec --cluster <cluster-id>:

Bash
databricks ssh setup --name <connection-name> --cluster <cluster-id>
remarque

Pour les utilisateurs d'IntelliJ, Databricks recommande d'ajouter --auto-start-cluster=false à la commande de configuration et de démarrer le cluster manuellement avant de se connecter. En effet, les IDEs JetBrains start tous les clusters configurés au lancement, ce qui peut entraîner des frais de compute inattendus.

Connecter en utilisant Visual Studio Code ou Cursor​

  1. Pour Visual Studio Code, installez l'extension Remote SSH. Cursor inclut une extension SSH à distance par default.

  2. Dans le menu principal de l’IDE, cliquez sur Affichage > Palette de commandes . Sélectionnez Remote-SSH : paramètres . Vous pouvez également sélectionner Préférences : ouvrir les paramètres utilisateur (JSON) pour modifier settings.json directement.

  3. Sous Remote.SSH : Default Extensions (ou remote.SSH.defaultExtensions dans settings.json), ajoutez ms-Python.Python et ms-toolsai.jupyter.

    Si vous modifiez settings.json:

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

Si vous le souhaitez, augmentez la valeur de Remote.SSH: Connect Timeout (ou remote.SSH.connectTimeout dans settings.json) afin de réduire davantage le risque d'erreurs d'expiration. Le délai d'expiration par default est de 360.

  1. Dans la palette de commandes, sélectionnez Remote-SSH : se connecter à l'hôte .

  2. Dans le menu déroulant, sélectionnez la connexion que vous avez configurée à la première étape. L’IDE se connecte ensuite dans une nouvelle fenêtre.

Se connecter à l'aide d'IDEs IntelliJ​

  1. Suivez le tutoriel Serveur distant pour la configuration.
  2. Dans l'écran de nouvelle connexion, saisissez :
    • Nom d'utilisateur : root
    • Hôte : <connection-name>

Se connecter à l'aide du terminal​

Bash
ssh <connection-name>

Projets ouverts​

Par default, la commande databricks ssh connect s'ouvre sur un répertoire éphémère. Pour accéder aux fichiers de workspace, accédez à votre répertoire de workspace depuis l'IDE ou le terminal :

  • Dans Visual Studio Code ou Cursor, à partir de la Palette de commandes (**Cmd/Ctrl+Shift+P**), sélectionnez **Ouvrir le dossier** et accédez /Workspace/Users/<your-username> à.
  • À partir d'une fenêtre de terminal, modifiez votre répertoire : cd /Workspace/Users/<your-username>.
remarque

Les fichiers dans /Workspace, /Volumes, et /dbfs persistent après les redémarrages de cluster. Les fichiers dans /home, /root et d'autres chemins locaux sont éphémères et perdus au redémarrage.

Exécuter du code (Visual Studio Code ou Cursor)​

Pour exécuter du code à l'aide du tunnel SSH, l'environnement virtuel Databricks doit être configuré. Cet environnement comprend toutes les bibliothèques DBR intégrées et les bibliothèques à portée du compute.

  1. Ouvrez la palette de commandes ( Cmd/Ctrl+Shift+P ) et sélectionnez Python : Sélectionner l'interpréteur .

  2. Sélectionnez l'environnement virtuel pythonEnv-xxx dans la liste. Si vous configurez les dépendances Python à l'aide de l'indicateur --base-environment, sélectionnez le nom d'environnement virtuel le plus long dans la liste des options. Si l'environnement virtuel n'apparaît pas :

    1. Exécutez echo $DATABRICKS_VIRTUAL_ENV à partir d'un terminal dans l'IDE.

      Résultat d’exemple : /local_disk0/.ephemeral_nfs/envs/pythonEnv-xxx/bin/python

    2. Collez la sortie complète comme chemin de l’interpréteur dans l’invite **Python : Sélectionner l’interpréteur**.

  3. Ouvrez un nouveau terminal et l'environnement virtuel devrait s'activer automatiquement.

  4. Pour exécuter un Notebook Jupyter, assurez-vous que l'environnement virtuel est sélectionné comme noyau. Cliquez sur **Sélectionner le noyau** en haut à droite du Notebook.

Exécutez et déboguez les fichiers Python et les .ipynb Notebooks à l'aide des extensions standard Python et Jupyter.

Pour utiliser Spark dans un fichier Python sur un compute Serverless, initialisez une session explicitement :

Python
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.serverless().profile("DEFAULT").getOrCreate()

Gérer les dépendances​

Gérez les dépendances à l'aide d'un environnement de base de Workspace, de bibliothèques de clusters, de scripts d'initialisation ou de notebooks, selon votre type et vos exigences de compute.

Environnements de base du Workspace (recommandé pour Serverless et AI Runtime)​

remarque

Cette fonctionnalité nécessite que la préversion prise en charge de l'environnement de base du Workspace Serverless dans les Jobs soit activée. Voir Gérer les aperçus Databricks.

Utilisez un environnement de base du Workspace avec la version 4 ou inférieure de l’environnement Serverless pour préconfigurer les dépendances Python. Créez un environnement de base à l'aide de l'interface utilisateur du Workspace ou de la commande Databricks CLI databricks environments create-workspace-base-environment.

Spécifiez l'environnement à l'aide de l'option --base-environment lors de la connexion :

Bash
databricks ssh connect --base-environment my-workspace-env

Pour plus d'informations sur les formats acceptés, consultez databricks ssh connect.

Bibliothèques de clusters (recommandé pour le compute classique)​

Installez les dépendances à l'aide de l'interface utilisateur du Workspace sous **Compute > Bibliothèques**. Ceux-ci persistent malgré les redémarrages des clusters et sont disponibles dans pythonEnv-xxx. Voir Bibliothèques de clusters.

Dépendances non-Python​

Pour persister les dépendances non Python, utilisez un script d'initialisation qui installe les packages au start du compute. Vous pouvez éventuellement stocker les packages dans un volume Unity Catalog et y faire référence à partir du script d'initialisation. Voir Que sont les scripts d'initialisation ?.

Configuration de notebook spécifique au projet​

Pour les dépendances propres au projet, exécutez un notebook contenant des commandes %pip install au start de chaque session :

Python
# Install from pyproject.toml
%pip install .

# Install from a requirements file
%pip install -r requirements.txt

# Install a wheel from Volumes or Workspace
%pip install /Volumes/catalog/schema/volume/your_library.whl

%pip les commandes incluent des garde-fous spécifiques à Databricks et propagent les dépendances aux nœuds d'exécuteur Spark. Ceci permet des fonctions définies par l'utilisateur (UDF) avec des dépendances personnalisées.

Pour plus d'exemples, consultez Gérer les bibliothèques avec les commandes %pip.

Vous n'avez pas besoin de réexécuter le Notebook si la session se reconnecte dans les 10 minutes. Ceci est configurable à l'aide de -shutdown-delay dans votre configuration SSH.

remarque

Plusieurs sessions SSH sur le même cluster partagent un environnement virtuel.

Utilisation de Git​

remarque

Cette fonctionnalité nécessite l'activation de l'aperçu Prise en charge de Git CLI pour les dossiers Git . Voir Gérer les aperçus Databricks.

Vous pouvez utiliser la CLI Git dans le tunnel SSH avec les dossiers Git nouvellement créés et les identifiants Git que vous avez configurés dans le workspace Databricks. Voir Utiliser les commandes CLI Git (Bêta).

Si le CLI vous demande des identifiants au lieu de les récupérer automatiquement, vous devez connecter votre fournisseur Git à Databricks. Voir Connecter votre fournisseur Git à Databricks.

Limitations​

Le tunnel SSH fourni par Databricks présente les limitations suivantes :

  • Les clusters partagés ne sont pas pris en charge.
  • L'extension Databricks pour Visual Studio Code et le tunnel SSH ne sont pas encore compatibles et ne doivent pas être utilisés ensemble.
  • Les fichiers modifiés en dehors de /Workspace, /Volumes et /dbfs sont perdus lors du redémarrage du cluster.
  • Un maximum de 10 connexions SSH sont autorisées par cluster.
  • Les sessions inactives pourraient être interrompues après 1 heure.
  • Le tunnel SSH ne peut pas être lancé à partir d'autres environnements distants ou conteneurs Docker.
  • Vous pourriez rencontrer des problèmes de performances ou de connexion lorsque trois notebooks Jupyter ou plus sont ouverts simultanément. Cette limitation sera résolue dans une prochaine version.

Databricks Notebooks différences​

Il existe des différences dans les notebooks lors de l'utilisation du tunnel SSH :

  • Les fichiers Python ne définissent aucun global Databricks (comme spark ou dbutils). Vous devez les importer explicitement avec from databricks.sdk.runtime import spark.
  • Pour les Notebooks ipynb, ces fonctionnalités sont disponibles :
    • Globales Databricks : display, displayHTML, dbutils, table, sql, udf, getArgument, sc, sqlContext, spark
    • %sql commande magique pour exécuter des cellules SQL

Pour travailler avec les sources Python des « Notebook » :

  • Recherchez jupyter.interactiveWindow.cellMarker.codeRegex et définissez-le sur :

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

  • Recherchez jupyter.interactiveWindow.cellMarker.default et définissez-le sur :

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

Dépannage​

Cette section contient des informations sur la résolution de problèmes courants.

La connexion SSH échoue ou expire.​

  • Vérifiez que le cluster est en cours d'exécution dans l'interface utilisateur du Workspace.
  • Vérifiez que le port sortant 22 est ouvert et autorisé sur votre ordinateur portable, votre réseau et votre VPN.
  • Augmentez le délai d’expiration SSH. Consultez Se connecter avec Visual Studio Code ou Cursor.
  • Pour les erreurs d'incompatibilité de clé, supprimez ~/.databricks/ssh-tunnel-keys et réexécutez databricks ssh setup.
  • Pour les erreurs « remote host identification has changed », vérifiez le fichier ~/.ssh/known_hosts et supprimez les entrées liées à votre cluster.
  • Les sessions SSH peuvent être interrompues après 1 heure et pas plus de 10 connexions SSH ne peuvent être établies sur un seul cluster. Consulter Limitations.

code commande introuvable​

Si vous voyez Error: exec: "code": executable file not found in $PATH, ouvrez la palette de commandes ( Cmd/Ctrl+Maj+P ), sélectionnez Shell Command: Install 'code' command in PATH , puis redémarrez votre EDI ou votre session de terminal.

Erreurs d'authentification CLI​

  • Confirmez que votre profil CLI Databricks est valide en utilisant databricks auth login.
  • Veuillez confirmer que vous disposez des autorisations CAN MANAGE sur le cluster.

Mon code ne fonctionne pas​

Les fichiers disparaissent ou l'environnement Reset après le redémarrage du cluster​

  • Les fichiers dans les montages /Workspace, /Volumes et /dbfs persistent après les redémarrages de cluster. Les fichiers dans /home, /root et d'autres chemins locaux sont éphémères et perdus au redémarrage.
  • Utilisez la gestion des bibliothèques de clusters pour les dépendances persistantes. Automatisez les réinstallations à l'aide de scripts d'initialisation si nécessaire. Voir Que sont les scripts d'initialisation ?.

La configuration SSH échoue sur Windows (WSL)​

Exécutez databricks ssh setup directement sous Windows, pas dans WSL. L'instance Windows Visual Studio Code ne peut pas trouver les configurations SSH créées côté WSL.

FAQ​

En quoi le tunnel SSH est-il différent de Databricks Connect ?​

Databricks Connect vous permet d'écrire du code à l'aide des Spark API et de les exécuter à distance sur le compute Databricks au lieu de dans la session Spark locale. L'extension Databricks Visual Studio Code utilise Databricks Connect pour fournir un debugging intégré du code utilisateur sur Databricks.

Le tunnel SSH vous permet d'accéder au Workspace depuis votre IDE et déplace l'intégralité de votre environnement de développement vers le compute — Python, noyau, et toutes les exécutions s'exécutent sur Databricks avec un accès complet aux ressources de compute.

Comment mon code et mes données sont-ils sécurisés ?​

Tout le code s’exécute dans votre VPC cloud Databricks. Aucune donnée ni aucun code ne quitte votre environnement sécurisé. Le trafic SSH est entièrement chiffré.

Quelles IDEs sont prises en charge ?​

Visual Studio Code et Cursor sont officiellement pris en charge. Tout IDE doté de capacités SSH est compatible, mais seuls VS Code et Cursor sont testés.

Toutes les fonctionnalités du Notebook Databricks sont-elles disponibles depuis l’IDE ?​

Certaines fonctionnalités telles que display(), dbutils et %sql sont disponibles avec des limitations ou une configuration manuelle. Voir les différences des Databricks Notebooks.

Mon cluster start automatiquement lorsque je me connecte via le tunnel SSH ?​

Oui, mais s'il faut plus de temps pour start le cluster que le délai d'attente de connexion, la tentative de connexion échouera. Pour éviter cela, augmentez la valeur de Remote.SSH: Connect Timeout à partir de la palette de commandes (ou remote.SSH.connectTimeout dans settings.json) afin de réduire davantage les risques d'erreurs de délai d'attente.

Comment savoir si mon cluster est en cours d'exécution ?​

Accédez à Compute dans l’interface utilisateur du Workspace Databricks, et vérifiez l’état du cluster. Le cluster doit afficher Running pour que la connexion SSH fonctionne.

Comment déconnecter ma session SSH/IDE ?​

Vous pouvez déconnecter une session en fermant la fenêtre de votre IDE, en utilisant l'option **Déconnecter** dans votre IDE, en fermant votre terminal SSH, ou en exécutant la exit commande dans le terminal.

Comment arrêter le cluster et éviter les frais lorsque je ne travaille pas ?​

Pour arrêter immédiatement, terminez le cluster depuis l'interface utilisateur du Workspace. Accédez à Compute dans l'interface utilisateur du workspace Databricks, trouvez votre cluster, et cliquez sur Terminate ou Stop .

Définissez une politique d'**arrêt automatique** de courte durée sur votre cluster depuis l'interface utilisateur du Workspace. Après votre déconnexion, le serveur SSH attend pendant la période shutdown-delay (default : 10 minutes), puis le délai d'inactivité du cluster s'applique.

Comment gérer les dépendances persistantes ?​

Les dépendances installées pendant une session sont perdues après le redémarrage du cluster. Utilisez un stockage persistant (/Workspace/Users/<your-username>) pour les exigences et les scripts de configuration. Utilisez les bibliothèques de clusters ou les scripts d'initialisation pour l'automatisation.

Quelles méthodes d’authentification sont prises en charge ?​

L’authentification utilise l’interface CLI Databricks et votre fichier de profils ~/.databrickscfg. Les clés SSH sont gérées par le tunnel SSH.

Puis-je me connecter à des bases de données ou des services externes depuis le cluster ?​

Oui, tant que la mise en réseau de votre cluster autorise les connexions sortantes et que vous disposez des bibliothèques nécessaires.

Puis-je utiliser des extensions IDE supplémentaires ?​

La plupart des extensions fonctionnent lorsqu'elles sont installées dans votre session SSH distante, selon votre IDE et votre cluster. Visual Studio Code par default n'installe pas d'extensions locales sur les hôtes distants. Vous pouvez les installer manuellement en ouvrant le panneau des extensions et en activant vos extensions locales sur l'hôte distant. Vous pouvez également configurer Visual Studio Code pour qu'il installe toujours certaines extensions à distance. Voir Se connecter à Databricks.

Le tunnel SSH prend-il en charge Private Link ?​

Oui, mais les administrateurs du Workspace doivent autoriser les URL des marketplace d'extensions Visual Studio Code et Cursor. Votre machine locale doit également avoir la possibilité d'accéder à Internet.

Sur cette page