Connect to Ranger via REST API

Sergei Tikhomirov

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 is DELETE.

  • <request_type> — type of the HTTP request (GET, POST, PUT, DELETE). If the request type is DELETE, 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_hdfs_id_8", (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> -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":42,"guid":"2c2f8cf1-4ef5-449e-b9f3-978f73d1adbf","isEnabled":true,"createdBy":"Admin","updatedBy":"Admin","createTime":1703770703338,"updateTime":1703770703338,"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}

You can check that the policy was created in Ranger Admin UI.

Newly created policy
Newly created policy
Newly created policy
Newly created policy

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":42,"guid":"2c2f8cf1-4ef5-449e-b9f3-978f73d1adbf","isEnabled":true,"createdBy":"Admin","updatedBy":"Admin","createTime":1703770703000,"updateTime":1703776521670,"version":2,"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","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.

Added user to a policy
Added user to a policy
Added user to a policy
Added user to a policy

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":42,"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.

Found a mistake? Seleсt text and press Ctrl+Enter to report it