Cloud Application Management for Platforms Version 1.1
Cloud Application Management for Platforms Version 1.1
Working Draft 08
13 March 2013
Updated by Alex Heneveld for Issue 4 (PDP upload), 10 April 2013
WORK IN PROGRESS
PROPOSAL
NOTE: This includes a much simpler proposal for Issue 3. If that issue is resolved prior to this one, this document should be rebased around it. As of this writing (10 Apr) they are identical and issue 3 only changes section 4.1.
Changed Sections:
• 4.1 — Incorporate proposal for Issue 3
• 4.2 / 4.3 — PDP deployment plan schema
• 5.x — TODO add optional “fulfillment” upload and “id” attributes to Requirement
• 2.1 — TODO mention fulfillment, and discuss in the section on relationships
• 2.2/2.3 — TODO include example deployment plan, discuss resolution
Version History (of the draft/proposal related to this issue):
• ah-v1 — initial write-up based on github + F2F
• ah-ao-v1 — improvements to language and clarifications
• ah-v2 — wrap deployment plan as a type (PDP), expand text and tune examples as per discussion in 10 Apr call, create new proposal for Issue 3 text (section 4.1)
Questions:
• Do we need to describe subtyping (parentType or derivedFrom attribute)? (I think so.)
• Should Assembly(Template) be able refer to a Platform Component (Template)? Or multiple AC(T)’s? Currently not, but I think this would make sense e.g. in a PaaS which generates a new project in a git repo – no ACT need be supplied.
• How is the behavior of “Parameters” determined with respect to an AssemblyTemplate coming from a PDP? (One lightweight way we could do this is to allow “parameters” to be included in the DeploymentPlan, each saying what parameter is being exposed, what parameter is being set, and what resource (by “id”) it is being set on.)
• Should we rename “requirement” to “dependency”? (This seems slightly more appropriate and would permit optionality whilst avoiding the oxymoron of “optional requirements”. Particularly if we are removing “capabilities” which I think we should do.)
• Do we like the “pdp:!” syntax using in Content?
Technical Committee:
OASIS Cloud Application Management for Platforms (CAMP) TC)
Chair:
Martin Chapman (martin.chapman@), Oracle
Editors:
Jacques Durand (jdurand@us.), Fujitsu Limited
Anish Karmarkar (Anish.Karmarkar@), Oracle
Adrian Otto (adrian.otto@), Rackspace Hosting, Inc.
Additional artifacts:
This prose specification is one component of a Work Product which also includes:
XML schemas: (list file names or directory name)
Other parts (list titles and/or file names)
Related work:
This specification replaces or supersedes:
Cloud Application Management for Platforms, Version 1.0, August 29, 2012.
This specification is related to:
Related specifications (hyperlink, if available)
Abstract:
This document defines the artifacts and APIs that need to be offered by a Platform as a Service (PaaS) cloud to manage the building, running, administration, monitoring and patching of applications in the cloud. Its purpose is to enable interoperability among self-service interfaces to PaaS clouds by defining artifacts and formats that can be used with any conforming cloud and enable independent vendors to create tools and services that interact with any conforming cloud using the defined interfaces. Cloud vendors can use these interfaces to develop new PaaS offerings that will interact with independently developed tools and components.
Status:
This Working Draft (WD) has been produced by one or more TC Members; it has not yet been voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and re-approve it any number of times as a Committee Draft.
Copyright © OASIS Open 2012, 2013. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
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 section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, 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 OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Table of Contents
1 Introduction 10
1.1 Overview 10
1.2 Purpose 10
1.3 Example (Non-normative) 11
1.4 Non-Goals 12
1.5 PaaS Roles 12
1.6 Terminology 13
1.7 Specification Version 13
1.7.1 Backwards Compatibility 13
1.8 Normative References 13
1.9 Non-Normative References 13
2 Architecture 14
2.1 Management Model 14
2.1.1 PaaS Resource Model 15
2.1.1.1 Platform 15
2.1.1.2 Assemblies 15
2.1.1.3 Components 15
2.1.1.4 Capabilities and Requirements 15
2.1.2 Resource Relationships 16
2.1.3 Representation Skew 17
2.1.4 Management Model Diagrams 18
2.1.4.1 Basic Platform Resources 18
2.1.4.2 Resources Loaded 19
2.1.4.3 Instantiated Resources 19
2.2 Importing a Platform Deployment Package 21
2.3 Exporting a Platform Deployment Package 22
3 Application Lifecycle 23
3.1 Uploaded 23
3.2 Deployed 24
3.3 Instantiated 24
3.4 Suspended 24
4 Platform Deployment Package 25
4.1 PDP Package Structure 25
4.2 Deployment Plan 25
4.2.1 Content References 27
4.2.2 Requirements 27
4.2.2.1 Implicit Requirements 27
4.2.2.2 Explicit Requirements 28
4.2.2.3 Extending Requirements 28
4.2.3 Transitive Requirements, Component References, and Fulfillment 29
4.3 Deployment Plan Schema 29
4.3.1 General Specification Attributes 30
4.3.1.1 type 30
4.3.1.2 id 30
4.3.1.3 tag 30
4.3.2 DeploymentPlan 30
4.3.2.1 name Attribute 30
4.3.2.2 tags Attribute 30
4.3.2.3 specifications Attribute 31
4.3.3 Application Component Template Specification 31
4.3.3.1 content Attribute 31
4.3.3.2 requirements Attribute 31
4.3.4 AssemblyTemplate Specification 31
4.3.4.1 applicationComponentTemplates Attribute 31
4.3.5 Content Specification 31
4.3.5.1 href Attribute 32
4.3.5.2 data Attribute 32
4.3.6 Requirement Specification 32
4.3.7 PlatformComponentTemplate Specification 32
5 Resources 33
5.1 Common Types 33
5.1.1 Boolean 33
5.1.2 String 33
5.1.3 URI 33
5.1.4 Timestamp 33
5.1.5 Link 33
5.1.5.1 href 33
5.1.5.2 targetName 33
5.2 Attribute Constraints 33
5.2.1 Required 34
5.2.2 Mutable 34
5.2.3 Consumer-mutable 34
5.3 Common Resource Attributes 34
5.3.1 uri 34
5.3.2 name 34
5.3.3 description 34
5.3.4 created 34
5.3.5 tags 35
5.3.6 type 35
5.3.7 representationSkew 35
5.4 Error Response Message Resource 36
5.5 PlatformEndpoints Resource 37
5.5.1 paltformEndpoints 38
5.6 PlatformEndpoint Resource 38
5.6.1 specificationVersion 39
5.6.2 backwardCompatibleSpecificationVersions 39
5.6.3 implementationVersion 39
5.6.4 backwardCompatibleImplementationVersions 39
5.6.5 platformUri 40
5.7 Platform Resource 40
5.7.1 supportedFormatsUri 40
5.7.2 extensionsURI 40
5.7.3 typeDefinitionsURI 41
5.7.4 platformEndpointsURI 41
5.7.5 platformEndpointsURI 41
5.7.6 specificationVersion 41
5.7.7 implementationVersion 41
5.7.8 assemblyTemplates 41
5.7.9 assemblies 42
5.7.10 platformComponentTemplates 42
5.7.11 platformComponentCapabilities 42
5.7.12 platformComponents 42
5.8 AssemblyTemplate Resource 42
5.8.1 applicationComponentTemplates 43
5.9 ApplicationComponentTemplate Resource 43
5.9.1 assemblyTemplate 43
5.9.2 applicationComponentTemplates 44
5.9.3 platformComponentTemplates 44
5.9.4 applicationComponentRequirements 44
5.9.5 platformComponentRequirements 44
5.10 ApplicationComponentRequirement Resource 44
5.11 ApplicationComponentCapability Resource 45
5.12 PlatformComponentTemplate Resource 45
5.13 PlatformComponentRequirement Resource 45
5.14 PlatformComponentCapability Resource 46
5.15 Assembly Resource 46
5.15.1 applicationComponents 46
5.15.2 assemblyTemplate 46
5.15.3 resourceState 47
5.16 ApplicationComponent Resource 47
5.16.1 assembly 47
5.16.2 applicationComponents 47
5.16.3 platformComponents 47
5.17 PlatformComponent Resource 48
5.17.1 externalManagementResource 48
5.18 Format Resource 48
5.18.1 name 48
5.18.2 mimeType 49
5.18.3 version 49
5.18.4 documentation 49
5.18.5 Required JSON Format Resource 49
5.19 Formats Resource 49
5.19.1 formatLinks 50
5.20 TypeDefinitions Resource 50
5.20.1 typeDefinitionLinks 50
5.21 TypeDefinition Resource 50
5.21.1 name 51
5.21.2 documentation 51
5.21.3 attributeDefinitionLinks 51
5.22 AttributeDefinition Resource 51
5.22.1 name 51
5.22.2 documentation 52
5.22.3 attributeType 52
5.22.4 required 52
5.22.5 mutable 52
5.22.6 consumerMutable 52
6 Protocol 53
6.1 Transport Protocol 53
6.2 URI Space 53
6.3 Media Types 53
6.3.1 Required Formats 53
6.3.2 Supported Formats 53
6.4 Request Headers 53
6.5 Request Parameters 53
6.6 Response Headers 54
6.7 HTTP Status Codes 54
6.8 Mutability of Resource Attributes 54
6.9 Updating Resources 54
6.9.1 Updating with PUT 54
6.9.2 Updating with JSON Patch 54
6.10 Concurrent API versions 55
6.11 Registering a PDP 55
6.12 Instantiating an Application 55
6.13 Suspending and Resuming an Application 56
6.14 Deleting an Application Instance and a Deployed Application 56
7 Extensions 57
7.1 Unique Name Requirement 57
7.2 Extension Resource 58
7.2.1 version 58
7.2.2 documentation 59
7.3 Extensions Resource 59
7.3.1 extensionLinks 59
7.4 Extending Existing Resources 59
8 Conformance 61
Appendix A. Acknowledgments 62
Appendix B. Glossary 63
Appendix C. Use Cases (Non-Normative) 65
C.1 Building the Application 65
C.1.1 Build Application and Package 65
C.1.2 Build Application in the Cloud and Optionally Package 66
C.2 Deploying and Managing the Application 67
C.2.1 Import Platform Deployment Package 68
C.2.2 Upload Application 68
C.2.3 Run/Stop/Suspend/Snapshot 69
C.2.4 Patch an Application Component Template 69
C.2.5 Patch a Created, Deployed or Running Application 69
Appendix D. Example Database Platform Component (Non-Normative) 70
D.1 Model 70
D.2 DatabaseCapability 70
D.2.1 clusterTypes 71
D.2.2 maxNumberNodes 71
D.2.3 maxCores 71
D.2.4 maxMemSize 71
D.2.5 maxDiskSize 72
D.2.6 backupAvailable 72
D.2.7 synchronousCopyAvailable 72
D.2.8 partitionAvailable 72
D.2.9 compressionAvailable 72
D.2.10 retentionAvailable 72
D.2.11 tunings 73
D.2.12 cachingAvailable 73
D.3 DatabaseRequirement 73
D.3.1 clusterTypes 73
D.3.2 numberNodesRange 74
D.3.3 coreRange 74
D.3.4 memSizeRange 74
D.3.5 diskSizeRange 74
D.3.6 backupEnabled 74
D.3.7 synchronousCopyEnabled 74
D.3.8 partitionEnabled 75
D.3.9 compressionEnabled 75
D.3.10 retentionEnabled 75
D.3.11 tunings 75
D.3.12 cachingEnabled 75
D.4 DatabaseTemplate 75
D.4.1 clusterType 76
D.4.2 numberNodes 76
D.4.3 cores 76
D.4.4 memSize 76
D.4.5 diskSize 77
D.4.6 backupEnabled 77
D.4.7 synchronousCopyEnabled 77
D.4.8 partitionEnabled 77
D.4.9 compressionEnabled 77
D.4.10 retentionEnabled 77
D.4.11 tuning 78
D.4.12 cachingEnabled 78
D.5 Database 78
D.5.1 externalManagementResource 78
D.5.2 clusterType 79
D.5.3 numberNodes 79
D.5.4 cores 79
D.5.5 memSize 79
D.5.6 diskSize 79
D.5.7 backupEnabled 79
D.5.8 synchronousCopyEnabled 79
D.5.9 partitionEnabled 80
D.5.10 compressionEnabled 80
D.5.11 retentionEnabled 80
D.5.12 tuning 80
D.5.13 cachingEnabled 80
D.5.14 operationsThroughput 80
D.5.15 operationsBandwidth 80
D.5.16 resourceState 81
Appendix E. Implementation Considerations (Non-Normative) 82
E.1 Types of Platform Deployments 82
E.2 Scaling 83
Appendix F. Revision History 84
Introduction
1 Overview
Platform as a Service (PaaS) is a term that refers to a type of cloud computing in which the service provider offers customers/consumers access to one or more instances of a running application computing platform or application service stack. NIST defines PaaS [SP800-145] as a “service model” with the following characteristics:
The capability provided to the consumer is to deploy onto the cloud infrastructure consumer-created or acquired applications created using programming languages and tools supported by the provider. The consumer does not manage or control the underlying cloud infrastructure including network, servers, operating systems, or storage, but has control over the deployed applications and possibly application hosting environment configurations.
There are multiple commercial PaaS offerings in existence using languages such as Java, Python and Ruby and frameworks such as Spring and Rails. Although these offerings differ in such aspects as programming languages, application frameworks, etc., there are inherent similarities in the way they manage the lifecycle of the applications that are targeted for, and deployed upon them. The core proposition of this specification is that these similarities can be leveraged to produce a generic application and platform management API that is language, framework, and platform neutral.
For PaaS consumers this management API would have the following benefits:
• “Portability between clouds” is emerging as one of the primary concerns of cloud computing. By standardizing the management API for the use cases around deploying, stopping, starting, and updating applications, this specification increases consumers’ ability to port their applications between PaaS offerings.
• It is likely that implementations of this specification will appear as plugins for application development environments (ADEs) and application management systems. Past experience has shown that, over time, such generic implementations are likely to receive more attention and be of higher quality than the implementations written for solitary, proprietary application management interfaces.
For PaaS providers this management API would have the following benefits:
• Because the strength and features of a PaaS offering’s application management API are unlikely to be perceived as key differentiators from other PaaS offerings, the existence of a consensus management API allows providers to leverage the experience and insight of the specification’s contributors and invest their design resources in other, more valuable areas.
• By increasing the portability of applications between PaaS offerings, this management API helps “grow the pie” of the PaaS marketplace by addressing one of the key pain points for PaaS consumers.
2 Purpose
This document defines the artifacts and APIs that need to be offered by a Platform as a Service (PaaS) cloud to manage the building, running, administration, monitoring and patching of applications in the cloud. Its purpose is to enable interoperability among self-service interfaces to PaaS clouds by defining artifacts and formats that can be used with any conforming cloud and enable independent vendors to create tools and services that interact with any conforming cloud using the defined interfaces. Cloud vendors can use these interfaces to develop new PaaS offerings that will interact with independently developed tools and components.
The following is a non-exhaustive list of the use cases which are supported by this specification. Details of these use cases can be found in Appendix C.
• Building and packaging an application in a local Application Development Environment (ADE)
• Building an application in an ADE running in the cloud
• Importing a Platform Deployment Package into the cloud
• Uploading application artifacts into the cloud
• Run, stop, suspend, snapshot, and patch an application
3 Example (Non-normative)
This example illustrates a scenario in which the application administrator wants to run and monitor an application. It assumes that the application package was previously made available to the platform, either because it was uploaded to the platform or developed directly on the platform.
The administrator starts by deploying the application package to the platform. This is done by sending an HTTP POST request to the platform entry point URL as shown below, where "/myPaaS" is the entry point and "/myPaas/pkgs/1" is the location of the application package.
POST /myPaaS HTTP/1.1
Host:
Content-Type: application/json
Content-Length: ...
{
"pdp_uri": "/myPaaS/pkgs/1"
}
On receiving such a request the platform deploys the application package and creates a new resource "/myPaas/templates/1" that represents the deployed application. The response from the platform is show below.
HTTP/1.1 201 Created
Location: .org/myPaaS/templates/1
Content-Type: ...
Content-Length: ...
...
Once the application is deployed, the administrator starts the application by sending an HTTP POST request to the resource that represents the deployed application, which was obtained in the previous step ("/myPaaS/templates/1").
POST /myPaaS/templates/1 HTTP/1.1
Host:
On successful start the platform creates a new resource representing the running application and provides the URL of that resource "/myPaaS/apps/1" in the response as show below.
HTTP/1.1 201 Created
Location: .org/myPaaS/apps/1
Content-Type: ...
Content-Length: ...
...
The administrator can now monitor the running application by sending an HTTP GET request to the resource that represents the running application, which was obtained in the previous step ("/myPaas/apps/1").
GET /myPaaS/apps/1 HTTP/1.1
Host:
The response contains the JSON representation of the running application as shown below.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...
{
"uri": "",
"name": "Hello Cloud App",
"type": "assembly",
"description": "Hello Cloud Application Running in a PaaS Env",
"created": "2012-06-04T20:47Z",
"applicationComponents": [
{
"href": "/myPaaS/apps/1/acs/1", "targetName": "appComp1"
},
{
"href": "myPaaS/apps/1/acs/2", "targetName:: "appComp2"
}
],
"platformComponents": [
{
"href": "/myPaaS/pcs/1", "targetName": "dbPlatComp"
},
{
"href": "myPaaS/pcs/2", "targetName": "msgBusPlatComp"
}
],
"assemblyTemplate": "/myPaaS/templates/1",
"resourceState": {
"state": "RUNNING"
}
}
4 Non-Goals
The specification of functional interfaces specific to services provided by individual components (see Application Components and Platform Components, below) is out of scope for this document. This is because such interfaces may be quite diverse and differ significantly from platform to platform.
5 PaaS Roles
There are many roles that can be defined for a PaaS environment. For the purposes of this specification we identify four roles:
Application Developer: The person that builds and tests an application and presents the developed artifacts for deployment.
Application Administrator: The person that deploys applications and manages the application throughout its life-cycle.
Together these two roles make up the consumers of the management API described in this specification. This specification is intended mainly for Application Administrators, though it does constraint the artifacts that an Application Developer presents for deployment.
Platform Administrator: The person that manages the platform. This specification describes some of the functions of a Platform Administrator, though most of the functions of this role are outside its scope.
Application End-User: A user of an application deployed on the platform. The interactions of the Application end-user and the application are outside the scope of this specification.
Extension Developer: The person who creates new Extensions for Platforms.
6 Terminology
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 [RFC2119].
Only the lower case versions of these keywords are used in this document in accordance with RFC 2119 in order to conform to ISO document requirements.
All text except examples, unless otherwise labeled, is normative. All examples are non-normative.
7 Specification Version
Each version of a CAMP specification is identified by a unique string termed the “Specification Version String”. The Specification Version String for this specification is “CAMP 1.1”.
1 Backwards Compatibility
This version of the CAMP specification is not backwards compatible with any previous version of the CAMP specification.
8 Normative References
[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. .
[RFC2616] R. Fielding et al, “Hypertext Transfer Protcol – HTTP/1.1”, IETF RFC 2616, June 1999.
[RFC2617] J. Franks et al, “HTTP Authentication: Basic and Digest Access Authentication”, IETF RFC 2617, June 1999.
[RFC 3986] T.Berners-Lee et al, “Uniform Resource Identifiers (URI): Generic Syntax”, IETF RFC 3986, August 1998.
[RFC4346] T. Dierks, E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2”, IETF RFC 4346, April 2006.
[RFC4627] D. Crockford, “The application/json Media Type for JavaScript Object Notation (JSON)”, IETF RFC 4627, July 2006.
[RFC5246] T. Dierks, E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2”, IETF RFC 5246, August 2008.
[RFC5789] L. Dusseault, Linden Lab, J. Snell, “PATCH Method for HTTP”, IETF RFC 5789, March 2010.
[JSON Patch] P. Bryan, M. Nottingham, “JSON Patch”, IETF Draft, January 2013.
[ISO 8601:20044] International Organization for Standardization, Geneva, Switzerland, “Data elements and interchange formats -- Information interchange - - Representation of dates and times”, March 2008. catalogue_tc/catalogue_detail.htm?csnumber=40874
9 Non-Normative References
[SP800-145] Peter Mell, Timothy Grance, “The NIST Definition of Cloud Computing”, Special Publication 800-145, September 2011.
[OVF] Distributed Management Task Force, “Open Virtualization Format Specification”, DSP0243, 12 January 2010.
[Git] The Software Freedom Conservancy, “Git, the fast version control system”, March 2012.
Architecture
1 Management Model
This document specifies the self-service management API that a Platform as a Service offering presents to the consumer of the platform. The API is typically the interface into a platform implementation layer that controls the deployment of applications and their use of the platform.
[pic]
Figure 1 - Typical PaaS Architecture
The figure above shows a typical architecture of a Platform as a Service cloud. The platform implementation is a management client of the underlying resources that transforms (through policies) the application requirements expressed by the Application Administrator into provisioning and other operations on those resources. The Platform Administrator manages the underlying hardware, storage, networks, and software services that make up the platform through existing administrative interfaces. Thus the Application Administrator is able to concentrate on their application and it’s deployment environment rather than having to be a systems administrator, database administrator and middleware administrator as well (as is the case with IaaS).
The goal of the management interface is to provide the PaaS consumer with a model that is as simple as possible, and yet still provides the essential elements that give them control over the deployment, execution, administration and metering of their application and it’s deployment environment.
1 PaaS Resource Model
The model of resources manipulated through the interface, in combination with the protocol used to remotely accomplish this, constitutes the self-service PaaS management API. The model contains resource types corresponding to the artifacts discussed earlier.
1 Platform
The Platform resource is the primary view of the platform and what is running on it. The Platform references deployed applications (as Assembly Templates) as well as running applications (as Assemblies) and enables discovery of the PaaS offering in terms of Platform Components and their capabilities. The Platform also determines the scope of access for sharing amongst multiple applications.
2 Assemblies
The Assembly Template resource represents a deployed application and its dependencies on the platform and other application components.
The Assembly resource represents a running application. Operations on an Assembly affect the components and elements of that application.
3 Components
There are two kinds of components, application components and platform components, each of which may exist in either template or instantiated forms.
The Application Component Template resource represents a discrete configuration of a deployed application component. The attributes of this resource represent the configuration values that will be applied to the component upon instantiation.
The Application Component resource represents an instantiated instance of an application component.
The Platform Component Template resource represents a discrete configuration of a platform component. The attributes of this resource represent the configuration values that will be applied to the component upon instantiation.
The Platform Component resource represents an instantiated instance of a platform component in use by an application. In addition to the configuration metadata (derived from the corresponding Platform Component Template on instantiation), the attributes of this resource also include metering information for this component. Such information is typically used in generating the consumer’s bill.
4 Capabilities and Requirements
Like Templates, Capability resources represent the configuration of instantiatable Components (Application Components or Platform Components). Unlike Templates, which delineate discrete configurations, Capabilities specify ranges of configuration values.
Requirement resources are created by the Application Developer or Application Administrator to express an application’s dependency on a component that is capable of satisfying a certain set of requirements. For example, an application component may depend upon a messaging service that supports a certain version of an AMQP API, can accept messages of up to 2MB in size, and which provides a persistent message store.
The process of matching Requirements with Capabilities is referred to as “requirement resolution”.
2 Resource Relationships
A Platform provides a set of Platform Components that may be used by the invoking applications. Examples of Platform Components include a servlet container, a web server, an LDAP store, and a database instance. The implementation and operation of Platform Components is managed by the Platform Administrator. Platforms may also provide higher-level business components such as a business rules manager to gain competitive advantage and developer loyalty.
An application is composed of a set of Application Components that depend on one or more Platform Components. Examples of Application Components include Ruby gems, Java libraries, and PHP modules. Application Components may also include non-code artifacts such as datasets and collections of identity information.
Application Components may also interact with other Application Components. Thus, an Application Component has two different sets of dependencies. It depends on the Components provided by the platform, and depends on services provided by other Application Components. Such Application Components may be on the same platform or may reside at some other location. The Assembly resource is used to aggregate the management of these components as shown below:
[pic]
Figure 2 - Runtime Management Resources
Platform Components have a set of Platform Component Capabilities that an application can choose from to meet its requirements. Applications can tailor Platform Component Requirements (a refinement or narrowing of the configuration ranges in the Capabilities) to meet their needs based on the range of parameters expressed in the Platform Component Capability.
The relationships of an Assembly Template to Application Component Templates and Platform Component Templates, or their Requirements are shown below:
[pic]
Figure 3 - Template Management Resources
An Application Component can express the exact configuration of its dependency on other Components using one of the Component Template resources (either an Application Component Template or Platform Component Template). Alternatively, it can express a range of configuration values that are acceptable for that dependency by using one of the Component Requirement resources (either an Application Component Requirement or Platform Component Requirement). This might be done, for example, in an ADE when the existing Component Templates are not known. During the deployment, these Requirements are matched with Capabilities that have attribute values that fall within the ranges specified by the Requirements.
An Application Component Template cannot be instantiated unless all of its dependencies are satisfied. An Application Component Template shall be referenced by a single Assembly Template. An Assembly Template shall not be instantiated until all of its Application Component Templates are successfully instantiated.
When instantiated, an Assembly Template results in an Assembly. The Assembly resource references the Assembly Template it was instantiated from, although attributes of the Assembly can deviate from the original template. An Assembly can be snapshot at a point in time and the resulting snapshot can be used to create a new Assembly Template.
A Deployment Plan is packaging management meta-data that includes a serialized copy of the Assembly Template resource and all dependent management resources such as Application Component Templates. Deployment Plans are an essential part of a Platform Deployment Package (PDP).
A Platform Deployment Package is an archive of executable images, dependency descriptions and metadata (management resources) that can be used to move an Application and its Components from Platform to Platform, or between an Application Development Environment and a Platform. It can be thought of as a serialized form of an Assembly Template and all of its dependent management resources.
3 Representation Skew
There can be situations in which the information in the resources provided by the CAMP API is not a complete or accurate representation of the state of the underlying platform implementation. For example, while instantiating a new instance of an application, a CAMP server might be asked to provide a representation of an Application Component that corresponds to a dataset that is in the process of being loaded onto a database service. While the CAMP server might not be able to provide all of the information about this Application Component, it would be inaccurate to say that Application Component does not exist; it exists but it an intermediate state. It is expected that these sorts of situations will be the exception and that, during the majority of its existence, a CAMP resource will be in synch with the state of its underlying platform implementation.
The significance of this skew is the manner in which it affects the client’s interactions with, and expectations about, the resource. In the above example, while the client cannot reasonably expect to make any changes to the Application Component until it has reached a steady state, the client can expect that the resource will reach this state in the near future. There are other situations in which, through some sort of error or breakdown, the CAMP API cannot tell when or if the information in the resource will ever be synchronized with the underlying implementation.
Details on how this skew is exposed in the CAMP API are provided in the ResourceSkew section of the Common Resource Attributes of this specification.specification.
4 Management Model Diagrams
The figures in this section list attributes for various management resources. The attributes listed here are not exhaustive. For a comprehensive list of attributes for resources see Section 5.
1 Basic Platform Resources
The CAMP model includes the resources below when no Assemblies have been created.
[pic]
Figure 4 - Basic Platform Resources
An empty Platform will have a number of resources visible through the API when the Application Administrator first accesses a new account. The Platform resource is used to find the other resources in this diagram. The various Platform Component Capabilities allow for discovery of all the platform services that are available with value ranges for each service’s attributes. The various Platform Component Templates may represent pools of previously configured platform resources and represent this configuration as specific values for each of the attributes. These values are chosen from the range of values in the corresponding Platform Component Capability.
2 Resources Loaded
After loading a PDP, the model may appear as follows:
[pic]
Figure 5 - Loaded Resources
An Assembly Template now is available with one or more Application Component Templates, Application Component Requirements and Platform Component Requirements. The Application Component Template management resources represent code and/or associated resources that were loaded with the PDP. The Application Component Requirement resources were used to find Application Component Templates (pre-existing software libraries for example) that were not part of the deployment plan but are required for the application. The Application Component Capability resources show the range of configurable attributes that the loaded Application Components can take on, when reused by future Application Components.
The Platform Component Requirement resources were used to find Platform Component Templates (pre-configured platform resources) that were part of the platform and required by the loaded Application Components, but perhaps unknown at the time the deployment plan was created (in an ADE for example).
3 Instantiated Resources
To start an application utilizing all of the previously configured Application Components and Platform Components, an Assembly is created using the Assembly Template. This also causes the Application Components and Platform Components corresponding to their respective templates to be created as shown below.
[pic]
Figure 6 - Instantiated Resources
To manage the operation of the application, the Application Administrator interacts with the Assembly resource and the related Application Component and Platform Component resources.
The traversal of the resources in the model can be accomplished by following arrays of URIs from each resource to the other resources it depends on as shown by the red arrows in the figure below:
[pic]
Figure 7 - Traversing Resources
2 Importing a Platform Deployment Package
A Platform Deployment Package may be imported into the platform and as a result the following takes place:
1. One or more Assembly Templates are created with URIs to the other elements and with any binary executables installed onto the platform.
2. One or more Application Component Templates are created with URIs to the other elements and with and binary executables installed onto the platform.
3. Zero or more Platform Component Requirements are created, representing the requirements on the underlying platform components. Connections may be made to existing Platform Component Templates whose attribute values fall within the ranges specified by the requirements.
4. Zero or more Application Component Requirements are created, representing the requirements on previously installed Application Components. Connections may be made to existing Application Component Templates whose attribute values fall within the ranges specified by the requirements.
3 Exporting a Platform Deployment Package
A Platform Deployment Package may be exported from the platform by an operation on an Assembly or an Assembly Template. The Assembly (Assembly Template), dependent Application Components (Application Component Templates) and Platform Components (Platform Component Templates) and associated Capabilities Requirements, if any, as well as all related images are then used to create the Deployment Plan and Platform Deployment Package. A URI to the Platform Deployment Package is returned as a result.
Application Lifecycle
The following state diagram depicts lifecycle of an Application from the perspective of the PaaS Management API.
[pic]
Figure 8 - Application Lifecycle
The following sections describe this diagram. It is important to note:
• The states and transitions shown in this diagram are abstract and do not necessarily correspond in a one-to-one fashion with any specific information or activities maintained or performed by either the Consumer or the Provider.
• The entities that define “the Application” vary between states. For example, in the “Deployed” state, the Application is represented by the graph of entities rooted in an Assembly Template. In in the “Instantiated” state, the Application is represented by the graph of entities rooted in an Assembly.
• Platform-specific environments might add to or extend this lifecycle to accommodate the needs of a particular framework or language. Such extensions are outside the scope of this specification.
1 Uploaded
While the development of Applications and their components is outside the scope of this specification, nonetheless it is recognized that such development may occur either within the PaaS environment itself, or externally (i.e. on the Application Developer’s local machine). In the latter case, the executable images, and Deployment Plan, and other metadata that make up the Application shall be imported into the platform in the form of a PDP. Because the PDP represents a significant interoperability point, the Uploaded state exists to depict the upload package transition. During this transition the PDP is un-archived, validated, and parsed (not necessarily in that order). Invalid PDPs will cause the upload package transition to fail. Once uploaded, the Application/PDP may be persisted in some fashion outside the scope of this specification. The invocation of the register transition may occur either automatically or via some unspecified action on the part of the Application Administrator.
2 Deployed
The Application enters the Deployed state via one of the register transitions. During these transitions the Deployment Plan is parsed and validated and the corresponding Assembly Template, Application Component Templates, Application Component Requirements, etc. are created as addressable entities in the Platform. The register transition also encompasses the process of dependency resolution in which Platform Component Requirements and Application Component Requirements are matched (respectively) against candidate Platform Component Templates and Application Component Templates. Note this process may require interaction with the Consumer. If the required dependencies are not resolved or if the metadata is incomplete, the register transition shall not happen.
Once deployed, an Application may be customized by the Application Administrator. This is represented by the customize transition. Customization may include changes to configuration parameters, modifying dependencies, etc. Application Administrators may elect to copy or create new Assembly Templates – effectively creating a new Application.
Deployed Applications may be removed as represented by the delete transition. Deleting an Application removes its Assembly Template, Application Component Template, Platform Component Requirement, and Application Component Requirement entities.
3 Instantiated
The Instantiated state represents a running Application. The management entity for an Application in this state is the Assembly. The Assembly and its graph of dependent Application Components and Platform Components are created upon entry to this state via the instantiate transition and removed during the delete instance transition.
4 Suspended
The optional Suspended state represents an Application that has been suspended. During this state the Application is unavailable to its clients and does not process any requests. This specification does not specify whether the suspension is done at full scale with all its existing resources allocated, or scaled back with minimum resources necessary to preserve its runtime context, or something in between. An implementation can specify scale at which suspension is done or allow clients to specify the scale of suspension via extensions. The scale at which the suspension is done affects resource utilization and therefore cost during the suspension phase. It also affects the time it takes to resume processing client requests at roughly the same rate as before suspension.
Note the delete instance transition has the same effect as the delete instance transition for an Instantiated Application.
Platform Deployment Package
The Platform Deployment Package (PDP) defines the file format for onboarding new applications into a CAMP system. It may be generated by an Application Development Environment, by a human, or by an export from another Platform instance. The platform SHALL respond to a valid PDP POSTed to a Platform URI by creating an AssemblyTemplate which can subsequently be used to instantiate new Assemblies.
1 PDP Package Structure
A PDP file shall be a ZIP archive containing the following files:
• Exactly one deployment plan file called “camp.json” located in the root of the archive, comprised of valid JSON with a schema as defined subsequently in this section
• Zero or more metadata files such as manifests, checksums, signatures and certificates
• Zero or more application content files such as a web archives, database schemas, installation scripts, localization bundles and icons
Implementations may impose their own archive validation mechanisms. To facilitate PDP portability, it is recommended that any such mechanism be designed with consideration for common conventions and other schemes.
2 Deployment Plan
The deployment plan provides the instructions to a CAMP implementation for assembling an application, resolved at the server in the form of an Assembly Template. The deployment plan MAY supply the name and tags for the Assembly Template as attributes and MUST supply a set of Specification objects in the “specifications” attribute. These Specification objects — of types including Application Component Template Specification and Requirements Specification — indicate what should populate the Assembly Template and how they are related.
In practice, the deployment plan will reference subtypes of Component Templates and/or Requirements. The CAMP specification does not define these subtypes, nor does it define the contract or attributes thereof, nor does it define how the logic should be implemented at a platform for selecting and provisioning components in accordance thereto. However, to ensure portability, providers of these subtypes SHOULD co-ordinate the semantics and behavior of such types or use uniquely namespaced types. It is noted that the use of typed Requirements or more general Component types in Specifications is likely to be more portable than the use of more specialized or product-specific Component Template subtypes.
Examples are included to illustrate ways that the Deployment Plan can be specified. Note that these examples are both non-normative and fictitious, and that they make implicit assumptions about the behavior of referenced imaginary types.
After some initial examples below, this section describes the key concepts behind them and builds up to more complex examples, including multiple specifications and references. The next section gives a formal schema for all Specification types introduced here.
Example: A Deployment Plan using a typed Requirement Specification to indicate that the application consists of a WAR file from the PDP ZIP running in two containers on Java 7 or higher (where the containers might be part of a PaaS or might be appservers on two newly created VM’s)
{
"name": "Hello WebApp Cluster",
"specifications": [ {
"content": { "href": "hello.war" },
"requirements": [ {
"type": "com.example.java:WarDeploymentRequirement",
"javaVersion": "[1.7,)",
"initialSize": 2
} ]
} ]
}
Example: A Deployment Plan using a typed Application Component Template Specification to indicate that the application consists of an RPM (external) installed to a machine
{
"specifications": [ {
"type": "com.example:RPM",
"content": { "" }
} ]
}
Example: A Deployment Plan using a typed Requirement Specification to indicate that the application consists of the PDP ZIP re-interpreted as an OASIS TOSCA Cloud Service Archive v1 and deployed accordingly
{
"specifications": [ {
"content": { "href": "pdp:!" },
"requirements": [ {
"type": "com.example.tosca:CsarDeploymentRequirement",
} ],
"csar-version": "1.0"
} ]
}
Example: A Deployment Plan using a transitive Requirement Specification to indicate that the application consists of an appserver (potentially clustered or PaaS) running a WAR and a database (potentially a service) with SQL executed, wired together using a defined “CDI” mode
{
"name": "Hello WebApp Cluster with Database",
"specifications": [ {
"content": { "href": "hello.war" },
"requirements": [ {
"type": "com.example.java:WarDeploymentRequirement",
"fulfillment": "id:appserver"
} ]
}, {
"content": { "href": "hello.sql" },
"requirements": [ {
"type": "com.example.java:InitializeDatabaseSqlRequirement",
"fulfillment": "id:database"
} ]
}, {
"id": "appserver",
"requirements": [ {
"type": "com.example.java:InjectDatabaseJdbcUrlRequirement",
"injectionMode": "CDI",
"fulfillment": "id:database"
} ]
} ]
}
1 Content References
Deployoment Plans commonly include a Specification for an Application Component Template which refers to one or more files. Where a Specification object has a unique file or piece of data associated with it, that object SHOULD reference that content referenced using a “content” attribute of type Content Specification. Content specifications MUST declare either a String attribute “data” containing the data or String attribute “href” pointing to the content, but not both, as shown in the example in the previous section.
Where “href” is supplied on a Content Specification, its value SHALL be interpreted as follows:
• URI’s including protocols “http” and “https” are interpreted in accordance with RFC-3986. A platform MAY support protocols beyond the list given.
• URL’s with the special protocol “pdp:” are interpreted as files contained in the PDP.
o If the path segment (after the “pdp:”) begins with a “/” it is an absolute path.
o If the path segment is “!” (i.e. the URL is “pdp:!”), the reference is to the PDP archive itself. This is useful to make an existing deployment package (such as a WAR) function as a PDP.
o For any other path segment, the path is relative to the location of the file where the Content reference is contained inside the PDP, subject to the guidelines below.
o Where the path segment contains the special character “!”, it is treated as a delimiter to look for the path to the right of “!” inside the archive at the path to the left of the “!". The platform MUST understand this delimiter and NOT resolve any content if the archive format is unsupported. For example “pdp:/certs.zip!/id_rsa.pub” refers to a file “id_rsa.pub” contained at the root of a “certs.zip” file located at the root of the PDP, and is valid only on platforms which support the ZIP format in conjunction with “!”. On other platforms the link will not be resolved.
• Where the value is not a URI, it is interpreted as a “pdp:” protocol link, as though it were preceded by “pdp:”.
The examples in the previous section illustrate a variety of these reference mechanisms.
2 Requirements
In most cases, the application component(s) supplied in the PDP will require corresponding platform components to run, which may in turn require additional components or configuration. There are three general ways that requirements are declared.
The mechanics of resolving requirements is not specified by the CAMP specification.
1 Implicit Requirements
Requirements MAY be imposed by subtypes of Application Component Template in a platform implementation, in which case they need not be declared in the deployment plan. This is illustrated in the RPM example above and in an alternative WAR example below.
Example: A Deployment Plan using a typed Application Component Template Specification defining an implicit requirement, indicating that the application consists of a WAR file deployed to a container (which might be part of a PaaS or might be an appserver on a newly created VM)
{
"name": "Hello WebApp",
"specifications": [ {
"type": "com.example.java:WAR",
"content": { "href": "hello.war" }
} ]
}
2 Explicit Requirements
Requirements MAY also be supplied as a list of Requirement Specifications on the “requirements” attribute of a Component Template Specification in a Deployment Plan. Each Requirement Specification typically includes a “type” attribute indicating a Requirement type which if supplied MUST known at the platform and one or more additional attributes understood by the Requirement type. Minimally it SHOULD contain either the “type” attribute or at least one additional attribute, otherwise the Requirement is pointless as it requires nothing.
The platform MUST respect all supplied requirements and attributes therein whenever instantiating the components.
Example: A Deployment Plan using multiple typed explicit Requirement Specifications to indicate that the application consists of a script inside a tarball to be executed on a new Ubuntu box
{
"name": "MyScript",
"specifications": [ {
"content": { "href": "my-app-tarball.tgz" },
"requirements": [ {
"type": "com.example.scripts:ExecuteArchiveRequirement",
"archiveFormat": "tgz",
"script": "./start.sh"
}, {
"type": "com.example.machines:NewMachineRequirement",
"minRam": "4096M",
"osFamily": "ubuntu"
} ]
}
}
3 Extending Requirements
The platform SHALL also permit an implicit requirement imposed by a Component Template to be modified by a Requirement Specification by declaring an “extends” attribute, provided that the implicit requirement declares an “id” attribute whose value is unique in that Component Template, and provided that this value is supplied as the value of the Requirement Specification’s “extends” attribute. Such an extending requirement SHALL be treated as though the implicit requirement were not present and a single new Requirement Specification were supplied containing the combination of the attributes from the implicit requirement and the attributes declared in the extending requirement, with attributes present in both taking their value from the extending requirement. The extending requirement SHOULD specify at least one additional attribute, otherwise it is pointless as it is identical to the original implicit requirement.
The platform MUST respect all such requirements and attributes therein whenever instantiating the components.
Example: A Deployment Plan using a Requirement Specification extending an implicit requirement from the WAR Component Template to indicate that the application consists of a WAR file deployed to two containers on Java 7 and a further explicit requirement indicating a server name
{
"name": "WebApp Cluster by extending a requirement",
"specifications": [ {
"type": "com.example.java:WAR",
"content": { "href": "pdp:!" },
"requirements": [ {
"extends": "appserver",
"javaVersion": "[1.7,)",
"initialSize": 2
}, {
"type": "com.example.java:ServerNameRequirement",
"serverName": "my."
} ]
}
]
3 Transitive Requirements, Component References, and Fulfillment
In some cases it is appropriate to declare requirements on a Component Template which the platform selects to fulfill the requirements on another Component Template Specification. CAMP implementations SHALL support such transitive requirements by recognizing a “fulfillment” attribute within a Requirement Specification. This attribute MUST supply a list of objects each of which is either:
• A String value referencing a Component Specification provided in the deployment plan, consisting of the the prefix “id:” concatenated with the “id” attribute of the referenced specification. The reference MUST be unique within the scope of the deployment plan.
• A valid Component Specification as a JSON associative array
• Compliant with an OPTIONAL extension format advertised by the platform
A Component Template Specification supplied thusly MAY specify a “type” and MAY specify one or more Requirements Specifications in its “requirements” attribute. The platform MUST fulfill the requirement with a Component Template of the specified type or a subtype, if a type is specified, and the Component Template MUST conform to all requirements imposed on it. Where multiple Requirement Specifications indicate fulfillment by the same “id”, the platform MUST use the same Component Template.
Example: A Deployment Plan using a transitive requirement to indicate that the application consists of a WAR file deployed to two containers on Java 7 (as before but specified differently)
{
"name": "WebApp Cluster defined transitivtely",
"specifications": [ {
"type": "com.example.java:WAR",
"content": { "href": "pdp:!" },
"requirements": [ {
"extends": "appserver",
"fulfillment": [ "id:the-appserver-container" ]
} ]
}, {
"type": "com.example.java:JeePaasContainer",
"id": "the-appserver-container",
"requirements": [ {
"type": "com.example.java:AppServerSizingRequirement",
"javaVersion": "[1.7,)",
"initialSize": 2
} ]
}
}
TODO one more example, more complex and from a different domain
3 Deployment Plan Schema
The deployment plan file “camp.json” located at the root of the PDP archive shall consist of a well-formed JSON list containing associative arrays in accordance with the schemas set forth in this section.
The following subsection formally define the types and their schemas which may be used within the deployment plan.
1 General Specification Attributes
1 type
Type: String
Required: false unless otherwise indicated
This attribute indicates the expected type at the server of a Specification object.
This attribute MAY be omitted in the common case where the type can be correctly inferred from its context and requirements. Where the type cannot be inferred, or where a specific subtype is being specified, this attribute MUST be specified and its value MUST be consistent with any and all restrictions on the object being specified. Where this attribute is supplied in a Specification, the object at the server corresponding to the containing Specification MUST be of the type specified or of a type derived from the specified type.
2 id
Type: String
Required: false
TODO
ID is deploy-time only
3 tag
TODO
tag is passed on
2 DeploymentPlan
This type defines the structure of the deployment plan supplied with the PDP. The PDP MUST contain a file “camp.json” which is compliant with this type. A DeploymentPlan MUST NOT contain any other objects of this type.
1 name Attribute
TODO
optional
The platform MUST always set the value for the “name” attribute on the resulting AssemblyTemplate equal to the value of this attribute if this attribute is supplied. Note that the “name” attribute is required in AssemblyTemplate so the platform MUST choose a value for it on the AssemblyTemplate if this attribute is not supplied in the DeploymentPlan.
2 tags Attribute
TODO
MUST include all indicated tags
3 specifications Attribute
TODO
MUST respect all the specifications when instantiating an AssemblyTemplate and when instantiating an Assembly
The order of Specifications SHALL NOT be significant
3 Application Component Template Specification
Deployment plans typically contain at least one Application Component Template Specification. The set of these components defines the application through their requirements, either explicit (listed in the object against the “requirements” attribute) or implicit (defined by the type in the platform).
The “type” attribute MAY be included, referring to a type in the platform derived from ApplicationComponentTemplate where specific instructions for instantiating an Application Component are defined. These instructions may include a definition of a set of requirements, optionally with an id attribute permitting them to be refined or overridden.
If the “type” of an object contained in the deployment plan list is not specified and a reference to its “id” does not impose a different type, it SHALL be inferred to be a plain Application Component Template Specification.
1 content Attribute
TODO
2 requirements Attribute
TODO
, and that the order of Specifications SHALL NOT be significant
4 AssemblyTemplate Specification
TODO
MUST
Must not contain multiple AT’s.
1 applicationComponentTemplates Attribute
TODO
List of ID URL’s ?
5 Content Specification
1 href Attribute
TODO
2 data Attribute
TODO
6 Requirement Specification
TODO
Any requirement in a deployment plan MUST be referenced directly or transitively from a component specification.
Must XXX
fulfillment
extends
7 PlatformComponentTemplate Specification
TODO
Looks identical to the application component specification apart from requiring that the “id” attribute MUST be supplied as this MUST be referenced as the fulfillment of a Requirement Specification
Resources
The following sections describe the resources defined by this specification.
1 Common Types
Resource attributes are defined using the following types:
1 Boolean
As defined by JSON [RFC4627], a token having a literal value of either true or false.
2 String
A UNICODE string as defined by JSON [RFC4627].
3 URI
A String (see above) that conforms to the syntax defined in RFC 3986 [RFC3986].
4 Timestamp
A String (see above) that conforms to the syntax defined in ISO 8601 [ISO 8601:20044] with the restriction that time stamps shall be expressed in UTC (Coordinated Universal Time), with a special UTC designator ("Z").
5 Link
The management model defined in this specification involves resource entity attribute values that link to other resource entities. For example, one of the Platform resource entity attribute values points to Assembly Templates. The “Link” type defined here is used for such attribute values.
"LinkName" : {
"href" : URI
"targetName" : String
…
}
The following attributes MUST be present in a Link. Other attributes, not defined in this specification, MAY also be present.
1 href
This attribute is the URI [RFC 3986] of the resource referenced by this Link. The value of this attribute may be changed by the Platform. Users may not change the value of this attribute.
2 targetName
This attribute echoes the value of the “name” attribute of the resource referenced by this Link. The value of this attribute may be changed by the Platform. Users may not change the value of this attribute.
2 Attribute Constraints
Resource attributes are constrained along a number of axes. These are:
1 Required
If the Required boolean constraint for an attribute of a resource type has a value of "true", then an instance of that resource type MUST have the attribute present. If the value is "false" then the instance is valid with or without the attribute present.
2 Mutable
This boolean indicates the mutability of the attribute’s value(s). “false” indicates that the value of the attribute, once set, shall not change for the lifetime of the resource. “true” indicates that the value of the attribute may change due to the actions or activity of either the provider or the consumer.
3 Consumer-mutable
This boolean indicates the ability of a consumer to set the value of the attribute. It is only relevant for mutable attributes. “false” indicates that the value(s) of the attribute MUST NOT be changed by the consumers. A value of “true” indicates that consumers MAY change the value of the attribute. Note that a value of 'true' does not preclude the provider from changing the value of the attribute.
3 Common Resource Attributes
All the resources in this specification contain the following common attributes:
1 uri
Type: URI
Requied: true
Mutable: false
This attribute expresses the URI of the resource.
2 name
Type: String
Requied: true
Mutable: true
Consumer-mutable: true
This attribute expresses the human-readable name of the resource.
3 description
Type: String
Required: false
Mutable: true
Consumer-mutable: true
This attribute expresses the human-readable description of the resource.
4 created
Type: Timestamp
Requied: true
Mutable: false
This attribute expresses the time which the resource was created.
5 tags
Type: String[]
Required: false
Mutable: true
Consumer-mutable: true
This attribute is an array of String values that may be assigned by the provider or the user. These values can be used for keywording and terms-of-interest.
6 type
Type: String
Requied: true
Mutable: false
Consumer-mutable: false
This attribute expresses the CAMP resource type. Every CAMP resource type defined in this specification specifies the required value for this attribute.
7 representationSkew
Type: String
Required: false
Mutable: true
Consumer-mutable: false
The representationSkew attribute expresses the relationship between the information presented in the resource and the status of the platform implementation artifacts that are represented by that resource (see Representation Skew section). It is an optional, enumerated String. If present, representationSkew must have one of the following values:
• “CREATING” – describes a resource that is in the process of being created. The client can expect that the resource will have a skew of “NONE” once this process has completed.
• “NONE” – is an assertion by the CAMP server that the information in the resource is an accurate representation of the underlying platform implementation. Absent some action by the client or some other event (e.g. platform shutdown), a resource with a skew of NONE can be expected to remain in synch with the platform implementation.
• “UNKNOWN” – indicates that the CAMP server cannot accurately depict the aspect of the platform implementation represented by this resource. Users can attempt to address the underlying issues(s) by manipulating this and/or other resources as specified by the API.
• “DESTROYING” – describes a resource that is in the process of being destroyed. The client can expect that the resource will cease to exist once this process has completed.
The absence of the reprsentationSkew attribute is semantically equivalent to the “NONE” value.
The value of the representationSkew attribute affects the availability of the HTTP methods for that resource. For example, resources with a representationSkew value of CREATING might support the GET, HEAD and DELETE methods, but no other HTTP methods. The following table lists the methods that must be supported for each representationSkew value.
|representationSkew value |Methods Available |
|CREATING |GET, DELETE |
|NONE |All supported methods for that resource. |
|UNKNOWN |All supported methods for that resource. |
|DESTROYING |GET |
Table 1 - representationSkew Available Methods
For each representationSkew value, CAMP servers may support HTTP methods in addition to those listed in the corresponding row of Table 1.
4 Error Response Message Resource
Successful requests will generally return an HTTP status code of 200 (OK), 201 (Created), 202 (Accepted), or 204 (No Content), to indicate that the requested action has been successfully performed or submitted. In addition, they might include a response message body containing a representation of the requested information. However, it is possible for a number of things to go wrong. The various underlying causes are described (as discussed in the previous section) by various HTTP status codes in the range 400-499 (for client side errors) or 500-599 (for server side problems).
If a response is returned with an error status code (400-499 or 500-599), where appropriate, the server is encouraged to include a response message body containing an ErrorMessage object (as defined below). The text values of such messages might be used, for example, to communicate with a human user of the client side application.
The list of messages included in a single error response is encapsulated in the ErrorMessage data model.
Table 2 – ErrorMessage Data Model
|Field |Type |Occurs |Description |
|message |Message |0..n |Zero or more message data for each individual message. |
An individual message contains the following fields:
Table 3 - Message Data Model
|Field |Type |Occurs |Description |
|code |String |0..1 |Symbolic error code identifying the type of error reported by this|
| | | |message |
|field |String |0..1 |Name of the field from the request data model that this message is|
| | | |associated with |
|hint |String |0..1 |Localized text further describing the nature of the problem, |
| | | |possibly including potential workarounds that the client could try|
|text |String |1 |Localized text describing the nature of the problem reported by |
| | | |this message |
|severity |String |0..1 |Label indicating the severity of the error condition represented |
| | | |by this message |
| | | |Vendor shall publish the enumerators that are associated with this|
| | | |field and their semantics |
|stackTrace |String |0..1 |Vendor specific stack trace associated with this message |
|source |String |0..1 |Symbolic identifier of the implementation component that triggered|
| | | |this message |
|message-id |String |0..1 |A unique string that identifies this particular message |
|profile |URI |0..1 |A reference to the standard URI to indicate the meaning of this |
| | | |message |
The profile attribute indicates the semantic meaning of the message which clients may handle automatically. Messages with the same profile shall adhere to the semantic requirements of that profile, but the payload (hint, text, severity, stackTrace) may be different. In other words, given a profile, clients processing the message should be able to subsequently interact with the providers in a consistent manner across.
Each provider may extend the profile to include specific scenarios and use cases.
The information captured in the message data element should be complementary to the HTTP status code, and COULD provide more detailed information. However, it shall not contradict the HTTP status code that is returned with the request.
The following table outlines the common profiles that would accompany this specification.
Table 4 - Common Message Profiles
|Profile |Description |
|/msg/unknown |Unknown error and information given is descriptive in nature |
|/msg/security |Security issues |
|/msg/security/authentication |An authentication error |
|/msg/access |Access violation error |
|/msg/allocation |Allocation related issues |
|/msg/allocation/insufficient |Insufficient resource to satisfy the request |
|/msg/infrastructure |Infrastructure related issues |
|/msg/infrastructure/maintenance |The request cannot be immediately responded due to the infrastructure being in maintenance |
| |status |
5 PlatformEndpoints Resource
A provider may concurrently offer multiple instances of the CAMP API. The primary example of why a provider might do this is to simultaneously support two or more incompatible versions/implementations of the CAMP API, but there are many reasons for a provider to offer multiple instances of the CAMP API.
Concurrent instances are supported through the use of multiple instances of the Platform Resource. The PlatformEndpoints Resource allows clients to discover all the instances of the CAMP API that are currently available. It contains an array of PlatformEndpoint Resources that each reference Platform Resources, and has the following general representation:
{
"uri": URI,
"name": String,
"type": "platformEndpoints",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [ String, + ], ?
"platformEndpoints":[ PlatformEndpoint + ]
}
Because of the unique function of this resource, future versions of the CAMP specification must not make non-backwards compatible changes to this resource.
NOTE: An implementation MAY expose the PlatformEndpoints and corresponding PlatformEndpoint resources in a way that allows for version discovery before the client has authenticated.
Figure 5.21: Example Implementation
[pic]
[pic]
1 paltformEndpoints
Type: PlatformEndpoint[]
Required: true
Mutable: false
This attribute is an array of PlatformEndpoint Resources. This array MUST contain at least one PlatformEndpoint Resource. References between the resources (PlatformEndpoints, PlatformEndpoint, and Platform) MUST be self-consistent.
6 PlatformEndpoint Resource
Each PlatformEndpoint Resource MUST refer to exactly one Platform Resource, and indicates the versions supported by the Platform. This specification is deliberately silent about any relationship between resources within different Platform trees. Each PlatformEndpoint Resource MAY represent a different CAMP API “view” of the same applications and services. On the other hand, each Endpoint MAY represent a completely independent system.
A PlatformEndpoint Resource has the following general representation:
{
"uri": URI,
"name": String,
"type": "platformEndpoint",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [ String, + ], ?
"platformUri": URI,
"specificationVersion": String,
"backwardCompatibleSpecificationVersions": String[], ?
"implementationVersion": String,
"backwardCompatibleImplementationVersions": String[], ?
}
Because of the unique function of this resource, future versions of the CAMP specification MUST NOT make non-backwards compatible changes to this resource.
1 specificationVersion
Type: String
Required: true
Mutable: false
Each instance of a Platform resource is the root of a tree of resources, the syntax and semantics of which conform to one or more versions of the CAMP specification. The value of this attribute is the Specification Version String of the CAMP specification that is supported by the resources rooted in the Platform referenced by the platformUri attribute of this resource.
For Platforms that implement this version of the CAMP specification, the value of this attribute must be “CAMP 1.1” as defined in section 1.7.
2 backwardCompatibleSpecificationVersions
Type: String[]
Required: false
Mutable: false
The values in this array identify each version of the CAMP specification that is backwards compatible with the current specificationVersion of the Platform (referenced in the platformUri attribute of this resource). The values in this array must be the Specification Version Strings of previous CAMP specification versions.
If this attribute is not present, the version of the CAMP specification implemented by the Platform (referenced in the platformUri attribute of this resource) is not backwards compatible with any previous version of the CAMP specification.
PlatformEndpoint resources that reference Specification Version “CAMP 1.1” Platform Resources MUST NOT include this attribute because no previous versions are compatible.
3 implementationVersion
Type: String
Required: false
Mutable: false
Multiple implementations of the same CAMP specification may be offered concurrently. For example, a provider may offer an initial beta version of “CAMP 1.1” and, later, a production version; allowing a period of overlap for their customers to migrate from the beta to the production version. The value of this attribute is an arbitrary String that expresses the provider-specific implementation version supported by the resources rooted in the Platform (referenced in the platformUri attribute of this resource).
4 backwardCompatibleImplementationVersions
Type: String[]
Required: false
Mutable: false
The values in this array list the provider-specific implementation versions that are backwards compatible with the implementation version of the Platform (referenced in the platformUri attribute of this resource). The values in this array are arbitrary Strings that correspond to previous implementationVersion Strings.
If this attribute is not present, the implementation version offered by the Platform (referenced in the PlatformURI attribute of this resource) is not backwards compatible with any previous implementation versions.
5 platformUri
Type: URI
Required: true
Mutable: false
This attribute is the URI of the Platform Resource that this PlatformEndpoint Resource represents.
7 Platform Resource
For a user, a Platform represents the user’s starting view of all accessible resources and deployed entities. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "platform",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"supportedFormatsUri": URI,
"extensionsUri": URI,
"typeDefinitionsUri": URI,
"platformEndpointsURIplatformEndpointsURI": URI, ?
"tags": [ String, + ], ?
"specificationVersion": String,
,
"implementationVersion": String,
"assemblyTemplates": [ Link + ], ?
"assemblies": [ Link + ], ?
"platformComponentTemplates": [ Link + ], ?
"platformComponentCapabilities": [Link + ], ?
"platformComponents": [ Link + ], ?
}
The Platform resource contains the following attributes:
1 supportedFormatsUri
Type: URI
Required: false
Mutable: false
This attribute is a URI reference to the Formats resource for the purpose of identifying all Supported Formats for this Platform.
2 extensionsURI
Type: URI
Requied: true
Mutable: false
This attribute provides a link to the Extensions this Platform supports. See the Extensions Section for details aboutabout Extensions.
3 typeDefinitionsURI
Type: URI
Requied: true
Mutable: false
This attribute provides a link to the TypeDefinitions resource that provides information on the resource types that the Platform supports. See thethe TypeDefinitions ResourceTypeDefinitions Resource section for details.
4 platformEndpointsURI
5 platformEndpointsURI
Type: URI
Requried: truetrue
Mutable: false
This attribute provides a link to aa PlatformEndpoints Resource. The PlatformEndpoints ResourceResource enumerates each CAMP implementation currently available. available.
6 specificationVersion
Type: String
Required: true
Mutable: false
Each instance of a Platform resource is the root of a tree of resources, the syntax and semantics of which conform to one or more versions of the CAMP specification. The value of this attribute is the Specification Version String of the CAMP specification that is supported by the resources rooted in this Platform.
For Platforms that implement this version of the CAMP specification, the value of this attribute must be “CAMP 1.1” as defined in section 1.7.
The value of this attribute MUST exactly match the value of the specificationVersion attribute of any PlatformEndpoint Resource that references this Platform Resource.
7 implementationVersion
Type: String
Required: false
Mutable: false
A provider may choose to offer multiple implementations of the same CAMP specification. For example, a provider may offer an initial beta version of “CAMP 1.1” and, later, a production version; allowing a period of overlap for their customers to migrate from the beta to the production version. The value of this attribute is an arbitrary String that expresses the provider-specific implementation version supported by the resources rooted in this Platform.
The value of this attribute MUST exactly match the value of the implementationVersion attribute of any PlatformEndpoint Resource that references this Platform Resource.
8 assemblyTemplates
Type: Link[]
Required: false
Mutable: true
Consumer-mutable: false
This attribute is an array of Links to the AssemblyTemplates that are accessible to the user.
9 assemblies
Type: Link[]
Required: false
Mutable: true
Consumer-mutable: false
This attribute is an array of Links to the Assembly resources that are accessible to the user.
10 platformComponentTemplates
Type: Link[]
Required: false
Mutable: true
Consumer-mutable: false
This attribute is an array of Links to the PlatformComponentRequirement resources that are accessible to the user.
11 platformComponentCapabilities
Type: Link[]
Required: false
Mutable: true
Consumer-mutable: false
This attribute is an array of Links to the PlatformComponentCapability resources that are accessible to the user.
12 platformComponents
Type: Link[]
Required: false
Mutable: true
Consumer-mutable: false
This attribute is an array of Links to the PlatformComponentCapability resources that are accessible to the user.
8 AssemblyTemplate Resource
For an Application Administrator, an Assembly Template represents the definition of the deployable Application. Application Administrators can create an Assembly Instance by specifying the URI of a Assembly Template as a field in a deployment request. The platform shall instantiate the Application Components and their configurations as specified in the definition of the Assembly Template. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "assemblyTemplate",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
], ?
"applicationComponentTemplates": [ Link + ], ?
}
The AssemblyTemplate resource contains the following attributes:
1 applicationComponentTemplates
Type: Link[]
Required: false
Mutable: true
Consumer-mutable: false
This attribute is an array of Links to the ApplicationComponentTemplate resources that are part of this AssemblyTemplate. An AssemblyTemplate MAY have zero references to ApplicationComponentTemplate resources, but conformant CAMP server implementations MUST NOT instantiate an Assembly using an AssemblyTemplate that does not reference at least one ApplicationComponentTemplate.
9 ApplicationComponentTemplate Resource
For an Application Administrator, an Application Component Template represents the definition of the deployable Component. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "applicationComponentTemplate",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
], ?
"assemblyTemplate" : Link,
"applicationComponentTemplates" : [ Link + ], ?
"platformComponentTemplates" : [ Link + ], ?
"applicationComponentRequirements" : [ Link + ], ?
"platformComponentRequirements" : [ Link + ] ?
}
The ApplicationComponentTemplate resource contains the following attributes:
1 assemblyTemplate
Type: Link
Requied: true
Mutable: true
Consumer-mutable: true
The attribute contains the link to the AssemblyTemplate that contains this resource. This attribute shall be present.
2 applicationComponentTemplates
Type: Link[]
Required: false
Mutable: true
Consumer-mutable: true
This attribute is an array of Links to ApplicationComponentTemplate resources. Each of these resources is a template for an Application Component that will be used by the Application Component that is instantiated from this template.
3 platformComponentTemplates
Type: Link[]
Required: false
Mutable: true
Consumer-mutable: true
This attribute is an array of Links to PlatformComponentTemplate resources. Each of these resources is a template for a Platform Component that will be used by the Application Component that is instantiated from this template.
4 applicationComponentRequirements
Type: Link[]
Required: false
Mutable: true
Consumer-mutable: true
This attribute is an array of Links to ApplicationComponentRequirement resources.
5 platformComponentRequirements
Type: Link[]
Required: false
Mutable: true
Consumer-mutable: true
This attribute is an array of Links to PlatformComponentRequirement resources.
10 ApplicationComponentRequirement Resource
For an Application Administrator, an Application Component Requirement represents an Application Component’s requirement on another Application Component and its required range of component capabilities. Each Application Component Requirement implements this class and adds its’ own Attribute Ranges to the list below. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "applicationComponentRequirement",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
] ?
}
11 ApplicationComponentCapability Resource
For an Application Administrator, an Application Component Capability represents the definition of an Applicaton Component’s range of component capabilities. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "applicationComponentCapability",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
] ?
}
Each Application Component Capability implements this class and adds its’ own Attributes.
12 PlatformComponentTemplate Resource
For an Application Administrator, a Platform Component Template represents the desired configuration of a Platform Component with specific values for the component capabilities. The specified value for each component attribute shall be in the range defined in the corresponding Platform Component Capability. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "platformComponentTemplate",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
] ?
}
Each Platform Component implements this class and adds its own Component Attributes.
13 PlatformComponentRequirement Resource
For an Application Administrator, a Platform Component Requirement represents an Application Component’s requirement on a Platform Component and its required range of component capabilities. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "platformComponentRequirement",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
] ?
}
Each Platform Component Requirement implements this class and adds its own Attribute Ranges.
14 PlatformComponentCapability Resource
For an Application Administrator, a Platform Component Capability represents the definition of Platform Component and its range of component capabilities. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "platformComponentCapability",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
] ?
}
Each Platform Component Capability implements this class and adds its own Attributes.
15 Assembly Resource
For an Application Administrator, an Assembly represents the definition of the deployed Application at runtime. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "assembly",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
], ?
"applicationComponents": [ Link + ], ?
"assemblyTemplate": Link ?
}
The Assembly resource contains the following attributes:
1 applicationComponents
Type: Link[]
Requied: true..*
Mutable: false
This attribute is an array of Links to the ApplicationComponent resources that are part of this Assembly. An Assembly resource MUST have at least one reference to an ApplicationComponent resource.
2 assemblyTemplate
Type: Link
Requied: true
Mutable: false
This attribute is a Link to the AssemblyTemplate resource from which this Assembly was created.
3 resourceState
Type: ResourceState
Requied: true
Mutable: true
Consumer-mutable: false
This attribute expresses state of the resource within the lifecycle.
16 ApplicationComponent Resource
For an Application Administrator, an Application Component represents the management of the deployed Component at runtime. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "applicationComponent",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
], ?
"assembly": Link,
"applicationComponents": [ Link + ], ?
"platformComponents": [ Link + ] ?
}
The ApplicationComponent resource contains the following attributes:
1 assembly
Type: Link
Requied: true
Mutable: false
This attribute is a Link to the Assembly resource of which this ApplicationComponent is a member.
2 applicationComponents
Type: Link[]
Required: false
Mutable: false
This attribute is an array of Links to the ApplicationComponent resources that this ApplicationComponent depends on.
3 platformComponents
Type: Link[]
Required: false
Mutable: false
This attribute is an array of Links to the PlatformComponent resources that this ApplicationComponent depends on.
resourceState
17 PlatformComponent Resource
For an Application Administrator, a Platform Component represents the runtime instance of a platform component and its configuration of component attributes as well as metrics associated with those attributes. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "platformComponent",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
], ?
"externalManagementResource": URI ?
}
Each Platform Component implements this class and adds its own attributes and to the list below.
1 externalManagementResource
Type: URI
Required: false
Mutable: false
A URI to an external management interface to manage this platform component (such as an IaaS API to manage the virtual machines that support this component). This is platform dependent and requires external documentation to understand its meaning.
18 Format Resource
A Format resource represents exactly one supported data serialization format. The Format resource is represented as:
{
"uri": URI,
"name": String,
"mimeType": String,
"type": "format",
"description": String,
"created": Timestamp,
"version": String,
"documentation": URI
}
Each Format resource includes the following attributes:
1 name
Type: String
Requied: true
Mutable: false
This attribute contains the common name of the serialization format. For example: “JSON”.
2 mimeType
Type: String
Requied: true
Mutable: false
This attribute contains the mime-type to be used by the Platform in HTTP2616 compliant content negotiation for this Format. For example: “application/json”.
3 version
Type: String
Required: false
Mutable: false
This attribute contains the version identifier of the data serialization format used.
4 documentation
Type: URI
Requied: true
Mutable: false
5 Required JSON Format Resource
The Required JSON Format Resource is defined as:
{
"uri": URI,
"name": "JSON",
"mimeType": "application/json",
"type": "format",
"version": "RFC4627",
"description": "JavaScript Object Notation",
"created": Timestamp,
"documentation": "",
"representationSkew": String ?
}
The name, mimeType, version, and documentation attribute values for the JSON Format Resource MUST reflect the above values.
19 Formats Resource
The Formats resource contains an array of Links to Format resources. It allows the identification of Supported Formats. The Formats resource is represented as:
{
"uri": URI,
"name": String,
"type": "types",
"description": String, ?
"created": Timestamp,
"tags": String[], ?
"representationSkew": String ?,
"formatLinks": Link[]
}
1 formatLinks
Type: Link[]
Requied: true
Mutable: false
This attribute contains Links to Format resources that contain information about data serialization formats supported by the Platform. For every format that the Platform supports, there MUST be a Format resource Link that represents such a format. The Required JSON Format Resource MUST be listed first in the formatLinks array.
20 TypeDefinitions Resource
This resource contains an array of Links to all TypeDefinition resources. The Platform resource MUST provide a Link to the Types resource in the required attribute named typeDefinitionsUri. The Types resource is represented as:
{
"uri": URI,
"name": String,
"type": "types",
"description": String, ?
"created": Timestamp,
"tags": String[], ?
"representationSkew": String ?,
"typeDefinitionLinks": Link[]
}
Each Types resource includes the following attributes:
1 typeDefinitionLinks
Type: Link[]
Requied: true
Mutable: false
This attribute contains Links to TypeDefinition resources that contain information about resource types supported by the Platform. If the Platform does not extend this Specification to add new resource types then the array can be empty. If the array is non-empty, for every resource type that the Platform supports, there MUST be a TypeDefinition resource Link that represents such a resource type. For more information on TypeDefinition resources see the next Section.
21 TypeDefinition Resource
A Type resource represents exactly one resource type supported by the Platform. The Type resource is represented as:
{
"uri": URI,
"name": String,
"type": "typeDefinition",
"description": String, ?
"created": Timestamp,
"tags": String[] ?
"documentation": URI,
"representationSkew": String ?,
"attributeDefinitionLinks": Link[],
}
Each Type resource includes the following attributes:
1 name
Type: String
Requied: true
Mutable: false
This attribute contains the name of the resource type. For example: “assembly”.
2 documentation
Type: URI
Requied: true
Mutable: false
This attribute contains a URI that points to the documentation for the resource type. For resource types that are defined in this Specification, the URI can point to this Specification.
3 attributeDefinitionLinks
Type: Link[]
Requied: true
Mutable: false
This attribute contains an array of Links. Each Link in this array points to an AttributeDefinition resource. Each of these AttributeDefinition resources represents an attribute of the type represented by the Type resource. For every attribute of the type, there MUST be an AttributeDefinition resource Link that represents the attribute. For more information on the AttributeDefinition resource see the next Section.
22 AttributeDefinition Resource
An Attribute resource represents exactly one supported attribute of one or more resource types. The Attribute resource is represented as:
{
"uri": URI,
"name": String,
"type": "attributeDefinition",
"description": String, ?
"created": Timestamp,
"tags": String[] ?
"documentation": URI,
"attributeType": String,
"required": Boolean,
"mutable": Boolean,
"consumerMutable": Boolean,
"representationSkew": String ?
}
Each Attribute resource includes the following attributes:
1 name
Type: String
Requied: true
Mutable: false
This attribute contains the name of the attribute that this resource represents. For example, “description”.
2 documentation
Type: URI
Requied: true
Mutable: false
This attribute contains a URI that points to the documentation for the attribute that this resource represents. For attributes that are defined in this Specification, the URI can point to this Specification.
3 attributeType
Type: String
Requied: true
Mutable: false
This attribute specifies the type of the attribute that this resource represents. For example, "String", "Timestamp".
4 required
Type: Boolean
Requied: true
Mutable: false
This attribute specifies if the attribute that this resource represents is required.
5 mutable
Type: Boolean
Requied: true
Mutable: false
This attribute specifies the mutability of the attribute that this resource represents.
6 consumerMutable
Type: Boolean
Requied: true
Mutable: false
This attribute specifies if the attribute this resource represents is writable by a CAMP client.
Protocol
1 Transport Protocol
All of The Platform APIs are based on the Hypertext Transfer Protocol, version 1.1 [RFC2616]. Each request will be authenticated using HTTP Basic Authentication [RFC2617] unless otherwise noted. Therefore, requests sent from clients across unsecured networks should use the HTTPS protocol. TLS 1.1 [RFC4346] shall be implemented by the provider and TLS 1.2 [RFC5246] is strongly RECOMMENDED. When TLS is implemented, the following cipher suites are RECOMMENDED to ensure a minimum level of security and interoperability between implementations:
• TLS_RSA_WITH_AES_128_CBC_SHA (mandatory for TLS 1.1/1.2)
• TLS_RSA_WITH_AES_256_CBC_SHA256 (addresses 112-bit security strength requirements)
2 URI Space
The resources in the system are identified by URIs. To begin operations, a client shall know the URI for a resource. Dereferencing the URI will yield a representation of the resource containing resource attributes and links to associated resources.
Clients shall not make assumptions about the layout of the URIs or the structure of the URIs of the resources.
3 Media Types
1 Required Formats
In this specification, resource representations, request bodies, and error response messages are encoded in JSON, as specified in [RFC4627]. The media-type associated with CAMP JSON resource and error response message representation is "application/json".
The Platform MUST provide representations of all resources available in JSON.
2 Supported Formats
If Supported Formats besides JSON are referenced in the supportedFormatsUri attribute of the Platform resource then resource representations, request bodies, and error response messages are allowed in the Supported Formats.
Supported Formats MUST be applied uniformly for all resources defined by this specification.
A client can request any Supported Format using HTTP content negotiation.
4 Request Headers
This API does not impose any requirements on clients’ use of HTTP headers. All PUT requests that update a resource SHOULD contain the If-Match header field with a single entity tag value. If the If-Match header field value in the request does not match the one on the server-side, the server MUST send back a '412 Precondition Failed' status code.
5 Request Parameters
To retrieve a subset of the attributes in a resource, the client may use the ‘SelectAttr’ request parameter in conjunction with the HTTP GET method.
Table 5 – Request Parameters
|Format |Description |Example |
|?SelectAttr=attr1,attr2|Comma (“,”) separated attribute names of the resource to |Assembly132?SelectAttr =name,description,tags |
|,… |return. |Would access only “name”, “description”, “tags” attributes |
| |If an attribute is not part of the resource, an HTTP 4XX |of Assembly132. |
| |status code shall be returned. | |
The “SelectAttr” query parameter may appear more than once (separated by an “&”). The client shall URL encode the request parameters.
When one or more request parameters are specified for a PUT request, a client shall not include attributes in the request entity body that are not specified in the request parameter. Upon receiving such a request the server shall respond with a 400 status code.
6 Response Headers
Responses returned by the Platform makes standard use of HTTP headers. All HTTP responses that return representation of a resource SHOULD use strong Etag response header field indicating the current value of the entity tag for the resource.
7 HTTP Status Codes
The API returns standard HTTP response codes.
8 Mutability of Resource Attributes
Consumers MUST NOT send a request that changes the value of a resource attribute that is declared with a constraint of 'Mutable=false' or 'Consumer-mutable=false'. On receiving such a request the Provider MUST generate an HTTP response with 403 HTTP status code.
9 Updating Resources
Attributtes of the resources defined with “consumerMutable: true” may be modified by clients in two ways. Clients can use the HTTP PUT method to replace the representation of a resource, in its entirety, with a new representation that adds, omits or replaces the values for some of the attributes. Alternatively, clients can use the [HTTP PATCH] method and the “application/json-patch” media type [JSON Patch] to add, delete, or replace specific attributes.
1 Updating with PUT
HTTP PUT requests are requests for complete replacement of the resource identified by the request URL. If a resource attribute is present on a resource and if an HTTP PUT request omits that attribute, it should be treated by the provider as a request to delete the attribute.
2 Updating with JSON Patch
JSON Patch [JSON Patch] defines a JSON document structure for expressing a sequence of operations to apply to a JSON document, suitable for use with the HTTP PATCH method. The "application/json-patch" media type is used to identify such patch documents.
Conformant CAMP servers must support the HTTP PATCH method in conjunction with the “application/json-patch” media type with the following, additional provisions with respect to the operations defined in section 4 of the JSON Patch specification [JSON Patch]:
• CAMP servers must support the ‘add’, ‘remove’, and ‘replace’ operations.
• CAMP servers may support the ‘move’, ‘copy, and ‘test’ operations.
10 Concurrent API versions
Multiple API versions may be offered concurrently to allow backward compatibility for clients. To discover available versions a client issues a GET request for the /api/versions resource and may select one of the listed versions. Each available API version is assigned a namespace identified by a URL.
The response to a GET request for /api/versions will include a list of available API versions and the URL where each version may be accessed. The list of available versions shall be expressed using the common Link type with an additional name version added to the link and its corresponding value.
An example of client requests to the platform are as follows:
GET / => {…, "links": […, "/api/versions", …], …}
GET /api/versions => [
{"version" : "1.0", "href": "",
"targetName": "v1.0"},
{"version" : "1.1", "href": "",
"targetName": "v1.1"}
]
Only versions defined by a CAMP specification can be listed. Additional features not defined in this specification can be implemented using the extensibility features discussed in this specification.
11 Registering a PDP
As indicated in Section 3, registering a package moves it to the deployed state. To register a PDP, a client sends a POST HTTP request to the Platform URL. The entity body of the request contains the URI that identifies the PDP that is being registered. If the URI that identifies the PDP is a relative URI, its base URI is the Platform URI. The JSON serialization of the HTTP request entity body is:
{"pdp_uri" : ""}
Where, the pdp_uri points to the URI of the PDP to be registered. The JSON object MAY contain additional name-value pairs that are not defined in this specification. On successful registration of the PDP, the server creates an AssemblyTemplate resource and sends a 201 Created HTTP status code with the Location header in the HTTP response. The Location header points to the newly created AssemblyTemplate resource. The server also updates the application_templates attribute of the Platform resource to include a reference to the newly created assembly template.
An example HTTP request-response is as follows:
POST / HTTP/1.1
Host:
Content-Type: application/json
Content-Length: ...
{"pdp_uri": "/paas/pdp/1"}
HTTP/1.1 201 Created
Location:
Content-Type: ...
Content-Length: ...
...
12 Instantiating an Application
Once the application is in the deployed state, a client can instantiate the application by sending a POST HTTP request to the corresponding AssemblyTemplate URL. The entity body of the request can be empty. Interpretation of a non-empty entity body of the request is implementation-dependent. On success the server creates an Assembly resource and sends a 201 Created HTTP status code with the Location header in the HTTP response. The Location header points to the newly created Assembly resource. The server also updates the AssemblyInstances attribute of the Platform resource to include a reference to the newly created assembly.
An example HTTP request-response is as follows:
POST /paas/asm_template/1 HTTP/1.1
Host:
HTTP/1.1 201 Created
Location: .org/paas/assembly/1
Content-Type: ...
Content-Length: ...
...
13 Suspending and Resuming an Application
To suspend, or resume an application, a client sends a POST HTTP request to the assembly resource URL. The entity body of the request contains the value of the new state for the application. The JSON serialization of the HTTP request entity body is:
{"new_state" : ""}
Where, new_state specifies the new desired value for the application state. This specification defines two such values: "suspend", and "resume," whose semantics are as defined in Section 3. An implementation MAY have additional state values that it allows. The JSON object MAY contain additional name-value pairs that are not defined in this specification. An implementation can define additional state values or name-value pairs, to allow clients to specify the scale at which the application is suspended and resumed.
An example HTTP request-response is as follows:
POST / HTTP/1.1
Host:
Content-Type: application/json
Content-Length: ...
{"new_state": "suspend"}
HTTP/1.1 200 OK
14 Deleting an Application Instance and a Deployed Application
To delete an application instance (an assembly), a client sends a DELETE HTTP request to the assembly resource URL. Similarly, to delete a deployed application, a client sends a DELETE HTTP request to the assembly template URL.
Extensions
Features provided by this specification may be extended to provide additional information and functionality. Using Requirements and Capabilities is RECOMMENDED instead of Extensions, if possible. Extensions MAY be added by registering the new functionality in the Extensions resource. Extensions MUST NOT change or remove any features or functionality of this specification. New features MAY be added. Each Extension MUST satisfy all criteria in the Conformance section and MUST NOT contradict any normative statements in this document. The following extensions are allowed:
Table 6 - Extension Categories and Functionality
|Category |Functionality |Description |
|API Extension |New HTTP Request Verbs |Support for additional HTTP Request Verbs that |
| | |are not used by this specification, such as |
| | |HEAD. |
|API Extension |HTTP Header Handlers |Processing of specific HTTP headers provided by|
| | |clients. For example, an API Extension may |
| | |require an authentication token header. |
|API Extension |New Resources |Addition of new resources that MAY handle HTTP |
| | |requests such as POST or PUT to create |
| | |instantiations of a new resource type. |
|API Extension |New Resource Methods |Allow the creation of new methods or actions |
| | |that may cause different sequences of state |
| | |changes than happen by default. |
|PDP Extension |New Metadata in the PDP |Additional metadata provided in the PDP to |
| | |allow for more sophisticated handling of the |
| | |bundled data. |
|Resource Extension |New Resource Types |Addition of new resource types. |
|Resource Extension |New Resource Attributes |Addition of new attributes to existing |
| | |resources. |
|Resource Extension |New States in any Application Lifecycle |Addition of new application states, such as an |
| | |intermediate state between the states defined |
| | |by the specification. |
1 Unique Name Requirement
Table 7- Entities
|Entities |
|Resources |
|Attributes |
|Methods |
|PDP Metadata Keys |
Entities are enumerated in Table 7. The Extension Developer MUST use a unique name for new Entities within an existing namespace. Entities added by an Extension MUST NOT interfere with names of existing entities, including any added by another Extension.
NOTE: Each resource has its own namespace. It is acceptable to create a resource named :Foo, and another resource named :Bar, where both resources have an attribute named fooBar.
Use of your registered ICAAN Internet domain name followed by a colon (“:”) character as a prefix to all your entity names is strongly RECOMMENDED to comply with these requirements.
Example: New Attribute “foo” added by Example Organization
:foo
Example: New Attribute “foo” added by Example Inc.
EXAMPLE-INC:foo
Table 8 - Unique Name Exceptions
|Extension Category |New Entity |Exception |
|API Extension |Adding HTTP Request Verbs |Unique name not required for HTTP verbs |
|API Extension |Adding HTTP Header Handlers |Unique name not required for HTTP headers |
A unique name is not required for entities listed in Table 8.
NOTE: RFC-3986 identifies Unreserved Characters that may be used in a URI without any encoding. Percent-Encoding allows any character to be represented in a URI. Special characters such as “:” and “.” Have specific meanings in scripting languages such as JavaScript. Special characters must be properly escaped in order to use them as part of a name string. Your data serialization format may not escape all problematic characters, so you may need to add logic to your clients to escape special characters to enable interaction with an Extension.
2 Extension Resource
An Extension resource represents new functionality added to the Platform. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "extension",
"description": String,
"version": String,
"created": Timestamp,
"documentation": URI ?
}
The Extension resource contains the following attributes:
1 version
Type: String
Requied: true
Mutable: false
This attribute contains a string identifier of the version of this Extension.
2 documentation
Type: Link
Required: false
Mutable: false
This attribute is a Link to a human readable document that describes the Extension in depth.
3 Extensions Resource
The Extensions resource contains an array of Links to Extension resources. It allows the identification of Extensions. The Extensions resource is represented as:
{
"uri": URI,
"name": String,
"type": "types",
"description": String, ?
"created": Timestamp,
"tags": String[], ?
"representationSkew": String ?,
"extensionLinks": Link[]
}
1 extensionLinks
Type: Link[]
Requied: true
Mutable: false
This attribute contains Links to Extension resources that contain information about Extensions available on the Platform. For every Extension available, there MUST be an Extension resource Link that represents the Extension. The Platform resource MUST provide a Link to the Extensions resource in the required attribute named extensionsUri.
Example of an extensionLinks value:
[
{
"targetName" : "EXAMPLE:Auth",
"href": ""
},
{
"targetName" : "EXAMPLE:PDPforFooLang",
"href" : ""
}
…
]
4 Extending Existing Resources
New attributes MAY be added to an existing resource using an Extension if the Unique Name Requirement in 7.1 is met. A new resource type is not required in order to add new attributes.
Example of an Extended Extension Resource:
{
"uri": URI,
"name": String,
"type": "extension",
"description": String,
"version": String,
"created": Timestamp,
"documentation": URI ?,
":foo": String ?
}
Note that in the above example, the new attribute “:foo” was added, and the type attribute remained set to the original value “extension”.
Conformance
TBD
Acknowledgments
The following individuals have participated in the creation of this specification and are gratefully acknowledged:
Participants:
[Participant Name, Affiliation | Individual Member]
[Participant Name, Affiliation | Individual Member]
Glossary
application – a set of components that act together to provide useful functions and are typically exposed as a service to Application end-users. An application is represented by different resources (e.g. Assembly Template, Assembly) throughout its lifecycle.
Application Component – a collection of code and/or, resources (optionally accompanied by metadata) that either provides a set of related services or functionality or contains a set of related information. Codeexamples include Ruby gems, Java libraries, and PHP modules. Examples of resources include data sets, identity sets (i.e. collections of user account and attribute information), and collections of graphical images.
Application Component Capability – a management resource that represents an Application Component’s capabilities.
Application Component Requirement – a management resource that represents a requirement on an Application Component, expressed with attributes that may have value ranges.
Application Component Template - a management resource that represents an unrealized Application Component and includes a reference to the executable code as well as metadata for configuring the Application Component and referencing its platform and other components.
Application Development Environment (ADE) – a developer tool used to create an application (can be an offline tool installed locally or part of the platform offering itself).
Assembly – a management resource that represents a running application.
Assembly Template - a management resource that represents an unrealized Assembly and includes a reference to the Application Component Templates used within the Application as well as metadata for configuring the Application Component and referencing its platform and other components.
Deploy – the step of creating one or more management resources on the platform. Deployment can be done through the API for individual management resources (i.e via a POST to a URI), or can be done as part of the import of a Platform Deployment Package.
Deployment Plan - packaging management meta-data that includes a serialized copy of the Assembly Template resource and all dependent management resources such as Application Component Templates. Deployment Plans are an essential part of a Platform Deployment Package.
Extension - a systematic representation of additional features and functionality added by an Extension Developer.
Platform – The collection of management resources that constitute the consumer visible view of the Platform as a Service offering. The Platform management resource is an aggregation and discovery point for all the Applications and their dependencies currently deployed and running.
Platform as a Service (PaaS) - A type of cloud computing in which the service provider offers customers/consumers access to one or more instances of a running application computing platform or application service stack.
Platform Component – a management resource that represents an application’s use of a realized and running Platform Component.
Platform Component Capability – a management resource that represents a Platform Component’s capabilities.
Platform Component Requirement – a management resource that represents a requirement on a Platform Component, expressed with attributes that may have value ranges.
Platform Component Template - a management resource that represents an unrealized Platform Component and includes references to metadata for configuring an instance of that Platform Component.
Platform Deployment Package (PDP) - an archive of executable images, dependency descriptions and metadata (Management Resources serialized into a Deployment Plan) that can be used to move an Application and its Components from Platform to Platform, or between an Application Development Environment and a Platform (e.g. a storefront application with component binaries, database images and all the configurations needed to install and run).
Supported Formats - one or more data serialization format for data representation. JSON format is required, but other data serialization formats are also allowed. The Platform resource identifies all Supported Formats in the optional supportedFormatsUri attribute. If the supportedFormatsUri attribute is absent from the Platform resource, then only JSON is supported.
Use Cases (Non-Normative)
The following is non-exhaustive list of detailed use cases addressed by this specification.
1. Building the Application
1. Build Application and Package
The Application Developer selects a local Application Development Environment (ADE) and uses it to build an application. The ADE may be aware of the Platform Components that are available in the target platform for the application and may provide the developer with assistance in consuming these Components. Once built, the Components that make up the application are packaged along with any necessary metadata as part of a deployment package. The output of the ADE is a Platform Deployment Package (PDP) with bundled Component executables (including language specific packages such as .war files) and Metadata included in the deployment plan (including the requirements for Platform Component elements). This is shown in the Figure below.
[pic]
Figure 9 - Platform Deployment
If the platform is using an IaaS infrastructure, there will be additional packages for the deployment of Platform Components virtual machines referenced by the metadata in the PDP as shown below:
[pic]
Figure 10 - Platform Deployment with IaaS
This shows the configuration of Platform Components in a virtual machine configuration and packaging tool, which outputs OVF [OVF] packages (one for each Platform Component). These OVF packages are then deployed in an Infrastructure as a Service environment, creating the platform. The PaaS Management API will include extension points for the Platform Components that allow the administrator to invoke the IaaS management API to manage the Platform Components.
2. Build Application in the Cloud and Optionally Package
This use case is the same as that described in the previous section except for the following:
• The ADE is itself an application that may be deployed on the Platform (see SaaS).
• The ADE is aware of the Platform Components that are available on the Platform for the Application.
• If the target platform for the application is “the same” as the platform that hosts the ADE, the packaging, registering and instantiation process may be simplified.
[pic]
Figure 11 - ADE Development to a Platform
2. Deploying and Managing the Application
To deploy an application the Application Administrator shall have an account with the platform provider and access to the required resources. Assume that Assembly Templates, Application Component Templates and Platform Component Templates have already been created in the ADE and serialized into a Platform Deployment Package as shown below:
[pic]
Figure 12 - Platform Deployment Package (PDP)
1. Import Platform Deployment Package
This allows the Application Administrator to import a Platform Deployment Package and that creates the corresponding Management Resources on the Platform. The Platform Deployment Package is unpacked and Assembly Templates, Application Component Templates and their Platform Component Templates are realized in the API as Management Resources and an Assembly Instance can then be created that is ready to run. Any resources that the Components depend on are created as well. The inverse export operation creates a Platform Deployment Package from a given set of Management Resources. The imported Management Resources are shown in the Figure below:
[pic]
Figure 13 - Imported Platform Deployment Package
2. Upload Application
Instead of importing a Platform Deployment Package, the PaaS Management API also supports uploading of application files, be it code, configuration, or data files, in full or in part. The typical use case is that of “pushing” incremental updates (“diffs”) as one would when using a version control system such as Git [Git]. However, this upload mechanism is not limited to incremental uploads. It may also be used to upload applications in their entirety.
3. Run/Stop/Suspend/Snapshot
This allows the Application Administrator to run an Assembly or individual Application Components, stop them, put them into suspension or snapshot them. Assemblies in suspension can be restarted and Assemblies can be restarted from snapshots.
4. Patch an Application Component Template
Replaces one or more Application Component Templates within an Assembly Template with, usually, updated versions. These updated templates will be used the next time an Assembly Instance is created from the Assembly Template or when already created Assemblies take up the change.
5. Patch a Created, Deployed or Running Application
This operation replaces one or more Application Component Templates within the Assembly Template associated in a deployed or running Assembly. The updated templates are used the next time the Assembly or an Application Component within the Assembly Instance is deployed.
Example Database Platform Component (Non-Normative)
One important Platform Component that can be provided by many platforms is a database. The following sections illustrate how database components could be provided by extending the model defined in this specification. The material in these sections is non-normative.
3. Model
A Database Platform Component provides four sub-classed resources as shown in the below diagram:
[pic]
Figure 14 - Database Platform Component Model
4. DatabaseCapability
For an Application Administrator, a Database Capability represents the definition of a database platform component and its range of capabilities. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "databaseCapability",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
], ?
"clusterTypes": [
String, +
],
"maxNumberNodes": String,
"maxCores": String,
"maxMemSize": String,
"maxDiskSize": String,
"backupAvailable": Boolean,
"synchronousCopyAvailable": Boolean,
"partitionAvailable": Boolean,
"compressionAvailable": Boolean,
"retentionAvailable": Boolean,
"tunings": [
String, +
],
"cachingAvailable": Boolean,
}
Each type of DatabasePlatformComponent implements this class and populates the attributes in the list below.
1. clusterTypes
Type: String[]
Requied: true
Mutable: true
Consumer-mutable: false
An array of supported cluster types. Values include: “active” and “passive”.
2. maxNumberNodes
Type: String
Requied: true
Mutable: true
Consumer-mutable: false
Expresses the maximum number of supported nodes for scaling purposes.
3. maxCores
Type: String
Requied: true
Mutable: true
Consumer-mutable: false
Expresses the maximum number of supported cores for scaling purposes.
4. maxMemSize
Type: String
Requied: true
Mutable: true
Consumer-mutable: false
Expresses the maximum size of supported memory for an instance.
5. maxDiskSize
Type: String
Requied: true
Mutable: true
Consumer-mutable: false
Expresses the limit to the size of a disk for an instance.
6. backupAvailable
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if backup can be enabled.
7. synchronousCopyAvailable
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if synchronous copy can be enabled
8. partitionAvailable
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if partitioning can be enabled
9. compressionAvailable
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if compression can be enabled
10. retentionAvailable
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if retention can be enabled
11. tunings
Type: String[]
Requied: true
Mutable: true
Consumer-mutable: false
An array of supported tuning types. Values include: “OLAP”, “DataMining”, and “Spatial”
12. cachingAvailable
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if caching can be enabled
5. DatabaseRequirement
For an Application Administrator, a Database Requirement represents an Application Component’s requirements on a database platform component and its required range of capabilities. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "databaseRequirement",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
], ?
"clusterTypes": [
String, +
],
"numberNodesRange": String,
"coreRange": String,
"memSizeRange": String,
"diskSizeRange": String,
"backupEnabled": Boolean,
"synchronousCopyEnabled": Boolean,
"partitionEnabled": Boolean,
"compressionEnabled": Boolean,
"retentionEnabled": Boolean,
"tunings": [
String, +
],
"cachingEnabled": Boolean
}
Each type of DatabaseRequirement implements this class and populates the attributes in the list below.
1. clusterTypes
Type: String[]
Requied: true
Mutable: true
Consumer-mutable: true
An array of required cluster types. Values include: “active” and “passive”.
2. numberNodesRange
Type: String
Requied: true
Mutable: true
Consumer-mutable: true
Expresses the range of the number of nodes for scaling purposes
3. coreRange
Type: String
Requied: true
Mutable: true
Consumer-mutable: true
Expresses the required range of number of cores.
4. memSizeRange
Type: String
Requied: true
Mutable: true
Consumer-mutable: true
Expresses the range of required memory sizes.
5. diskSizeRange
Type: String
Requied: true
Mutable: true
Consumer-mutable: true
Expresses the range if disk sizes required.
6. backupEnabled
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: true
true if backup is required.
7. synchronousCopyEnabled
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if synchronous copy is required.
8. partitionEnabled
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: true
true if partitioning is required.
9. compressionEnabled
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: true
true if compression is required.
10. retentionEnabled
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: true
true if retention is required.
11. tunings
Type: String[]
Requied: true
Mutable: true
Consumer-mutable: true
An array of required tuning types. Values include: “OLAP”, “DataMining” and “Spatial”.
12. cachingEnabled
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: true
true if caching is required.
6. DatabaseTemplate
A Database Template represents the desired configuration of a Database Platform Component with specific values for the component capabilities. The specified value for each component attribute shall be in the range defined in the corresponding Database Capability. Some PaaS offerings might only offer a fixed number of Database Template instances that cannot be modified (read-only, no new instances) indicating pre-tuned and configured pools of database resources from which these draw. Other PaaS offerings may allow newly created Database Template instances with values in any combination. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "databaseTemplate",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
], ?
"clusterType": String,
"numberNodes": String,
"cores": String,
"memSize": String,
"diskSize": String,
"backupEnabled": Boolean,
"synchronousCopyEnabled": Boolean,
"partitionEnabled": Boolean,
"compressionEnabled": Boolean,
"retentionEnabled": Boolean,
"tuning": String,
"cachingEnabled": Boolean
}
Each type of DatabaseTemplate implements this class and populates the attributes in the list below.
1. clusterType
Type: String
Requied: true
Mutable: true
Consumer-mutable: false
The desired cluster type. Values include: “active” and “passive”
2. numberNodes
Type: String
Requied: true
Mutable: true
Consumer-mutable: false
The desired number of nodes for an instance
3. cores
Type: String
Requied: true
Mutable: true
Consumer-mutable: false
The desired number of cores for an instance
4. memSize
Type: String
Requied: true
Mutable: true
Consumer-mutable: false
The desired size of memory for an instance
5. diskSize
Type: String
Requied: true
Mutable: true
Consumer-mutable: false
The desired size of a disk for an instance.
6. backupEnabled
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if backup is desired for an instance.
7. synchronousCopyEnabled
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if synchronous copy is desired for an instance.
8. partitionEnabled
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if partitioning is desired for an instance
9. compressionEnabled
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if compression is desired for an instance
10. retentionEnabled
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if retention is desired for an instance
11. tuning
Type: String
Requied: true
Mutable: true
Consumer-mutable: false
The desired tuning types. Values include: “OLAP”, “DataMining” and “Spatial”
12. cachingEnabled
Type: Boolean
Requied: true
Mutable: true
Consumer-mutable: false
true if caching is desired for an instance
7. Database
A Database represents the runtime instance of a Database Template and its configuration of component attributes as well as metrics associated with those attributes. Each Application’s use of a Database is represented by an instance of this resource. This resource has the following, general representation:
{
"uri": URI,
"name": String,
"type": "database",
"description": String,
"created": Timestamp,
"representationSkew": String, ?
"tags": [
String, +
], ?
"externalManagementResource": String,
"clusterType": String,
"numberNodes": String,
"cores": String,
"memSize": String,
"diskSize": String,
"backupEnabled": Boolean,
"synchronousCopyEnabled": Boolean,
"partitionEnabled": Boolean,
"compressionEnabled": Boolean,
"retentionEnabled": Boolean,
"tuning": String,
"cachingEnabled": Boolean,
"operationsThroughput": String,
"operationsBandwidth": String
}
Each type of Database implements this class and populates the attributes in the list below.
1. externalManagementResource
Type: URI
Required: false
Mutable: false
A URI to an external management interface to manage this platform component (such as an IaaS API to manage the virtual machines that make up this database). This is platform dependent and requires external documentation to understand its meaning.
2. clusterType
Type: String
Requied: true
Mutable: false
The actual cluster type. Values include: “active” and “passive”
3. numberNodes
Type: String
Requied: true
Mutable: false
The actual number of nodes for an instance.
4. cores
Type: String
Requied: true
Mutable: false
The actual number of cores for an instance.
5. memSize
Type: String
Requied: true
Mutable: false
The actual size of memory for an instance.
6. diskSize
Type: String
Requied: true
Mutable: false
The actual size of a disk for an instance.
7. backupEnabled
Type: Boolean
Requied: true
Mutable: false
true if backup is enabled for this instance.
8. synchronousCopyEnabled
Type: Boolean
Requied: true
Mutable: false
true if synchronous copy is enabled for this instance.
9. partitionEnabled
Type: Boolean
Requied: true
Mutable: false
true if partitioning is enabled for this instance.
10. compressionEnabled
Type: Boolean
Requied: true
Mutable: false
true if compression is enabled for this instance.
11. retentionEnabled
Type: Boolean
Requied: true
Mutable: false
true if retention is enabled for this instance.
12. tuning
Type: String
Requied: true
Mutable: false
The actual tuning type of the database instance. Values include: “OLAP”, “DataMining” and “Spatial”
13. cachingEnabled
Type: Boolean
Requied: true
Mutable: false
true if caching is enabled for this instance.
14. operationsThroughput
Type: String
Requied: true
Mutable: true
Consumer-mutable: false
The billable operations per second.
15. operationsBandwidth
Type: String
Requied: true
Mutable: true
Consumer-mutable: false
The billable MegaBytes per second.
16. resourceState
Type: ResourceState
Requied: true
Mutable: true
Consumer-mutable: false
This attribute expresses state of the database instance within its lifecycle.
Implementation Considerations (Non-Normative)
8. Types of Platform Deployments
Platforms can be built with resources that provide isolation at different levels. For example, each Platform Component (e.g. application server, database) can sit atop a stack of virtual machine, operating system, and component, as seen below:
[pic]
Figure 15 - Platform Component Virtual Machine Isolation
The point of isolation in the above is the virtual machine.
The level at which isolation is provided has profound effects upon the way in which Platform Components are managed and secured. In the above example, each consumer is provided with a dedicated VM, OS, and Platform Component. It is likely (though not certain) that, in the above model, the Consumer will perform both the Application Administrator and the Platform Administrator roles - managing not only their application but also the underlying infrastructure including, potentially, the operating system.
Platform Components can also be deployed without a hypervisor, and instead use multiple Platform Components running on a single OS as shown below:
[pic]
Figure 16 - Platform Component Operating System Isolation
The point of isolation in the above is the operating system.
Although the consumer may still perform both the Application Administrator and some portions of the Platform Administrator roles, for obvious security reasons consumers cannot be allowed control of the operating system as a single OS can be shared by multiple consumers.
Lastly, the Platform Component container itself can offer virtualize instances of the Platform Component to each consumer and isolate multiple consumers from each other as shown below:
[pic]
Figure 17 - Platform Component Container Isolation
The point of isolation in the above is the Platform Component container.
In the above case the consumer can only act as an Application Administrator. The tasks of configuring and managing the Platform Component container (tasks assigned to the Platform Administrator) can only be performed by the cloud provider.
This PaaS Management API is agnostic with respect to the above deployment models as it deals only with the management of an Application’s dependencies on various Platform Components and not with the lifecycle of the Platform Components themselves. The API may be extended to include the management of Platform Component containers, Platform Components, operating systems, and other infrastructural elements.
9. Scaling
The PaaS Management API assumes that applications are organized architecturally in tiers, some of which are hosted on the platform, while others may be external to the platform (and hence unmanaged). Each tier may consist of one or more components. For example, the “application tier” of a PHP application may be implemented by a mod_php component combined with an Apache component. Components in turn can be either provided by the platform or by the application itself.
Conceptually, scaling operations affect individual application tiers. In practice however, since tiers are composed of Application and Platform Components, this means they affect Components. In addition, scaling operations are also specific to each Component and may be subject to explicit or implicit restrictions and policies imposed by the Component on both, scaling operations and grouping. For instance, a Component such as a database may be inherently non-replicable. Conversely, a Component such as PHP module may need to be in the same group as its hosting Apache instance because it needs to be dynamically loaded into the latter--even though it can scale out without limit.
Individual Components may define events and policies for implementing auto-scaling. For instance, a multithreaded webserver component may trigger a scale-up if the number of idle worker threads drops below a given threshold. Or a MongoDB component may impose a policy that scaling may only happen in increments of 3 nodes.
Scaling operations may also be performed directly on the Application Component’s Platform Component resources. This is known as manual scaling and generally results in a new reservation being created in the platform’s auto-scaling setup. Other forms of scaling may require changes to how the Assembly Template uses Application Component Templates and Platform Component Templates. The actual scaling architecture for a Platform Component is outside the scope of this specification.
Revision History
|Revision |Date |Editor |Changes Made |
|1 |2012-12-04 |Anish Karmarkar |Applied OASIS template to version 1.0 |
|2 |2012-12-18 |Anish Karmarkar |Included resolutions for issues 7, 12, 13, 15, 24, 33. |
|3 |2013-02-05 |Anish Karmarkar |Included resolutions for issues 2, 6, 10, 14, 25, 35 |
|4 |2013-02-12 |Adrian Otto |Included resolutions for 19, 38 |
|5 |2013-02-13 |Adrian Otto |Included resolutions for 1, 49 |
|6 |2013-02-27 |Adrian Otto |Included resolutions for 36, 48, 53 |
|7 |2013-02-27 |Adrian Otto |Included Resolutions for 34, 52 |
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related searches
- minecraft version 1.12.2 free download
- minecraft version 1 8 download
- minecraft free download version 1 8
- minecraft version 1 12 2 free download
- minecraft version 1 15 download
- minecraft version 1 0 download
- minecraft version 1 14 4 download
- minecraft version 1 10 2 download
- minecraft version 1 10 2 free
- minecraft version 1 12 download
- download minecraft version 1 12 2
- minecraft version 1 5 2 download