Tunnel SSH di Databricks

Il tunnel SSH di Databricks consente di connettere l'IDE al calcolo di Databricks. È semplice da configurare, consente di eseguire e fare il debug del codice in modo interattivo nel cluster, riduce le mancate corrispondenze dell'ambiente e mantiene tutto il codice e i dati protetti all'interno dell'area di lavoro di Databricks.

Requisiti

Per usare il tunnel SSH, è necessario disporre di:

• È necessario che la versione 0.269 o successiva dell'interfaccia a riga di comando (CLI) di Databricks sia installata sul tuo computer locale e che l'autenticazione sia configurata. Vedere Installare.
• Calcolo nell'area di lavoro di Databricks con modalità di accesso dedicata (utente singolo). Vedere Panoramica del calcolo dedicato.
  • Il calcolo deve usare Databricks Runtime 17.0 e versioni successive.
  • Il catalogo unity deve essere abilitato.
  • Se esiste una politica di calcolo, non deve vietare l'esecuzione dei processi.

Configurare il tunnel SSH

Prima di tutto, impostare il tunnel SSH utilizzando il comando databricks ssh setup. Sostituire <connection-name> con il nome del tunnel, my-tunnelad esempio .

databricks ssh setup --name <connection-name>

L'interfaccia della riga di comando richiede di scegliere un cluster oppure di specificare un ID cluster passando --cluster <cluster-id>.

Connettersi a Databricks

Connettersi quindi a Databricks usando un IDE o un terminale.

Connettersi utilizzando Visual Studio Code o Cursor

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

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. Nell'elenco a discesa selezionare il tunnel configurato nel primo passaggio. L'IDE procede per la connessione in una nuova finestra.

   Annotazioni

   Se il calcolo non è in esecuzione, verrà avviato. Tuttavia, se è necessario più tempo del timeout per l'avvio del calcolo, il tentativo di connessione SSH avrà esito negativo.

6. Selezionare Linux quando viene richiesto il tipo di server.

Connettersi con gli IDE IntelliJ

1. Segui la guida di sviluppo remoto per configurare.

2. Nella schermata nuova connessione immettere quanto segue:

   Nome utente: root<connection-name>

Connettersi tramite terminale

Per connettersi a Databricks dalla riga di comando, specificare il ssh nome della connessione, ad esempio:

ssh my-tunnel

Aprire progetti

1. La connessione iniziale apre una finestra IDE vuota senza alcuna cartella aperta. In Visual Studio Code usare il comando Apri cartella dal riquadro comandi per aprire un progetto desiderato.
2. Usare il mount dell'area di lavoro (/Workspace/Users/<your-username>) per l'archiviazione permanente.

Eseguire il codice (Visual Studio Code)

• Se si apre un progetto Python, l'estensione Python può rilevare automaticamente gli ambienti virtuali, ma è comunque necessario attivare manualmente quella corretta. Selezionare il comando Interprete dal riquadro comandi e scegliere l'ambiente pythonEnv-xxx. Questo ha accesso a tutte le librerie di Databricks Runtime predefinite o a qualsiasi elemento installato a livello globale nel cluster.
• In alcuni casi l'estensione Python non riesce a rilevare automaticamente gli ambienti virtuali (venv), ad esempio quando si apre una cartella che non può essere riconosciuta come progetto Python. Per risolvere questo problema, aprire un terminale ed eseguire echo $DATABRICKS_VIRTUAL_ENV, quindi copiare il percorso e usarlo nel comando Python: Select Interpreter (Python: Select Interpreter ).

Dopo aver selezionato venv, i file o i notebook Python possono essere eseguiti con azioni di esecuzione o debug normali fornite dalle estensioni Python o Jupyter.

Gestire le dipendenze Python

Il modo più semplice per installare le dipendenze necessarie consiste nell'usare l'interfaccia utente dell'area di lavoro. Vedere Librerie con ambito di calcolo. Con questo approccio, le dipendenze vengono installate a livello globale per il cluster. Non è necessario reinstallare le librerie ogni volta che il cluster viene riavviato.

Tuttavia, per un'installazione più programmatica specifica a un progetto, usare un'installazione con ambito notebook.

Notebook di installazione specifico del progetto

Per gestire le dipendenze per un progetto specifico:

1. Creare un setup.ipynb file nel progetto.

2. L'interfaccia della riga di comando ssh crea un ambiente Python (pythonEnv-xxx), che include già librerie di runtime di Databricks predefinite o librerie con ambito di calcolo. Collega il notebook a questo pythonEnv-xxx ambiente.

