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.

artifact

Defines the settings to build an artifact.

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`	Map	The source files for the artifact, defined as an artifact_file.
`path`	String	The location where the built artifact will be saved.
`type`	String	Required. The type of the artifact. Valid values are `whl`.

artifacts

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.

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

Example

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

artifact_file

Defines an artifact file in a bundle.

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

`bundle`

The attributes of the bundle. See bundle.

Key	Type	Description
`cluster_id`	String	The ID of a cluster to use to run the bundle. See cluster_id.
`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 deployment and Databricks Asset Bundle deployment modes.
`git`	Map	The Git version control details that are associated with your bundle. For supported attributes, see git and git.
`name`	String	Required. The name of the bundle.

deployment

Defines bundle deployment attributes.

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 lock.

experimental

Defines attributes for experimental features.

Key	Type	Description
`python_wheel_wrapper`	Boolean	Whether to use a Python wheel wrapper.
`scripts`	Command (String)	The commands to run
`use_legacy_run_as`	Boolean	Whether to use the legacy run_as behavior.

git

Defines the Git version control details that are associated with the bundle. See git.

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

grant

Defines access to Unity Catalog objects. For more information, see Connect to cloud object storage using Unity Catalog.

Key	Type	Description
`principal`	String	Required. The name of the principal that will be granted privileges.
`privileges`	String	Required. The privileges to grant to the specified entity.

Example

The following example defines a Unity Catalog schema with grants:

resources:
  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"

lock

Defines the bundle deployment lock attributes.

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

permission

Defines 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	Required. 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`.

permissions

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.

Example

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

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

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.

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

Key	Type	Description
`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

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

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.

target

Defines deployment targets for the bundle. See targets

Key	Type	Description
`artifacts`	Map	The artifacts to include in the target deployment. See artifacts.
`bundle`	Map	The bundle attributes when deploying to this target.
`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 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 permissions.
`presets`	Map	The deployment presets for the target. See presets.
`resources`	Map	The resource definitions for the target. See resources.
`run_as`	Map	The identity to use to run the bundle. See run_as and Specify a run identity for a Databricks Asset Bundles workflow.
`sync`	Map	The local paths to sync to the target workspace when a bundle is run or deployed. See sync.
`variables`	Map	The custom variable definitions for the target. See variables and Substitutions and variables in Databricks Asset Bundles.
`workspace`	Map	The Databricks workspace for the target. workspace

variables

A Map that defines the custom variables for the bundle, where each key is the name of the variable, and the value is a Map that defines the variable. See Substitutions and variables in Databricks Asset Bundles.

Key	Type	Description
variable-name	Map	The definition of a variable. See variable-name.

variable-name

Each variable definition has the following attributes:

Key	Type	Description
`description`	String	The description of the variable.
`lookup`	String	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.
`type`	String	The type of the variable. Valid values are `complex`.

workspace

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.