Partilhar via

Túnel SSH do Databricks

Importante

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

O túnel SSH do Databricks permite-lhe ligar o seu IDE ao seu computador do Databricks. É simples de configurar, permite-lhe executar e depurar código de forma interativa no cluster, reduz incompatibilidades no ambiente e mantém todo o código e dados seguros dentro do seu espaço de trabalho Databricks.

Requerimentos

Para usar o túnel SSH, deve ter:

  • O CLI Databricks versão 0.269 ou superior instalado na sua máquina local e autenticação devidamente configurada. Consulte Instalar.
  • Calcule no seu espaço de trabalho Databricks com um modo de acesso dedicado (utilizador único). Consulte Visão geral de computação dedicada.
    • A computação deve estar a usar Databricks Runtime 17.0 ou superior.
    • O Unity Catalog tem de estar ativado.
    • Se existir uma política de computação, não deve proibir a execução de tarefas.

Montar o túnel SSH

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

databricks ssh setup --name <connection-name>

A CLI pede-lhe para escolher um cluster, ou pode fornecer um ID de cluster passando por --cluster <cluster-id>.

Observação

Para o IntelliJ, o Databricks recomenda que inclua –-auto-start-cluster=false no comando setup. Iniciar um IDE JetBrains inicia automaticamente todos os clusters, o que pode resultar em custos de computação não intencionais. Se definires esta opção, tens de iniciar o cluster no workspace para iniciar o túnel SSH.

Liga-te aos Databricks

De seguida, ligue-se aos Databricks usando um IDE ou terminal.

Liga-te usando Visual Studio Code ou Cursor

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

  2. No menu principal do IDE, clique em Ver>Paleta de Comandos. Selecione Remote-SSH: Definições. Alternativamente, selecione Preferências: Abrir Definições de Utilizador (JSON) para modificar settings.json diretamente.

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

    Se está a modificar settings.json:

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

    Observação

    Opcionalmente, aumente o valor do Remote.SSH: Tempo de Espera de Conexão (ou remote.SSH.connectTimeout em settings.json) para reduzir ainda mais a probabilidade de erros de timeout. O timeout padrão é 360.

  4. Na Paleta de Comandos, selecione Remote-SSH: Ligar ao Anfitrião.

  5. Na lista suspensa, selecione o túnel que configurou na primeira etapa. O IDE procede a ligar-se numa nova janela.

    Observação

    Se a computação não estiver em execução, será iniciada. No entanto, se demorar mais tempo do que o timeout para o cálculo começar, a tentativa de ligação SSH falhará.

  6. Selecione Linux quando solicitado para o tipo de servidor.

Liga-te usando IDEs IntelliJ

  1. Segue o tutorial de desenvolvimento remoto para te preparares.

  2. No novo ecrã de ligação, insira o seguinte:

    Nome de utilizador: rootAnfitrião:<connection-name>

Liga-te usando terminal

Para ligar aos Databricks a partir da linha de comandos, forneça ao ssh comando o nome da sua ligação, por exemplo:

ssh my-tunnel

Projetos em aberto

  1. A ligação inicial abre uma janela do IDE vazia sem qualquer pasta aberta. No Visual Studio Code, use o comando Abrir Pasta da paleta Command para abrir um projeto desejado.
  2. Use o ponto de montagem do espaço de trabalho (/Workspace/Users/<your-username>) para armazenamento persistente.

Executar código (Visual Studio Code)

  • Se abrir um projeto Python, a extensão Python pode detetar automaticamente ambientes virtuais, mas ainda precisa de ativar manualmente o correto. Selecione o comando Interpreter na paleta de comandos e escolha o ambiente pythonEnv-xxx. Isto tem acesso a todas as bibliotecas de tempo de execução Databricks incorporadas, ou a tudo o que tenha instalado globalmente no cluster.
  • Em alguns casos, a extensão Python não consegue detetar automaticamente ambientes virtuais (venv), como quando se abre uma pasta que não pode ser reconhecida como um projeto Python. Para resolver isto, abre um terminal e executa echo $DATABRICKS_VIRTUAL_ENV, depois copia o caminho e usa-o no comando Python: Select Interpreter .

Depois de selecionado o venv, os ficheiros ou cadernos Python podem ser executados com ações normais de execução ou depuração fornecidas pelas extensões Python ou Jupyter.

Gerir dependências de Python

A forma mais simples de instalar as dependências necessárias é usar a interface do workspace. Consulte Bibliotecas abrangidas por computação. Com esta abordagem, instala-se as dependências globalmente para o cluster. Não precisas de reinstalar bibliotecas sempre que o cluster é reiniciado.

No entanto, para uma configuração mais programática que esteja orientada para um projeto específico, use uma instalação com âmbito de caderno.

Caderno de configuração específico do projeto

