API Access

This document provides instructions on how to access Openstack API’s for STC Cloud Virtual Datacenters. It is not intended for this document to be a reference guide for how to use Openstack API’s, for these the reader is kindly instructed to consult Openstack API reference available online developer openstack website.

The document will cover accessing the API using curl, openstack CLI and the openstack4j Java client library.

Please note that there are some API differences between our datacenters depending on the implemented version.

CURL

The first step to access Openstack APIs is to get an access token using the identity end point. This is done through issuing a POST request to the /tokens end point. Replace “your username”, “your password” and “your openstack tenant name” with your corresponding credentials.

JED1

curl -i -H "Content-Type: application/json" -d '{"auth": {"identity": {"methods":
["password"],"password": {"user": {"domain":{"name": "jed1"},"name": "your
username","password": "your password"}}},"scope": {"project":
{"domain":{"name":"jed1"},"name": "your teneant name"}}}}' \
https://api-jed1-vdc.bluvalt.com/identity/v3/auth/tokens ; echo

RUH2

curl -i -H "Content-Type: application/json" -d '{"auth": {"identity": {"methods":
["password"],"password": {"user": {"domain":{"name": "ruh2"},"name": "your
username","password": "your password"}}},"scope": {"project":
{"domain":{"name":"ruh2"},"name": "your teneant name"}}}}' \
https://api-ruh2-vdc.bluvalt.com/identity/v3/auth/tokens ; echo

Upon successful authentication the API will return a response which will contain the access token in the http header X-Subject-Token. Below is a sample of the response headers.

HTTP/1.1 200 OK
Date: Mon, 21 Jun 2021 08:51:26 GMT
Content-Length: 0

The access token can then be used to call other openstack APIs e.g. compute, network, image etc. For example we can use the generated to token to list the virtual machines that are deployed in the tenant as in the request below. Replace token with the token that you extracted from above and replace tenant-id with the tenant-id.

OpenStack CLI

The openstack CLI provides command line access to Openstack. You can install the latest version of openstack CLI using Python pip module

pip install python-openstackclient

In order to use the openstack CLI client, it is recommended to use environment variables stored in a file with your credentials. Keep these files secured as they’ll contain sensitive information. Start by creating a file with the following contents depending on the datacenter that your tenant resides in.

First, create openrc.sh file using your favorite editor

RUH2

export OS_USERNAME='your username'
echo "enter the password"
read -sr OS_PASSWORD
export OS_PASSWORD=$OS_PASSWORD
export OS_PROJECT_NAME='your tenant name'
export OS_AUTH_URL=https://api-ruh2-vdc.bluvalt.com/identity/v3
export OS_IDENTITY_API_VERSION=3
export OS_USER_DOMAIN_NAME=ruh2
export OS_DOMAIN_NAME=ruh2
export OS_PROJECT_DOMAIN_NAME=ruh2

JED1

export OS_USERNAME='your username'
echo "enter the password"
read -sr OS_PASSWORD
export OS_PASSWORD=$OS_PASSWORD
export OS_TENANT_NAME='your tenant name'
export OS_AUTH_URL=https://api-jed1-vdc.bluvalt.com/identity/v3
export OS_IDENTITY_API_VERSION=3
export OS_DOMAIN_NAME=jed1
export OS_PROJECT_DOMAIN_NAME=jed1

You’ll need to source the file before issuing commands. Supposing that the file is named openrc. You can use these commands to list the servers in your tenant.

$ source openrc.sh
$ openstack server list

To create a new virtual machine using Openstack CLI commands, you can use the following command script

$ openstack server create --image image_id --flavor flavor_id --nic net-id=network_id
VM_name

You can get the network, image and flavor IDs by calling the List command for each one. “$ openstack flavor list”, “$ openstack image list”, “$ openstack network list”.

This will work in RUH2 (SULAYMANIYAH DC), if you need to run the script on JED1 (JEDDAH DC) you will have to include the volume_size variable.

For more information on using openstack CLI please refer to the the online documentation http://docs.openstack.org/user-guide/cli-cheat-she et.html

Openstack4j - Java Client

There are many clients in different programming languages that provide programmatic access to the Openstack APIs. This document will use the openstack4j library for Java as an example. You can get the latest version of openstack4j from openstack4j website. The listing below shows the code required to get the list of servers from a tenant.

RUH2

OSClient client = OSFactory.builderV2()
.endpoint("https://api-ruh2-vdc.bluvalt.com/identity/v2.0")
.credentials("your username", "your password")
.tenantName("your tenant name")
.authenticate();
List<? extends Server> servers = client.compute().servers().list();

JED1

OSClient client = OSFactory.builderV3()
.endpoint("https://api-jed1-vdc.bluvalt.com/identity/v3")
.credentials("your username", "your password", Identifier
.byName("jed1"))
.scopeToProject(Identifier.byName("your tenant name"), Identifier
.byName("jed1"))
.authenticate();
List<? extends Server> servers = client.compute().servers().list();