Databricks 자산 번들 구성

아티클
05/03/2024

이 문서에서는 Databricks 자산 번들을 정의하는 Databricks 자산 번들 구성 파일의 구문을 설명합니다. Databricks 자산 번들이란?

번들 구성 파일은 YAML 형식으로 표현되어야 하며 최소한 최상위 번 들 매핑을 포함해야 합니다. 각 번들에는 이름이 지정된 databricks.yml번들 구성 파일이 하나 이상 포함되어야 합니다. 여러 번들 구성 파일이 있는 경우 파일에서 databricks.yml 참조해야 합니다.

YAML에 대한 자세한 내용은 공식 YAML 사양 및 자습서를 참조하세요.

번들 구성 파일을 만들고 사용하려면 Databricks 자산 번들 개발을 참조하세요.

개요
예제
매핑
사용자 지정 변수
대체

개요

이 섹션에서는 번들 구성 파일 스키마의 시각적 표현을 제공합니다. 자세한 내용은 매핑을 참조 하세요.

# These is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  compute_id: string
  git:
    origin_url: string
    branch: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string

# These are the default workspace settings if not otherwise overridden in
# the following "targets" top-level mapping.
workspace:
  artifact_path: string
  auth_type: string
  azure_client_id: string # For Azure Databricks only.
  azure_environment: string # For Azure Databricks only.
  azure_login_app_id: string # For Azure Databricks only. Non-operational and reserved for future use.
  azure_tenant_id: string # For Azure Databricks only.
  azure_use_msi: true | false # For Azure Databricks only.
  azure_workspace_resource_id: string # For Azure Databricks only.
  client_id: string # For Databricks on AWS only.
  file_path: string
  google_service_account: string # For Databricks on Google Cloud only.
  host: string
  profile: string
  root_path: string
  state_path: string

# These are the permissions to apply to experiments, jobs, models, and pipelines defined
# in the "resources" mapping.
permissions:
  - level: <permission-level>
    group_name: <unique-group-name>
  - level: <permission-level>
    user_name: <unique-user-name>
  - level: <permission-level>
    service_principal_name: <unique-principal-name>

# These are the default artifact settings if not otherwise overridden in
# the following "targets" top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    files:
      - source: string
    path: string
    type: string

# These are any additional configuration files to include.
include:
  - "<some-file-or-path-glob-to-include>"
  - "<another-file-or-path-glob-to-include>"

# This is the identity to use to run the bundle
run_as:
  - user_name: <user-name>
  - service_principal_name: <service-principal-name>

# These are the default job and pipeline settings if not otherwise overridden in
# the following "targets" top-level mapping.
resources:
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the Experiments API's create experiment request payload reference.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See the Jobs API's create job request payload reference.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the Models API's create model request payload reference.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the Delta Live Tables API's create pipeline request payload reference.

# These are any additional files or paths to include or exclude.
sync:
  include:
    - "<some-file-or-path-glob-to-include>"
    - "<another-file-or-path-glob-to-include>"
  exclude:
    - "<some-file-or-path-glob-to-exclude>"
    - "<another-file-or-path-glob-to-exclude>"

# These are the targets to use for deployments and workflow runs. One and only one of these
# targets can be set to "default: true".
targets:
  <some-unique-programmatic-identifier-for-this-target>:
    artifacts:
      # See the preceding "artifacts" syntax.
    bundle:
      # See the preceding "bundle" syntax.
    compute_id: string
    default: true | false
    mode: development
    resources:
      # See the preceding "resources" syntax.
    sync:
      # See the preceding "sync" syntax.
    variables:
      <preceding-unique-variable-name>: <non-default-value>
    workspace:
      # See the preceding "workspace" syntax.
    run_as:
      # See the preceding "run_as" syntax.

예

다음은 번들 구성 파일의 예입니다. 이 번들은 이름이 databricks.yml지정된 로컬 번들 구성 파일과 동일한 디렉터리에 있는 hello.py 로컬 파일의 원격 배포를 지정합니다. 지정된 클러스터 ID가 있는 원격 클러스터를 사용하여 이 Notebook을 작업으로 실행합니다. 원격 작업 영역 URL 및 작업 영역 인증 자격 증명은 호출자의 로컬 구성 프로필에서 DEFAULT읽습니다.

참고 항목

Databricks는 가능한 경우 매핑 대신 default 매핑을 사용하는 host 것이 좋습니다. 이렇게 하면 번들 구성 파일이 더 이식 가능합니다. 매핑을 host 설정하면 Databricks CLI가 파일에서 .databrickscfg 일치하는 프로필을 찾은 다음 해당 프로필의 필드를 사용하여 사용할 Databricks 인증 유형을 결정하도록 지시합니다. 일치하는 host 필드가 있는 여러 프로필이 파일 내에 .databrickscfg 있는 경우 이 프로필을 사용하여 profile 사용할 특정 프로필에 대해 Databricks CLI에 지시해야 합니다. 예를 들어 이 섹션의 뒷부분에 있는 prod 대상 선언을 참조하세요.

이 기술을 사용하면 블록 내에서 resources 작업 정의 및 설정을 재정의할 뿐만 아니라 다시 사용할 수 있습니다.

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true

