Relationship

This document describes how a relationship can be established between resources of different APS types.

Note

It is not possible to provision an application without a resource relationship.

• Relation in an APS type is a description of possible links between APS resources.

• Link is a connection between two APS resources at runtime done through a declared relation.

Overview

When planning an APS package for a cloud application, keep in mind the following practical key points:

• The application itself must be always represented by an APS resource instantiated from the special Application APS type and available to all customers. It belongs to the provider, and all other resources of this application relate to it directly or indirectly. This APS resource represents an APS application instance.

• To provision some resources, the provider often creates a set of offers (also known by other names, for example, samples or service profiles) used to create resources for customers. For example, a VPS offer can specify a set of parameters for virtual private servers. Such offers must relate with the Application resource.

• A customer must have an automatically provisioned management resource (a kind of sand-box or shell) that can be named differently in different packages, for example, Context, or Tenant, or Identity. Such a management context must implement the SubscriptionService type and linked with the Application, Account, and Subscription resources.

• Customer resources created from an offer must keep a relation with the offer. In addition, all customer resources relate with the customer context directly or indirectly.

Some examples in this specification will be based on the following resource model diagram illustrating the resource relations for a demo application named VPScloud.

In the diagram, there are four APS types (clouds, offers, contexts, and vpses) and the relations between them. For example, the resources based on the cloud and offer APS types are related as follows:

• The offers relation is used for creating a collection of links from the application to offers.

• The cloud is a backward single relation between an offer and the cloud resource.

  The offers and cloud relations define the same links, but on the opposite sides.

The Application Resource here is called cloud and it has the relations described in the clouds.schema file as follows:

"relations": {
   "offers": {
       "type": "http://examples.apsdemo.org/vpscloud/offers/1.0",
       "collection": true
   },
   "contexts": {
       "type": "http://examples.apsdemo.org/vpscloud/contexts/1.0",
       "collection": true
   }
}

Attributes

Each relation can have the following attributes:

Attribute	Required?	Value	Default	Example
name	Yes	string	N/A	“vpses”:
type	Yes	string	N/A	“type”: “http://examples.apsdemo.org/vpscloud/vpses/1.0”
collection	-	boolean	false	“collection”: true
required	-	boolean	false	“required”: true
requirement	-	RQL expression	null	“requirement”: [ “version >= 2.0” ]
defaults	-	JSON object	null	“defaults”: { “prefix”: “somevalue”, “some-attribute”: { “with-complex-value” }}
allocate	-	“new”, “existing”, “any”	“any”	“allocate”: “new”

name

Value: string

Default: N/A

Each relation must have a unique (case-sensitive) name that matches the following pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$. The name cannot coincide with any property name and is used to refer to the links in the resource representation:

{
   "properties": {
      // None of the properties could be named "samples" since there is a relation with that name
   },
   "relations": {
      "samples": {  // <<<< definition of a relation with name "samples" starts here
         // ...
      }
   }
}

type

Value: string

Default: N/A

This attribute defines either a single APS type or an array of APS types that must be implemented by the Resource on the other side of the link.

In the following example, the relation defines a link “db” to the database APS type:

"relations": {
    "db": {
        // Another side of the link must implement this Type:
        "type": "http://aps-standard.org/types/infrastructure/database"
    }
}

Note

The other side of the link can actually be http://aps-standard.org/types/infrastructure/mysql or another type that implements the http://aps-standard.org/types/infrastructure/database type.

Another example is a requirement for the other side of the link to implement multiple APS types:

{
   "relations": {
       "env": {
           "type": [
               // Another side of the link must implement both required Types:
               "http://aps-standard.org/types/infrastructure/environment/php/1.0",
               "http://aps-standard.org/types/infrastructure/environment/web/1.0"
           ]
       }
   }
}

Note

In the type property, you can specify an APS type either without a version, with the full version, or with the major version only. Follow the Version Compatibility recommendations to choose the correct way.

collection

Value: boolean

Default: false

This attribute allows you to define if this relation supports multiple links or single link only. A relation that supports multiple links is usually referred to as a collection. A relation that can only have a single link is called singular.

In the above diagram, the vpses relation is a collection, meaning many VPSes can be based on the same offer.

"vpses": {
    "type": "http://examples.apsdemo.tst/vpscloud/vpses/1.0",
    "collection": true
}

required

Value: boolean

Default: false

This attribute explicitly defines whether this relation is required or optional. A required relation must be established during resource provisioning and cannot be removed while the resource exists. Required relations are also known as strong relations. Optional relations are also known as weak relations.

In the above diagram, an offer has a strong relation with the Application and weak relations with VPSes:

"relations": {
    "cloud": {
       "type": "http://techdoc.apsdemo.tst/vpscloud/cloudes/1.1",
       "required": true,
       "collection": false
    },
    "vpses": {
       "type": "http://techdoc.apsdemo.tst/vpscloud/vpses/1.0",
       "collection": true
    }
}

Note

There are several specifics regarding this attribute:

• A required collection means that at least one element must be in that collection.

• All required relations are satisfied prior to the execution of the resource provisioning method.

• The “required”:true attribute is allowed only on one side of a relation.

requirement

Value: RQL expression

Default: null

A relation may define which conditions must be met by a resource on the other side of the link. These conditions are expressed by means of the Resource Query Language (RQL).

This allows you to require a particular version of the database in the following example:

{
   "relations": {
       "db": {
           "type": "http://aps-standard.org/types/infrastructure/database",
           "collection": false,
           "required": true,

           // Version of the database must be at least 2.0
           "requirement": [
               "version =ge= 2.0"
           ]

           ...
       }
   }
}

Note

Each line of the “requirement” array is treated as a single expression combined with the other expressions using the AND (‘&’) operator.

defaults

Value: JSON object

Default: null

The optional attribute defaults allows you to define values that must be assigned to some of the resource properties on the other side of the link if that resource will be automatically provisioned to satisfy the relation requirement.

The default values are defined as a JSON object:

{
   "relations": {
       "db": {
           "type": "http://aps-standard.org/types/infrastructure/database",
           "collection": false,
           "required": true,
           "requirement": [
               "version =ge= 2.0"
           ],
           // If the DB resource is being provisioned, assign these default values to it:
           "defaults": {
               "prefix": "somevalue",
               "some-attribute": { "with-complex-value" }
           }
           ...
       }
   }
}

allocate

Value: “new”, or “existing”, or “any”

Default: “any”

This attribute allows you to define an allocation policy the APS controller will use to satisfy strong (that is, "required":true) relations. You can assign one of the following values to it:

• new forces unconditional allocation of a new resource.

• existing forces the use of an existing resource. If no matching resources are found, it generates an error.

• any tries to use the “existing” policy and forces the “new” in case of failure.

{
   "relations": {
       "db": {
           "type": "http://aps-standard.org/types/infrastructure/database",
           "collection": false,
           "required": true,
           "requirement": [
               "version =ge= 2.0"
           ],
           "defaults": {
               "prefix": "somevalue",
               "some-attribute": { "with-complex-value" }
           },

           // Aways allocate a new Database:
           "allocate": "new"
       }
   }
}

Note

The application update may affect resource relations as specified in the Update Process section.

← Properties

Operations →