1 / 41

Plan Portability API: Brief Overview

Plan Portability API: Brief Overview. Gerd Breiter Frank Leymann Thomas Spatzier. A Caveat. The draft of the Plan Portability has been uploaded about a year ago Thus, it does not reflect features the TC added over the last year E.g. Requirements, Capabilities, Artifacts,...

watson
Download Presentation

Plan Portability API: Brief Overview

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Plan Portability API:Brief Overview Gerd Breiter Frank Leymann Thomas Spatzier

  2. A Caveat • The draft of the Plan Portability has been uploaded about a year ago • Thus, it does not reflect features the TC added over the last year • E.g. Requirements, Capabilities, Artifacts,... • These features must be reflected in case the TC agrees to work on the API

  3. A Pattern: Embracing Plan Tasks • The effects achieved by an operation are often reflected by the return data of the operation • Thus, this return data is passed to a post-Task of the task bound to the operation, and this post-Task uses the Plan Portability API to store this data • From then on, the effects achieved by an operation is available in the environment in a portable manner! • pre-Tasks can use the API to collect data required for invoking the task proper (i.e. task T) op effects N invokes pre-T T post-T Plan Portability API State of Instancesof service templates

  4. API Style • The API is a REST API • The style might be adopted to add additional REST principles and patterns • E.g. HATEOAS, task resources,...

  5. Requirements on the API • Retrieve the values of the properties of a specific instance of a node template • Retrieve the state of a specific instance of a node template • Create an instance of a service template • This will typically be used within the build plan associated with the service template • Create an instance of a node template (considering cardinality) • Update values of particular properties and attributes of a specific node instance • Delete an node instance • Delete a service instance • Retrieve the instance identifier (URI) of a specific instance of a topology template • This API supports queries to filter on all instances of a specific topology template • Note: This API is for convenience only. The instance identifier of a service instance may be returned in the output message of the build plan and stored somewhere by the requestor of the build plan. • Discover instance identifiers (URIs) of instances of node templates of a specific service instance • This API supports queries to filter node instances in a particular state only, and it allows to navigate through the topology of the service template of the corresponding service instance in order to conveniently locate the node templates instance of which are of interest.

  6. Basic Assumptions • The base URI of each REST API is available when binding a plan • For example, during installation of a TOSCA container the base URIs are set and stored in some environment parameters • During binding of a task that uses one of the specified REST APIs the base URI of the API is set

  7. Assumptions About Identifiers • Service Templates are uniquely identified by a URI assigned to them at the time they are registered in a particular environment, i.e. when they are “stored” in a TOSCA container • Service instances are identified by URIs assigned to them at instantiation time • Node templates are identified within a service template by their unique ID attribute (as defined by the TOSCA specification) • Instances of node templates are identified by their URI assigned to them at instantiation time

  8. Supported HTTP Headers& HTTP Return Codes • (see the draft document)

  9. Retrieve Instance ID (URI) of Service Instance • Description: Retrieve the URIs of service instances created in a particular environment, satisfying certain conditions • GET /ServiceInstances?parameter_list • parameter_list: A list of parameters used to filter instance identifiers • The parameters supported are: • ServiceTemplateName: the name of the service template for which instance identifiers are to be retrieved • ServiceTemplateID: the identifier of the service template for which instance identifiers are to be retrieved • DateCreated: the date the service instance has been created • CreatedBefore: the time before the service instance has been created • CreatedAfter: the time after which the service instance has been created • … • The parameters in query string of the request URI are ANDed.

  10. Request Headers Accept - Must be application/xml. Accept-Encoding – Supported value is gzip. If this field is not specified the response will not be encoded at all. Authorization - The credentials passed by the client to the TOSCA container to authenticate itself. Host - The base URI that the TOSCA container provides to support the specific API. TOSCA-PP-API-Version - The version of the specification of this API; must be 1.0.

  11. Example GET /ServiceInstances ?ServiceTemplateName=myWebSphereCluster &CreatedAfter=2013-04-13&CreatedBefore=2013-06-10 HTTP/1.1 Accept: application/xml Accept-Encoding: gzip Authorization: Basic WalorEerq45AElk Host: www.my-tosca-container.com TOSCA-PP-API-Version: 1.0

  12. Response • <ServiceInstances> • <ServiceInstanceURI/>* • </ServiceInstances> • The <ServiceInstances> element has the following properties: • ServiceInstanceURI: The URI representing the identifier of the qualifying service instance.

  13. Applicable Headers Applicable Response Header Fields: Server – TOSCA container producing the response. WWW-Authenticate – Returned only if client is not authenticated. Applicable Entity Header Fields: Content-Length - The number of octets of the enclosed entity. Content-Type - The media type of the enclosed entity. Last-Modified - Time the enclosed entity has been modified last time at the origin server. Applicable General Header Fields: Cache-Control – Freshness period of the returned resource is provided in the max-age directive (in number of seconds; “0” indicate that resource must always be re-validated). Date – Time the message was sent. Transfer-Encoding – Encoding that has been applied to the whole message.

  14. Example HTTP/1.1 200 OK Content-Length: 212 Content-Type: application/xml Last-Modified: Tue, 1 Nov 2011 19:39:22 CET < ServiceInstances> <ServiceInstanceURI> http://www.ibm.com/websphereCluster42 </ServiceTemplateURI> <ServiceInstanceURI> http://www.ibm.com/websphereCluster4711 </ServiceTemplateURI> </ServiceInstances> ...andhereitget‘sclear, thatthe API cangetmoreHATEOASich

  15. Retrieve Instance ID (URI) of a Node Instance by Path Expression • Description: Retrieve the URIs of node instances for a particular service instance, possibly filtered via a path expression navigating from a node template or a node instance to its children. • GET /NodeTemplateInstances • ?ServiceInstanceID=URI • &NodeTemplateID=ID • &NodeInstanceID=URI • &PathExpression=string • &StateExpression=string • The parameters of the query string are: • ServiceInstanceID: the identifier (URI) of the service instance • NodeTemplateID: the identifier (xsd:ID) of the node template the path expression starts with • NodeInstanceID: the identifier (URI) of the node instance the path expression starts with • PathExpression: a path expression similar to Xpath • StateExpression: a Boolean expression in the state property of the corresponding node template.

  16. Response • Response Message Body: • <NodeInstances> • <NodeInstanceNodeTemplateID="ID"? uri="anyURI"/>* • </NodeInstances> • The <NodeInstances> element has the following properties: • NodeInstance: this element provides the URI of the instance qualified. Its NodeTemplateID attribute provides the value of the ID attribute of the corresponding node template. The NodeTemplateID attribute is only required in case instances of more than one node template are retrieved.

  17. Example 1 The following request filters from the specific service instance …/314 all node instance identifiers reachable from all instances of node template A via relationship R1 that have a value “p1” of the property “p”. GET /NodeTemplateInstances ?ServiceInstanceID=http://www.sample.com/314 &NodeTemplateID=A &PathExpression=R1[p=p1] HTTP/1.1 Accept: application/xml Response Only the instance with identifier “b1” has the value “p1” of property “p”. Thus, only b1 qualifies under the filter and is, thus, returned. HTTP/1.1 200 OK <NodeInstances> <NodeInstanceuri="b1"/> </NodeInstances>

  18. Example 2 The following request filters from the specific service instance …/314 all node instance identifiers reachable from all instances of node template A via relationship R1 followed by relationship R2. GET /NodeTemplateInstances ?ServiceInstanceID=http://www.sample.com/314 &NodeTemplateID=A &PathExpression=R1/R2 HTTP/1.1 Accept: application/xml Response 2: Both node instances, c1 and c2, reachable from the instances a1 and a2 of node template A qualify under filter. HTTP/1.1 200 OK <NodeInstances> <NodeInstanceuri="c1"/> <NodeInstanceuri="c2"/> </NodeInstances>

  19. Example 3 The following request filters from the specific service instance …/314 all node instance identifiers reachable from the particular instances a2 of node template A via relationship R1 followed by relationship R2. GET /NodeTemplateInstances ?ServiceInstanceID=http://www.sample.com/314 &NodeInstanceID=a2 &PathExpression=R1/R2 HTTP/1.1 Accept: application/xml Response 3: Node instance c2 is reachable via the given path expression from a2 and is, thus, returned. HTTP/1.1 200 OK <NodeInstances> <NodeInstanceuri="c2"/> </NodeInstances>

  20. Example 4 The following request filters from the specific service instance …/314 all node instance identifiers of all node templates of the topology template. GET /NodeTemplateInstances ?ServiceInstanceID=http://www.sample.com/314 HTTP/1.1 Accept: application/xml Response 4: All node instance identifiers of all node templates are returned. Note that the node template IDs of the returned node instance identifiers are returned too to allow an identification of the node templates of each node instance identifier returned. HTTP/1.1 200 OK <NodeInstances> ... <NodeInstanceNodeTemplateID="C" uri="c1"/> <NodeInstanceNodeTemplateID="C" uri="c2"/> <NodeInstanceNodeTemplateID="..." uri="..."/> ... </NodeInstances>

  21. Example 5 The following request checks whether the node instance of ID a1 is in state “running”. GET /NodeTemplateInstances ?ServiceInstanceID=http://www.sample.com/314 &NodeInstanceID=a1 &StateExpression="state=running" HTTP/1.1 Accept: application/xml Response 5: Because node instance of ID a1 is in fact in state ‘running’ its node instance identifier is returned. HTTP/1.1 200 OK <NodeInstances> <NodeInstanceuri="a1"/> </NodeInstances>

  22. Example 6 The following request filters from the specific service instance …/314 all node instance identifiers reachable from all instances of node template A via relationship R1 followed by relationship R2 that are either in state ‘running’ or in state ‘terminated’. GET /NodeTemplateInstances ?ServiceInstanceID=http://www.sample.com/314 &NodeTemplateID=A &PathExpression=R1/R2 &StateExpression="state=running OR state=terminated" HTTP/1.1 Accept: application/xml Response 6: Assume that instance c1 of node template C is starting (i.e. is does not satisfy the state expression), but instance c2 of node template C is in state ‘terminated’. Thus, only the identifier of node instance c2 is returned. HTTP/1.1 200 OK <NodeInstances> <NodeInstanceuri="c2"/> </NodeInstances>

  23. Retrieve Artifacts of a Node Template • Description: Retrieve deployment artifacts or implementation artifacts of a node template. • GET /Artifacts • ?NodeTemplateID=ID • &ArtifactType=[Implementation | Deployment ] • &Name=string • The parameters of the query string are: • NodeTemplateID: the identifier (xsd:ID) of the node template the artifact(s) of which are to be retrieved • ArtifactType: the type of the artifact to be retrieved, i.e. whether implementation artifacts (ArtifactType=Implementation), deployment artifacts (ArtifactType=Deployment), or both are to be retrieved. For the latter case, the ArtifactType parameter is omitted. • Name: the name of the deployment artifact to be retrieved, or the operation name of the implementation artifact to be retrieved. If the Name parameter is omitted, all artifacts of the specified ArtifactType are retrieved; otherwise, only the artifact of the specified ArtifactType and Name is retrieved.

  24. Response <Artifacts> <DeploymentArtifacts>? <DeploymentArtifactname="string" type="anyURI">+ artifactspecificcontent </DeploymentArtifact> </DeploymentArtifacts> <ImplementaionArtifacts>? <ImplementationArtifactoperationName="string" type="anyURI">+ artifactspecificcontent </ImplementationArtifact> </ImplementaionArtifacts> </Artifacts> The <Artifacts> elementhasthefollowingproperties: • DeploymentArtifacts: thiselementprovidesdeploymentartifactsofthespecifiednodetemplate. Ifthe Name parameterhadbeenspecified in thequerystringoftherequestthereturneddeploymentartifact will beofthatname. • ImplementationArtifacts: thiselementprovidesimplementationartifactsofthespecifiednodetemplate. Ifthe Name parameterhadbeenspecified in thequerystringoftherequestthereturnedimplementationartifacts will bethoseofthecorrespondingoperationname (note, thatmorethanoneimplementationartifactsassociatedwiththe same operationnameareallowed).

  25. Example

  26. Retrieve Property Values and State of a Node Instance • Description: Retrieve the values of the specified properties of a particular instance of a node template as well as its state. • GET NodeInstanceURI?PropertyList=list&State • The GET request is on the node instance resource identified by its actual NodeInstanceURI. The parameters supported are: • PropertyList: the list of parameters the values of which are to be retrieved. • In case the PropertyList is not specified at all, none of the property values are returned. • In case no “=list” is specified for the PropertyList parameter, all property values are returned. • State: if specified the state value of the node instance is requested • In case this parameter is not specified, no state information is returned.

  27. Response • <Properties> • XML fragment • </Properties>? • <State timestamp="xsd:dateTime"> • state • </State>? • The response message contains a properties element or a state element. • The <Properties> element has the following properties: • XML fragment: the XML document corresponding to the properties to be retrieved. • The <State> element contains a string representing the actual state of the node instance. • Its dateTime attribute can be used to heuristically decide on the timeliness of the state returned.

  28. Example 1 The following request retrieves the value of the IPAddress and CPUSpeed property of the node instance with the URI http://www.sample.com/appScrMember1. GET http://www.sample.com/appScrMember1 ?PropertyList=IPAddress+CPUSpeed HTTP/1.1 Accept: application/xml Response 1: The response contains the actual values of the properties requested. HTTP/1.1 200 OK Cache-Control: max-age=0 <Properties> <IPAddress>1.2.3.4</IPAddress> <CPUSpeed>2.7GHz</CPUSpeed> </Properties>

  29. Example 2 The following request retrieves the state of the node instance of URI http://www.sample.com/appScrMember1. GET http://www.sample.com/appScrMember1?State HTTP/1.1 Accept: application/xml Response 2: The state of the node instance is ‘running’, i.e. the corresponding value is returned. HTTP/1.1 200 OK Cache-Control: max-age=0 <State>running</State>

  30. Example 3 The following request retrieves the values of all properties of the node instance of URI http://www.sample.com/appScrMember1. GET http://www.sample.com/appScrMember1?PropertyList HTTP/1.1 Accept: application/xml Response 3: All property values are returned. HTTP/1.1 200 OK <Properties> <IPAddress>1.2.3.4</IPAddress> <CPUSpeed>2.7GHz</CPUSpeed> <HostName>myHost</HostName> ... </Properties>

  31. Create an Instance of a Service Template

  32. Response <ServiceInstanceURI/>? The <ServiceInstanceURI> element contains the URI representing the identifier of the service instance created. If an error occurs, no service instance URI is returned

  33. Example Example: POST /ServiceInstances ?ServiceTemplateID=http://www.sample.com/314 &NTID=A&CARD=7&NTID=B&CARD=0 HTTP/1.1 Accept: application/xml This requests the creation of an instance of the service template with the specified identifier. Node template A is to be instantiated seven times, while node template B is not to be instantiated at all. Resonse HTTP/1.1 201 Created <ServiceInstanceURI> http://www.ibm.com/websphereCluster42 </ServiceTemplateURI>

  34. Create an Instance of a Node Template (i.e. a Create a Node Instance) • Description: Create an instance of a node template considering the cardinality of the node template as specified in the topology template. • This request will instantiate a node template. The number of instances to be created can be specified. Typically, this request will be used in plans different from build plans and termination plans. • POST /NodeInstances • ?ServiceInstanceID=URI • &NodeTemplateID=ID • &ParentNodeInstanceID=URI • The parameters of this request are: • ServiceInstanceID: the identifier (URI) of the service instance • NodeTemplateID: the identifier (xsd:ID) of the node template the path expression starts with • ParentNodeInstanceID: the identifier of the node instance of the parent node template. This parameter is optional; is must be specified in case the node template to be instantiated is a child of a node template of variable cardinality.

  35. Response <NodeInstanceURI/>? The <NodeInstanceURI> element contains the URI representing the identifier of the node instance created. If an error occurs, no node instance URI is returned Status Codes: 201 Created - The request to create a new resource has been processed correctly. The Location header contains the URI of the created resource. The Content-Type header contains the media type of this resource. An ETag header might be returned too. …

  36. Example POST /NodeInstances ?ServiceInstanceID=http://www.sample.com/271 &NodeTemplateID=C &ParentNodeInstanceID=b2 HTTP/1.1 Accept: application/xml This requests the creation of an instance of the node template C. Because the parent node template of C (with node template identifier B) is a multi-instance node, the identifier of the instance of B under which the new instance of C has to be created must be specified. In the example, the new instance of C should be created as child of node instance b2. The newly created instance of C has identifier c3. Response: HTTP/1.1 201 Created <NodeInstanceuri="c3"/>

  37. Update Values of Properties and State of a Node Instance • Description: Modify the properties of a particular node instance or its state. • PUT /NodeInstanceURI? • ... • ModifiedResource • The parameters of this request are:NodeInstanceURI: the identifier (URI) of the node instance to be modified. • The HTTP body of this request is:ModifiedResource: the modified properties or state of the node instance encoded in the HTTP body of the request. • Either the <Properties> element or the <State> element (or both) must be specified in the HTTP body. • HTTP Body: • <Properties> • XML fragment • </Properties>? • <State> • state • </State>? • The HTTP body contains a properties element or a state element. • The <Properties> element has the following value: • XML fragment: the XML document corresponding to the properties to be substituted. This XML document is an instance of the node type properties element of the corresponding node type. Thus, the processor of this request will validate the XML document provided; in case of the validation resulting in an error, a corresponding HTTP error code will be returned. • The <State> element contains a string representing the modified state of the node instance.

  38. Example PUT http://www.sample.com/appScrMember1 HTTP/1.1 Content-Type: application/xml ... <Properties> <IPAddress>3.1.4.1</IPAddress> <CPUSpeed>2.0GHz</CPUSpeed> <HostName>ThomasHost</HostName> ... </Properties> <State>running</State> HTTP/1.1 200 OK

  39. Delete a Node Instance Description: Delete an instance of a node template. DELETE NodeInstanceURI The node instance identified by the specified URI is deleted. In case the node instance to be deleted is a child of a multi instance node and the deletion would result in a violation of the minimum number of instances of the parent node, the deletion is not performed and a corresponding HTTP error is returned.

  40. Delete a Service Instance Description: Delete an instance of a service template. DELETE ServiceInstanceURI The service instance identified by the specified URI is deleted.

  41. End ofpresentation

More Related