Connect to Ranger via KMS REST API
Overview
Ranger KMS REST API is identical to Hadoop KMS REST API. Hence, you need to have a valid Kerberos ticket on the host from which you are trying to access Ranger KMS. To get a full list of available endpoints, head over to Ranger KMS 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, provided you have a valid ticket. A template curl command looks like the one below:
$ curl -i --negotiate -u : -X <request_type> <ranger_kms_host>/kms/<endpoint>
where:
-
<request_type>
— type of the HTTP request (GET
,POST
,DELETE
). If the request is supposed to carry some data, specify its content type using-H
and attach the data using-d
. -
<ranger_kms_host>
— Ranger KMS host URL with port (e.g. http://stikhomirov-adps.ru-central1.internal:9292). -
<endpoint>
— resource to which the request will be sent.
The -i
option allows you to see the HTTP headers and check the status of the request, feel free to remove it if deemed unnecessary. The -u
option is required but it’s ignored and a ticket is used for authentication.
Example
This example demonstrates how to get key names using Ranger KMS REST API. Since, by default, there are no keys, you need to create one using the REST API or in Ranger Admin Web UI. The second option is demonstrated below.
Preparation
-
Log into Ranger Admin Web UI as
keyadmin
, open the Key Manager page from a menu on the left, select the kms service option, and click Add New Key.The Encryption pageThe Encryption page -
Fill in the necessary details and click Save at the bottom of the page. The newly created key will appear on the Key Manager page.
The Create Key pageThe Create Key page
Process
-
Log onto a host within a cluster that has a valid Kerberos ticket.
-
Make sure that your curl version has
GSS-Negotiate
among its features by running the command below:$ curl -V
A possible output is:
curl 7.29.0 (x86_64-redhat-linux-gnu) libcurl/7.29.0 NSS/3.90 zlib/1.2.7 libidn/1.28 libssh2/1.8.0 Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp scp sftp smtp smtps telnet tftp Features: AsynchDNS GSS-Negotiate IDN IPv6 Largefile NTLM NTLM_WB SSL libz unix-sockets
-
Make sure that you have a valid ticket by running
klist
. -
Run the command below:
$ curl -i --negotiate -u : -X GET <ranger_kms_host>/kms/v1/keys/names
-
You can find an array of key names in the response body. The key name from the example is returned as follows:
[ "testkey" ]