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 coût et les tarifs des fonctionnalités en version Beta sont susceptibles d'être modifiés.

Le tunnel SSH (Secure Shell) Databricks connecte Visual Studio Code, Cursor ou votre terminal au Workspace Databricks et au compute serverless, à l’environnement d’exécution de l’IA ou au compute classique de Databricks. Utilisez-le pour modifier les fichiers du Workspace et pour exécuter ou déboguer des scripts Python et des Notebooks, avec votre environnement Python et l’exécution du code sur le compute distant. Connectez-vous directement au compute serverless ou configurez une connexion SSH réutilisable vers un cluster classique dédié.

remarque

Le tunnel SSH est destiné au développement piloté par IDE. Pour exécuter des agents de codage dans un environnement léger et sandboxé, consultez Databricks Sandbox. Pour une comparaison des deux, consultez IDE connecté avec SSH.

Exigences​

start la connexion SSH à partir de votre machine locale. Le tunnel ne peut pas être lancé depuis un autre environnement distant ou un conteneur Docker.

Pour vous connecter au compute serverless ou classique, vous devez disposer de :

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

Pour se connecter au compute serverless, la redirection de port vers le compute serverless doit être activée. Voir Gérer la redirection de port vers le compute serverless.

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

Exigences supplémentaires pour le compute classique​

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

Choisir une connexion SSH​

Utilisez la méthode de connexion adaptée à votre type de compute :

Calculer

Méthode de connexion

Conditions d'installation

Compute serverless

databricks ssh connect

Aucune étape de configuration SSH distincte.

Ajouter --ide vscode ou --ide cursor pour lancer un IDE.

Runtime de l’IA

databricks ssh connect --accelerator <accelerator>

Aucune étape de configuration SSH distincte.

Ajouter --ide vscode ou --ide cursor pour lancer un IDE.

Pour les accélérateurs pris en charge, consultez --accelerator.

compute classique dédié à un seul utilisateur

Exécutez databricks ssh setup --name <connection-name> dans votre terminal.

start ensuite la session SSH depuis l'IDE ou exécutez ssh <connection-name>.

Sélectionnez un cluster dédié mono-utilisateur qui répond aux exigences du compute classique.

Les clusters partagés ne sont pas pris en charge.

Calculer

Méthode de connexion

Conditions d'installation

Compute serverless

databricks ssh connect

Aucune étape de configuration SSH distincte.

Ajouter --ide vscode ou --ide cursor pour lancer un IDE.

Runtime de l’IA

databricks ssh connect --accelerator <accelerator>

Aucune étape de configuration SSH distincte.

Ajouter --ide vscode ou --ide cursor pour lancer un IDE.

Pour les accélérateurs pris en charge, consultez --accelerator.

compute classique dédié à un seul utilisateur

Exécutez databricks ssh setup --name <connection-name> dans votre terminal.

start ensuite la session SSH depuis l'IDE ou exécutez ssh <connection-name>.

Sélectionnez un cluster dédié mono-utilisateur qui répond aux exigences du compute classique.

Les clusters partagés ne sont pas pris en charge.

Pour une comparaison avec Databricks Connect et d’autres options de développement, voir Se connecter depuis votre IDE.

Connectez-vous au compute serverless​

Une fois les exigences ci-dessus remplies, exécutez databricks ssh connect depuis votre terminal ou votre IDE.

La valeur --ide sélectionne l'éditeur à lancer, quel que soit l'éditeur ou le terminal à partir duquel vous exécutez la commande.

Bash
databricks ssh connect --ide vscode

La CLI ouvre une fenêtre Visual Studio Code connectée au compute distant.

Pour connaître les options de commande, y compris les connexions nommées et les profils d'authentification, voir databricks ssh connect.

Après la connexion, ouvrez votre projet de workspace et sélectionnez l'environnement Python. Si la connexion échoue, consultez Dépanner les connexions de tunnel SSH.

Connectez-vous au compute GPU serverless avec AI Runtime​

