> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sifi.life/llms.txt
> Use this file to discover all available pages before exploring further.

# Databricks Apps 개요

이 페이지는 Databricks Apps의 기능 개요입니다. 앱 생성, 인증, 배포, 예제 등 실전 가이드는 **[Databricks 소개 → Databricks Apps](/blog/guides/apps/overview)** 를 참고하세요.

## 왜 Databricks Apps가 필요한가요?

데이터 팀이 분석 결과나 ML 모델을 만들었다고 해서 바로 비즈니스 가치가 생기는 것은 아닙니다. **최종 사용자가 쉽게 접근할 수 있는 웹 애플리케이션** 형태로 제공해야 합니다. 하지만 기존에는 별도의 서버를 프로비저닝하고, 인증을 구현하고, 네트워크를 설정하는 등 복잡한 인프라 작업이 필요했습니다.

> 💡 **Databricks Apps** 는 Databricks 플랫폼 위에서 **웹 애플리케이션을 개발, 배포, 호스팅** 할 수 있는 관리형 서비스입니다. Streamlit, Gradio, Flask, FastAPI, Dash 등 Python 웹 프레임워크를 지원하며, **별도의 인프라 관리 없이** Databricks의 데이터와 AI 모델에 안전하게 접근하는 앱을 만들 수 있습니다.

| 구성 요소                          | 역할             | 연결                                                  |
| ------------------------------ | -------------- | --------------------------------------------------- |
| **개발자**                        | Python 앱 코드 작성 | `databricks apps deploy`로 배포                        |
| **Databricks Apps (관리형 컨테이너)** | 앱 호스팅          | SQL Warehouse, Model Serving, Lakebase, Secrets에 접근 |
| **SQL Warehouse**              | 데이터 조회         | 앱에서 SQL로 데이터를 조회합니다                                 |
| **Model Serving**              | AI 추론          | 앱에서 ML 모델을 호출합니다                                    |
| **Lakebase**                   | OLTP 데이터       | 앱에서 트랜잭션 데이터를 읽고 씁니다                                |
| **Secrets**                    | 자격 증명          | 민감 정보를 안전하게 관리합니다                                   |
| **최종 사용자 (브라우저)**              | 앱 사용           | OAuth 인증으로 앱에 접속합니다                                 |

***

## 지원 프레임워크

Databricks Apps는 다양한 Python 웹 프레임워크를 지원합니다. 각 프레임워크의 특성에 맞게 선택하면 됩니다.

| 프레임워크         | 적합한 용도            | 특징                              |
| ------------- | ----------------- | ------------------------------- |
| **Streamlit** | 데이터 대시보드, ML 데모   | 가장 적은 코드로 대화형 UI 구현. 데이터 앱에 최적화 |
| **Gradio**    | AI 모델 인터페이스, 챗봇   | ML 모델 데모에 특화. 입출력 컴포넌트 풍부       |
| **Dash**      | 대화형 데이터 시각화       | Plotly 기반. 복잡한 대시보드에 적합         |
| **Flask**     | REST API, 커스텀 백엔드 | 경량 웹 프레임워크. 자유도가 높음             |
| **FastAPI**   | 고성능 REST API      | 비동기 지원, 자동 API 문서 생성            |

> 💡 **어떤 프레임워크를 선택해야 할까요?** 빠르게 데이터 대시보드를 만들고 싶다면 **Streamlit**, AI 모델 데모가 목적이라면 **Gradio**, REST API 백엔드가 필요하다면 **FastAPI** 를 추천합니다.

***

## 앱 아키텍처

Databricks Apps는 내부적으로 **컨테이너 기반** 아키텍처로 동작합니다.

| 계층                  | 구성 요소                  | 역할                  |
| ------------------- | ---------------------- | ------------------- |
| **Databricks Apps** | 앱 컨테이너 (Python 프로세스)   | 앱 코드를 실행합니다         |
|                     | 인증 프록시 (OAuth 2.0)     | 사용자 인증을 처리합니다       |
| **리소스 바인딩**         | SQL Warehouse          | 데이터 조회에 사용됩니다       |
|                     | Model Serving Endpoint | AI 모델 호출에 사용됩니다     |
|                     | Secret Scope           | 자격 증명을 관리합니다        |
|                     | Service Principal      | 자동화된 접근에 사용됩니다      |
| **외부**              | 브라우저 (사용자)             | OAuth 인증 후 앱에 접속합니다 |

### 핵심 아키텍처 구성 요소

