PowerVC provides a rich and powerful set of APIs. We know this is true because the PowerVC web console uses those APIs itself. If you can do something via the PowerVC web console, you can do it via the APIs! And you don't need a special client. PowerVC provides REST APIs, which means that any client implementation adhering to the HTTP standard will work. That is a very long list. Are you taking advantage of these capabilities? Would you like to know more about how you could? Let's dive in and take a look.
Requesting a token...
The first thing to understand is that Keystone is... well, the keystone. Nearly every API request is restricted to authorized users. In order to prove that you are who you say you are (authentication) and have permissions to do what you're requesting (authorization), you will need to provide a token as part of your request. In order to get this token, you will need to send a special API request to Keystone (the identity service) including your userid and password for Keystone to validate. So let's start there. Here's how you might do that using curl, a very handy command you'll find on pretty much any non-Windows operating system:
curl -1 -k -i -X POST https://mypowervchostname:5000/v3/auth/tokens -H "Accept: application/json" -H "Content-Type: application/json" -d '{"auth": {"scope": {"project": {"name": "ibm-default", "domain": {"name": "Default"}}}, "identity": {"methods": ["password"], "password": {"user": {"domain": {"name": "Default"}, "name": "myuser", "password": "mypassword"}}}}}' | grep X-Subject-Token | cut -d ' ' -f2
Let's break that down piece by piece:
1) For security reasons, PowerVC 1.2.3 requires TLS 1.2. Not all versions of curl support TLS 1.2 by default, so we specify the -1 to tell curl to use TLS. You may or may not find this necessary, but it certainly won't hurt.
2) Somewhat in conflict with the concern for security that the previous element showed, we've also specified the -k argument, which tells curl to bypass certificate validation. In a production environment you would probably not want to do this, but we've done this for simplicity's sake. You can find a wealth of information about certificate validation in other sources across the internet. Check out the --cacert and --capath arguments to do proper certificate validation with curl.
3) -X POST... This is where we specify which HTTP method we're going to use in our request. There are a number of different methods in the HTTP specification (mostly found in section 4.3 of RFC 7231). In this case, we are going to make a POST request, sending data to the server for it to use in creating a new token.
4) https://mypowervchostname:5000/v3/auth/tokens ... This URL tells curl both where to send the request (port 5000 on a server named mypowervchostname), to send it over https (for SSL/TLS security), and which particular entity we're interested in (/v3/auth/tokens). You will of course want to replace "mypowervchostname" with the correct hostname or IP address for your environment.
5) -H "Accept: application/json" ... This indicates that we would like the response to come back in the JSON data format (the only supported format since OpenStack dropped XML support)
6) -H "Content-Type: application/json" ... This indicates that the body of our request (yet to come) will be in JSON format
7) -d '{"auth": {"scope": {"project": {"name": "ibm-default", "domain": {"name": "Default"}}}, "identity": {"methods": ["password"], "password": {"user": {"domain": {"name": "Default"}, "name": "myuser", "password": "mypassword"}}}}}' ... The request body, which in this case tells keystone what scope you're requesting and what credentials you're providing as proof of your identity. Replace "myuser" and "mypassword" with a valid user and password for your environment.
8) grep X-Subject-Token ... This is stripping out the line of the response that includes the X-Subject-Token header.
9) cut -d ' ' -f2 ... This is parsing the new token id value out of the X-Subject-Token header.
Doing that with Python...
Or you might do something like this in python:
#!/usr/bin/python
import json
import requests
address = 'mypowervchostname'
usr = 'myuser'
pwd = 'mypassword'
token_req_template = json.dumps(
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"domain": {
"name": "Default"
},
"name": "%(usr)s",
"password": "%(pwd)s"
}
}
},
"scope": {
"project": {
"domain": {
"name": "Default"
},
"name": "ibm-default"
}
}
}
})
# get an auth token from keystone
r = requests.post('https://%s:5000/v3/auth/tokens' % address,
headers={'accept': 'application/json',
'content-type': 'application/json'},
data=token_req_template % {'usr': usr, 'pwd': pwd},
verify=False)
tok = r.headers['x-subject-token']
print "token id:", tok
As with the curl request, note that the address, user, and password will be unique to your environment and the user attempting to make the request. Replace those values with your own and this code will print the token id, found in the X-Subject-Token header of the response. The nitty gritty details of this request and its responses are documented here if you want to dig deeper: http://developer.openstack.org/api-ref-identity-v3.html#authenticate . For the purpose of this post, suffice it to say that the address, userid and password are the only values you will need to customize in the request above when working with PowerVC 1.2.3, which does not have multiple projects, etc. You may also need to modify the line that says "verify=False" in order to do certificate verification, but as with the curl example we will skip over that here.
We have a token... what now?
Now that you have a token, you can make any number of requests that will yield what you're really after. How do we do that? Well, we'll start by checking the service catalog to see how we should address our next request. This is another element of the token response we just got from keystone. PowerVC is composed of multiple services, each with their own API operating on a separate port. The service catalog has entries for each of these. To continue our python example:
json.loads(r.text)['token']
# find the nova url
for entry in resp_body['catalog']:
if entry['type'] == 'compute':
for endpoint in entry['endpoints']:
if endpoint['interface'] == 'public':
nova_url = endpoint['url']
print "nova public url:", nova_url
If you add that to the previous code sample and run it all together, you should get back something like this:
token id: 84d0f1af6c094a439713eba72c2d7daa
nova public url: https://mypowervchostname:8774/v2/c5d8571d1d674d5e99e89b49af583941
Port numbers are not configurable in PowerVC 1.2.3, so you could just remember that the compute service runs on port 8774, but this may not always be the case in the future. And the project id, also known as the tenant id, (c5d8571d1d674d5e99e89b49af583941 in this example) will vary from installation to installation. So the service catalog is there to give you this information, upon which you will build further API requests.
Making the next request...
So let's ask the compute service for a list of servers (virtual machines):
r = requests.get(nova_url + '/servers',
headers={'accept': 'application/json',
'x-auth-token': tok},
verify=False)
print json.dumps(json.loads(r.text), indent=3)
You'll notice that this request included the token we got from keystone in an "X-Auth-Token" header. Without a valid X-Auth-Token header, the request will fail with an authentication error. It does not include the Content-Type header because it does not send any data on the request. We are using the GET method rather than the POST method, which indicates that we're simply reading data from the server, not sending any of our own.
A couple more tips before we bring this to a close...
The examples above should get you started. There is a wealth of information on different REST APIs that PowerVC supports in the PowerVC Knowledge Center documentation, found at the following links:
for PowerVM: http://www-01.ibm.com/support/knowledgecenter/SSXK2N_1.2.3/com.ibm.powervc.standard.help.doc/powervc_pg_kickoff_hmc.html
for PowerKVM: http://www-01.ibm.com/support/knowledgecenter/SSXK2N_1.2.3/com.ibm.powervc.kvm.help.doc/powervc_pg_kickoff_kvm.html
But you don't necessarily have to build all your requests from scratch. Earlier I mentioned that the PowerVC web console is using the PowerVC APIs. You can use this to your advantage whenever you're not exactly sure how to craft an API request of your own. Do what you want to do via the PowerVC web console, and capture the request(s) that it sends. This can be accomplished quite easily with something like the Firebug extension for the Firefox browser. You'll see both the requests and the responses. Combine these with the PowerVC Knowledge Center documentation to help you interpret what you're seeing, and away you go!
One important note to make here is that PowerVC also employs a reverse proxy running on standard https port 443 so that the PowerVC web console can route all requests to a single port. This is done to satisfy the same-origin restriction enforced by modern web browsers. So if you do use that last tip, you'll see URLs like https://mypowervchostname/powervc/openstack/compute/v2/c5d8571d1d674d5e99e89b49af583941 instead of https://mypowervchostname:8774/v2/c5d8571d1d674d5e99e89b49af583941 . You can direct traffic to that proxy as well, but unless you're writing something that will run in a browser, you're probably better off converting that to the format which includes the port number. This avoids the overhead of going through the proxy, and gives you a more standard way of access the APIs (since the proxy is PowerVC-specific, whereas most APIs are not when used directly).
We hope this has been helpful. Please let us know if you have further questions, find an error in our documentation, have a suggestion where we can improve, etc. We want PowerVC to meet your needs.