Connettersi a Databricks usando un tunnel SSH

Importante

Questa funzionalità è in versione beta.

Il tunnel SSH fornito da Databricks consente di accedere all'area di lavoro ed eseguire in modo interattivo i carichi di lavoro nelle risorse di calcolo di Databricks dagli IDE usando un tunnel SSH. È semplice configurare, eliminare la necessità di gestione dell'ambiente e mantenere tutto il codice e i dati protetti all'interno dell'area di lavoro di Databricks.

Requisiti

Per usare il tunnel SSH per connettersi al calcolo serverless o classico di Databricks, è necessario disporre di:

  • Databricks CLI versione 1.5.0 o successiva installato sul computer locale con autenticazione configurata. Consulta Installare o aggiornare la CLI di Databricks.
  • Uno dei seguenti:
    • Visual Studio Code versione: 1.110.0 (universale) o successiva e l'estensione Remote - SSH (1.0.46+) installata.
    • Versione di Cursor: 2.6.11 (Universal) o successiva.

Per connettersi al calcolo GPU serverless, è necessario abilitare la funzionalità Runtime di intelligenza artificiale. Vedi Runtime di intelligenza artificiale.

Per connettersi al calcolo classico (dedicato, utente singolo):

Collegarsi al calcolo serverless

Per connettersi all'elaborazione serverless, eseguire il comando databricks ssh connect nel terminale dell'IDE. Non è necessario alcun passaggio di configurazione separato.

Per altre informazioni sul databricks ssh connect comando, vedere ssh Gruppo di comandi.

databricks ssh connect

Usare l'opzione --accelerator per connettersi al runtime di intelligenza artificiale:

databricks ssh connect --accelerator=GPU_1xA10

databricks ssh connect offre una sessione interattiva in un singolo nodo. Per i processi di addestramento a esecuzione prolungata o per l'addestramento distribuito su più nodi, invia invece il carico di lavoro con la CLI air. Vedi AI Runtime CLI.

Dopo la connessione, completare la configurazione dell'ambiente di sviluppo. Vedere Open projects (Apri progetti).

Per connettersi all'ambiente di calcolo serverless e avviare la sessione in Visual Studio Code o Cursor, usa l'opzione --ide. La CLI apre una finestra dell'IDE sulla cartella home dell'area di lavoro.

databricks ssh connect --ide=vscode

Connettersi al calcolo classico

Per connettersi al calcolo classico, configurare prima di tutto la connessione SSH, quindi connettersi usando l'IDE o dal terminale.

Configurare la connessione SSH

Annotazioni

La configurazione della connessione SSH è necessaria solo se ci si connette al calcolo classico.

Prima di tutto, impostare il tunnel SSH utilizzando il comando databricks ssh setup. Specificare un nome per la connessione, ad esempio sostituire <connection-name> con my-connection:

databricks ssh setup --name <connection-name>

L'interfaccia della riga di comando richiede di selezionare un cluster. È anche possibile specificarne uno direttamente con --cluster <cluster-id>:

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

Annotazioni

Per gli utenti di IntelliJ, Databricks consiglia di aggiungere --auto-start-cluster=false al comando di installazione e avviare manualmente il cluster prima della connessione. Ciò è dovuto al fatto che gli IDE JetBrains avviano tutti i cluster configurati all'avvio, causando costi di calcolo imprevisti.

