SSH 터널을 사용하여 Databricks에 연결

중요합니다

이 기능은 베타 버전으로 제공됩니다.

Databricks에서 제공하는 SSH 터널을 사용하면 SSH 터널을 사용하여 작업 영역에 액세스하고 IDE의 Databricks 컴퓨팅에서 워크로드를 대화형으로 실행할 수 있습니다. 간단하게 설정하고, 환경 관리가 필요하지 않으며, Databricks 작업 영역 내에서 모든 코드와 데이터를 안전하게 유지합니다.

요구 사항

SSH 터널을 사용하여 Databricks 서버리스 또는 클래식 컴퓨팅에 연결하려면 다음이 있어야 합니다.

로컬 머신에 Databricks CLI 버전 1.5.0 이상이 설치되어 있고 인증이 설정되어 있어야 합니다. Databricks CLI 설치 또는 업데이트를 참조하세요.
다음 중 하나에 해당하는 경우:
- Visual Studio Code 버전: 1.110.0(유니버설) 이상 및 원격 - SSH 확장(1.0.46 이상)이 설치되었습니다.
- 커서 버전: 2.6.11(유니버설) 이상

서버리스 GPU 컴퓨팅에 연결하려면 AI 런타임 기능을 사용하도록 설정해야 합니다. AI 런타임을 참조하세요.

클래식(전용 단일 사용자) 컴퓨팅에 연결하려면 다음을 수행합니다.

컴퓨팅은 Databricks Runtime 17.0 이상을 실행해야 합니다. 전용 컴퓨팅 개요를 참조하세요.
Unity 카탈로그를 사용하도록 설정해야 합니다.
컴퓨팅 정책이 있는 경우 작업 실행을 금지해서는 안 됩니다.
전용 컴퓨팅에 Databricks Container Services를 사용하는 경우 Docker 이미지가 설치되어 있어야 합니다openssh-server.

서버리스 컴퓨팅에 연결

서버리스 컴퓨팅에 연결하려면 IDE 내의 databricks ssh connect 터미널에서 명령을 실행합니다. 별도의 설정 단계가 필요하지 않습니다.

명령에 대한 databricks ssh connect 자세한 내용은 명령 그룹을 참조ssh하세요.

databricks ssh connect

이 --accelerator 옵션을 사용하여 AI 런타임에 연결합니다.

databricks ssh connect --accelerator=GPU_1xA10

databricks ssh connect 는 단일 노드에서 대화형 세션을 제공합니다. 장시간 실행되는 학습 작업이나 다중 노드 분산 학습의 경우에는 대신 air CLI를 사용해 워크로드를 제출하세요. AI 런타임 CLI를 참조하세요.

연결한 후 개발 환경 설정을 완료합니다. 프로젝트 열기를 참조하세요.

서버리스 컴퓨팅에 연결하고 Visual Studio Code 또는 커서에서 세션을 시작하려면 이 --ide 옵션을 사용합니다. CLI는 홈 작업 영역 폴더를 가리키는 IDE 창을 엽니다.

databricks ssh connect --ide=vscode

클래식 컴퓨팅에 연결

클래식 컴퓨팅에 연결하려면 먼저 SSH 연결을 설정한 다음 IDE를 사용하거나 터미널에서 연결합니다.

SSH 연결 설정

비고

SSH 연결을 설정하는 것은 클래식 컴퓨팅에 연결하는 경우에만 필요합니다.

먼저 databricks ssh 설치 명령을 사용하여 SSH 터널을 설정합니다. 연결에 대한 이름을 제공합니다. 예를 들어 다음으로 바꿉다<connection-name>.my-connection

databricks ssh setup --name <connection-name>

CLI는 클러스터를 선택하라는 메시지를 표시합니다. 다음을 사용하여 직접 지정할 수도 있습니다.--cluster <cluster-id>

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

비고

