Configuration reference

This article provides reference for keys supported by Databricks Asset Bundles configuration (YAML). See What are Databricks Asset Bundles?.

For complete bundle examples, see Bundle configuration examples and the bundle-examples GitHub repository.

artifacts

Type: Map

Defines the attributes to build artifacts, where each key is the name of the artifact, and the value is a Map that defines the artifact build settings. For information about the artifacts mapping, see artifacts.

Artifact settings defined in the top level of the bundle configuration can be overridden in the targets mapping. See Define artifact settings in Databricks Asset Bundles.

YAML

artifacts:
  <artifact-name>:
    <artifact-field-name>: <artifact-field-value>

Key	Type	Description
build	String	An optional set of build commands to run locally before deployment.
executable	String	The executable type. Valid values are bash, sh, and cmd.
files	Sequence	The relative or absolute path to the built artifact files. See artifacts.name.files.
path	String	The local path of the directory for the artifact.
type	String	Required if the artifact is a Python wheel. The type of the artifact. Valid values are whl and jar.

Example

YAML

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

artifacts.name.files

Type: Sequence

The source files for the artifact.

Key	Type	Description
source	String	Required. The artifact source file.

bundle

Type: Map

The bundle attributes when deploying to this target.

Key	Type	Description
cluster_id	String	The ID of a cluster to use to run the bundle. See cluster_id.
compute_id	String	Deprecated. The ID of the compute to use to run the bundle.
databricks_cli_version	String	The Databricks CLI version to use for the bundle. See databricks_cli_version.
deployment	Map	The definition of the bundle deployment. For supported attributes see Databricks Asset Bundle deployment modes. See bundle.deployment.
git	Map	The Git version control details that are associated with your bundle. For supported attributes see git. See bundle.git.
name	String	The name of the bundle.
uuid	String	Reserved. A Universally Unique Identifier (UUID) for the bundle that uniquely identifies the bundle in internal Databricks systems. This is generated when a bundle project is initialized using a Databricks template (using the databricks bundle init command).

bundle.deployment

Type: Map

The definition of the bundle deployment

Key	Type	Description
fail_on_active_runs	Boolean	Whether to fail on active runs. If this is set to true a deployment that is running can be interrupted.
lock	Map	The deployment lock attributes. See bundle.deployment.lock.

bundle.deployment.lock

Type: Map

The deployment lock attributes.

Key	Type	Description
enabled	Boolean	Whether this lock is enabled.
force	Boolean	Whether to force this lock if it is enabled.

bundle.git

Type: Map

The Git version control details that are associated with your bundle.

Key	Type	Description
branch	String	The Git branch name. See git.
origin_url	String	The origin URL of the repository. See git.

experimental

Type: Map

Defines attributes for experimental features.

Key	Type	Description
pydabs	Map	The PyDABs configuration. See experimental.pydabs.
python	Map	Configures loading of Python code defined with ‘databricks-bundles’ package. See experimental.python.
python_wheel_wrapper	Boolean	Whether to use a Python wheel wrapper.
scripts	Map	The commands to run.
use_legacy_run_as	Boolean	Whether to use the legacy run_as behavior.

experimental.pydabs

Type: Map

The PyDABs configuration.

Key	Type	Description
enabled	Boolean	Whether or not PyDABs (Private Preview) is enabled.
import	Sequence	The PyDABs project to import to discover resources, resource generator and mutators.
venv_path	String	The Python virtual environment path.

experimental.python

Type: Map

Configures loading of Python code defined with ‘databricks-bundles’ package.

Key	Type	Description
mutators	Sequence	Mutators contains a list of fully qualified function paths to mutator functions, such as [my_project.mutators:add_default_cluster].
resources	Sequence	Resources contains a list of fully qualified function paths to load resources defined in Python code, such as ["my_project.resources:load_resources"]
venv_path	String	VEnvPath is path to the virtual environment. If enabled, Python code will execute within this environment. If disabled, it defaults to using the Python interpreter available in the current shell.

include

Type: Sequence

Specifies a list of path globs that contain configuration files to include within the bundle. See include.

permissions

Type: Sequence

A Sequence that defines the permissions to apply to experiments, jobs, pipelines, and models defined in the bundle, where each item in the sequence is a permission for a specific entity.

See permissions and Set permissions for resources in Databricks Asset Bundles.

Key	Type	Description
group_name	String	The name of the group that has the permission set in level.
level	String	The allowed permission for user, group, service principal defined for this permission.
service_principal_name	String	The name of the service principal that has the permission set in level.
user_name	String	The name of the user that has the permission set in level.

Example

YAML

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

presets

Type: Map

Defines bundle deployment presets. See Custom presets.

