Databricks 자산 번들의 대체 및 변수

Databricks 자산 번들은 대체 및 사용자 지정 변수를 지원하므로 번들 구성 파일을 더 모듈화하고 재사용할 수 있습니다. 대체 변수와 사용자 지정 변수를 모두 사용하면 번들이 배포되고 실행될 때 설정을 확인할 수 있도록 값을 동적으로 검색할 수 있습니다.

팁

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

대체 항목

대체를 사용하여 번들 배포 및 실행의 컨텍스트에 따라 변경 될 수 있는 설정의 값을 검색할 수 있습니다. 예를 들어 번들 name, 번들 target, 및 작업 공간 userName 필드의 값을 참조하여 번들 구성 파일에서 작업 공간 root_path을 생성하는 데 대체를 사용할 수 있습니다.

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

이 번들을 someone@example.com이(가) 배포한다면, 루트 경로 /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev에 배포될 것입니다.

명명된 리소스에 대한 대체를 만들 수도 있습니다. 예를 들어 다음 파이프라인 정의의 경우 파이프라인 대상의 값에 사용할 ${resources.pipelines.my_pipeline.target} 수 있습니다.

resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      schema: pipeline_bundle_${bundle.target}
      libraries:
        - notebook:
            path: ../src/my_pipeline.ipynb

      configuration:
        bundle.sourcePath: ${workspace.file_path}/src

유효한 대체를 확인하려면 번들 구성 참조, 리소스 구성 참조 또는 REST API 참조에 설명된 해당 개체의 스키마 계층 구조 또는 명령의 출력을 bundle schema 사용합니다.

팁

리소스에 사용할 수 있는 대체의 전체 목록은 Databricks CLI GitHub 리포지토리 out.fields.txt 참조하세요.

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

${bundle.name}
${bundle.target} # Use this substitution instead of ${bundle.environment}
${workspace.host}
${workspace.current_user.domain_friendly_name}
${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}

사용자 지정 변수

번들에서 간단하고 복잡한 사용자 지정 변수를 모두 정의하여 많은 시나리오에 필요한 값을 동적으로 검색할 수 있습니다. 사용자 지정 변수는 variables 매핑 내의 번들 구성 파일 또는 variable-overrides.json 파일에 선언됩니다. variables 매핑에 대한 자세한 내용은 변수를 참조하세요.

다음 예시 구성은 변수 my_cluster_id 및 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 않는 경우 번들 명령을 실행할 때, 환경 변수를 통해, 번들 구성 파일 내의 다른 곳 또는 번들 프로젝트의 파일에서 .databricks/bundle/<target>/variable-overrides.json 변수를 설정해야 합니다. 변수 값 설정을 참조하세요.

변수 참조

