Конфигурация пакета активов Databricks

Статья
10/31/2024

В этой статье описывается синтаксис файлов конфигурации пакета ресурсов Databricks, определяющих пакеты ресурсов Databricks. См. сведения о пакетах ресурсов Databricks?

Файл конфигурации пакета должен быть выражен в формате YAML и должен содержать как минимум сопоставление пакетов верхнего уровня. Каждый пакет должен содержать как минимум один (и только один) файл конфигурации пакета с именем databricks.yml. При наличии нескольких файлов конфигурации пакета они должны ссылаться databricks.yml на файл с помощью include сопоставления.

Дополнительные сведения о YAML см. в официальной спецификации и руководстве ПО YAML .

Сведения о создании и работе с файлами конфигурации пакета см. в разделе "Разработка пакетов активов Databricks".

Источники данных в Azure Monitor

В этом разделе представлено визуальное представление схемы файла конфигурации пакета. Дополнительные сведения см. в разделе "Сопоставления".

# 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конфигурации локального пакета. Он запускает эту записную книжку в качестве задания с помощью удаленного кластера с указанным идентификатором кластера. URL-адрес удаленной рабочей области и учетные данные проверки подлинности рабочей области считываются из локального профиля DEFAULTконфигурации вызывающего пользователя.

Databricks рекомендует использовать host сопоставление вместо default сопоставления везде, где это возможно, так как это делает файлы конфигурации пакета более переносимыми. host Задание сопоставления указывает интерфейсу командной строки Databricks найти соответствующий профиль в .databrickscfg файле, а затем использовать поля этого профиля для определения типа проверки подлинности Databricks. Если в .databrickscfg файле существует несколько профилей с host соответствующим полем, необходимо указать profile интерфейс командной строки Databricks о том, какой профиль следует использовать. Пример см. в объявлении целевого 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

В следующем примере добавляется целевой объект с именемprod, использующим другой URL-адрес удаленной рабочей области и учетные данные проверки подлинности рабочей области, которые считываются из соответствующей записи файла host вызывающего объекта .databrickscfg с указанным URL-адресом рабочей области. Это задание выполняет ту же записную книжку, но использует другой удаленный кластер с указанным идентификатором кластера. Обратите внимание, что не нужно объявлять notebook_task сопоставление в сопоставлении, так как оно возвращается к использованию notebook_task сопоставления в prod сопоставлении верхнего уровня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

Сопоставления

В следующих разделах описан синтаксис файла конфигурации пакета по сопоставлению верхнего уровня.

связка
variables
рабочая область
разрешения
artifacts
include
resources
sync
Цели

связка

Файл конфигурации пакета должен содержать только одно сопоставление верхнего уровня bundle , которое связывает содержимое пакета и параметры рабочей области Azure Databricks.

Это bundle сопоставление должно содержать name сопоставление, указывающее программное (или логическое) имя пакета. В следующем примере объявляется пакет с программным (или логическим) именем hello-bundle.

bundle:
  name: hello-bundle

Сопоставление bundle также может быть дочерним элементом одного или нескольких целевых объектов в сопоставлении целевых объектов верхнего уровня. Каждое из этих дочерних bundle сопоставлений указывает любые переопределения, отличные от по умолчанию, на целевом уровне. Однако значение сопоставления name верхнего уровня bundle нельзя переопределить на целевом уровне.

cluster_id

Сопоставление bundle может иметь дочернее cluster_id сопоставление. Это сопоставление позволяет указать идентификатор кластера, который будет использоваться в качестве переопределения для кластеров, определенных в другом месте файла конфигурации пакета. Сведения о том, как получить идентификатор кластера, см. в разделе URL-адрес и идентификатор кластера.

cluster_id Переопределение предназначено только для сценариев, предназначенных только для разработки, и поддерживается только для целевого объекта, которому присвоено developmentзначение mode сопоставления. Дополнительные сведения о сопоставлении см. в разделе целевых target объектов.

compute_id

Примечание.

Этот параметр не рекомендуется. Вместо этого используйте cluster_id .

Сопоставление bundle может иметь дочернее compute_id сопоставление. Это сопоставление позволяет указать идентификатор кластера, который будет использоваться в качестве переопределения для кластеров, определенных в другом месте файла конфигурации пакета.

Git

