SSH トンネルを使用して Databricks に接続する

Azure DatabricksのSSH(Secure Shell)トンネルは、Visual Studio Code、Cursor、または端末をDatabricksワークスペースやAzure Databricksのサーバーレス、サーバーレスGPU、クラシックコンピュートに接続します。 これを使用して、ワークスペースファイルの編集や、リモートコンピュート上での Python 環境とコード実行により、Python スクリプトやノートブックの実行・デバッグを行うことができます。 サーバーレスコンピュートに直接接続するか、専用のクラシッククラスターに再利用可能なSSH接続を設定することができます。

Requirements

ローカルマシンからSSH接続を開始してください。 トンネルは他のリモート環境やDockerコンテナから起動することはできません。

サーバーレスやクラシックコンピュートに接続するには、以下の条件が必要です:

• Databricks CLI バージョン 1.5.0 以降がローカル マシンにインストールされており、認証が構成されていること。 インストールされているバージョンを databricks --versionで確認します。 「Databricks CLI のインストールまたは更新」を参照してください。
• 次のいずれかが必要です。
  • Visual Studio Code バージョン 1.110.0 (ユニバーサル) 以上で、Remote - SSH 拡張 (1.0.46+) がインストールされていること。
  • Cursorバージョン2.6.11（Universal）以降。

サーバーレス GPU コンピューティングに接続するには、AI ランタイム機能を有効にする必要があります。 AI ランタイムを参照してください。

クラシックコンピュートの追加要件

クラシック (専用、シングル ユーザー) コンピューティングに接続するには:

• コンピューティングで Databricks Runtime 17.0 以降が実行されている必要があります。 専用コンピューティングの概要を参照してください。
• Unity カタログを有効にする必要があります。
• コンピューティング ポリシーが存在する場合は、ジョブの実行を禁止してはなりません。
• 専用コンピューティングに Databricks Container Services を使用する場合は、Docker イメージopenssh-serverインストールされている必要があります。

SSH接続を選択してください

コンピュートタイプに合った接続方法を使用してください:

SSHトンネルとDatabricksのIDE拡張は互換性がなく、一緒に使用すべきではありません。 Databricks Connectやその他の開発オプションとの比較については、IDE から接続するをご覧ください。

サーバーレス コンピューティングに接続する

上記の要件を満たしたら、端末またはIDEからdatabricks ssh connectを実行してください。

--ide値は、どのエディタやターミナルからコマンドを実行しても、起動するエディタを選択します。

Visual Studio Code

databricks ssh connect --ide vscode

CLIはリモートコンピュートに接続されたVisual Studio Codeウィンドウを開きます。

Cursor

databricks ssh connect --ide cursor

CLIはリモートコンピュートに接続されたCursorウィンドウを開きます。

Terminal

databricks ssh connect

CLIは対話型のSSHセッションを開始します。

コマンドオプション、名前付き接続や認証プロファイルについては、databricks ssh connectを参照してください。

接続後、ワークスペースプロジェクトを開き、Python環境を選択します。 接続が失敗した場合は 、「SSHトンネル接続のトラブルシューティング」を参照してください。

AIランタイム付きのサーバーレスGPUコンピュートに接続

AIランタイムを有効にした状態で、GPU計算を活用するための --accelerator を追加してください:

databricks ssh connect --accelerator GPU_1xA10

databricks ssh connect では、1 つのノードで対話型セッションが提供されます。 長期的なトレーニングジョブやマルチノード分散トレーニングの場合は、 databricks air と一緒にワークロードを提出してください。 「 Data bricks CLIとAIランタイムを使いましょう」を参照してください。

クラシック コンピューティングに接続する

クラシックな専用クラスタへの再利用可能な接続をするには、SSHホスト名を設定し、IDEでそのホストを選択するか、ターミナルから接続してください。

SSH 接続を設定する

ローカルマシンで databricks ssh setup を実行してください。 <connection-name> をこの接続の名前（例: my-connection）に置き換えてください:

databricks ssh setup --name <connection-name>

CLIはクラスタを選択するよう促し、SSH設定にホストエントリを追加します。 クラスターを直接選択することもできます。 <cluster-id>を専用クラスタのIDに置き換えてください:

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

最後のクライアントが切断された後のSSHサーバーの待ち時間を設定するには、セットアップコマンドに --shutdown-delay を追加してください。 既定では 10 分です。 例えば、このSSHホストエントリを通じた接続に30分の遅延を設定する場合:

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

Visual Studio Code または Cursor を使用して接続する

