Connect to Ranger via REST API
Overview
Ranger provides a web interface — Ranger Admin UI, but another way to manage Ranger is via its REST API. This article provides a few examples of how to carry out HDFS policy-related tasks using the API. To get a full list of endpoints and available methods, see the Ranger REST API documentation.
A simple way to create a query is to use curl and it’s going to be demonstrated below, but you can construct requests in any convenient way and send them from any host within the cluster.
A template request looks like this:
$ curl -i -u <login>:<password> -H "Content-Type: application/json" -d '<json>' -X <request_type> <ranger_host>/service/<endpoint>
where:
-
<login>
— admin username. -
<password>
— password for<login>
. -
<json>
— JSON string to be sent with the request. Omit if the request type isDELETE
. -
<request_type>
— type of the HTTP request (GET
,POST
,PUT
,DELETE
). If the request type isDELETE
, remove the-H
parameter from the command. -
<ranger_host>
— Ranger host URL (e.g. http://stikhomirov-adps2.ru-central1.internal:6080). -
<endpoint>
— resource to which the request will be sent.
The -i
option allows to see the HTTP headers and check the status of the request, feel free to remove it if deemed unnecessary.
Create a policy
To create a resource-based policy, you need to construct one in JSON. An example of a policy for an HDFS service is presented below:
{
"isEnabled": true,
"service": "adh-2_hdfs_id_13", (1)
"name": "test_policy", (2)
"description": "Test policy for HDFS service",
"isAuditEnabled": true,
"resources":{
"path":{
"values":["/resource"], (3)
"isExcludes":false,
"isRecursive":true
}
},
"policyItems": [{
"accesses": [
{
"type":"read", (4)
"isAllowed":true
},
{
"type":"write",
"isAllowed":true
}],
"users": ["test_user"], (5)
"groups": [],
"conditions": [],
"delegateAdmin": false
}],
"denyPolicyItems": [],
"allowExceptions": [],
"denyExceptions": [],
"dataMaskPolicyItems": [],
"rowFilterPolicyItems": []
}
1 | Name of the resource-based service for which the policy is created. |
2 | Name of the policy. |
3 | Resource for which the policy is created. Cannot create multiple policies for one resource. |
4 | Access permissions. |
5 | Users to which the access permissions apply. |
IMPORTANT
Make sure to turn JSON into a string. To do that, you can use a service like JSON Minifier.
|
The corresponding curl command is:
$ curl -i -u <login>:<password> -H "Content-Type: application/json" -d '<json>' -X POST <ranger_host>/service/public/v2/api/policy
The expected output should contain the 200 OK
status and the newly created policy in JSON format:
HTTP/1.1 200 OK Set-Cookie: RANGERADMINSESSIONID=4ED38E17D1A30D9950BCC859F890BB2F; Path=/; HttpOnly Cache-Control: no-cache, no-store, max-age=0, must-revalidate X-Frame-Options: DENY X-XSS-Protection: 1; mode=block Strict-Transport-Security: max-age=31536000; includeSubDomains Content-Security-Policy: default-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline';font-src 'self' X-Content-Type-Options: nosniff Content-Type: application/json Transfer-Encoding: chunked Date: Thu, 28 Dec 2023 13:38:23 GMT Server: Apache Ranger {"id":43,"guid":"2c2f8cf1-4ef5-449e-b9f3-978f73d1adbf","isEnabled":true,"createdBy":"Admin","updatedBy":"Admin","createTime":1703770703338,"updateTime":1703770703338,"version":1,"service":"adh-2_hdfs_id_13","name":"test_policy","policyType":0,"policyPriority":0,"description":"Test policy for HDFS service","resourceSignature":"391f2d50f6f473f28077e9fe73af7b47d918e0905025176820a2e8b540257a72","isAuditEnabled":true,"resources":{"path":{"values":["/resource"],"isExcludes":false,"isRecursive":true}},"policyItems":[{"accesses":[{"type":"read","isAllowed":true},{"type":"write","isAllowed":true}],"users":["test_user"],"groups":[],"roles":[],"conditions":[],"delegateAdmin":false}],"denyPolicyItems":[],"allowExceptions":[],"denyExceptions":[],"dataMaskPolicyItems":[],"rowFilterPolicyItems":[],"serviceType":"hdfs","options":{},"validitySchedules":[],"policyLabels":[],"zoneName":"","isDenyAllElse":false}
You can check that the policy was created in Ranger Admin UI.
Update a policy
You may need to update a policy to add a user to the list of users with the same permissions to some resource. To do that, you need to use the PUT
request and the following curl command:
$ curl -i -u <login>:<password> -H "Content-Type: application/json" -d '<json>' -X PUT <ranger_host>/service/public/v2/api/policy/<id>
where:
-
<json>
is the updated policy. -
<id>
is the ID of the policy you want to update.
The expected output should contain the 200 OK
status and the updated policy in JSON:
HTTP/1.1 200 OK Set-Cookie: RANGERADMINSESSIONID=85F63B544BD11D123B4E81E32492B59E; Path=/; HttpOnly Cache-Control: no-cache, no-store, max-age=0, must-revalidate X-Frame-Options: DENY X-XSS-Protection: 1; mode=block Strict-Transport-Security: max-age=31536000; includeSubDomains Content-Security-Policy: default-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline';font-src 'self' X-Content-Type-Options: nosniff Content-Type: application/json Transfer-Encoding: chunked Date: Thu, 28 Dec 2023 15:15:21 GMT Server: Apache Ranger {"id":43,"guid":"2c2f8cf1-4ef5-449e-b9f3-978f73d1adbf","isEnabled":true,"createdBy":"Admin","updatedBy":"Admin","createTime":1703770703000,"updateTime":1703776521670,"version":2,"service":"adh-2_hdfs_id_13","name":"test_policy","policyType":0,"policyPriority":0,"description":"Test policy for HDFS service","resourceSignature":"391f2d50f6f473f28077e9fe73af7b47d918e0905025176820a2e8b540257a72","isAuditEnabled":true,"resources":{"path":{"values":["/resource"],"isExcludes":false,"isRecursive":true}},"policyItems":[{"accesses":[{"type":"read","isAllowed":true},{"type":"write","isAllowed":true}],"users":["test_user","new_test_user"],"groups":[],"roles":[],"conditions":[],"delegateAdmin":false}],"denyPolicyItems":[],"allowExceptions":[],"denyExceptions":[],"dataMaskPolicyItems":[],"rowFilterPolicyItems":[],"serviceType":"hdfs","options":{},"validitySchedules":[],"policyLabels":[],"zoneName":"","isDenyAllElse":false}
In the Ranger Admin UI, you can see that a new user has appeared.
Get a policy
You can get a Ranger policy if you know its ID or you can search for it by its parameters.
The corresponding command if you know the ID:
$ curl -i -u <login>:<password> -X GET <ranger_host>/service/public/v2/api/policy/<id>
where <id>
is the ID of a policy in Ranger.
The corresponding command if you want to search for it (e.g. by name):
$ curl -i -u <login>:<password> -X GET <ranger_host>/service/public/v2/api/policy?policyName=<policy_name>
where <policy_name>
is the name of a policy in Ranger.
NOTE
If you search by a parameter that is not unique you may get multiple policies as a result.
|
In both cases, the expected output should contain the 200 OK
status and a policy in JSON format:
HTTP/1.1 200 OK Set-Cookie: RANGERADMINSESSIONID=BCC2C0CA55B3330BED1ACC0700E18817; Path=/; HttpOnly Cache-Control: no-cache, no-store, max-age=0, must-revalidate X-Frame-Options: DENY X-XSS-Protection: 1; mode=block Strict-Transport-Security: max-age=31536000; includeSubDomains Content-Security-Policy: default-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline';font-src 'self' X-Content-Type-Options: nosniff Content-Type: application/json Transfer-Encoding: chunked Date: Thu, 28 Dec 2023 13:38:49 GMT Server: Apache Ranger {"id":43,"guid":"2c2f8cf1-4ef5-449e-b9f3-978f73d1adbf","isEnabled":true,"createdBy":"Admin","updatedBy":"Admin","createTime":1703770703000,"updateTime":1703770703000,"version":1,"service":"adh_hdfs_id_8","name":"test_policy","policyType":0,"policyPriority":0,"description":"Test policy for HDFS service","resourceSignature":"391f2d50f6f473f28077e9fe73af7b47d918e0905025176820a2e8b540257a72","isAuditEnabled":true,"resources":{"path":{"values":["/resource"],"isExcludes":false,"isRecursive":true}},"policyItems":[{"accesses":[{"type":"read","isAllowed":true},{"type":"write","isAllowed":true}],"users":["test_user"],"groups":[],"roles":[],"conditions":[],"delegateAdmin":false}],"denyPolicyItems":[],"allowExceptions":[],"denyExceptions":[],"dataMaskPolicyItems":[],"rowFilterPolicyItems":[],"serviceType":"hdfs","options":{},"validitySchedules":[],"policyLabels":[],"zoneName":"","isDenyAllElse":false}
Delete a policy
To delete a policy, you need to know its ID in Ranger.
The corresponding curl command is:
$ curl -i -u <login>:<password> -X DELETE <ranger_host>/service/public/v2/api/policy/<id>
where <id>
is the ID of the policy you want to delete.
The expected output for this command should contain the 204 No Content
status:
HTTP/1.1 204 No Content Set-Cookie: RANGERADMINSESSIONID=EBB540344061AEEB0485AEA9DE40E58C; Path=/; HttpOnly Cache-Control: no-cache, no-store, max-age=0, must-revalidate X-Frame-Options: DENY X-XSS-Protection: 1; mode=block Strict-Transport-Security: max-age=31536000; includeSubDomains Content-Security-Policy: default-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline';font-src 'self' X-Content-Type-Options: nosniff Date: Thu, 28 Dec 2023 13:40:18 GMT Server: Apache Ranger
The deleted policy will disappear from the Ranger Admin UI as well.