Вы можете получить и переопределить сведения об управлении версиями Git, связанные с вашим пакетом. Это полезно для аннотирования развернутых ресурсов. Например, может потребоваться включить URL-адрес источника репозитория в описание развернутой модели машинного обучения.

При выполнении bundle такой команды, как validatedeploy , илиrunbundle, команда заполняет дерево конфигурации команды следующими параметрами по умолчанию:

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 пусты.

При необходимости можно переопределить origin_url параметры и branch параметры в git сопоставлении сопоставления верхнего уровня bundle , как показано ниже.

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

databricks_cli_version

Сопоставление bundle может содержать databricks_cli_version сопоставление, которое ограничивает версию интерфейса командной строки Databricks, необходимую пакетом. Это может предотвратить проблемы, вызванные использованием сопоставлений, которые не поддерживаются в определенной версии интерфейса командной строки Databricks.

Версия ИНТЕРФЕЙСА командной строки Databricks соответствует семантической версии , а 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:
  <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>

Примечание.

Предполагается, что переменные имеют тип string, если type не задано значение complex. См. раздел "Определение сложной переменной".

Чтобы ссылаться на пользовательскую переменную в конфигурации пакета, используйте подстановку ${var.<variable_name>}.

Дополнительные сведения о пользовательских переменных и подстановках см. в разделе "Замены" и переменных в пакетах ресурсов Databricks.

рабочая область

Файл конфигурации пакета может содержать только одно сопоставление верхнего уровня workspace , чтобы указать любые параметры рабочей области Azure, отличные от по умолчанию.

Внимание

Допустимые пути рабочей области 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 используется путь /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 используется путь ${workspace.root}/artifactsпо умолчанию, который использует подстановки.

Примечание.

Сопоставление artifact_path не поддерживает пути файловой системы Databricks (DBFS).

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 используется путь ${workspace.root}/filesпо умолчанию, который использует подстановки.

state_path

Сопоставление state_path по умолчанию с путем по умолчанию и представляет путь ${workspace.root}/state в рабочей области для хранения сведений о состоянии Terraform о развертываниях.

Другие сопоставления рабочих областей

Сопоставление workspace также может содержать следующие необязательные сопоставления, чтобы указать механизм проверки подлинности Azure Databricks для использования. Если они не указаны в этом workspace сопоставлении, они должны быть указаны в workspace сопоставлении как дочерний объект одного или нескольких целевых объектов в сопоставлении целевых объектов верхнего уровня.

Внимание

Для проверки подлинности Azure Databricks необходимо использовать жесткие значения кода для следующих workspace сопоставлений. Например, нельзя указать пользовательские переменные для значений этих сопоставлений с помощью синтаксиса ${var.*} .

Сопоставление profile (или --profile -p параметры при выполнении пакета проверки, развертывания, запуска и уничтожения команд с помощью интерфейса командной строки Databricks) указывает имя профиля конфигурации, используемого с этой рабочей областью для проверки подлинности Azure Databricks. Этот профиль конфигурации сопоставляется с созданным при настройке интерфейса командной строки Databricks.

Примечание.

Databricks рекомендует использовать host сопоставление (или --profile -p параметры при выполнении пакета проверки, развертывания, запуска и уничтожения команд с помощью интерфейса командной строки Databricks), profile так как это делает файлы конфигурации пакета более переносимыми. host Задание сопоставления указывает интерфейсу командной строки Databricks найти соответствующий профиль в .databrickscfg файле, а затем использовать поля этого профиля для определения типа проверки подлинности Databricks. Если в .databrickscfg файле существует несколько профилей с host соответствующим полем, необходимо использовать profile сопоставление (или --profile -p параметры командной строки), чтобы указать Интерфейс командной строки Databricks о том, какой профиль следует использовать. Пример см. в объявлении целевого prod объекта в примерах.
Сопоставление host указывает URL-адрес рабочей области Azure Databricks. См . URL-адрес рабочей области для каждой рабочей области.
Для проверки подлинности OAuth между компьютерами (M2M) используется сопоставление client_id . Кроме того, можно задать это значение в локальной переменной DATABRICKS_CLIENT_IDсреды. Или можно создать профиль конфигурации со значением, а затем указать имя профиля с client_id profile сопоставлением (или с помощью --profile -p параметров при выполнении пакета проверки, развертывания, запуска и уничтожения команд с помощью интерфейса командной строки Databricks). Ознакомьтесь с проверкой подлинности доступа к Azure Databricks с помощью субъекта-службы с помощью OAuth (OAuth M2M).

