Desenvolvimento Remoto com Databricks

O Desenvolvimento Remoto do Databricks permite que você acesse seu workspace e execute cargas de trabalho interativamente a partir de IDEs, utilizando um túnel SSH para comunicação com a computação do Databricks. É simples de configurar, elimina a necessidade de gerenciamento de ambiente e mantém todo o código e dados seguros em seu workspace do Databricks.

Requirements

Para usar o Desenvolvimento Remoto, você deve ter:

• CLI do Databricks versão 0.269 ou superior instalada em seu computador local e autenticação configurada. Consulte Instalar.
• Um cluster dedicado (de usuário único) executando o Databricks Runtime 17.0 ou superior. Confira a visão geral da computação dedicada. Além disso:
  • O Catálogo do Unity deve estar habilitado.
  • Se houver uma política de computação, ela não deverá proibir a execução de trabalhos.

Configurar a conexão SSH

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

databricks ssh setup --name <connection-name>

A CLI solicita que você selecione um cluster. Você também pode especificar um diretamente com --cluster <cluster-id>:

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

Conectar-se ao Databricks

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

Conectar usando o Visual Studio Code ou o Cursor

1. Para o Visual Studio Code, instale a extensão SSH Remota. O cursor inclui uma extensão SSH remota por padrão.

2. No menu principal do IDE, clique em Exibir>Paleta de Comandos. Selecione Remote-SSH: Configurações. Como alternativa, 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 in settings.json), adicione ms-Python.Python e ms-toolsai.jupyter.

   Se você estiver modificando settings.json:

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

   Observação

   Opcionalmente, aumente o valor de Remote.SSH: Connect Timeout (ou remote.SSH.connectTimeout em settings.json) para minimizar ainda mais a possibilidade de erros de tempo limite. O tempo limite padrão é 360.

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

5. Na lista suspensa, selecione a conexão que você configurou na primeira etapa. O IDE continua a se conectar em uma nova janela.

Conectar usando IDEs do IntelliJ

1. Siga o tutorial do servidor remoto para ser configurado.
2. Na nova tela de conexão, insira:
   • Nome de utilizador: root
   • Host: <connection-name>

Conectar-se usando o terminal

ssh <connection-name>

Abrir projetos

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

Executar código ( Visual Studio Code ou Cursor)

Para executar o código usando o Desenvolvimento Remoto, você precisa garantir que o ambiente virtual do Databricks esteja configurado. Esse ambiente inclui todas as bibliotecas integradas do DBR e bibliotecas com escopo de computação definido.

1. Execute echo $DATABRICKS_VIRTUAL_ENV em 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: Selecione Interpretador. Cole a saída acima.

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

4. Para executar um jupyter notebook, verifique se o ambiente virtual está selecionado como o kernel. Clique em Selecionar Kernel no canto superior direito do bloco de anotações.

Arquivos Python e .ipynb notebooks podem ser executados e depurados usando as extensões padrão de Python e Jupyter.

Gerenciar dependências do Python

As dependências do Python podem ser gerenciadas globalmente no nível do cluster ou em âmbito de projetos individuais usando notebooks.

Bibliotecas de cluster (recomendado)

Instale dependências por meio da interface do usuário do workspace em Bibliotecas de Computação.> Elas persistem entre reinicializações de cluster e estão disponíveis em pythonEnv-xxx. Consulte bibliotecas de cluster.

Configuração específica de notebook do Project

Para dependências com escopo de projeto, é necessário executar um notebook que contém os comandos %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 os comandos incluem guardrails específicos do Databricks e propagam dependências para os nós executores do Spark. Isso permite UDFs (funções definidas pelo usuário) com dependências personalizadas.

Para obter mais exemplos, consulte Gerenciar bibliotecas com %pip comandos.

Você não precisará executar novamente o notebook se a sessão se reconectar dentro de 10 minutos. Isso é configurável usando -shutdown-delay na sua configuração de SSH.

Limitações

O Desenvolvimento Remoto do Databricks tem as seguintes limitações:

• Ainda não há suporte para clusters compartilhados com vários usuários e sem servidor.
• A extensão Databricks para Visual Studio Code e Desenvolvimento Remoto ainda não é compatível e não deve ser usada em conjunto.
• Arquivos editados fora de /Workspace, /Volumes e /dbfs são perdidos na reinicialização do cluster.
• No máximo 10 conexões SSH são permitidas por cluster.
• Sessões inativas podem ser encerradas após 1 hora.

Diferenças do Databricks Notebooks

Há algumas diferenças nos notebooks ao usar o Desenvolvimento Remoto:

• Os arquivos Python não definem nenhum global do Databricks (como spark ou dbutils). Você deve importá-los explicitamente com from databricks.sdk.runtime import spark.
• Para notebooks ipynb, esses recursos estão disponíveis:
  • Databricks globals: display, displayHTML, dbutils, table, sql, udf, getArgument, sc, sqlContext, spark
  • %sql comando mágico para executar células SQL

Para trabalhar com "notebooks" de origem do Python:

• Pesquise por jupyter.interactiveWindow.cellMarker.codeRegex e defina como:

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

