앱 생성하기

​

왜 Databricks Apps인가?

• VPC 보안 그룹에서 Databricks 워크스페이스로의 아웃바운드 트래픽 허용
• PAT(Personal Access Token)를 AWS Secrets Manager에 저장하고 주기적으로 로테이션
• SSL 인증서 발급 및 ALB 구성
• 사용자 인증 시스템(Cognito, Auth0 등) 별도 구축

​

사전 준비

참고 사전 준비가 중요한 이유: 앱 생성 자체는 수 분이면 되지만, 권한 부족으로 인한 디버깅에 수 시간을 소모하는 경우가 흔합니다. 특히 리소스 권한(항목 3)이 누락되면 앱은 정상 배포되지만 데이터 조회 시 Permission denied 오류가 발생합니다. 앱의 서비스 프린시펄에 대한 권한이 아니라 본인 계정의 권한만 확인하는 실수가 가장 빈번합니다.

​

방법 1: UI에서 앱 생성

​

Step 1: 앱 생성 시작

1. 워크스페이스 사이드바에서 + New> App 클릭
2. 다음 중 하나를 선택합니다:
   • 템플릿 사용: Streamlit, Gradio Hello world, Flask, FastAPI 등 사전 구성된 템플릿
   • 빈 앱 생성: 처음부터 직접 코드 작성

참고 이 단계에서 실제로 무슨 일이 일어나는가: “App” 버튼을 클릭하는 순간 Databricks는 내부적으로 Kubernetes 네임스페이스를 예약 합니다. 이 네임스페이스는 앱 전용의 격리된 실행 환경이 됩니다. 템플릿을 선택하면 사전 작성된 app.py, app.yaml, requirements.txt가 자동으로 해당 네임스페이스에 복사됩니다. 빈 앱을 선택하면 네임스페이스만 생성되고, 이후에 코드를 직접 업로드합니다.

​

Step 2: 앱 정보 입력

주의 앱 이름 규칙: 소문자, 숫자, 하이픈만 사용 가능합니다. 앱 이름은 생성 후 변경할 수 없으며 URL에 직접 반영되므로 신중하게 지정하세요.

참고 이 단계에서 실제로 무슨 일이 일어나는가: 앱 이름은 단순한 라벨이 아닙니다. 이 이름이 곧 앱의 URL 경로 가 됩니다. 예를 들어 my-dashboard-app이라는 이름을 지정하면 URL은 https://my-dashboard-app-<workspace-id>.<region>.databricksapps.com이 됩니다.

• 팀명-기능명 패턴을 사용하세요 (예: data-team-sales-dashboard)
• 환경을 이름에 포함하지 마세요 (예: my-app-dev보다는 환경별 별도 앱 생성)
• 이름은 변경 불가하므로, 임시 이름보다는 영구적으로 사용할 이름을 선택하세요
• URL에 표시되므로 외부에 노출되어도 문제없는 이름을 사용하세요

​

Step 3: 리소스 연결 (선택)

참고 이 단계에서 실제로 무슨 일이 일어나는가: 리소스를 연결하면 Databricks는 앱의 서비스 프린시펄(SP)에 해당 리소스에 대한 접근 권한을 자동으로 부여 합니다. 내부적으로는 app.yaml에 리소스 정의가 추가되고, 앱 실행 시 해당 리소스의 연결 정보가 환경변수로 자동 주입됩니다.

주의 흔한 실수: 리소스를 연결했지만 서비스 프린시펄에 실제 권한을 부여하지 않는 경우가 많습니다. 리소스 연결은 “이 앱이 이 리소스를 사용한다”는 선언일 뿐, 권한 부여는 별도로 해야 합니다. SQL Warehouse의 경우 Warehouse 설정에서 앱의 SP에 CAN USE 권한을, UC 테이블의 경우 SQL로 GRANT SELECT ON TABLE ... TO <sp-id>를 실행해야 합니다.

​

Step 4: Install 클릭

1. 전용 서비스 프린시펄 생성
2. 컨테이너 환경 프로비저닝
3. 앱 코드 배포 및 실행
4. 공개 URL 생성

참고 이 단계에서 실제로 무슨 일이 일어나는가: Install 버튼 뒤에서 일어나는 과정을 단계별로 설명합니다.

1. 서비스 프린시펄 생성: 앱 전용 OAuth 클라이언트가 생성됩니다. DATABRICKS_CLIENT_ID와 DATABRICKS_CLIENT_SECRET가 이 SP의 자격 증명입니다.
2. 컨테이너 빌드: requirements.txt에 명시된 패키지가 설치되고, Python/Node.js 런타임이 구성됩니다. 이 과정이 배포 시간의 대부분을 차지합니다.
3. 앱 실행: app.yaml의 command에 지정된 명령이 컨테이너 내에서 실행됩니다.
4. 헬스체크: Databricks가 앱이 지정된 포트에서 HTTP 요청에 응답하는지 확인합니다. 응답이 오면 Running 상태로 전환됩니다.
5. URL 라우팅: 앱의 고유 URL이 리버스 프록시에 등록되고, HTTPS가 자동으로 적용됩니다.