Avec AI Runtime activé, ajoutez --accelerator pour utiliser le compute GPU :

Bash
databricks ssh connect --accelerator GPU_1xA10

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

Connectez-vous au compute classique​

Pour une connexion réutilisable à un cluster dédié classique, configurez un host name SSH, puis sélectionnez cet hôte dans votre IDE ou connectez-vous depuis un terminal.

Configurez la connexion SSH​

remarque

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

Exécutez databricks ssh setup sur votre machine locale. Remplacez <connection-name> par un nom pour cette connexion, par exemple my-connection:

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

La CLI vous invite à sélectionner un cluster et ajoute une entrée d'hôte à votre configuration SSH. Vous pouvez également sélectionner un cluster directement. Remplacez <cluster-id> par l'ID de votre cluster dédié :

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

Pour configurer la durée pendant laquelle le tunnel SSH attend après la dernière déconnexion du client, ajoutez --shutdown-delay à la commande d'installation. La valeur default est de 10 minutes. Par exemple, pour définir un délai de 30 minutes pour les connexions via cette entrée d'hôte SSH :

Bash
databricks ssh setup --name <connection-name> --cluster <cluster-id> --shutdown-delay 30m
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 au compute classique à partir d'un terminal​

Utilisez le nom de connexion que vous avez configuré avec databricks ssh setup:

Bash
ssh <connection-name>

Pour une connexion directe sans entrée d'hôte SSH réutilisable, vous pouvez également utiliser la CLI. Remplacez <cluster-id> par l'ID de votre cluster dédié :

Bash
databricks ssh connect --cluster <cluster-id>

Consultez connexion SSH databricks.

Ouvrir des projets Workspace via SSH​

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 Python et les notebooks dans la session SSH​

Sélectionnez l'environnement Python fourni par votre session SSH avant d'exécuter le code. Pour le compute classique, cet environnement inclut les bibliothèques intégrées Databricks Runtime et les bibliothèques à l'échelle 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 pour les sessions SSH​

Choisissez la gestion des dépendances pour votre type de compute :

Pour les packages non Python, consultez les dépendances non Python.

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 de workspace avec la version 4 ou une version inférieure de l'environnement serverless pour préconfigurer les dépendances Python. Le tunnel SSH ne prend pas en charge --base-environment avec la version 5 ou une version supérieure de l'environnement serverless. Créez un environnement de base à l'aide de l'interface utilisateur du Workspace ou de la commande databricks environments create-workspace-base-environment de l'interface de ligne de commande Databricks CLI.

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

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

L’option --base-environment accepte un nom d’affichage, un chemin d'accès YAML au workspace ou un ID de ressource. Vous ne pouvez pas l’utiliser en même temps que --cluster. Voir 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 relancer le notebook de configuration si vous vous reconnectez avant l’arrêt du tunnel SSH. default, le tunnel s’arrête 10 minutes après la déconnexion du dernier client. Pour modifier ce délai, utilisez --shutdown-delay avec la commande correspondant à votre méthode de connexion :

  • Pour une connexion compute classique réutilisable, définissez le délai avec configuration SSH databricks. L'entrée d'hôte SSH générée applique le délai lorsque vous vous connectez depuis votre IDE ou exécutez ssh <connection-name>.
  • Pour une connexion CLI directe, définissez le délai avec databricks ssh connect.
remarque

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

Utiliser Git dans une session SSH​

info

Aperçu

Cette fonctionnalité est en Aperçu public. Les administrateurs de workspace peuvent contrôler l’accès au support de l’interface CLI Git pour les dossiers Git depuis la page Aperçus . Consultez Gérer les aperçus Databricks.

Vous pouvez utiliser le 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 de Git.

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.

Maintenir l’exécution des processus détachés​

