> ## 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의 배포 과정을 이해하면 배포 실패 시 문제를 빠르게 진단할 수 있습니다. 배포는 크게 **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. 로컬 개발 환경 설정

### 필수 도구 설치

```bash theme={null}
# Databricks CLI 설치
pip install databricks-cli
# 또는
brew install databricks
```

이 명령은 Databricks CLI를 설치합니다. CLI는 앱 생성, 배포, 상태 확인, 로그 조회 등 모든 배포 작업을 커맨드라인에서 수행할 수 있게 합니다.

```bash theme={null}
# 인증 설정 (OAuth 기반 — 권장)
databricks auth login --host https://<workspace-url>
```

이 명령은 브라우저 기반 OAuth 인증을 시작합니다. PAT(Personal Access Token)보다 OAuth가 권장되는 이유는 토큰 자동 갱신이 지원되고, 토큰이 파일에 평문으로 저장되지 않기 때문입니다.

```bash theme={null}
# 인증 확인
databricks current-user me
```

이 명령으로 인증이 정상적으로 설정되었는지 확인합니다. 현재 로그인한 사용자 정보가 반환되면 인증이 올바르게 구성된 것입니다.

### 프로젝트 구조

선호하는 IDE(VS Code, PyCharm, IntelliJ 등)에서 개발합니다. Databricks VS Code Extension 사용을 권장합니다.

```bash theme={null}
my-app/
├── app.py              # 앱 코드
├── app.yaml            # 앱 설정 (런타임, 리소스, 환경 변수)
├── requirements.txt    # Python 의존성
└── static/             # 정적 파일 (선택)
```

이 4개 파일이 Databricks App의 전체입니다. `app.py`가 비즈니스 로직, `app.yaml`이 실행 환경, `requirements.txt`가 의존성, `static/`이 정적 에셋입니다.

### app.yaml 예시

```yaml theme={null}
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분)의 사이클을 반복해야 하지만, 로컬에서는 즉시 확인할 수 있습니다.

```bash theme={null}
# Databricks CLI 로컬 실행 (권장 — Databricks 인증, 환경 변수 자동 처리)
databricks apps run-local --prepare-environment --debug
```

`--prepare-environment`는 `app.yaml`에 정의된 모든 환경변수와 리소스 참조를 로컬 환경에 자동으로 설정합니다. `--debug`는 상세 로그를 출력하여 인증 문제나 리소스 접근 오류를 즉시 확인할 수 있게 합니다.

또는 프레임워크별로 직접 실행:

```bash theme={null}
# 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 명령어

### 기본 배포

```bash theme={null}
# 로컬 소스 코드를 워크스페이스에 배포
databricks apps deploy <app-name> --source-code-path /path/to/local/app
```

이 명령은 지정된 디렉토리의 모든 파일을 패키징하여 Databricks에 업로드하고, 컨테이너 빌드와 앱 실행을 트리거합니다. 10MB를 초과하는 개별 파일이 있으면 배포가 실패합니다.

### 배포 상태 확인

```bash theme={null}
# 배포 상태 조회
databricks apps get <app-name>

# 배포 로그 확인 (디버깅 시)
databricks apps logs <app-name>
```

`get` 명령은 앱의 현재 상태, URL, 서비스 프린시펄 정보, 마지막 배포 시간을 반환합니다. `logs` 명령은 Python의 `print()` 출력, 프레임워크의 로그 메시지, 에러 트레이스백을 보여줍니다.

### 앱 중지/재시작

```bash theme={null}
# 앱 중지
databricks apps stop <app-name>

# 앱 시작
databricks apps start <app-name>
```

앱을 중지하면 과금이 중지됩니다. 인메모리 상태는 초기화되므로 영속적 데이터는 미리 저장해야 합니다.

***

## 4. 환경 간 이동 (dev → staging → prod)

리소스를 하드코딩하지 않고 `app.yaml`의 `valueFrom`을 사용하면, 코드 수정 없이 다른 워크스페이스로 앱을 이동할 수 있습니다. 이것이 **리소스 추상화의 핵심 가치** 입니다.

### 전략: 환경별 app.yaml 분리

```bash theme={null}
my-app/
├── app.py
├── app.yaml              # 기본 설정 (dev)
├── app.staging.yaml      # 스테이징 설정
├── app.prod.yaml         # 프로덕션 설정
└── requirements.txt
```

이 구조에서 `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`      |