| 구성 요소                 | 설명                                                                |
| --------------------- | ----------------------------------------------------------------- |
| **앱 컨테이너**            | Python 프로세스가 실행되는 격리된 컨테이너 환경입니다                                  |
| **인증 프록시**            | 모든 요청에 Databricks OAuth 인증을 자동으로 적용합니다                            |
| **리소스 바인딩**           | `app.yaml`에 선언된 Databricks 리소스(Warehouse, Endpoint 등)에 안전하게 접근합니다 |
| **Service Principal** | 앱 생성 시 자동으로 할당되어, 앱의 ID로 리소스에 접근합니다                               |

***

## app.yaml 설정 상세

`app.yaml`은 앱의 실행 방법, 환경 변수, 필요한 리소스를 선언하는 핵심 설정 파일입니다.

### 기본 구조

| 파일                 | 설명                 |
| ------------------ | ------------------ |
| `app.py`           | 메인 앱 코드            |
| `app.yaml`         | Databricks Apps 설정 |
| `requirements.txt` | 추가 Python 패키지      |
| `static/logo.png`  | 정적 파일 (선택)         |

### 설정 항목 상세

| 항목          | 필수  | 설명                                               |
| ----------- | --- | ------------------------------------------------ |
| `command`   | Yes | 앱 실행 명령어입니다. 포트는 반드시 **8000** 으로 설정해야 합니다        |
| `env`       | No  | 환경 변수를 정의합니다. `valueFrom`으로 Secret 값을 참조할 수 있습니다 |
| `resources` | No  | 앱이 접근할 Databricks 리소스를 선언합니다                     |

### 지원되는 리소스 유형

| 리소스                    | `app.yaml` 키        | 권한 옵션                     |
| ---------------------- | ------------------- | ------------------------- |
| SQL Warehouse          | `sql_warehouse`     | `CAN_USE`, `CAN_MANAGE`   |
| Model Serving Endpoint | `serving_endpoint`  | `CAN_QUERY`, `CAN_MANAGE` |
| Secret                 | `secret`            | `READ`                    |
| Lakebase Database      | `lakebase_database` | `CAN_USE`                 |

> ⚠️ **포트 번호 주의**: 앱은 반드시 **포트 8000** 에서 수신 대기해야 합니다. 다른 포트를 사용하면 앱이 정상적으로 동작하지 않습니다.

***

## 컴퓨트 사이징

앱의 워크로드에 맞는 컴퓨트 크기를 선택할 수 있습니다.

| 크기            | vCPU | 메모리   | 적합한 용도            |
| ------------- | ---- | ----- | ----------------- |
| **Small**(기본) | 1    | 2 GB  | 경량 대시보드, 간단한 API  |
| **Medium**    | 2    | 6 GB  | 데이터 시각화, 중간 규모 앱  |
| **Large**     | 4    | 12 GB | 복잡한 분석, 대량 데이터 처리 |

> 🆕 **컴퓨트 사이징 GA**: Medium(2 vCPU, 6GB)과 Large(4 vCPU, 12GB) 옵션이 GA되어, 앱의 워크로드에 맞는 리소스를 선택할 수 있습니다.

***

## 앱 인증 모델

Databricks Apps는 **두 가지 인증 모델** 을 지원합니다.

### 1. 앱 서비스 프린시펄 인증 (App-on-behalf-of-itself)

앱 생성 시 자동으로 할당된 **Service Principal** 의 권한으로 리소스에 접근합니다. 모든 사용자가 동일한 데이터를 보게 됩니다.

```python theme={null}
# 앱 Service Principal 인증 (기본)
from databricks.sdk import WorkspaceClient

# 앱 내부에서는 자동으로 앱의 Service Principal로 인증됩니다
w = WorkspaceClient()
tables = w.tables.list(catalog_name="main", schema_name="default")
```

### 2. 사용자 대리 인증 (App-on-behalf-of-user)

로그인한 **사용자의 OAuth 토큰** 을 사용하여 리소스에 접근합니다. 각 사용자가 자신의 권한에 맞는 데이터만 볼 수 있습니다.

```python theme={null}
# 사용자 대리 인증
from databricks.sdk import WorkspaceClient

def get_user_client(request_headers):
    """요청 헤더에서 사용자 토큰을 추출하여 클라이언트 생성"""
    w = WorkspaceClient(
        host=os.environ["DATABRICKS_HOST"],
        token=request_headers.get("X-Forwarded-Access-Token")
    )
    return w
```