Par default, lorsque le tunnel SSH est fermé, chaque processus start par la session est arrêté, y compris les processus que vous avez détachés de la session avec tmux, setsid ou nohup. Avant de les arrêter, le tunnel Logs un avertissement avec leurs ID de processus dans la sortie de l'exécution du Job du tunnel. databricks ssh connect imprime l'ID d'exécution du Job lorsqu'il start le tunnel.

Pour que le travail détaché continue après votre déconnexion, utilisez le flag --keep-detached-processes. Définissez l'indicateur sur la connexion qui start le tunnel avant de start le travail que vous souhaitez conserver. Voir Connexions à un tunnel existant.

  • Compute serverless ou classique : passez le flag à databricks ssh connect.
  • Compute classique avec un hôte SSH configuré : passez l’option à databricks ssh setup. L’entrée d’hôte SSH générée l’applique à chaque fois que vous vous connectez. Les connexions serverless ne nécessitent pas de configuration. Cette option ne s’applique donc qu’au compute classique.

L'exemple suivant maintient l'exécution des processus détachés sur le compute serverless :

Bash
databricks ssh connect --keep-detached-processes

L’exemple suivant maintient les processus détachés en cours d’exécution sur un cluster dédié :

Bash
databricks ssh connect --cluster 0123-456789-abcdefgh --keep-detached-processes

Lorsque vous utilisez ce flag et que le dernier client se déconnecte, le tunnel se comporte comme suit :

  • Après la période --shutdown-delay, le tunnel recherche les processus détachés. Pendant l'exécution, le tunnel continue de fonctionner au lieu de s'arrêter.
  • Les processus détachés conservent leur accès à /Workspace et /Volumes.
  • Après la fermeture du dernier processus détaché, le tunnel est fermé et l'exécution de son job est terminée.

Pendant que le tunnel est actif, vous pouvez vous reconnecter au même compute et reprendre le travail interrompu, par exemple avec tmux attach. Sur un compute Serverless, reconnectez-vous avec le même nom de connexion. Si vous omettez --name, la CLI déduit le nom de la connexion à partir de votre Workspace et des flags --accelerator et --base-environment, de sorte que la modification de l'un ou l'autre de ces flags start une connexion distincte.

Connexions à un tunnel existant​

Le mode du tunnel est fixe lorsqu'il start, et les connexions ultérieures le gèrent comme suit :

  • Si vous vous connectez avec l'indicateur à un tunnel qui a start sans lui, la CLI démarre un nouveau tunnel. Les processus que vous avez détachés dans le tunnel existant ne sont pas conservés, et ils s'arrêtent toujours lorsque ce tunnel s'arrête. Sur un cluster dédié, le nouveau tunnel arrête immédiatement celui existant, ce qui termine ses sessions ouvertes et arrête ses processus détachés.
  • Si vous vous connectez sans indicateur à un tunnel qui a été start avec, le CLI réutilise ce tunnel, et le tunnel continue de s'exécuter tandis que les processus détachés restent. Cela s'applique également aux connexions à partir d'autres entrées d'hôte SSH ou sessions IDE vers le même compute.

Coûts et durée de vie maximale​

Gardez les éléments suivants à l'esprit :

  • Pendant que le tunnel est en cours d'exécution, le compute reste en cours d'exécution et entraîne des coûts. Un cluster classique ne s'arrête pas automatiquement. Une session tmux inactive compte comme un processus détaché en cours d'exécution ; fermez-la donc lorsque vous n'en avez plus besoin.
  • L'exécution de job s'arrête toujours lorsqu'elle atteint la durée de vie maximale définie par --server-timeout, même si des processus détachés sont en cours d'exécution. Cette durée de vie commence au start de l'exécution du Job, et non au moment de la déconnexion du dernier client. Après l'arrêt de l'exécution du job, les processus détachés perdent leur accès à /Workspace et /Volumes. Sur le compute Serverless, les processus détachés s'arrêtent. Sur le compute classique, ils peuvent continuer à s'exécuter sans cet accès jusqu'à la fin du cluster. Pour conserver la sortie des travaux détachés de longue durée, enregistrez-la avec le SDK Databricks ou l'API REST au lieu de l'écrire dans les chemins /Workspace ou /Volumes. Voir Travailler avec des fichiers dans des volumes Unity Catalog.
  • Pour les travaux plus longs, utilisez plutôt des jobs ou des bundles.

