Databricks 자산 번들 구성

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

번들 구성 파일은 YAML 형식으로 표현되어야 하며 최소한 최상위 번들 매핑을 포함해야 합니다. 각 번들에는 databricks.yml이라는 번들 구성 파일이 최소 하나(그리고 단 하나) 포함되어야 합니다. 여러 번들 구성 파일이 있는 경우 databricks.yml 매핑을 사용하여 include 파일에서 참조해야 합니다.

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

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

개요

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

# This is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  cluster_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 or complex

# 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:
  dashboards:
    <some-unique-programmatic-identifier-for-this-dashboard>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See REST API create request payload reference for jobs.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the REST API create request payload reference for models.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the REST API create request payload reference for Delta Live Tables (pipelines).
  schemas:
    <some-unique-programmatic-identifier-for-this-schema>:
      # See the Unity Catalog schema 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>"
  paths:
    - "<some-file-or-path-to-synchronize>"

# 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.
    cluster_id: string
    default: true | false
    mode: development
    presets:
      <preset>: <value>
    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.

예제

참고 항목

번들 기능 및 일반적인 번들 사용 사례를 보여 주는 구성 예제는 번들 구성 예제 및 GitHub의 번들 예제 리포지토리를 참조하세요.

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

Databricks는 가능한 경우 host 매핑 대신 default 매핑을 사용하는 것이 좋습니다. 이렇게 하면 번들 구성 파일의 이식성이 더 높습니다. 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라는 대상을 추가합니다. 이는 지정된 작업 영역 URL을 사용하여 호출자의 .databrickscfg 파일에서 일치하는 host 항목에서 읽습니다. 이 작업은 동일한 Notebook을 실행하지만 지정된 클러스터 ID가 있는 다른 원격 클러스터를 사용합니다. notebook_task 매핑 내에서 prod 매핑이 명시적으로 재정의되지 않은 경우 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

매핑

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

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

번들

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

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

bundle:
  name: hello-bundle

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

cluster_id

bundle 매핑에는 자식 cluster_id 매핑이 있을 수 있습니다. 이 매핑을 사용하면 번들 구성 파일의 다른 위치에 정의된 클러스터를 재정의하는 데 사용할 클러스터의 ID를 지정할 수 있습니다. 클러스터의 ID를 검색하는 방법에 대한 자세한 내용은 클러스터 URL 및 ID를 참조하세요.

cluster_id 재정의는 개발 전용 시나리오를 위한 것이며 mode 매핑이 development로 설정된 대상에 대해서만 지원됩니다. target 매핑에 대한 자세한 내용은 대상을 참조하세요.

compute_id

참고 항목

이 설정은 더 이상 사용되지 않습니다. cluster_id를 대신 사용합니다.

bundle 매핑에는 자식 compute_id 매핑이 있을 수 있습니다. 이 매핑을 사용하면 번들 구성 파일의 다른 위치에 정의된 클러스터를 재정의하는 데 사용할 클러스터의 ID를 지정할 수 있습니다.

git

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

bundle, validate 또는 deploy와 같은 run 명령을 실행할 때마다 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 매핑의 branch 매핑 내에서 origin_url 및 git 설정을 재정의할 수 있습니다.

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

번들 설정 파일에는 사용자 지정 변수가 정의된 최상위 variables 매핑이 하나 포함될 수 있습니다. 각 변수에 대해 다음 형식을 사용하여 선택적 설명, 기본값, 사용자 지정 변수가 복합 형식인지 또는 조회를 설정하여 ID 값을 검색합니다.

variables:
  <variable-name>:
    description: <variable-description>
    default: <optional-default-value>
    type: <optional-type-value> # "complex" is the only valid value
    lookup:
      <optional-object-type>: <optional-object-name>

참고 항목

변수는 type이 complex로 설정되지 않는 한 string 형식으로 간주됩니다. 복합 변수 정의를 참조하세요.

번들 구성 내에서 사용자 지정 변수를 참조하려면 ${var.<variable_name>} 대체를 사용합니다.

사용자 지정 변수 및 대체에 대한 자세한 내용은 Databricks 자산 번들의 대체 및 변수를 참조하세요.

작업 영역

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

Important

