Menyambungkan ke Databricks menggunakan terowongan SSH

Penting

Fitur ini ada di Beta.

Biaya dan harga untuk fitur Beta dapat berubah.

Terowongan Azure Databricks SSH (Secure Shell) menghubungkan Visual Studio Code, Cursor, atau terminal Anda ke ruang kerja Azure Databricks dan komputasi nirserver Azure Databricks, AI Runtime, atau komputasi klasik. Gunakan ini untuk mengedit file workspace dan menjalankan atau mendebug skrip dan notebook Python, dengan lingkungan Python dan eksekusi kode Anda pada komputasi jarak jauh. Hubungkan langsung ke komputasi serverless, atau atur koneksi SSH yang dapat digunakan ulang ke klaster klasik khusus.

Persyaratan

Mulai koneksi SSH dari mesin lokal Anda. Tunnel tidak dapat diluncurkan dari lingkungan jarak jauh lain atau kontainer Docker.

Untuk terhubung ke komputasi serverless atau klasik, Anda harus memiliki:

  • Databricks CLI versi 1.5.0 atau yang lebih baru diinstal pada komputer lokal Anda dan autentikasi dikonfigurasi. Periksa versi terinstal Anda dengan databricks --version. Lihat Menginstal atau memperbarui Databricks CLI.
  • Salah satu hal berikut ini:
    • Visual Studio Code versi 1.110.0 (Universal) atau lebih tinggi dan ekstensi Remote - SSH (1.0.46+) terpasang.
    • Cursor versi 2.6.11 (Universal) atau lebih tinggi.

Untuk terhubung ke komputasi tanpa server, penerusan port ke komputasi tanpa server harus diaktifkan. Lihat Kelola port forwarding ke komputasi serverless.

Untuk menyambungkan ke komputasi GPU tanpa server, fitur Runtime AI harus diaktifkan. Lihat Runtime AI.

Persyaratan tambahan untuk komputasi klasik

Untuk terhubung ke komputasi klasik (khusus, pengguna tunggal):

Pilih koneksi SSH

Gunakan metode koneksi untuk tipe komputasi Anda:

Compute Metode koneksi Persyaratan penyiapan
Komputasi tanpa server databricks ssh connect Tidak ada langkah pengaturan SSH terpisah.
Tambahkan --ide vscode atau --ide cursor untuk meluncurkan IDE.
AI Runtime databricks ssh connect --accelerator <accelerator> Tidak ada langkah pengaturan SSH terpisah.
Tambahkan --ide vscode atau --ide cursor untuk meluncurkan IDE.
Untuk akselerator yang didukung, lihat --accelerator.
Komputasi khusus klasik untuk satu pengguna Jalankan databricks ssh setup --name <connection-name> di terminal Anda.
Kemudian mulai sesi SSH dari IDE atau jalankan ssh <connection-name>.		 Pilih klaster khusus untuk pengguna tunggal yang memenuhi persyaratan komputasi klasik.
Kluster bersama tidak didukung.

Untuk perbandingan dengan Databricks Connect dan opsi pengembangan lainnya, lihat Terhubung dari IDE Anda.

Menyambungkan ke komputasi tanpa server

Setelah memenuhi persyaratan di atas, jalankan databricks ssh connect dari terminal atau IDE Anda.

Nilai --ide memilih editor yang akan dijalankan, terlepas dari editor atau terminal mana Anda menjalankan perintah tersebut.

Visual Studio Code

databricks ssh connect --ide vscode

CLI membuka jendela Visual Studio Code yang terhubung ke komputasi jarak jauh.

Cursor

databricks ssh connect --ide cursor

CLI membuka jendela Cursor yang terhubung ke komputasi remote.

Stasiun

databricks ssh connect

CLI memulai sesi SSH interaktif.

Untuk opsi perintah, termasuk koneksi bernama dan profil autentikasi, lihat databricks ssh connect.

Setelah terhubung, buka proyek workspace Anda dan pilih lingkungan Python. Jika koneksi gagal, lihat Troubleshoot SSH tunnel connections.

Terhubung ke komputasi GPU tanpa server dengan AI Runtime

Dengan AI Runtime diaktifkan, tambahkan --accelerator untuk menggunakan komputasi GPU:

databricks ssh connect --accelerator GPU_1xA10

databricks ssh connect memberi Anda sesi interaktif pada satu simpul. Untuk tugas pelatihan yang berjalan lama atau pelatihan terdistribusi multi-node, kirimkan beban kerja dengan databricks air sebagai gantinya. Lihat Gunakan Databricks CLI dengan AI Runtime.

Hubungkan ke komputasi klasik