Примечание.

Нельзя указать значение секрета OAuth Azure Databricks в файле конфигурации пакета. Вместо этого задайте переменную DATABRICKS_CLIENT_SECRETлокальной среды. Кроме того, можно добавить client_secret значение в профиль конфигурации, а затем указать имя профиля с profile сопоставлением (или с помощью --profile -p параметров при выполнении пакета проверки, развертывания, запуска и уничтожения команд с помощью интерфейса командной строки Databricks).
Для проверки подлинности Azure CLI используется сопоставление azure_workspace_resource_id . Кроме того, можно задать это значение в локальной переменной DATABRICKS_AZURE_RESOURCE_IDсреды. Или можно создать профиль конфигурации со значением, а затем указать имя профиля с azure_workspace_resource_id profile сопоставлением (или с помощью --profile -p параметров при выполнении пакета проверки, развертывания, запуска и уничтожения команд с помощью интерфейса командной строки Databricks). См . проверку подлинности Azure CLI.
Для проверки подлинности секрета клиента Azure с помощью субъектов-служб используются сопоставления azure_workspace_resource_idazure_tenant_idи azure_client_id используются. Кроме того, эти значения можно задать в переменных DATABRICKS_AZURE_RESOURCE_IDARM_TENANT_IDлокальной среды и ARM_CLIENT_IDсоответственно. Или можно создать профиль конфигурации с помощью и azure_client_id azure_tenant_idзначений, а затем указать имя профиля с profile azure_workspace_resource_idсопоставлением (или с помощью --profile -p параметров при проверке, развертывании, запуске и уничтожении команд с помощью интерфейса командной строки Databricks). См. сведения о проверке подлинности субъекта-службы MS Entra.

Примечание.

Нельзя указать значение секрета клиента Azure в файле конфигурации пакета. Вместо этого задайте переменную ARM_CLIENT_SECRETлокальной среды. Кроме того, можно добавить azure_client_secret значение в профиль конфигурации, а затем указать имя профиля с profile сопоставлением (или с помощью --profile -p параметров при выполнении пакета проверки, развертывания, запуска и уничтожения команд с помощью интерфейса командной строки Databricks).
Для проверки подлинности управляемых azure_use_msiazure_client_idудостоверений Azure используются сопоставления и azure_workspace_resource_id используются. Кроме того, эти значения можно задать в переменных ARM_USE_MSIARM_CLIENT_IDлокальной среды и DATABRICKS_AZURE_RESOURCE_IDсоответственно. Или можно создать профиль конфигурации с помощью и azure_workspace_resource_id azure_client_idзначений, а затем указать имя профиля с profile azure_use_msiсопоставлением (или с помощью --profile -p параметров при проверке, развертывании, запуске и уничтожении команд с помощью интерфейса командной строки Databricks). См . проверку подлинности управляемых удостоверений Azure.
Сопоставление azure_environment указывает тип среды Azure (например, Public, UsGov, Китай и Германия) для определенного набора конечных точек API. Значение по умолчанию — PUBLIC. Кроме того, можно задать это значение в локальной переменной ARM_ENVIRONMENTсреды. Кроме того, можно добавить azure_environment значение в профиль конфигурации, а затем указать имя профиля с profile сопоставлением (или с помощью --profile -p параметров при выполнении пакета проверки, развертывания, запуска и уничтожения команд с помощью интерфейса командной строки Databricks).
Сопоставление azure_login_app_id не работает и зарезервировано для внутреннего использования.
Сопоставление auth_type указывает используемый тип проверки подлинности Azure Databricks, особенно в тех случаях, когда интерфейс командной строки Databricks вызывает непредвиденный тип проверки подлинности. Ознакомьтесь с доступом к ресурсам Azure Databricks с проверкой подлинности.

Разрешения

Сопоставление верхнего уровня permissions указывает один или несколько уровней разрешений для применения ко всем ресурсам, определенным в пакете. Если вы хотите применить разрешения к конкретному ресурсу, см. статью "Определение разрешений для определенного ресурса".