유효한 Databricks 작업 영역 경로는 둘 중 하나 /Workspace 또는 /Volumes.로 시작합니다. 사용자 지정 작업 영역 경로는 자동으로 접두사로 /Workspace지정되므로 사용자 지정 경로 ${workspace.file_path}에서 작업 영역 경로 대체를 사용하는 경우 경로 앞에 추가할 /Workspace 필요가 없습니다.

root_path

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

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

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

artifact_path

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

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

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

참고 항목

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

file_path

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

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

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

state_path

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

기타 작업 영역 매핑

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

Important

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

• profile 매핑(또는 Databricks CLI에서 번들 validate, deploy, run, 및 destroy 명령을 실행할 때의 --profile 또는 -p 옵션)은 Azure Databricks 인증에 이 작업 영역에서 사용할 구성 프로필의 이름을 지정합니다. 이 구성 프로필은 Databricks CLI를 설정할 때 만든 프로필에 매핑됩니다.

  참고 항목

  Databricks에서는 host 매핑 대신 --profile 매핑(또는 Databricks CLI로 번들 validate, deploy, run 및 destroy 명령을 실행할 때 -p 또는 profile 옵션)을 사용할 것을 권장합니다. 이렇게 하면 번들 구성 파일의 이식성이 향상됩니다. host 매핑을 설정하면 Databricks CLI가 .databrickscfg 파일에서 일치하는 프로필을 찾은 다음 해당 프로필의 필드를 사용하여 사용할 Databricks 인증 유형을 결정하도록 지시합니다. 일치하는 host 필드가 있는 여러 프로필이 .databrickscfg 파일 내에 있는 경우 profile 매핑(또는 --profile 또는 -p 명령줄 옵션)을 사용하여 사용할 프로필에 대해 Databricks CLI에 지시해야 합니다. 예제는 예제의 prod 대상 선언을 참조하세요.

• host 매핑은 Azure Databricks 작업 영역의 URL을 지정합니다. 작업 영역별 URL을 참조하세요.

• OAuth M2M(컴퓨터-컴퓨터) 인증의 경우 매핑 client_id이(가) 사용됩니다. 또는 로컬 환경 변수 DATABRICKS_CLIENT_ID에서 이 값을 설정할 수 있습니다. 또는 client_id 값으로 구성 프로필을 만든 다음 profile 매핑을 사용하여(또는 Databricks CLI에서 번들 validate, deploy, run 및 destroy 명령을 실행할 때 --profile 또는 -p 옵션 사용하여) 프로필 이름을 지정할 수 있습니다. OAuth(OAuth M2M)를 사용하여 서비스 주체로 Azure Databricks에 액세스 인증을 참조하세요.

  참고 항목

  번들 구성 파일에서 Azure Databricks OAuth 비밀 값을 지정할 수 없습니다. 대신 로컬 환경 변수 DATABRICKS_CLIENT_SECRET을(를) 설정합니다. 또는 구성 프로필에 client_secret 값을 추가한 다음 profile 매핑을 사용하여 프로필의 이름을 지정할 수 있습니다(또는 번들을 실행할 때 --profile 또는 -p 옵션을 사용하여 Databricks CLI로 명령 유효성 검사, 배포, 실행 및 삭제).

• Azure CLI 인증에 azure_workspace_resource_id 매핑이 사용됩니다. 또는 로컬 환경 변수 DATABRICKS_AZURE_RESOURCE_ID에서 이 값을 설정할 수 있습니다. 또는 azure_workspace_resource_id 값으로 구성 프로필을 만든 다음 profile 매핑을 사용하여(또는 Databricks CLI에서 번들 validate, deploy, run 및 destroy 명령을 실행할 때 --profile 또는 -p 옵션 사용하여) 프로필 이름을 지정할 수 있습니다. Azure CLI 인증을 참조하세요.