Untuk koneksi yang dapat digunakan ulang ke klaster khusus klasik, atur nama host SSH, lalu pilih host tersebut di IDE Anda atau hubungkan dari terminal.

Menyiapkan koneksi SSH

Nota

Menyiapkan koneksi SSH hanya diperlukan jika Anda tersambung ke komputasi klasik.

Jalankan databricks ssh setup di mesin lokal Anda. Ganti <connection-name> dengan nama untuk koneksi ini, seperti my-connection:

databricks ssh setup --name <connection-name>

CLI meminta Anda untuk memilih cluster dan menambahkan entri host ke konfigurasi SSH Anda. Anda juga dapat memilih klaster secara langsung. Ganti <cluster-id> dengan ID klaster khusus Anda:

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

Untuk mengonfigurasi berapa lama terowongan SSH menunggu setelah klien terakhir terputus, tambahkan --shutdown-delay ke perintah setup. Defaultnya adalah 10 menit. Sebagai contoh, untuk mengatur jeda 30 menit untuk koneksi melalui entri host SSH ini:

databricks ssh setup --name <connection-name> --cluster <cluster-id> --shutdown-delay 30m

Nota

Untuk pengguna IntelliJ, Databricks merekomendasikan untuk menambahkan --auto-start-cluster=false ke perintah penyiapan dan memulai kluster secara manual sebelum menyambungkan. Ini karena IDE JetBrains memulai semua kluster yang telah dikonfigurasi setiap kali diluncurkan, yang dapat mengakibatkan biaya komputasi tak terduga.

Menyambungkan menggunakan Visual Studio Code atau Kursor

  1. Untuk Visual Studio Code, instal ekstensi SSH Jarak Jauh. Kursor menyertakan ekstensi SSH jarak jauh secara default.

  2. Di menu utama IDE, klik Tampilkan>Palet Perintah. Pilih Remote-SSH: Pengaturan. Atau, pilih Preferensi: Buka Pengaturan Pengguna (JSON) untuk memodifikasi settings.json secara langsung.

  3. Di bawah Remote.SSH: Ekstensi Default (atau remote.SSH.defaultExtensions di settings.json), tambahkan ms-Python.Python dan ms-toolsai.jupyter.

    Jika Anda memodifikasi settings.json:

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

    Nota

    Secara opsional, tingkatkan nilai Remote.SSH: Connect Timeout (atau remote.SSH.connectTimeout in settings.json) untuk mengurangi kemungkinan kesalahan batas waktu lebih lanjut. Batas waktu default adalah 360.

  4. Di Palet Perintah, pilih Remote-SSH: Sambungkan ke Host.

  5. Dari menu drop-down, pilih koneksi yang Anda siapkan di langkah pertama. IDE melanjutkan untuk terhubung di jendela baru.

Menyambungkan menggunakan IDE IntelliJ

  1. Ikuti tutorial server jarak jauh untuk pengaturan.
  2. Pada layar koneksi baru, masukkan:
    • Nama pengguna:root
    • Pembawa acara: <connection-name>

Hubungkan ke komputasi klasik dari terminal

Gunakan nama koneksi yang Anda konfigurasikan dengan databricks ssh setup:

ssh <connection-name>

Untuk koneksi langsung tanpa entri host SSH yang dapat digunakan ulang, Anda juga dapat menggunakan CLI. Ganti <cluster-id> dengan ID klaster khusus Anda:

databricks ssh connect --cluster <cluster-id>

Lihat databricks ssh connect.

Buka proyek workspace melalui SSH

Secara bawaan, perintah databricks ssh connect akan terbuka di direktori sementara. Untuk mengakses file ruang kerja, navigasikan ke direktori ruang kerja Anda dari IDE atau terminal:

  • Di Visual Studio Code atau Kursor, dari Palet Perintah (Cmd/Ctrl+Shift+P) pilih Buka Folder dan navigasi ke /Workspace/Users/<your-username>.
  • Dari jendela terminal, ubah direktori Anda: cd /Workspace/Users/<your-username>.

Nota

File di /Workspace, /Volumes, dan /dbfs tetap ada saat kluster di-restart. File di /home, /root, dan jalur lokal lainnya bersifat sementara dan hilang saat memulai ulang.

Jalankan Python dan notebook di sesi SSH

