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

Túnel SSH do Databricks

info

Beta

O túnel SSH do Databricks está em versão Beta.

O túnel SSH Databricks permite que você conecte seu IDE ao seu compute Databricks . É fácil de configurar, permite executar e depurar código interativamente no cluster, reduz incompatibilidades de ambiente e mantém todo o código e dados seguros dentro do seu workspace Databricks .

Requisitos​

Para usar o túnel SSH, você precisa ter:

  • A versão 0.269 ou superior da CLI do Databricks deve estar instalada em sua máquina local e a autenticação deve estar configurada. Consulte Instalar.
  • Execute tarefas computacionais em seu workspace Databricks com o modo de acesso dedicado (usuário único). Consulte a Visão geral compute dedicada.
    • O compute deve estar utilizando Databricks Runtime 17.0 ou superior.
    • Unity Catalog precisa estar ativado.
    • Caso exista uma política compute , ela não deve proibir a execução de tarefas.

Configure o túnel SSH.​

Primeiro, configure o túnel SSH usando o comando ` databricks ssh setup` . Substitua <connection-name> pelo nome do túnel, por exemplo, my-tunnel.

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

A CLI solicita que você escolha um cluster, ou você pode fornecer um ID de cluster passando --cluster <cluster-id>.

nota

Para o IntelliJ, a Databricks recomenda que você inclua –-auto-start-cluster=false no comando de configuração. Ao iniciar um ambiente de desenvolvimento integrado (IDE) da JetBrains, todos clusters são iniciados automaticamente, o que pode resultar em custos compute não intencionais. Se você ativar essa opção, será necessário iniciar o cluster no workspace para iniciar o túnel SSH.

Conecte-se ao Databricks​

Em seguida, conecte-se ao Databricks usando uma IDE ou um terminal.

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.

  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. Na dropdown, selecione o túnel que você configurou na primeira etapa. O IDE inicia a conexão em uma nova janela.

nota

Se o compute não estiver em execução, ele será reiniciado. No entanto, se o tempo limite para o compute iniciar for maior que o limite definido, a tentativa de conexão SSH falhará.

  1. Selecione Linux quando solicitado o tipo de servidor.

Conecte-se usando o IntelliJ IDEs​

  1. Siga o tutorial de desenvolvimento remoto para configurar tudo.

  2. Na tela de nova conexão, insira o seguinte:

    Nome de usuário : root Hospedar: <connection-name>

Conecte-se usando o terminal​

Para conectar-se ao Databricks a partir da linha de comando, forneça ao comando ssh o nome da sua conexão, por exemplo:

Bash
ssh my-tunnel

Projetos abertos​

  1. A conexão inicial abre uma janela IDE vazia, sem nenhuma pasta aberta. No Visual Studio Code, use o comando Abrir Pasta na paleta de comandos para abrir o projeto desejado.
  2. Use o ponto de montagem workspace (/Workspace/Users/<your-username>) para armazenamento persistente.

código de execução (código do Visual Studio)​

  • Ao abrir um projeto Python, a extensão Python pode detectar automaticamente os ambientes virtuais, mas você ainda precisa ativar manualmente o ambiente correto. Selecione o comando Interpreter na paleta de comandos e escolha o ambiente pythonEnv-xxx. Isso dá acesso a toda a biblioteca integrada Databricks Runtime , ou a qualquer outra coisa que você tenha instalado globalmente no cluster.
  • Em alguns casos, a extensão Python não consegue detectar automaticamente ambientes virtuais (venv), como quando você abre uma pasta que não pode ser reconhecida como um projeto Python. Para corrigir isso, abra um terminal e execute echo $DATABRICKS_VIRTUAL_ENV, depois copie o caminho e use-o no comando Python: Selecionar Interpretador .

Após a seleção do ambiente virtual (venv), arquivos Python ou Notebooks podem ser executados com ações de execução normal ou de depuração fornecidas pelas extensões Python ou Jupyter.

Gerenciar dependências Python​

A maneira mais simples de instalar as dependências necessárias é usando a interface do usuário workspace . Veja biblioteca com escopo de computação. Com essa abordagem, você instala as dependências globalmente para o cluster. Não é necessário reinstalar a biblioteca sempre que o cluster for reiniciado.

No entanto, para uma configuração mais programática e específica para um projeto, utilize uma instalação com escopo de Notebook.

Notebook de configuração específico do projeto​

Para gerenciar as dependências de um projeto específico:

  1. Crie um arquivo setup.ipynb em seu projeto.

  2. A CLI ssh cria um ambiente Python (pythonEnv-xxx), que já possui biblioteca Databricks Runtime integrada ou biblioteca com escopo de computação. Anexe o Notebook a este ambiente pythonEnv-xxx .

  3. Use o comando %pip install para instalar suas dependências:

    • %pip install . se você tiver pyproject.toml (%pip install .<group> para reduzir o escopo)
    • %pip install -r dependencies.txt se você tiver dependencies.txt
    • %pip install /Volumes/your/wheel.whl (ou caminhos /Workspace ) se você criou e carregou uma biblioteca personalizada como um wheel.

    %pip O comando possui lógica específica Databrickscom proteções adicionais. A lógica também garante que as dependências estejam disponíveis para todos os nós executor Spark , e não apenas para o nó de driver ao qual você está conectado. Isso permite funções definidas pelo usuário (UDFs) com dependências personalizadas.

    Para mais exemplos de uso, consulte gerenciar biblioteca com %pip comando.

execute este Notebook sempre que você estabelecer uma nova sessão ssh. Não é necessário reinstalar as dependências se uma sessão SSH existente for encerrada e reconectada ao cluster em menos de 10 minutos. (O tempo pode ser configurado com a opção -shutdown-delay=10m na sua configuração SSH local.)