Limites du tunnel SSH​

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

  • Les clusters partagés ne sont pas pris en charge.
  • 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 performance ou de connexion si trois notebooks Jupyter ou plus sont ouverts en même temps.

Comportement des notebooks dans les sessions SSH​

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épanner les connexions via tunnel SSH​

start par le symptôme qui correspond à l'échec :

Symptôme

Vérifiez d'abord

La connexion SSH échoue ou expire.

Vérifiez l'accès HTTPS et WebSocket au workspace. Pour le compute classique, vérifiez également l'état du cluster et le délai d'attente de l'IDE. Voir La connexion SSH échoue ou expire.

La CLI signale qu'elle ne peut pas trouver code.

Installez la commande shell Visual Studio Code dans votre PATH local. Voir La commande code est introuvable.

L'authentification CLI échoue.

Vérifiez le profil CLI et, pour le compute classique, les autorisations de cluster. Voir Erreurs d’authentification CLI.

La CLI rapporte invalid_grant avec Refresh token is invalid.

Reconnectez-vous au workspace en utilisant le même profil CLI, puis réessayez de vous connecter. Voir Le jeton refresh n’est pas valide.

Le code Python ou les notebooks échouent après la connexion.

Vérifiez l'interpréteur ou le kernel du notebook sélectionné. Voir Le code Python ou les Notebook échouent dans la session SSH.

Les fichiers disparaissent après un redémarrage du cluster.

Vérifiez si les fichiers ont été stockés sur un chemin local éphémère. Voir Les fichiers disparaissent ou l’environnement est réinitialisé après le redémarrage du cluster.

Symptôme

Vérifiez d'abord

La connexion SSH échoue ou expire.

Vérifiez l'accès HTTPS et WebSocket au workspace. Pour le compute classique, vérifiez également l'état du cluster et le délai d'attente de l'IDE. Voir La connexion SSH échoue ou expire.

La CLI signale qu'elle ne peut pas trouver code.

Installez la commande shell Visual Studio Code dans votre PATH local. Voir La commande code est introuvable.

L'authentification CLI échoue.

Vérifiez le profil CLI et, pour le compute classique, les autorisations de cluster. Voir Erreurs d’authentification CLI.

La CLI rapporte invalid_grant avec Refresh token is invalid.

Reconnectez-vous au workspace en utilisant le même profil CLI, puis réessayez de vous connecter. Voir Le jeton refresh n’est pas valide.

Le code Python ou les notebooks échouent après la connexion.

Vérifiez l'interpréteur ou le kernel du notebook sélectionné. Voir Le code Python ou les Notebook échouent dans la session SSH.

Les fichiers disparaissent après un redémarrage du cluster.

Vérifiez si les fichiers ont été stockés sur un chemin local éphémère. Voir Les fichiers disparaissent ou l’environnement est réinitialisé après le redémarrage du cluster.

La connexion SSH échoue ou expire​

  • Pour le compute classique, vérifiez que le cluster est en cours d'exécution dans l'interface utilisateur du workspace.
  • Vérifiez que votre réseau, votre VPN et votre pare-feu autorisent le trafic HTTPS et WebSocket vers votre domaine de workspace. Le tunnel SSH n’utilise pas le port 22. Il tunnelise tout le trafic via le même endpoint HTTPS que les autres commandes CLI de Databricks. Voir Configurer les règles de pare-feu de nom de domaine.
  • Si un proxy ou un pare-feu inspecte le trafic TLS, vérifiez qu’il autorise la demande de mise à niveau WebSocket. Un intermédiaire qui bloque ou supprime la mise à niveau entraîne l’échec ou l’expiration de la connexion. Demandez à votre administrateur réseau d’autoriser les mises à niveau WebSocket vers votre domaine de workspace, ou de contourner l’inspection TLS pour ce domaine.
  • Si vous vous connectez via un proxy HTTP d’entreprise, définissez la variable d’environnement HTTPS_PROXY, ou NO_PROXY pour contourner le proxy pour votre domaine de workspace. Le tunnel SSH utilise la même configuration de proxy que les autres commandes CLI de Databricks. Voir Configuration du serveur proxy.
  • Vérifiez que votre machine locale dispose d'un accès HTTPS à github.com et release-assets.githubusercontent.com.
  • 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 s'interrompre après 1 heure et pas plus de 10 connexions SSH peuvent être effectuées vers un seul cluster. Consultez les limitations des tunnels SSH.