Pilih lingkungan Python yang disediakan oleh sesi SSH Anda sebelum menjalankan kode. Untuk komputasi klasik, lingkungan ini mencakup pustaka Databricks Runtime bawaan dan library cakupan komputasi.

  1. Buka Palet Perintah (Cmd/Ctrl+Shift+P) dan pilih Python: Pilih Interpreter.

  2. Pilih pythonEnv-xxx lingkungan virtual dari daftar. Jika Anda menyiapkan dependensi Python dengan flag --base-environment, pilih nama lingkungan virtual yang lebih panjang dari daftar opsi yang tersedia. Jika lingkungan virtual tidak muncul:

    1. Jalankan echo $DATABRICKS_VIRTUAL_ENV dari terminal dalam IDE.

      Contoh output: /local_disk0/.ephemeral_nfs/envs/pythonEnv-xxx/bin/python

    2. Tempelkan output lengkap sebagai jalur penerjemah di Python: Pilih prompt Interpreter.

  3. Buka terminal baru dan lingkungan virtual harus diaktifkan secara otomatis.

  4. Untuk menjalankan notebook Jupyter, pastikan bahwa lingkungan virtual dipilih sebagai kernel. Klik Pilih Kernel di kanan atas buku catatan.

Jalankan dan men-debug berkas Python dan notebook .ipynb menggunakan ekstensi Python dan Jupyter standar.

Untuk menggunakan Spark dalam file Python pada komputasi tanpa server, inisialisasi sesi secara eksplisit:

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

Kelola ketergantungan untuk sesi SSH

Pilih manajemen ketergantungan untuk tipe komputasi Anda:

  • Untuk komputasi serverless, gunakan workspace base environment dengan versi lingkungan serverless yang didukung.
  • Untuk komputasi klasik, gunakan library cluster untuk dependensi yang bertahan selama restart (restart).
  • Untuk dependensi yang terbatas pada sesi proyek, gunakan notebook setup.

Untuk paket non-Python, lihat Ketergantungan Non-Python.

Lingkungan dasar ruang kerja (direkomendasikan untuk serverless dan AI Runtime)

Nota

Fitur ini mengharuskan dukungan lingkungan dasar ruang kerja Tanpa Server dalam pratinjau Pekerjaan diaktifkan. Lihat Kelola Pratinjau Azure Databricks.

Gunakan lingkungan dasar ruang kerja dengan lingkungan tanpa server versi 4 atau di bawah ini untuk mengonfigurasi dependensi Python sebelumnya. Tunnel SSH tidak mendukung --base-environment dengan lingkungan serverless versi 5 atau lebih tinggi. Buat lingkungan dasar menggunakan UI workspace atau perintah databricks environments create-workspace-base-environment.

Tentukan lingkungan menggunakan --base-environment opsi saat menyambungkan:

databricks ssh connect --base-environment my-workspace-env

Opsi --base-environment ini menerima nama tampilan, jalur YAML workspace, atau ID sumber daya. Anda tidak bisa menggabungkannya dengan --cluster. Lihat databricks ssh connect.

Pustaka kluster (direkomendasikan untuk komputasi klasik)

Instal dependensi menggunakan UI ruang kerja di bawah Pustaka Komputasi>. Ini bertahan selama seluruh proses memulai ulang kluster dan tersedia di pythonEnv-xxx. Lihat Pustaka kluster.

Ketergantungan non-Python

Untuk mempertahankan dependensi non-Python, gunakan skrip init yang menginstal paket saat komputasi dimulai. Secara opsional, simpan paket dalam volume Katalog Unity dan referensikan dari skrip init. Lihat Apa itu skrip init?.

penyiapan notebook khusus Project

Untuk dependensi cakupan proyek, jalankan notebook dengan berisi perintah %pip install pada awal setiap sesi.

# 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 perintah mencakup pagar pembatas khusus Databricks dan menyebarluaskan dependensi ke simpul eksekutor Spark. Ini memungkinkan fungsi yang ditentukan pengguna (UDF) dengan dependensi kustom.

Untuk contoh selengkapnya, lihat Mengelola pustaka dengan %pip perintah.

Anda tidak perlu menjalankan ulang notebook setup jika Anda terhubung kembali sebelum terowongan SSH mati. Secara default, terowongan akan mati 10 menit setelah klien terakhir terputus. Untuk mengubah jeda ini, gunakan --shutdown-delay dengan perintah untuk metode koneksi Anda:

  • Untuk koneksi komputasi klasik yang dapat digunakan ulang, atur delay dengan databricks ssh setup. Entri host SSH yang dihasilkan menerapkan delay saat Anda terhubung dari IDE atau menjalankan ssh <connection-name>.
  • Untuk koneksi CLI langsung, atur delay dengan databricks ssh connect.

Nota

Beberapa sesi SSH pada kluster yang sama berbagi satu lingkungan virtual.

Gunakan Git dalam sesi SSH

Penting

