Databricks SSH 터널

중요합니다

Databricks SSH 터널은 베타에 있습니다.

Databricks SSH 터널을 사용하면 IDE를 Databricks 컴퓨팅에 연결할 수 있습니다. 간단하게 설정하고, 클러스터에서 코드를 대화형으로 실행하고 디버그할 수 있으며, 환경 불일치를 줄이고, Databricks 작업 영역 내에서 모든 코드와 데이터를 안전하게 유지합니다.

요구 사항

SSH 터널을 사용하려면 다음이 있어야 합니다.

로컬 컴퓨터에 Databricks CLI 버전 0.269 이상이 설치되고 인증이 구성되어야 합니다. 설치를 참조 하세요.
전용(단일 사용자) 액세스 모드를 사용하여 Databricks 작업 영역에서 컴퓨팅합니다. 전용 컴퓨팅 개요를 참조하세요.
- 컴퓨팅은 Databricks Runtime 17.0 이상을 사용해야 합니다.
- Unity 카탈로그를 사용하도록 설정해야 합니다.
- 컴퓨팅 정책이 있는 경우 작업 실행을 금지해서는 안 됩니다.

SSH 터널 설정

먼저 databricks ssh 설치 명령을 사용하여 SSH 터널을 설정합니다. 터널의 이름을 <connection-name>에서 예를 들어 my-tunnel로 바꾸십시오.

databricks ssh setup --name <connection-name>

CLI는 클러스터를 선택하라는 메시지를 표시하거나 전달 --cluster <cluster-id>하여 클러스터 ID를 제공할 수 있습니다.

비고

IntelliJ의 경우 Databricks는 설정 명령에 –-auto-start-cluster=false를 포함하는 것을 권장합니다. JetBrains IDE를 시작하면 모든 클러스터가 자동으로 시작되어 의도하지 않은 컴퓨팅 비용이 발생할 수 있습니다. 이 옵션을 설정하는 경우 작업 영역에서 클러스터를 시작하여 SSH 터널을 시작해야 합니다.

Databricks에 연결

다음으로, IDE 또는 터미널을 사용하여 Databricks에 연결합니다.

Visual Studio Code 또는 커서를 사용하여 연결

Visual Studio Code의 경우 원격 SSH 확장을 설치합니다. 커서에는 원격 SSH 확장이 포함됩니다.
IDE 주 메뉴에서명령 팔레트> 클릭합니다. Remote-SSH: 설정을 선택합니다. 또는 기본 설정을 선택합니다. JSON(사용자 설정)을 열어 직접 수정 settings.json 합니다.
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 in settings.json)의 값을 늘려 시간 제한 오류의 가능성을 더 줄입니다. 기본 시간 제한은 360입니다.
명령 팔레트에서 Remote-SSH를 선택합니다. 호스트에 연결합니다.
드롭다운에서 첫 번째 단계에서 설정한 터널을 선택합니다. IDE는 새 창에서 연결을 진행합니다.

비고

컴퓨트가 실행되고 있지 않으면 시작됩니다. 그러나 컴퓨팅을 시작하는 데 시간 제한보다 오래 걸리는 경우 SSH 연결 시도가 실패합니다.
서버 유형에 대한 메시지가 표시되면 Linux 를 선택합니다.

IntelliJ IDE를 사용하여 연결

원격 개발 자습서에 따라 설정합니다.
새 연결 화면에서 다음을 입력합니다.

사용자 이름: root호스트:<connection-name>

터미널을 사용하여 연결

명령줄에서 Databricks에 연결하려면 ssh 명령에 연결 이름을 제공해야 합니다. 예를 들어:

ssh my-tunnel

프로젝트 열기

초기 연결은 열려 있는 폴더가 없는 빈 IDE 창을 엽니다. Visual Studio Code에서 명령 팔레트의 폴더 열기 명령을 사용하여 원하는 프로젝트를 엽니다.
영구 스토리지로 작업 영역 마운트(/Workspace/Users/<your-username>)를 사용합니다.

코드 실행(Visual Studio Code)