Connettersi utilizzando Visual Studio Code o Cursor

  1. Per Visual Studio Code, installare l'estensione Remote SSH. Il cursore include un'estensione SSH remota per impostazione predefinita.

  2. Nel menu principale dell'IDE fare clic su Visualizza>riquadro comandi. Selezionare Remote-SSH: Settings (Remote-SSH: Impostazioni). In alternativa, selezionare Preferenze: aprire Impostazioni utente (JSON) per modificare settings.json direttamente.

  3. In Remote.SSH: Estensioni predefinite (o remote.SSH.defaultExtensions in settings.json) aggiungere ms-Python.Python e ms-toolsai.jupyter.

    Se si sta modificando settings.json:

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

    Annotazioni

    Facoltativamente, aumentare il valore di Remote.SSH: Connect Timeout (o remote.SSH.connectTimeout in settings.json) per ridurre ulteriormente la probabilità di errori di timeout. Il timeout predefinito è 360.

  4. Nel riquadro comandi selezionare Remote-SSH: Connect to Host (Remote-SSH: Connetti all'host).

  5. Dal menu a discesa selezionare la connessione configurata nel primo passaggio. L'IDE procede per la connessione in una nuova finestra.

Connettersi con gli IDE IntelliJ

  1. Segui il tutorial sul server remoto per impostare.
  2. Nella nuova schermata di connessione immettere:
    • Nome utente: root
    • Host: <connection-name>

Connettersi tramite terminale

ssh <connection-name>

Aprire progetti

Per impostazione predefinita, il databricks ssh connect comando si apre in una directory temporanea. Per accedere ai file dell'area di lavoro, passare alla directory dell'area di lavoro dall'IDE o dal terminale:

  • In Visual Studio Code o Cursor, dalla Raccolta comandi (Cmd/Ctrl+Shift+P) seleziona Apri cartella e passa a /Workspace/Users/<your-username>.
  • In una finestra del terminale, cambia directory: cd /Workspace/Users/<your-username>.

Annotazioni

I file in /Workspace, /Volumese /dbfs vengono mantenuti tra i riavvii del cluster. I file in /home, /roote altri percorsi locali sono temporanei e persi al riavvio.

Esegui codice (Visual Studio Code o cursore)

Per eseguire il codice usando il tunnel SSH, è necessario configurare l'ambiente virtuale Databricks. Questo ambiente include tutte le librerie DBR predefinite e le librerie con ambito di calcolo.

  1. Aprire il riquadro comandi (CMD/CTRL+MAIUSC+P) e selezionare Python: Seleziona interprete.

  2. Selezionare l'ambiente pythonEnv-xxx virtuale dall'elenco. Se non viene visualizzato:

    1. Eseguire echo $DATABRICKS_VIRTUAL_ENV da un terminale all'interno dell'IDE.

      Output di esempio: /local_disk0/.ephemeral_nfs/envs/pythonEnv-xxx/bin/python

    2. Incolla l'output completo come percorso dell'interprete nel prompt Python: Seleziona interprete.

  3. Aprire un nuovo terminale e l'ambiente virtuale deve essere attivato automaticamente.

  4. Per eseguire un notebook Jupyter, assicurati che l'ambiente virtuale sia selezionato come *kernel*. Fare clic su Seleziona kernel in alto a destra del notebook.

Eseguire ed eseguire il debug di file Python e notebook .ipynb utilizzando le estensioni standard di Python e Jupyter.

Per usare Spark in un file Python nel serverless compute, inizializza esplicitamente una sessione:

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

Gestire le dipendenze Python

Gestire le dipendenze Python globalmente a livello di cluster o limitatamente a singoli progetti utilizzando i notebook.

Installare le dipendenze tramite l'interfaccia utente dell'area di lavoro in Librerie > di calcolo. Questi elementi vengono mantenuti tra i riavvii del cluster e sono disponibili in pythonEnv-xxx. Consultare Librerie cluster.

configurazione del notebook specifica di Project

Per le dipendenze con ambito progetto, eseguire un notebook contenente %pip install i comandi all'inizio di ogni sessione:

# 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 I comandi includono protezioni specifiche di Databricks e propagano le dipendenze ai nodi di esecuzione di Spark. Ciò consente funzioni definite dall'utente con dipendenze personalizzate.

Per altri esempi, vedere Gestire le librerie con %pip i comandi.

Non è necessario eseguire nuovamente il notebook se la sessione si riconnette entro 10 minuti. Questa operazione è configurabile usando -shutdown-delay nella configurazione SSH.

Annotazioni

Più sessioni SSH nello stesso cluster condividono un ambiente virtuale.

Limitazioni

Il tunnel SSH fornito da Databricks presenta le limitazioni seguenti:

  • I cluster condivisi non sono supportati.
  • L'estensione Databricks per Visual Studio Code e il tunnel SSH non sono ancora compatibili e non devono essere usate insieme.
  • I file modificati all'esterno di /Workspace, /Volumes e /dbfs vengono persi al riavvio del cluster.
  • È consentito un massimo di 10 connessioni SSH per ogni cluster.
  • Le sessioni inattive potrebbero scadere dopo 1 ora.
  • Il tunnel SSH non può essere avviato da altri ambienti remoti o da contenitori Docker.
  • È possibile che si verifichino problemi di prestazioni o connessione quando tre o più notebook jupyter sono aperti contemporaneamente. Questa limitazione verrà risolta in una versione futura.

Differenze tra notebook di Databricks

Esistono alcune differenze nei notebook quando si usa il tunnel SSH:

  • I file Python non definiscono nessuna globalità di Databricks (ad esempio spark o dbutils). È necessario importarli in modo esplicito con from databricks.sdk.runtime import spark.
  • Per i notebook ipynb, sono disponibili queste funzionalità:
    • Variabili globali di Databricks: display, displayHTML, dbutils, table, sql, udf, getArgument, sc, sqlContext, spark
    • %sql comando magico per eseguire le celle SQL

Per lavorare con i notebook sorgente Python:

  • Cercare jupyter.interactiveWindow.cellMarker.codeRegex e impostarlo su:

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

  • Cercare jupyter.interactiveWindow.cellMarker.default e impostarlo su:

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

Risoluzione dei problemi

Questa sezione contiene informazioni sulla risoluzione dei problemi comuni.

Connessione SSH non riuscita o timeout

  • Verificare che il cluster sia in esecuzione nell'interfaccia utente dell'area di lavoro.
  • Verificare che la porta in uscita 22 sia aperta e consentita nel computer portatile, nella rete e nella VPN.
  • Aumentare il timeout SSH. Consulta Connettersi utilizzando Visual Studio Code o Cursor.
  • Per gli errori di mancata corrispondenza delle chiavi, eliminare ~/.databricks/ssh-tunnel-keys ed eseguire databricks ssh setupdi nuovo .
  • Per gli errori di "identificazione host remota modificata", controllare il ~/.ssh/known_hosts file ed eliminare le voci correlate al cluster.
  • Le sessioni SSH possono essere interrotte dopo 1 ora e non è possibile stabilire più di 10 connessioni SSH a un singolo cluster. Vedere Limitazioni.

Comando code non trovato

Se viene visualizzato Error: exec: "code": executable file not found in $PATH, aprire il riquadro comandi (CMD/CTRL+MAIUSC+P), selezionare Comando shell: Installa il comando 'code' in PATH e riavviare l'IDE o la sessione del terminale.

Errori di autenticazione CLI

  • Verifica che il profilo CLI di Databricks sia valido utilizzando databricks auth login.
  • Verificare di disporre delle CAN MANAGE autorizzazioni per il cluster.

Il codice non funziona

I file scompaiono o reimpostano l'ambiente dopo il riavvio del cluster

  • I file nei montaggi /Workspace, /Volumes, e /dbfs persistono tra i riavvii del cluster. I file in /home, /roote altri percorsi locali sono temporanei e persi al riavvio.
  • Usare la gestione delle librerie cluster per le dipendenze persistenti. Automatizzare le reinstallazioni usando script init, se necessario. Consulta Che cosa sono gli script init?.

L'installazione di SSH non riesce in Windows (WSL)

Eseguire databricks ssh setup direttamente in Windows, non in WSL. L'istanza di Windows Visual Studio Code non riesce a trovare le configurazioni SSH create sul lato WSL.

Domande frequenti

In che modo il tunnel SSH è diverso da Databricks Connect?

Databricks Connect consente di scrivere codice usando le API Spark ed eseguirle in modalità remota nel calcolo di Databricks anziché nella sessione Spark locale. L'estensione databricks Visual Studio Code usa Databricks Connect per fornire il debug predefinito del codice utente in Databricks.

Il tunnel SSH consente di accedere all'area di lavoro dall'IDE e spostare l'intero ambiente di sviluppo nell'ambiente di calcolo, Python, kernel e tutte le esecuzioni in Databricks con accesso completo alle risorse di calcolo.

Come vengono protetti il codice e i dati?

Tutto il codice viene eseguito all'interno del cloud VPC di Databricks. Nessun dato o codice lascia l'ambiente sicuro. Il traffico SSH è completamente crittografato.

Quali IDE sono supportati?

Visual Studio Code e Cursor sono ufficialmente supportati. Qualsiasi IDE con funzionalità SSH è compatibile, ma vengono testati solo VS Code e Cursor.

Tutte le funzionalità del notebook di Databricks sono disponibili nell'IDE?

Alcune funzionalità, display()ad esempio , dbutilse %sql sono disponibili con limitazioni o configurazione manuale. Vedere Differenze tra i notebook di Databricks.

Il cluster verrà avviato automaticamente quando ci si connette usando il tunnel SSH?

Sì, ma se l'avvio del cluster richiede più tempo rispetto al timeout della connessione, il tentativo di connessione avrà esito negativo. Per evitare questo problema, aumentare il valore di Remote.SSH: Connetti timeout dal riquadro comandi (o remote.SSH.connectTimeout in settings.json) per ridurre ulteriormente la probabilità di errori di timeout.

Come posso sapere se il mio cluster è in esecuzione?

Passare a Calcolo nell'interfaccia utente dell'area di lavoro di Databricks e controllare lo stato del cluster. Per consentire il corretto funzionamento della connessione SSH, il cluster deve visualizzare Running.

Come si disconnette la sessione SSH/IDE?

È possibile disconnettere una sessione chiudendo la finestra dell'IDE, usando l'opzione Disconnetti nell'IDE, chiudendo il terminale SSH o eseguendo il exit comando nel terminale.

Come arrestare il cluster ed evitare addebiti quando non funziona?

Per arrestare immediatamente, terminate il cluster dall'interfaccia utente dell'area di lavoro. Passare a Calcolo nell'interfaccia utente dell'area di lavoro di Databricks, individuare il cluster e fare clic su Termina o Arresta.

Impostare un breve criterio di terminazione automatica nel cluster dall'interfaccia utente dell'area di lavoro. Dopo la disconnessione, il server SSH attende il shutdown-delay periodo (predefinito: 10 minuti), quindi si applica il timeout di inattività del cluster.

Come gestire le dipendenze persistenti?

Le dipendenze installate durante una sessione vengono perse dopo il riavvio del cluster. Usare l'archiviazione permanente (/Workspace/Users/<your-username>) per i requisiti e gli script di installazione. Usare librerie cluster o script init per l'automazione.

Quali metodi di autenticazione sono supportati?

L'autenticazione usa l'interfaccia della riga di comando di Databricks e il file dei profili ~/.databrickscfg. Le chiavi SSH vengono gestite dal tunnel SSH.

È possibile connettersi a database o servizi esterni dal cluster?

Sì, purché la rete del cluster consenta le connessioni in uscita e le librerie necessarie.

È possibile usare estensioni IDE aggiuntive?

La maggior parte delle estensioni funziona quando viene installata all'interno della sessione SSH remota, a seconda dell'IDE e del cluster. Visual Studio Code per impostazione predefinita non installa le estensioni locali in host remoti. È possibile installarli manualmente aprendo il pannello delle estensioni e abilitando le estensioni locali nell'host remoto. È anche possibile configurare Visual Studio Code per installare sempre determinate estensioni in modalità remota. Vedere Connettersi a Databricks.

Sì, tuttavia gli amministratori del workspace devono inserire nell'elenco consentito gli URL di Visual Studio Code e del marketplace delle estensioni di Cursor. Il computer locale deve anche avere la possibilità di accedere a Internet.

  • Last updated on