Conectar-se ao Databricks usando um túnel SSH

O túnel SSH fornecido pelo Databricks permite que você acesse seu espaço de trabalho e execute cargas de trabalho interativamente nos recursos de computação do Databricks a partir de IDEs por meio de um túnel SSH. É 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 túnel SSH para se conectar à computação clássica ou sem servidor do Databricks, você deve ter:

• CLI do Databricks versão 1.5.0 ou superior instalada em seu computador 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 superior e a extensão Remote – SSH (1.0.46+) instalada.
  • Versão do cursor: 2.6.11 (Universal) ou superior.

Para se conectar à computação de GPU sem servidor, o recurso AI Runtime deve estar habilitado. Consulte AI Runtime.

Para se conectar à computação clássica (dedicada, de usuário único):

• A computação deve estar executando o Databricks Runtime 17.0 ou superior. Confira a visão geral da computação dedicada.
• 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.
• Ao usar os Serviços de Contêiner do Databricks para computação dedicada, sua imagem do Docker deve ter openssh-server sido instalada.

Conectar-se à computação sem servidor

Para se conectar à computação sem servidor, execute o databricks ssh connect comando de um terminal em seu IDE. Nenhuma etapa de instalação separada é necessária.

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

databricks ssh connect

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

databricks ssh connect --accelerator=GPU_1xA10

databricks ssh connect oferece uma sessão interativa em um único nó. Para tarefas de treinamento de longa duração ou treinamento distribuído em vários nós, envie a carga de trabalho com a CLI air. Consulte a CLI do AI Runtime.

Depois de se conectar, conclua a configuração do ambiente de desenvolvimento. Consulte Projetos abertos.

Para se conectar à computação sem servidor e iniciar a sessão no Visual Studio Code ou no Cursor, use a opção --ide. A CLI abre uma janela IDE apontando para a pasta de workspace inicial.

databricks ssh connect --ide=vscode

Conectar-se à computação clássica

Para se conectar à computação clássica, primeiro configure a conexão SSH e conecte-se usando o IDE ou o terminal.

Configurar a conexão SSH

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:

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 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. No menu suspenso, 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

Por padrão, o databricks ssh connect comando é aberto para um diretório efêmero. Para acessar arquivos de workspace, navegue até o diretório do workspace do IDE ou terminal:

• Em Visual Studio Code ou Cursor, na Paleta de Comandos (Cmd/Ctrl+Shift+P), selecione Abrir Pasta e navegue até /Workspace/Users/<your-username>.
• Em uma janela de terminal, altere o diretório: cd /Workspace/Users/<your-username>.

Executar código ( Visual Studio Code ou Cursor)

Para executar o código usando o túnel SSH, o ambiente virtual do Databricks deve ser configurado. Esse ambiente inclui todas as bibliotecas integradas do DBR e bibliotecas com escopo de computação definido.

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 não aparecer:

   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. Cole o resultado completo como caminho do interpretador no prompt Python: Selecionar Interpretador.

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.

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 na computação sem servidor, inicialize uma sessão explicitamente:

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

Gerenciar dependências do Python

Gerencie as dependências do Python globalmente, no nível do cluster, ou com escopo limitado a projetos individuais usando notebooks.

Bibliotecas de cluster (recomendado)

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

Configuração de notebook específica do projeto

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

Os comandos %pip incluem proteções específicas 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 túnel SSH fornecido pelo Databricks tem as seguintes limitações:

• Não há suporte para clusters compartilhados.
• A extensão do Databricks para Visual Studio Code e o túnel SSH ainda não são compatíveis e não devem ser usadas 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.
• As 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 do Docker.
• Você pode encontrar problemas de desempenho ou conexão quando três ou mais notebooks Jupyter estiverem abertos simultaneamente. Essa limitação será resolvida em uma versão futura.

Diferenças do Databricks Notebooks

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

• 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:
  • 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 "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.

code comando não encontrado

Se você vir Error: exec: "code": executable file not found in $PATH, abra a Paleta de Comandos (Cmd/Ctrl+Shift+P), selecione Comando shell: instale o comando 'code' no PATH e reinicie o IDE ou a sessão de terminal.

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 notebooks do Databricks *.py têm acesso às globais do Databricks, mas os arquivos Python *.py não. Confira as diferenças do Databricks Notebooks.

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

• Os arquivos em montagens /Workspace, /Volumes, e /dbfs 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. Consulte 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 de Windows Visual Studio Code não consegue localizar as configurações de SSH criadas no lado do WSL.

perguntas frequentes

Como o túnel SSH é 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 Databricks Visual Studio Code usa o Databricks Connect para fornecer depuração integrada do código do usuário no Databricks.

O túnel SSH permite que você acesse o workspace pela sua IDE e transfere todo o seu ambiente de desenvolvimento para o ambiente computacional — Python, kernel e toda a execução são executados no Databricks, com acesso total aos recursos de computação.

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 encerramento automático curta em seu cluster a partir 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 manipuladas pelo túnel SSH.

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 túnel SSH dá suporte a Link Privado?

Sim, no entanto, os administradores do workspace devem adicionar as URLs dos marketplaces de extensões do Visual Studio Code e do Cursor à lista de permissões. Seu computador local também deve ter a capacidade de acessar a Internet.