Conectar-se ao Databricks usando um túnel SSH
O túnel SSH (Secure Shell) do Databricks conecta o Visual Studio Code, o Cursor ou seu terminal ao workspace do Databricks e ao Databricks serverless, GPU serverless ou compute clássico. Use-o para editar arquivos de workspace e executar ou depurar scripts e notebooks Python, com seu ambiente Python e execução de código no compute remoto. Conecte-se diretamente ao compute serverless ou configure uma conexão SSH reutilizável com um cluster clássico dedicado.
O túnel SSH é para desenvolvimento orientado por IDE. Para executar agentes de código em um ambiente leve e isolado, consulte Databricks Sandbox. Para uma comparação entre os dois, consulte IDE conectado com SSH.
Requisitos
Começar a conexão SSH em sua máquina local. O túnel não pode ser iniciado de outro ambiente remoto ou de um contêiner do Docker.
Para se conectar ao compute serverless ou classic, você deve ter:
- A CLI do Databricks versão 1.5.0 ou acima está instalada em sua máquina local e a autenticação está configurada. Verifique a versão instalada com
databricks --version. Consulte Instalar ou atualizar a CLI do Databricks. - Qualquer um dos seguintes:
- Visual Studio Code versão 1.110.0 (Universal) ou acima e a extensão Remote - SSH (1.0.46+) instalada.
- Versão 2.6.11 do Cursor (Universal) ou acima.
Para se conectar ao compute de GPU serverless, o recurso AI Runtime deve ser habilitado. Consulte AI Runtime.
Requisitos adicionais para compute clássico
Para se conectar ao compute clássico (dedicado, de usuário único):
- O compute deve estar executando o Databricks Runtime 17.0 ou acima. Consulte a visão geral do compute dedicado.
- Unity Catalog precisa estar ativado.
- Caso exista uma política compute , ela não deve proibir a execução de tarefas.
- Ao usar Databricks Container Services para compute dedicado, sua Docker Image deve ter
openssh-serverinstalado.
Escolha uma conexão SSH
Use o método de conexão para o seu tipo de compute:
Compute | Método de conexão | Requisito de configuração |
|---|---|---|
computação sem servidor |
| Nenhum o passo de configuração de SSH separada. Adicione |
Compute de GPU serverless |
| Nenhum o passo de configuração de SSH separada. Adicione Para os aceleradores compatíveis, consulte |
Compute clássico dedicado e de usuário único | Execução Em seguida, começar a sessão SSH a partir do IDE ou execução | Selecione um cluster dedicado de usuário único que atenda aos requisitos de compute clássico. Clusters compartilhados não têm suporte. |
O túnel SSH e a extensão do Databricks IDE não são compatíveis e não devem ser usados juntos. Para uma comparação com o Databricks Connect e outras opções de desenvolvimento, consulte Conectar-se do seu IDE.
Conectar-se ao compute serverless
Ao cumprir os requisitos acima, execução databricks ssh connect em seu terminal ou IDE.
O valor --ide seleciona o editor a ser iniciado, independentemente do editor ou terminal a partir do qual você executa o comando.
- Visual Studio Code
- Cursor
- Terminal
databricks ssh connect --ide vscode
A CLI abre uma janela do Visual Studio Code conectada ao compute remoto.
databricks ssh connect --ide cursor
A CLI abre uma janela do Cursor conectada ao compute remoto.
databricks ssh connect
A CLI começa uma sessão SSH interativa.
Para opções de comando, incluindo conexões nomeadas e perfis de autenticação, consulte databricks ssh connect.
Após conectar, abra o projeto do seu workspace e selecione o ambiente Python. Se a conexão falhar, consulte Solucionar problemas de conexões de túnel SSH.
Conectar ao compute de GPU serverless com o Runtime de AI
Com o AI Runtime habilitado, adicione --accelerator para usar a compute de GPU:
databricks ssh connect --accelerator GPU_1xA10
databricks ssh connect gives you an interactive session on a single node. For long-running training jobs or multi-node distributed training, submit the workload with databricks air instead. See Use the Databricks CLI with AI Runtime.
Conectar ao compute clássico
Para uma conexão reutilizável a um cluster dedicado clássico, configure um host name SSH e, em seguida, selecione esse host em seu IDE ou conecte-se a partir de um terminal.
Configure a conexão SSH.
A configuração da conexão SSH é necessária apenas se você estiver se conectando ao compute clássico.
execução databricks ssh setup em sua máquina local. Substitua <connection-name> por um nome para esta conexão, como my-connection:
databricks ssh setup --name <connection-name>
A CLI pede que você selecione um cluster e adiciona uma entrada de host à sua configuração SSH. Você também pode selecionar um cluster diretamente. Substitua <cluster-id> pelo ID do seu cluster dedicado:
databricks ssh setup --name <connection-name> --cluster <cluster-id>
Para configurar por quanto tempo o servidor SSH espera depois que o último cliente se desconecta, adicione --shutdown-delay ao comando de configuração. O default é 10 minutos. Por exemplo, para definir um atraso de 30 minutos para conexões através desta entrada de host SSH:
databricks ssh setup --name <connection-name> --cluster <cluster-id> --shutdown-delay 30m
Para usuários do IntelliJ, a Databricks recomenda adicionar --auto-start-cluster=false ao comando de configuração e iniciar o cluster manualmente antes de conectar. Isso ocorre porque IDEs da JetBrains iniciam todos clusters configurados na inicialização, o que pode resultar em cobranças compute inesperadas.
Conecte-se usando o Visual Studio Code ou o cursor.
-
Para o Visual Studio Code, instale a extensão Remote SSH. O Cursor inclui uma extensão SSH remota por default.
-
No menu principal da IDE, clique em Exibir > Paleta de comandos . Selecione SSH remoto: Configurações . Alternativamente, selecione Preferências: Abrir configurações do usuário (JSON) para modificar
settings.jsondiretamente. -
Em Remote.SSH: extensões padrão (ou
remote.SSH.defaultExtensionsemsettings.json), adicionems-Python.Pythonems-toolsai.jupyter.Se você estiver modificando
settings.json:JSON"remote.SSH.defaultExtensions": [
"ms-Python.Python",
"ms-toolsai.jupyter"
]
Opcionalmente, aumente o valor de Remote.SSH: Connect Timeout (ou remote.SSH.connectTimeout em settings.json) para reduzir ainda mais a chance de erros de tempo limite. O tempo limite default é 360.
-
Na paleta de comandos, selecione Remote-SSH: Conectar ao host .
-
No menu suspenso, selecione a conexão que você configurou no primeiro passo. O IDE prossegue para se conectar em uma nova janela.
Conecte-se usando o IntelliJ IDEs
- Siga o tutorial do servidor remoto para configurar tudo.
- Na tela de nova conexão, digite:
- Nome de usuário :
root - Hospedar :
<connection-name>
- Nome de usuário :
Conectar-se ao compute clássico de um terminal
Use o nome da conexão que você configurou com databricks ssh setup:
ssh <connection-name>
Para uma conexão direta sem uma entrada de host SSH reutilizável, você pode também usar a CLI. Substitua <cluster-id> pelo ID do seu cluster dedicado:
databricks ssh connect --cluster <cluster-id>
Consulte databricks ssh connect.
Abrir projetos de workspace via SSH
Por default, o comando databricks ssh connect abre para um diretório efêmero. Para acessar arquivos do workspace, navegue até seu diretório de workspace a partir do IDE ou terminal:
- No Visual Studio Code ou Cursor, na Paleta de Comandos ( Cmd/Ctrl+Shift+P ) selecione Abrir Pasta e navegue até
/Workspace/Users/<your-username>. - De uma janela de terminal, altere seu diretório:
cd /Workspace/Users/<your-username>.
Os arquivos em /Workspace, /Volumes e /dbfs persistem após reinicializações do cluster. Os arquivos em /home, /root e outros caminhos locais são efêmeros e perdidos ao reiniciar.
Executar Python e notebooks na sessão SSH
Selecione o ambiente Python fornecido pela sua sessão SSH antes de executar o código. Para o compute clássico, esse ambiente inclui as bibliotecas integradas do Databricks Runtime e bibliotecas com escopo para compute.
-
Abra a Paleta de Comandos ( Cmd/Ctrl+Shift+P ) e selecione Python: Selecionar Interpretador .
-
Selecione o ambiente virtual
pythonEnv-xxxda lista. Se você configurar dependências Python usando o sinalizador--base-environment, selecione o nome do ambiente virtual mais longo na lista de opções. Se o ambiente virtual não aparecer:-
execução
echo $DATABRICKS_VIRTUAL_ENVde um terminal dentro do IDE.Exemplo de saída:
/local_disk0/.ephemeral_nfs/envs/pythonEnv-xxx/bin/python -
Cole a saída completa como o caminho do interpretador no prompt Python: Selecionar Interpretador .
-
-
Abra um novo terminal e o ambiente virtual deverá ser ativado automaticamente.
-
Para executar um Notebook Jupyter, certifique-se de que o ambiente virtual esteja selecionado como o kernel. Clique em Selecionar Kernel no canto superior direito do Notebook.
Execute e depure arquivos Python e notebooks .ipynb usando as extensões padrão do Python e do Jupyter.
Para usar o Spark em um arquivo Python no compute serverless, inicialize uma sessão explicitamente:
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.serverless().profile("DEFAULT").getOrCreate()
Gerenciar dependências para sessões SSH
Escolha o gerenciamento de dependência para seu tipo de compute:
- Para compute serverless, use um ambiente base de workspace com uma versão de ambiente serverless compatível.
- Para compute clássico, use bibliotecas de cluster para dependências que persistem após reinicializações.
- Para dependências com escopo para uma sessão de projeto, use um notebook de instalação.
Para pacotes que não são do Python, consulte Dependências que não são do Python.
Ambientes base do Workspace (recomendado para Serverless e AI Runtime)
Este recurso requer que a prévia **Serverless workspace base environment support in Jobs** esteja habilitada. Consulte Gerenciar prévias do Databricks.
Use um ambiente base do workspace com a versão de ambiente serverless 4 ou abaixo para pré-configurar as dependências Python. O túnel SSH não é compatível com --base-environment com a versão de ambiente serverless 5 ou acima. Crie um ambiente base usando a IU do workspace ou o comando da CLI do Databricks databricks environments create-workspace-base-environment.
Especifique o ambiente usando a opção --base-environment ao conectar:
databricks ssh connect --base-environment my-workspace-env
A opção --base-environment aceita um nome de exibição, um caminho YAML de workspace ou um ID de recurso. Você não pode combiná-lo com --cluster. Consulte databricks ssh connect.
Bibliotecas de clusters (recomendado para compute clássico)
Instale dependências usando a interface do usuário do Workspace em Compute > Bibliotecas . Eles persistem nas reinicializações do cluster e estão disponíveis em pythonEnv-xxx. Consulte Bibliotecas de clusters.
Dependências não Python
Para persistir dependências não Python, use um init script que instale os pacotes quando o compute começar. Opcionalmente, armazene os pacotes em um volume do Unity Catalog e referencie-os do init script. Consulte O que são init scripts?.
Configuração do Notebook específica do projeto
Para dependências no escopo do projeto, execute um Notebook contendo o comando %pip install no início de cada sessão:
# 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 O comando inclui as proteções específicas Databrickse propaga as dependências para os nós executor Spark . Isso permite funções definidas pelo usuário (UDFs) com dependências personalizadas.
Para mais exemplos, veja gerenciar biblioteca com %pip comando.
Você não precisa executar novamente o Notebook de configuração se se reconectar antes que o servidor SSH seja desligado. Por default, o servidor é desligado 10 minutos após o último cliente se desconectar. Para alterar esse atraso, use --shutdown-delay com o comando para o seu método de conexão:
- Para uma conexão de compute clássica reutilizável, defina o atraso com databricks ssh setup. A entrada de host SSH gerada aplica o atraso quando você se conecta do seu IDE ou execução
ssh <connection-name>. - Para uma conexão direta via CLI, defina o atraso com databricks ssh connect.
Várias sessões SSH no mesmo cluster compartilham um ambiente virtual.
Usar o Git em uma sessão SSH
Este recurso requer a visualização prévia **Suporte de CLI do Git para pastas Git** habilitada. Consulte Gerenciar prévias do Databricks.
Você pode usar o Git CLI no túnel SSH com pastas Git recém-criadas e as credenciais Git que você configurou no workspace do Databricks. Consulte Usar comandos do Git CLI.
Se a CLI solicitar credenciais em vez de buscá-las automaticamente, você deverá conectar seu provedor Git ao Databricks. Consulte Conecte seu provedor Git ao Databricks.
Limitações do túnel SSH
O túnel SSH fornecido pelo Databricks apresenta as seguintes limitações:
- Clusters compartilhados não têm suporte.
- A extensão de IDE do Databricks e o túnel SSH ainda não são compatíveis e não devem ser usados juntos.
- Os arquivos editados fora de
/Workspace,/Volumese/dbfssão perdidos na reinicialização do cluster. - É permitido um máximo de 10 conexões SSH por cluster.
- Sessões inativas podem ser encerradas após 1 hora.
- O túnel SSH não pode ser iniciado de outros ambientes remotos ou contêineres Docker.
- Você pode encontrar problemas de desempenho ou de conexão quando três ou mais notebooks Jupyter estão abertos simultaneamente.
Comportamento do notebook em sessões SSH
Existem algumas diferenças no Notebook ao usar o túnel SSH:
- Os arquivos Python não definem nenhuma variável global do Databricks (como
sparkoudbutils). Você deve importá-los explicitamente comfrom databricks.sdk.runtime import spark. - Para notebooks ipynb , estes recursos estão disponíveis:
- Valores globais do Databricks:
display,displayHTML,dbutils,table,sql,udf,getArgument,sc,sqlContext,spark %sqlcomando mágico para executar células SQL
- Valores globais do Databricks:
Para trabalhar com o código-fonte Python “Notebook”:
-
Procure por
jupyter.interactiveWindow.cellMarker.codeRegexe defina-o como:^# COMMAND ----------|^# Databricks notebook source|^(#\\s*%%|#\\s*\<codecell\\>|#\\s*In\\[\\d*?\\]|#\\s*In\\[ \\]) -
Procure por
jupyter.interactiveWindow.cellMarker.defaulte defina-o como:# COMMAND ----------
Solucionar problemas de conexões do túnel SSH
Comece com o sintoma que corresponde à falha:
Sintoma | Primeiro verifique |
|---|---|
A conexão SSH falha ou esgota o tempo limite. | Verifique o acesso HTTPS e WebSocket do workspace. Para o compute clássico, verifique também o estado do cluster e o tempo limite do IDE. Consulte Falha ou tempo limite na conexão SSH. |
A CLI informa que não é possível encontrar | Instale o comando shell do Visual Studio Code no seu |
A autenticação da CLI falha. | Verifique o perfil da CLI e, para compute clássica, as permissões de clusters. Consulte Erros de autenticação da CLI. |
A CLI informa | Entre novamente no Workspace usando o mesmo perfil da CLI e tente conectar novamente. Consulte O token refresh é inválido. |
O código Python ou os notebooks falham após a conexão. | Verifique o intérprete ou o kernel do notebook selecionado. Consulte O código Python ou os notebooks falham na sessão SSH. |
Os arquivos desaparecem após um reinício de cluster. | Verifique se os arquivos foram armazenados em um caminho local efêmero. Consulte Arquivos desaparecem ou o ambiente é Reset após o reinício do cluster. |
A conexão SSH falha ou expira
- Para o compute clássico, verifique se o cluster está sendo executado na IU do workspace.
- Verifique se sua rede, VPN e firewall permitem tráfego HTTPS e WebSocket para o seu domínio do workspace. O túnel SSH não usa a porta 22. Ele faz o túnel de todo o tráfego pelo mesmo endpoint HTTPS que outros comandos da CLI do Databricks. Consulte Configurar regras de firewall de nome de domínio.
- Se um proxy ou firewall inspecionar o tráfego TLS, verifique se ele permite a solicitação de upgrade de WebSocket. Um intermediário que bloqueia ou remove o upgrade faz com que a conexão falhe ou expire. Solicite ao administrador de rede que permita upgrades de WebSocket para o domínio do seu workspace ou que ignore a inspeção TLS para esse domínio.
- Se você se conectar por meio de um proxy HTTP corporativo, defina a variável de ambiente
HTTPS_PROXY, ouNO_PROXYpara ignorar o proxy para o seu domínio do workspace. O túnel SSH usa a mesma configuração de proxy que outros comandos da CLI do Databricks. Consulte a configuração do servidor proxy. - Verifique se sua máquina local tem acesso HTTPS a
github.comerelease-assets.githubusercontent.com. - Aumente o tempo limite do SSH. Consulte Conectar usando o Visual Studio Code ou o Cursor.
- Para erros de incompatibilidade key , exclua
~/.databricks/ssh-tunnel-keyse reexecuçãodatabricks ssh setup. - Para erros de "identificação do host remoto alterada", verifique o arquivo
~/.ssh/known_hostse exclua as entradas relacionadas ao seu cluster. - As sessões SSH podem cair após 1 hora e não mais que 10 conexões SSH podem ser feitas para um único cluster. Consulte Limitações do túnel SSH.
code comando não encontrado
Se vir Error: exec: "code": executable file not found in $PATH, abra a Paleta de Comandos ( Cmd/Ctrl+Shift+P ), selecione Comando do Shell: Instalar comando 'code' no PATH e reinicie sua sessão IDE ou terminal.
Quais métodos de autenticação CLI são suportados?
- Inscreva-se no seu workspace usando databricks auth login.
- Para o compute clássico, confirme se você tem permissões
CAN MANAGEno cluster.
O refresh token é inválido
Se databricks ssh connect falhar com error getting token, invalid_grant e Refresh token is invalid, o servidor de autorização rejeitou o token de refresh OAuth salvo da CLI. Entre novamente para obter uma nova sessão:
-
Identifique o perfil de configuração do workspace ao qual você deseja se conectar:
Bashdatabricks auth profiles --skip-validate -
Entre novamente usando esse perfil.
<workspace-url>Substitua pelo URL do workspace, sem o caminho/oidc/v1/tokene<profile-name>pelo nome do perfil correspondente:Bashdatabricks auth login --host <workspace-url> --profile <profile-name>Complete o fluxo de login em seu navegador.
-
Tente novamente a conexão com o mesmo perfil:
Bashdatabricks ssh connect --ide vscode --profile <profile-name>Use
--ide cursorpara Cursor, ou omita--idepara uma sessão de terminal.
Se o erro persistir, verifique se o comando com falha tem como alvo o mesmo workspace e perfil que você acabou de entrar. Consulte Autenticação de usuário para máquina (U2M) OAuth.
Código ou notebooks Python falham na sessão SSH
- Selecione o ambiente Python fornecido pela sessão SSH. Para um notebook, selecione esse ambiente como kernel. Consulte execução Python e Notebooks na sessão SSH.
- Os notebooks IPYNB e os notebooks
*.pyDatabricks têm acesso aos globais do Databricks, mas os arquivos Python*.pynão têm. Consulte Comportamento de Notebooks em sessões SSH.
Arquivos desaparecem ou o ambiente é Reset após a reinicialização dos clusters
- Os arquivos nos pontos de montagem
/Workspace,/Volumese/dbfspersistem mesmo após reinicializações do cluster. Os arquivos em/home,/roote outros caminhos locais são efêmeros e perdidos ao reiniciar. - Utilize o gerenciamento de bibliotecas cluster para dependências persistentes. Automatize reinstalações usando um script de inicialização, se necessário. Veja O que são scripts de inicialização?
A configuração SSH falha no Windows (WSL)
Execute databricks ssh setup diretamente no Windows, não dentro do WSL. A instância do Windows Visual Studio Code não consegue encontrar configurações SSH criadas no lado do WSL.
Perguntas frequentes
O compute serverless requer configuração SSH?
Não. Depois de instalar e autenticar a CLI do Databricks, use databricks ssh connect para compute serverless. O comando databricks ssh setup configura entradas de host SSH reutilizáveis para compute dedicado clássico.
O túnel SSH do Databricks requer a porta 22?
Não. O túnel SSH transporta tráfego sobre HTTPS para o domínio do seu workspace e requer suporte a WebSocket. Sua rede, VPN, firewall e proxy devem autorizar esse tráfego. Consulte A conexão SSH falha ou expira.
Qual a diferença entre o túnel SSH e o Databricks Connect?
Databricks Connect permite que você escreva código usando APIs Spark e o execute remotamente no compute Databricks , em vez de na sessão local Spark . A extensão Databricks para Visual Studio Code utiliza o Databricks Connect para fornecer depuração integrada do código do usuário no Databricks.
O túnel SSH permite que você acesse o workspace de seu IDE e move todo o seu ambiente de desenvolvimento para o compute. Python, o kernel e a execução de código são executados no Databricks com acesso aos recursos de compute.
Como meu código e meus dados são protegidos?
O tráfego SSH é criptografado de ponta a ponta e o código é executado no compute do Databricks ao qual você se conecta. A autenticação usa a CLI do Databricks e seu perfil de workspace configurado. Consulte Quais métodos de autenticação são compatíveis?.
Quais IDEs são suportadas?
O Visual Studio Code e o Cursor são oficialmente suportados. Qualquer IDE com recursos SSH é compatível, mas apenas o VS Code e o Cursor foram testados.
Todos os recursos Databricks Notebook estão disponíveis no IDE?
Alguns recursos, como display(), dbutils e %sql, estão disponíveis com limitações ou configuração manual. Consulte Comportamento do Notebooks em sessões SSH.
Meu cluster iniciará automaticamente quando eu me conectar usando o túnel SSH?
Sim, mas se a inicialização do cluster demorar mais do que o tempo limite de conexão, a tentativa de conexão falhará. Para evitar isso, aumente o valor de Remote.SSH: Connect Timeout na paleta de comandos (ou remote.SSH.connectTimeout em settings.json) para reduzir ainda mais a chance de erros de tempo limite.
Como posso saber se meu cluster está em execução?
Navegue até "Compution" na interface do usuário workspace Databricks e verifique o status do cluster. O cluster precisa mostrar "Em execução" para que a conexão SSH funcione.
Como faço para desconectar minha sessão SSH/IDE?
Você pode desconectar uma sessão fechando a janela do seu IDE, usando a opção Desconectar no seu IDE, fechando o terminal SSH ou executando o comando exit no terminal.
Como faço para desligar o cluster e evitar cobranças quando não estou trabalhando?
Para interromper imediatamente, encerre o cluster na interface do usuário workspace . Navegue até "Compution" na interface do usuário workspace Databricks , encontre seu cluster e clique em "Terminate " ou "Stop" .
Configure uma política de encerramento automático de curta duração no seu cluster a partir da interface do usuário workspace . Após a desconexão, o servidor SSH aguarda o período shutdown-delay (default: 10 minutos), então o tempo limite do parado do cluster é aplicado.
Como devo lidar com dependências persistentes?
As dependências instaladas durante uma sessão são perdidas após a reinicialização do cluster. Use armazenamento persistente (/Workspace/Users/<your-username>) para requisitos e scripts de configuração. Utilize a biblioteca cluster ou o script de inicialização para automação.
Quais métodos de autenticação são suportados?
A autenticação usa o Databricks CLI e seu arquivo de perfis ~/.databrickscfg. As chaves SSH são tratadas pelo túnel SSH.
Posso me conectar a bancos de dados ou serviços externos a partir do cluster?
Sim, desde que a sua rede cluster permita conexões de saída e você tenha a biblioteca necessária.
Posso usar extensões adicionais da IDE?
A maioria das extensões funciona quando instalada em sua sessão SSH remota, dependendo do seu IDE e cluster. Por default o Visual Studio Code não instala extensões locais em hosts remotos. Você pode instalá-las manualmente abrindo o painel de extensões e ativando suas extensões locais no host remoto. Você também pode configurar o Visual Studio Code para sempre instalar determinadas extensões remotamente. Consulte Conectar-se ao Databricks.
O túnel SSH oferece suporte ao Private Link?
Sim; no entanto, os administradores de workspace devem adicionar os URLs dos marketplaces de extensão do Visual Studio Code e Cursor à lista de permissões. Sua máquina local também deve ter a capacidade de acessar a internet.