Controller Blueprint Archive (.cba)

The Controller Blueprint Archive is the overall service design, fully model-driven, intent based package needed for provisioning and configuration management automation.

The CBA is .zip file, comprised of the following folder structure, the files may vary:

├── Definitions
│   ├── blueprint.json							Overall TOSCA service template (workflow + node_template)
│   ├── artifact_types.json 					(generated by enrichment)
│   ├── data_types.json 						(generated by enrichment)
│   ├── policy_types.json 						(generated by enrichment)
│   ├── node_types.json 						(generated by enrichment)
│   ├── relationship_types.json 				(generated by enrichment)
│   ├── resources_definition_types.json 		(generated by enrichment)
|   └── *-mapping.json							One per Template
├── Environments								Contains *.properties files as required by the service
├── Plans										Contains Directed Graph
├── Tests										Contains uat.yaml file for testing cba actions within a cba package 
├── Scripts										Contains scripts
│   ├── python					 				Python scripts
│   └── kotlin									Kotlin scripts
├── TOSCA-Metadata
│   └── TOSCA.meta								Meta-data of overall package
└── Templates									Contains combination of mapping and template

To process a CBA for any service we need to enrich it first. This will gather all the node-type, data-type, artifact-type, data-dictionary definitions provided in the blueprint.json.

Tosca Meta

Tosca meta file is captures the model entities that compose the cba package name, version, type and searchable tags. 

Template Type Reference

Default Template Type

https://git.onap.org/ccsdk/cds/tree/components/model-catalog/blueprint-model/test-blueprint/capability_cli/TOSCA-Metadata/TOSCA.meta

KOTLIN_DSL Template Type

https://git.onap.org/ccsdk/cds/tree/components/model-catalog/blueprint-model/test-blueprint/resource-audit/TOSCA-Metadata/TOSCA.meta

GENERIC_SCRIPT Template Type

https://git.onap.org/ccsdk/cds/tree/components/model-catalog/blueprint-model/test-blueprint/capability_python/TOSCA-Metadata/TOSCA.meta

Dynamic payload

One of the most important API provided by the run time is to execute a CBA Package.

The nature of this API request and response is model driven and dynamic.

Here is how the a generic request and response look like.

{
  "commonHeader": {
    "originatorId": "",
    "requestId": "",
    "subRequestId": ""
  },
  "actionIdentifiers": {
    "blueprintName": "",
    "blueprintVersion": "",
    "actionName": "",
    "mode": ""
  },
  "payload": {
    "$actionName-request": {
      "$actionName-properties": {
      }
    }
  }
}

{
  "commonHeader": {
    "originatorId": "",
    "requestId": "",
    "subRequestId": ""
  },
  "actionIdentifiers": {
    "blueprintName": "",
    "blueprintVersion": "",
    "actionName": "",
    "mode": ""
  },
  "payload": {
    "$actionName-response": {
    }
  }
}

