Configuration reference

This page provides reference for keys supported by Declarative Automation Bundles (formerly known as Databricks Asset Bundles) configuration (YAML). See What are Declarative Automation Bundles?.

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

artifacts

Type: Map

Specifies the artifacts to automatically build during bundle deployments that can be used later in bundle runs. Each key is the name of the artifact, and the value is a Map that defines the artifact build settings.

tip

You can define, combine, and override the settings for artifacts in bundles as described in Override with target settings.

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. For Python wheel builds, the Databricks CLI assumes that it can find a local install of the Python wheel package to run builds, and it runs the command python setup.py bdist_wheel by default during each bundle deployment. Specify multiple build commands on separate lines.
dynamic_version	Boolean	Whether to patch the wheel version dynamically based on the timestamp of the whl file. If this is set to true, new code can be deployed without having to update the version in setup.py or pyproject.toml. This setting is only valid when type is set to whl. Added in Databricks CLI version 0.245.0
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.
git	Map	For a tgz artifact, snapshot this git ref instead of the working tree. Mutually exclusive with build. See artifacts.name.git. Added in Databricks CLI version 1.15.0
include	Sequence	For a tgz artifact, subpaths of path to pack, relative to it; empty packs the whole path. .gitignore is honored; the bundle-wide sync include/exclude do not apply. Archive entries are named relative to path. Mutually exclusive with build. Added in Databricks CLI version 1.15.0
path	String	The local path of the directory for the artifact. Paths are relative to the location of the bundle configuration file. For Python wheel builds, it is the path to the Python wheel file's setup.py file. If path is not included, the Databricks CLI attempts to find the Python wheel file's setup.py file in the bundle's root.
type	String	The type of the artifact. Valid values are whl, jar, and tgz. Required if the artifact is a Python wheel. This setting does not need to be specified to build other artifacts.

Key	Type	Description
build	String	An optional set of build commands to run locally before deployment. For Python wheel builds, the Databricks CLI assumes that it can find a local install of the Python wheel package to run builds, and it runs the command python setup.py bdist_wheel by default during each bundle deployment. Specify multiple build commands on separate lines.
dynamic_version	Boolean	Whether to patch the wheel version dynamically based on the timestamp of the whl file. If this is set to true, new code can be deployed without having to update the version in setup.py or pyproject.toml. This setting is only valid when type is set to whl. Added in Databricks CLI version 0.245.0
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.
git	Map	For a tgz artifact, snapshot this git ref instead of the working tree. Mutually exclusive with build. See artifacts.name.git. Added in Databricks CLI version 1.15.0
include	Sequence	For a tgz artifact, subpaths of path to pack, relative to it; empty packs the whole path. .gitignore is honored; the bundle-wide sync include/exclude do not apply. Archive entries are named relative to path. Mutually exclusive with build. Added in Databricks CLI version 1.15.0
path	String	The local path of the directory for the artifact. Paths are relative to the location of the bundle configuration file. For Python wheel builds, it is the path to the Python wheel file's setup.py file. If path is not included, the Databricks CLI attempts to find the Python wheel file's setup.py file in the bundle's root.
type	String	The type of the artifact. Valid values are whl, jar, and tgz. Required if the artifact is a Python wheel. This setting does not need to be specified to build other artifacts.

Examples

The following configuration builds a Python wheel using Poetry:

YAML

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

The following configuration runs tests and builds a wheel. For a complete bundle tutorial that uses artifacts to build a wheel, see Build a Python wheel file using Declarative Automation Bundles.

YAML

artifacts:
  default:
    type: whl
    build: |-
      # run tests
      python -m pytest tests/ -v

      # build the actual artifact
      python setup.py bdist_wheel

    path: .

For an example configuration that builds a JAR and uploads it to Unity Catalog, see Bundle that uploads a JAR file to Unity Catalog.

artifacts.name.files

Type: Sequence

The relative or absolute path to the built artifact files. Use source to specify the built artifacts. Paths are relative to the location of the bundle configuration file.

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

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

artifacts.name.git

Type: Map

For a tgz artifact, snapshot this git ref instead of the working tree. Mutually exclusive with build.

Added in Databricks CLI version 1.15.0

Key	Type	Description
branch	String	The git branch to snapshot. Added in Databricks CLI version 1.15.0
commit	String	The git commit to snapshot. Takes precedence over branch when both are set. Added in Databricks CLI version 1.15.0

Key	Type	Description
branch	String	The git branch to snapshot. Added in Databricks CLI version 1.15.0
commit	String	The git commit to snapshot. Takes precedence over branch when both are set. Added in Databricks CLI version 1.15.0

bundle

Type: Map

The bundle attributes when deploying to this target.

A bundle configuration file must contain only one top-level bundle mapping.

This bundle mapping must contain a name mapping that specifies a programmatic (or logical) name for the bundle. The following example declares a bundle with the programmatic (or logical) name hello-bundle.

YAML

bundle:
  name: hello-bundle

A bundle mapping can also be a child of one or more of the targets in the top-level targets mapping. Each of these child bundle mappings specify any non-default overrides at the target level.

