DBX에서 번들로 마이그레이션하기

아티클
09/25/2024

Important

Databricks에서는 Databricks Labs의 dbx 대신 Databricks Asset Bundles를 사용하는 것이 좋습니다. dbx에 대한 문서는 사용 중지되었으며 업데이트되지 않을 수 있습니다.

이 문서에서는 Databricks Labs의 프로젝트를 Databricks Asset Bundles의 dbx(으)로 마이그레이션하는 방법을 설명합니다. Databricks Labs의 dbx 소개 및 Databricks 자산 번들이란?을 참조하세요.

마이그레이션하기 전에 Databricks Labs의 dbx과(와) Databricks Asset Bundles의 다음 제한 사항과 기능 비교를 참고하세요.

제한 사항

Databricks Labs의 dbx에서 지원하는 다음 기능은 제한되어 있거나 존재하지 않거나 Databricks Asset Bundles에서 해결 방법이 필요합니다.

번들에서는 JAR 아티팩트 빌드가 지원되지 않습니다.
번들에서는 작업 영역 경로에 대한 FUSE 표기법이 지원되지 않습니다(예: /Workspace/<path>/<filename>). 그러나 /Workspace/${bundle.file_path}/<filename>과(와) 같은 표기법을 사용하면 배포 중에 번들에 FUSE 스타일의 작업 영역 경로를 생성하도록 지시할 수 있습니다.

기능 비교

마이그레이션하기 전에 Databricks Labs의 dbx에 대한 다음 기능이 Databricks Asset Bundles에서 어떻게 구현되는지 확인하세요.

템플릿 및 프로젝트

dbx에서는 Jinja 템플릿을 지원합니다. 배포 구성에 Jinja 템플릿을 포함하고 환경 변수를 인라인이나 변수 파일을 통해 전달할 수 있습니다. 권장되지는 않지만 dbx에서는 사용자 지정 사용자 함수에 대한 실험적 지원도 제공합니다.

번들은 구성 재사용을 위한 Go 템플릿에 대한 지원을 제공합니다. 사용자는 미리 빌드된 템플릿을 기반으로 번들을 만들 수 있습니다. 사용자 지정 사용자 함수를 제외하면 템플릿 작성은 거의 동등합니다.

빌드 관리

dbx는 pip wheel, 시 및 Flit을 통해 빌드를 지원합니다. 사용자는 프로젝트 deployment.yml 파일 build 섹션에서 빌드 옵션을 지정할 수 있습니다.

사용자는 번들을 이용하여 Python 휠 파일을 빌드, 배포, 실행할 수 있습니다. 사용자는 번들의 databricks.yml 파일에서 기본 제공 whl 항목을 활용할 수 있습니다.

코드 동기화, 배포 및 실행

dbx을(를) 이용하면 Azure Databricks 작업과 같은 작업 영역 리소스를 생성하는 것과 별도로 코드를 업로드할 수 있습니다.

번들은 항상 코드를 업로드하고 동시에 작업 영역 리소스를 생성하거나 업데이트합니다. 이렇게 하면 배포가 간소화되고 이미 진행 중인 작업에 대한 차단 조건이 방지됩니다.

dbx 프로젝트를 번들로 마이그레이션

Databricks Labs의 dbx(과)와 Databricks Asset Bundles의 제한 사항과 기능 비교를 확인하면 dbx을(를) 번들로 마이그레이션할 준비가 끝납니다.

Databricks에서는 dbx 프로젝트 마이그레이션을 시작하려면 dbx 프로젝트를 원래 폴더에 보관하고 원래 dbx 프로젝트의 내용을 복사할 별도의 빈 폴더를 만드는 것이 좋습니다. 이 별도 폴더가 새로운 번들이 됩니다. dbx 프로젝트를 원래 폴더에서 번들로 변환하기 시작한 다음 실수를 하거나 처음부터 다시 시작하려는 경우 예상치 못한 문제가 발생할 수 있습니다.

1단계: Databricks CLI 설치 및 설정

Databricks 자산 번들은 일반적으로 Databricks CLI 버전 0.218.0 이상에서 사용할 수 있습니다. 이미 Databricks CLI 버전 0.218.0 이상을 설치하고 설정한 경우 2단계로 건너뛰세요.

참고 항목

번들은 Databricks CLI 버전 0.18 이하와 호환되지 않습니다.

Databricks CLI 버전 0.218.0 이상을 설치하거나 업데이트하세요. Databricks CLI 설치 또는 업데이트를 참조하세요.
예를 들어 Azure Databricks 개인 액세스 토큰 인증을 사용하여 대상 Azure Databricks 작업 영역에 대한 인증을 위해 Databricks CLI를 설정합니다. 다른 Azure Databricks 인증 유형에 대해서는 Databricks CLI에 대한 인증을 참조하세요.

