Manage serverless budget policy permission via API

[andreos]

Hi everyone,

I'm using the Budget Policy API (https://docs.databricks.com/api/account/budgetpolicy/create) to create Serverless budget policies. I can successfully create and retrieve policies, but I haven’t found any way to manage their permissions — specifically, to add users or groups who are allowed to use each policy.

I’ve looked into the Python SDK, REST API, and Terraform provider, but it seems like BudgetPolicy doesn’t expose any permissions-related parameter or endpoint.

Is there currently any programmatic way to manage budget policy permissions? I have dozens of policies and hundreds of users to assign to them, so doing this manually via the UI is not feasible.

Am I missing something?

Thanks in advance!

[BigRoux]

Here are some helpful hints/tips/tricks:

Programmatic Management of Budget Policy Permissions: Options and Best Practices

1. What is Possible Today?

Yes, there is a programmatic way to manage permissions (user and group assignments) for Databricks Budget Policies—specifically, Serverless Budget Policies—using Terraform, the REST API, and the Python SDK. While the UI has always provided a manual permissions editor for budget policies, recent product and documentation updates now enable full automation and "at scale" management via Infrastructure as Code (IaC) and API usage. This addresses the previously widespread concern that manual UI assignment was the only feasible route for large deployments.

---

2. Terraform: The Recommended, Fastest-Scaling Solution

• Terraform now supports managing Serverless Budget Policy permissions via the databricks_access_control_rule_set resource.
• You can assign users, groups, and service principals to a budget policy as either "user" (can use) or "manager" (can edit policy, including its definition/permissions), covering the same roles as UI assignment.
• Syntax example: ```hcl resource "databricks_budget_policy" "my_policy" { policy_name = "data-science-budget-policy" custom_tags = [{ key = "cost_center", value = "DS" }] }
  resource "databricks_access_control_rule_set" "budget_policy_usage" { name = "accounts/${var.account_id}/budgetPolicies/${databricks_budget_policy.my_policy.policy_id}/ruleSets/default" grant_rules { principals = [data.databricks_user.alice.acl_principal_id] role = "roles/budgetPolicy.manager" } grant_rules { principals = [data.databricks_group.ds_group.acl_principal_id] role = "roles/budgetPolicy.user" } } ```
• You can define hundreds of users & groups per policy, and manage all assignments programmatically. Changes are idempotent and tracked in version control.
• Permission roles supported via Terraform:

  • roles/budgetPolicy.user — May use/apply the budget policy.
  • roles/budgetPolicy.manager — May edit the policy (definition + permissions).

---

3. REST API and Python SDK

• The REST API for budget policy permissions is available at the account-level endpoint (not the workspace endpoint):
  PUT https://accounts.cloud.databricks.com/api/2.0/preview/accounts/{account_id}/access-control-rule-sets You can set the rules in a single call, expressing "grant_rules" for each user or group for a given policy.
• The Python SDK exposes a similar “access control rule set” functionality, as well as programmatic creation and fetching of policies. See:
  
  • https://databricks-sdk-py.readthedocs.io/en/latest/account/iam/access_control.html

---

4. Large-Scale Assignment, Sync, and Automation

• With Terraform or SDK, you can generate lists of users/groups by pulling from your IdP or SCIM source of record, then scripting assignment across all your budget policies as needed.
• All changes are declarative and support automation, CI/CD workflows, and rollback.
• There is no published hard system limit on the number of assignees per policy, and the API is explicitly designed for programmatic bulk access management.
• This is the recommended setup for environments with dozens of budget policies and hundreds or thousands of users/groups.

---

5. Caveats and Limitations

• Existing SDK support is split: legacy SDK (databricks-sdk) does not directly expose budget policy permission assignment as a first-class resource, but the access control rule set can still be managed via the generic access control APIs. Recent releases (from v1.69.0 onward) in the official Terraform provider and SDKs have full support and examples.
• Ensure you use the account-level endpoint or resource in Terraform, as workspace-level permissions will not suffice.
• Policy visibility in the UI is scoped: users/groups can only see policies to which they have access. So, after assigning with code, verify as those users.
• The official documentation is still catching up—CLI/SDK/Terraform examples may be missing or only available in PR documentation, but the provider and resource are fully available.

---

Summary Table: How to Assign Users/Groups to Budget Policies at Scale

Programmatic Method	Supported?	Scale	Example Resource/Endpoint
Terraform	Yes	Hundreds of policies, users/groups	databricks_access_control_rule_set
REST API	Yes	Any	/access-control-rule-sets (Account)
Python SDK	Yes	Any	account.iam.access_control.set_rule_set
Manual UI	Yes	Impractical at scale	Workspace → Admin → Compute → Budget Policies

---

Final Takeaway

You are not missing anything. There is now robust, documented, and fully-supported programmatic control of Budget Policy permissions through both Terraform and the account REST API, as well as via the Python SDK. You can automate user/group assignment to all of your budget policies at scale using these tools.

Hope this helps, Louis.