• 서비스 주체를 사용한 Azure 클라이언트 비밀 인증의 경우 azure_workspace_resource_id, azure_tenant_id 및 azure_client_id매핑이 사용됩니다. 또는 로컬 환경 변수 DATABRICKS_AZURE_RESOURCE_ID, ARM_TENANT_ID, ARM_CLIENT_ID에서 각각 이러한 값을 설정할 수 있습니다. 또는 azure_workspace_resource_id, azure_tenant_id 및 azure_client_id 값을 사용하여 구성 프로필을 만든 다음 profile 매핑을 사용하여(또는 Databricks CLI에서 번들 validate, deploy, run 및 destroy 명령을 실행할 때 --profile 또는 -p 옵션을 사용하여) 프로필의 이름을 지정할 수 있습니다. MS Entra 서비스 주체 인증을 참조하세요.

  참고 항목

  번들 구성 파일에서 Azure 클라이언트 비밀 값을 지정할 수 없습니다. 대신 로컬 환경 변수 ARM_CLIENT_SECRET을(를) 설정합니다. 또는 구성 프로필에 azure_client_secret 값을 추가한 다음 profile 매핑을 사용하여 프로필의 이름을 지정할 수 있습니다(또는 번들을 실행할 때 --profile 또는 -p 옵션을 사용하여 Databricks CLI로 명령 유효성 검사, 배포, 실행 및 삭제).

• Azure 관리 ID 인증의 경우 azure_use_msi, azure_client_id 및 azure_workspace_resource_id 매핑이 사용됩니다. 또는 로컬 환경 변수 ARM_USE_MSI, ARM_CLIENT_ID, DATABRICKS_AZURE_RESOURCE_ID에서 각각 이러한 값을 설정할 수 있습니다. 또는 azure_use_msi, azure_client_id 및 azure_workspace_resource_id 값을 사용하여 구성 프로필을 만든 다음 profile 매핑을 사용하여(또는 Databricks CLI에서 번들 validate, deploy, run 및 destroy 명령을 실행할 때 --profile 또는 -p 옵션을 사용하여) 프로필의 이름을 지정할 수 있습니다. Azure 관리 ID 인증을 참조하세요.

• azure_environment 매핑은 특정 API 엔드포인트 집합에 대한 Azure 환경 유형(예: 공용, UsGov, 중국 및 독일)을 지정합니다. 기본값은 PUBLIC입니다. 또는 로컬 환경 변수 ARM_ENVIRONMENT에서 이 값을 설정할 수 있습니다. 또는 구성 프로필에 azure_environment 값을 추가한 다음 profile 매핑을 사용하여 프로필의 이름을 지정할 수 있습니다(또는 번들을 실행할 때 --profile 또는 -p 옵션을 사용하여 Databricks CLI로 명령 유효성 검사, 배포, 실행 및 삭제).

• azure_login_app_id 매핑은 비작동이며 내부용으로 예약되어 있습니다.

• auth_type 매핑은 특히 Databricks CLI가 예기치 않은 인증 유형을 유추하는 경우 사용할 Azure Databricks 인증 유형을 지정합니다. Azure Databricks 리소스에 대한 액세스 인증을 참조하세요.

permissions

최상위 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

최상위 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

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

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

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

다음 예제에는 세 개의 구성 파일이 포함되어 있습니다. 이러한 파일은 번들 구성 파일과 동일한 폴더에 있습니다.

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

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

include:
  - "bundle*.yml"

resources

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

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

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

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

리소스 종류	리소스 매핑
cluster	클러스터 매핑: POST /api/2.1/clusters/create
대시보드	대시보드 매핑: POST /api/2.0/lakeview/dashboards
experiment	실험 매핑: POST /api/2.0/mlflow/experiments/create
작업(job)	작업 매핑: POST /api/2.1/jobs/create 자세한 내용은 작업 작업 유형을 참조하고 새 작업 클러스터 설정을 재정의합니다.
파이프라인	파이프라인 매핑: POST /api/2.0/pipelines
model	모델 매핑: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoint	엔드포인트 매핑을 제공하는 모델: POST /api/2.0/serving-endpoints
registered_model(Unity Catalog)	Unity 카탈로그 모델 매핑: POST /api/2.1/unity-catalog/models
스키마(Unity Catalog)	Unity 카탈로그 스키마 매핑: POST /api/2.1/unity-catalog/schemas

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

cluster

클러스터 리소스를 사용하면 다목적 클러스터를 만들 수 있습니다. 다음 예제에서는 my_cluster이라는 클러스터를 생성하고 my_job에서 Notebook을 실행하는 데 사용할 클러스터로 설정합니다.

bundle:
  name: clusters

resources:
  clusters:
    my_cluster:
      num_workers: 2
      node_type_id: "i3.xlarge"
      autoscale:
        min_workers: 2
        max_workers: 7
      spark_version: "13.3.x-scala2.12"
      spark_conf:
        "spark.executor.memory": "2g"

  jobs:
    my_job:
      tasks:
        - task_key: test_task
          existing_cluster_id: ${resources.clusters.my_cluster.id}
          notebook_task:
            notebook_path: "./src/my_notebook.py"