번들 구성 내에서 사용자 지정 변수를 참조하려면 변수 대체${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 하려는 경우, 변수의 새 임시 값을 다음 방법 중 하나를 사용하여 제공하십시오.

참고

번들 변수는 배포 시간 변수입니다. 번들을 배포할 때 해석됩니다. 예를 들어 작업을 실행할 때는 이전에 배포된 작업과 해당 배포에 대해 구성된 변수를 실행하므로 작업 실행에 대해 다른 값을 변수에 전달하는 것은 적용되지 않습니다. 대신 작업 매개 변수를 사용하여 작업 실행에 값을 전달합니다. Pass 작업 매개 변수를 참조하세요.

변수의 값을 bundle 명령의 일부로 제공하십시오. 예: validate, deploy, 또는 run. 이렇게 하려면 변수의 이름과 --var="<key>=<value>" 변수의 값인 옵션을 <key><value> 사용합니다. 예를 들어 bundle validate 명령의 일부로서 1234-567890-abcde123로 명명된 변수에 my_cluster_id 값을 제공하고 ./hello.py로 명명된 변수에 my_notebook_path 값을 제공하려면 다음을 실행합니다.
```
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 값을 제공하고 ./hello.py로 명명된 변수에 my_notebook_path 값을 제공하려면, bundle, validate, deploy 같은 run 명령을 호출하기 전에 다음 명령을 실행합니다.

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와 같은 bundlevalidatedeploy명령의 일부로 변수 값을 run 제공합니다.
```
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"
```
변수의 값을 제공하려면 다음 형식에 따라 번들 구성 파일 내에서 variables 매핑 안에 targets 매핑을 사용하십시오.
```
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/bundle/<target>/variable-overrides.json 변수의 값을 제공합니다.
```
{
  "<variable-name>": "<variable-value>"
}
```
예를 들어 개발 대상에 대한 my_cluster_id 및 my_notebook_path 변수에 대한 값을 제공하려면 파일 .databricks/bundle/dev/variable-overrides.json 만들고 해당 내용을 다음으로 설정합니다.
```
{
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}
```
variable-overrides.json 파일에서 복잡한 변수를 정의할 수도 있습니다.

참고

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

우선 순위

Databricks CLI는 변수를 위한 값을 찾을 때까지 다음 순서대로 값을 검색합니다.

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

복잡한 변수 정의

사용자 지정 변수는 복합 변수로 정의하지 않는 한 문자열 형식으로 간주됩니다. 번들 구성에서 번들에 대한 복합 형식으로 사용자 지정 변수를 정의하려면 typecomplex설정합니다.

참고

type 설정에 유효한 값은 complex입니다. 또한 type가 complex로 설정되어 있으며 변수에 대해 정의된 default가 단일 값인 경우 번들 유효성 검사가 실패합니다.

다음 예제에서 클러스터 설정은 my_cluster로 명명된 사용자 지정 복합 변수 내에 정의됩니다.

variables:
  my_cluster:
    description: 'My cluster definition'
    type: complex
    default:
      spark_version: '13.2.x-scala2.11'
      node_type_id: 'Standard_DS3_v2'
      num_workers: 2
      spark_conf:
        spark.speculation: true
        spark.databricks.delta.retentionDurationCheck.enabled: false

resources:
  jobs:
    my_job:
      job_clusters:
        - job_cluster_key: my_cluster_key
          new_cluster: ${var.my_cluster}
      tasks:
        - task_key: hello_task
          job_cluster_key: my_cluster_key

다음 예제와 같이 .databricks/bundle/<target>/variable-overrides.json 파일에서 복잡한 변수를 정의할 수도 있습니다.

{
  "my_cluster": {
    "spark_version": "13.2.x-scala2.11",
    "node_type_id": "Standard_DS3_v2",
    "num_workers": 2
  }
}

개체의 ID 값 검색

alert, cluster_policy,cluster, dashboard,instance_pool, ,job, metastore, , notification_destination, pipelinequeryservice_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}

출력 대체 및 변수 값

당신의 대체 및 변수가 Databricks 자산 번들에 의해 올바르게 지정되고 구문 분석되도록 하려면 databricks bundle validate을 실행하십시오. databricks 번들 유효성 검사를 참조하세요. 번들을 배포할 때 사용할 값을 보려면 다음 --output json 옵션을 사용합니다.

databricks bundle validate --output json

예를 들어, 작업 태스크에서 정의되고 사용되는 변수 my_cluster_id가 있는 번들의 경우:

bundle:
  name: variables_bundle

variables:
  my_cluster_id:
    default: 1234-567890-abcde123

resources:
  jobs:
    variables_bundle_job:
      name: variables_bundle_job
      tasks:
        - task_key: notebook_task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ../src/notebook.ipynb

스키마 출력은 databricks bundle validate 다음과 같습니다.

{
  "bundle": {
    "..."
    "name": "variables_bundle",
    "target": "dev",
  "..."
  },
  "resources": {
    "jobs": {
      "variables_bundle_job": {
        "deployment": {
          "kind": "BUNDLE",
          "metadata_file_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/state/metadata.json"
        },
        "max_concurrent_runs": 4,
        "name": "[dev someone] variables_bundle_job",
        "tasks": [
          {
            "existing_cluster_id": "1234-567890-abcde123",
            "notebook_task": {
              "notebook_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/files/variables_bundle/src/notebook"
            },
            "task_key": "notebook_task"
          },
        ],
      "..."
      }
    }
  },
  "..."
  "variables": {
    "my_cluster_id": {
      "default": "1234-567890-abcde123",
      "value": "1234-567890-abcde123"
    }
  },
"..."
}

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-12-04