Create a Role

Use the Create a Role API to create a custom role in Pulse.

A role defines the permissions and cluster-level access that can be assigned to users. A role consists of one or more clusters, a set of permissions, and optional user or Active Directory (AD) group mappings.

Before invoking this API, authenticate with the Pulse server. For more information, see Authenticate with Pulse APIs.

Endpoint

Property	Value
Method	POST
Endpoint	/graphql
API Type	GraphQL

Request

Invoke the addRole GraphQL mutation to create a role.

Because the request payload can be large, store it in a JSON file and reference it by using the -d @<file> option.

Run the following command:

curl -X POST 'https://<pulse_url>/graphql' \ -H 'Content-Type: application/json' \ -b cookies.txt \ -H "role: $ROLE" \ -d @create-role.json

Example Request

The following example creates a role named DataEngineer.

{ "query": "mutation AddRole($definition: RoleDef!) { addRole(definition: $definition) { _id name } }", "variables": { "definition": { "name": "DataEngineer", "clusters": [ "prod-cluster" ], "permissions": { "hdfs": true, "hdfs~snapshot": true, "yarn": true, "yarn~services": true, "spark": true, "spark~kpi~view": true, "impala": true, "impala~impala-queries": true, "chargeback-reports": true, "chargeback-reports~hdfs": true }, "serviceQueues": { "prod-cluster": [ "default" ] }, "serviceUsers": { "prod-cluster": [ "hdfs", "hive" ] }, "impalaUsers": { "prod-cluster": [] }, "adGroupsMapped": [ "data-engineers" ], "adUsersMapped": [] } } }

Request Parameters

Field	Required	Description
Field	Required	Description
`name`	Yes	Specifies a unique name for the role.
`clusters`	Yes	Specifies the clusters to which the role applies.
`permissions`	Yes	Specifies the permissions assigned to the role. Each permission key must be set to `true`.
`serviceQueues`	Yes*	Specifies the allowed YARN service queues for each cluster.
`serviceUsers`	Yes*	Specifies the allowed service users for each cluster.
`impalaUsers`	Conditional	Specifies the allowed Impala users for each cluster. Required only when Impala is used.
`adGroupsMapped`	No	Specifies the Active Directory groups mapped to the role.
`adUsersMapped`	No	Specifies the Active Directory users mapped to the role.

Example Response

{ "data": { "addRole": { "_id": "66571d6a5d2d9e0012345678", "name": "DataEngineer" } } }

Validation Rules

When creating a role:

Specify at least one cluster.
Enable at least one permission by setting its value to true.
Ensure that the role name is unique.
Configure serviceQueues and serviceUsers for each cluster.
Configure impalaUsers when assigning Impala permissions.

Configure Role Permissions

The permissions object is a flat map of permission keys.

To grant a permission, set its value to true.

"permissions": { "spark": true, "spark~kpi~view": true, "yarn": true, "yarn~services": true }

For the complete list of supported permission keys, see Role Permission Reference

Last updated on

Was this page helpful?