IntelliJ 사용자의 경우, Databricks는 --auto-start-cluster=false를 설치 명령에 추가하고 연결하기 전에 클러스터를 수동으로 시작할 것을 권장합니다. JetBrains IDE는 시작 시 구성된 모든 클러스터를 시작하여 예기치 않은 컴퓨팅 요금이 발생할 수 있기 때문입니다.

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는 새 창에서 연결을 진행합니다.

IntelliJ IDE를 사용하여 연결

원격 서버 자습서에 따라 설정합니다.
새 연결 화면에서 다음을 입력합니다.
- 사용자 이름: root
- 호스트: <connection-name>

터미널을 사용하여 연결

ssh <connection-name>

프로젝트 열기

기본적으로 databricks ssh connect 명령은 임시 디렉터리로 열립니다. 작업 영역 파일에 액세스하려면 IDE 또는 터미널에서 작업 영역 디렉터리로 이동합니다.

Visual Studio Code 또는 커서의 명령 팔레트(Cmd/Ctrl+Shift+P)에서 폴더 열기를 선택하고 으로 이동합니다/Workspace/Users/<your-username>.
터미널 창에서 디렉터리를 변경합니다. cd /Workspace/Users/<your-username>

비고

에 있는 /Workspace/Volumes파일 및 /dbfs 클러스터를 다시 시작할 때 유지됩니다. 및 /home기타 로컬 경로의 /root파일은 임시이며 다시 시작할 때 손실됩니다.

코드 실행(Visual Studio Code 또는 커서)

SSH 터널을 사용하여 코드를 실행하려면 Databricks 가상 환경을 설정해야 합니다. 이 환경에는 모든 기본 제공 DBR 라이브러리 및 컴퓨팅 범위 라이브러리가 포함됩니다.

명령 팔레트(Cmd/Ctrl+Shift+P)를 열고 Python 선택합니다. 인터프리터를 선택합니다.
pythonEnv-xxx 목록에서 가상 환경을 선택합니다. 플래그를 사용하여 --base-environment Python 종속성을 설정하는 경우 옵션 목록에서 더 긴 가상 환경 이름을 선택합니다. 가상 환경이 표시되지 않는 경우:
1. IDE 내의 터미널에서 실행 echo $DATABRICKS_VIRTUAL_ENV 합니다.
  
  출력 예제: /local_disk0/.ephemeral_nfs/envs/pythonEnv-xxx/bin/python
2. 전체 출력을 Python 인터프리터 경로로 붙여넣습니다. 인터프리터 프롬프트를 선택합니다.
새 터미널을 열면 가상 환경이 자동으로 활성화됩니다.
Jupyter Notebook을 실행하려면 가상 환경이 커널로 선택되어 있는지 확인합니다. 노트북 오른쪽 상단의 커널 선택을 클릭합니다.

표준 Python 및 Jupyter 확장 프로그램을 사용하여 Python 파일 및 .ipynb notebook을 실행하고 디버그합니다.

서버리스 컴퓨팅의 Python 파일에서 Spark를 사용하려면 세션을 명시적으로 초기화합니다.

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

종속성 관리

컴퓨팅 유형 및 요구 사항에 따라 작업 영역 기본 환경, 클러스터 라이브러리, 초기화 스크립트 또는 Notebook을 사용하여 종속성을 관리합니다.

작업 영역 기본 환경(서버리스 및 AI 런타임에 권장됨)

비고

이 기능을 사용하려면 작업 미리 보기 에서 서버리스 작업 영역 기본 환경 지원을 사용하도록 설정해야 합니다. Azure Databricks 미리 보기 관리를 참조하세요.

서버리스 환경 버전 4 이하의 작업 영역 기본 환경을 사용하여 Python 종속성을 미리 구성합니다. 작업 영역 UI 또는 Databricks CLI databricks 환경 create-workspace-base-environment 명령을 사용하여 기본 환경을 만듭니다.

연결할 때 옵션을 --base-environment 사용하여 환경을 지정합니다.

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