Допустимые уровни разрешений верхнего уровня: CAN_VIEWи CAN_MANAGECAN_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 — это необязательный относительный путь от расположения файла конфигурации пакета к расположению файла setup.py колесика Python. Если path он не включен, интерфейс командной строки Databricks попытается найти файл setup.py колесика Python в корневом каталоге пакета.
files — необязательное сопоставление, включающее дочернее source сопоставление, которое можно использовать для указания расположений, отличных от по умолчанию, для включения сложных инструкций по сборке. Расположения указываются как относительные пути из расположения файла конфигурации пакета.
build — это необязательный набор команд сборки, отличных от по умолчанию, которые необходимо выполнить локально перед развертыванием. Для сборок колес Python интерфейс командной строки Databricks предполагает, что он может найти локальную установку пакета Python wheel для выполнения сборок, и она выполняет команду python setup.py bdist_wheel по умолчанию во время каждого развертывания пакета. Чтобы указать несколько команд сборки, разделите каждую команду с символами double-ampersand (&&).

Дополнительные сведения, включая пример пакета, который использует artifacts, см. в разделе "Разработка файла колеса Python с помощью пакетов ресурсов Databricks".

Совет

Вы можете определить, объединить и переопределить параметры артефактов в пакетах с помощью методов, описанных в разделе "Определение параметров артефакта" динамически в пакетах ресурсов Databricks.

включать

Массив include задает список глобов пути, содержащих файлы конфигурации для включения в пакет. Эти глобы пути относятся к расположению файла конфигурации пакета, в котором указаны глобы пути.

Интерфейс командной строки Databricks не включает файлы конфигурации по умолчанию в пакете. Массив необходимо использовать include для указания всех и всех файлов конфигурации для включения в пакет, кроме databricks.yml самого файла.

Этот include массив может отображаться только как сопоставление верхнего уровня.

В следующем примере конфигурации содержится три файла конфигурации. Эти файлы находятся в той же папке, что и файл конфигурации пакета:

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

В следующем примере конфигурации содержатся все файлы с именами файлов, начинающимися bundle и заканчивающимися .yml. Эти файлы находятся в той же папке, что и файл конфигурации пакета:

include:
  - "bundle*.yml"

ресурсы

Сопоставление resources указывает сведения о ресурсах Azure Databricks, используемых пакетом.

Это resources сопоставление может отображаться как сопоставление верхнего уровня или может быть дочерним из одного или нескольких целевых объектов в сопоставлении целевых объектов верхнего уровня и включает ноль или один из поддерживаемых типов ресурсов. Каждое сопоставление типов ресурсов включает в себя одно или несколько отдельных объявлений ресурсов, которые должны иметь уникальное имя. Эти объявления отдельных ресурсов используют полезные данные запроса операции создания соответствующего объекта, выраженные в YAML, для определения ресурса. Поддерживаемые свойства ресурса — это поддерживаемые поля соответствующего объекта.

Полезные данные запроса на создание операций описаны в справочнике по REST API Databricks, а команда databricks bundle schema выводит все поддерживаемые схемы объектов. Кроме того, команда возвращает предупреждения, databricks bundle validate если неизвестные свойства ресурсов находятся в файлах конфигурации пакета.

В следующей таблице перечислены поддерживаемые типы ресурсов для пакетов и ссылок на документацию по соответствующим полезным данным.

Тип ресурса	Сопоставления ресурсов
cluster	Сопоставления кластеров: POST /api/2.1/clusters/create
щиток	Сопоставления панелей мониторинга: POST /api/2.0/preview/sql/dashboards
Эксперимент	Сопоставления экспериментов: POST /api/2.0/mlflow/experiments/create
работа	Сопоставления заданий: POST /api/2.1/jobs/create Дополнительные сведения см. в разделе "Типы задач задания" и переопределение новых параметров кластера заданий.
трубопровод	Сопоставления конвейеров: POST /api/2.0/pipelines
модель	Сопоставления моделей: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoint	Сопоставления конечных точек обслуживания модели: POST /api/2.0/обслуживающие конечные точки
registered_model (каталог Unity)	Сопоставления моделей каталога Unity: POST /api/2.1/unity-catalog/models
schema (каталог Unity)	Сопоставления схем каталога Unity: POST /api/2.1/unity-catalog/schemas

Все пути к папкам и файлам, на которые ссылаются объявления ресурсов, относятся к расположению файла конфигурации пакета, в котором указаны эти пути.

cluster

Ресурс кластера позволяет создавать кластеры всех назначений. В следующем примере создается кластер с именем my_cluster и задается кластер, используемый для запуска записной книжки в my_job:

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"

dashboard