1. Visual Studio Code の場合は、 リモート SSH 拡張機能をインストールします。 カーソルには、既定でリモート SSH 拡張機能が含まれています。

2. IDE のメイン メニューで、[表示]>[コマンド パレット]をクリックします。 [Remote-SSH: Settings]\(リモート SSH: 設定\) を選択します。 または、[ Preferences: Open User Settings (JSON)] を選択して、 settings.json を直接変更します。

3. Remote.SSH: 既定の拡張機能 (またはremote.SSH.defaultExtensionsのsettings.json) で、ms-Python.Pythonとms-toolsai.jupyterを追加します。

   settings.jsonを変更する場合:

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

   注

   必要に応じて、Remote.SSH: Connect Timeout (または remote.SSH.connectTimeout のsettings.json) の値を大きくして、タイムアウト エラーの可能性をさらに減らします。 既定のタイムアウトは 360 です。

4. コマンド パレットで、[ Remote-SSH: Connect to Host]\(リモート SSH: ホストに接続\) を選択します。

5. ドロップダウン メニューから、最初の手順で設定した接続を選択します。 IDE は新しいウィンドウで接続を続行します。

IntelliJ IDE を使用して接続する

1. リモート サーバーのチュートリアルに従ってセットアップします。
2. 新しい接続画面で、次のように入力します。
   • ユーザー名: root
   • ホスト: <connection-name>

ターミナルからクラシックコンピュートに接続

databricks ssh setup で設定した接続名を使用してください:

ssh <connection-name>

再利用可能なSSHホストエントリなしで直接接続する場合は、CLIを使うこともできます。 <cluster-id>を専用のクラスタIDに置き換えてください:

databricks ssh connect --cluster <cluster-id>

Databricksのssh connectを参照してください。

SSHを通じてワークスペースプロジェクトを開く

既定では、 databricks ssh connect コマンドが一時ディレクトリに対して開きます。 ワークスペース ファイルにアクセスするには、IDE またはターミナルからワークスペース ディレクトリに移動します。

• Visual Studio Codeまたはカーソルで、コマンド パレット (Cmd/Ctrl + Shift + P) から [フォルダーを開く] を選択し、/Workspace/Users/<your-username>に移動します。
• ターミナル ウィンドウから、ディレクトリを変更します: cd /Workspace/Users/<your-username>。

SSHセッションでPythonとノートブックを動かしてください

コードを実行する前に、SSHセッションが提供するPython環境を選択してください。 クラシック計算環境には、組み込みのDatabricks Runtimeライブラリとコンピュート スコープのライブラリが含まれます。

1. コマンド パレット (Cmd/Ctrl + Shift + P) を開き、[Python: インタープリターの選択] を選択します。

2. pythonEnv-xxx仮想環境を一覧から選択します。 --base-environment フラグを使用してPython依存関係を設定する場合は、オプションの一覧から長い仮想環境名を選択します。 仮想環境が表示されない場合:

   1. IDE 内のターミナルから echo $DATABRICKS_VIRTUAL_ENV を実行します。

      出力例: /local_disk0/.ephemeral_nfs/envs/pythonEnv-xxx/bin/python

   2. Python: インタープリターの選択プロンプトに、完全な出力をインタープリター パスとして貼り付けます。

3. 新しいターミナルを開き、仮想環境が自動的にアクティブ化されます。

4. Jupyter Notebook を実行するには、仮想環境がカーネルとして選択されていることを確認します。 ノートブックの右上にある [ カーネルの選択 ] をクリックします。

標準のPythonと Jupyter 拡張機能を使用して、Pythonファイルと.ipynbノートブックを実行およびデバッグします。

サーバーレス コンピューティングのPython ファイルで Spark を使用するには、セッションを明示的に初期化します。

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

SSHセッションの依存関係を管理する

計算タイプに対して依存関係管理を選択してください:

• サーバーレスコンピュートの場合は、サポートされているサーバーレス環境バージョンを備えた ワークスペース ベース環境 を使いましょう。
• クラシックコンピュートの場合は、再起動後も持続する依存関係には クラスタライブラリ を使いましょう。
• プロジェクトセッションにスコープをかけた依存関係については、 セットアップノートブックを使いましょう。

非Pythonパッケージについては、Non-Python依存関係を参照してください。

ワークスペースの基本環境 (サーバーレスおよび AI ランタイムに推奨)

サーバーレス環境バージョン 4 以下のワークスペース基本環境を使用して、Python依存関係を事前に構成します。 SSHトンネルはサーバーレス環境バージョン5以上では --base-environment をサポートしません。 ワークスペース UI または Databricks CLI databricks 環境 create-workspace-base-environment コマンドを使用して、基本環境を作成します。

