Instance Profiles API 2.0

The Instance Profiles API allows admins to add, list, and remove instance profiles that users can launch clusters with. Regular users can list the instance profiles available to them. See Secure access to S3 buckets using instance profiles for more information.

Important

To access Databricks REST APIs, you must authenticate.

Add

Endpoint	HTTP Method
`2.0/instance-profiles/add`	`POST`

Register an instance profile. In the UI, you can select the instance profile when launching clusters.

This API is only available to admin users.

Example

curl --netrc -X POST \
https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/instance-profiles/add \
--data '{ "instance_profile_arn": "arn:aws:iam::123456789012:instance-profile/my-profile" }'

{}

Request structure

Field Name	Type	Description
instance_profile_arn	`STRING`	The AWS ARN of the instance profile to register with Databricks. It should look like: `arn:aws:iam::<account-id>:instance-profile/<name>`. This field is required.
iam_role_arn	`STRING`	The AWS IAM role ARN of the role associated with the instance profile. It must have the form `arn:aws:iam::<account-id>:role/<name>`. This field is required if your role name and instance profile name do not match and you want to use the instance profile with Databricks SQL Serverless. Otherwise, this field is optional.
is_meta_instance_profile	`BOOL`	Whether the instance profile is a meta instance profile. Used only in IAM credential passthrough. This field is optional.
skip_validation	`BOOL`	By default, Databricks validates that it has sufficient permissions to launch instances with the instance profile. This validation uses AWS dry-run mode for the `RunInstances` API. If validation fails with an error message that does not indicate an IAM related permission issue, (e.g. “Your requested instance type is not supported in your requested availability zone”), you can pass this flag to skip the validation and forcibly add the instance profile.

Edit

Endpoint	HTTP Method
`2.0/instance-profiles/edit`	`POST`

Edit an instance profile, but the only supported field to change is the optional IAM role ARN associated with the instance profile. It is required to specify the IAM role ARN if both of the following are true:

Your role name and instance profile name do not match. The name is the part after the last slash in each ARN.
You want to use the instance profile with Databricks SQL Serverless.

To understand where these fields are in the AWS console, see Enable Serverless SQL warehouses.

This API is only available to admin users.

Example

curl --netrc -X POST \
https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/instance-profiles/edit \
--data '{ "instance_profile_arn": "arn:aws:iam::123456789012:instance-profile/my-profile",
    "iam_role_arn": "arn:aws:iam::123456789012:role/my-profile2" }'

{}

Request structure

Field Name	Type	Description
instance_profile_arn	`STRING`	The AWS ARN of the instance profile to register with <Databricks>. It should look like: `arn:aws:iam::<account-id>:instance-profile/<name>`. This field is required. This field identifies which registered instance profile to modify.
iam_role_arn	`STRING`	The AWS IAM role ARN of the role associated with the instance profile. It must have the form `arn:aws:iam::<account-id>:role/<name>`. This field is required.

List

Endpoint	HTTP Method
`2.0/instance-profiles/list`	`GET`

List the instance profiles that the calling user can use to launch a cluster.

This API is available to all users.

Example

curl --netrc -X GET \
https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/instance-profiles/list \
| jq .

{
  "instance_profiles": [
    {
      "instance_profile_arn": "arn:aws:iam::123456789012:instance-profile/my-profile",
      "is_meta_instance_profile": false
    }
  ]
}

Response structure

Field Name	Type	Description
instance_profiles	An array of InstanceProfile	A list of instance profiles that the user can access.

Remove

Endpoint	HTTP Method
`2.0/instance-profiles/remove`	`POST`

Remove the instance profile with the provided ARN. Existing clusters with this instance profile will continue to function.

This API is only accessible to admin users.

Example

curl --netrc -X POST \
https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/instance-profiles/remove \
--data '{ "instance_profile_arn": "arn:aws:iam::123456789012:instance-profile/my-profile" }'

{}

Request structure

Field Name	Type	Description
instance_profile_arn	`STRING`	The ARN of the instance profile to remove. This field is required.

Data structures

In this section:

InstanceProfile

InstanceProfile

An IAM instance profile that can be attached to instances when launching a cluster.

Field Name	Type	Description
instance_profile_arn	`STRING`	The AWS ARN of the instance profile to register with Databricks. It should look like: `arn:aws:iam::<account-id>:instance-profile/<name>`. This field is required.
is_meta_instance_profile	`BOOL`	Whether the instance profile is a meta instance profile. Used only in IAM credential passthrough. For more information, see Set up a meta instance profile.