Set permissions for resources in Declarative Automation Bundles

This article describes how to set permissions for resources in Declarative Automation Bundles. For information about resources supported in bundles, see Declarative Automation Bundles resources.

In Azure Databricks bundle configuration files, you can define permissions at the top level to apply to all resources defined in the bundle, or you can define permissions to apply to specific resources.

Note

You can define permissions for the same user, group, or service principal in both the top-level permissions mapping and in a resource's permissions mapping. For that resource, the resource-level permission takes precedence. See Permissions order of precedence.

Tip

To prevent non-admin users from modifying assets after they are deployed, deploy your bundle to an immutable, read-only folder. See Immutable deployments.

Define permissions to apply to all resources

You can define permissions to apply to all supported resources defined in resources using the top-level permissions mapping. Databricks recommends this approach for managing Declarative Automation Bundles resource permissions.

Permissions define the allowed permissions level for a user_name, group_name, or service_principal_name. Allowed top-level permission levels are CAN_VIEW, CAN_MANAGE, and CAN_RUN. For more information about the top-level permissions mapping, see permissions.

The following example sets top-level permissions for the dev target. The user someone@example.com will have CAN_RUN permissions on my-job:

bundle:
  name: my-bundle

resources:
  jobs:
    my-job:
      # ...

targets:
  dev:
    # ...
    permissions:
      - user_name: someone@example.com
        level: CAN_RUN

Define permissions for a specific resource

You can use the permissions mapping in a dashboard, experiment, job, model, or pipeline definition in resources to define one or more permissions for that resource.

Each permission in the permissions mapping must include the following:

  • Either user_name, group_name, or service_principal_name, set to the name of the user, group, or service principal, respectively.
  • level, set to the name of the permission level. Allowed permission levels for each resource are the following:
    • Alerts: CAN_EDIT, CAN_MANAGE, CAN_READ, CAN_RUN
    • Apps: CAN_MANAGE, CAN_USE
    • Clusters: CAN_ATTACH_TO, CAN_MANAGE, CAN_RESTART
    • Dashboards: CAN_EDIT, CAN_MANAGE, CAN_RUN, CAN_READ*
    • Database instances: CAN_MANAGE, CAN_USE, CAN_CREATE
    • Genie agents: CAN_EDIT, CAN_MANAGE, CAN_RUN, CAN_VIEW
    • Experiments: CAN_EDIT, CAN_MANAGE, CAN_READ, CAN_RUN
    • Jobs: CAN_MANAGE, CAN_MANAGE_RUN, CAN_VIEW, IS_OWNER
    • Models: CAN_EDIT, CAN_MANAGE, CAN_MANAGE_STAGING_VERSIONS, CAN_MANAGE_PRODUCTION_VERSIONS, CAN_READ
    • Pipelines: CAN_MANAGE, CAN_RUN, CAN_VIEW, IS_OWNER
    • Secret scopes: READ, WRITE, MANAGE
    • SQL warehouse: CAN_MANAGE, CAN_USE, CAN_VIEW, CAN_MONITOR, IS_OWNER

* The workspace UI refers to view-only access as CAN VIEW, while the Permissions API uses CAN READ to represent the same level of access.

Important

Allowed permission levels for resources cannot necessarily be applied to resources using the top-level permissions mapping. For valid permission levels for the top-level permissions mapping, see permissions.

The following syntax shows how to declare permissions for a resource type (in this example, pipelines) in the top-level resources mapping and in a resources mapping within a target:

# ...
resources:
  pipelines:
    <some-programmatic-identifier-for-this-pipeline>:
      # ...
      permissions:
        - user_name: <user-name> # Or:
          group_name: <group-name-1> # Or:
          service_principal_name: <service-principal-name>
          level: <permission-level>
      # ...
targets:
  <some-programmatic-identifier-for-this-target>:
    resources:
      pipelines:
        <some-programmatic-identifier-for-this-pipeline>:
          # ...
          permissions:
            - user_name: <user-name> # Or:
              group_name: <group-name> # Or:
              service_principal_name: <service-principal-name>
              level: <permission-level>
          # ...
    # ...

Any permissions that are declared for a resource in the top-level resources mapping are combined with any permissions that are declared for that same resources mapping in an individual target. For example, given the following resources mapping for the same resource at both the top level and in a target:

bundle:
  name: my-bundle

resources:
  jobs:
    my-job:
      # ...
      permissions:
        - group_name: test-group
          level: CAN_VIEW
      # ...

targets:
  dev:
    # ...
    resources:
      jobs:
        my-job:
          # ...
          permissions:
            - user_name: someone@example.com
              level: CAN_MANAGE_RUN
          # ...

When you run databricks bundle validate for this example, the resulting graph is as follows:

{
  "...": "...",
  "resources": {
    "jobs": {
      "my-job": {
        "permissions": [
          {
            "level": "CAN_VIEW",
            "group_name": "test-group"
          },
          {
            "level": "CAN_MANAGE_RUN",
            "user_name": "someone@example.com"
          }
        ],
        "...": "..."
      }
    }
  }
}

Permissions order of precedence

If you define permissions for the same user, group, or service principal in multiple places in your bundle configuration, Declarative Automation Bundles determines the configured permission for each principal on each resource as follows:

  • Resource-level permissions override top-level permissions: If a resource defines a permission for a principal, either in the top-level resources mapping or in a target's resources mapping, the permissions defined for the resource apply to that resource. Declarative Automation Bundles ignores any top-level permissions or target permissions for that principal on that resource, even if they grant a higher level.
  • Permissions at the same level combine to the highest level: If a principal has more than one permission at the same level, the principal gets the highest of those permission levels. This applies to permissions for a resource in the top-level resources mapping and in a target's resources mapping, and to the top-level permissions mapping and a target's permissions mapping. As a result, a target can raise a permission that is set at the same level, but it can't lower it.

These rules combine permission entries for the same user_name, group_name, or service_principal_name. They don't determine a user's effective access, which can also come from the groups the user belongs to. For example, if a job grants CAN_VIEW to a user and the top-level permissions mapping grants CAN_MANAGE to a group that the user belongs to, the job has two permission entries, and the user can manage the job through the group.

In the following configuration, the group test-group has CAN_MANAGE permissions for the job in the dev target, and CAN_MANAGE_RUN permissions for the job in the prod target. The top-level CAN_VIEW permission doesn't apply to the job, because the job defines its own permission for test-group. In the dev target, the job's CAN_MANAGE_RUN and CAN_MANAGE permissions combine to CAN_MANAGE, the higher level. If the dev target sets CAN_VIEW for the job instead, test-group keeps CAN_MANAGE_RUN:

bundle:
  name: my-bundle

permissions:
  - group_name: test-group
    level: CAN_VIEW

resources:
  jobs:
    my-job:
      # ...
      permissions:
        - group_name: test-group
          level: CAN_MANAGE_RUN
      # ...

targets:
  dev:
    # ...
    resources:
      jobs:
        my-job:
          # ...
          permissions:
            - group_name: test-group
              level: CAN_MANAGE
          # ...
  prod:
    # ...
    resources:
      jobs:
        my-job:
          # ...