Pular para o conteúdo principal
Última atualização em

Conectar-se ao Databricks usando um túnel SSH

info

Beta

Este recurso está em Beta.

Os custos e preços dos recursos em beta estão sujeitos a alterações.

O túnel SSH fornecido pelo Databricks permite que você acesse seu workspace e execute cargas de trabalho interativamente no compute do Databricks a partir de IDEs usando um túnel SSH (Secure Shell). É simples de configurar, elimina a necessidade de gerenciamento de ambiente e mantém todo o código e dados seguros dentro do seu workspace do Databricks.

nota

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​

Para usar o túnel SSH para conectar-se ao Databricks serverless ou ao compute clássico, você deve ter:

  • Databricks CLI versão 1.5.0 ou superior instalada em sua máquina local e autenticação configurada. 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 do Cursor: 2.6.11 (Universal) ou acima.

Para se conectar ao compute de GPU serverless, o recurso AI Runtime deve ser habilitado. Consulte AI Runtime.

Para se conectar ao compute clássico (dedicado, de usuário único):

Conectar-se ao compute serverless​

Para se conectar ao compute serverless, execute o comando databricks ssh connect em um terminal dentro do seu IDE. Nenhuma etapa de configuração separada é necessária.

Para obter mais informações sobre o comando databricks ssh connect, consulte o ssh grupo de comando.

Bash
databricks ssh connect

Use a opção --accelerator para conectar ao AI Runtime:

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

Após conectar, conclua a configuração do seu ambiente de desenvolvimento. Consulte Projetos abertos.

Para conectar-se ao compute serverless e começar a sessão no Visual Studio Code ou no Cursor, use a opção --ide. A CLI abre uma janela do IDE apontando para a pasta inicial do workspace.

Bash
databricks ssh connect --ide=vscode

Conectar ao compute clássico​

Para conectar-se ao compute clássico, primeiro configure a conexão SSH e, em seguida, conecte-se usando seu IDE ou a partir do terminal.

Configure a conexão SSH.​

nota

A configuração da conexão SSH é necessária apenas se você estiver se conectando ao compute clássico.

Primeiro, configure o túnel SSH usando o comando databricks ssh setup. Forneça um nome para a conexão, por exemplo, substitua <connection-name> por my-connection:

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

A interface de linha de comando (CLI) solicita que você selecione um cluster. Você também pode especificar um diretamente com --cluster <cluster-id>:

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

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

  1. Para o Visual Studio Code, instale a extensão Remote SSH. O Cursor inclui uma extensão SSH remota por default.

  2. 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.json diretamente.

  3. Em Remote.SSH: extensões padrão (ou remote.SSH.defaultExtensions em settings.json), adicione ms-Python.Python e ms-toolsai.jupyter.

    Se você estiver modificando settings.json:

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

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.

  1. Na paleta de comandos, selecione Remote-SSH: Conectar ao host .

  2. 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​

  1. Siga o tutorial do servidor remoto para configurar tudo.
  2. Na tela de nova conexão, digite:
    • Nome de usuário : root
    • Hospedar : <connection-name>

Conecte-se usando o terminal​

Bash
ssh <connection-name>

Abrir projetos​

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

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.

código de execução (Visual Studio Code ou Cursor)​

Para executar código usando o túnel SSH, o ambiente virtual Databricks deve ser configurado. Este ambiente inclui todas as bibliotecas DBR integradas e bibliotecas com escopo de compute.

  1. Abra a Paleta de Comandos ( Cmd/Ctrl+Shift+P ) e selecione Python: Selecionar Interpretador .

  2. Selecione o ambiente virtual pythonEnv-xxx da 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:

    1. execução echo $DATABRICKS_VIRTUAL_ENV de um terminal dentro do IDE.

      Exemplo de saída: /local_disk0/.ephemeral_nfs/envs/pythonEnv-xxx/bin/python

    2. Cole a saída completa como o caminho do interpretador no prompt Python: Selecionar Interpretador .

  3. Abra um novo terminal e o ambiente virtual deverá ser ativado automaticamente.

  4. 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:

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

Gerenciar dependências​

Gerencie as dependências usando um ambiente base do workspace, bibliotecas de cluster, init scripts ou Notebooks, dependendo do seu tipo de compute e requisitos.

Ambientes base do Workspace (recomendado para Serverless e AI Runtime)​

nota

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 4 do ambiente Serverless ou abaixo para pré-configurar dependências do Python. Crie um ambiente base usando a interface do usuário do workspace ou o comando databricks environments create-workspace-base-environment da CLI do Databricks.

Especifique o ambiente usando a opção --base-environment ao conectar:

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

Para obter mais informações sobre os formatos aceitos, consulte conectar ssh do Databricks.

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:

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

Não é necessário executar o Notebook novamente se a sessão se reconectar em até 10 minutos. Isso pode ser configurado usando -shutdown-delay na sua configuração SSH.

nota

Várias sessões SSH no mesmo cluster compartilham um ambiente virtual.

Usando Git​

nota

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​

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, /Volumes e /dbfs sã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.
  • Podem surgir problemas de desempenho ou conexão quando três ou mais notebooks Jupyter estiverem abertos simultaneamente. Esta limitação será resolvida em uma versão futura.

Diferenças entre NotebooksDatabricks​

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 spark ou dbutils). Você deve importá-los explicitamente com from 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
    • %sql comando mágico para executar células SQL

Para trabalhar com o código-fonte Python “Notebook”:

  • Procure por jupyter.interactiveWindow.cellMarker.codeRegex e defina-o como:

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

  • Procure por jupyter.interactiveWindow.cellMarker.default e defina-o como:

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

Solução de problemas​

Esta seção contém informações sobre como resolver problemas comuns.

A conexão SSH falha ou expira.​

  • Verifique se o cluster está em execução na interface do usuário 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, ou NO_PROXY para 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.com e release-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-keys e reexecução databricks ssh setup.
  • Para erros de "identificação do host remoto alterada", verifique o arquivo ~/.ssh/known_hosts e exclua as entradas relacionadas ao seu cluster.
  • As sessões SSH podem cair após 1 hora e não mais de 10 conexões SSH podem ser feitas para um único cluster. Consulte Limitações.

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

erros de autenticação da CLI​

  • Confirme se o seu perfil do Databricks CLI é válido usando databricks auth login.
  • Confirme se você tem permissões CAN MANAGE no cluster.

Meu código não funciona.​

Os arquivos desaparecem ou o ambiente é redefinido após a reinicialização cluster .​

  • Os arquivos nos pontos de montagem /Workspace, /Volumes e /dbfs persistem mesmo após reinicializações do cluster. Os arquivos em /home, /root e 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​

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 acessar o workspace do seu IDE e move todo o seu ambiente de desenvolvimento para o compute — Python, kernel e todas as execuções rodam no Databricks com acesso total aos recursos de compute.

Como meu código e meus dados são protegidos?​

Toda a execução de código ocorre dentro da sua VPC cloud Databricks . Nenhum dado ou código sai do seu ambiente seguro. O tráfego SSH é totalmente criptografado.

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. Veja as diferenças entre os notebooksDatabricks.

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.

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.

Nesta página