Fitur ini ada di Pratinjau Umum. Admin ruang kerja dapat mengontrol akses ke dukungan Git CLI untuk folder Git dari halaman Pratinjau . Lihat Kelola Pratinjau Azure Databricks.

Anda dapat menggunakan Git CLI di tunnel SSH dengan folder Git yang baru dibuat dan kredensial Git yang telah Anda konfigurasikan di workspace Azure Databricks. Lihat Menggunakan perintah Git CLI.

Jika CLI meminta kredensial alih-alih mengambilnya secara otomatis, Anda harus menghubungkan penyedia Git Anda ke Azure Databricks. Lihat Menyambungkan penyedia Git Anda ke Databricks.

Pertahankan proses yang terpisah tetap berjalan

Secara default, ketika tunnel SSH mati, ia menghentikan setiap proses yang dimulai oleh sesi, termasuk proses yang Anda lepaskan dari sesi dengan tmux, setsid, atau nohup. Sebelum menghentikan proses tersebut, terowongan mencatat peringatan dengan ID prosesnya dalam output eksekusi job tunnel. databricks ssh connect mencetak ID run pekerjaan saat memulai tunnel.

Untuk menjaga proses yang dilepas tetap berjalan setelah Anda memutuskan koneksi, gunakan flag --keep-detached-processes. Setel flag pada koneksi yang memulai tunnel, sebelum Anda memulai pekerjaan yang ingin Anda tetap aktifkan. Lihat Koneksi ke terowongan yang sudah ada.

  • Komputasi tanpa server atau klasik: Teruskan flag ke databricks ssh connect.
  • Komputasi klasik dengan host SSH yang dikonfigurasi: Teruskan flag ke databricks ssh setup. Entri host SSH yang dihasilkan akan berlaku setiap kali Anda terhubung. Koneksi serverless tidak memerlukan pengaturan, jadi opsi ini hanya berlaku untuk komputasi klasik.

Contoh berikut menjaga proses terpisah tetap berjalan di komputasi serverless:

databricks ssh connect --keep-detached-processes

Contoh berikut menjaga proses terpisah tetap berjalan pada klaster khusus:

databricks ssh connect --cluster 0123-456789-abcdefgh --keep-detached-processes

Ketika Anda menggunakan flag ini dan klien terakhir terputus, tunnel berperilaku sebagai berikut:

  • Setelah periode tersebut --shutdown-delay, tunnel memeriksa proses detached. Selama masih ada yang berjalan, tunnel tetap berjalan alih-alih mati.
  • Proses terpisah tetap memiliki akses ke /Workspace dan /Volumes.
  • Setelah proses terakhir yang terpisah keluar, terowongan akan mati dan eksekusi job-nya berakhir.

Sementara tunnel terus berjalan, Anda dapat terhubung kembali ke instance compute yang sama dan menghubungkan kembali ke pekerjaan yang dilepas, misalnya dengan tmux attach. Pada komputasi serverless, sambungkan kembali dengan nama koneksi yang sama. Jika Anda menghilangkan --name, CLI menurunkan nama koneksi dari workspace Anda serta flag --accelerator dan --base-environment, jadi mengubah salah satu flag akan memulai koneksi terpisah.

Koneksi ke terowongan yang sudah ada

Mode terowongan ditetapkan saat dimulai, dan sambungan berikutnya menanganinya sebagai berikut:

  • Jika Anda terhubung menggunakan flag ke terowongan yang dimulai tanpa flag, CLI memulai terowongan baru. Proses yang Anda lepaskan di tunnel yang ada tidak dipertahankan, dan tetap berhenti saat tunnel itu ditutup. Pada klaster dedicated, terowongan baru langsung menghentikan terowongan yang sudah ada, yang mengakhiri sesi terbukanya dan menghentikan proses terpisahnya.
  • Jika Anda terhubung tanpa flag ke tunnel yang dimulai dengan flag tersebut, CLI akan menggunakan kembali tunnel tersebut, dan tunnel tetap berjalan selama proses yang berjalan secara terlepas masih ada. Hal ini juga berlaku untuk koneksi dari entri host SSH lain atau sesi IDE ke instance komputasi yang sama.

Biaya dan masa pakai maksimum