The actionName, under the actionIdentifiers refers to the name of a Workflow (see Modeling Concepts#workflow)

The content of the payload is what is fully dynamic / model driven.

The first top level element will always be either $actionName-request for a request or $actionName-response for a response.

Then the content within this element is fully based on the workflow inputs and outputs.

During the Enrichment, CDS will aggregate all the resources defined to be resolved as input, within mapping definition files, as data-type, that will then be use as type of an input called $actionName-properties.

Enrichment

The idea is that the CBA is a self-sufficient package, hence requires all the various types definition its using.

Reason for this is the types its using might evolve. In order for the CBA to be bounded to the version it has been using when it has been designed, these types are embedded in the CBA, so if they change, the CBA is not affected.

The enrichment process will complete the package by providing all the definition of types used:

• gather all the node-type used and put them into a node_types.json file
• gather all the data-type used and put them into a data_types.json file
• gather all the artifact-type used and put them into a artifact_types.json file
• gather all the data dictionary definitions used from within the mapping files and put them into a resources_definition_types.json file

The enrichment can be run using REST API, and required the .zip file as input. It will return an enriched-cba.zip file.

curl -X POST \
  'http://{{ip}}:{{cds-designtime}}/api/v1/blueprint-model/enrich' \
  -H 'content-type: multipart/form-data' \
  -F file=@cba.zip

The enrichment process will also, for all resources to be resolved as input and default:

• dynamically gather them under a data-type, named dt-${actionName}-properties
• will add it as a input of the workflow, as follow using this name: ${actionName}-properties

Example for workflow named resource-assignment:

  "resource-assignment-properties": {
    "required": true,
    "type": "dt-resource-assignment-properties"
  }

External Systems support

Interaction with external systems is made dynamic, removing development cycle to support new endpoint.

In order to define the external system information, TOSCA provides dsl_definitions. Link to TOSCA spec info 1, info 2.


Use cases:

• Resource resolution using Modeling Concepts#REST or Modeling Concepts#SQL external systems
• gRPC is supported for remote execution
• Any REST endpoint can be dynamically injected as part of the scripting framework.

Here are some examples on how to populate the system information within the package:

{
  . . .
  "dsl_definitions": {
    "ipam-1": {
      "type": "token-auth",
      "url": "http://netbox-nginx.netprog:8080",
      "token": "Token 0123456789abcdef0123456789abcdef01234567"
    }
  }
  . . .
}

{
  . . .
  "dsl_definitions": {
    "ipam-1": {
      "type": "basic-auth",
      "url": "http://localhost:8080",
      "username": "bob",
      "password": "marley"
    }
  }
  . . .
}

{
  . . .
  "dsl_definitions": {
    "ipam-1": {
      "type" : "ssl-basic-auth",
      "url" : "http://localhost:32778",
      "keyStoreInstance": "JKS or PKCS12",
      "sslTrust": "trusture",
      "sslTrustPassword": "trustore password",
      "sslKey": "keystore",
      "sslKeyPassword: "keystore password"
    }
  }
  . . .
}

{
  . . .
  "dsl_definitions": {
    "remote-executor": {
      "type": "token-auth",
      "host": "cds-command-executor.netprog",
      "port": "50051",
      "token": "Basic Y2NzZGthcHBzOmNjc2RrYXBwcw=="
    }
  }
  . . .
}

{
  . . .
  "dsl_definitions": {
    "netprog-db": {
      "type": "maria-db",
      "url": "jdbc:mysql://10.195.196.123:32050/netprog",
      "username": "netprog",
      "password": "netprog"
    }
  }
  . . .
}

Expression

TOSCA provides for a set of functions to reference elements within the template or to retrieve runtime values.

Below is a list of supported expressions

"resolution-key": {
  "get_input": "resolution-key"
}

"get_attribute": [
  "resource-assignment",
  "assignment-params"
]

Data Dictionary

A data dictionary models the how a specific resource can be resolved.

A resource is a variable/parameter in the context of the service. It can be anything, but it should not be confused with SDC or Openstack resources.

A data dictionary can have multiple sources to handle resolution in different ways.

The main goal of data dictionary is to define re-usable entity that could be shared.

Creation of data dictionaries is a standalone activity, separated from the blueprint design.

As part of modelling a data dictionary entry, the following generic information should be provided:

Bellow are properties that all the resource source can have

The modeling does allow for data translation between external capability and CDS for both input and output key mapping.

Example:
vf-module-model-customization-uuid and vf-module-label are two data dictionaries. A SQL table, VF_MODULE_MODEL, exist to correlate them.

Here is how input-key-mapping, output-key-mapping and key-dependencies can be used:

{
  "name" : "vf-module-label",
  "tags" : "vf-module-label",
  "updated-by" : "adetalhouet",
  "property" : {
    "description" : "vf-module-label",
    "type" : "string"
  },
  "sources" : {
    "primary-db" : {
      "type" : "source-primary-db",
      "properties" : {
        "type" : "SQL",
        "query" : "select sdnctl.VF_MODULE_MODEL.vf_module_label as vf_module_label from sdnctl.VF_MODULE_MODEL where sdnctl.VF_MODULE_MODEL.customization_uuid=:customizationid",
        "input-key-mapping" : {
          "customizationid" : "vf-module-model-customization-uuid"
        },
        "output-key-mapping" : {
          "vf-module-label" : "vf_module_label"
        },
        "key-dependencies" : [ "vf-module-model-customization-uuid" ]
      }
    }
  }
}

Data type

Represents the schema of a specific type of data.

Supports both primitive and complex data types:

For complex data type, an entry schema is required, defining the type of value contained within the complex type, if list or array.

Users can create as many data type as needed.

Data type are useful to manipulate data during resource resolution. They can be used to format the JSON output as needed.

List of existing data type: https://github.com/onap/ccsdk-cds/tree/master/components/model-catalog/definition-type/starter-type/data_type

TOSCA specification

Below is a list of existing data types

{
	"version": "1.0.0",
	"description": "This is Resource Assignment Data Type",
	"properties": {
		"property": {
			"required": true,
			"type": "datatype-property"
		},
		"input-param": {
			"required": true,
			"type": "boolean"
		},
		"dictionary-name": {
			"required": false,
			"type": "string"
		},
		"dictionary-source": {
			"required": false,
			"type": "string"
		},
		"dependencies": {
			"required": true,
			"type": "list",
			"entry_schema": {
				"type": "string"
			}
		},
		"updated-date": {
			"required": false,
			"type": "string"
		},
		"updated-by": {
			"required": false,
			"type": "string"
		}
	},
	"derived_from": "tosca.datatypes.Root"
}

{
  "version": "1.0.0",
  "description": "This is Entry point Input Data Type, which is dynamic datatype, The parameter names will be populated during the Design time for each inputs",
  "properties": {
    "type": {
      "required": true,
      "type": "string"
    },
    "description": {
      "required": false,
      "type": "string"
    },
    "required": {
      "required": false,
      "type": "boolean"
    },
    "default": {
      "required": false,
      "type": "string"
    },
    "entry_schema": {
      "required": false,
      "type": "string"
    }
  },
  "derived_from": "tosca.datatypes.Root"
}

Artifact Type

Represents the type of a artifact, used to identify the implementation of the functionality supporting this type of artifact.

TOSCA definition

This node was created, derived from tosca.artifacts.Root to be the root TOSCA node for all artifact.


{
  "description": "TOSCA base type for implementation artifacts",
  "version": "1.0.0",
  "derived_from": "tosca.artifacts.Root"
}

Bellow is a list of supported artifact types

{
  "description": " Velocity Template used for Configuration",
  "version": "1.0.0",
  "file_ext": [
    "vtl"
  ],
  "derived_from": "tosca.artifacts.Implementation"
}

{
  "description": " Jinja Template used for Configuration",
  "version": "1.0.0",
  "file_ext": [
    "jinja"
  ],
  "derived_from": "tosca.artifacts.Implementation"
}

{
  "description": "Resource Mapping File used along with Configuration template",
  "version": "1.0.0",
  "file_ext": [
    "json"
  ],
  "derived_from": "tosca.artifacts.Implementation"
}

{
  "description": "Directed Graph File",
  "version": "1.0.0",
  "file_ext": [
    "json",
    "xml"
  ],
  "derived_from": "tosca.artifacts.Implementation"
}