Key	Type	Description
jobs_max_concurrent_runs	Integer	The maximum concurrent runs for a job.
name_prefix	String	The prefix for job runs of the bundle.
pipelines_development	Boolean	Whether pipeline deployments should be locked in development mode.
source_linked_deployment	Boolean	Whether to link the deployment to the bundle source.
tags	Map	The tags for the bundle deployment.
trigger_pause_status	String	A pause status to apply to all job triggers and schedules. Valid values are PAUSED or UNPAUSED.

resources

Type: Map

A Map that defines the resources for the bundle, where each key is the name of the resource, and the value is a Map that defines the resource. For more information about Databricks Asset Bundles supported resources, and resource definition reference, see Databricks Asset Bundles resources.

YAML

resources:
  <resource-type>:
    <resource-name>:
      <resource-field-name>: <resource-field-value>

Key	Type	Description
apps	Map	The Databricks app definitions for the bundle, where each key is the name of the app. See app.
clusters	Map	The cluster definitions for the bundle, where each key is the name of a cluster. See cluster.
dashboards	Map	The dashboard definitions for the bundle, where each key is the name of the dashboard. See dashboard.
experiments	Map	The experiment definitions for the bundle, where each key is the name of the experiment. See experiment.
jobs	Map	The job definitions for the bundle, where each key is the name of the job. See job.
model_serving_endpoints	Map	The model serving endpoint definitions for the bundle, where each key is the name of the model serving endpoint. See model_serving_endpoint.
models	Map	The model definitions for the bundle, where each key is the name of the model. See model (legacy).
pipelines	Map	The pipeline definitions for the bundle, where each key is the name of the pipeline. See pipeline.
quality_monitors	Map	The quality monitor definitions for the bundle, where each key is the name of the quality monitor. See quality_monitor (Unity Catalog).
registered_models	Map	The registered model definitions for the bundle, where each key is the name of the Unity Catalog registered model. See registered_model (Unity Catalog).
schemas	Map	The schema definitions for the bundle, where each key is the name of the schema. See schema (Unity Catalog).
volumes	Map	The volume definitions for the bundle, where each key is the name of the volume. See volume (Unity Catalog).

run_as

Type: Map

The identity to use when running Databricks Asset Bundles workflows. See Specify a run identity for a Databricks Asset Bundles workflow.

Key	Type	Description
service_principal_name	String	The application ID of an active service principal. Setting this field requires the servicePrincipal/user role.
user_name	String	The email of an active workspace user. Non-admin users can only set this field to their own email.

sync

Type: Map

The files and file paths to include or exclude in the bundle. See sync.

Key	Type	Description
exclude	Sequence	A list of files or folders to exclude from the bundle.
include	Sequence	A list of files or folders to include in the bundle.
paths	Sequence	The local folder paths, which can be outside the bundle root, to synchronize to the workspace when the bundle is deployed.

targets

Type: Map

Defines deployment targets for the bundle. See targets

YAML

targets:
  <target-name>:
    <target-field-name>: <target-field-value>

Key	Type	Description
artifacts	Map	The artifacts to include in the target deployment. See targets.name.artifacts.
bundle	Map	The bundle attributes when deploying to this target. See targets.name.bundle.
cluster_id	String	The ID of the cluster to use for this target.
compute_id	String	Deprecated. The ID of the compute to use for this target.
default	Boolean	Whether this target is the default target.
git	Map	The Git version control settings for the target. See targets.name.git.
mode	String	The deployment mode for the target. Valid values are development or production. See Databricks Asset Bundle deployment modes.
permissions	Sequence	The permissions for deploying and running the bundle in the target. See targets.name.permissions.
presets	Map	The deployment presets for the target. See targets.name.presets.
resources	Map	The resource definitions for the target. See targets.name.resources.
run_as	Map	The identity to use to run the bundle, see Specify a run identity for a Databricks Asset Bundles workflow. See targets.name.run_as.
sync	Map	The local paths to sync to the target workspace when a bundle is run or deployed. See targets.name.sync.
variables	Map	The custom variable definitions for the target. See targets.name.variables.
workspace	Map	The Databricks workspace for the target. See targets.name.workspace.

targets.name.artifacts

Type: Map

The artifacts to include in the target deployment.

YAML

artifacts:
  <artifact-name>:
    <artifact-field-name>: <artifact-field-value>

Key	Type	Description
build	String	An optional set of non-default build commands to run locally before deployment.
executable	String	The executable type. Valid values are bash, sh, and cmd.
files	Sequence	The source files for the artifact. See targets.name.artifacts.name.files.
path	String	The location where the built artifact will be saved.
type	String	Required. The type of the artifact. Valid values are whl.