接続時に --base-environment オプションを使用して環境を指定します。

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

--base-environmentオプションは表示名、ワークスペースのYAMLパス、またはリソースIDを受け付けます。 それを--clusterと組み合わせることはできません。 Databricksのssh connectを参照してください。

クラスター ライブラリ (クラシック コンピューティングに推奨)

コンピューティング > ライブラリのワークスペース UI を使用して依存関係をインストールします。 これらはクラスターの再起動間で保持され、 pythonEnv-xxxで使用できます。 クラスター ライブラリを参照してください。

Python以外の依存関係

Python以外の依存関係を保持するには、コンピューティングの開始時にパッケージをインストールする init スクリプトを使用します。 必要に応じて、Unity カタログ ボリュームにパッケージを格納し、init スクリプトからパッケージを参照します。 initスクリプトとは何かについては、を参照してください。。

プロジェクト固有のノートブックのセットアップ

プロジェクト スコープの依存関係の場合は、各セッションの開始時に %pip install コマンドを含むノートブックを実行します。

# 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 コマンドには、Databricks 固有のガードレールが含まれており、依存関係が Spark Executor ノードに伝達されます。 これにより、カスタム依存関係を持つユーザー定義関数 (UDF) が有効になります。

その他の例については、「%pip コマンドを使用したライブラリの管理」を参照してください。

SSHサーバーがシャットダウンする前に再接続すれば、セットアップノートブックを再実行する必要はありません。 デフォルトでは、最後のクライアントが切断されてから10分後にサーバーがシャットダウンします。 この遅延を変更するには、接続方法に応じたコマンドで --shutdown-delay を使用します:

• 再利用可能なクラシックコンピュート接続の場合は、databricks ssh setupで遅延を設定します。 生成されたSSHホストエントリでは、IDEから接続したりssh <connection-name>を実行したりするときに遅延が発生します。
• 直接CLI接続の場合は、databricks ssh connectで遅延を設定します。

SSHセッションでGitを使います

新しく作成された Git フォルダーと、Databricks ワークスペースで構成した Git 資格情報を使用して、SSH トンネル内の Git CLI を使用できます。 Git CLI コマンドの使用を参照してください。

CLI で資格情報を自動的に選択する代わりに資格情報の入力を求められた場合は、Git プロバイダーを Databricks に接続する必要があります。 「 Git プロバイダーを Databricks に接続する」を参照してください。

SSHトンネルの制限

Databricks によって提供される SSH トンネルには、次の制限があります。

• 共有クラスターはサポートされていません。
• DatabricksのIDE拡張とSSHトンネルはまだ互換性がなく、一緒に使用すべきではありません。
• /Workspace、/Volumes、/dbfsの外部で編集されたファイルは、クラスターの再起動時に失われます。
• クラスターごとに最大 10 個の SSH 接続が許可されます。
• 非アクティブなセッションは、1 時間後に削除される可能性があります。
• SSH トンネルは、他のリモート環境または Docker コンテナーから起動できません。
• 3 つ以上の Jupyter ノートブックが同時に開かれていると、パフォーマンスや接続の問題が発生する可能性があります。

SSHセッションにおけるノートブックの挙動

SSH トンネルを使用する場合、ノートブックにはいくつかの違いがあります。

• Python ファイルでは、Databricks グローバル ( spark や dbutilsなど) は定義されません。 from databricks.sdk.runtime import sparkを使用して明示的にインポートする必要があります。
• ipynb ノートブックの場合、次の機能を使用できます。
  • Databricks グローバル: display、 displayHTML、 dbutils、 table、 sql、 udf、 getArgument、 sc、 sqlContext、 spark
  • %sql SQL セルを実行するマジック コマンド

Python ソースコード「notebooks」を使用するには:

• jupyter.interactiveWindow.cellMarker.codeRegexを検索して、それに設定します。

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

• jupyter.interactiveWindow.cellMarker.defaultを検索して、それに設定します。

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

SSHトンネル接続のトラブルシューティング

まずは障害に合致する症状から始めましょう：

SSH接続が失敗する、またはタイムアウトする