2단계: 번들 구성 파일 생성

Visual Studio Code, PyCharm Professional 또는 IntelliJ IDEA Ultimate와 같이 YAML 파일과 JSON 스키마 파일을 지원하는 IDE를 사용하는 경우 다음과 같이 IDE를 사용하여 번들 구성 파일을 생성할 수 있을 뿐만 아니라 파일의 구문과 형식을 확인하고 코드 완성 힌트를 제공할 수도 있습니다.

Visual Studio Code

예를 들어 Visual Studio Code 마켓플레이스에서 YAML 확장을 설치하여 VISUAL Studio Code에 YAML 언어 서버 지원을 추가합니다.
Databricks CLI를 사용함으로써 Databricks 자산 번들 구성 JSON 스키마 파일을 생성하여 bundle schema 명령을 실행하고 출력을 JSON 파일로 리디렉션합니다. 예를 들어 다음과 같이 현재 디렉터리 내에 bundle_config_schema.json이라는 이름의 파일을 생성합니다.
```
databricks bundle schema > bundle_config_schema.json
```
Visual Studio Code를 사용하여 현재 디렉터리 내에서 번들 구성 파일을 만들거나 엽니다. 규칙에 따라 이 파일의 이름은 databricks.yml입니다.
번들 구성 파일의 시작 부분에 다음 설명을 추가합니다.
```
# yaml-language-server: $schema=bundle_config_schema.json
```
참고 항목

앞의 설명에서 Databricks 자산 번들 구성 JSON 스키마 파일이 다른 경로에 있는 경우 bundle_config_schema.json을 스키마 파일의 전체 경로로 바꿉니다.
이전에 추가한 YAML 언어 서버 기능을 사용합니다. 자세한 내용은 YAML 언어 서버의 설명서를 참조하세요.

PyCharm Professional

Databricks CLI를 사용함으로써 Databricks 자산 번들 구성 JSON 스키마 파일을 생성하여 bundle schema 명령을 실행하고 출력을 JSON 파일로 리디렉션합니다. 예를 들어 다음과 같이 현재 디렉터리 내에 bundle_config_schema.json이라는 이름의 파일을 생성합니다.
```
databricks bundle schema > bundle_config_schema.json
```
번들 구성 JSON 스키마 파일을 인식하도록 PyCharm을 구성한 다음 사용자 지정 JSON 스키마 구성의 지침에 따라 JSON 스키마 매핑을 완료합니다.
PyCharm을 사용하여 번들 구성 파일을 만들거나 엽니다. 규칙에 따라 이 파일의 이름은 databricks.yml입니다. 입력할 때 PyCharm은 JSON 스키마 구문 및 서식을 확인하고 코드 완료 힌트를 제공합니다.

IntelliJ IDEA Ultimate

Databricks CLI를 사용함으로써 Databricks 자산 번들 구성 JSON 스키마 파일을 생성하여 bundle schema 명령을 실행하고 출력을 JSON 파일로 리디렉션합니다. 예를 들어 다음과 같이 현재 디렉터리 내에 bundle_config_schema.json이라는 이름의 파일을 생성합니다.
```
databricks bundle schema > bundle_config_schema.json
```
번들 구성 JSON 스키마 파일을 인식하도록 IntelliJ IDEA를 구성한 다음 사용자 지정 JSON 스키마 구성의 지침에 따라 JSON 스키마 매핑을 완료합니다.
IntelliJ IDEA를 사용하여 번들 구성 파일을 만들거나 엽니다. 규칙에 따라 이 파일의 이름은 databricks.yml입니다. 입력할 때 IntelliJ IDEA는 JSON 스키마 구문 및 서식을 확인하고 코드 완료 힌트를 제공합니다.

3단계: dbx 프로젝트 설정을 databricks.yml으로 변환

dbx 프로젝트 .dbx/project.json 파일의 설정을 번들 databricks.yml 파일의 해당 설정으로 변환합니다. 자세한 내용은 dbx 프로젝트 설정을 databricks.yml로 변환을 참조하세요.

4단계: dbx 배포 설정을 databricks.yml으로 변환

dbx 프로젝트 conf 폴더의 설정을 번들 databricks.yml 파일의 해당 설정으로 변환합니다. 자세한 내용은 dbx 프로젝트 배포를 databricks.yml로 변환을 참조하세요.

5단계: 번들 유효성 검사

아티팩트를 배포하거나 Azure Databricks 작업, Delta Live Tables 파이프라인 또는 MLOps 파이프라인을 실행하기 전에 번들 구성 파일의 구문이 올바른지 확인해야 합니다. 이 작업을 수행하려면 번들 루트에서 bundle validate 명령을 실행합니다.

databricks bundle validate

bundle validate에 대한 자세한 내용은 번들 유효성 검사를 참조하세요.