​

Step 5: 배포 확인

• 앱 URL: https://<app-name>-<workspace-id>.<region>.databricksapps.com
• 실행 상태: Running, Deploying, Crashed 등
• 로그: 앱 실행 로그 (디버깅에 필수)
• 서비스 프린시펄: 자동 생성된 SP 정보

참고 각 상태의 의미와 대처법:

• Running: 앱이 정상적으로 실행 중이며 URL로 접속 가능합니다. 이 상태에서도 로그를 주기적으로 확인하여 런타임 오류가 발생하고 있지 않은지 모니터링하세요.
• Deploying: 컨테이너 빌드 또는 패키지 설치가 진행 중입니다. 보통 2~5분 내에 완료됩니다. 10분 이상 이 상태가 지속되면 requirements.txt에 설치에 오래 걸리는 패키지가 있거나, 네트워크 문제가 있을 수 있습니다.
• Crashed: 앱 코드에 오류가 있어 프로세스가 비정상 종료된 상태입니다. 반드시 Logs 탭에서 에러 메시지를 확인 하세요. 가장 흔한 원인은 ModuleNotFoundError(패키지 누락), PermissionError(SP 권한 부족), ConnectionError(Warehouse/Endpoint 접속 실패)입니다.
• Stopped: 사용자가 수동으로 앱을 중지한 상태입니다. 과금이 발생하지 않으며, 다시 시작하려면 Start 버튼을 클릭하세요.

​

방법 2: Databricks CLI로 앱 생성

​

앱 생성

# 앱 생성 (빈 앱)
databricks apps create --name my-dashboard-app \
  --description "매출 분석 대시보드"

​

앱 배포

# 로컬 소스 코드를 앱에 배포
databricks apps deploy my-dashboard-app \
  --source-code-path /path/to/local/app

​

앱 상태 확인

# 앱 상태 조회
databricks apps get my-dashboard-app

# 앱 목록 조회
databricks apps list

참고 CLI 활용 팁: databricks apps get 출력을 jq와 조합하면 특정 필드만 추출할 수 있습니다. 예를 들어 databricks apps get my-app --output json | jq '.status'로 상태만 확인하거나, jq '.url'로 URL만 추출할 수 있습니다. CI/CD 파이프라인에서 배포 후 상태를 검증할 때 유용합니다.

​

소스 코드 다운로드 및 로컬 개발

mkdir my-dashboard-app && cd my-dashboard-app
# Overview 페이지에서 제공하는 sync 커맨드 실행

​

로컬 실행 및 테스트

# 의존성 설치
pip install -r requirements.txt

# Databricks CLI로 로컬 실행 (권장 — Databricks 인증 자동 처리)
databricks apps run-local --prepare-environment --debug

# 또는 프레임워크별 직접 실행
streamlit run app.py          # Streamlit
uvicorn app:app --reload      # FastAPI
python app.py                 # Gradio / Flask

​

재배포

# 수정된 코드를 워크스페이스에 재배포
databricks apps deploy my-dashboard-app \
  --source-code-path /path/to/local/app

​

앱 생성 후 확인 체크리스트

주의 체크 순서가 중요합니다: 항목 1-2가 정상이더라도 항목 3-4에서 실패하는 경우가 매우 흔합니다. 앱 자체는 실행되지만 데이터에 접근하지 못하는 것입니다. 반드시 실제 데이터 조회나 모델 호출까지 테스트 하세요.

​

일반적인 오류와 해결 방법

참고 디버깅 팁: databricks apps run-local --debug 명령으로 로컬에서 먼저 테스트하면, 배포 후 발생하는 대부분의 오류를 사전에 잡을 수 있습니다.

주의 가장 빈번한 실수 TOP 3:

1. SP 권한 미부여: 앱이 Running이지만 데이터 접근 시 Permission denied. 앱의 서비스 프린시펄에 GRANT SELECT와 Warehouse CAN USE 권한을 부여했는지 확인하세요.
2. 포트 미설정: FastAPI/Flask에서 host=0.0.0.0과 port=$DATABRICKS_APP_PORT를 지정하지 않으면 앱이 시작되지만 외부에서 접속할 수 없습니다.
3. requirements.txt 불일치: 로컬에서는 잘 되지만 배포 후 에러가 나는 경우, 로컬에 설치된 패키지가 requirements.txt에 누락되었을 가능성이 높습니다. pip freeze > requirements.txt로 현재 환경을 캡처하세요 (단, 불필요한 패키지는 제거).