```bash theme={null}
# 스테이징 배포
databricks apps deploy my-app-staging --source-code-path ./my-app

# 프로덕션 배포
databricks apps deploy my-app-prod --source-code-path ./my-app
```

> **참고**
> **환경 분리 전략**: 가장 간단한 방법은 환경별로 별도 앱을 생성하는 것입니다 (`my-app-dev`, `my-app-staging`, `my-app-prod`). 각 앱에서 UI Configure 화면에서 해당 환경의 리소스를 연결하면 됩니다.

***

## 5. CI/CD 파이프라인 구성 예시

프로덕션 앱은 수동 배포 대신 **CI/CD 파이프라인을 통한 자동 배포** 가 권장됩니다. 자동 배포는 인적 오류를 줄이고, 배포 이력을 추적 가능하게 하며, 일관된 배포 프로세스를 보장합니다.

### GitHub Actions 예시

아래 워크플로우는 `main` 브랜치에 `my-app/` 디렉토리의 변경이 푸시되면 자동으로 앱을 배포합니다.

```yaml theme={null}
# .github/workflows/deploy-app.yml
name: Deploy Databricks App

on:
  push:
    branches: [main]
    paths: ['my-app/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Databricks CLI
        run: pip install databricks-cli

      - name: Configure Databricks Auth
        env:
          DATABRICKS_HOST: ${{ secrets.DATABRICKS_HOST }}
          DATABRICKS_TOKEN: ${{ secrets.DATABRICKS_TOKEN }}
        run: |
          databricks configure --token <<EOF
          $DATABRICKS_HOST
          $DATABRICKS_TOKEN
          EOF

      - name: Deploy App
        run: |
          databricks apps deploy my-app \
            --source-code-path ./my-app
```

이 워크플로우에서 핵심 포인트는 다음과 같습니다:

* `paths: ['my-app/**']`로 앱 코드가 변경될 때만 배포가 트리거됩니다.
* `DATABRICKS_HOST`와 `DATABRICKS_TOKEN`은 **GitHub Secrets** 에 저장됩니다. 절대 코드에 직접 넣지 마세요.
* 배포 후 상태 확인 단계를 추가하면 더 안전합니다.

### Azure DevOps 예시

```yaml theme={null}
# azure-pipelines.yml
trigger:
  branches:
    include:
      - main
  paths:
    include:
      - my-app/**

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: '3.10'

  - script: pip install databricks-cli
    displayName: 'Install Databricks CLI'

  - script: |
      export DATABRICKS_HOST=$(DATABRICKS_HOST)
      export DATABRICKS_TOKEN=$(DATABRICKS_TOKEN)
      databricks apps deploy my-app --source-code-path ./my-app
    displayName: 'Deploy App'
    env:
      DATABRICKS_HOST: $(DATABRICKS_HOST)
      DATABRICKS_TOKEN: $(DATABRICKS_TOKEN)
```

Azure DevOps에서도 패턴은 동일합니다. `DATABRICKS_HOST`와 `DATABRICKS_TOKEN`을 Pipeline Variables(Secret)로 설정하세요.

> **주의**
> **보안 주의**: CI/CD에서 Databricks 인증 정보는 반드시 **GitHub Secrets** 또는 해당 CI 도구의 시크릿 관리 기능을 사용하세요. 코드에 토큰을 직접 넣지 마세요.

> **참고**
> **CI/CD 고급 패턴**: 프로덕션 배포 파이프라인에서는 다음 단계를 추가하는 것이 좋습니다:

1. **린트/테스트**: 코드 품질 검사 및 단위 테스트 실행
2. **스테이징 배포**: 프로덕션 전 스테이징 환경에 먼저 배포
3. **스모크 테스트**: 스테이징에서 기본 기능 동작 확인
4. **승인 게이트**: 수동 승인 후 프로덕션 배포
5. **프로덕션 배포**: 메인 앱 배포
6. **상태 검증**: 배포 후 앱 상태가 `Running`인지 확인

더 체계적인 배포 관리가 필요하다면 **Databricks Asset Bundles (DABs)** 를 사용하세요. DABs는 앱 설정, 리소스, 권한을 코드로 선언하여 환경별 자동 배포를 가능하게 합니다. 자세한 내용은 [고급 기능 — DABs](/blog/guides/apps/advanced) 페이지를 참고하세요.

***

> **다음 페이지**: 모니터링, 스케일링, 비용, 롤백, 의존성 관리 내용은 [Databricks Apps 운영 — 모니터링, 비용, 롤백](/blog/guides/apps/deployment-monitoring) 페이지에서 이어집니다.