Commande code 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​

  • Connectez-vous à votre Workspace à l'aide de databricks auth login.
  • Pour le compute classique, confirmez que vous disposez de l'autorisation CAN ATTACH TO sur le cluster, ou de CAN RESTART si le cluster n'est pas en cours d'exécution.

Le jeton refresh est non valide​

Si databricks ssh connect échoue avec error getting token, invalid_grant et Refresh token is invalid, le serveur d'autorisation a rejeté le jeton refresh OAuth enregistré par la CLI. Reconnectez-vous pour obtenir une nouvelle session :

  1. Identifiez le profil de configuration du workspace auquel vous souhaitez vous connecter :

    Bash
    databricks auth profiles --skip-validate

  2. Reconnectez-vous avec ce profil. Remplacez <workspace-url> par l’URL du workspace, sans le chemin /oidc/v1/token, et <profile-name> par le nom de profil correspondant :

    Bash
    databricks auth login --host <workspace-url> --profile <profile-name>

    Terminez le flux de connexion dans votre navigateur.

  3. Réessayez la connexion avec le même profil :

    Bash
    databricks ssh connect --ide vscode --profile <profile-name>

    Utilisez --ide cursor pour Cursor ou omettez --ide pour une session de terminal.

Si l'erreur persiste, vérifiez que la commande ayant échoué cible le même workspace et le même profil auquel vous venez de vous connecter. Consultez Authentification OAuth utilisateur à machine (U2M).

Le code Python ou les notebooks échouent dans la session SSH​

Les fichiers disparaissent ou l'environnement se réinitialise 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​

Le compute Serverless nécessite-t-il une configuration SSH ?​

N° Après avoir installé et authentifié la CLI Databricks, utilisez databricks ssh connect pour le compute serverless. La commande databricks ssh setup configure des entrées hôte SSH réutilisables pour le compute dédié classique.

Le tunnel SSH Databricks nécessite-t-il le port 22 ?​

Non. Le tunnel SSH transporte le trafic via HTTPS vers votre domaine de workspace et nécessite la prise en charge de WebSocket. Votre réseau, VPN, pare-feu et proxy doivent autoriser ce trafic. Consultez La connexion SSH échoue ou expire.

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, le noyau et l'exécution du code s'exécutent sur Databricks avec accès aux Ressources compute.

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

Le trafic SSH est chiffré de bout en bout et le code s’exécute sur le compute Databricks auquel vous êtes connecté. L’authentification utilise la CLI Databricks et votre profil de workspace configuré. Consultez Quelles méthodes d’authentification sont prises en charge ?.

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 via une configuration manuelle. Voir Comportement du notebook dans les sessions SSH.

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 de terminaison automatique courte sur votre cluster depuis l'interface utilisateur de Workspace. Une fois déconnecté, le tunnel SSH attend la période shutdown-delay (default : 10 minutes), puis le délai d’inactivité du cluster s’applique. Si vous utilisez --keep-detached-processes, le cluster ne s'arrête pas automatiquement pendant l'exécution de processus détachés. Cela s’applique également aux connexions sans le flag qui réutilisent un tunnel start avec celui-ci. Consultez Connexions à un tunnel existant.

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 sont les méthodes d’authentification 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