다음 번들 구성 파일은 기능적으로 동일하지만 모듈화되지 않으므로 다시 사용할 수 없습니다. 또한 이 선언은 기존 작업을 재정의하는 작업 대신 작업에 작업을 추가합니다.

bundle:
  name: hello-bundle

targets:
  dev:
    default: true
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 1234-567890-abcde123
              notebook_task:
                notebook_path: ./hello.py

다음은 이전의 모듈화된 예제이지만 다른 원격 작업 영역 URL 및 작업 영역 인증 자격 증명을 사용하는 프로그래밍 방식(또는 논리적) 이름으로 prod 대상을 추가하여 호출자의 .databrickscfg 파일과 일치하는 host 항목에서 지정된 작업 영역 URL로 읽습니다. 이 작업은 동일한 Notebook을 실행하지만 지정된 클러스터 ID가 있는 다른 원격 클러스터를 사용합니다. 매핑 내에서 매핑이 명시적으로 재정의 notebook_taskprod 되지 않은 경우 notebook_task 최상위 resources 매핑 내에서 매핑을 사용하기 notebook_task 위해 대체되므로 매핑 내에서 prod 매핑을 선언할 필요가 없습니다.

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

대상 내에서 dev 이 작업의 유효성을 검사, 배포 및 실행하려면 다음 명령을 실행합니다.

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run hello_job

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev hello_job

대신 대상 내에서 prod 이 작업의 유효성을 검사, 배포 및 실행하려면 다음 명령을 실행합니다.

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod hello_job

다음은 이전 예제이지만 더 많은 모듈화를 위해 구성 요소 파일로 분할하고 여러 번들 구성 파일에서 더 잘 재사용하는 예제입니다. 이 기술을 사용하면 다양한 정의와 설정을 다시 사용할 수 있을 뿐만 아니라 완전히 다른 선언을 제공하는 다른 파일로 이러한 파일을 교환할 수도 있습니다.

databricks.yml:

bundle:
  name: hello-bundle

include:
  - "bundle*.yml"

bundle.resources.yml:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

bundle.targets.yml:

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

자세한 예제는 GitHub의 번들 예제 리포지토리를 참조하세요.

매핑을

다음 섹션에서는 최상위 매핑을 통해 번들 구성 파일 구문을 설명합니다.

bundle
variables
작업 영역
permissions
artifacts
include
resources
sync
대상

보따리

번들 구성 파일에는 번들의 콘텐츠와 Azure Databricks 작업 영역 설정을 연결하는 최상위 bundle 매핑이 하나만 포함되어야 합니다.

이 bundle 매핑에는 번들에 대한 프로그래밍 방식(또는 논리적) 이름을 지정하는 매핑이 포함되어 name 야 합니다. 다음 예제에서는 프로그래밍 방식(또는 논리적) 이름으로 hello-bundle번들을 선언합니다.

bundle:
  name: hello-bundle

매핑은 bundle 최상위 대상 매핑에서 하나 이상의 대상의 자식일 수도 있습니다 . 이러한 각 자식 bundle 매핑은 대상 수준에서 기본이 아닌 재정의를 지정합니다. 그러나 최상위 bundle 매핑의 값은 대상 수준에서 재정의 name 할 수 없습니다.

compute_id

매핑에는 bundle 자식 compute_id 매핑이 있을 수 있습니다. 이 매핑을 사용하면 번들 구성 파일의 다른 곳에 정의된 모든 클러스터에 대한 재정의로 사용할 클러스터의 ID를 지정할 수 있습니다. 이 재정의는 프로덕션 이전의 개발 전용 시나리오를 위한 것입니다. 매핑은 compute_id 매핑이 설정된 대상 mode 에 대해서만 작동합니다 development. 매핑에 대한 compute_id 자세한 내용은 대상 매핑을 참조하세요 .

git

번들과 연결된 Git 버전 제어 세부 정보를 검색하고 재정의할 수 있습니다. 배포된 리소스에 주석을 추가할 때 유용합니다. 예를 들어 배포하는 기계 학습 모델에 대한 설명 내에 리포지토리의 원본 URL을 포함할 수 있습니다.

또는 명령과 같은 bundlerundeployvalidate명령을 실행할 bundle 때마다 명령은 명령의 구성 트리를 다음 기본 설정으로 채웁니다.

bundle.git.origin_url- 리포지토리의 원본 URL을 나타냅니다. 복제된 리포지토리에서 명령을 git config --get remote.origin.url 실행한 경우 얻을 수 있는 값과 동일합니다. 대체를 사용하여 번들 구성 파일${bundle.git.origin_url}에서 이 값을 참조할 수 있습니다.
bundle.git.branch- 리포지토리 내의 현재 분기를 나타냅니다. 복제된 리포지토리에서 명령을 git branch --show-current 실행한 경우 얻을 수 있는 값과 동일합니다. 대체를 사용하여 번들 구성 파일${bundle.git.branch}에서 이 값을 참조할 수 있습니다.
bundle.git.commit- 리포지토리 내의 HEAD 커밋을 나타냅니다. 복제된 리포지토리에서 명령을 git rev-parse HEAD 실행한 경우 얻을 수 있는 값과 동일합니다. 대체를 사용하여 번들 구성 파일${bundle.git.commit}에서 이 값을 참조할 수 있습니다.