Ingatlah hal-hal berikut ini:

  • Sementara terowongan terus berjalan, resource komputasi tetap berjalan dan menimbulkan biaya. Klaster klasik tidak otomatis diakhiri. Sesi idle tmux dihitung sebagai proses terpisah yang sedang berjalan, jadi tutup saja saat Anda tidak membutuhkannya lagi.
  • Run pekerjaan tetap berhenti ketika mencapai masa hidup maksimum yang ditetapkan oleh --server-timeout, meskipun proses terpisah sedang berjalan. Masa berlaku ini dihitung sejak saat eksekusi job dimulai, bukan sejak klien terakhir terputus koneksinya. Setelah run pekerjaan berhenti, proses yang terpisah kehilangan aksesnya ke /Workspace dan /Volumes. Pada komputasi tanpa server, proses detached akan berhenti. Pada komputasi klasik, mereka bisa terus berjalan tanpa akses tersebut sampai klaster dihentikan. Untuk mempertahankan output dari pekerjaan terpisah yang berjalan lama, simpan dengan Azure Databricks SDK atau API REST daripada menulis ke jalur /Workspace atau /Volumes. Lihat Mengelola file pada volume Katalog Unity.
  • Untuk pekerjaan yang berlangsung lebih lama, gunakan job atau bundle sebagai gantinya.

Jalankan agen coding dalam sesi SSH

Anda dapat menjalankan Claude Code dan Codex dalam sesi SSH tanpa instalasi atau konfigurasi apapun. Agen mengirim permintaan model melalui Unity Gateway di workspace Anda dan mengautentikasi dengan kredensial sesi SSH Anda.

Persyaratan agen coding

  • Databricks CLI versi 1.23.0 atau lebih tinggi di mesin lokal Anda.

  • Unity Gateway diaktifkan untuk workspace Anda, dengan akses ke model yang ingin Anda gunakan. Lihat prasyarat panduan mulai cepat agen coding.

  • Akses HTTPS keluar dari komputasi ke host-host berikut ini. Peluncuran pertama mengunduh alat agen dari sana:

    • github.com dan nodejs.org
    • PyPI: pypi.org dan files.pythonhosted.org
    • Registri NPM: registry.npmjs.org

    Jika image komputasi sudah mencakup uv atau npm, peluncur akan melewati pengunduhannya.

Luncurkan agen pengkodean

  1. Hubungkan ke instans komputasi Anda. Lihat Memilih koneksi SSH untuk berbagai cara terhubung.

  2. Di terminal sesi SSH, jalankan agent:

    claude

    atau

    codex

    Setiap argumen yang Anda tambahkan akan diteruskan ke agen tanpa perubahan.

Untuk menjalankan agen tanpa membuka sesi interaktif, berikan perintah agen setelah --. Shell remote menginterpretasikan perintah, jadi bungkus seluruh perintah dengan tanda kutip tunggal agar argumen yang dikutip tetap utuh. Misalnya, untuk menjalankan Claude Code dalam mode non-interaktif:

databricks ssh connect -- 'claude -p "Summarize the notebooks in my workspace home folder"'

Perintah yang diberikan setelah -- dimulai di direktori utama Anda di lingkungan compute, bukan di folder beranda workspace Anda.

Pertama kali Anda menjalankan agen pada compute, peluncur akan mengunduh dan menginstal alat agen secara otomatis.

Batasan agen pengodean

  • Alat agen, riwayat percakapan, dan pengaturan agen disimpan di direktori utama Anda pada mesin komputasi. Pada komputasi serverless, direktori ini hilang saat komputasi dimatikan. Pada klaster khusus, hal tersebut tetap ada di seluruh sesi SSH hingga klaster tersebut dimulai ulang atau dihentikan. Untuk menyimpan pekerjaan Anda, simpan file di /Workspace atau /Volumes. Lihat File hilang atau reset lingkungan setelah restart cluster.
  • Jika Anda menginstal claude atau codex di komputasi Anda sendiri, instalasi tersebut akan menjadi prioritas dan tidak dikonfigurasi untuk Unity Gateway.

Keterbatasan terowongan SSH

Terowongan SSH yang disediakan oleh Databricks memiliki batasan berikut:

  • Kluster bersama tidak didukung.
  • File yang diedit di luar /Workspace, /Volumes, dan /dbfs hilang saat menghidupkan ulang kluster.
  • Maksimum 10 koneksi SSH diizinkan per kluster.
  • Sesi yang tidak aktif dapat terputus setelah 1 jam.
  • Terowongan SSH tidak dapat diluncurkan dari lingkungan jarak jauh atau kontainer Docker lainnya.
  • Anda mungkin mengalami masalah performa atau koneksi saat tiga atau beberapa notebook Jupyter terbuka secara bersamaan.

Perilaku notebook dalam sesi SSH

Ada beberapa perbedaan dalam notebook saat menggunakan terowongan SSH:

  • File Python tidak menentukan databricks global apa pun (seperti spark atau dbutils). Anda harus mengimpornya secara eksplisit dengan from databricks.sdk.runtime import spark.
  • Untuk buku catatan ipynb, fitur-fitur ini tersedia:
    • Databricks globals: display, displayHTML, dbutils, table, sqludf, getArgument, sc, sqlContext, spark
    • %sql perintah magic untuk menjalankan sel SQL

