> ## 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.

# DABs 배포: 환경 관리와 CI/CD

## 5. 환경별 배포 (Targets)

### dev / staging / prod 타겟 설정

```yaml theme={null}
# databricks.yml
bundle:
  name: "ecommerce-data-pipeline"

variables:
  catalog:
    default: "dev_catalog"
  warehouse_id:
    default: ""
  notification_email:
    default: "dev-team@company.com"

include:
  - "resources/*.yml"

targets:
  # 개발 환경 — 기본 타겟
  dev:
    mode: development       # 리소스 이름에 [dev 사용자명] 접두사 자동 추가
    default: true
    workspace:
      host: "https://dbc-dev.cloud.databricks.com"
    variables:
      catalog: "dev_catalog"
      warehouse_id: "aaa111bbb"

  # 스테이징 환경
  staging:
    workspace:
      host: "https://dbc-staging.cloud.databricks.com"
    variables:
      catalog: "staging_catalog"
      warehouse_id: "ccc222ddd"
      notification_email: "staging-alerts@company.com"

  # 프로덕션 환경
  prod:
    mode: production        # 실수로 destroy 시 확인 요구, run_as 강제
    workspace:
      host: "https://dbc-prod.cloud.databricks.com"
    variables:
      catalog: "prod_catalog"
      warehouse_id: "eee333fff"
      notification_email: "oncall@company.com"
    run_as:
      service_principal_name: "sp-prod-data-pipeline"
```

### mode: development vs mode: production

| mode          | 동작                                            |
| ------------- | --------------------------------------------- |
| `development` | 리소스 이름에 `[dev 사용자명]` 접두사가 자동으로 붙어 개인 개발 공간 격리 |
| `production`  | `run_as` 설정 필수, `bundle destroy` 시 확인 프롬프트 표시 |
| (미설정)         | 기본 동작, 이름 변경 없음                               |

### 권한(Permissions) 설정

```yaml theme={null}
# resources/jobs.yml — 리소스별 권한
resources:
  jobs:
    daily_etl:
      name: "daily-sales-etl-${bundle.target}"
      permissions:
        - level: "CAN_MANAGE"
          group_name: "data-engineers"
        - level: "CAN_VIEW"
          group_name: "data-analysts"
        - level: "IS_OWNER"
          service_principal_name: "sp-prod-data-pipeline"
```

***

## 6. 배포 워크플로

### 배포 3단계

```bash theme={null}
# 1단계: 검증 — 실제 배포 없이 설정 오류 사전 확인 (Dry Run)
databricks bundle validate

# 2단계: 배포 — 리소스 생성/업데이트
databricks bundle deploy -t staging

# 3단계: 실행 — 배포된 Job/Pipeline 즉시 실행
databricks bundle run daily_etl -t staging

# 리소스 삭제 (개발 환경 정리)
databricks bundle destroy -t dev
```

### validate 출력 예시

```
Name: ecommerce-data-pipeline
Target: staging
Workspace:
  Host: https://dbc-staging.cloud.databricks.com
  User: data-engineer@company.com
  Path: /Workspace/Users/data-engineer@company.com/.bundle/ecommerce-data-pipeline/staging

Validation OK!
```

### GitHub Actions CI/CD 연동

```yaml theme={null}
# .github/workflows/deploy.yml
name: Deploy Data Pipeline

on:
  push:
    branches: [main]        # main 머지 시 prod 자동 배포
  pull_request:
    branches: [main]        # PR 생성 시 staging 검증

jobs:
  validate:
    name: Validate Bundle
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4

      - name: Install Databricks CLI
        uses: databricks/setup-cli@main

      - name: Validate (staging)
        run: databricks bundle validate -t staging
        env:
          DATABRICKS_HOST: ${{ secrets.STAGING_DATABRICKS_HOST }}
          DATABRICKS_TOKEN: ${{ secrets.STAGING_DATABRICKS_TOKEN }}

  deploy-prod:
    name: Deploy to Production
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    environment: production   # GitHub Environment 보호 규칙 적용
    steps:
      - uses: actions/checkout@v4

      - name: Install Databricks CLI
        uses: databricks/setup-cli@main

      - name: Deploy to Production
        run: |
          databricks bundle validate -t prod
          databricks bundle deploy -t prod
        env:
          DATABRICKS_HOST: ${{ secrets.PROD_DATABRICKS_HOST }}
          DATABRICKS_TOKEN: ${{ secrets.PROD_DATABRICKS_TOKEN }}
```

