Overview

Platform9 is the simplest way for enterprises to implement a private cloud, with intelligent, self-service provisioning of workloads onto their computing infrastructure. Platform9’s cloud service enables the use of existing and new virtualized servers to power private clouds in a minutes, while interoperating seamlessly with existing processes and management products.

Platform9 is based on OpenStack and is 100% compatible with core OpenStack APIs. This documentation describes Platform9’s REST APIs, which include APIs for core OpenStack components that Platform9 supports such as Nova, Glance and Keystone, along with APIs for Platform9’s proprietary components such as Resource Manager.

To use Platform9’s REST API, you are required to get an authentication token, which must be passed into all API calls as an X-Auth-Token request header. All REST API calls are in JSON format. Check the Usage section for more information.

Terminology

Service Endpoint: A Service Endpoint is a distinct web service exposed by Platform9. For eg, Nova, Glance, Keystone and Resource Manager are the distinct Service Endpoints. Each Service Endpoint has a distinct URL that follows the format:

https://<my-company-platform9-url>/<service-endpoint-name>

Example: ‘https://foo.platform9.net/keystone’

where:

◦ my-company-platform9-url is the URL corresponding to the Platform9 account created for your company. This URL is typically of the format https://{company-name}.platform9.net. Eg https://foo.platform9.net

◦ service-endpoint-name is the distinct name for the given service endpoint. For eg the service-endpoint-name for Keystone Service Endpoint is ‘keystone’. The corresponding documentation sections for each Service Endpoint such as Nova, Glance, Keystone and Resource Manager will list the distinct Service Endpoint URL at the beginning.

A REST API request to a Service Endpoint always includes the version of the API being referenced, immediately after the Service Endpoint name.

Example: ‘https://foo.platform9.net/keystone/v2.0’

where ‘2.0’ is the current supported version of keystone API.

Tenant: Platform9 Private Cloud is designed to be shared by multiple users and teams of users. The concept of a ‘Tenant’ is designed so that Administrators can create a distinct Tenant per team of users that will be using the Platform9 Private Cloud. For eg, an Administrator might want to create distinct Tenants for ‘Development’ and ‘QA’ teams to definte different logical pools of resources that each of these teams will utilize. At any given point, a user logged into Platform9 is always operating in the context of a distinct Tenant. An Administrator can assign a given user to one or more Tenants.
Role: Role-based access controls what functionality a user has access to, within a given Tenant. Platform9 currently supports two roles.
- Administrator: As an Administrator user, you have complete access to all functionality exposed by Platform9. You can add or remove servers to Platform9, configure networking, populate image catalog, create and destroy instances etc.
- Self-Service User: A Self-Service user does not have access to infrastructure. He cannot see or manipulate servers, storage or networking configuration. But he does have access to all instances running within a given tenant, as well as Images in the catalog that the tenant has access to. He can create a new instance from Images in the catalog, view all instances running within given tenant, perform lifecycle operations on them, or delete them.
Flavor: A flavor is a pre-defined instance configuration that determines the amount of CPU, Memory and Storage that will be allocated to an instance. Flavors allow the Administrators to standardize on one or more resource configurations for instances within their environment and ensure that all instances are created using one of these standard configurations only. Platform9 ships with a default set of useful flavors, but Administrators can create their own set of flavors that better suit their environments.

Usage

# Copyright (c) Platform9 Systems. All rights reserved

# This python sample code demonstrates how to get the authentication-token from Platform9 Keystone Service by passing username and password credentials. 

import requests
import json

# Platform9 currently ships with a default tenant with name 'service'.

TENANT = 'service'

def login(username, password):

    data = {
        "auth": {
            "tenantName": TENANT,
            "passwordCredentials": {
                "username": username,
                "password": password
            }
        }
    }

    req = requests.post("https://my-company.platform9.net/keystone/v2.0/tokens",
                    json.dumps(data),
                    verify=False,
                    headers={'Content-Type': 'application/json'})

    if req.status_code != 200 :
        raise Exception("Platform9 login returned %d, body:%s" %
                (r.status_code, r.text))
    else :
        return req.json()

# This is the Platform9 username and password associated with your Platform9 account. 
username = <my-platform9-username>
password = <my-platform9-password>
auth = login(username, password)
auth_token = auth['access']['token']['id']

A typical Platform9 REST API call involves following two steps:

All Platform9 REST API calls use JSON as content type. Set the content-type property to be “application/json” in the request header for all Platform9 REST API calls.
Get an authorization token from keystone by making a POST request to:

https://<my-company-platform9-url>/keystone/v2.0/tokens

with your credentials in the request body. (Please check the documentation for this endpoint to see the request format.)

Make your REST API call by setting the ‘X-AuthToken’ parameter in request header to the authentication token you just received in the step above. Each REST API call URL will follow the syntax:

http://<service-endpoint-url>/<api-call-parameters>

◦ service-endpoint-url is described as part of definition of Service Endpoint here

◦ api-call-parameters are defined per API request and are described below.

For example, if you wanted to get a list of users on a specified tenant, you would make a GET request to:

https://my-company.platform9.net/keystone_admin/v2.0/tenants/{tenantId}/users

replacing {tenantId} with the correct identifier of the Tenant you are operating in the context of.

API Endpoints

Please refer to the OpenStack API Reference Guide for a complete OpenStack API documentation, and refer to the table below for a list of services that Platform9 supports and respective API documentation.

APIs that are unique to Platform9 or are not listed on the OpenStack website are described in the Platform9 API Documentation.