| 구분            | 앱 Service Principal | 사용자 대리 인증          |
| ------------- | ------------------- | ------------------ |
| **데이터 접근**    | 모든 사용자가 동일          | 사용자별 권한 적용         |
| **설정 복잡도**    | 낮음 (기본값)            | 중간 (토큰 전달 필요)      |
| **적합한 경우**    | 공용 대시보드, 공개 데이터     | 개인화된 데이터 뷰, 민감 데이터 |
| **감사(Audit)** | 앱 이름으로 기록           | 실제 사용자 이름으로 기록     |

> 💡 **어떤 인증을 선택해야 할까요?** 데이터에 행/열 수준 보안이 필요하거나, 누가 어떤 데이터에 접근했는지 감사 추적이 중요하다면 **사용자 대리 인증** 을 사용하세요.

***

## 개발 워크플로

Databricks Apps의 개발은 **로컬 개발 → 배포 → 테스트 → 반복** 사이클을 따릅니다.

| 단계 | 작업    | 설명                             |
| -- | ----- | ------------------------------ |
| 1  | 로컬 개발 | app.py + app.yaml을 작성합니다       |
| 2  | 배포    | CLI 또는 UI로 배포합니다               |
| 3  | 테스트   | 앱 URL에 접속하여 테스트합니다             |
| 4  | 로그 확인 | 문제를 진단합니다. 수정이 필요하면 1단계로 돌아갑니다 |
| 5  | 프로덕션  | 완료 후 공유합니다                     |

### 로컬 프로젝트 구조

```
my-app/
| 파일 | 설명 |
|------|------|
| `app.py` | 메인 앱 코드 |
| `app.yaml` | Databricks Apps 설정 |
| `requirements.txt` | 추가 Python 패키지 |
| `static/logo.png` | 정적 파일 (선택) |
```

***

## 배포 방법

### 방법 1: Databricks CLI

```bash theme={null}
# 1. 앱 생성 (최초 1회)
databricks apps create my-dashboard \
  --description "매출 분석 대시보드"

# 2. 앱 배포 (코드 업로드 + 시작)
databricks apps deploy my-dashboard \
  --source-code-path ./my-app

# 3. 앱 상태 확인
databricks apps get my-dashboard

# 4. 앱 로그 확인
databricks apps get-logs my-dashboard
```

### 방법 2: Workspace UI

1. 좌측 메뉴에서 **Compute**> **Apps** 선택
2. **Create App** 클릭
3. 앱 이름과 설명 입력
4. 소스 코드 업로드 또는 Git 연결
5. 리소스 바인딩 설정
6. **Deploy** 클릭

### 방법 3: Databricks Asset Bundles (DABs)

프로덕션 환경에서는 DABs로 앱을 인프라-as-코드로 관리할 수 있습니다.

```yaml theme={null}
# databricks.yml
bundle:
  name: my-dashboard

resources:
  apps:
    my-dashboard:
      name: "my-dashboard"
      description: "매출 분석 대시보드"
      source_code_path: ./src
      config:
        command:
          - "streamlit"
          - "run"
          - "app.py"
          - "--server.port"
          - "8000"
        resources:
          - name: "warehouse"
            sql_warehouse:
              id: "${var.warehouse_id}"
              permission: "CAN_USE"
```

***

## 데이터 접근 방법

앱에서 Databricks 데이터에 접근하는 주요 방법입니다.

### SQL Warehouse를 통한 데이터 조회

```python theme={null}
import streamlit as st
from databricks import sql
import os

# SQL Warehouse 연결 (리소스 바인딩 활용)
connection = sql.connect(
    server_hostname=os.environ["DATABRICKS_HOST"],
    http_path=os.environ["DATABRICKS_SQL_WAREHOUSE_HTTP_PATH"],
    credentials_provider=lambda: {
        "Authorization": f"Bearer {os.environ['DATABRICKS_TOKEN']}"
    }
)

cursor = connection.cursor()
cursor.execute("SELECT * FROM main.sales.daily_revenue LIMIT 100")
df = cursor.fetchall_arrow().to_pandas()

st.dataframe(df)
```

### Databricks SDK 사용

```python theme={null}
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Unity Catalog 테이블 목록 조회
for table in w.tables.list(catalog_name="main", schema_name="sales"):
    print(f"테이블: {table.name}")
```

***

***

## 참고 링크

* [Databricks: Databricks Apps 개요](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/)
* [Databricks: App 설정 (app.yaml)](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/configuration.html)
* [Azure Databricks: Databricks Apps](https://learn.microsoft.com/en-us/azure/databricks/dev-tools/databricks-apps/)