Installing and managing Docker by Using the Rancher API’s – Part 2

In the first part of this article, I discussed how to install/configure Rancher, how to use it from within the Web-UI. below I am going to focus on the Rancher APIs, options to connect and how to use them.

Working with the Rancher API

Before we start using the Rancher API, I suggest you to visit your Rancher API reference page. The API page can be accessed by going to. http://rancher.domain.com:8080/v1 Rancher API Web-UI Reference This makes it extremely easy to explore the Rancher API capability’s. Now, lets just dive in with a simple example.

Using CURL to access API data

Rancher APIs are written in a way to work with any RESTful API request. The simplest way to manipulate and test Rancher data is by using CURL. Tip: All the Rancher documentation is written using CURL examples. After you generated Rancher API keys, we are now ready to use them, just follow the the below examples. for how to generated your Rancher API keys, please read – Rancher APIs Part 1. Note:Since all access to Rancher requires the use of API keys, I decided to use that in my examples below.

curl -s -u "BECFBDD1837652F7AD07:YUHJbca2k7LwK5v4RgSrhKbxBqV5mJ9QdXCs7gqi" \
http://rancher.domain.com:8080/v1/apiKey \
|python -m json.tool

Lets break out the request above.

First part, the Rancher Access Key and Rancher Secret Key
Second part, your rancher domain/port followed by the version, in this case v1
Last part, the request detail, in this case the key is apiKey

After the version(in my case v1), you specify the resource you are going to use, lets look on a more specific request below. The previous request returned all apiKey’s, below I am querying for just one specific key.

curl -s -u "BECFBDD1837652F7AD07:YUHJbca2k7LwK5v4RgSrhKbxBqV5mJ9QdXCs7gqi" \
http://rancher.domain.com:8080/v1/apiKey?uuid='81a3e987-c703-4729-ad72-e894bc54124f' \
|python -m json.tool

What nice about Rancher is, you can explore the api and context right from within the Ranger Web-UI, in our example the apiKey.

apiKey?uuid='81a3e987-c703-4729-ad72-e894bc54124f'

All of this is available as a click thru in the Web-UI.

Rancher handy commend line tool – Gdapi

Next I am going to show you the Rancher API commend line tool Gdapi. Gdapi is a Python client for Rancher APIs. First you need to make sure its installed on your system. To install Gdapi on your system, just run the below.

pip install gdapi-python
[..]snip

Next, to use Gdapi we need to set the below variables.

export GDAPI_URL=http://rancher.domain.com:8080/v1
export GDAPI_ACCESS_KEY=BECFBDD1837652F7AD07
export GDAPI_SECRET_KEY=YUHJbca2k7LwK5v4RgSrhKbxBqV5mJ9QdXCs7gqi

Make sure Gdapi works by running gdapi –help, it should return all gdapi available options. Now that we are ready to use gdapi, lets look / use the same example from the previous section. This can be done by running the below.

gdapi list-apiKey --uuid='3aa684a1-c40a-4be6-9c2d-4c1c4db9f22d'
| Type   | Id   | Name                  | Value                                |
--------------------------------------------------------------------------------
| apiKey | 1c50 | accountId             | 1a5                                  |
| apiKey | 1c50 | uuid                  | 3aa684a1-c40a-4be6-9c2d-4c1c4db9f22d |
| apiKey | 1c50 | baseType              | credential                           |
| apiKey | 1c50 | state                 | active                               |
| apiKey | 1c50 | transitioning         | no                                   |
| apiKey | 1c50 | description           | null                                 |
| apiKey | 1c50 | transitioningProgress | null                                 |
| apiKey | 1c50 | transitioningMessage  | null                                 |
| apiKey | 1c50 | removed               | null                                 |
| apiKey | 1c50 | publicValue           | BECFBDD1837652F7AD07                 |
| apiKey | 1c50 | kind                  | apiKey                               |
| apiKey | 1c50 | name                  | Elis-key                             |
| apiKey | 1c50 | created               | 2017-06-27T16:47:44Z                 |
| apiKey | 1c50 | createdTS             | 1498582064000                        |
| apiKey | 1c50 | secretValue           | null                                 |

Tip: To get back all api Keys, just omit the more specific options. an example is below.

gdapi list-apiKey
[...]

In summery, Gdapi is a very handy tool to explore many aspects of the Rancher API. For more information on Gdapi click here.

Using Python to manipulate the Rancher API data

In this section, I am using Python to access the Rancher APIs. Below, I am again using the previous example, accessing the same Rancher API data, but instead of CURL or Gdapi I am using Python to manipulate the Ranger API data.

#!/usr/bin/python

import requests
from requests.auth import HTTPBasicAuth
import sys, json, os
import yaml

url='http://rancher.domain.com:8080/v1'
access_key='BECFBDD1837652F7AD07'
secret_key='YUHJbca2k7LwK5v4RgSrhKbxBqV5mJ9QdXCs7gqi'
ContentType = 'application/json'
api_v='v1'
uuid_num='81a3e987-c703-4729-ad72-e894bc54124f'
account_name='system'

# Remove proxy if set (as it might block or send unwanted requests to the proxy)
if "http_proxy" in os.environ:
    del os.environ['http_proxy']
if "https_proxy" in os.environ:
    del os.environ['https_proxy']

def getReqType( reqType, uuid_num, account_name, api_v ):
     if reqType == "uuid":
       if uuid_num:
        reqType = 'http://rancher.domain.com:8080/'+ api_v + '/apiKey?uuid=' + uuid_num
       else:
        reqType = 'http://rancher.domain.com:8080/'+ api_v + '/apiKey'
     elif reqType == "accounts":
       if account_name:
        reqType = 'http://rancher.domain.com:8080/'+ api_v + '/accounts?name=' + account_name
       else          
        reqType = 'http://rancher.domain.com:8080/'+ api_v + '/accounts'
     return reqType

# Set values
headers                 = {}
headers['Content-Type'] = ContentType
url                     = getReqType("uuid", uuid_num, account_name, api_v)
reqType                 = "apiKey"

r = requests.get(url, auth=(access_key, secret_key))

data = json.loads(r.text)
print json.dumps(data, sort_keys=True,
                 indent=4 )

Note: There is also a Python binding for Gdapi, but I was not able getting it to work (it seemed deprecated in the recent versions, as any REST calls should work).

Ruby API bindings for Rancher

In case you are looking for a Ruby option, there is also a Ruby wrapper for the Rancher APIs. To install the Ruby bindings, just run the below.

gem install rancher-api

Full details is available here. To summarize, Rancher is an extremely powerful platform for managing Docker, both on the UI front or APIs, there are a number of alternatives but Rancher is defiantly a very good option. Now its your turn. What tools worked best for you to manage a Docker environment? please let me know in the comments below.