targets.name.artifacts.name.files

Type: Sequence

The source files for the artifact.

Key	Type	Description
source	String	Required. The path of the files used to build the artifact.

targets.name.bundle

Type: Map

The bundle attributes when deploying to this target.

Key	Type	Description
cluster_id	String	The ID of a cluster to use to run the bundle. See cluster_id.
compute_id	String	Deprecated. The ID of the compute to use to run the bundle.
databricks_cli_version	String	The Databricks CLI version to use for the bundle. See databricks_cli_version.
deployment	Map	The definition of the bundle deployment. For supported attributes see Databricks Asset Bundle deployment modes. See targets.name.bundle.deployment.
git	Map	The Git version control details that are associated with your bundle. For supported attributes see git. See targets.name.bundle.git.
name	String	The name of the bundle.
uuid	String	Reserved. A Universally Unique Identifier (UUID) for the bundle that uniquely identifies the bundle in internal Databricks systems. This is generated when a bundle project is initialized using a Databricks template (using the databricks bundle init command).

targets.name.bundle.deployment

Type: Map

The definition of the bundle deployment

Key	Type	Description
fail_on_active_runs	Boolean	Whether to fail on active runs. If this is set to true a deployment that is running can be interrupted.
lock	Map	The deployment lock attributes. See targets.name.bundle.deployment.lock.

targets.name.bundle.deployment.lock

Type: Map

The deployment lock attributes.

Key	Type	Description
enabled	Boolean	Whether this lock is enabled.
force	Boolean	Whether to force this lock if it is enabled.

targets.name.bundle.git

Type: Map

The Git version control details that are associated with your bundle.

Key	Type	Description
branch	String	The Git branch name. See git.
origin_url	String	The origin URL of the repository. See git.

targets.name.git

Type: Map

The Git version control settings for the target.

Key	Type	Description
branch	String	The Git branch name. See git.
origin_url	String	The origin URL of the repository. See git.

targets.name.permissions

Type: Sequence

The permissions for deploying and running the bundle in the target.

Key	Type	Description
group_name	String	The name of the group that has the permission set in level.
level	String	The allowed permission for user, group, service principal defined for this permission.
service_principal_name	String	The name of the service principal that has the permission set in level.
user_name	String	The name of the user that has the permission set in level.

targets.name.presets

Type: Map

The deployment presets for the target.

Key	Type	Description
jobs_max_concurrent_runs	Integer	The maximum concurrent runs for a job.
name_prefix	String	The prefix for job runs of the bundle.
pipelines_development	Boolean	Whether pipeline deployments should be locked in development mode.
source_linked_deployment	Boolean	Whether to link the deployment to the bundle source.
tags	Map	The tags for the bundle deployment.
trigger_pause_status	String	A pause status to apply to all job triggers and schedules. Valid values are PAUSED or UNPAUSED.

targets.name.resources

Type: Map

The resource definitions for the target.

Key	Type	Description
apps	Map	The Databricks app definitions for the bundle, where each key is the name of the app. See app.
clusters	Map	The cluster definitions for the bundle, where each key is the name of a cluster. See cluster.
dashboards	Map	The dashboard definitions for the bundle, where each key is the name of the dashboard. See dashboard.
experiments	Map	The experiment definitions for the bundle, where each key is the name of the experiment. See experiment.
jobs	Map	The job definitions for the bundle, where each key is the name of the job. See job.
model_serving_endpoints	Map	The model serving endpoint definitions for the bundle, where each key is the name of the model serving endpoint. See model_serving_endpoint.
models	Map	The model definitions for the bundle, where each key is the name of the model. See model (legacy).
pipelines	Map	The pipeline definitions for the bundle, where each key is the name of the pipeline. See pipeline.
quality_monitors	Map	The quality monitor definitions for the bundle, where each key is the name of the quality monitor. See quality_monitor (Unity Catalog).
registered_models	Map	The registered model definitions for the bundle, where each key is the name of the Unity Catalog registered model. See registered_model (Unity Catalog).
schemas	Map	The schema definitions for the bundle, where each key is the name of the schema. See schema (Unity Catalog).
volumes	Map	The volume definitions for the bundle, where each key is the name of the volume. See volume (Unity Catalog).

targets.name.run_as

Type: Map

The identity to use to run the bundle.

Key	Type	Description
service_principal_name	String	The application ID of an active service principal. Setting this field requires the servicePrincipal/user role.
user_name	String	The email of an active workspace user. Non-admin users can only set this field to their own email.

targets.name.sync

Type: Map

The local paths to sync to the target workspace when a bundle is run or deployed.