대시보드

대시보드 리소스를 사용하면 번들에서 AI/BI 대시보드를 관리할 수 있습니다. AI/BI 대시보드에 대한 자세한 내용은 대시보드를 참조 하세요.

다음 예제에서는 샘플 NYC Taxi Trip Analysis 대시보드를 Databricks 작업 영역에 포함하고 배포합니다.

resources:
  dashboards:
    nyc_taxi_trip_analysis:
      display_name: "NYC Taxi Trip Analysis"
      file_path: ../src/nyc_taxi_trip_analysis.lvdash.json
      warehouse_id: ${var.warehouse_id}

UI를 사용하여 대시보드를 수정하는 경우 UI를 통해 수정한 내용은 명시적으로 업데이트 bundle generate하지 않는 한 로컬 번들의 대시보드 JSON 파일에 적용되지 않습니다. 이 옵션을 사용하여 대시보드에 --watch 대한 변경 내용을 지속적으로 폴링하고 검색할 수 있습니다. 번들 구성 파일 생성을 참조하세요.

또한 원격 작업 영역에 있는 것과 다른 대시보드 JSON 파일이 포함된 번들을 배포하려고 하면 오류가 발생합니다. 로컬 작업 영역으로 원격 작업 영역의 대시보드를 강제로 배포하고 덮어쓰려면 이 --force 옵션을 사용합니다. 번들 배포를 참조하세요.

작업(job)

다음 예제에서는 다음과 같은 hello-job 리소스 키를 사용하여 작업을 선언합니다.

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

파이프라인

다음 예제에서는 다음과 같은 hello-pipeline 리소스 키를 사용하여 파이프라인을 선언합니다.

resources:
  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

schema(스키마)

스키마 리소스 유형을 사용하면 번들의 일부로 만든 워크플로 및 파이프라인의 테이블 및 기타 자산에 대한 Unity 카탈로그 스키마를 정의할 수 있습니다. 다른 리소스 종류와 다른 스키마에는 다음과 같은 제한 사항이 있습니다.

• 스키마 리소스의 소유자는 항상 배포 사용자이며 변경할 수 없습니다. 번들에 run_as가 지정된 경우 스키마에 대한 작업에서 무시됩니다.
• 해당 스키마 개체 만들기 API에서 지원하는 필드만 schema 리소스에 사용할 수 있습니다. 예를 들어 enable_predictive_optimization은 업데이트 API에서만 사용할 수 있으므로 지원되지 않습니다.

다음 예제에서는 my_pipeline 리소스 키를 사용하여 my_schema 키를 대상으로 하는 Unity Catalog 스키마를 생성하는 파이프라인을 선언합니다.

resources:
  pipelines:
    my_pipeline:
      name: test-pipeline-{{.unique_id}}
      libraries:
        - notebook:
            path: ./nb.sql
      development: true
      catalog: main
      target: ${resources.schemas.my_schema.id}

  schemas:
    my_schema:
      name: test-schema-{{.unique_id}}
      catalog_name: main
      comment: This schema was created by DABs.

최상위 권한 부여 매핑은 Databricks 자산 번들에서 지원되지 않으므로 스키마에 대한 권한을 설정하려면 schemas 매핑 내에서 스키마에 대한 권한을 정의합니다.

schemas:
    my_schema:
      name: test-schema
      grants:
        - principal: users
          privileges:
            - CAN_MANAGE
        - principal: my_team
          privileges:
            - CAN_READ
      catalog_name: main
      comment: "my schema with grants"

sync

sync 매핑을 사용하면 번들 배포의 일부인 파일을 구성할 수 있습니다.

포함 및 제외

include 매핑 내 exclude 및 sync의 매핑은 다음 규칙에 따라 번들 배포 내에 포함하거나 제외할 파일 또는 폴더 목록을 지정합니다.

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

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

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

예를 들어 다음 .gitignore 파일에 다음 항목이 포함된 경우:

.databricks
my_package/dist

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

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

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

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

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

그러면 my_package/dist이라는 이름의 파일을 제외하고, *.whl 폴더 안에 있는 파일 확장자가 delete-me.whl인 모든 파일이 포함됩니다. my_package/dist 폴더의 다른 파일도 포함되지 않습니다.

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

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