Service	Version	Documentation
keystone	v3	http://developer.openstack.org/api-ref-identity-v3.html
keystone	v2	http://developer.openstack.org/api-ref-identity-v2.html
nova	v2	http://developer.openstack.org/api-ref-compute-v2.html
glance	v2	http://developer.openstack.org/api-ref-image-v2.html
glance	v1	http://developer.openstack.org/api-ref-image-v1.html
cinder	v2	http://developer.openstack.org/api-ref-blockstorage-v2.html
cinder	v1	http://developer.openstack.org/api-ref-blockstorage-v1.html
neutron	v2.0	http://developer.openstack.org/api-ref-networking-v2.html
heat	v1	http://developer.openstack.org/api-ref-orchestration-v1.html
ceilometer	v2	http://developer.openstack.org/api-ref-telemetry-v2.html

Resource Manager

Service Endpoint URI: https://<my-company-platform9-url>/resmgr

The resource manager is source of truth for:

Hosts allocated to Platform9.
Their roles in the Platform9 system.
(Optionally) which hosts are approved by user for specific role in Platform9.

Check the Usage section for usage details.

GET /v1/roles

[
    {
        "name": "roleA",
        "display_name": "Role A",
        "description": "Simple role A",
        "active_version": "3.0.9-1"
    },
    {
        "name": "roleB",
        "display_name": "Role B",
        "description": "Another role B",
        "active_version": "1.0.2-5"
    }
]

Returns a list of Platform9 roles available in the system.

Response parameters

Parameter	Type	Description
name	string	The name of the role.
display_name	string	The user-friendly name for the role.
description	string	A description of the role.
active_version	string	The version of the role.

GET /v1/roles/{role_name}

{
    "name": "roleA",
    "display_name": "Role A",
    "description": "Simple role A",
    "active_version": "3.0.9-1"
}

Returns a Platform9 role corresponding to role_name.

Request Parameters

Parameter	Style	Type	Description
role_name	URI	string	The name of the role.

Response parameters

Parameter	Type	Description
name	string	The name of the role.
display_name	string	The user-friendly name for the role.
description	string	A description of the role.
active_version	string	The version of the role.

GET /v1/hosts

[
    {
        "id": "rsc_1",
        "state": "active",
        "info": {
            "hostname": "leb-centos-1.platform9.sys",
            "os_family": "Linux",
            "arch": "x86_64",
            "os_info": "centos 6.4 Final",
            "responding": true,
            "last_response_time": "2014-08-29T18:04:42Z"
        },
        "roles": ["role_1", "role2"],
        "role_status": "ok"
    },
    {
        "id": "rsc_2",
        "state": "activating",
        "info": {
            "hostname": "leb-centos-1.platform9.sys",
            "os_family": "Linux",
            "arch": "x86_64",
            "os_info": "centos 6.4 Final",
            "responding": false,
            "last_response_time": "2014-08-29T18:04:42Z"

        },
        "roles": ["role_2", "role5"],
        "role_status": "ok"
    },
]

Returns a list of hosts in the Platform9 system with their assigned roles.

The last_response_time values are used when the host is not responding. Otherwise, this value may be null.

For unauthorized hosts, responding, last_response_time, and role_status are not exposed.

Response parameters

Parameter	Type	Description
id	string	The unique ID of the host.
state	string	The current state of the host. Can be `active` (host currently has a role assigned to it), `inactive` (host currently has no roles assigned to it), or `activating` (host is currently being assigned a role).
hostname	string	The name of the host.
os_family	string	The operating system family of the host.
arch	string	The architecture of the host.
os_info	string	Information about the operating system.
responding	boolean	If `true`, it indicates that the host is currently responding.
last_response_time	dateTime	The time of the last response by the host.
roles	array	A list of roles by name that belong to the host.
role_status	string	Can be `ok`, `converging`, `retrying`, or `failed`.

GET /v1/hosts/{id}

{
    "id": "rsc_1",
    "info": {
        "hostname": "leb-centos-1.platform9.sys",
        "os_family": "Linux",
        "arch": "x86_64",
        "os_info": "centos 6.4 Final",
        "responding": true,
        "last_response_time": "2014-08-29T18:04:42Z"

    },
    "state": "active",
    "roles": ["role4", "role3"],
    "role_status": "ok"
}

Returns details for a single host.

The last_response_time value is used when the host is not responding. Otherwise, this value may be null.

For unauthorized hosts, responding, last_response_time, and role_status are not exposed.

Request Parameters

Parameter	Style	Type	Description
id	URI	string	The unique ID of the host.

Response Parameters

Parameter	Type	Description
id	string	The unique ID of the host.
state	string	The current state of the host. Can be `active` (host currently has a role assigned to it), `inactive` (host currently has no roles assigned to it), or `activating` (host is currently being assigned a role).
hostname	string	The name of the host.
os_family	string	The operating system family of the host.
arch	string	The architecture of the host.
os_info	string	Information about the operating system.
responding	boolean	If `true`, it indicates that the host is currently responding.
last_response_time	dateTime	The time of the last response by the host.
roles	array	A list of roles by name that belong to the host.
role_status	string	Can be `ok`, `converging`, `retrying`, or `failed`.

Platform9 OpenStack Private Cloud API Documentation

Overview

Terminology

Usage

API Endpoints

Resource Manager

GET /v1/roles

Response parameters

GET /v1/roles/{role_name}

Request Parameters

Response parameters

GET /v1/hosts

Response parameters

GET /v1/hosts/{id}

Request Parameters

Response Parameters