Data Types
data_types
are useful for grouping and re-using a common set of properties, together with their types and default values.
Supported Definitions
To use data_types
, the definitions version must be cloudify_dsl_1_2
or higher.
Declaration
data_types:
data_type1:
description: ...
properties: ...
data_type2:
derived_from: data_type1
description: ...
properties: ...
Schema
Keyname | Required | Type | Description |
---|---|---|---|
description | no | string | Description for the data type. |
properties | no | dictionary | Dictionary of the data type properties. |
derived_from | no | string | Parent data type. |
description
This property can be used to describe the data type.
properties
The properties
property is used to define the data type schema.
properties
is a dictionary from a property name to a dictionary describing the property.
Property Schema:
Keyname | Required | Type | Description |
---|---|---|---|
description | no | string | Description for the property. |
type | no | string | Property type. If you do not specify a data type, the type can be anything (including types not listed in the valid types). Valid types: string, integer, float, boolean or a another custom data type. |
default | no | <any> | An optional default value for the property. |
required | no | boolean | Specifies whether the property is required. (Default: true , Supported since: cloudify_dsl_1_2) |
derived_from
The derived_from
property can be used to build over and extend an existing data type.
When a data type derives from another data type, its properties
are merged with the parent’s properties
. The merge is at the property level. A property defined on the parent type is overridden by a property with the same name that is defined on the deriving type. An exception to this rule is when a property type
references some other custom data type. This is explained in detail in the following examples.
Features and Examples
Basic Usage
In this example, a my.datatypes.Endpoint
data type is defined with two properties: ip
and port
.
The, a DatabaseService
node type is defined to represent an external database service. In this type’s properties, an endpoint
property is defined, it’s type being the endpoint data type that was previously defined. Finally, a node template with a DatabaseService
type is defined. This node template fully configures the endpoint properties (i.e. the ip
and port
).
tosca_definitions_version: cloudify_dsl_1_2
data_types:
my.datatypes.Endpoint:
description: Socket endpoint details
properties:
ip:
description: the endpoint IP
type: string
port:
description: the endpoint port
type: integer
node_types:
DatabaseService:
derived_from: cloudify.nodes.DBMS
properties:
endpoint:
type: my.datatypes.Endpoint
node_templates:
my_db_service:
type: DatabaseService
properties:
endpoint:
ip: 192.168.15.85
port: 2233
Schema Validations
If a property is missed or an additional property spcified under endpoint
, the blueprint will fail validation. For example
node_templates:
my_db_service2:
type: DatabaseService
properties:
endpoint:
ip: 192.168.15.85
will fail validation because of the missing port
property. (Note that if port
had its required
attribute set to false
, there would not be a validation failure.)
Similarly,
node_templates:
my_db_service3:
type: DatabaseService
properties:
endpoint:
ip: 192.168.15.85
port: 2233
some_other_property: the_value
will fail validation because of the unexpected some_other_property
, which is not specified in endpoint
’s schema.
Inheritance
You can derive from previously-defined data types, to extend their schema. For example, consider the my.datatypes.Endpoint
defined in the previous example. You can derive from it, to create an endpoint data type that also includes a user name, as shown below.
tosca_definitions_version: cloudify_dsl_1_2
data_types:
my.datatypes.Endpoint:
...
my.datatypes.ExtendedEndpoint:
derived_from: my.datatypes.Endpoint
properties:
username:
description: Username used to connect to the endpoint
type: string
node_types:
DatabaseService:
derived_from: cloudify.nodes.DBMS
properties:
endpoint:
type: my.datatypes.ExtendedEndpoint
node_templates:
my_db_service:
type: DatabaseService
properties:
endpoint:
ip: 192.168.15.85
port: 2233
username: jimmy
Composition
Data type property types can themselves be other data types. Using the previously defined my.datatypes.Endpoint
, in the following example, a my.datatypes.Connection
is created that will hold endpoint information and authentication details.
tosca_definitions_version: cloudify_dsl_1_2
data_types:
my.datatypes.Endpoint:
...
my.datatypes.Connection:
properties:
endpoint:
type: my.datatypes.Endpoint
auth:
type: my.datatypes.Auth
my.datatypes.Auth:
properties:
username:
type: string
password:
type: string
node_types:
DatabaseService:
derived_from: cloudify.nodes.DBMS
properties:
connection:
type: my.datatypes.Connection
node_templates:
my_db_service:
type: DatabaseService
properties:
connection:
endpoint:
ip: 192.168.15.85
port: 2233
auth:
username: jimmy
password: secret
Default Values
Default values can help make highly configurable components easy to use by setting default values where it is logical to do so. Consider the previously defined my.datatypes.Connection
. Its usage can be simplified if, for example, you know that port
by default will be 2233
and username by default will be admin
.
tosca_definitions_version: cloudify_dsl_1_2
data_types:
my.datatypes.Connection:
properties:
endpoint:
type: my.datatypes.Endpoint
auth:
type: my.datatypes.Auth
my.datatypes.Endpoint:
description: Socket endpoint details
properties:
ip:
description: the endpoint IP
type: string
port:
default: 2233
type: integer
my.datatypes.Auth:
properties:
username:
default: admin
type: string
password:
type: string
node_types:
DatabaseService:
derived_from: cloudify.nodes.DBMS
properties:
connection:
type: my.datatypes.Connection
node_templates:
my_db_service:
type: DatabaseService
properties:
connection:
endpoint:
ip: 192.168.15.85
auth:
password: secret
Notice how the my_db_service
node template only specified the connection.endpoint.ip
and connection.auth.password
. The other properties received the default 2233
port and admin
user.
Overriding Default Values
You can override default values in same way as you would configure properties without default values. For example:
node_templates:
my_db_service:
type: DatabaseService
properties:
connection:
endpoint:
ip: 192.168.15.85
port: 2244
auth:
password: secret
In the example, the default connection.endpoint.port
value is replaced and the default connection.auth.username
value is retained.
Nested Merging Semantics
Data Types, Node Types, and Node Template
In this example, a data type datatypes.Data1
is defined with three properties that have their default values set.
Next, a node type nodes.MyApp
that has a data1
property of type datatypes.Data1
is defined. In this type, the single nested property prop2
of the data1
property is overridden. Finally, a node template my_app
of type nodes.MyApp
is configured. This node template overrides another single nested property, prop3
of the data1
property.
tosca_definitions_version: cloudify_dsl_1_2
data_types:
datatypes.Data1:
properties:
prop1:
default: prop1_default
prop2:
default: prop2_default
prop3:
default: prop3_default
node_types:
nodes.MyApp:
properties:
data1:
type: datatypes.Data1
default:
prop2: prop2_override
node_templates:
my_app:
type: nodes.MyApp
properties:
data1:
prop3: prop3_override
After the blueprint is parsed, the my_app
node template properties will be:
data1:
prop1: prop1_default
prop2: prop2_override
prop3: prop3_override
This also applies for compound data types, for example:
data_types:
datatypes.Data1:
...
datatypes.Data2:
properties:
data1:
type: datatypes.Data1
default:
prop2: prop2_override
In which case, datatypes.Data2
’s data1
property default value will be:
data1:
prop1: prop1_default
prop2: prop2_override
prop3: prop3_default
Nested Merging and Inheritance
When a node type derives from another node type, if it overrides a property that has a custom data type and it keeps that type explicitly, a similar nested merging logic will apply, as described previously. For example:
tosca_definitions_version: cloudify_dsl_1_2
data_types:
datatypes.Data1:
properties:
prop1:
default: prop1_default
prop2:
default: prop2_default
prop3:
default: prop3_default
node_types:
nodes.MyApp:
properties:
data2:
type: datatypes.Data1
default:
prop2: prop2_override
nodes.DerivedFromMyApp:
derived_from: nodes.MyApp
properties:
data2:
type: datatypes.Data1
default:
prop3: prop3_override
node_templates:
my_app:
type: nodes.DerivedFromMyApp
After the blueprint is parsed, the my_app
node template properties will be:
data1:
prop1: prop1_default
prop2: prop2_override
prop3: prop3_override
The nested merging semantics described in the previous section have not yet been defined in the TOSCA simplified YAML profile.