Do not edit this page - it's contents are now being transferred to latex.

Core & Models - Working Area

Changelog

• Moved ID attribute from Resource to Kind.
• Merged Andy's more detailed description of the "type system".
• Note on how to implement external links.
• UML fix, remove Category -- Action composition. Actions are advertised through the Resource. Removes an ugly loop in the model.
• Updated Category description. Tagging to create collections and templates for VM provisioning should be clear now.
• Clarified provider-defined Categories.
• Added requirement that a Resource must only expose its currently available actions.
• Rewrote Category definition to clarify static types versus introducing new behaviour to resource instances.
• Rewrote Template definition adding recommended use of Templates.
• Added Template use case examples, i.e. how to use Categories outside of the static type system.
• Added subsection on Category hierarchies.
• Moved extension stuff to the Extensibility section.
• The new Extensibility section is somewhat repetitive but as long as it is consistent that should be ok.
• Update Introduction diagram.
• Updated UML diagram. Fixes the issue with Actions.
• Updated and re-structured description/definition of the base types. Please read everything through.
• Templates definition added, it is just a Category but without the requirement to be a type construct.
• Added full description of the Category base type. Including how to determine if a category is for a resource or a template.
• Removed all REST and HTTP stuff. This information will reappear in the HTTP Rendering document.
• HTTP related Open Issues will reappear in the HTTP Rendering document.
• Extension rules properly defined.
• Discovery mechanism from the Core perspective.

Status of this Document

This document provides information to the community regarding the specification of the Open Cloud Computing Interface. Distribution is unlimited.

Copyright Notice

Copyright © Open Grid Forum (2009-2010). All Rights Reserved.

Trademarks

OCCI is a trademark of the Open Grid Forum.

1 Abstract

This document, part of a document series, produced by the OCCI working group within the Open Grid Forum (OGF), provides a high-level definition of a Protocol and API. The document is based upon previously gathered requirements and focuses on the scope of important capabilities required to support modern service offerings.

2 Introduction

The Open Cloud Computing Interface (OCCI) is a RESTful Protocol (and API) for all kinds of Management tasks. Originally initiated to create a remote management API for IaaS model based Services, allowing for the development of interoperable tools for common tasks including deployment, autonomic scaling and monitoring, it now can be used to severe other models as well. To be modular and extensible the current specification itself is currently split into three complimentary documents:

1. Core – this defines the OCCI model, common resource types and shared attributes (This document)
2. Infrastructure – this defines the infrastructure domain resource types, the required attributes for each and the actions that can be taken on each.
3. HTTP Rendering - this defines how to manipulate the core model using the OCCI RESTful API. The document defines how the OCCI model can be communicated and thus serialized using HTTP headers.

OCCI is a boundary protocol/API that acts as a service front-end to a provider’s internal management framework. The following diagram shows OCCI's place in a provider’s architecture:

3 Notational Conventions

All these parts and the information within are mandatory for implementors (unless otherwise specified). The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

4 Core & Models

The core of the OCCI model is a simple. The central resource type is Resource and contains a number of common attributes that domain-specific resource types inherit. These resource types are complemented by two additional types, Link and Action. Accompanying, Kind and Category provide the fabric for a safe extension model towards domain-specific usage. For compliance with OCCI Core, all types MUST be implemented.

The following sections of the specification define the foundations of the OCCI model, including common resource types, linkages and attributes.

4.1 The base types

The following sections describe the base types of the OCCI core model. The base types are Kind, Category, Resource, Link and Action. All base types MUST be implemented.

4.1.1 Kinds The Kind type is an abstract base type and common to all resources in the OCCI context. It MUST be implemented. Kind enforces for all subtypes a required id attribute and an (optional) title attribute. More importantly Kind introduces one or more type mix-ins, called Category (see below). The following table defines the attributes the Kind type MUST implement to be compliant:

4.1.2 Categories

The Category type represent the classification mechanism used by OCCI. It MUST be implemented. From a system point of view a Category is used for two different classification purposes. See also section 4.3 "Type System".

