배포 아키텍처: 코드에서 실행까지
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)을 만들어 테스트 후 전환. 롤백이 빠름 |
| 카나리 배포 | 지원하지 않음 | 일부 트래픽만 새 버전으로 보내는 것은 불가 |
주의 배포 중 다운타임: 롤링 업데이트 중에 짧은 시간(수 초~수십 초) 동안 앱 접속이 불안정할 수 있습니다. 프로덕션 앱에서 무중단 배포가 필요하면, 별도 앱으로 블루-그린 배포를 수동으로 구성하는 것을 권장합니다.
전체 흐름
1. 로컬 개발 환경 설정
필수 도구 설치
프로젝트 구조
선호하는 IDE(VS Code, PyCharm, IntelliJ 등)에서 개발합니다. Databricks VS Code Extension 사용을 권장합니다.app.py가 비즈니스 로직, app.yaml이 실행 환경, requirements.txt가 의존성, static/이 정적 에셋입니다.
app.yaml 예시
command로 Streamlit을 시작하고, env로 환경 정보를 주입하며, resources로 SQL Warehouse와 Serving Endpoint에 대한 접근을 선언합니다.
2. 로컬 테스트
로컬 테스트는 배포 전 반드시 거쳐야 할 단계 입니다. 배포 후 오류를 발견하면 코드 수정 후 재배포 후 대기(2~5분)의 사이클을 반복해야 하지만, 로컬에서는 즉시 확인할 수 있습니다.--prepare-environment는 app.yaml에 정의된 모든 환경변수와 리소스 참조를 로컬 환경에 자동으로 설정합니다. --debug는 상세 로그를 출력하여 인증 문제나 리소스 접근 오류를 즉시 확인할 수 있게 합니다.
또는 프레임워크별로 직접 실행:
DATABRICKS_WAREHOUSE_ID, DATABRICKS_HOST 등의 환경변수를 수동으로 설정해야 합니다.
참고run-localvs 직접 실행:databricks apps run-local은app.yaml에 정의된 환경 변수와 리소스를 자동으로 주입합니다. 직접 실행 시에는 환경 변수를 수동으로 설정해야 합니다.
주의 로컬 테스트의 한계: 로컬에서는 Databricks의 리버스 프록시, SSL 종료, 포트 매핑 등이 없으므로, 네트워크 관련 문제는 로컬에서 재현되지 않을 수 있습니다. 코드 로직, 데이터 접근, 인증 문제는 로컬에서 검증하고, 네트워크 관련 문제는 배포 후 확인하세요.
3. Databricks CLI deploy 명령어
기본 배포
배포 상태 확인
get 명령은 앱의 현재 상태, URL, 서비스 프린시펄 정보, 마지막 배포 시간을 반환합니다. logs 명령은 Python의 print() 출력, 프레임워크의 로그 메시지, 에러 트레이스백을 보여줍니다.
앱 중지/재시작
4. 환경 간 이동 (dev → staging → prod)
리소스를 하드코딩하지 않고app.yaml의 valueFrom을 사용하면, 코드 수정 없이 다른 워크스페이스로 앱을 이동할 수 있습니다. 이것이 리소스 추상화의 핵심 가치 입니다.
전략: 환경별 app.yaml 분리
app.py는 환경에 따라 변경되지 않습니다. 환경변수를 통해 Warehouse ID, Endpoint 이름 등이 주입되므로, 코드 수정 없이 설정 파일만 교체하면 다른 환경에 배포할 수 있습니다.
환경별 리소스 매핑 예시
아래 표는 동일한 앱이 환경에 따라 다른 리소스를 사용하는 예를 보여줍니다.| 리소스 | dev | staging | prod |
|---|---|---|---|
| SQL Warehouse | dev-warehouse-id | staging-warehouse-id | prod-warehouse-id |
| Serving Endpoint | model-dev | model-staging | model-prod |
| Secret Scope | dev-secrets | staging-secrets | prod-secrets |
참고 환경 분리 전략: 가장 간단한 방법은 환경별로 별도 앱을 생성하는 것입니다 (my-app-dev,my-app-staging,my-app-prod). 각 앱에서 UI Configure 화면에서 해당 환경의 리소스를 연결하면 됩니다.
5. CI/CD 파이프라인 구성 예시
프로덕션 앱은 수동 배포 대신 CI/CD 파이프라인을 통한 자동 배포 가 권장됩니다. 자동 배포는 인적 오류를 줄이고, 배포 이력을 추적 가능하게 하며, 일관된 배포 프로세스를 보장합니다.GitHub Actions 예시
아래 워크플로우는main 브랜치에 my-app/ 디렉토리의 변경이 푸시되면 자동으로 앱을 배포합니다.
paths: ['my-app/**']로 앱 코드가 변경될 때만 배포가 트리거됩니다.DATABRICKS_HOST와DATABRICKS_TOKEN은 GitHub Secrets 에 저장됩니다. 절대 코드에 직접 넣지 마세요.- 배포 후 상태 확인 단계를 추가하면 더 안전합니다.
Azure DevOps 예시
DATABRICKS_HOST와 DATABRICKS_TOKEN을 Pipeline Variables(Secret)로 설정하세요.
주의 보안 주의: CI/CD에서 Databricks 인증 정보는 반드시 GitHub Secrets 또는 해당 CI 도구의 시크릿 관리 기능을 사용하세요. 코드에 토큰을 직접 넣지 마세요.
참고 CI/CD 고급 패턴: 프로덕션 배포 파이프라인에서는 다음 단계를 추가하는 것이 좋습니다:
- 린트/테스트: 코드 품질 검사 및 단위 테스트 실행
- 스테이징 배포: 프로덕션 전 스테이징 환경에 먼저 배포
- 스모크 테스트: 스테이징에서 기본 기능 동작 확인
- 승인 게이트: 수동 승인 후 프로덕션 배포
- 프로덕션 배포: 메인 앱 배포
- 상태 검증: 배포 후 앱 상태가
Running인지 확인
다음 페이지: 모니터링, 스케일링, 비용, 롤백, 의존성 관리 내용은 Databricks Apps 운영 — 모니터링, 비용, 롤백 페이지에서 이어집니다.