Untuk bekerja dengan sumber Python "notebooks":

  • Cari jupyter.interactiveWindow.cellMarker.codeRegex dan atur ke:

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

  • Cari jupyter.interactiveWindow.cellMarker.default dan atur ke:

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

Memecahkan masalah koneksi terowongan SSH

Mulailah dengan gejala yang sesuai dengan masalah:

Gejala Pemeriksaan pertama
Koneksi SSH gagal atau waktu tunggu habis. Periksa akses workspace HTTPS dan WebSocket. Untuk komputasi klasik, juga periksa status klaster dan timeout IDE. Lihat koneksi SSH gagal atau mengalami time-out.
CLI melaporkan bahwa mereka tidak dapat menemukan code. Instal perintah shell Visual Studio Code di PATH lokal Anda. Perintah code tidak ditemukan.
Autentikasi CLI gagal. Periksa profil CLI dan, untuk komputasi klasik, izin cluster. Lihat kesalahan autentikasi CLI.
CLI melaporkan invalid_grant dengan Refresh token is invalid. Masuk lagi ke workspace menggunakan profil CLI yang sama, lalu coba sambungkan kembali. Lihat Refresh token tidak valid.
Kode Python atau notebook gagal setelah tersambung. Periksa interpreter atau kernel notebook yang dipilih. Lihat kode Python atau notebook yang gagal di sesi SSH.
File-file hilang setelah cluster dimulai ulang. Periksa apakah file disimpan pada jalur lokal ephemeral. Lihat File hilang atau reset lingkungan setelah restart cluster.
claude atau codex gagal dimulai. Periksa apakah Unity Gateway diaktifkan dan token serta izin Anda mengizinkan akses. Lihat Agen pengkodean gagal dimulai.

Koneksi SSH gagal atau mengalami time-out

  • Untuk komputasi klasik, pastikan klaster berjalan di UI workspace.
  • Periksa apakah jaringan, VPN, dan firewall Anda mengizinkan lalu lintas HTTPS dan WebSocket ke domain workspace Anda. Terowongan SSH tidak menggunakan port 22. Perangkat ini melakukan tunneling semua lalu lintas melalui endpoint HTTPS yang sama seperti perintah CLI Databricks lainnya. Lihat Mengonfigurasi aturan firewall nama domain.
  • Jika proxy atau firewall memeriksa lalu lintas TLS, periksa apakah mereka mengizinkan permintaan upgrade WebSocket. Perantara yang memblokir atau menghapus upgrade menyebabkan koneksi gagal atau timeout. Minta administrator jaringan Anda mengizinkan peningkatan WebSocket pada domain workspace Anda, atau melewati inspeksi TLS untuk domain tersebut.
  • Jika Anda terhubung melalui proxy HTTP perusahaan, atur variabel lingkungan HTTPS_PROXY, atau NO_PROXY untuk melewati proxy bagi domain ruang kerja Anda. Terowongan SSH menggunakan konfigurasi proxy yang sama seperti perintah CLI Databricks lainnya. Lihat Konfigurasi server proxy.
  • Periksa bahwa mesin lokal Anda memiliki akses HTTPS ke github.com dan release-assets.githubusercontent.com.
  • Tingkatkan batas waktu SSH. Lihat Menyambungkan menggunakan Visual Studio Code atau Kursor.
  • Untuk kesalahan ketidakcocokan kunci, hapus ~/.databricks/ssh-tunnel-keys dan jalankan databricks ssh setupkembali .
  • Untuk kesalahan "identifikasi host jarak jauh telah berubah", periksa ~/.ssh/known_hosts file dan hapus entri yang terkait dengan kluster Anda.
  • Sesi SSH mungkin turun setelah 1 jam dan tidak lebih dari 10 koneksi SSH dapat dilakukan ke satu kluster. Lihat batasan terowongan SSH.

code perintah tidak ditemukan

Jika Anda melihat Error: exec: "code": executable file not found in $PATH, buka Palet Perintah (Cmd/Ctrl+Shift+P), pilih Perintah Shell: Instal perintah 'kode' di PATH, dan mulai ulang SESI IDE atau terminal Anda.

Kesalahan autentikasi CLI

  • Masuk ke workspace Anda menggunakan databricks auth login.
  • Untuk komputasi klasik, pastikan Anda memiliki CAN ATTACH TO izin pada cluster, atau CAN RESTART jika cluster tidak berjalan.

Token refresh tidak valid

