Databricks Desenvolvimento Remoto

O Databricks Remote Development permite-lhe aceder ao seu espaço de trabalho e executar interativamente cargas de trabalho no processamento Databricks a partir de IDEs usando um túnel SSH. É simples de configurar, elimina a necessidade de gestão do ambiente e mantém todo o código e dados seguros dentro do seu espaço de trabalho Databricks.

Requerimentos

Para utilizar o Desenvolvimento Remoto, deve ter:

• Databricks CLI versão 0.269 ou superior instalada na sua máquina local e autenticação configurada. Consulte Instalar.
• Um cluster dedicado (de utilizador único) a executar Databricks Runtime 17.0 ou superior. Consulte Visão geral de computação dedicada. Além disso:
  • O Unity Catalog tem de estar ativado.
  • Se existir uma política de computação, não deve proibir a execução de tarefas.

Configurar a ligação SSH

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

databricks ssh setup --name <connection-name>

A CLI pede-te para selecionar um cluster. Também pode especificar um diretamente com:--cluster <cluster-id>

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

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 por padrão uma extensão remota SSH.

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. No menu suspenso, selecione a conexão que estabeleceu na primeira etapa. O IDE procede a ligar-se numa nova janela.

Liga-te usando IDEs IntelliJ

1. Segue o tutorial do servidor remoto para te configurares.
2. No novo ecrã de ligação, introduz:
   • Nome de utilizador: root
   • Anfitrião: <connection-name>

Liga-te usando terminal

ssh <connection-name>

Projetos em aberto

Depois de ligar, use Abrir Pasta da Paleta de Comandos e navegue até /Workspace/Users/<your-username>.

Executar código (Visual Studio Code ou Cursor)

Para executar código usando Desenvolvimento Remoto, é necessário garantir que o ambiente virtual do Databricks está configurado. Este ambiente inclui todas as bibliotecas DBR integradas e bibliotecas compute-scoped.

1. Executa echo $DATABRICKS_VIRTUAL_ENV a partir de um terminal dentro do IDE.

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

2. Abra a Paleta de Comandos e escolha Python: Selecionar Interpretador. Cole a saída acima.

3. Abre um novo terminal e o ambiente virtual deverá ativar-se automaticamente.

4. Para executar um notebook Jupyter, certifique-se de que o ambiente virtual está selecionado como kernel. Clique em Select Kernel no canto superior direito do caderno.

Ficheiros Python e notebooks .ipynb podem ser executados e debugados usando as extensões padrão Python e Jupyter.

Gerir dependências de Python

As dependências de Python podem ser geridas globalmente ao nível do cluster ou atribuídas a projetos individuais usando notebooks.

Bibliotecas de cluster (recomendado)

Instale dependências através da interface do espaço de trabalho em Compute > Libraries. Estas persistem mesmo após reinícios do cluster e estão disponíveis em pythonEnv-xxx. Veja Bibliotecas em cluster.

Configuração específica do notebook do projeto

Para dependências com âmbito de projeto, execute um caderno contendo %pip install comandos 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 os comandos incluem guardrails específicos do Databricks e propagam dependências para nós executores do Spark. Isto permite funções definidas pelo utilizador (UDFs) com dependências personalizadas.

Para mais exemplos, veja Gerir bibliotecas com %pip comandos.

Não precisas de voltar a executar o caderno se a sessão se reconectar dentro de 10 minutos. Isto é configurável usando -shutdown-delay na sua configuração SSH.

Limitações

O Databricks Remote Development apresenta as seguintes limitações:

• Clusters partilhados com múltiplos utilizadores e serverless ainda não são suportados.
• A extensão Databricks para Visual Studio Code e Remote Development ainda não é compatível e não deve ser usada em conjunto.
• Ficheiros editados fora de /Workspace, /Volumes e /dbfs são perdidos ao reiniciar o cluster.
• É permitido um máximo de 10 ligações SSH por cluster.
• As sessões inativas podem ser desligadas após uma hora.