Python 프로젝트를 열면 Python 확장에서 가상 환경을 자동으로 검색할 수 있지만 올바른 환경을 수동으로 활성화해야 합니다. 명령 팔레트에서 인터프리터 명령을 선택하고 환경을 pythonEnv-xxx선택합니다. 모든 기본 제공 Databricks 런타임 라이브러리 또는 클러스터에 전역적으로 설치한 모든 라이브러리에 액세스할 수 있습니다.
Python 프로젝트로 인식할 수 없는 폴더를 열 때와 같이 Python 확장에서 가상 환경(venv)을 자동으로 검색할 수 없는 경우도 있습니다. 이 문제를 해결하려면 터미널을 열고 실행 echo $DATABRICKS_VIRTUAL_ENV한 다음, 경로를 복사하여 Python: 인터프리터 선택 명령에서 사용합니다.

venv를 선택한 후 Python 또는 Jupyter 확장에서 제공하는 일반 실행 또는 디버그 작업을 사용하여 Python 파일 또는 Notebook을 실행할 수 있습니다.

Python 종속성 관리

필요한 종속성을 설치하는 가장 간단한 방법은 작업 영역 UI를 사용하는 것입니다. 컴퓨팅 범위 라이브러리를 참조하십시오. 이 방법을 사용하면 클러스터에 대한 종속성을 전역적으로 설치합니다. 클러스터를 다시 시작할 때마다 라이브러리를 다시 설치할 필요가 없습니다.

그러나 특정 프로젝트로 범위가 지정된 프로그래밍 방식 설정의 경우 Notebook 범위 설치를 사용합니다.

프로젝트별 설정 Notebook

특정 프로젝트에 대한 종속성을 관리하려면 다음을 수행합니다.

setup.ipynb 프로젝트에 파일을 만듭니다.
ssh CLI는 Python 환경(pythonEnv-xxx)을 생성하며, 이 환경에는 이미 기본 제공된 Databricks 런타임 라이브러리 또는 컴퓨트 범위 라이브러리가 포함되어 있습니다. 이 pythonEnv-xxx 환경에 Notebook을 연결합니다.
%pip install 명령을 사용하여 종속성을 설치하세요.
- %pip install . pyproject.toml로 범위를 축소해 %pip install .<group>가 있는 경우
- %pip install -r dependencies.txt 가지고 있는 경우 dependencies.txt
- %pip install /Volumes/your/wheel.whl 사용자 지정 라이브러리를 만들고 휠로 업로드한 경우(또는 /Workspace 경로)
%pip 명령에는 Databricks에 특화된 논리가 추가적인 안전 장치와 함께 포함되어 있습니다. 또한 이 논리는 연결된 드라이버 노드뿐만 아니라 모든 Spark 실행기 노드에서 종속성을 사용할 수 있도록 합니다. 이렇게 하면 사용자 지정 종속성이 있는 UDF(사용자 정의 함수)를 사용할 수 있습니다.

더 많은 사용 예제는 명령을 사용하여 라이브러리 %pip 관리를 참조하세요.

새 ssh 세션을 설정할 때마다 이 Notebook을 실행합니다. 기존 ssh 세션을 삭제하고 10분 안에 클러스터에 다시 연결하는 경우 종속성을 다시 설치할 필요가 없습니다. (시간은 로컬 ssh 구성의 옵션으로 -shutdown-delay=10m 구성할 수 있습니다.)

비고

동일한 클러스터에 동시에 연결된 여러 ssh 세션이 있는 경우 동일한 가상 환경을 사용합니다.

제한점

Databricks SSH 터널에는 다음과 같은 제한 사항이 있습니다.

Visual Studio Code 및 Databricks SSH 터널에 대한 Databricks 확장은 아직 호환되지 않으므로 함께 사용하면 안 됩니다.
Databricks 작업 영역 UI를 통해 작업 영역에서 만든 Git 폴더 는 Git CLI 및 IDE git 통합에 의해 git 리포지토리로 인식되지 않습니다. 이러한 폴더에는 .git 메타데이터가 없기 때문에 이 문제를 해결하려면 SSH 터널에서 Git을 사용하는 방법을 참조하세요.
연결하는 클러스터의 홈 및 루트 탑재는 임시입니다. 클러스터를 다시 시작할 때 클러스터의 콘텐츠는 유지되지 않습니다.

Databricks Notebook의 차이점

SSH 터널을 사용하는 경우 Notebook에는 몇 가지 차이점이 있습니다.

