다음을 통해 공유

Databricks 자산 번들의 대체 및 변수

  • 아티클

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

팁

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

대체

대체를 사용하여 번들 배포 및 실행의 컨텍스트에 따라 변경되는 설정 값을 검색할 수 있습니다.

예를 들어 bundle validate --output json 명령을 실행할 때 다음과 같은 그래프가 표시될 수 있습니다.

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

번들 구성 파일에서 작업 영역 name를 생성하기 위해 번들 target, 번들 userName 및 작업 영역 root_path 필드의 값을 참조하는 데 대체를 사용할 수 있습니다.

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

명명된 리소스에 대한 대체를 만들 수도 있습니다. 예를 들어 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}

사용자 지정 변수

번들에서 간단하고 복잡한 사용자 지정 변수를 모두 정의하여 많은 시나리오에 필요한 값을 동적으로 검색할 수 있습니다. 사용자 지정 변수는 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 값을 제공하지 않는 경우 변수의 값 설정에 설명된 대로 번들 명령을 실행할 때, 환경 변수를 통해 또는 번들 구성 파일 내의 다른 곳에서 변수를 설정해야 합니다.

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

  • 변수 값을 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에 대한 예시로 bundle, validate, deploy 같은 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 CLI는 다음 순서대로 변수 my_cluster_id 및 my_notebook_path에 대한 값을 찾고 일치하는 각 변수에 대한 값을 찾으면 중지하고 해당 변수에 대한 다른 위치를 건너뜁니다.

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

복잡한 변수 정의

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

참고 항목

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

개체 ID 값 검색

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

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}