Git 설정을 검색하거나 재정의하려면 번들이 Git 리포지토리와 연결된 디렉터리 내에 있어야 합니다(예: 명령을 실행 git clone 하여 초기화된 로컬 디렉터리). 디렉터리가 Git 리포지토리와 연결되지 않은 경우 이러한 Git 설정은 비어 있습니다.

필요한 경우 다음과 같이 최상위 bundle 매핑의 매핑 내에서 git 설정과 branch 설정을 재정 origin_url 의할 수 있습니다.

bundle:
  git:
    origin_url: <some-non-default-origin-url>
    branch: <some-non-current-branch-name>

databricks_cli_version

매핑에는 bundle 번들에 필요한 Databricks CLI 버전을 제한하는 매핑이 포함될 databricks_cli_version 수 있습니다. 이렇게 하면 특정 버전의 Databricks CLI에서 지원되지 않는 매핑을 사용하여 발생하는 문제를 방지할 수 있습니다.

Databricks CLI 버전은 의미 체계 버전 지정을 준수하며 매핑은 databricks_cli_version 버전 제약 조건 지정을 지원합니다. 현재 databricks --version 값이 번들의 매핑에 지정된 범위 내에 있지 않으면 번들 databricks_cli_version 에서 실행될 때 databricks bundle validate 오류가 발생합니다. 다음 예제에서는 몇 가지 일반적인 버전 제약 조건 구문을 보여 줍니다.

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.0" # require Databricks CLI 0.218.0

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.*" # allow all patch versions of Databricks CLI 0.218

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0" # allow any version of Databricks CLI 0.218.0 or higher

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0, <= 1.0.0" # allow any Databricks CLI version between 0.218.0 and 1.0.0, inclusive

변수

번들 설정 파일에는 사용할 변수 설정을 지정하는 최상위 매핑이 하나 variables 포함될 수 있습니다. 사용자 지정 변수를 참조 하세요.

작업

번들 구성 파일에는 사용할 기본이 아닌 Azure Databricks 작업 영역 설정을 지정하는 최상위 workspace 매핑이 하나만 포함될 수 있습니다.

이 workspace 매핑에는 배포 및 워크플로 실행 모두에 대해 작업 영역 내에서 사용할 기본이 아닌 루트 경로를 지정하는 매핑이 포함될 root_path 수 있습니다. 예를 들면 다음과 같습니다.

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

기본적으로 Databricks CLI의 경우 root_path 대체를 사용하는 기본 경로를 /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}사용합니다.

또한 이 workspace 매핑에는 배포 및 워크플로 실행 모두에 대해 작업 영역 내에서 사용할 기본이 아닌 아티팩트 경로를 지정하는 매핑이 포함될 artifact_path 수 있습니다. 예를 들면 다음과 같습니다.

workspace:
  artifact_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/artifacts

기본적으로 Databricks CLI의 경우 artifact_path 대체를 사용하는 기본 경로를 ${workspace.root}/artifacts사용합니다.

.. 참고:: 매핑은 artifact_path DBFS(Databricks 파일 시스템) 경로를 지원하지 않습니다.

이 workspace 매핑에는 배포 및 워크플로 실행 모두에 대해 작업 영역 내에서 사용할 기본이 아닌 파일 경로를 지정하는 매핑이 포함될 file_path 수도 있습니다. 예를 들면 다음과 같습니다.

workspace:
  file_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/files

기본적으로 Databricks CLI의 경우 file_path 대체를 사용하는 기본 경로를 ${workspace.root}/files사용합니다.

매핑은 state_path 기본적으로 기본 경로로 설정되며 배포에 대한 Terraform 상태 정보를 저장할 작업 영역 내의 ${workspace.root}/state 경로를 나타냅니다.

매핑에는 workspace 사용할 Azure Databricks 인증 메커니즘을 지정하는 다음과 같은 선택적 매핑이 포함될 수도 있습니다. 이 workspace 매핑 내에 지정되지 않은 경우 매핑에서 최상위 대상 매핑에서 workspace 하나 이상의 대상에 대한 자식으로 지정해야 합니다.

Important

Azure Databricks 인증을 위해 다음 workspace 매핑에 대한 하드 코드 값을 지정해야 합니다. 예를 들어 구문을 사용하여 이러한 매핑 값에 대한 사용자 지정 변수를 ${var.*} 지정할 수 없습니다.

매핑(또는 --profile-p 번들을 실행할 때 Databricks CLI를 사용하여 명령 유효성 검사, 배포, 실행 및 삭제)은 profile Azure Databricks 인증에 이 작업 영역에서 사용할 구성 프로필의 이름을 지정합니다. 이 구성 프로필은 Databricks CLI를 설정할 때 만든 프로필에 매핑됩니다.

참고 항목