Jika databricks ssh connect gagal dengan error error getting token, invalid_grant, dan Refresh token is invalid, server otorisasi menolak token refresh OAuth yang disimpan dari CLI. Masuk lagi untuk mendapatkan sesi baru:

  1. Identifikasi profil konfigurasi untuk workspace yang ingin Anda sambungkan:

    databricks auth profiles --skip-validate

  2. Masuk lagi menggunakan profil tersebut. Ganti <workspace-url> dengan URL workspace, tanpa jalur /oidc/v1/token, dan <profile-name> dengan nama profil yang sesuai:

    databricks auth login --host <workspace-url> --profile <profile-name>

    Selesaikan alur masuk di browser Anda.

  3. Coba ulang koneksi dengan profil yang sama:

    databricks ssh connect --ide vscode --profile <profile-name>

    Gunakan --ide cursor untuk Cursor, atau hilangkan --ide untuk sesi terminal.

Jika kesalahan tetap ada, periksa apakah perintah yang gagal menargetkan workspace dan profil yang sama yang baru saja Anda masuk ke. Lihat autentikasi pengguna-ke-mesin (U2M) OAuth.

Kode atau notebook Python gagal di sesi SSH

File menghilang atau lingkungan direset setelah restart cluster

  • File di /Workspace, /Volumes, dan /dbfs mount bertahan selama klaster melakukan restart. File di /home, /root, dan jalur lokal lainnya bersifat sementara dan hilang saat memulai ulang.
  • Gunakan manajemen pustaka kluster untuk dependensi persisten. Mengotomatiskan instalasi ulang menggunakan skrip init jika diperlukan. Lihat Apa itu skrip init?.

Agen coding gagal dimulai

Saat Anda menjalankan claude atau codex, peluncur memeriksa bahwa Anda dapat mengakses Unity Gateway sebelum mengunduh alat agen. Jika Anda tidak memiliki akses ke Unity Gateway, agen bawaan tidak dapat berjalan. Cocokkan pesan kesalahan dengan penyebab:

  • Unity Gateway tidak diaktifkan di workspace ini: Minta admin workspace Anda untuk mengaktifkan Unity Gateway. Lihat Prasyarat.
  • Akses layanan model tidak dapat diverifikasi: Periksa bahwa Anda memenuhi prasyarat Unity Gateway, atau minta admin workspace Anda memberikan akses ke model-model tersebut.
  • Langkah instalasi gagal, misalnya ✗ Installing Node.js diikuti oleh failed to download: Periksa bahwa compute dapat mencapai github.com, nodejs.org, pypi.org, files.pythonhosted.org, dan registry.npmjs.org melalui HTTPS. Lihat Persyaratan untuk agen pengkodean.

Jika claude atau codex tidak ditemukan, periksa bahwa CLI Databricks lokal Anda adalah versi 1.23.0 atau lebih tinggi, lalu sambungkan kembali. Lihat Persyaratan untuk agen pengkodean.

Penyiapan SSH gagal pada Windows (WSL)

Jalankan databricks ssh setup langsung di Windows, bukan dalam WSL. Instans Windows Visual Studio Code tidak dapat menemukan konfigurasi SSH yang dibuat di sisi WSL.

FAQ

Apakah komputasi serverless memerlukan pengaturan SSH?

No. Setelah menginstal dan mengautentikasi CLI Databricks, gunakan databricks ssh connect untuk komputasi serverless. Perintah databricks ssh setup mengonfigurasi entri host SSH yang dapat digunakan ulang untuk komputasi khusus klasik.

Apakah terowongan SSH Databricks memerlukan port 22?

No. Terowongan SSH membawa lalu lintas melalui HTTPS ke domain workspace Anda dan memerlukan dukungan WebSocket. Jaringan, VPN, firewall, dan proxy Anda harus mengizinkan lalu lintas tersebut. Lihat koneksi SSH gagal atau mengalami time-out.

Apa perbedaan terowongan SSH dengan Databricks Connect?

Databricks Connect memungkinkan Anda menulis kode menggunakan API Spark dan menjalankannya dari jarak jauh pada komputasi Databricks alih-alih dalam sesi Spark lokal. Ekstensi Databricks Visual Studio Code menggunakan Databricks Connect untuk menyediakan debugging kode pengguna yang terintegrasi di Databricks.

Tunnel SSH memungkinkan Anda mengakses workspace dari IDE Anda dan memindahkan seluruh lingkungan pengembangan Anda ke mesin komputasi. Python, kernel, dan eksekusi kode dijalankan di Azure Databricks dengan akses ke sumber daya komputasi.

Bagaimana kode dan data saya diamankan?