3. Usa i comandi %pip install per installare le dipendenze:

   • %pip install . se hai pyproject.toml (%pip install .<group> per restringere l'ambito)
   • %pip install -r dependencies.txt se avete dependencies.txt
   • %pip install /Volumes/your/wheel.whl (o /Workspace percorsi) se è stata creata e caricata una libreria personalizzata come rotellina

   %pip I comandi hanno una logica specifica di Databricks con protezioni aggiuntive. La logica garantisce anche che le dipendenze siano disponibili per tutti i nodi dell'executor Spark, non solo per il nodo driver a cui si è connessi. Ciò consente funzioni definite dall'utente con dipendenze personalizzate.

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

Eseguire questo notebook ogni volta che si stabilisce una nuova sessione SSH. Non è necessario reinstallare le dipendenze se una sessione SSH esistente viene eliminata e riconnessa al cluster in meno di 10 minuti. L'ora è configurabile con -shutdown-delay=10m l'opzione nella configurazione ssh locale.

Limitazioni

Il tunnel SSH di Databricks presenta le limitazioni seguenti:

• L'estensione Databricks per Visual Studio Code e il tunnel SSH di Databricks non sono ancora compatibili e non devono essere usate insieme.
• Qualsiasi cartella Git creata nell'area di lavoro tramite l'interfaccia utente dell'area di lavoro di Databricks non verrà riconosciuta come repository Git dall'interfaccia della riga di comando git e dalle integrazioni git dell'IDE, perché queste cartelle non dispongono di metadati .git. Per risolvere questo problema, vedere Come si usa Git con il tunnel SSH?
• I mount di home e root nel cluster a cui ci si connette sono effimeri. Qualsiasi contenuto nel cluster non viene mantenuto quando il cluster viene riavviato.

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à:
  • Databricks globals: 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

• Assicurati che il tuo cluster sia in ESECUZIONE nell'interfaccia utente di Databricks e non solo fermo o in fase di avvio.
• Controlla che la porta in uscita 22 sia aperta e consentita sul tuo laptop/rete/VPN.
• Aumentare il timeout della connessione SSH nell'IDE. Consulta Connettersi utilizzando Visual Studio Code o Cursor.
• Se vengono visualizzati errori di mancata corrispondenza della chiave pubblica o privata, provare a eliminare la ~/.databricks/ssh-tunnel-keys cartella.
• Se vengono visualizzati errori di "identificazione host remota modificata", controllare il ~/.ssh/known_hosts file ed eliminare le voci correlate al cluster.
• Se la sessione SSH viene eliminata dopo 1 ora, si tratta di una limitazione nota. Vedere Limitazioni.
• Non sono consentite più di 10 connessioni SSH a un singolo cluster.

Errori di autenticazione CLI

• Verificare che il profilo del CLI di Databricks sia valido e autenticato (databricks auth login).
• Assicurarsi di disporre delle autorizzazioni del cluster appropriate, ad esempio CAN MANAGE.

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

• Solo /Workspace, /Volumes e /dbfs montaggi sono persistenti. Tutti i dati in /home, /roote così via vengono cancellati dopo un 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?.

Errore "Non un repository Git" o funzionalità Git mancanti nell'IDE

Git funziona solo se si clona /Workspace/Users/<your-username> usando il terminale. Le cartelle create dal Web non hanno metadati .git. Vedere Come si usa Git con il tunnel SSH?

Il codice non funziona

• Assicurarsi di selezionare l'interprete Python corretto che abbia accesso a tutte le dipendenze di Databricks Runtime.
  • Se si apre un progetto Python, l'estensione Python può rilevare automaticamente gli ambienti virtuali, ma è comunque necessario attivare manualmente quella corretta. Esegui Python: selezionare il comando Interprete e scegliere pythonEnv-xxx environment (Ambiente pythonEnv-xxx ). Avrà accesso a tutte le librerie di Databricks Runtime predefinite o a qualsiasi elemento installato a livello globale nel cluster.
  • In alcuni casi l'estensione Python non riesce a rilevare automaticamente gli ambienti virtuali, ad esempio quando si apre una cartella che non può essere riconosciuta come progetto Python. È possibile aprire un terminale ed eseguire , quindi copiare il percorso e usarlo nel comando Python: Select Interpreter .You can open a terminal and execute echo $DATABRICKS_VIRTUAL_ENV, then copy the path and use it in the Python: Select Interpreter command.
• I notebook IPYNB e *.py i notebook di Databricks hanno accesso alle variabili globali di Databricks, ma i file Python *.py non ne hanno accesso. Vedere Differenze tra i notebook di Databricks.

Non è possibile configurare la connessione SSH in Windows in WSL

Databricks consiglia di eseguire l'installazione ssh direttamente in Windows. Se viene configurato sul lato WSL, ma si utilizza Visual Studio Code nella versione per Windows, non troverà le configurazioni ssh necessarie.

Domande frequenti

Come vengono protetti il codice e i dati?

Tutto il codice viene eseguito all'interno del cloud VPC (Virtual Private Cloud) 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, ma il tunnel SSH di Databricks è compatibile con qualsiasi IDE con funzionalità SSH.

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.

È possibile sviluppare più utenti nello stesso cluster contemporaneamente?

No

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

Sì, ma se l'avvio del cluster richiede più tempo rispetto al timeout della connessione, il tentativo di connessione avrà esito negativo.

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. Il cluster deve mostrare In esecuzione affinché le connessioni del tunnel SSH funzionino.

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.

La disconnessione di SSH arresta automaticamente il cluster?

No, il server SSH ha un ritardo di arresto configurabile e continuerà l'esecuzione in background per un periodo di tempo specificato (10m per impostazione predefinita, può essere modificato nell'opzione ssh config ProxyCommand modificando -shutdown-delay ). Dopo il timeout, il server si termina, e si attiva il timeout di inattività del cluster (che configuri durante la creazione del cluster).

Come interrompere il cluster per evitare addebiti non necessari?

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

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 di Databrick.

È 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.

Come si usa Git con il tunnel SSH?

Attualmente le cartelle Git create usando l'interfaccia utente dell'area di lavoro di Databricks non vengono riconosciute come repository Git negli IDE. Per risolvere questo problema, clonare i repository usando il CLI di git dalla sessione SSH nella cartella di lavoro persistente:

1. Aprire un terminale e passare alla directory padre desiderata (ad esempio, cd /Workspace/Users/<your-username>)
2. Clona il repository in tale directory.
3. In Visual Studio Code aprire questa cartella in una nuova finestra eseguendo code <repo-name> o aprendo la cartella in una nuova finestra usando l'interfaccia utente.