Databricks는 번들 구성 파일을 더 이식 가능하게 하므로 매핑 대신 매핑(또는 -p--profile 번들을 실행할 때 Databricks CLI를 사용하여 명령 유효성 profile 검사, 배포, 실행 및 삭제)을 사용하는 host 것이 좋습니다. 매핑을 host 설정하면 Databricks CLI가 파일에서 .databrickscfg 일치하는 프로필을 찾은 다음 해당 프로필의 필드를 사용하여 사용할 Databricks 인증 유형을 결정하도록 지시합니다. 일치하는 host 필드가 있는 여러 프로필이 파일 내에 .databrickscfg 있는 경우 매핑(또는 --profile-p 명령줄 옵션)을 사용하여 profile 사용할 프로필에 대해 Databricks CLI에 지시해야 합니다. 예제는 예제의 prod 대상 선언을 참조하세요.
매핑은 host Azure Databricks 작업 영역의 URL을 지정합니다. 작업 영역별 URL을 참조하세요.
OAuth M2M(컴퓨터-컴퓨터) 인증의 경우 매핑 client_id 이 사용됩니다. 또는 로컬 환경 변수 DATABRICKS_CLIENT_ID에서 이 값을 설정할 수 있습니다. 또는 값을 사용하여 구성 프로필을 client_id 만든 다음 매핑을 profile 사용하여 프로필의 이름을 지정할 수 있습니다(또는 번들을 실행할 때 또는 -p 옵션을 사용하여 Databricks CLI를 사용하여 --profile 명령 유효성 검사, 배포, 실행 및 삭제). OAuth M2M(컴퓨터-컴퓨터) 인증을 참조하세요.

참고 항목

번들 구성 파일에서 Azure Databricks OAuth 비밀 값을 지정할 수 없습니다. 대신 로컬 환경 변수 DATABRICKS_CLIENT_SECRET를 설정합니다. 또는 구성 프로필에 client_secret 값을 추가한 다음 매핑을 사용하여 프로필의 이름을 profile 지정할 수 있습니다(또는 번들을 실행할 때 또는 -p 옵션을 사용하여 Databricks CLI를 사용하여 --profile 명령 유효성 검사, 배포, 실행 및 삭제).
Azure CLI 인증의 경우 매핑 azure_workspace_resource_id 이 사용됩니다. 또는 로컬 환경 변수 DATABRICKS_AZURE_RESOURCE_ID에서 이 값을 설정할 수 있습니다. 또는 값을 사용하여 구성 프로필을 azure_workspace_resource_id 만든 다음 매핑을 profile 사용하여 프로필의 이름을 지정할 수 있습니다(또는 번들을 실행할 때 또는 -p 옵션을 사용하여 Databricks CLI를 사용하여 --profile 명령 유효성 검사, 배포, 실행 및 삭제). Azure CLI 인증을 참조하세요.
서비스 주체를 사용한 Azure 클라이언트 비밀 인증의 경우 매핑azure_workspace_resource_idazure_tenant_id이 azure_client_id 사용되며 사용됩니다. 또는 로컬 환경 변수 DATABRICKS_AZURE_RESOURCE_IDARM_TENANT_IDARM_CLIENT_ID및 각각에서 이러한 값을 설정할 수 있습니다. 또는 , azure_tenant_id및 값을 사용하여 구성 프로필을 azure_workspace_resource_id만든 다음 매핑을 사용하여 프로필의 이름을 profile 지정할 수 있습니다(또는 번들을 실행할 때 또는 Databricks CLI를 사용하여 명령 유효성 검사, 배포, 실행 및 삭제를 실행할 때 또는 -p 옵션을 사용하여 --profileazure_client_id). Microsoft Entra ID 서비스 주체 인증을 참조하세요.

참고 항목

번들 구성 파일에서 Azure 클라이언트 비밀 값을 지정할 수 없습니다. 대신 로컬 환경 변수 ARM_CLIENT_SECRET를 설정합니다. 또는 구성 프로필에 azure_client_secret 값을 추가한 다음 매핑을 사용하여 프로필의 이름을 profile 지정할 수 있습니다(또는 번들을 실행할 때 또는 -p 옵션을 사용하여 Databricks CLI를 사용하여 --profile 명령 유효성 검사, 배포, 실행 및 삭제).
Azure 관리 ID 인증의 경우 매핑이 azure_use_msiazure_client_idazure_workspace_resource_id 사용되며 사용됩니다. 또는 로컬 환경 변수 ARM_USE_MSIARM_CLIENT_IDDATABRICKS_AZURE_RESOURCE_ID및 각각에서 이러한 값을 설정할 수 있습니다. 또는 , azure_client_id및 값을 사용하여 구성 프로필을 azure_use_msi만든 다음 매핑을 사용하여 프로필의 이름을 profile 지정할 수 있습니다(또는 번들을 실행할 때 또는 Databricks CLI를 사용하여 명령 유효성 검사, 배포, 실행 및 삭제를 실행할 때 또는 -p 옵션을 사용하여 --profileazure_workspace_resource_id). Azure 관리 ID 인증을 참조하세요.
매핑은 azure_environment 특정 API 엔드포인트 집합에 대한 Azure 환경 유형(예: 공용, UsGov, 중국 및 독일)을 지정합니다. 기본값은 PUBLIC입니다. 또는 로컬 환경 변수 ARM_ENVIRONMENT에서 이 값을 설정할 수 있습니다. 또는 구성 프로필에 azure_environment 값을 추가한 다음 매핑을 사용하여 프로필의 이름을 profile 지정할 수 있습니다(또는 번들을 실행할 때 또는 -p 옵션을 사용하여 Databricks CLI를 사용하여 --profile 명령 유효성 검사, 배포, 실행 및 삭제).
매핑은 azure_login_app_id 비작동이며 내부용으로 예약되어 있습니다.
매핑은 auth_type 특히 Databricks CLI가 예기치 않은 인증 유형을 유추하는 경우 사용할 Azure Databricks 인증 유형을 지정합니다. 인증 유형 필드를 참조하세요.