> **인증 방법**: 프로덕션 배포에는 Personal Access Token 대신 **Service Principal + OAuth M2M** 인증을 사용합니다. GitHub Secrets에 `DATABRICKS_CLIENT_ID`, `DATABRICKS_CLIENT_SECRET`을 저장하고 `DATABRICKS_TOKEN` 대신 사용합니다.

***

## 7. 실전 패턴

### 7-1. 모노레포(Monorepo) 구조

여러 팀/도메인의 파이프라인을 하나의 Git 저장소에서 관리하는 패턴입니다.

```
data-platform/
├── domains/
│   ├── ecommerce/
│   │   ├── databricks.yml
│   │   ├── resources/
│   │   └── src/
│   ├── marketing/
│   │   ├── databricks.yml
│   │   ├── resources/
│   │   └── src/
│   └── finance/
│       ├── databricks.yml
│       └── ...
└── shared/
    └── libraries/          # 공통 유틸리티 모듈
```

각 도메인 디렉토리에서 독립적으로 `databricks bundle deploy`를 실행합니다. GitHub Actions에서는 `paths` 필터로 변경된 도메인만 선택적으로 배포합니다.

### 7-2. 다중 Job 오케스트레이션

한 번들 내에서 여러 Job이 서로를 참조할 수 있습니다.

```yaml theme={null}
resources:
  jobs:
    ingestion_job:
      name: "ingestion-${bundle.target}"
      tasks:
        - task_key: "run_pipeline"
          pipeline_task:
            pipeline_id: "${resources.pipelines.raw_ingest.id}"

    transformation_job:
      name: "transformation-${bundle.target}"
      # 다른 Job 완료 후 트리거하는 패턴 (run_job_task)
      tasks:
        - task_key: "transform"
          run_job_task:
            job_id: "${resources.jobs.ingestion_job.id}"
```

### 7-3. 대시보드 코드화

```bash theme={null}
# UI에서 대시보드를 JSON으로 추출
databricks dashboards export <dashboard-id> > src/dashboards/sales_overview.lvdash.json

# 번들에 포함하여 배포
databricks bundle deploy -t prod
```

이렇게 하면 대시보드도 Git 이력 관리가 가능하고, 환경 간 일관된 대시보드 배포가 가능합니다.

### 7-4. include로 설정 분리

큰 프로젝트에서는 리소스 파일을 분리하여 가독성을 높입니다.

```yaml theme={null}
# databricks.yml
include:
  - "resources/jobs/*.yml"
  - "resources/pipelines/*.yml"
  - "resources/dashboards/*.yml"
```

***

## 8. 장단점과 트레이드오프

### DABs vs 수동 배포(UI)

|            | DABs                 | 수동 배포            |
| ---------- | -------------------- | ---------------- |
| **초기 설정**  | YAML 학습 필요, 초기 비용 있음 | 즉시 시작 가능         |
| **반복 배포**  | 명령어 한 줄              | 매번 UI 클릭 반복      |
| **환경 일관성** | 완벽히 보장               | 사람에 의존, 오류 발생 가능 |
| **감사/추적**  | Git 이력으로 완전 추적       | 불가               |
| **팀 협업**   | PR 리뷰 기반 변경 관리       | 변경 충돌 발생 가능      |
| **적합한 규모** | 중규모 이상 팀             | 개인/소규모 PoC       |

### DABs vs Terraform

|                    | DABs               | Terraform                          |
| ------------------ | ------------------ | ---------------------------------- |
| **Databricks 신기능** | 즉시 지원              | Provider 릴리즈 대기                    |
| **클라우드 인프라**       | 불가 (Databricks 전용) | AWS/Azure/GCP 모두 관리                |
| **상태 파일**          | 불필요 (플랫폼 관리)       | `.tfstate` 직접 관리, 협업 시 원격 상태 설정 필요 |
| **드리프트 감지**        | 제한적                | 강력한 `terraform plan`               |
| **생태계**            | Databricks 내부      | 광범위한 커뮤니티 모듈                       |

### 학습 곡선

```
초급: databricks.yml 기본 구조 이해 (1-2일)
  → Job/Pipeline 단순 배포

중급: 멀티 환경(targets), 변수 관리, 권한 설정 (1주)
  → dev/staging/prod 분리 운영

고급: CI/CD 연동, 모노레포, 커스텀 템플릿 (2-4주)
  → 팀 전체 배포 플랫폼 구축
```