1. Taxonomy. A Category is used to assign static type information to each resource type inheriting Kind or a descendant of Kind. This use of Categories denotes the OCCI "static type system". A unique Category MUST be assigned to every descendant of Kind. See the section 4.1.2.1 "Hierarchy".
2. Folksonomy. A Category can be used to assign tags to resource instances via a mix-in like model. A Category mix-in MUST NOT be related to an OCCI base type (or any descendent of Kind) and MUST NOT be the unique identifier thereof. Example use cases are collections, location information and templates for virtual machine provisioning.

The following table defines the attributes the Category type MUST implement to be compliant:

A Category is uniquely identified by concatenating the categorisation scheme with the category term, e.g. http://example.com/category/scheme#term. This is done to enable discovery of Category definitions per HTTP. All renderings MUST make use and understand concatenated unique identifiers of Categories.

4.1.2.1 Hierarchy

To be a part of the "static type system" a Category MUST be related, either directly or indirectly, to a base type Category. Extension of the OCCI base types through subtyping thus implies a hierarchy of related Categories.

In an example where "Custom-Compute-Resource" is a subtype of "Compute-Resource", which in turn is a subtype of the Resource base type, three related Categories would be involved. The following table illustrates the exemplified hierarchy of Categories relating the custom Category to a base type Category.

Example

4.1.3 Resources

The Resource type describes a concrete resource that can be inspected and manipulated. It represents a general object in the OCCI core model and MUST be implemented. Resource enforces the inheritance of a set of common attributes into subtypes (such as a unique identifier and an optional descriptive summary). Moreover, it introduces relationships to other Kind instances, denoted by Links. It also introduces operations that can be invoked on this instance, denoted by Actions.

The Resource type is assigned the http://schemas.ogf.org/occi/core#resource Category.

• A Resource instance MUST at least expose this or a related Category together with any associated attributes.
• A Resource instance MUST advertise those of its Actions, if any, which are currently applicable.
• A Resource instance MUST implement the attributes in the following table:

The OCCI Infrastructure document define a set of specific subtypes of Resource. They inherit Resource and is each assigned an unique Category.

4.1.4 Links

The Link type defines a base association between two Resources. It MUST be implemented. Link indicates that one resource is connected to another.

The Link type is assigned the http://schemas.ogf.org/occi/core#link Category. A Link instance MUST at least expose this or a related Category together with any associated attributes. A Link instance MUST also implement the attributes in the following table:

The Link base type MUST NOT refer to an external resource. A provider MAY however create a subtype of Link with different semantics that e.g. have a target attribute containing an URI and thus the ability of linking with external resources.

4.1.5 Actions

The Action type defines an invocable operation on an associated Resource. It MUST be implemented. In general, Actions modify state (by performing a complex operation such as rebooting a virtual machine).

The Action type is assigned the http://schemas.ogf.org/occi/core#action Category. A Action instance MUST at least expose this or a related Category together with any associated attributes.

4.2 Mutability

Attributes of a OCCI base type instance, a resource instance, are either client mutable or client immutable. If an attribute is noted to be mutable this MUST be interpreted that a client can create a resource instance that is parameterised by the attribute. Likewise, if an attribute is mutable, a client can update that resource instance's mutable attribute value and the server side MUST support this. If an attribute is marked as immutable, it indicates that the server side implementation MUST manage these exclusively. Immutable attributes MUST NOT be modifiable by clients under any circumstance.

4.3 Type System

The Category type is the classification mechanism used by OCCI. This tells service providers what type of concrete OCCI Kind should be created. Each domain-specific section of the OCCI specification (e.g. infrastructure) defines its own concrete Resource, Action and optionally Link specialisations. It should be noted that depending on the clients credentials, access to creating certain OCCI Kind instances may be restricted.

The type system is a flexible and extensible one allowing for the addition of "mix-in" Category types. Mixin Category types are ones that add additional behaviour to OCCI Kinds and are Categories not defined by the OCCI specificatons. The mix-in Category types can be added to an OCCI Kind both at Kind creation time and runtime. The Kinds to which a particular mix-in Category type can be applied, is defined by the provider implementation. At which time, creation- or run-time, these mix-in types can be applied is also defined by the provider implementation. Discovery of mix-in types can be achieved by querying the OCCI Query interface. Mix-in Categories are those that are NOT related to an OCCI base type Category and MUST be implemented as such. When a client attempts to add a mix-in at a stage not supported by the provider, the provider MUST notify the client that it has issued a bad request.

