Connect to Ranger via KMS REST API

Sergei Tikhomirov

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

  1. Log into Ranger Admin Web UI as keyadmin, open the Key Manager page on the Encryption tab, select the kms service option, and click Add New Key.

    The Encryption page
    The Encryption page
    The Encryption page
    The Encryption page

  2. 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 page
    The Create Key page
    The Create Key page
    The Create Key page

Process

  1. Log onto a host within a cluster that has a valid Kerberos ticket.

  2. 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

  3. Make sure that you have a valid ticket by running klist.

  4. Run the command below:

    $ curl -i --negotiate -u : -X GET <ranger_kms_host>/kms/v1/keys/names

  5. You can find an array of key names in the response body. The key name from the example is returned as follows:

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