권한을

최상위 permissions 매핑은 번들에 정의된 모든 리소스에 적용할 하나 이상의 사용 권한 수준을 지정합니다. 특정 리소스에 사용 권한을 적용하려면 특정 리소스에 대한 권한 정의를 참조하세요.

허용되는 최상위 권한 수준은 CAN_VIEW, CAN_MANAGE및 CAN_RUN.

번들 구성 파일의 다음 예제는 번들에 정의된 모든 작업, 파이프라인, 실험 및 모델에 적용되는 사용자, 그룹 및 서비스 주체에 resources 대한 사용 권한 수준을 정의합니다.

permissions:
  - level: CAN_VIEW
    group_name: test-group
  - level: CAN_MANAGE
    user_name: someone@example.com
  - level: CAN_RUN
    service_principal_name: 123456-abcdef

아티팩트

최상위 artifacts 매핑은 번들 배포 중에 자동으로 빌드되고 나중에 번들 실행에서 사용할 수 있는 하나 이상의 아티팩트만 지정합니다. 각 자식 아티팩트에서 지원하는 매핑은 다음과 같습니다.

type은 필수입니다. 배포하기 전에 Python 휠 파일을 빌드하려면 이 매핑을 .로 설정 whl해야 합니다.
path 는 번들 구성 파일의 위치에서 Python 휠 파일의 위치까지의 선택적 상대 경로입니다 setup.py . 포함되지 않은 경우 path Databricks CLI는 번들의 루트에서 Python 휠 파일의 setup.py 파일을 찾으려고 시도합니다.
files 는 복잡한 빌드 지침에 포함할 기본이 아닌 위치를 지정하는 데 사용할 수 있는 자식 source 매핑을 포함하는 선택적 매핑입니다. 위치는 번들 구성 파일의 위치에서 상대 경로로 지정됩니다.
build 는 배포 전에 로컬로 실행하려는 기본이 아닌 빌드 명령의 선택적 집합입니다. Python 휠 빌드의 경우 Databricks CLI는 빌드를 실행할 Python wheel 패키지의 로컬 설치를 찾을 수 있다고 가정하고 각 번들 배포 중에 기본적으로 명령을 python setup.py bdist_wheel 실행합니다. 여러 빌드 명령을 지정하려면 각 명령을 이중 앰퍼샌드(&&) 문자로 구분합니다.

사용하는 artifacts샘플 번들을 비롯한 자세한 내용은 Databricks 자산 번들을 사용하여 Python 휠 파일 개발을 참조 하세요.

팁

Databricks 자산 번들의 아티팩트 설정 정의에 설명된 기술을 사용하여 번들의 아티팩트 설정을 정의, 결합 및 재정의할 수 있습니다.

포함하다

배열은 include 번들 내에 포함할 구성 파일을 포함하는 경로 globs 목록을 지정합니다. 이러한 경로 GLOB는 경로 GLOB가 지정된 번들 구성 파일의 위치를 기준으로 합니다.

Databricks CLI는 기본적으로 번들 내에 구성 파일을 포함하지 않습니다. 배열을 include 사용하여 파일 자체를 제외한 databricks.yml 번들 내에 포함할 모든 구성 파일을 지정해야 합니다.

이 배열은 include 최상위 매핑으로만 나타날 수 있습니다.

번들 구성 파일의 다음 예제에는 지정된 세 개의 구성 파일이 포함됩니다. 이러한 파일은 번들 구성 파일과 동일한 디렉터리에 있습니다.

include:
  - "bundle.artifacts.yml"
  - "bundle.resources.yml"
  - "bundle.targets.yml"

번들 구성 파일의 다음 예제에는 파일 이름으로 시작하고 bundle 끝나는 .yml모든 파일이 포함됩니다. 이러한 파일은 번들 구성 파일과 동일한 디렉터리에 있습니다.

include:
  - "bundle*.yml"

리소스

매핑은 resources 번들에서 사용하는 Azure Databricks 리소스에 대한 정보를 지정합니다.

이 매핑은 resources 최상위 매핑으로 표시되거나 최상위 대상 매핑에 있는 하나 이상의 대상의 자식일 수 있으며 지원되는 리소스 종류 중 하나 또는 0개를 포함할 수 있습니다. 각 리소스 종류 매핑에는 각각 고유한 이름이 있어야 하는 하나 이상의 개별 리소스 선언이 포함됩니다. 이러한 개별 리소스 선언은 YAML로 표현된 해당 개체의 만들기 작업의 요청 페이로드를 사용하여 리소스를 정의합니다. 리소스에 대해 지원되는 속성은 해당 개체의 지원되는 필드입니다.

작업 요청 만들기 페이로드는 Databricks REST API 참조에 설명되어 있으며 databricks bundle schema 명령은 지원되는 모든 개체 스키마를 출력합니다. 또한 databricks bundle validate 이 명령은 번들 구성 파일에서 알 수 없는 리소스 속성이 발견되면 경고를 반환합니다.

다음 표에서는 번들에 대해 지원되는 리소스 종류와 해당 페이로드에 대한 설명서에 대한 링크를 나열합니다.