4.3.1 Creating Instances

A client MUST supply the concrete Kind type as a Category. All OCCI implementations MUST understand these requests containing concrete Kind types, i.e. Resource, Link, Action or a subtype thereof.

4.4 Extensibility

The OCCI Core model has a flexible yet fairly simple extension mechanism through the use of subtyping and Categories.

4.4.1 Subtypes and Categories

A provider MAY extend the OCCI core model by creating a subtype of either an OCCI Core base type or a provider defined subtype.

A provider MUST assign a new unique Category to each new subtype defined. The new Category MUST be, either directly or indirectly, related to one of the Core base types, i.e. Resource, Link or Action. If a provider extends a subtype the new Category SHOULD be related to the subtype extended, provided the previous rule holds true.

Providers MAY also define new Categories for tagging and templating purposes. Such a Category MUST NOT be the unique identifier of a resource type, i.e. must not be part of the "static type system".

The scheme of provider-defined Categories MUST reside in a unique namespace different from those in the OCCI specification. Any attributes defined by a new Category MUST NOT have a name starting with occi. The occi namespace prefix is reserved for extensions which are standardized. A provider SHOULD use an attribute namespace comprising the reverse domain name as prefix to every attribute name.

A provider-defined Category identifying a custom subtype of Resource could be exemplified as follows. The term and scheme is defined by the provider. The related set MUST include a, direct or indirect (through a hierarchy), reference to the Resource base type category.

• term = custom_resource
• scheme = http://example.com/occi/resource#
• related = http://schemas.ogf.org/occi/core#resource

4.4.2 Extension of the base types

A provider MAY define subtypes of the Core base types Resource, Link and Action for domain-specific purposes. A unique Category MUST be assigned to each new subtype. The assigned Category MUST be directly related to the Category of the base type extended.

4.4.3 Extension of subtypes

A provider MAY define subtypes of any existing subtype, either defined in OCCI or by someone else. A unique Category MUST be assigned to each new subtype. The assigned Category MUST be either directly or indirectly related to a base type Category. It is RECOMMENDED the Category is related to the Category of the subtype extended.

4.5 Discovery

An OCCI client MUST be able to discover all Categories a particular provider supports before interacting with the provider. Since the rendering of the Categories is depended of the protocol the rendering documents give more information on how information is send and can be parsed.

5 Contributors

• Editors: Andy Edmonds, Thijs Metsch
• Contributors: Alexander Papaspyrou, Ralf Nyrén, Sam Johnston

6 Glossary

7 Intellectual Property Statement

The OGF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the OGF Secretariat.

The OGF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this recommendation. Please address the information to the OGF Executive Director.

8 Disclaimer

This document and the information contained herein is provided on an “As Is” basis and the OGF disclaims all warranties, express or implied, including but not limited to any warranty that the use of the information herein will not infringe any rights or any implied warranties of merchantability or fitness for a particular purpose.

9 Full Copyright Notice

Copyright (C) Open Grid Forum (2009-2010). All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the OGF or other organizations, except as needed for the purpose of developing Grid Recommendations in which case the procedures for copyrights defined in the OGF Document process must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by the OGF or its successors or assignees.

10 References

Note that only permanent documents should be cited as references. Other items, such as Web pages or working groups, should be cited inline (i.e., see the Open Grid Forum, http://www.ogf.org). References should conform to a standard such as used by IEEE/ACM, MLA, Chicago or similar. Include an author, year, title, publisher, place of publication. For online materials, also add a URL. It is acceptable to separate out “normative references,” as IETF documents typically do. Some sample citations:

Attachments:

core_model3.png [CoreAndModels/core_model3.png] core_model2.png [CoreAndModels/core_model2.png] occi-intro.graffle [CoreAndModels/occi-intro.graffle] occi-intro.png [CoreAndModels/occi-intro.png] core_model.png [CoreAndModels/core_model.png] occi.xmi [CoreAndModels/occi.xmi] occi.zuml [CoreAndModels/occi.zuml] occi-core.png [CoreAndModels/occi-core.png] core.jpg [CoreAndModels/core.jpg] diagram.png [CoreAndModels/diagram.png] ad6zqhvkzs9_36ftf4k9d2_b [CoreAndModels/ad6zqhvkzs9_36ftf4k9d2_b]