허용되는 형식에 대한 자세한 내용은 databricks ssh connect를 참조하세요.

클러스터 라이브러리(클래식 컴퓨팅에 권장)

컴퓨팅 > 라이브러리에서 작업 영역 UI를 사용하여 종속성을 설치합니다. 이러한 항목은 클러스터 다시 시작에서도 유지되며 pythonEnv-xxx에서 사용할 수 있습니다. 클러스터 라이브러리를 참조하세요.

비 Python 종속성

비 Python 종속성을 유지하려면 컴퓨팅이 시작될 때 패키지를 설치하는 init 스크립트를 사용합니다. 필요에 따라 패키지를 Unity 카탈로그 볼륨에 저장하고 init 스크립트에서 참조합니다. init 스크립트란?을 참조하세요.

프로젝트 전용 노트북 설정

프로젝트 범위의 종속성을 위해, 각 세션 시작 시 명령이 포함된 %pip install Notebook을 실행합니다.

# 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 실행기 노드로 전파합니다. 이렇게 하면 사용자 지정 종속성이 있는 UDF(사용자 정의 함수)를 사용할 수 있습니다.

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

세션이 10분 이내에 다시 연결되는 경우 Notebook을 다시 실행할 필요가 없습니다. 이것은 SSH 구성에서 -shutdown-delay을 사용하여 설정할 수 있습니다.

비고

동일한 클러스터의 여러 SSH 세션은 하나의 가상 환경을 공유합니다.

Git 사용

비고

이 기능을 사용하려면 Git 폴더 미리 보기에 대한 Git CLI 지원이 필요합니다. Azure Databricks 미리 보기 관리를 참조하세요.

새로 만든 Git 폴더와 Databricks 작업 영역에서 구성한 Git 자격 증명을 사용하여 SSH 터널에서 Git CLI를 사용할 수 있습니다. Git CLI 명령 사용(베타)을 참조하세요.

CLI가 자격 증명을 자동으로 인식하지 못하고 자격 증명 입력을 요청하는 경우, Git 제공업체를 Databricks에 연결해야 합니다. Databricks에 Git 공급자 연결을 참조하세요.

제한점

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

공유 클러스터는 지원되지 않습니다.
Visual Studio Code 및 SSH 터널에 대한 Databricks 확장은 아직 호환되지 않으므로 함께 사용하면 안 됩니다.
외부에서 /Workspace/Volumes편집된 파일은 /dbfs 클러스터를 다시 시작할 때 손실됩니다.
클러스터당 최대 10개의 SSH 연결이 허용됩니다.
비활성 세션은 1시간 후에 삭제될 수 있습니다.
SSH 터널은 다른 원격 환경 또는 Docker 컨테이너에서 시작할 수 없습니다.
3개 이상의 Jupyter Notebook이 동시에 열려 있는 경우 성능 또는 연결 문제가 발생할 수 있습니다. 이 제한 사항은 향후 릴리스에서 해결될 예정입니다.

Databricks Notebook의 차이점

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

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

Troubleshooting

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

SSH 연결 실패 또는 타임아웃

클러스터가 작업 영역 UI에서 실행되고 있는지 확인합니다.
아웃바운드 포트 22가 열려 있고 랩톱, 네트워크 및 VPN에서 허용되는지 확인합니다.
SSH 시간 제한을 늘입니다. Visual Studio Code 또는 커서를 사용하여 연결을 참조하세요.
주요 불일치 오류가 발생할 경우, ~/.databricks/ssh-tunnel-keys를 삭제하고 databricks ssh setup을 다시 실행합니다.
"원격 호스트 식별이 변경되었습니다." 오류의 ~/.ssh/known_hosts 경우 파일을 확인하고 클러스터와 관련된 항목을 삭제합니다.
SSH 세션은 1시간 후에 삭제될 수 있으며 단일 클러스터에 10개 이하의 SSH 연결을 만들 수 있습니다. 제한 사항을 참조하세요.

