A cluster policy limits the ability to create clusters based on a set of rules.
The policy rules limit the attributes or attribute values available for cluster creation.
Cluster policies have ACLs that limit their use to specific users and groups.
Only admin users can create, edit, and delete policies. Admin users also have access to all policies.
To access Databricks REST APIs, you must authenticate.
Cluster Policies API
The Cluster Policies API allows you to create, list, and edit cluster policies.
Creation and editing is available to admins only. Listing can be performed by any user and
is limited to policies accessible by that user.
Important
The Cluster Policies API requires a policy JSON definition to be passed within a JSON request in stringified form. In most cases this requires escaping of the quote characters.
The policy ID about which to retrieve information.
Response structure
Field Name
Type
Description
policy_id
STRING
Canonical unique identifier for the cluster policy.
name
STRING
Cluster policy name. This must be unique. Length must be between 1 and 100 characters.
definition
STRING
Policy definition JSON document expressed in Databricks Policy Definition Language. The JSON document must be passed as a string and cannot be simply embedded in the requests.
created_at_timestamp
INT64
Creation time. The timestamp (in millisecond) when this cluster policy was created.
List
Endpoint
HTTP Method
2.0/policies/clusters/list
GET
Return a list of policies accessible by the requesting user.
Create a new policy with a given name and definition.
Request structure
Field Name
Type
Description
name
STRING
Cluster policy name. This must be unique. Length must be between 1 and 100 characters.
definition
STRING
Policy definition JSON document expressed in Databricks Policy Definition Language. You must pass the JSON document as a string; it cannot be simply embedded in the requests.
Canonical unique identifier for the cluster policy.
Example
{
"policy_id": "ABCD000000000000",
}
Edit
Endpoint
HTTP Method
2.0/policies/clusters/edit
POST
Update an existing policy. This may make some clusters governed by this policy invalid.
For such clusters the next cluster edit must provide a confirming configuration, but
otherwise they can continue to run.
Request structure
Field Name
Type
Description
policy_id
STRING
The ID of the policy to update. This field is required.
name
STRING
Cluster policy name. This must be unique. Length must be between 1 and 100 characters.
definition
STRING
Policy definition JSON document expressed in Databricks Policy Definition Language. You must pass the JSON document as a string; it cannot be simply embedded in the requests.
Canonical unique identifier for the cluster policy.
name
STRING
Cluster policy name. This must be unique. Length must be between 1 and 100 characters.
definition
STRING
Policy definition JSON document expressed in Databricks Policy Definition Language. You must pass the JSON document as a string; it cannot be simply embedded in the requests.
creator_user_name
STRING
Creator user name. The field won’t be included in the response if the user has already been deleted.
created_at_timestamp
INT64
Creation time. The timestamp (in millisecond) when this cluster policy was created.
PolicySortColumn
The sort order for the ListPolices request.
Name
Description
POLICY_CREATION_TIME
Sort result list by policy creation type.
POLICY_NAME
Sort result list by policy name.
Cluster Policy Permissions API
The Cluster Policy Permissions API enables you to set permissions on a cluster policy. When you grant CAN_USE permission on a policy to a user, the user will be able to create new clusters based on it. A user does not need the cluster_create permission to create new clusters.
Only admin users can set permissions on cluster policies.
In the following endpoints, <basepath> = /api/2.0/preview.
Same as a GET call on <clusterPolicyId>, returns back modified permissions for cluster.
Set or delete permissions
A PUT request replaces all direct permissions on the cluster policy
object. You can make delete requests by making a GET request to retrieve
the current list of permissions followed by a PUT request removing
entries to be deleted.
List of all permissions set on this ACL object for a specific principal. Includes both permissions directly set on this ACL object and permissions inherited from an ancestor ACL object.
Permission
Attribute Name
Type
Description
permission_level
STRING
The name of the permission level.
inherited
BOOLEAN
True when the ACL permission is not set directly but inherited from an ancestor ACL object. False if set directly on the ACL object.
inherited_from_object
List[STRING]
The list of parent ACL object IDs that contribute to inherited permission on an ACL object. This is defined only if inherited is true.
AccessControlInput
An item representing an ACL rule applied to the principal (user or group).
Attribute Name
Type
Description
user_name OR group_name
STRING
Name of the principal (user or group) that has permissions set on the ACL object.
permission_level
STRING
The name of the permission level.
PermissionLevel
Permission level that you can set on a cluster policy.
Permission Level
Description
CAN_USE
Allow user to create clusters based on the policy. The user does not need the cluster create permission.