Diferenças entre Databricks e Cadernos

Existem algumas diferenças nos laptops quando utiliza o Desenvolvimento Remoto.

• 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

• Verifica se o cluster está a correr na interface do workspace.
• Verifica se a porta de saída 22 está aberta e permitida no teu portátil, rede e VPN.
• Aumenta o tempo de espera do SSH. Veja Conectar-se com Visual Studio Code ou Cursor.
• Para erros de descorrespondência de chaves, apague ~/.databricks/ssh-tunnel-keys e volte a executar databricks ssh setup.
• Para erros de "a identificação remota do host foi alterada", verifique o ficheiro ~/.ssh/known_hosts e apague as entradas relacionadas com o cluster.
• As sessões SSH podem ser interrompidas após 1 hora e não podem ser feitas mais de 10 ligações SSH a um único cluster. Consulte Limitações.

Erros de autenticação CLI

• Confirme que o seu perfil de CLI Databricks é válido usando databricks auth login.
• Confirma que tens CAN MANAGE permissões no cluster.

O meu código não funciona

• Certifique-se de que configurou o ambiente virtual Databricks, veja Executar código (Visual Studio Code ou Cursor)
• 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.

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

• Ficheiros em pontos de montagem /Workspace, /Volumes e /dbfs persistem durante os reinícios do cluster. Ficheiros em /home, /root, e outros caminhos locais são efémeros e perdem-se ao reiniciar.
• 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?.

Configuração do SSH falha no Windows (WSL)

Executa databricks ssh setup diretamente no Windows, não dentro do WSL. A instância do Windows VS Code não consegue encontrar configurações SSH criadas do lado do WSL.

FAQ

Em que é que o Desenvolvimento Remoto difere do Databricks Connect?

O Databricks Connect permite-lhe escrever código usando APIs do Spark e executá-lo remotamente no processamento do Databricks em vez de na sessão local do Spark. A extensão Databricks Visual Studio Code utiliza o Databricks Connect para fornecer depuração integrada do código de utilizador no Databricks.

O Desenvolvimento Remoto permite-lhe aceder ao espaço de trabalho a partir do seu IDE e move todo o seu ambiente de desenvolvimento para o cluster — Python, kernel, e toda a execução corre em Databricks com acesso total aos recursos do cluster.

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

Todo o código corre dentro da tua VPC cloud Databricks. Nenhum dado ou código sai do seu ambiente seguro. O tráfego SSH está totalmente encriptado.

Que IDEs são suportados?

O Visual Studio Code e o Cursor são oficialmente suportados. Qualquer IDE com capacidades SSH é compatível, mas apenas o VS Code e o Cursor são testados.

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.

O meu cluster arranca automaticamente quando me ligo usando o túnel SSH?

Sim, mas se demorar mais a iniciar o cluster do que o tempo limite da ligação, a tentativa de ligação falha. Para evitar isto, aumente o valor do Remote.SSH: Conecte Timeout da paleta de comandos (ou remote.SSH.connectTimeout em settings.json) para reduzir ainda mais a possibilidade de erros de timeout.

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 a conexão SSH funcione.

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.

Como posso parar o cluster e evitar cobranças quando não estou a trabalhar?

Para parar imediatamente, termine o cluster a partir da interface de utilizador do workspace. Navegue até Computar na interface de trabalho do Databricks, encontre o seu cluster e clique em Terminar ou Parar.

Defina uma política curta de auto-terminação no seu cluster a partir da interface do espaço de trabalho. Depois de desligar, o servidor SSH espera pelo período shutdown-delay (padrão: 10 minutos), depois, aplica-se o tempo limite de inatividade do cluster.

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 Databrick Remote Development.

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.

O Remote Development suporta o Private Link?

Sim, no entanto, os administradores de workspace devem permitir listar URLs dos marketplaces de extensões VS Code e Cursor. As máquinas locais dos utilizadores também devem ter a capacidade de aceder à internet.