6단계: 번들 배포

지정된 로컬 아티팩트를 원격 작업 영역에 배포하려면 번들 루트에서 bundle deploy 명령을 실행합니다. 명령 옵션이 지정되지 않으면 번들 구성 파일에 선언된 기본 대상이 사용됩니다.

databricks bundle deploy

특정 대상의 컨텍스트 내에서 아티팩트를 배포하려면 번들 구성 파일 내에서 선언된 대상 이름과 함께 -t(또는 --target) 옵션을 지정합니다. 예를 들어 development 이름으로 선언된 대상의 경우 다음과 같습니다.

databricks bundle deploy -t development

bundle deploy에 대한 자세한 내용은 번들 배포를 참조하세요.

팁

Azure Databricks 작업 영역에서 번들로 정의된 작업 및 파이프라인을 기존 작업 및 파이프라인에 연결하여 동기화 상태를 유지할 수 있습니다. 번들 리소스 바인딩을 참조하세요.

7단계: 번들 실행

특정 작업이나 파이프라인을 실행하려면 번들 루트에서 bundle run 명령을 실행합니다. 번들 구성 파일 내에서 선언된 작업 또는 파이프라인을 지정해야 합니다. -t 옵션을 지정하지 않으면 번들 구성 파일 내에 선언된 기본 대상이 사용됩니다. 예를 들어, 기본 대상의 컨텍스트 내에서 이름이 hello_job인 작업을 실행하려면 다음과 같이 합니다.

databricks bundle run hello_job

이름이 development(으)로 선언된 대상의 컨텍스트 내에서 이름이 hello_job인 작업을 실행하려면:

databricks bundle run -t development hello_job

bundle run에 대한 자세한 내용은 번들 실행을 참조하세요.

(선택 사항) 8단계: GitHub을 사용하여 CI/CD를 위한 번들 구성

CI/CD에 GitHub을 사용하는 경우 GitHub Actions를 사용하여 특정 GitHub 워크플로 이벤트 및 기타 기준에 따라 databricks bundle deploy 및 databricks bundle run 명령을 자동으로 실행할 수 있습니다. Databricks 자산 번들 및 GitHub Actions를 사용하여 CI/CD 워크플로 실행을 참조하세요.

dbx 프로젝트 설정을 databricks.yml으로 변환

dbx의 경우, 프로젝트 설정은 기본적으로 프로젝트 .dbx 폴더에 있는 project.json(이)라는 이름의 파일에 저장됩니다. 프로젝트 SDK 참조를 참조하세요.

번들의 경우 번들 구성은 기본적으로 번들의 루트 폴더 내에 이름이 databricks.yml인 파일에 있습니다. Databricks 자산 번들 구성을 참조하세요.

다음 콘텐츠가 포함된 conf/project.json 파일을 만듭니다.

{
  "environments": {
    "default": {
      "profile": "charming-aurora",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Shared/dbx/charming_aurora",
        "artifact_location": "/Shared/dbx/projects/charming_aurora"
      }
    }
  },
  "inplace_jinja_support": true
}

해당 databricks.yml 파일은 다음과 같습니다.

bundle:
  name: <some-unique-bundle-name>

targets:
  default:
    workspace:
      profile: charming-aurora
      root_path: /Shared/dbx/charming_aurora
      artifact_path: /Shared/dbx/projects/charming_aurora
    resources:
      # See an example "resources" mapping in the following section.

이 예제의 이전 conf/project.json 파일에 있는 다음 개체는 databricks.yml 파일에서 지원되지 않으며 해결 방법이 없습니다.

inplace_jinja_support
storage_type

conf/project.json 파일에서 허용되는 추가 개체는 다음과 같으며 databricks.yml 파일에서 지원되지 않으며 해결 방법이 없습니다.

enable-context-based-upload-for-execute
enable-failsafe-cluster-reuse-with-assets

dbx 배포 설정을 databricks.yml으로 변환

dbx의 경우, 배포 설정은 기본적으로 프로젝트 conf 폴더 내의 파일에 있습니다. 배포 파일 참조를 참조하세요. 기본적으로 배포 설정 파일의 이름은 다음 파일 이름 중 하나입니다.

deployment.yml
deployment.yaml
deployment.json
deployment.yml.j2
deployment.yaml.j2
deployment.json.j2

번들의 경우 배포 설정은 기본적으로 번들의 루트 폴더 내에 이름이 databricks.yml인 파일에 있습니다. Databricks 자산 번들 구성을 참조하세요.

다음 콘텐츠가 포함된 conf/deployment.yml 파일을 만듭니다.

build:
  python: "pip"

environments:
  default:
    workflows:
      - name: "workflow1"
        tasks:
          - task_key: "task1"
            python_wheel_task:
              package_name: "some-pkg"
              entry_point: "some-ep"