• Pesquise por jupyter.interactiveWindow.cellMarker.default e defina como:

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

Resoluçã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 workspace.
• Verifique se a porta de saída 22 está aberta e permitida em seu laptop, rede e VPN.
• Aumente o tempo limite do SSH. Consulte Conectar usando o Visual Studio Code ou o Cursor.
• Para erros de incompatibilidade de chave, exclua ~/.databricks/ssh-tunnel-keys e execute novamente databricks ssh setup.
• Para erros de "identificação do host remoto mudou", verifique o arquivo ~/.ssh/known_hosts e remova as entradas relacionadas ao seu cluster.
• As sessões SSH podem ser suspensas após 1 hora e não mais do que 10 conexões SSH podem ser feitas em um único cluster. Confira Limitações.

Erros de autenticação da CLI

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

Meu código não funciona

• Verifique se você configurou o ambiente virtual do Databricks, consulte Run code (Visual Studio Code ou Cursor)
• Notebooks do IPYNB e do Databricks têm acesso às variáveis globais do Databricks, mas os arquivos Python não. Confira as diferenças do Databricks Notebooks.

Arquivos desaparecem ou ambiente redefine após a reinicialização do cluster

• Os arquivos em /Workspace, /Volumes, e /dbfs montagens persistem entre reinicializações do cluster. Os arquivos em /home, /roote outros caminhos locais são efêmeros e perdidos na reinicialização.
• Use o gerenciamento de biblioteca de cluster para dependências persistentes. Automatize reinstalações usando scripts de inicialização, se necessário. Confira O que são scripts de inicialização?.

Falha na instalação do SSH no Windows (WSL)

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

perguntas frequentes

Como o Desenvolvimento Remoto é diferente do Databricks Connect?

O Databricks Connect permite escrever código usando APIs do Spark e executá-las remotamente na computação do Databricks em vez de na sessão do Spark local. A extensão do Databricks Visual Studio Code usa o Databricks Connect para fornecer depuração integrada do código do usuário no Databricks.

O Desenvolvimento Remoto permite que você acesse o workspace do seu IDE e mova todo o ambiente de desenvolvimento para o cluster — Python, kernel e todas as execuções no Databricks com acesso total aos recursos do cluster.

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

Todo o código é executado em seu VPC de nuvem do Databricks. Nenhum dado ou código deixa seu ambiente seguro. O tráfego SSH é totalmente criptografado.

Quais IDEs têm suporte?

Visual Studio Code e Cursor têm suporte oficial. Qualquer IDE com funcionalidades SSH é compatível, mas apenas o VS Code e o Cursor são testados.

Todos os recursos do notebook do Databricks estão disponíveis no IDE?

Alguns recursos, como display(), dbutilse %sql estão disponíveis com limitações ou configuração manual. Confira as diferenças do Databricks Notebooks.

Meu cluster será iniciado automaticamente quando eu me conectar usando o túnel SSH?

Sim, mas se levar mais tempo para iniciar o cluster do que o tempo limite de conexão, a tentativa de conexão falhará. Para evitar isso, aumente o valor de Remote.SSH: Timeout de Conexão na Command Palette (ou remote.SSH.connectTimeout em settings.json), reduzindo ainda mais a chance de erros de timeout.

Como saber se meu cluster está em execução?

Navegue até Computação na interface do usuário do workspace Databricks e verifique o status do cluster. O cluster deve mostrar Executando 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 IDE, usando a opção Desconectar em seu IDE, fechando seu terminal SSH ou executando o exit comando no terminal.

Como faço para parar o cluster e evitar custos quando não estou trabalhando?

Para parar imediatamente, encerre o cluster na interface do usuário do espaço de trabalho. Navegue até Computação na interface do usuário do Databricks, localize o cluster e clique em Encerrar Cluster ou Parar Cluster.

Defina uma política de terminação automática curta em seu cluster da interface do usuário do workspace. Depois que você se desconectar, o servidor SSH aguarda pelo shutdown-delay período (padrão: 10 minutos); em seguida, 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 a reinicialização do cluster. Use o armazenamento persistente (/Workspace/Users/<your-username>) para requisitos e scripts de instalação. Use bibliotecas de cluster ou scripts de inicialização para automação.

Quais métodos de autenticação têm suporte?

A autenticação usa a CLI do Databricks e o arquivo de perfis ~/.databrickscfg. As chaves SSH são tratadas pelo Desenvolvimento Remoto do Databrick.

Posso me conectar a bancos de dados ou serviços externos do cluster?

Sim, desde que sua rede de cluster permita conexões de saída e você tenha as bibliotecas necessárias.

Posso usar extensões adicionais do IDE?

A maioria das extensões funciona quando instaladas em sua sessão SSH remota, dependendo do IDE e do cluster. Por padrão, 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 habilitando 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 Desenvolvimento Remoto dá suporte a Link Privado?

Sim, no entanto, os administradores do workspace devem incluir na lista de permitidos as URLs dos marketplaces de extensões do VS Code e do Cursor. Os computadores locais dos usuários também devem ter a capacidade de acessar a Internet.