Para gerir dependências para um projeto específico:

  1. Crie um setup.ipynb ficheiro no seu projeto.

  2. A CLI ssh cria um ambiente Python (pythonEnv-xxx), que já possui bibliotecas de Databricks em tempo de execução ou bibliotecas com âmbito computacional incorporadas. Liga o caderno a este pythonEnv-xxx ambiente.

  3. Use os comandos %pip install para instalar as suas dependências.

    • %pip install . Se tiver pyproject.toml (%pip install .<group> para limitar o âmbito)
    • %pip install -r dependencies.txt se tiver dependencies.txt
    • %pip install /Volumes/your/wheel.whl (ou /Workspace caminhos) se construíste e carregaste uma biblioteca personalizada como uma roda

    %pip os comandos têm lógica específica para Databricks com mecanismos de segurança adicionais. A lógica também garante que as dependências estão disponíveis para todos os nós executores do Spark, não apenas para o nó driver ao qual está ligado. Isto permite funções definidas pelo utilizador (UDFs) com dependências personalizadas.

    Para mais exemplos de utilização, veja Gerir bibliotecas com %pip comandos.

Executa este caderno sempre que estabeleceres uma nova sessão de SSH. Não precisas de reinstalar dependências se uma sessão SSH existente for cortada e religada ao cluster em menos de 10 minutos. (A hora é configurável com a opção -shutdown-delay=10m na sua configuração local de SSH.)

Observação

Se tiveres várias sessões SSH ligadas ao mesmo cluster ao mesmo tempo, elas usam o mesmo ambiente virtual.

Limitações

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

  • A extensão Databricks para Visual Studio Code e o túnel SSH Databricks ainda não são compatíveis e não devem ser usados em conjunto.
  • Qualquer pasta Git que tenha criado no seu espaço de trabalho através da interface do espaço de trabalho Databricks não será reconhecida como repositório git pelas integrações git CLI e IDE, pois estas pastas não têm metadados .git. Para contornar isto, veja Como uso o Git com o Túnel SSH?
  • Os suportes de origem e raiz no cluster a que se liga são efémeros. Qualquer conteúdo no cluster não é preservado quando o cluster é reiniciado.

Diferenças entre Databricks e Cadernos

Existem algumas diferenças nos notebooks ao usar o túnel SSH:

  • Os ficheiros Python não definem os globais do Databricks (como spark ou dbutils). Deve importá-los explicitamente com from databricks.sdk.runtime import spark.
  • Para cadernos ipynb, estas funcionalidades estão disponíveis:
    • Databricks globais: display, displayHTML, dbutils, table, sql, udf, getArgument, sc, sqlContext, spark
    • %sql comando mágico para executar células SQL

Para trabalhar com "notebooks" de fonte em Python:

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

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

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

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

Solução de problemas

Esta secção contém informações sobre como resolver questões comuns.

Ligação SSH falha ou expira

  • Certifique-se de que o seu cluster está a correr na interface do Databricks e não simplesmente parado ou a iniciar.
  • Verifica se a porta de saída 22 está aberta e permitida no teu portátil/rede/VPN.
  • Aumenta o timeout da ligação SSH no teu IDE. Veja Conectar-se com Visual Studio Code ou Cursor.
  • Se vires erros de descorrespondência de chave pública ou privada, tenta apagar a ~/.databricks/ssh-tunnel-keys pasta.
  • Se vires erros de "identificação remota do host alterada", verifica o ~/.ssh/known_hosts ficheiro e elimina as entradas relacionadas com o teu cluster.
  • Se a sessão SSH for interrompida após 1 hora, esta é uma limitação conhecida. Consulte Limitações.
  • Não são permitidas mais de 10 ligações ssh num único cluster.

Erros de autenticação CLI

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

Ficheiros desaparecem ou o ambiente reinicia após o reinício do cluster

  • Apenas /Workspace, /Volumes e /dbfs montagens são persistentes. Todos os dados em /home, /root, etc. são apagados após um reinício.
  • Use a gestão de bibliotecas de cluster para dependências persistentes. Automatiza reinstalações usando scripts de init se necessário. Consulte O que são scripts init?.

Erro "Não é um repositório git" ou funcionalidades git em falta no IDE

O Git só funciona se clonarem em /Workspace/Users/<your-username> usando o terminal. Pastas criadas na web não têm metadados .git. Vê Como uso o Git com o Túnel SSH?