리소스 종류	리소스 매핑
`jobs`	작업 매핑: POST /api/2.1/jobs/create 자세한 내용은 작업 작업 유형을 참조하고 새 작업 클러스터 설정을 재정의합니다.
`pipelines`	파이프라인 매핑: POST /api/2.0/pipelines
`experiments`	실험 매핑: POST /api/2.0/mlflow/experiments/create
`models`	모델 매핑: POST /api/2.0/mlflow/registered-models/create
`model_serving_endpoints`	엔드포인트 매핑을 제공하는 모델: POST /api/2.0/serving-endpoints
`registered_models` (Unity 카탈로그)	Unity 카탈로그 모델 매핑: POST /api/2.1/unity-catalog/models

리소스 선언에서 참조하는 폴더 및 파일에 대한 모든 경로는 이러한 경로가 지정된 번들 구성 파일의 위치를 기준으로 합니다.

다음 예제에서는 리소스 키가 있는 작업과 리소스 키가 hello-job 있는 파이프라인을 hello-pipeline선언합니다.

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py
  pipelines:
    hello-pipeline:
      name: hello-pipeline
      clusters:
        - label: default
          num_workers: 1
      development: true
      continuous: false
      channel: CURRENT
      edition: CORE
      photon: false
      libraries:
        - notebook:
            path: ./pipeline.py

동기화

배열은 sync 다음 규칙에 따라 번들 배포 내에 포함하거나 번들 배포에서 제외할 파일 또는 경로 globs 목록을 지정합니다.

번들의 루트 include 에 있는 .gitignore 파일의 파일 및 경로 globs 목록에 따라 매핑에는 명시적으로 포함할 파일 GLOB, 경로 globs 또는 둘 다(번들의 루트를 기준으로) 목록이 포함될 수 있습니다.
번들의 루트에 있는 .gitignore 파일의 파일 및 경로 globs 목록과 매핑 exclude 의 파일 및 경로 GLOB include 목록을 기반으로 매핑은 명시적으로 제외할 파일 globs, 경로 globs 또는 둘 다 목록을 포함할 수 있습니다.

지정된 폴더 및 파일에 대한 모든 경로는 이러한 경로가 지정된 번들 구성 파일의 위치를 기준으로 합니다.

파일 및 exclude 경로 패턴의 구문 include 은 표준 .gitignore 패턴 구문을 따릅니다. gitignore 패턴 형식을 참조하세요.

예를 들어 다음 파일에 다음 .gitignore 항목이 포함되어 있으면 다음과 같습니다.

.databricks
my_package/dist

그리고 번들 구성 파일에는 다음 include 매핑이 포함됩니다.

