Previous topic

Properties

Next topic

Operations

DOCUMENTATION
Last updated 12-Sep-2016

Relations

This section describes relations that can be established between resources of different Types.

Note

It is not possible to provision an application without resource relations.

  • Relation is a description of a possible Link between resources.
  • Link is a connection between two resources at runtime done through a Relation.

Overview

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

  • Application itself must be always represented by a special Application resource shared for all customers. It belongs to the provider, and all other resources of this application relate with it directly or indirectly.
  • To provision some resources, the provider often creates a set of offers (also known by other names, e.g. samples) used for creating resources for customers. For example, a VPS offer would 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 (kind of sand-box or shell) that can be named differently in different packages, e.g. Context, or Tenant, or Identity. Such a management context must be bound to the Application, Account, and Subscription resources.
  • Customer resources created from an offer must keep 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 diagram illustrating the resource relations for a demo application named VPScloud.

../../../_images/type-resource-relations.png

There are four types (clouds, offers, contexts, and vpses) and relations between them, e.g.:

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

  • The cloud is a single relation between a sample and the cloud resource.

    The offers and cloud relations present 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” ]
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" !
},
"relations": {
   "samples": {  // <<<< definition of a relation with name "samples" starts here
   ...
}

type

Value: string
Default: N/A
This attribute defines either a single Type or an array of 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 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 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"
           ]
       }
   }
}

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 if this relation is required or optional. A required relation must be established during resource provisioning and cannot be removed when 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 a number of 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.
../../../_images/relations-overview-3.png

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 us 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 via the AND (‘&’) operator.

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 (i.e. “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"
       }
   }
}

See also

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