Skip to main content

​
배포 아키텍처: 코드에서 실행까지

Databricks Apps의 배포 과정을 이해하면 배포 실패 시 문제를 빠르게 진단할 수 있습니다. 배포는 크게 5단계 로 진행됩니다.
단계동작소요 시간실패 시 증상
1. 소스 업로드로컬 파일이 Databricks 컨트롤 플레인으로 전송수 초”파일 크기 초과” 에러 (개별 10MB 제한)
2. 의존성 설치requirements.txt 기반 패키지 설치1~5분ModuleNotFoundError, 빌드 타임아웃
3. 컨테이너 시작app.yaml의 command로 앱 프로세스 시작수 초command 오류, 포트 바인딩 실패
4. 헬스체크지정된 포트에서 HTTP 응답 확인30초~2분앱이 포트에 바인딩하지 않음, Crash
5. URL 라우팅리버스 프록시에 앱 URL 등록수 초내부 라우팅 오류 (드물게 발생)
참고 배포 시간의 핵심: 전체 배포 시간의 대부분은 2단계(의존성 설치) 에서 소요됩니다. torch, tensorflow 같은 대용량 패키지가 있으면 10분 이상 걸릴 수 있습니다. 이미 설치된 패키지가 동일하면 캐시가 활용되어 재배포 시간이 크게 단축됩니다. requirements.txt에서 버전을 고정하면 캐시 적중률이 높아져 배포 속도가 빨라집니다.

​
배포 전략: Databricks Apps는 어떻게 배포하는가?

Databricks Apps는 롤링 업데이트(Rolling Update) 방식을 사용합니다. 새 버전의 컨테이너가 시작되어 헬스체크를 통과하면, 이전 버전의 컨테이너가 종료됩니다.
배포 전략Databricks Apps 지원설명
롤링 업데이트기본 동작새 버전이 준비되면 이전 버전 교체. 짧은 전환 시간 발생
블루-그린 배포수동 구현 가능별도 앱(v2)을 만들어 테스트 후 전환. 롤백이 빠름
카나리 배포지원하지 않음일부 트래픽만 새 버전으로 보내는 것은 불가
주의 배포 중 다운타임: 롤링 업데이트 중에 짧은 시간(수 초~수십 초) 동안 앱 접속이 불안정할 수 있습니다. 프로덕션 앱에서 무중단 배포가 필요하면, 별도 앱으로 블루-그린 배포를 수동으로 구성하는 것을 권장합니다.

​
전체 흐름

[로컬 개발] → [로컬 테스트] → [워크스페이스 배포] → [설정/리소스 연결] → [운영]
이 흐름의 각 단계는 독립적인 목적을 가지고 있습니다. 로컬 개발 에서는 빠른 반복으로 코드를 작성하고, 로컬 테스트 에서는 Databricks 인증과 리소스 접근이 정상적인지 검증하며, 워크스페이스 배포 에서는 실제 환경에 앱을 올리고, 운영 에서는 모니터링과 유지보수를 수행합니다.

​
1. 로컬 개발 환경 설정

​
필수 도구 설치

# Databricks CLI 설치
pip install databricks-cli
# 또는
brew install databricks
이 명령은 Databricks CLI를 설치합니다. CLI는 앱 생성, 배포, 상태 확인, 로그 조회 등 모든 배포 작업을 커맨드라인에서 수행할 수 있게 합니다. 
# 인증 설정 (OAuth 기반 — 권장)
databricks auth login --host https://<workspace-url>
이 명령은 브라우저 기반 OAuth 인증을 시작합니다. PAT(Personal Access Token)보다 OAuth가 권장되는 이유는 토큰 자동 갱신이 지원되고, 토큰이 파일에 평문으로 저장되지 않기 때문입니다. 
# 인증 확인
databricks current-user me
이 명령으로 인증이 정상적으로 설정되었는지 확인합니다. 현재 로그인한 사용자 정보가 반환되면 인증이 올바르게 구성된 것입니다.

​
프로젝트 구조