Lalu lintas SSH dienkripsi secara end-to-end, dan kode berjalan pada komputasi Azure Databricks yang Anda sambungkan. Autentikasi menggunakan Databricks CLI dan profil workspace Anda yang telah dikonfigurasi. Lihat Metode otentikasi apa saja yang didukung?.

Platform IDE apa yang didukung?

Visual Studio Code dan Kursor secara resmi didukung. IDE apa pun dengan kemampuan SSH kompatibel, tetapi hanya Visual Studio Code dan Kursor yang diuji.

Bisakah saya menggunakan agen coding dalam sesi SSH?

Yes. Dalam sesi SSH pada komputasi serverless atau klaster khusus, jalankan claude atau codex. Agen menggunakan Unity Gateway tanpa pengaturan tambahan. Lihat Jalankan agen pengkodean dalam sesi SSH.

Apakah semua fitur notebook Databricks tersedia dari IDE?

Beberapa fitur seperti display(), dbutils, dan %sql tersedia dengan batasan atau penyiapan manual. Lihat Perilaku Notebook dalam sesi SSH.

Apakah kluster saya akan dimulai secara otomatis saat saya tersambung menggunakan terowongan SSH?

Ya, tetapi jika diperlukan waktu lebih lama untuk memulai kluster daripada batas waktu koneksi, upaya koneksi akan gagal. Untuk mencegah hal ini, tingkatkan nilai Remote.SSH: Sambungkan Batas Waktu dari palet perintah (atau remote.SSH.connectTimeout di settings.json) untuk lebih mengurangi kemungkinan kesalahan waktu habis.

Bagaimana cara mengetahui apakah kluster saya berjalan?

Navigasi ke Komputasi di UI ruang kerja Databricks, dan periksa status kluster. Kluster harus menunjukkan Berjalan agar koneksi SSH berfungsi.

Bagaimana cara memutuskan sambungan sesi SSH/IDE saya?

Anda dapat memutuskan sesi dengan menutup jendela IDE Anda, menggunakan opsi Putuskan sambungan di IDE Anda, menutup terminal SSH Anda, atau menjalankan exit perintah di terminal.

Bagaimana cara menghentikan cluster dan menghindari tagihan saat saya tidak bekerja?

Untuk segera berhenti, hentikan kluster dari UI ruang kerja. Navigasi ke Komputasi di UI ruang kerja Databricks, temukan kluster Anda, dan klik Hentikan atau Hentikan.

Tetapkan kebijakan penghentian otomatis singkat pada kluster Anda dari antarmuka pengguna ruang kerja. Setelah Anda terputus, terowongan SSH menunggu selama periode shutdown-delay (default: 10 menit), lalu timeout cluster akan berlaku. Jika Anda menggunakan --keep-detached-processes, cluster tidak otomatis dihentikan saat proses terpisah sedang berjalan. Ini juga berlaku untuk sambungan tanpa flag yang menggunakan kembali terowongan yang dimulai dengan bendera tersebut. Lihat Koneksi ke terowongan yang sudah ada.

Bagaimana cara menangani dependensi persisten?

Dependensi yang diinstal selama sesi hilang setelah mulai ulang kluster. Gunakan penyimpanan persisten (/Workspace/Users/<your-username>) untuk persyaratan dan skrip penyiapan. Gunakan pustaka kluster atau skrip init untuk otomatisasi.

Metode autentikasi apa yang didukung?

Autentikasi menggunakan Databricks CLI dan file profil Anda ~/.databrickscfg . Kunci SSH ditangani oleh terowongan SSH.

Bisakah saya menyambungkan ke database atau layanan eksternal dari kluster?

Ya, selama jaringan klaster Anda memungkinkan koneksi keluar dan Anda memiliki pustaka yang diperlukan.

Dapatkah saya menggunakan ekstensi IDE tambahan?

Sebagian besar ekstensi berfungsi saat diinstal dalam sesi SSH jarak jauh Anda, tergantung pada IDE dan kluster Anda. Visual Studio Code secara default tidak menginstal ekstensi lokal pada host jarak jauh. Anda dapat menginstalnya secara manual dengan membuka panel ekstensi dan mengaktifkan ekstensi lokal Anda di host jarak jauh. Anda juga dapat mengonfigurasi Visual Studio Code untuk selalu menginstal ekstensi tertentu dari jarak jauh. Lihat Menyambungkan ke Databricks.

Ya, namun admin ruang kerja harus memasukkan URL Visual Studio Code dan marketplace ekstensi Cursor ke daftar yang diizinkan. Komputer lokal Anda juga harus memiliki kemampuan untuk mengakses internet.

  • Terakhir diperbarui pada