Key	Type	Description
cluster_id	String	The ID of a cluster to use to run the bundle. This key enables you to specify the ID of a cluster to use as an override for clusters defined elsewhere in the bundle configuration file. For information about how to retrieve the ID of a cluster, see Compute resource URL and ID. The cluster_id override is intended for development-only scenarios and is only supported for the target that has its mode mapping set to development. For more information about the target mapping, see targets.
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 bundle.databricks_cli_version.
deployment	Map	The definition of the bundle deployment. For supported attributes see Declarative Automation Bundles deployment modes. See bundle.deployment.
engine	String	The deployment engine to use. Valid values are terraform and direct. The default value is direct. This configuration takes priority over the DATABRICKS_BUNDLE_ENGINE environment variable. For information about the direct deployment engine, see Migrate to the direct deployment engine. Added in Databricks CLI version 0.295.0
git	Map	The Git version control details that are associated with your bundle. For supported attributes see 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). Added in Databricks CLI version 0.236.0

Key	Type	Description
cluster_id	String	The ID of a cluster to use to run the bundle. This key enables you to specify the ID of a cluster to use as an override for clusters defined elsewhere in the bundle configuration file. For information about how to retrieve the ID of a cluster, see Compute resource URL and ID. The cluster_id override is intended for development-only scenarios and is only supported for the target that has its mode mapping set to development. For more information about the target mapping, see targets.
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 bundle.databricks_cli_version.
deployment	Map	The definition of the bundle deployment. For supported attributes see Declarative Automation Bundles deployment modes. See bundle.deployment.
engine	String	The deployment engine to use. Valid values are terraform and direct. The default value is direct. This configuration takes priority over the DATABRICKS_BUNDLE_ENGINE environment variable. For information about the direct deployment engine, see Migrate to the direct deployment engine. Added in Databricks CLI version 0.295.0
git	Map	The Git version control details that are associated with your bundle. For supported attributes see 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). Added in Databricks CLI version 0.236.0

bundle.databricks_cli_version

The bundle mapping can contain a databricks_cli_version mapping that constrains the Databricks CLI version required by the bundle. This can prevent issues caused by using mappings that are not supported in a certain version of the Databricks CLI.

The Databricks CLI version conforms to semantic versioning and the databricks_cli_version mapping supports specifying version constraints. If the current databricks --version value is not within the bounds specified in the bundle's databricks_cli_version mapping, an error occurs when databricks bundle validate is executed on the bundle. The following examples demonstrate some common version constraint syntax:

YAML

bundle:
  name: hello-bundle
  databricks_cli_version: '0.218.0' # require Databricks CLI 0.218.0

YAML

bundle:
  name: hello-bundle
  databricks_cli_version: '0.218.*' # allow all patch versions of Databricks CLI 0.218

YAML

bundle:
  name: my-bundle
  databricks_cli_version: '>= 0.218.0' # allow any version of Databricks CLI 0.218.0 or higher

YAML

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

bundle.deployment

Type: Map

The definition of the bundle deployment

Key	Type	Description
deployment_id	String	The ID the deployment metadata service assigned to this bundle's deployment. Output only. Added in Databricks CLI version 1.16.0
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.
latest_version_id	Integer	The most recent version the deployment metadata service recorded for this deployment. Output only. Added in Databricks CLI version 1.16.0
lock	Map	The deployment lock attributes. See bundle.deployment.lock.

Key	Type	Description
deployment_id	String	The ID the deployment metadata service assigned to this bundle's deployment. Output only. Added in Databricks CLI version 1.16.0
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.
latest_version_id	Integer	The most recent version the deployment metadata service recorded for this deployment. Output only. Added in Databricks CLI version 1.16.0
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.

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

experimental

Type: Map

Defines attributes for experimental features.

Key	Type	Description
deployment_history	Boolean	Whether to record deployment history using the deployment metadata service (DMS), which tracks what changed across deployments. Added in Databricks CLI version 1.16.0
immutable_folder	Boolean	Whether to deploy the bundle to a hidden, read-only folder so that deployed assets can't be modified by non-admin users and running jobs aren't affected by in-progress deployments. See immutable_folder. Added in Databricks CLI version 1.6.0
python	Map	Deprecated. Use the top-level python mapping instead. Added in Databricks CLI version 0.238.0
python_wheel_wrapper	Boolean	Whether to use a Python wheel wrapper.
scripts	Map	The commands to run.
skip_artifact_cleanup	Boolean	Determines whether to skip deleting the .internal folder within workspace.artifact_path. By default, this folder is deleted before uploading new build artifacts (such as Python wheels) during deployment. Set to true to preserve existing artifacts across deployments. Added in Databricks CLI version 0.254.0
skip_name_prefix_for_schema	Boolean	Whether to skip adding the prefix (set in presets.name_prefix or computed when mode: development) to the names of Unity Catalog schemas defined in the bundle. Added in Databricks CLI version 0.255.0
use_legacy_run_as	Boolean	Whether to use the legacy run_as behavior.

Key	Type	Description
deployment_history	Boolean	Whether to record deployment history using the deployment metadata service (DMS), which tracks what changed across deployments. Added in Databricks CLI version 1.16.0
immutable_folder	Boolean	Whether to deploy the bundle to a hidden, read-only folder so that deployed assets can't be modified by non-admin users and running jobs aren't affected by in-progress deployments. See immutable_folder. Added in Databricks CLI version 1.6.0
python	Map	Deprecated. Use the top-level python mapping instead. Added in Databricks CLI version 0.238.0
python_wheel_wrapper	Boolean	Whether to use a Python wheel wrapper.
scripts	Map	The commands to run.
skip_artifact_cleanup	Boolean	Determines whether to skip deleting the .internal folder within workspace.artifact_path. By default, this folder is deleted before uploading new build artifacts (such as Python wheels) during deployment. Set to true to preserve existing artifacts across deployments.