nota

Se você tiver várias sessões SSH conectadas ao mesmo cluster ao mesmo tempo, elas usarão o mesmo ambiente virtual.

Limitações​

O túnel SSH do Databricks apresenta as seguintes limitações:

  • A extensão Databricks para Visual Studio Code e o túnel SSH do Databricks ainda não são compatíveis e não devem ser usados em conjunto.
  • Qualquer pastaGit criada em seu workspace por meio da workspace Databricks não será reconhecida como um diretório Git pela CLI do Git e pelas integrações do Git em IDEs, pois essas pastas não possuem a extensão .git. metadados. Para contornar isso, consulte Como usar o Git com o túnel SSH?
  • Os pontos de montagem raiz e inicial no cluster ao qual você se conecta são efêmeros. O conteúdo presente no cluster não é preservado quando o cluster é reiniciado.

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

  • Certifique-se de que seu cluster esteja EM EXECUÇÃO na interface do usuário do Databricks e não apenas parado ou iniciando.
  • Verifique se a porta de saída 22 está aberta e permitida em seu laptop/rede/VPN.
  • Aumente o tempo limite de conexão SSH em sua IDE. Consulte Conectar usando o Visual Studio Code ou o Cursor.
  • Se você vir erros de incompatibilidade key pública ou privada, tente excluir a pasta ~/.databricks/ssh-tunnel-keys .
  • Se você vir erros "a identificação do host remoto foi alterada", verifique o arquivo ~/.ssh/known_hosts e exclua as entradas relacionadas ao seu cluster.
  • Se a sessão SSH for encerrada após 1 hora, trata-se de uma limitação conhecida. Consulte as limitações.
  • Não são permitidas mais de 10 conexões SSH em um único cluster.

erros de autenticação da CLI​

  • Confirme se o seu perfil do Databricks CLI é válido e autenticado (databricks auth login).
  • Certifique-se de ter as permissões de cluster adequadas, como CAN MANAGE.

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

  • Apenas as montagens /Workspace, /Volumes e /dbfs são persistentes. Todos os dados em /home, /root, etc. são apagados após uma reinicialização.
  • 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?

Erro "Não é um repositório git" ou recurso git ausente no IDE​

O Git só funciona se você clonar para /Workspace/Users/<your-username> usando o terminal. Pastas criadas na web não possuem a extensão .git. metadados. Veja Como usar o Git com o túnel SSH?

Meu código não funciona.​

  • Certifique-se de selecionar o interpretador Python correto que tenha acesso a todas as dependências do Databricks Runtime.

    • Ao abrir um projeto Python, a extensão Python pode detectar automaticamente os ambientes virtuais, mas você ainda precisa ativar manualmente o ambiente correto. Executar Python: Selecione o comando Interpreter e escolha o ambiente pythonEnv-xxx . Terá acesso a toda a biblioteca Databricks Runtime integrada, ou a qualquer outra coisa que você tenha instalado globalmente no cluster.
    • Em alguns casos, a extensão Python não consegue detectar automaticamente ambientes virtuais, como quando você abre uma pasta que não pode ser reconhecida como um projeto Python. Você pode abrir um terminal e executar echo $DATABRICKS_VIRTUAL_ENV, depois copiar o caminho e usá-lo no comando Python: Selecionar Interpretador .

  • Os notebooks ipynb e *.py Databricks têm acesso aos globais Databricks , mas os arquivos Python *.py não. Veja as diferenças entre os notebooksDatabricks.

Não consigo configurar uma conexão SSH no Windows usando o WSL.​

A Databricks recomenda realizar a configuração SSH diretamente no Windows. Se você configurar o SSH no WSL, mas usar uma versão do Visual Studio Code para Windows, ele não encontrará as configurações necessárias.

Perguntas frequentes​

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

Toda a execução de código ocorre dentro da sua cloud privada virtual (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, mas o túnel SSH do Databricks é compatível com qualquer IDE que possua recursos SSH.

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.

Vários usuários podem desenvolver no mesmo cluster simultaneamente?​

Não.

Meu cluster iniciará automaticamente quando eu me conectar via 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á.

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 as conexões de túnel SSH funcionem.

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.

Desconectar o SSH interrompe automaticamente meu cluster?​

Não, o servidor ssh tem um atraso de desligamento configurável e continuará a ser executado em segundo plano por um período de tempo especificado (10 minutos por default, pode ser alterado no ProxyCommand de configuração ssh modificando a opção -shutdown-delay ). Após o tempo limite, o servidor é encerrado, o que aciona o tempo limite do cluster Parado (que você configura durante a criação cluster ).

Como faço para interromper o cluster e evitar cobranças desnecessárias?​

Navegue até "Compution" na interface do usuário workspace Databricks , encontre seu cluster e clique em "Terminate " ou "Stop" .

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 a CLI do Databricks e seu arquivo de perfis ~/.databrickscfg . As chaves SSH são gerenciadas pelo túnel SSH do Databrick.

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.

Como faço para usar o Git com o túnel SSH?​

Atualmente, as pastas Git criadas usando a interface de usuário Databricks workspace não são reconhecidas como repositórios Git em IDEs. Para contornar isso, clone os repositórios usando a CLI do Git a partir da sua sessão SSH para a pasta do seu workspace persistente:

  1. Abra um terminal e navegue até o diretório pai desejado (por exemplo, cd /Workspace/Users/<your-username>).
  2. Clone seu repositório nesse diretório.
  3. No Visual Studio Code, abra esta pasta em uma nova janela executando code <repo-name> ou abra a pasta em uma nova janela usando a interface do usuário.