paths

sync 매핑에는 작업 영역에 동기화할 로컬 경로를 지정하는 paths 매핑이 포함될 수 있습니다. paths 매핑을 사용하면 번들 간에 공통 파일을 공유할 수 있으며 번들 루트 외부에 있는 파일을 동기화하는 데 사용할 수 있습니다. (번들 루트는 databricks.yml 파일의 위치입니다.) 이는 여러 번들을 호스트하고 라이브러리, 코드 파일 또는 구성을 공유하려는 단일 리포지토리가 있는 경우에 특히 유용합니다.

지정된 경로는 paths 매핑이 설정된 폴더에 고정된 파일 및 디렉터리를 기준으로 해야 합니다. 하나 이상의 경로 값이 디렉터리를 번들 루트의 상위 항목으로 트래버스하는 경우 루트 경로는 폴더 구조가 그대로 유지되도록 동적으로 결정됩니다. 예를 들어 번들 루트 폴더의 이름이 my_bundle인 경우 databricks.yml의 이 구성은 번들 루트보다 한 수준 위에 있는 common 폴더와 번들 루트 자체를 동기화합니다.

sync:
  paths:
    - ../common
    - .

이 번들을 배포하면 작업 영역에서 다음과 같은 폴더 구조가 생성됩니다.

common/
  common_file.txt
my_bundle/
  databricks.yml
  src/
    ...

targets

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

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

(이 targets 매핑은 선택 사항이지만 강력히 권장됩니다.) 지정된 경우 최상위 매핑으로만 표시될 수 있습니다.

최상위 작업 영역, 아티팩트 및 리소스 매핑의 설정은 targets 매핑에 지정되지 않은 경우에 사용되지만 충돌하는 설정은 대상 내의 설정에 의해 재정의됩니다.

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

default

번들 명령에 대한 대상 기본값을 지정하려면 default 매핑을 true로 설정합니다. 예를 들어 이름이 dev인 이 대상은 기본 대상입니다.

targets:
  dev:
    default: true

기본 대상이 구성되지 않았거나 특정 대상 내에서 작업 또는 파이프라인을 유효성 검사, 배포 및 실행하려면 -t 번들 명령 옵션을 사용합니다.

다음 명령은 my_job 및 dev 대상 내에서 prod을 유효성 검사, 배포 및 실행합니다.

databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev my_job

databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod my_job

다음 예제에서는 두 개의 대상을 선언합니다. 첫 번째 대상은 이름이 dev이며 번들 명령에 대해 대상이 지정되지 않은 경우 사용되는 기본 대상입니다. 두 번째 대상은 이름이 prod이며 이 대상이 번들 명령에 대해 지정된 경우에만 사용됩니다.

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

모드 및 사전 설정

Databricks 자산 번들은 간편한 개발 및 CI/CD 모범 사례를 촉진하기 위해 사전 프로덕션 및 프로덕션 워크플로의 기본 동작을 설정하는 대상에 대한 배포 모드를 제공합니다. 일부 동작도 구성할 수 있습니다. 자세한 내용은 Databricks 자산 번들 배포 모드를 참조 하세요.

팁

번들 실행 ID를 설정하려면 Databricks 자산 번들 워크플로에 대한 실행 ID 지정에 설명된 대로 각 대상에 대해 run_as을 지정할 수 있습니다.

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

targets:
  prod:
    mode: production

presets 매핑을 사용하여 일부 동작을 사용자 지정할 수 있습니다. 사용 가능한 사전 설정 목록은 사용자 지정 사전 설정을 참조하세요. 다음 예제에서는 모든 프로덕션 리소스의 접두사를 지정하고 태그를 지정하는 사용자 지정된 프로덕션 대상을 보여 줍니다.

targets:
  prod:
    mode: production
    presets:
      name_prefix: "production_"  # prefix all resource names with production_
      tags:
        prod: true

mode와 presets 둘 다 설정되면 사전 설정이 기본 모드 동작을 재정의합니다. 개별 리소스의 설정은 사전 설정을 재정의합니다. 예를 들어 일정이 UNPAUSED로 설정되어 있지만 trigger_pause_status 사전 설정이 PAUSED로 설정된 경우 일정이 일시 중지되지 않습니다.