O meu código não funciona

  • Certifica-te de que escolhes o interpretador Python certo que tenha acesso a todas as dependências do Databricks em tempo de execução.
    • Se abrir um projeto Python, a extensão Python pode detetar automaticamente ambientes virtuais, mas ainda precisa de ativar manualmente o correto. Executar Python: Selecione o comando Interpreter e escolha o ambiente pythonEnv-xxx . Terá acesso a todas as bibliotecas de Runtime do Databricks incorporadas, ou a tudo o que tenha instalado globalmente no cluster.
    • Em alguns casos, a extensão Python não consegue detetar automaticamente ambientes virtuais, como quando se abre uma pasta que não pode ser reconhecida como um projeto Python. Podes abrir um terminal e executar echo $DATABRICKS_VIRTUAL_ENV, depois copiar o caminho e usá-lo no comando Python: Select Interpreter .
  • Os cadernos IPYNB e *.py Databricks têm acesso às variáveis globais do Databricks, mas os ficheiros Python *.py não têm. Ver diferenças nos Databricks Notebooks.

Não consigo configurar a ligação SSH no Windows sob WSL

O Databricks recomenda realizar a configuração do SSH diretamente no Windows. Se o configuraste no lado do WSL, mas depois usares a versão para Windows do Visual Studio Code, não conseguirá encontrar as configurações SSH necessárias.

FAQ

Como é que o meu código e dados estão protegidos?

Todo o código corre dentro da sua nuvem privada virtual Databricks (VPC). Nenhum dado ou código sai do seu ambiente seguro. O tráfego SSH está totalmente encriptado.

Que IDEs são suportados?

Visual Studio Code e Cursor são oficialmente suportados, mas o túnel SSH Databricks é compatível com qualquer IDE com capacidades SSH.

Todas as funcionalidades dos notebooks Databricks estão disponíveis no IDE?

Algumas funcionalidades como display(), dbutils, e %sql estão disponíveis com limitações ou configuração manual. Ver diferenças nos Databricks Notebooks.

Podem vários utilizadores desenvolver-se no mesmo cluster ao mesmo tempo?

Não.

O meu cluster vai arrancar automaticamente quando me ligar via SSH Tunnel?

Sim, mas se demorar mais a iniciar o cluster do que o tempo limite da ligação, a tentativa de ligação falha.

Como sei se o meu cluster está a funcionar?

Navega até Computar na interface do espaço de trabalho Databricks e verifica o estado do cluster. O cluster tem de mostrar Em execução para que as ligações SSH ao túnel funcionem.

Como posso desligar a minha sessão de SSH/IDE?

Podes desligar uma sessão fechando a janela do IDE, usando a opção Desligar no teu IDE, fechando o terminal SSH ou executando o exit comando no terminal.

Desconectar o SSH interrompe automaticamente o funcionamento do meu cluster?

Não, o servidor ssh tem um atraso de desligamento configurável e continuará a funcionar em segundo plano durante um período de tempo especificado (10 minutos por defeito, podendo ser alterado no ProxyCommand das configurações ssh ao modificar a opção -shutdown-delay). Após o timeout, o servidor termina, o que inicia o timeout de inatividade do cluster (que se configura durante a criação do cluster).

Como posso parar o cluster para evitar cobranças desnecessárias?

Navegue até Computar na interface de trabalho do Databricks, encontre o seu cluster e clique em Terminar ou Parar.

Como devo lidar com dependências persistentes?

As dependências instaladas durante uma sessão são perdidas após o reinício do cluster. Use armazenamento persistente (/Workspace/Users/<your-username>) para requisitos e scripts de configuração. Use bibliotecas de cluster ou scripts de init para automação.

Que métodos de autenticação são suportados?

A autenticação utiliza a CLI Databricks e o ficheiro dos seus ~/.databrickscfg perfis. As chaves SSH são tratadas pelo túnel SSH Databrick.

Posso ligar-me a bases de dados ou serviços externos a partir do cluster?

Sim, desde que a tua rede de cluster permita ligações de saída e tenhas as bibliotecas necessárias.

Posso usar extensões adicionais do IDE?

A maioria das extensões funciona quando instalada dentro da tua sessão remota de SSH, dependendo do teu IDE e cluster. O Visual Studio Code, por defeito, não instala extensões locais em hosts remotos. Pode instalá-las manualmente abrindo o painel de extensões e ativando as extensões locais no host remoto. Também podes configurar o Visual Studio Code para instalar sempre certas extensões remotamente. Ver Conectar ao Databricks.

Como uso o Git com o Túnel SSH?

Atualmente, pastas Git criadas usando a interface do espaço de trabalho Databricks não são reconhecidas como repositórios git nos IDEs. Para contornar isto, clone repositórios usando o git CLI da sua sessão SSH para a sua pasta de trabalho persistente.

  1. Abra um terminal e navegue até ao diretório pai desejado (por exemplo, cd /Workspace/Users/<your-username>)
  2. Clona o teu repositório nesse diretório.
  3. No Visual Studio Code, abra esta pasta numa nova janela executando code <repo-name> ou abra a pasta numa nova janela usando a interface.
  • Last updated on