• クラシックコンピュートの場合は、クラスタがワークスペースUIで動作しているか確認してください。
• ネットワーク、VPN、ファイアウォールがワークスペースドメインへのHTTPSやWebSocketトラフィックを許可しているか確認してください。 SSHトンネルはポート22を使用しません。 すべてのトラフィックを他のDatabricksのCLIコマンドと同じHTTPSエンドポイント経由でトンネルします。 ドメイン名ファイアウォール規則の構成に関するセクションを参照してください。
• プロキシやファイアウォールがTLSトラフィックを検査した場合、WebSocketのアップグレードリクエストが許可されているか確認してください。 アップグレードをブロックまたは剥奪する仲介者が接続を失敗またはタイムアウトさせます。ネットワーク管理者に、ワークスペースドメインへのWebSocketアップグレードを許可するか、TLS検査を回避してもらうよう依頼してください。
• 企業のHTTPプロキシ経由で接続する場合は、 HTTPS_PROXY 環境変数を設定するか、ワークスペースドメインのプロキシを回避する NO_PROXY を設定してください。 SSHトンネルは他のDatabricksのCLIコマンドと同じプロキシ構成を使用します。 プロキシ サーバーの設定を参照してください。
• ローカルマシンが github.com や release-assets.githubusercontent.comにHTTPSアクセス権を持っているか確認してください。
• SSH タイムアウトを増やします。 Visual Studio Code またはカーソルを使用した接続を参照してください。
• キーの不一致エラーの場合は、 ~/.databricks/ssh-tunnel-keys を削除し、 databricks ssh setupを再実行します。
• "リモート ホスト ID が変更されました" エラーについては、 ~/.ssh/known_hosts ファイルを確認し、クラスターに関連するエントリを削除します。
• SSH セッションは 1 時間後に削除される可能性があり、1 つのクラスターに対して 10 を超える SSH 接続を作成することはできません。 SSHトンネルの制限を参照してください。

code コマンドが見つかりません

Error: exec: "code": executable file not found in $PATH表示された場合は、コマンド パレット (Cmd/Ctrl + Shift + P) を開き、[シェル コマンド: PATH に 'code' コマンドをインストールする] を選択し、IDE またはターミナル セッションを再起動します。

CLI認証エラー

• databricks auth login を使用してワークスペースにサインインしてください。
• クラシックコンピュートの場合は、クラスタに対する CAN MANAGE の権限を持っていることを確認してください。

リフレッシュトークンは無効です

databricks ssh connectがerror getting token、invalid_grant、Refresh token is invalidで失敗した場合、認可サーバーはCLIが保存したOAuthリフレッシュトークンを拒否しました。 新しいセッションを取得するには再度サインインしてください:

1. 接続したいワークスペースの設定プロファイルを特定してください:

   databricks auth profiles --skip-validate
   

2. そのプロフィールで再度サインインしてください。 <workspace-url>を/oidc/v1/tokenパスを除いたワークスペースのURLに、<profile-name>を対応するプロフィール名に置き換えます。

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

   ブラウザーでサインイン フローを完了します。

3. 同じプロファイルで接続を再試してみてください:

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

   カーソルには --ide cursor を使い、Cursor の場合は --ide を省略してください。

エラーが続く場合は、失敗したコマンドが先ほどサインインしたものと同じワークスペースとプロファイルを対象にしているか確認してください。 OAuthユーザー対マシン(U2M)認証を参照してください。

PythonコードやノートブックがSSHセッション内で失敗する

• SSHセッションが提供するPython環境を選択してください。 ノートブックの場合は、その環境をカーネルとして選択します。 SSH セッションで Python とノートブックを実行する を参照してください。
• IPYNB ノートブックと *.py Databricks ノートブックは Databricks グローバルにアクセスできますが、Python *.py ファイルにはアクセスできません。 SSH セッションにおけるノートブックの挙動を参照してください。

クラスタ再起動後にファイルが消えたり環境がリセットされたりします

• /Workspace、/Volumes、および/dbfsマウント内のファイルは、クラスターの再起動後も保持されます。 /home、/root、およびその他のローカル パス内のファイルは一時的であり、再起動時に失われます。
• 永続的な依存関係にはクラスター ライブラリ管理を使用します。 必要に応じて、init スクリプトを使用して再インストールを自動化します。 initスクリプトとは何かについては、を参照してください。。

Windows (WSL) で SSH セットアップが失敗する

WSL 内ではなく、Windows で直接 databricks ssh setup を実行します。 Windows Visual Studio Code インスタンスは、WSL 側で作成された SSH 構成を見つけることができません。

FAQ

サーバーレスコンピュートはSSH設定が必要ですか?

No. Databricks CLIをインストールし認証した後、サーバーレス計算のために databricks ssh connect を使いましょう。 databricks ssh setupコマンドは、クラシック専用コンピュート用に再利用可能なSSHホストエントリを設定します。

