Manage budget permissions

This article explains how to control who can view and manage budgets in your Azure Databricks account.

Budgets are account-level objects that let you monitor usage across your account, or scope tracking to specific teams, projects, or workspaces. See Create and monitor budgets. Access to a budget is governed by an access control list (ACL): each budget has a set of grant rules that assign roles to principals (users, groups, or service principals).

Account admins and workspace admins can create budgets. When you create a budget, you are automatically granted the Budget Manager role on it.

Budget roles

There are two roles that you can grant on a budget: Budget Manager and Budget Viewer.

Role Grant name Description
Budget Manager roles/budget.manager View the budget; edit its thresholds and alert configurations, including block-usage enforcement and external email alert targets; and manage its permissions by granting or revoking roles for other principals.
Budget Viewer roles/budget.viewer View the budget and its configuration. Cannot edit the budget, edit per-user overrides, or manage permissions.

Note

A budget's filters are set when the budget is created and can't be edited afterward. Revoking a role does not cascade to other grants on the budget.

Default permissions

Default access to a budget depends on your admin role:

  • Account admins have full, super-user access to every budget in the account. They can view, edit, delete, and manage permissions on any budget, regardless of the grants on it. This access cannot be revoked at the individual-budget level.
  • Workspace admins can create budgets scoped to workspaces they administer. They receive the Budget Manager role only on the budgets they create, and do not have access to budgets created by others unless they are explicitly granted a role.
  • The budget creator is automatically granted the Budget Manager role on the budget they create. An account admin or another budget manager can revoke it later.

Note

Permission changes can take 30 seconds or longer to propagate across the system.

Who can do what

Access depends on your role in the account and whether you use the API or the Budgets UI, which is available in the Governance Hub UI and the account console Usage UI.

Note

The Budgets UI is available only to account admins and workspace admins. Users who hold the Budget Manager or Budget Viewer role but are not admins use the Budget API to view and manage their budgets. The Budget API is accessible to account admins, workspace admins, and any user granted the Budget Manager or Budget Viewer role on a budget.

Action Account admin Workspace admin Budget manager (non-admin) Budget viewer (non-admin)
Create budget All budgets (UI and API) Budgets for workspaces they administer (UI and API) — —
View or list budget All budgets (UI and API) Budgets they manage or view (UI and API) Budgets they manage (API) Budgets they view (API)
Edit budget All budgets (UI and API) Budgets they manage (UI and API) Budgets they manage (API) —
Manage permissions All budgets (UI and API) Budgets they manage (UI and API) Budgets they manage (API) —

Note

The list API returns a comprehensive set: every budget you can see across the account, regardless of workspace scope.

Manage budget permissions using the Databricks CLI

A budget's ACL is stored as a rule set: a named ACL attached to the budget. You read and modify a budget's permissions with the account access-control command group in the Databricks CLI, which is account-scoped. For information about installing and authenticating to the Databricks CLI, see Databricks CLI.

You can also manage budget permissions using the Rule Set API.

A budget's rule set is named:

accounts/<ACCOUNT_ID>/budgets/<BUDGET_ID>/ruleSets/default

Read a budget's permissions

The account access-control command group uses an etag field for optimistic concurrency control. To grant or revoke roles, first run get-rule-set to read the current rule set and its etag, apply your changes locally, and then run update-rule-set with that etag.

Run the following command to read the current permissions, passing an empty string for the etag to indicate no freshness requirement:

databricks account access-control get-rule-set \
  "accounts/<ACCOUNT_ID>/budgets/<BUDGET_ID>/ruleSets/default" ""

Replace:

  • <ACCOUNT_ID> with your account ID.
  • <BUDGET_ID> with the budget ID.

Example response:

{
  "etag": "1790271814348000",
  "grant_rules": [
    { "principals": ["users/manager@example.com"], "role": "roles/budget.manager" },
    { "principals": ["users/viewer@example.com"], "role": "roles/budget.viewer" }
  ],
  "name": "accounts/<ACCOUNT_ID>/budgets/<BUDGET_ID>/ruleSets/default"
}

Copy the etag field from the response for the update request.

Grant or revoke permissions

To grant a role, add the principal to the relevant grant_rules entry. To revoke a role, run the update again without that principal. Because the update replaces the entire grant_rules list, include every grant that you want to keep, not only the new one. To clear all permissions, pass an empty grant_rules list.

Create a rule-set.json file with the final state of the rules. Use the etag that you copied from the get-rule-set response:

{
  "name": "accounts/<ACCOUNT_ID>/budgets/<BUDGET_ID>/ruleSets/default",
  "rule_set": {
    "name": "accounts/<ACCOUNT_ID>/budgets/<BUDGET_ID>/ruleSets/default",
    "etag": "1790271814348000",
    "grant_rules": [
      { "role": "roles/budget.manager", "principals": ["users/manager@example.com"] },
      { "role": "roles/budget.viewer", "principals": ["users/viewer@example.com", "groups/cost-team"] }
    ]
  }
}

Then, apply the update:

databricks account access-control update-rule-set --json @rule-set.json

Important

Because this update replaces the entire rule set, all existing roles are overwritten. To keep any existing roles, include them in the grant_rules list. A stale etag is rejected, so always use the etag from your most recent get-rule-set response.

Specify principals using the following formats:

Type Format
User users/<email>
Group groups/<group-name>
Service principal servicePrincipals/<application-id>

Use a budget with your granted permissions

Account admins, workspace admins, and users granted the Budget Manager or Budget Viewer role work with budgets through the Budget API. Your role determines which operations you can perform:

Your role List and get Update and delete Manage permissions
Manager ✔ ✔ ✔
Viewer ✔ ✘ ✘

Additional resources

  • Last updated on