dbx에서 번들로 마이그레이션

아티클
06/26/2024

Important

Databricks는 Databricks Labs 대신 dbx Databricks 자산 번들을 사용하는 것이 좋습니다. 관련 dbx 문서는 사용 중지되었으며 업데이트되지 않을 수 있습니다.

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

마이그레이션하기 전에 Databricks Labs와 Databricks 자산 번들 간의 dbx 다음과 같은 제한 사항 및 기능 비교에 유의하세요.

제한 사항

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

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

기능 비교

마이그레이션하기 전에 Databricks Labs의 다음 기능이 dbx Databricks 자산 번들에서 어떻게 구현되는지 확인합니다.

템플릿 및 프로젝트

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

번들은 구성 재사용을 위해 Go 템플릿을 지원합니다 . 사용자는 미리 빌드된 템플릿을 기반으로 번들을 만들 수 있습니다. 사용자 지정 사용자 함수를 제외하고 템플릿에 대한 패리티가 거의 완전합니다.

빌드 관리

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

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

코드 동기화, 배포 및 실행

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

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

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

Databricks Labs와 Databricks 자산 번들 간의 dbx 이전 제한 사항 및 기능 비교를 확인하면 번들로 마이그레이션 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단계: 번들 구성 파일 만들기

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

Visual Studio Code

예를 들어 Visual Studio Code Marketplace에서 YAML 확장을 설치하여 VISUAL Studio Code에 YAML 언어 서버 지원을 추가합니다.
Databricks CLI를 사용하여 Databricks Asset Bundle 구성 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 Asset Bundle 구성 JSON 스키마 파일이 다른 경로에 있는 경우 스키마 파일의 전체 경로로 바꿉 bundle_config_schema.json 니다.
이전에 추가한 YAML 언어 서버 기능을 사용합니다. 자세한 내용은 YAML 언어 서버의 설명서를 참조하세요.

PyCharm Professional

Databricks CLI를 사용하여 Databricks Asset Bundle 구성 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 Asset Bundle 구성 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/project.json 설정을 dbx 번들 파일의 databricks.yml 해당 설정으로 변환합니다. 자세한 내용은 dbx 프로젝트 설정을 databricks.yml 변환을 참조하세요.

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

프로젝트 폴더의 conf 설정을 dbx 번들 파일의 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

특정 대상의 컨텍스트 내에서 아티팩트를 배포하려면 번들 구성 파일 내에 선언된 대상 이름과 함께 (또는--target) 옵션을 지정 -t 합니다. 예를 들어 이름으로 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 run 기타 조건에 따라 명령 및 명령을 자동으로 실행할 databricks bundle deploy 수 있습니다. Databricks 자산 번들 및 GitHub Actions를 사용하여 CI/CD 워크플로 실행을 참조 하세요.

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

프로젝트 dbx설정은 기본적으로 프로젝트 폴더에 .dbx 이름이 지정된 project.json 파일에 있습니다. 프로젝트 파일 참조를 참조하세요.

번들의 경우 번들 구성은 기본적으로 번들의 루트 폴더 내에 있는 파일에 있습니다 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"