Ресурс панели мониторинга позволяет управлять панелями мониторинга ИИ/BI в пакете. Сведения о панелях мониторинга AI/BI см. в разделе "Панели мониторинга".

Следующий пример включает и развертывает пример панели мониторинга анализа поездки такси Нью-Йорка в рабочую область 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}

Если вы используете пользовательский интерфейс для изменения панели мониторинга, изменения, внесенные с помощью пользовательского интерфейса, не применяются к JSON-файлу панели мониторинга в локальном пакете, если вы явно не обновите его с помощью bundle generate. Вы можете использовать --watch этот параметр для непрерывного опроса и получения изменений на панели мониторинга. См. раздел "Создание файла конфигурации пакета".

Кроме того, при попытке развернуть пакет, содержащий JSON-файл панели мониторинга, отличный от файла JSON в удаленной рабочей области, возникнет ошибка. Чтобы принудительно развернуть и перезаписать панель мониторинга в удаленной рабочей области с локальной, используйте --force этот параметр. См. раздел "Развертывание пакета".

задание

В следующем примере объявляется задание с ключом 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 он указан в пакете, он будет игнорироваться операциями со схемой.
Для ресурса доступны schema только поля, поддерживаемые соответствующим API создания объектов Schemas. Например, не поддерживается, enable_predictive_optimization так как он доступен только в API обновления.

В следующем примере объявляется конвейер с ключом my_pipeline ресурса, который создает схему каталога Unity с ключом my_schema в качестве целевого объекта:

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 позволяет настроить файлы, которые являются частью развертываний пакета.

включить и исключить

В include сопоставлении и exclude сопоставлений sync указывается список файлов или папок для включения или исключения из развертываний пакета в зависимости от следующих правил:

На основе любого списка глобов файлов и путей в файле в .gitignore корневом каталоге пакета сопоставление может содержать список глобов файлов, глобов пути или обоих, относительно корневого include каталога пакета, чтобы явно включить.
На основе любого списка глобов файлов и путей в файле в .gitignore корневом каталоге пакета, а также список глобов файлов и путей в include сопоставлении, exclude сопоставление может содержать список глобов файлов, глобов пути или обоих, относительно корня пакета, чтобы явным образом исключить.

Все пути к указанным файлам и папкам относятся к расположению файла конфигурации пакета, в котором они указаны.

Синтаксис шаблонов include и шаблонов файлов и exclude путей следует стандартному .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 папке с расширением *.whlфайла, кроме именованного delete-me.whlфайла, включаются. Другие файлы в папке my_package/dist также не включены.

Сопоставление sync также можно объявить в targets сопоставлении для определенного целевого объекта. Любое sync сопоставление, объявленное в целевом объекте, объединяется с любыми объявлениями сопоставления верхнего уровня sync . Например, продолжая работу с предыдущим примером, следующее include сопоставление на targets уровне объединяется с include сопоставлением в сопоставлении верхнего уровня sync :

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 указывает один или несколько контекстов, в которых выполняется рабочий процесс 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>

режим и предустановки

Чтобы упростить разработку и рекомендации по CI/CD, наборы активов Databricks предоставляют режимы развертывания для целевых объектов, которые устанавливают поведение по умолчанию для предварительных и рабочих рабочих процессов. Некоторые поведения также можно настроить. Дополнительные сведения см. в режимах развертывания пакета ресурсов Databricks.

Совет

Чтобы задать удостоверения запуска для пакетов, можно указать run_as для каждого целевого объекта, как описано в разделе "Указание удостоверения запуска для рабочего процесса пакетов активов Databricks".

Чтобы указать, что целевой объект рассматривается как целевой объект разработки, добавьте в нее набор developmentсопоставленийmode. Чтобы указать, что целевой объект обрабатывается как целевой объект рабочей среды, добавьте в нее набор productionсопоставленийmode. Например, этот целевой объект рассматривается как рабочий целевой объект 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, расписание будет неоплачено.

Поделиться через

Конфигурация пакета активов Databricks

Источники данных в Azure Monitor

Примеры

Сопоставления

связка

cluster_id

compute_id

Git

databricks_cli_version

Переменные

рабочая область

root_path

artifact_path

file_path

state_path

Другие сопоставления рабочих областей

Разрешения

Артефакты

включать

ресурсы

cluster

dashboard

задание

конвейер

schema

синхронизировать

включить и исключить

paths

Цели

default

режим и предустановки

Обратная связь

Дополнительные ресурсы