DatabricksのSSHトンネルはポート22を必要としますか?

No. SSHトンネルはHTTPS経由でワークスペースドメインへのトラフィックを運び、WebSocketのサポートが必要です。 ネットワーク、VPN、ファイアウォール、プロキシはそのトラフィックを許可しなければなりません。 SSH 接続が失敗する、またはタイムアウトするを参照してください。

SSH トンネルと Databricks Connect の違い

Databricks Connect を使用すると、Spark API を使用してコードを記述し、ローカルの Spark セッションではなく Databricks コンピューティングでリモートで実行できます。 Databricks Visual Studio Code拡張機能では、Databricks Connect を使用して、Databricks でのユーザー コードの組み込みデバッグが提供されます。

SSHトンネルを使用するとIDEからワークスペースにアクセスでき、開発環境全体はコンピュート上に移されます。 Python、カーネル、コード実行はAzure Databricks上で動作し、コンピューティング リソースにアクセスして実行されます。

コードとデータはどのように保護されますか?

SSHトラフィックはエンドツーエンドで暗号化されており、コードは接続先の Azure Databricks コンピュート上で動作します。 認証はDatabricksのCLIと設定済みのワークスペースプロファイルを使用します。 「サポートされている認証方法は何ですか？」をご覧ください。

どの IDE がサポートされていますか?

Visual Studio Codeとカーソルは正式にサポートされています。 SSH 機能を備えた IDE には互換性がありますが、テストされるのは VS Code と Cursor のみです。

すべての Databricks ノートブック機能は IDE から利用できますか?

display()、dbutils、%sqlなどの一部の機能は、制限付きで、または手動で設定できます。 SSH セッションにおけるノートブックの挙動を参照してください。

SSH トンネルを使用して接続すると、クラスターは自動的に開始されますか?

はい。ただし、クラスターの起動に接続タイムアウトよりも時間がかかる場合、接続の試行は失敗します。 これを回避するには、コマンド パレット (または のremote.SSH.connectTimeout) から settings.json の値を大きくして、タイムアウト エラーの可能性をさらに減らします。

クラスターが実行されているかどうかを確認するにはどうすればよいですか?

Databricks ワークスペース UI で [コンピューティング ] に移動し、クラスターの状態を確認します。 クラスターには、SSH 接続が機能するために [実行中 ] と表示されている必要があります。

SSH/IDE セッションを切断するにはどうすればよいですか?

セッションを切断するには、IDE ウィンドウを閉じるか、IDE の [切断 ] オプションを使用するか、SSH ターミナルを閉じるか、ターミナルで exit コマンドを実行します。

クラスターを停止し、動作していないときに課金を回避するにはどうすればよいですか?

すぐに停止するには、ワークスペース UI からクラスターを終了します。 Databricks ワークスペース UI で [コンピューティング ] に移動し、クラスターを見つけて、[ 終了 ] または [停止] をクリックします。

ワークスペース UI からクラスターに短い 自動終了 ポリシーを設定します。 切断後、SSH サーバーは shutdown-delay 期間 (既定値: 10 分) を待機し、クラスターのアイドル タイムアウトが適用されます。

永続的な依存関係を処理する方法

セッション中にインストールされた依存関係は、クラスターの再起動後に失われます。 要件とセットアップ スクリプトには永続的ストレージ (/Workspace/Users/<your-username>) を使用します。 自動化には、クラスター ライブラリまたは init スクリプトを使用します。

どのような認証方法がサポートされていますか?

認証では、Databricks CLI と ~/.databrickscfg プロファイル ファイルが使用されます。 SSH キーは SSH トンネルによって処理されます。

クラスターから外部データベースまたはサービスに接続できますか?

はい。クラスター ネットワークで送信接続が許可され、必要なライブラリがある限りです。

追加の IDE 拡張機能を使用できますか?

ほとんどの拡張機能は、IDE とクラスターに応じて、リモート SSH セッション内にインストールされている場合に機能します。 Visual Studio Code では、既定ではリモート ホストにローカル拡張機能はインストールされません。 拡張機能パネルを開き、リモート ホストでローカル拡張機能を有効にすると、手動でインストールできます。 また、特定の拡張機能を常にリモートでインストールするように Visual Studio Code を構成することもできます。 Databricks への接続を参照してください。

SSH トンネルはPrivate Linkをサポートしていますか?

はい。ただし、ワークスペース管理者は、Visual Studio Codeおよび Cursor 拡張機能マーケットプレースの URL を許可する必要があります。 ローカル コンピューターには、インターネットにアクセスする機能も必要です。