We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
DCRM OCCI Open RESTful API Specification - FIWARE Forge Wiki

DCRM OCCI Open RESTful API Specification

From FIWARE Forge Wiki

Revision as of 07:38, 13 August 2014 by Jkennedyie (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents


Introduction to the Open Cloud Computing Interface (OCCI) API

Please check the following Legal Notice (essential patents license) to understand the rights to use these specifications.

This specification is based on OCCI, published by OGF. Check the OCCI Legal Notice to understand the relevant usage rights.

OCCI is an open, standardised, extendable, RESTful interface designed to manage arbitrary resources. Whilst OCCI is used in FI-WARE to manage virtual machines, OCCI can also be used to manage storage resources, network resources, and even software services.

The OCCI walkthrough presentation provides a useful introduction to OCCI. Complete technical details of the standard are available in the formal specification documents:

Any observations, feedback or questions on OCCI can be posted to the OCCI community via the OCCI Mailing list.

OCCI API Core

The OCCI core model forms the basis of its type system. Types made available by OCCI implementations are defined by the Category construct. There are two specialised forms of the Category construct: Kind and Mixin. Kind defines the basic capabilities (attributes and functionality) of a type of resource. Mixin defines a means to further modify and extend a particular Kind’s capabilities. Action’s define the executable functionality (e.g. methods) of either. Categories are self-descriptive, they can be discovered through a Query interface. The Query Interface allows for all service provider supported Categories to be discovered and described. The core model forms the basis for the Infrastructure as a Service specification. This specification extends the core model and it in itself provides an example of how one can extend the OCCI model to suit particular needs.

Intended Audience

This specification is intended for both software developers and Cloud Providers. For the former, this document provides a full specification of how to interoperate with Cloud Platforms that implement the OCCI API. For the latter, this specification describes the interface to be provided in order for clients to interoperate with the Cloud Platform to provide the described functionalities. To use this information, the reader should firstly have a general understanding of the Data Centre Resource Manager Generic Enabler service. The reader should also be familiar with:

  • ReSTful web services.
  • HTTP 1.1.
  • Text and JSON data serialisation formats.

API Change History

This version of the DCRM Open RESTful API Specification replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
Apr 30, 2012
  • Initial Version
Sept 4, 2012
  • Updated Templated sections
April 29, 2013
  • Restructured content

How to Read This Document

It is assumed that the reader is familiar with the RESTful architectural style. This document uses the following notation:

  • A bold, mono-spaced font is used to represent code or logical entities, e.g., HTTP method (GET, PUT, POST, DELETE).
  • An italic font is used to represent document titles or some other kind of special text, e.g., URI.

For a description of some of the terms used within this document, see the Data Center Resource Management Architecture.

Additional Resources

General OCCI API Information

Resources Summary

To understand what infrastructural resources are specified by OCCI see GFD184. To understand the core resource model within OCCI see GFD183 Sections 3 and 4. As providers of the API may wish to use different URI schemes and hierarchies, OCCI does not prescribe a static configuration. To understand how the hierarchy can be discovered through OCCI’s query interface see GFD183. The OCCI Query Interface is advertised using the well-known location IETF RFC5785. OCCI is highly extensible and various extension mechanisms and extension points are documented in GFD183 Section 4.6.

Authentication

Each HTTP request against OCCI requires the inclusion of specific authentication credentials. The specific implementation of this API may support multiple authentication schemes (OAuth, Basic Auth, Token) as such mechanisms are orthogonal to the API. This will be determined by the specific provider that implements the GE. Please contact with it to determine the best way to authenticate against this API. Remember that some authentication schemes may require that the API operate using SSL over HTTP (HTTPS). See GFD185 for further details.

Representation Format

The OCCI API supports plain text:

  • text/plain - this is the default content type
  • text/occi
  • text/uri-list

See GFD185 for precise Augmented Backus-Naur Form (ABNF) specifications of these content types. JSON support is currently being developed. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using the standard HTTP Accept header.

Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC–2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary. For OCCI specifics see GFD185.

Resource Identification

To understand how resource identification is achieved in OCCI, see GFD183.

Linking Resources

Resources often lead to refer to other resources. To review how this is done in OCCI (using the Link construct), see GFD183 Section 4.5.3 and GFD184 on their application to infrastructural resources.

Pagination of Resource Collections

This is being developed through the JSON specification.

API Limits

This is implementation specific. In the OpenStack OCCI implementation, within the nova-api module, a WSGI middleware is included to enable rate limiting. The OCCI API can also use this and as such be part of its middleware pipeline as is done for all OpenStack API services. This is configured through the /etc/nova/api-paste.ini file.

Versions

To get the version that an OCCI service is using, see GFD185. Associated semantics with version mismatches etc are also dealt with there.

Extensibility

See GFD183 and GFD184. It should be noted that GFD184 is an extension itself and so offers a comprehensive example OCCI extensibility. The CompatibleOne project uses OCCI as their core model. How they extend the OCCI core model can be seen in the CORDS reference manual.

Faults

For the full set of faults that an OCCI service can return please also see GFD185. The most common error codes are listed here:

HTTP Return code Description
200 OK Indicates that the request was successful. The response MUST contain the created resource instance's representation.
201 OK Indicates that the request was successful. The response MUST contain a HTTP Location header to the newly created resource instance.
400 Bad Request Used to signal parsing errors or missing information (e.g. an attribute that is required is not supplied in the request).
401 Unauthorized The client does not have the required permissions/credentials.
404 Not Found Used to signal that the request had information (e.g. a kind, mixin, action, attribute, location) that was unknown to the service and so not found.
500 Internal Server Error The state before the request should be maintained in such an error condition. The implementation MUST roll-back any partial changes made during the erroneous execution.

API Operations

See GFD183, GFD184 and GFD185 for all OCCI specifications on specific aspects. The FI-WARE programmer guide will also provide examples of how to use the API. Only operations related to OCCI extensions will be discussed and described here. In the sections below a summary of the extension, its purpose and example usage will be given. The example usages will use the text/occi content type for brevity.

Architectural Operation Mapping

These operations are listed in the Data Centre Resource Management architectural specification. A high level mapping of these operations to OCCI requests are presented below. The operations described here are all listed with mandatory inputs.

  • createVirtualServer
    • Description: provision a new virtual server with the given properties (virtual hardware, policy parameters, access, etc). Returns unique ID of the virtual server.
    • OCCI Mapping: A HTTP POST using the compute, OsTemplate and ResourceTemplate categories.
  • destroyVirtualServer
    • Description: remove a virtual server
    • OCCI Mapping: A HTTP DELETE issued against the HTTP URL identifying the virtual server instance.
  • powerOnVirtualServer
    • Description: turn on a virtual server
    • OCCI Mapping: A HTTP POST using the start action.
  • createVirtualServer
    • Description: provision a new virtual server with the given properties (virtual hardware, policy parameters, access, etc). Returns unique ID of the virtual server.
    • OCCI Mapping: A HTTP POST using the compute, OsTemplate and ResourceTemplate categories.
  • destroyVirtualServer
    • Description: remove a virtual server
    • OCCI Mapping: A HTTP DELETE issued against the HTTP URL identifying the virtual server instance.
  • powerOnVirtualServer
    • Description: turn on a virtual server
    • OCCI Mapping: A HTTP POST using the start action.
  • powerOffVirtualServer
    • Description: turn off a virtual server
    • OCCI Mapping: A HTTP POST using the stop action, parameterised with the method=acpioff.
  • restartVirtualServer
    • Description: restart a virtual server
    • OCCI Mapping: A HTTP POST using the restart action.
  • shutdownVirtualServer
    • Description: shut down a virtual server (note: the ability to perform this operation on the fly depends on the capabilities of the underlying virtualisation platform)
    • OCCI Mapping: A HTTP POST using the stop action, parameterised with the method=graceful.
  • resizeVirtualServer
    • Description: change the virtual hardware allocation for a virtual server (note: the types of resources for which the reconfiguration can be done on the fly depends on the capabilities of the underlying virtualization platform)
    • OCCI Mapping: A HTTP POST (partial update) against the the HTTP URL identifying the virtual server instance and with the ResourceTemplate specified indicating the new hardware allocation profile.
  • getVirtualServerDetails
    • Description: returns details of a virtual server (virtual hardware specification, state, associated policy parameters, access details, etc)
    • OCCI Mapping: A HTTP GET against the the HTTP URL identifying the virtual server instance.
  • createVirtualDisk
    • Description: provision a new virtual disk with the given properties (size, capabilities, etc). Returns unique ID of the virtual disk.
    • OCCI Mapping: A HTTP POST using the storage category.
  • destroyVirtualDisk
    • Description: remove a virtual disk
    • OCCI Mapping: A HTTP DELETE issued against the HTTP URL identifying the virtual disk instance.
  • attachVirtualDisk
    • Description: attach a given virtual disk to a given virtual server (note: the ability to perform this operation on the fly depends on the capabilities of the underlying virtualization platform)
    • OCCI Mapping: A HTTP POST using the storagelink link category.
  • detachVirtualDisk
    • Description: detach a given virtual disk from a given virtual server (note: the ability to perform this operation on the fly depends on the capabilities of the underlying virtualization platform)
    • OCCI Mapping: A HTTP DELETE issued against the HTTP URL identifying the storage link associating the virtual server with the virtual disk instances.
  • getVirtualDiskDetails
    • Description: return details of a given virtual disk (ID, capabilities, attachment details, etc)
    • OCCI Mapping: A HTTP GET against the the HTTP URL identifying the virtual disk instance.
  • createVirtualNetwork
    • Description: provision a new virtual network with the given properties (e.g., VLAN ID, capabilities, etc). Returns unique ID of the virtual network.
    • OCCI Mapping: A HTTP POST using the network and ipnetwork categories.
  • destroyVirtualNetwork
    • Description: remove a virtual network
    • OCCI Mapping: A HTTP DELETE issued against the HTTP URL identifying the virtual network instance.
  • attachVirtualServerToNetwork
    • Description: attach a virtual network interface of a given virtual server to a given virtual network
    • OCCI Mapping: A HTTP POST using the networkinterface link category and ipnetworkinterface mixin.
  • detachVirtualServerFromNetwork
    • Description: detach a virtual network interface of a given virtual server from a given virtual network
    • OCCI Mapping: A HTTP DELETE issued against the HTTP URL identifying the network link associating the virtual server with the virtual network instances.
  • getVirtualNetworkDetails
    • Description: return details of a given virtual network (ID, capabilities, attachment details, etc)
    • OCCI Mapping: A HTTP GET against the the HTTP URL identifying the virtual network instance.
  • listVirtualImages
    • Description: return a list of all available virtual images (visible by the authenticated user)
    • OCCI Mapping: HTTP GET on the Query Interface
  • queryVirtualImages
    • Description: return a list of available virtual images, filtered by given query criteria.
    • OCCI Mapping: HTTP GET on the Query Interface with a categories filter applied.
  • getVirtualImageDetails
    • Description: return details of a virtual image (type, size, creation details, etc)
    • OCCI Mapping: image details are present in all HTTP GETs on the Query Interface.
  • uploadVirtualImage
    • Description: upload a new virtual image into the virtual image repository
    • OCCI Mapping: HTTP POST against the query interface with the OsTemplate category supplied (Note not currently supported in OCCI V1.1).

OCCI Kind Extensions

These extensions extend the OCCI core model Kind construct (See Core Model Section 4.4.2). As such they can have full create, retrieve, update and delete functionality.

Security Group Extension

Security Rules are associated with a Collection defined by a Mixin. Rules can be removed likewise. The semantics of this are set out in the OCCI Core Model document Section 4.6.3, where user-supplied Mixins are described. This is a candidate extension to be offered to OCCI for inclusion in main spec.

Example Text Rendering:

Category: my_grp; scheme="http://www.mystuff.org/sec#"; class="mixin"; rel="http://schemas.ogf.org/occi/infrastructure/security#group

Security Rule Extension

Using this extension network security ingress rules can be applied to VMs. The definition of such rules are a requirement in satisfying NIST cloud computing SAJACC use cases. EC2, OpenStack and OpenNebula all share this functionality. This is a candidate extension to be offered to OCCI for inclusion in main spec.

Example text rendering:

Category: rule; scheme="http://schemas.openstack.org/occi/infrastructure/network/security#"; class="kind"
X-OCCI-Attribute: occi.network.security.protocol = "tcp"
X-OCCI-Attribute: occi.network.security.to = 22
X-OCCI-Attribute: occi.network.security.from = 22
X-OCCI-Attribute: occi.network.security.range = "0.0.0.0/24"

VNC Console Extension

This extension is used only to relay information back to the client about console endpoint information. It only supports HTTP GET or retrieve functionality.

Example text rendering:

Category: vnc_console; scheme="http://schemas.openstack.org/occi/infrastructure/compute#"; class="mixin"
X-OCCI-Attribute: org.openstack.compute.console.vnc="http://10.234.54.23:5901"

SSH Console Extension

This extension is used only to relay information back to the client about console endpoint information. It only supports HTTP GET or retrieve functionality.

Example text rendering:

Category: ssh_console; scheme="http://schemas.openstack.org/occi/infrastructure/compute#"; class="mixin"
X-OCCI-Attribute: org.openstack.compute.console.ssh="ssh://142.123.45.42:22"

OCCI Mixin Extensions

These extensions extend the OCCI core model Mixin construct (See Core Model Section 4.4.3). As such they can only have full create and delete functionality.

TCP - Trusted Compute Pool Extension

This mixin extension signals to the backend implementation that the requested VM to be provisioned should be placed on hardware that has TCP capabilities.

Example text rendering:

Category: floating_ip; scheme="http://schemas.openstack.org/instance/network#"; class="mixin"
X-OCCI-Attribute: org.openstack.credentials.publickey.name="my_pub_key"

Administrative Password Extension

This mixin extension allows for authenticated users to specify the administrative password of the VM.

Example text rendering:

Category: admin_pwd; scheme="http://schemas.openstack.org/instance/credentials#"; class="mixin"
X-OCCI-Attribute: org.openstack.credentials.admin_pwd="pussinboots"

Access IP Extension

This mixin extension allows for authenticated users to specify an additional access IP and is used as a means to route from that IP to the target VM’s internal IP.

Example text rendering:

Category: access_ip; scheme="http://schemas.openstack.org/instance/network#"; class="mixin"
X-OCCI-Attribute: org.openstack.network.access.ip="188.12.132.58"
X-OCCI-Attribute: org.openstack.network.access.version="ipv4"

Key Pair Extension

This mixin extension allows for authenticated users to set a SSH public key for passwordless authentication (via SSH) against the provisioned VM.

Example text rendering:

Category: floating_ip; scheme="http://schemas.openstack.org/instance/network#"; class="mixin"
X-OCCI-Attribute: org.openstack.credentials.publickey.name="my_pub_key"
X-OCCI-Attribute: org.openstack.credentials.publickey.datap="ssh-dss AAAAB3NzaC1kc3MAAACBAML/WvvbXBF1DWTou0ISmDJGo4OsfU6qW94vyZuiM05LbChnPrBVlzv1p2gWw/PlC6jkD/aNaMJwbuQoS/1J2G6cHgcX6oeNM+mo/BtHKZGUmMjvKeeNuP8BqB0YX4OMSQ5E0GLfFmLC0P4QpjZ0jiuE4K8AM3Ht75p9XCtdTpF3AAAAFQC6E882UjUeZGbv8zja97gfFbLTGwAAAIBERL187u5siYAf2Cq4pBZ3YSoeWjrn68bU5h9DWXlRnMb1G0waPhh4MCbYfKefqstu/mwuq9w2gIGYuzY2NBHX2BYDtC2cfKh0v1SzFv1U6UtOg9WT34eNuHNkCrgE1p+JuSaZQ8rO864GabxwSWxMQe53DwpaznCzcuK6KL4VGQAAAIBybl3bv7S1UsW51LmnasshlVVaMF5i1pS5qFYjK829"

Floating IP Extension

This mixin extension allows for authenticated users know what the allocated floating IP address of a VM is.

Example text rendering:

Category: floating_ip; scheme="http://schemas.openstack.org/instance/network#"; class="mixin"
X-OCCI-Attribute: org.openstack.network.floating.ip="172.156.89.12"

OCCI Action Extensions

These extensions extend the OCCI core model Action construct (See Core Model Section 4.5.4). As such they only implement the executive aspect of the construct (via HTTPPOST`).

Change Password Action Extension

This action allows authenticated users to change the administrative user’s password.

Example text rendering:

Category: chg_pwd; scheme="http://schemas.openstack.org/instance/action#"; class="action"
X-OCCI-Attribute: org.openstack.credentials.admin_pwd="new_pass"

Revert Action Extension

This action allows authenticated users to rollback a VM resize operation.

Example text rendering:

Category: revert_resize; scheme="http://schemas.openstack.org/instance/action#"; class="action"

Confirm Resize Action Extension

This action allows authenticated users to confirm that a VM resize operation was successful and met their needs.

Example text rendering:

Category: confirm_resize; scheme="http://schemas.openstack.org/instance/action#"; class="action"

Create Image Action Extension

In order to create a bootable VM image from an existing running VM, a user can use the create_image Action. The resultant image MUST and will be exposed only to the owning user through the OCCI query interface.

Example text rendering:

Category: create_image; scheme="http://schemas.openstack.org/instance/action#"; class="action"
X-OCCI-Attribute: org.openstack.snapshot.image_name="my_image_name" 

Allocate IP Action Extension

This action allows authenticated users to allocate a floating (static) IP to a VM. The pools (pool names are obtained from the Query Interface) from which IPs can be obtained is listed in the OCCI Query Interface.

Example text rendering:

Category: alloc_float_ip; scheme="http://schemas.openstack.org/instance/action#"; class="action"
X-OCCI-Attribute: org.openstack.network.floating.pool="nova"

Deallocate IP Action Extension

This action allows authenticated users to deallocate a floating (static) IP to a VM and release back to the originating IP pool.

Example text rendering:

Category: dealloc_float_ip; scheme="http://schemas.openstack.org/instance/action#"; class="action"
Personal tools
Create a book