`code` 명령을 찾을 수 없음

Error: exec: "code": executable file not found in $PATH가 표시되면 명령 팔레트(Cmd/Ctrl+Shift+P)를 열고 셸 명령: PATH에 'code' 명령 설치를 선택한 다음 IDE 또는 터미널 세션을 다시 시작하세요.

CLI 인증 오류

Databricks CLI 프로필이 유효한지 databricks auth login을(를) 사용하여 확인하십시오.
클러스터에 대한 권한이 있는지 CAN MANAGE 확인합니다.

내 코드가 작동하지 않음

Databricks 가상 환경을 설정했는지 확인하려면 코드 실행(Visual Studio Code 또는 커서)
IPYNB Notebook 및 *.py Databricks Notebook은 Databricks 글로벌에 액세스할 수 있지만 Python *.py 파일은 액세스할 수 없습니다. Databricks Notebook의 차이점을 참조하세요.

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

/Workspace, /Volumes, /dbfs 탑재 지점의 파일은 클러스터를 다시 시작할 때도 그대로 유지됩니다. 및 /home기타 로컬 경로의 /root파일은 임시이며 다시 시작할 때 손실됩니다.
영구 종속성에 클러스터 라이브러리 관리를 사용합니다. 필요한 경우 init 스크립트를 사용하여 다시 설치를 자동화합니다. init 스크립트란?을 참조하세요.

WSL(Windows SSH 설정이 실패함)

Windows에서 databricks ssh setup를 WSL이 아닌 환경에서 직접 실행합니다. Windows Visual Studio Code 인스턴스는 WSL 쪽에서 만든 SSH 구성을 찾을 수 없습니다.

자주 묻는 질문(FAQ)

SSH 터널은 Databricks Connect와 어떻게 다른가요?

Databricks Connect를 사용하면 Spark API를 사용하여 코드를 작성하고 로컬 Spark 세션이 아닌 Databricks 컴퓨팅에서 원격으로 실행할 수 있습니다. Databricks Visual Studio Code 확장은 Databricks Connect를 사용하여 Databricks에서 사용자 코드의 기본 제공 디버깅을 제공합니다.

SSH 터널을 사용하면 IDE에서 작업 영역에 액세스하고 전체 개발 환경을 컴퓨팅으로 이동할 수 있습니다. Python, 커널 및 모든 실행은 컴퓨팅 리소스에 대한 모든 액세스 권한이 있는 Databricks에서 실행됩니다.

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

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

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

Visual Studio Code 및 커서가 공식적으로 지원됩니다. SSH 기능을 사용하는 모든 IDE는 호환되지만 VS Code 및 커서만 테스트됩니다.

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

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

SSH 터널을 사용하여 연결할 때 클러스터가 자동으로 시작되나요?

예, 하지만 연결 시간 제한보다 클러스터를 시작하는 데 시간이 오래 걸리면 연결 시도가 실패합니다. 이를 방지하려면, 명령 팔레트에서 또는 를 사용하여 remote.SSH.connectTimeout 값을 늘려 시간 초과 오류의 가능성을 더 줄입니다.

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

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

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

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

작동하지 않을 때 클러스터를 중지하고 요금을 방지하려면 어떻게 해야 하나요?

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

작업 영역 UI에서 클러스터에 짧은 자동 종료 정책을 설정합니다. 연결을 끊은 후 SSH 서버는 기간(기본값: 10분)을 기다린 shutdown-delay 후 클러스터의 유휴 시간 제한이 적용됩니다.

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

클러스터를 다시 시작한 후 세션 중에 설치된 종속성이 손실됩니다. 요구 사항 및 설정 스크립트에 영구 스토리지(/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을 허용 목록에 추가해야 합니다. 로컬 머신에도 인터넷에 액세스할 수 있는 기능이 있어야 합니다.

피드백

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

Last updated on 2026-07-13