선호하는 IDE(VS Code, PyCharm, IntelliJ 등)에서 개발합니다. Databricks VS Code Extension 사용을 권장합니다. 
my-app/
├── app.py              # 앱 코드
├── app.yaml            # 앱 설정 (런타임, 리소스, 환경 변수)
├── requirements.txt    # Python 의존성
└── static/             # 정적 파일 (선택)
이 4개 파일이 Databricks App의 전체입니다. app.py가 비즈니스 로직, app.yaml이 실행 환경, requirements.txt가 의존성, static/이 정적 에셋입니다.

​
app.yaml 예시

command:
  - "streamlit"
  - "run"
  - "app.py"
  - "--server.port"
  - "$DATABRICKS_APP_PORT"

env:
  - name: "ENVIRONMENT"
    value: "production"

resources:
  - name: "sql-warehouse"
    sql_warehouse:
      id: "abc123def456"
      permission: "CAN_USE"
  - name: "serving-endpoint"
    serving_endpoint:
      name: "my-model-endpoint"
      permission: "CAN_QUERY"
이 예시는 Streamlit 앱의 전형적인 설정입니다. command로 Streamlit을 시작하고, env로 환경 정보를 주입하며, resources로 SQL Warehouse와 Serving Endpoint에 대한 접근을 선언합니다.

​
2. 로컬 테스트

로컬 테스트는 배포 전 반드시 거쳐야 할 단계 입니다. 배포 후 오류를 발견하면 코드 수정 후 재배포 후 대기(2~5분)의 사이클을 반복해야 하지만, 로컬에서는 즉시 확인할 수 있습니다. 
# Databricks CLI 로컬 실행 (권장 — Databricks 인증, 환경 변수 자동 처리)
databricks apps run-local --prepare-environment --debug
--prepare-environment는 app.yaml에 정의된 모든 환경변수와 리소스 참조를 로컬 환경에 자동으로 설정합니다. --debug는 상세 로그를 출력하여 인증 문제나 리소스 접근 오류를 즉시 확인할 수 있게 합니다. 또는 프레임워크별로 직접 실행: 
# Streamlit
streamlit run app.py

# Flask
gunicorn app:app -w 4

# FastAPI
uvicorn app:app --reload

# Gradio
python app.py
직접 실행할 때는 DATABRICKS_WAREHOUSE_ID, DATABRICKS_HOST 등의 환경변수를 수동으로 설정해야 합니다.
참고 run-local vs 직접 실행: databricks apps run-local은 app.yaml에 정의된 환경 변수와 리소스를 자동으로 주입합니다. 직접 실행 시에는 환경 변수를 수동으로 설정해야 합니다.
주의 로컬 테스트의 한계: 로컬에서는 Databricks의 리버스 프록시, SSL 종료, 포트 매핑 등이 없으므로, 네트워크 관련 문제는 로컬에서 재현되지 않을 수 있습니다. 코드 로직, 데이터 접근, 인증 문제는 로컬에서 검증하고, 네트워크 관련 문제는 배포 후 확인하세요.

​
3. Databricks CLI deploy 명령어

​
기본 배포

# 로컬 소스 코드를 워크스페이스에 배포
databricks apps deploy <app-name> --source-code-path /path/to/local/app
이 명령은 지정된 디렉토리의 모든 파일을 패키징하여 Databricks에 업로드하고, 컨테이너 빌드와 앱 실행을 트리거합니다. 10MB를 초과하는 개별 파일이 있으면 배포가 실패합니다.

​
배포 상태 확인

# 배포 상태 조회
databricks apps get <app-name>

# 배포 로그 확인 (디버깅 시)
databricks apps logs <app-name>
get 명령은 앱의 현재 상태, URL, 서비스 프린시펄 정보, 마지막 배포 시간을 반환합니다. logs 명령은 Python의 print() 출력, 프레임워크의 로그 메시지, 에러 트레이스백을 보여줍니다.

​
앱 중지/재시작

# 앱 중지
databricks apps stop <app-name>

# 앱 시작
databricks apps start <app-name>
앱을 중지하면 과금이 중지됩니다. 인메모리 상태는 초기화되므로 영속적 데이터는 미리 저장해야 합니다.