***

## 9. 베스트 프랙티스와 흔한 실수

### 베스트 프랙티스

**1. 항상 validate 먼저 실행**

```bash theme={null}
# 배포 전 반드시 검증
databricks bundle validate -t prod
databricks bundle deploy -t prod
```

**2. Service Principal로 CI/CD 인증**

Personal Access Token은 사용자와 연결되어 있어 퇴직 시 파이프라인이 중단됩니다. CI/CD에서는 반드시 Service Principal을 사용합니다.

**3. run\_as를 prod에 명시**

```yaml theme={null}
targets:
  prod:
    mode: production
    run_as:
      service_principal_name: "sp-prod-pipeline"  # 사용자 개인 계정이 아닌 SP 사용
```

**4. 변수 기본값은 dev 기준으로 설정**

개발자가 `-t` 옵션 없이 명령을 실행하면 기본 타겟(dev)이 사용됩니다. 실수로 prod에 영향을 주는 것을 방지합니다.

**5. 리소스 이름에 `${bundle.target}` 포함**

```yaml theme={null}
name: "daily-etl-${bundle.target}"   # daily-etl-dev, daily-etl-prod 구분
```

같은 Workspace를 여러 환경이 공유할 때 이름 충돌을 방지합니다.

### 흔한 실수

| 실수                      | 원인                                                                 | 해결 방법                                       |
| ----------------------- | ------------------------------------------------------------------ | ------------------------------------------- |
| 배포 후 리소스가 사라짐           | `mode: development`에서 다른 사용자가 deploy 실행 — 이름에 사용자명이 붙어 별도 리소스로 생성됨 | dev는 개인별 독립 공간임을 이해, 공유 dev는 mode 생략        |
| prod에 dev 카탈로그 데이터가 들어감 | 변수 기본값이 dev 카탈로그인 상태로 prod 배포                                      | `-t prod` 지정 시 변수 재확인, validate에서 변수 출력 확인  |
| CI/CD 인증 실패             | Token 만료 또는 Service Principal 권한 부족                                | SP에 Workspace 접근 + 번들 리소스 CAN\_MANAGE 권한 부여 |
| YAML 들여쓰기 오류            | 탭/스페이스 혼용                                                          | 에디터에서 YAML 린터 활성화, `bundle validate`로 사전 확인 |
| 리소스 삭제 안 됨              | `bundle destroy`를 실행했지만 외부에서 수동으로 생성된 리소스는 삭제 불가                   | DABs 외부에서 생성한 리소스는 DABs가 관리하지 않음을 이해        |

***

## 정리

| 핵심 개념               | 설명                                                        |
| ------------------- | --------------------------------------------------------- |
| **databricks.yml**  | 번들의 모든 것을 정의하는 메인 설정 파일입니다                                |
| **resources**       | Jobs, Pipelines, Dashboards 등 Databricks 리소스를 YAML로 선언합니다 |
| **targets**         | dev, staging, prod 등 환경별 설정을 분리합니다                        |
| **variables**       | 환경별로 다른 값(카탈로그, 엔드포인트 등)을 `${var.이름}` 으로 참조합니다            |
| **bundle validate** | 실제 배포 없이 설정 오류를 사전에 확인합니다                                 |
| **bundle deploy**   | 정의된 리소스를 대상 환경에 생성/업데이트합니다                                |
| **CI/CD**           | GitHub Actions 등과 연동하여 PR 기반 자동 배포 파이프라인을 구축합니다           |

***

## 참고 링크

* [Databricks: Declarative Automation Bundles 공식 문서](https://docs.databricks.com/aws/en/dev-tools/bundles/)
* [Databricks: Bundle configuration reference (전체 YAML 스키마)](https://docs.databricks.com/aws/en/dev-tools/bundles/settings.html)
* [Databricks: Bundle resources (리소스 유형별 설정)](https://docs.databricks.com/aws/en/dev-tools/bundles/resources.html)
* [Databricks: Bundle templates](https://docs.databricks.com/aws/en/dev-tools/bundles/templates.html)
* [Databricks: CI/CD with DABs (GitHub Actions)](https://docs.databricks.com/aws/en/dev-tools/bundles/ci-cd.html)
* [Azure Databricks: Declarative Automation Bundles](https://learn.microsoft.com/en-us/azure/databricks/dev-tools/bundles/)
* [Databricks: DABs vs Terraform — When to use each](https://docs.databricks.com/aws/en/dev-tools/index.html)