Python 파일은 Databricks 전역(예: spark 또는 dbutils)을 정의하지 않습니다. 명시적으로 from databricks.sdk.runtime import spark를 사용하여 가져와야 합니다.
ipynb Notebook의 경우 다음 기능을 사용할 수 있습니다.
- Databricks globals: 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 ----------
```

Troubleshooting

이 섹션에는 일반적인 문제를 해결하는 방법에 대한 정보가 포함되어 있습니다.

SSH 연결 실패 또는 타임아웃

클러스터가 중지 또는 시작이 아니라 Databricks UI에서 실행 중인지 확인합니다.
아웃바운드 포트 22가 열려 있으며 노트북/네트워크/VPN에서 허용되었는지 확인하세요.
IDE에서 SSH 연결 시간 제한을 늘입니다. Visual Studio Code 또는 커서를 사용하여 연결을 참조하세요.
공개 또는 프라이빗 키 불일치 오류가 표시되면 ~/.databricks/ssh-tunnel-keys 폴더를 삭제해 보세요.
"원격 호스트 식별이 변경되었습니다." 오류가 표시되면 파일을 확인하고 ~/.ssh/known_hosts 클러스터와 관련된 항목을 삭제합니다.
SSH 세션이 1시간 후에 삭제되는 경우 알려진 제한 사항입니다. 제한 사항을 참조하세요.
단일 클러스터에 대해 10개 이하의 ssh 연결이 허용됩니다.

CLI 인증 오류

Databricks CLI 프로필이 유효하고 인증()되어databricks auth login 있는지 확인합니다.
와 같은 CAN MANAGE적절한 클러스터 권한이 있는지 확인합니다.

클러스터를 다시 시작한 후 파일이 사라지거나 환경이 다시 설정됩니다.

만 /Workspace, /Volumes및 /dbfs 탑재는 영구적입니다. 모든 /home, /root 등의 데이터는 다시 시작한 후 지워집니다.
영구 종속성에 클러스터 라이브러리 관리를 사용합니다. 필요한 경우 init 스크립트를 사용하여 다시 설치를 자동화합니다. init 스크립트란?을 참조하세요.

IDE에서 "Git 리포지토리 아님" 오류 또는 누락된 git 기능

Git은 터미널을 사용하여 /Workspace/Users/<your-username> 복제하는 경우에만 작동합니다. 웹에서 만든 폴더에는 .git 메타데이터가 없습니다. SSH 터널에서 Git을 사용하는 방법을 참조하세요.

내 코드가 작동하지 않음

모든 Databricks 런타임 종속성에 액세스할 수 있는 올바른 Python 인터프리터를 선택해야 합니다.
- Python 프로젝트를 열면 Python 확장에서 가상 환경을 자동으로 검색할 수 있지만 올바른 환경을 수동으로 활성화해야 합니다. Python 실행: 인터프리터 명령을 선택하고pythonEnv-xxx 환경을 선택합니다. 기본 제공 Databricks 런타임 라이브러리 및 귀하가 클러스터에 전역적으로 설치한 것에 모두 액세스할 수 있습니다.
- Python 프로젝트로 인식할 수 없는 폴더를 열 때와 같이 Python 확장에서 가상 환경을 자동으로 검색할 수 없는 경우도 있습니다. 터미널을 열고 실행 echo $DATABRICKS_VIRTUAL_ENV한 다음, 경로를 복사하여 Python: 인터프리터 선택 명령에서 사용할 수 있습니다.
IPYNB Notebook 및 *.py Databricks Notebook은 Databricks 글로벌에 액세스할 수 있지만 Python *.py 파일은 액세스할 수 없습니다. Databricks Notebook의 차이점을 참조하세요.

WSL의 창에서 ssh 연결을 설정할 수 없습니다.

Databricks는 Windows에서 직접 ssh 설정을 수행하는 것이 좋습니다. WSL 쪽에서 설정한 다음 Windows 버전의 Visual Studio Code를 사용하는 경우 필요한 ssh 구성을 찾을 수 없습니다.

자주 묻는 질문(FAQ)

내 코드와 데이터는 어떻게 보호되는가?

모든 코드는 Databricks 클라우드 VPC(가상 프라이빗 클라우드) 내에서 실행됩니다. 어떤 데이터나 코드도 보안 환경을 벗어나지 않습니다. SSH 트래픽은 완전히 암호화됩니다.

지원되는 IDE는 무엇인가요?

Visual Studio Code 및 커서는 공식적으로 지원되지만 Databricks SSH 터널은 SSH 기능이 있는 모든 IDE와 호환됩니다.

IDE에서 모든 Databricks Notebook 기능을 사용할 수 있나요?

와 같은 display()dbutils%sql 일부 기능은 제한 사항 또는 수동 설정과 함께 사용할 수 있습니다. Databricks Notebook의 차이점을 참조하세요.

여러 사용자가 동일한 클러스터에서 한 번에 개발할 수 있나요?

아니요.

SSH 터널을 통해 연결할 때 클러스터가 자동으로 시작되나요?

예, 하지만 연결 시간 제한보다 클러스터를 시작하는 데 시간이 오래 걸리면 연결 시도가 실패합니다.

클러스터가 실행 중인지 어떻게 알 수 있나요?

Databricks 작업 영역 UI에서 컴퓨팅 으로 이동하고 클러스터의 상태를 확인합니다. 클러스터에는 SSH 터널 연결이 작동하기 위해 실행 중으로 표시되어야 합니다.

SSH/IDE 세션의 연결을 끊는 방법

IDE 창을 닫거나, IDE의 연결 끊기 옵션을 사용하거나, SSH 터미널을 닫거나, 터미널에서 명령을 실행하여 세션 연결을 exit 끊을 수 있습니다.

SSH 연결을 끊을 때 클러스터가 자동으로 중지됩니까?

아니요, ssh 서버에는 구성 가능한 종료 지연이 있으며 지정된 시간 동안 백그라운드에서 계속 실행됩니다(기본적으로 10m는 옵션을 수정하여 -shutdown-delay ssh 구성 ProxyCommand에서 변경할 수 있음). 시간 제한이 종료되면 서버가 종료되며 클러스터를 만드는 동안 구성하는 클러스터 유휴 시간 제한이 시작됩니다.

불필요한 요금을 방지하기 위해 클러스터를 중지하려면 어떻게 해야 하나요?

Databricks 작업 영역 UI에서 컴퓨팅 으로 이동하여 클러스터를 찾은 다음 종료 또는 중지를 클릭합니다.

영구 종속성을 어떻게 처리해야 하나요?

클러스터를 다시 시작한 후 세션 중에 설치된 종속성이 손실됩니다. 요구 사항 및 설정 스크립트에 영구 스토리지(/Workspace/Users/<your-username>)를 사용합니다. 자동화를 위해 클러스터 라이브러리 또는 init 스크립트를 사용합니다.

지원되는 인증 방법은 무엇인가요?

인증은 Databricks CLI 및 ~/.databrickscfg 프로필 파일을 사용합니다. SSH 키는 Databrick SSH 터널에서 처리됩니다.

클러스터에서 외부 데이터베이스 또는 서비스에 연결할 수 있나요?

예, 클러스터 네트워킹이 아웃바운드 연결을 허용하고 필요한 라이브러리가 있는 한.

추가 IDE 확장을 사용할 수 있나요?

대부분의 확장은 IDE 및 클러스터에 따라 원격 SSH 세션 내에 설치될 때 작동합니다. Visual Studio Code는 기본적으로 원격 호스트에 로컬 확장을 설치하지 않습니다. 확장 패널을 열고 원격 호스트에서 로컬 확장을 사용하도록 설정하여 수동으로 설치할 수 있습니다. 특정 확장을 항상 원격으로 설치하도록 Visual Studio Code를 구성할 수도 있습니다. Databricks에 연결을 참조하세요.

SSH 터널에서 Git을 사용하려면 어떻게 해야 하나요?

현재 Databricks 작업 영역 UI를 사용하여 만든 Git 폴더는 IDE에서 git 리포지토리로 인식되지 않습니다. 이 작업을 해결하려면 SSH 세션에서 git CLI를 사용하여 리포지토리를 영구 작업 영역 폴더로 복제합니다.

터미널을 열고 원하는 부모 디렉터리(예: cd /Workspace/Users/<your-username>)로 이동합니다.
해당 디렉터리에 리포지토리를 복제합니다.
Visual Studio Code에서 code <repo-name> 명령을 실행하여 새 창에서 이 폴더를 열거나 UI를 사용하여 새 창에서 폴더를 엽니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-01-16