sync:
  include:
    - my_package/dist/*.whl

그런 다음 파일 확장명인 my_package/dist 폴더의 *.whl 모든 파일이 포함됩니다. 폴더의 my_package/dist 다른 파일은 포함되지 않습니다.

그러나 번들 구성 파일에 다음 매핑도 포함된 경우:exclude

sync:
  include:
    - my_package/dist/*.whl
  exclude:
    - my_package/dist/delete-me.whl

그런 다음 파일 확장명my_package/dist(이름이 지정된 delete-me.whl파일을 제외한)이 있는 폴더의 *.whl모든 파일이 포함됩니다. 폴더의 my_package/dist 다른 파일도 포함되지 않습니다.

sync 특정 대상에 대한 매핑에서 배열을 targets 선언할 수도 있습니다. 대상에 선언된 모든 sync 배열은 최상위 sync 배열 선언과 병합됩니다. 예를 들어 앞의 예제를 계속 진행하면 수준에서 다음 include 매핑 targets 이 최상위 sync 배열의 include 매핑과 병합됩니다.

targets:
  dev:
    sync:
      include:
        - my_package/dist/delete-me.whl

실행할 databricks bundle validate --output json때 결과 그래프의 관련 부분은 다음과 같습니다.

"sync": {
  "include": [
    "my_package/dist/*.whl",
    "my_package/dist/delete-me.whl"
  ],
  "exclude": [
    "my_package/dist/delete-me.whl"
  ]
}

대상

매핑은 targets Azure Databricks 워크플로를 실행할 하나 이상의 컨텍스트를 지정합니다. 각 대상 은 아티팩트, Azure Databricks 작업 영역 설정 및 Azure Databricks 작업 또는 파이프라인 세부 정보의 고유한 컬렉션입니다.

이 targets 매핑은 선택 사항이지만 권장됩니다. 지정된 경우 최상위 매핑으로만 표시될 수 있습니다. 매핑을 targets 지정하지 않으면 최상위 작업 영역, 아티팩트 및 리소스 매핑의 설정이 항상 사용됩니다.

매핑은 targets 각각 고유한 프로그래밍 방식(또는 논리적) 이름이 있어야 하는 하나 이상의 대상 매핑으로 구성됩니다.

대상 매핑에서 자식 매핑 또는 resources 자식 매핑을 지정artifactsworkspace하지 않으면 해당 대상은 최상위 수준 workspaceartifacts및 resources 매핑의 설정을 사용합니다.

대상 매핑이 , 또는 resources 매핑을 지정workspaceartifacts하고 최상위 workspaceartifacts수준 또는 resources 매핑도 있는 경우 충돌하는 설정은 대상 내의 설정에 의해 재정의됩니다.

대상은 최상위 변수의 값을 재정의할 수도 있습니다.

달리 지정하지 않는 한 대상이 기본 대상이 되도록 지정하려면 매핑을 default 다음으로 true설정합니다. 예를 들어 명명된 dev 이 대상은 기본 대상입니다.

targets:
  dev:
    default: true

대상이 개발 대상으로 처리되도록 지정하려면 매핑을 mode 다음으로 설정합니다 development. 대상이 프로덕션 대상으로 처리되도록 지정하려면 매핑을 mode 추가하고 다음으로 production설정합니다. 예를 들어 명명된 prod 이 대상은 프로덕션 대상으로 처리됩니다.

targets:
  prod:
    mode: production

지정하면 mode 사전 프로덕션 및 프로덕션 워크플로에 해당하는 기본 동작 컬렉션이 제공됩니다. 자세한 내용은 Databricks 자산 번들 배포 모드를 참조 하세요. 또한 Databricks 자산 번들 워크플로에 대한 실행 ID 지정에 설명된 대로 각 대상에 대해 지정할 run_as 수 있습니다.

다음 예제에서는 두 개의 대상을 선언합니다. 첫 번째 대상의 이름은 프로그래밍 방식(또는 논리적) dev 이며 기본 대상입니다. 두 번째 대상에는 프로그래밍 방식(또는 논리적) 이름이 prod 있으며 기본 대상이 아닙니다. 이 두 번째 대상은 인증을 위해 명명된 PROD Azure Databricks 연결 프로필을 사용합니다.

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>

대상 내에서 dev 작업 또는 파이프라인의 유효성을 검사, 배포 및 실행하려면 다음 명령을 실행합니다.

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run <job-or-pipeline-programmatic-name>

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev <job-or-pipeline-programmatic-name>

대신 대상 내에서 prod 이 작업의 유효성을 검사, 배포 및 실행하려면 다음 명령을 실행합니다.

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod <job-or-pipeline-programmatic-name>

사용자 지정 변수

사용자 지정 변수를 사용하여 번들 구성 파일을 모듈화하고 재사용 가능하게 만들 수 있습니다. 예를 들어 기존 클러스터의 ID를 나타내는 변수를 선언한 다음 번들 구성 파일의 원래 코드를 변경하지 않고 여러 대상 내에서 실행되는 다양한 워크플로에 대해 해당 변수의 값을 다른 클러스터 ID로 변경하려고 할 수 있습니다.

매핑 내에서 번들 구성 파일에서 하나 이상의 변수를 선언할 variables 수 있습니다. 각 변수에 대해 다음 형식에 따라 선택적 설명, 기본값 또는 조회를 설정하여 ID 값을 검색할 수 있습니다.

variables:
  <variable-name>:
    description: <optional-description>
    default: <optional-default-value>
    lookup:
      <optional-object-type>: <optional-object-name>

예를 들어 기본값으로 명명된 my_cluster_id 변수와 다음의 1234-567890-abcde123기본값./hello.py으로 명명된 my_notebook_path 변수를 선언합니다.

variables:
  my_cluster_id:
    description: The ID of an existing cluster.
    default: 1234-567890-abcde123
  my_notebook_path:
    description: The path to an existing notebook.
    default: ./hello.py

이 선언의 일부로 변수에 대한 값을 제공하지 default 않는 경우 나중에 명령줄, 환경 변수 또는 번들 구성 파일 내의 다른 위치에서 값을 제공해야 합니다. 이러한 방법은 이 섹션의 뒷부분에 설명되어 있습니다.

참고 항목

변수 값을 제공하기 위해 어떤 방법을 선택하든 배포 및 실행 단계 모두에서 동일한 접근 방식을 사용합니다. 그렇지 않으면 배포 시간과 기존 배포를 기반으로 하는 작업 또는 파이프라인 실행 사이에 예기치 않은 결과가 발생할 수 있습니다.

번들 구성 파일 내에서 사용자 지정 변수를 참조하려면 대체를 사용합니다. 변수의 경우 형식 ${var.<variable_name>}을 사용합니다. 예를 들어 다음과 같이 명명 my_cluster_id 된 my_notebook_path변수를 참조합니다.

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ${var.my_notebook_path}

변수 값 설정

변수에 대한 값을 제공하지 default 않았거나 변수의 값을 일시적으로 재정 default 의하려는 경우 다음 방법 중 하나를 사용하여 변수의 새 임시 값을 제공합니다.

변수 값을 명령의 일부로 제공합니다(예: < a0bundle/>)run. deployvalidate 이렇게 하려면 변수의 이름과 <value> 변수의 값인 옵션을 --var="<key>=<value>"<key> 사용합니다. 예를 들어 명령의 bundle validate 일부로 명명된 변수에 1234-567890-abcde123 값을 제공하고 이름이 my_cluster_id지정된 my_notebook_path변수에 ./hello.py 값을 제공하려면 다음을 실행합니다.
```
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py"

# Or:
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"
```
환경 변수를 설정하여 변수의 값을 제공합니다. 환경 변수의 이름은 .로 BUNDLE_VAR_시작해야 합니다. 환경 변수를 설정하려면 운영 체제 설명서를 참조하세요. 예를 들어 명명된 변수에 1234-567890-abcde123 값을 제공하고 이름이 my_cluster_id지정된 my_notebook_path변수에 ./hello.py 값을 제공하려면 , 또는 run다음과 같은 validatedeploy명령을 호출 bundle 하기 전에 다음 명령을 실행합니다.

Linux 및 macOS의 경우:
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
Windows의 경우:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
또는 Linux 및 macOS와 같은 validatedeployrun명령의 일부로 변수 값을 bundle 제공합니다.
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
또는 Windows의 경우:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```
번들 구성 파일 내에서 변수의 값을 제공합니다. 이렇게 하려면 다음 형식에 variablestargets 따라 매핑 내에서 매핑을 사용합니다.
```
variables:
  <variable-name>: <value>
```
예를 들어 명명된 my_cluster_id 변수와 my_notebook_path 두 개의 개별 대상에 대한 값을 제공하려면 다음을 수행합니다.
```
targets:
  dev:
    variables:
      my_cluster_id: 1234-567890-abcde123
      my_notebook_path: ./hello.py
  prod:
    variables:
      my_cluster_id: 2345-678901-bcdef234
      my_notebook_path: ./hello.py
```

앞의 예제에서 Databricks CLI는 변수 my_cluster_idmy_notebook_path 에 대한 값을 찾고 다음 순서대로 일치하는 각 변수에 대한 값을 찾으면 중지하고 해당 변수에 대한 다른 위치를 건너뜁니다.

--var 명령의 일부로 지정된 옵션 내에 있습니다bundle.
로 시작하는 BUNDLE_VAR_모든 환경 변수 집합 내에서 .
모든 variables 매핑 내에서 번들 구성 파일 내의 targets 매핑 중 하나입니다.
번들 구성 파일 내의 최상위 variables 매핑 중 해당 변수 정의에 대한 모든 default 값입니다.

개체의 ID 값 검색

alert, cluster_policy,cluster, dashboard,instance_pool, ,job, metastore, pipeline, , queryservice_principal및 warehouse 개체 형식의 경우 사용자 지정 변수에 대해 다음 형식을 사용하여 명명된 개체의 ID를 검색하도록 정의 lookup 할 수 있습니다.

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

변수에 대한 조회가 정의된 경우 지정된 이름을 가진 개체의 ID가 변수 값으로 사용됩니다. 이렇게 하면 개체의 올바른 확인된 ID가 항상 변수에 사용됩니다.

참고 항목

지정한 이름을 가진 개체가 없거나 지정된 이름을 가진 개체가 두 개 이상 있는 경우 오류가 발생합니다.

예를 들어 다음 구성 ${var.my_cluster_id} 에서는 12.2 공유 클러스터의 ID로 바뀝니다.

variables:
  my_cluster_id:
    description: An existing cluster
    lookup:
      cluster: "12.2 shared"

resources:
  jobs:
    my_job:
      name: "My Job"
      tasks:
        - task_key: TestTask
          existing_cluster_id: ${var.my_cluster_id}

대체

대체를 사용하여 번들 구성 파일을 더 모듈화하고 재사용 가능하게 만들 수 있습니다.

팁

작업 매개 변수 값에 동적 값 참조를 사용하여 작업 실행에 대한 컨텍스트를 작업 태스크에 전달할 수도 있습니다. 작업 실행에 대한 Pass 컨텍스트를 참조 하세요.

예를 들어 명령을 실행할 bundle validate --output json 때 다음과 같은 그래프가 표시될 수 있습니다(줄임표는 생략된 콘텐츠를 간결하게 표시함).

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

앞의 예제에서는 번들 구성 파일의 값을 someone@example.com 대체 ${workspace.current_user.userName}와 함께 참조할 수 있습니다.

마찬가지로 다음과 같은 대체 항목이 있습니다.

/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

다음과 같은 번들 구성 파일에서(줄임표는 간결하게 하기 위해 생략된 콘텐츠를 나타냅니다).

bundle:
  name: hello-bundle

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

# ...

targets:
  dev:
    default: true

명령을 실행할 bundle validate --output json 때 다음 그래프로 확인됩니다(줄임표는 간결하게 하기 위해 생략된 콘텐츠를 나타낸다).

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "profile": "DEFAULT",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "root": "/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev",
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

명명된 리소스에 대한 대체를 만들 수도 있습니다. 예를 들어 이름으로 my_pipeline${resources.pipelines.my_pipeline.target} 구성된 파이프라인의 경우 대상 my_pipeline값이 대체됩니다.

유효한 대체를 확인하려면 REST API 참조 또는 명령의 bundle schema 출력에 설명된 스키마 계층 구조를 사용할 수 있습니다.

다음은 일반적으로 사용되는 몇 가지 대체 항목입니다.

${bundle.name}
${bundle.target} # Use this substitution instead of ${bundle.environment}
${workspace.host}
${workspace.current_user.short_name}
${workspace.current_user.userName}
${workspace.file_path}
${workspace.root_path}
${resources.jobs.<job-name>.id}
${resources.models.<model-name>.name}
${resources.pipelines.<pipeline-name>.name}

다음을 통해 공유

Databricks 자산 번들 구성

개요

예

매핑을

보따리

compute_id

git

databricks_cli_version

변수

작업

권한을

아티팩트

포함하다

리소스

동기화

대상

사용자 지정 변수

변수 값 설정

개체의 ID 값 검색

대체

피드백

피드백

추가 리소스