Key	Type	Description
exclude	Sequence	A list of files or folders to exclude from the bundle.
include	Sequence	A list of files or folders to include in the bundle.
paths	Sequence	The local folder paths, which can be outside the bundle root, to synchronize to the workspace when the bundle is deployed.

targets.name.variables

Type: Map

The custom variable definitions for the target.

YAML

variables:
  <variable-name>:
    <variable-field-name>: <variable-field-value>

Key	Type	Description
default	Any	The default value for the variable. If this is not specified,
description	String	The description of the variable.
lookup	Map	The name of the alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, pipeline, query, service_principal, or warehouse object for which to retrieve an ID. See targets.name.variables.name.lookup.
type	String	The type of the variable.

targets.name.variables.name.lookup

Type: Map

The name of the alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, pipeline, query, service_principal, or warehouse object for which to retrieve an ID.

Key	Type	Description
alert	String	The name of the alert for which to retrieve an ID.
cluster	String	The name of the cluster for which to retrieve an ID.
cluster_policy	String	The name of the cluster_policy for which to retrieve an ID.
dashboard	String	The name of the dashboard for which to retrieve an ID.
instance_pool	String	The name of the instance_pool for which to retrieve an ID.
job	String	The name of the job for which to retrieve an ID.
metastore	String	The name of the metastore for which to retrieve an ID.
notification_destination	String	The name of the notification_destination for which to retrieve an ID.
pipeline	String	The name of the pipeline for which to retrieve an ID.
query	String	The name of the query for which to retrieve an ID.
service_principal	String	The name of the service_principal for which to retrieve an ID.
warehouse	String	The name of the warehouse for which to retrieve an ID.

targets.name.workspace

Type: Map

The Databricks workspace for the target.

Key	Type	Description
artifact_path	String	The artifact path to use within the workspace for both deployments and workflow runs
auth_type	String	The authentication type.
azure_client_id	String	The Azure client ID
azure_environment	String	The Azure environment
azure_login_app_id	String	The Azure login app ID
azure_tenant_id	String	The Azure tenant ID
azure_use_msi	Boolean	Whether to use MSI for Azure
azure_workspace_resource_id	String	The Azure workspace resource ID
client_id	String	The client ID for the workspace
file_path	String	The file path to use within the workspace for both deployments and workflow runs
google_service_account	String	The Google service account name
host	String	The Databricks workspace host URL
profile	String	The Databricks workspace profile name
resource_path	String	The workspace resource path
root_path	String	The Databricks workspace root path
state_path	String	The workspace state path

variables

Type: Map

Defines a custom variable for the bundle. See variables.

YAML

variables:
  <variable-name>:
    <variable-field-name>: <variable-field-value>

Key	Type	Description
default	Any	The default value for the variable.
description	String	The description of the variable
lookup	Map	The name of the alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, pipeline, query, service_principal, or warehouse object for which to retrieve an ID. See variables.name.lookup.
type	String	The type of the variable.

variables.name.lookup

Type: Map

The name of the alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, pipeline, query, service_principal, or warehouse object for which to retrieve an ID.

Key	Type	Description
alert	String	The name of the alert for which to retrieve an ID.
cluster	String	The name of the cluster for which to retrieve an ID.
cluster_policy	String	The name of the cluster_policy for which to retrieve an ID.
dashboard	String	The name of the dashboard for which to retrieve an ID.
instance_pool	String	The name of the instance_pool for which to retrieve an ID.
job	String	The name of the job for which to retrieve an ID.
metastore	String	The name of the metastore for which to retrieve an ID.
notification_destination	String	The name of the notification_desination for which to retrieve an ID.
pipeline	String	The name of the pipeline for which to retrieve an ID.
query	String	The name of the query for which to retrieve an ID.
service_principal	String	The name of the service_principal for which to retrieve an ID.
warehouse	String	The name of the warehouse for which to retrieve an ID.

workspace

Type: Map

Defines the Databricks workspace for the bundle. See workspace.

Key	Type	Description
artifact_path	String	The artifact path to use within the workspace for both deployments and workflow runs
auth_type	String	The authentication type.
azure_client_id	String	The Azure client ID
azure_environment	String	The Azure environment
azure_login_app_id	String	The Azure login app ID
azure_tenant_id	String	The Azure tenant ID
azure_use_msi	Boolean	Whether to use MSI for Azure
azure_workspace_resource_id	String	The Azure workspace resource ID
client_id	String	The client ID for the workspace
file_path	String	The file path to use within the workspace for both deployments and workflow runs
google_service_account	String	The Google service account name
host	String	The Databricks workspace host URL
profile	String	The Databricks workspace profile name
resource_path	String	The workspace resource path
root_path	String	The Databricks workspace root path
state_path	String	The workspace state path