diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/API.md | 528 | ||||
| -rw-r--r-- | docs/DatabaseTables.md | 101 | ||||
| -rw-r--r-- | docs/Deployment.md | 39 | ||||
| -rw-r--r-- | docs/Design.md | 142 | ||||
| -rw-r--r-- | docs/Upgrade.md | 13 | ||||
| -rw-r--r-- | docs/images/dcae_inventory_communication.png | bin | 0 -> 36079 bytes |
6 files changed, 823 insertions, 0 deletions
diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..a6f0472 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,528 @@ +# DCAE Inventory API + + +<a name="overview"></a> +## Overview +DCAE Inventory is a web service that provides the following: + +1. Real-time data on all DCAE services and their components +2. Comprehensive details on available DCAE service types + + +### Version information +*Version* : 2.1.0 + + +### Contact information +*Contact Email* : dcae@lists.openecomp.org + + + + +<a name="paths"></a> +## Paths + +<a name="dcaeservicetypestypenameput"></a> +### POST /dcae-service-types + +#### Description +Inserts a new `DCAEServiceType` or updates an existing instance. Updates are only allowed iff there are no running DCAE services of the requested type, + + +#### Parameters + +|Type|Name|Description|Schema|Default| +|---|---|---|---|---| +|**Body**|**body** <br>*required*||[DCAEServiceTypeRequest](#dcaeservicetyperequest)|| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|Single `DCAEServiceType` object.|[DCAEServiceType](#dcaeservicetype)| +|**400**|Bad request provided.|[ApiResponseMessage](#apiresponsemessage)| +|**409**|Failed to update because there are still DCAE services of the requested type running.|[ApiResponseMessage](#apiresponsemessage)| + + +#### Consumes + +* `application/json` + + +#### Produces + +* `application/json` + + +<a name="dcaeservicetypesget"></a> +### GET /dcae-service-types + +#### Description +Get a list of `DCAEServiceType` objects. + + +#### Parameters + +|Type|Name|Description|Schema|Default| +|---|---|---|---|---| +|**Query**|**asdcResourceId** <br>*optional*|Filter by associated asdc design resource id. Setting this to `NONE` will return instances that have asdc resource id set to null|string|| +|**Query**|**asdcServiceId** <br>*optional*|Filter by associated asdc design service id. Setting this to `NONE` will return instances that have asdc service id set to null|string|| +|**Query**|**offset** <br>*optional*|Query resultset offset used for pagination (zero-based)|integer(int32)|| +|**Query**|**onlyActive** <br>*optional*|If set to true, query returns only *active* DCAE service types. If set to false, then all DCAE service types are returned. Default is true|boolean|`"true"`| +|**Query**|**onlyLatest** <br>*optional*|If set to true, query returns just the latest versions of DCAE service types. If set to false, then all versions are returned. Default is true|boolean|`"true"`| +|**Query**|**serviceId** <br>*optional*|Filter by assocaited service id. Instances with service id null or empty is always returned.|string|| +|**Query**|**serviceLocation** <br>*optional*|Filter by associated service location. Instances with service location null or empty is always returned.|string|| +|**Query**|**typeName** <br>*optional*|Filter by service type name|string|| +|**Query**|**vnfType** <br>*optional*|Filter by associated vnf type. No wildcards, matches are explicit. This field is treated case insensitive.|string|| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|List of `DCAEServiceType` objects|[InlineResponse200](#inlineresponse200)| + + +#### Consumes + +* `application/json` +* `application/vnd.dcae.inventory.v1+json` + + +#### Produces + +* `application/json` +* `application/vnd.dcae.inventory.v1+json` + + +<a name="dcaeservicetypestypeidget"></a> +### GET /dcae-service-types/{typeId} + +#### Description +Get a `DCAEServiceType` object. + + +#### Parameters + +|Type|Name|Description|Schema|Default| +|---|---|---|---|---| +|**Path**|**typeId** <br>*required*||string|| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|Single `DCAEServiceType` object|[DCAEServiceType](#dcaeservicetype)| +|**404**|Resource not found|[DCAEServiceType](#dcaeservicetype)| + + +#### Consumes + +* `application/json` + + +#### Produces + +* `application/json` + + +<a name="dcaeservicetypestypeiddelete"></a> +### DELETE /dcae-service-types/{typeId} + +#### Description +Deactivates existing `DCAEServiceType` instances + + +#### Parameters + +|Type|Name|Description|Schema|Default| +|---|---|---|---|---| +|**Path**|**typeId** <br>*required*||string|| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|`DCAEServiceType` has been deactivated|[ApiResponseMessage](#apiresponsemessage)| +|**404**|`DCAEServiceType` not found|[ApiResponseMessage](#apiresponsemessage)| +|**410**|`DCAEServiceType` already gone|[ApiResponseMessage](#apiresponsemessage)| + + +#### Consumes + +* `application/vnd.dcae.inventory.v1+json` +* `application/json` + + +#### Produces + +* `application/vnd.dcae.inventory.v1+json` +* `application/json` + + +<a name="dcaeservicesget"></a> +### GET /dcae-services + +#### Description +Get a list of `DCAEService` objects. + + +#### Parameters + +|Type|Name|Description|Schema|Default| +|---|---|---|---|---| +|**Query**|**componentType** <br>*optional*|Use to filter by a specific DCAE service component type|string|| +|**Query**|**created** <br>*optional*|Use to filter by created time|string|| +|**Query**|**offset** <br>*optional*|Query resultset offset used for pagination (zero-based)|integer(int32)|| +|**Query**|**shareable** <br>*optional*|Use to filter by DCAE services that have shareable components or not|boolean|| +|**Query**|**typeId** <br>*optional*|DCAE service type name|string|| +|**Query**|**vnfId** <br>*optional*||string|| +|**Query**|**vnfLocation** <br>*optional*||string|| +|**Query**|**vnfType** <br>*optional*|Filter by associated vnf type. This field is treated case insensitive.|string|| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|List of `DCAEService` objects|[InlineResponse2001](#inlineresponse2001)| +|**502**|Bad response from DCAE controller|[ApiResponseMessage](#apiresponsemessage)| +|**504**|Failed to connect with DCAE controller|[ApiResponseMessage](#apiresponsemessage)| + + +#### Consumes + +* `application/json` +* `application/vnd.dcae.inventory.v1+json` + + +#### Produces + +* `application/json` +* `application/vnd.dcae.inventory.v1+json` + + +<a name="dcaeservicesgroupbypropertynameget"></a> +### GET /dcae-services-groupby/{propertyName} + +#### Description +Get a list of unique values for the given `propertyName` + + +#### Parameters + +|Type|Name|Description|Schema|Default| +|---|---|---|---|---| +|**Path**|**propertyName** <br>*required*|Property to find unique values. Restricted to `type`, `vnfType`, `vnfLocation`|string|| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|List of unique property values|[DCAEServiceGroupByResults](#dcaeservicegroupbyresults)| + + +#### Consumes + +* `application/json` +* `application/vnd.dcae.inventory.v1+json` + + +#### Produces + +* `application/json` +* `application/vnd.dcae.inventory.v1+json` + + +<a name="dcaeservicesserviceidget"></a> +### GET /dcae-services/{serviceId} + +#### Description +Get a `DCAEService` object. + + +#### Parameters + +|Type|Name|Description|Schema|Default| +|---|---|---|---|---| +|**Path**|**serviceId** <br>*required*||string|| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|Single `DCAEService` object|[DCAEService](#dcaeservice)| +|**404**|DCAE service not found|[ApiResponseMessage](#apiresponsemessage)| +|**502**|Bad response from DCAE controller|[ApiResponseMessage](#apiresponsemessage)| +|**504**|Failed to connect with DCAE controller|[ApiResponseMessage](#apiresponsemessage)| + + +#### Consumes + +* `application/json` +* `application/vnd.dcae.inventory.v1+json` + + +#### Produces + +* `application/json` +* `application/vnd.dcae.inventory.v1+json` + + +<a name="dcaeservicesserviceidput"></a> +### PUT /dcae-services/{serviceId} + +#### Description +Put a new or update an existing `DCAEService` object. + + +#### Parameters + +|Type|Name|Description|Schema|Default| +|---|---|---|---|---| +|**Path**|**serviceId** <br>*required*||string|| +|**Body**|**body** <br>*required*||[DCAEServiceRequest](#dcaeservicerequest)|| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|Single `DCAEService` object|[DCAEService](#dcaeservice)| +|**422**|Bad request provided|[ApiResponseMessage](#apiresponsemessage)| + + +#### Consumes + +* `application/json` +* `application/vnd.dcae.inventory.v1+json` + + +#### Produces + +* `application/json` +* `application/vnd.dcae.inventory.v1+json` + + +<a name="dcaeservicesserviceiddelete"></a> +### DELETE /dcae-services/{serviceId} + +#### Description +Remove an existing `DCAEService` object. + + +#### Parameters + +|Type|Name|Description|Schema|Default| +|---|---|---|---|---| +|**Path**|**serviceId** <br>*required*||string|| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|DCAE service has been removed|No Content| +|**404**|Unknown DCAE service|[ApiResponseMessage](#apiresponsemessage)| + + +#### Consumes + +* `application/vnd.dcae.inventory.v1+json` +* `application/json` + + +#### Produces + +* `application/json` +* `application/vnd.dcae.inventory.v1+json` + + + + +<a name="definitions"></a> +## Definitions + +<a name="apiresponsemessage"></a> +### ApiResponseMessage + +|Name|Description|Schema| +|---|---|---| +|**code** <br>*optional*||integer(int32)| +|**message** <br>*optional*||string| +|**type** <br>*optional*||string| + + +<a name="dcaeservice"></a> +### DCAEService + +|Name|Description|Schema| +|---|---|---| +|**components** <br>*optional*||< [DCAEServiceComponent](#dcaeservicecomponent) > array| +|**created** <br>*optional*||string(date-time)| +|**deploymentRef** <br>*optional*|Reference to a Cloudify deployment|string| +|**modified** <br>*optional*||string(date-time)| +|**selfLink** <br>*optional*|Link.title is serviceId|[Link](#link)| +|**serviceId** <br>*optional*||string| +|**typeLink** <br>*optional*|Link.title is typeId|[Link](#link)| +|**vnfId** <br>*optional*||string| +|**vnfLink** <br>*optional*|Link.title is vnfId|[Link](#link)| +|**vnfLocation** <br>*optional*|Location information of the associated VNF|string| +|**vnfType** <br>*optional*||string| + + +<a name="dcaeservicecomponent"></a> +### DCAEServiceComponent + +|Name|Description|Schema| +|---|---|---| +|**componentId** <br>*required*|The id format is unique to the source|string| +|**componentLink** <br>*required*|Link to the underlying resource of this component|[Link](#link)| +|**componentSource** <br>*required*|Specifies the name of the underying source service that is responsible for this components|enum (DCAEController, DMaaPController)| +|**componentType** <br>*required*||string| +|**created** <br>*required*||string(date-time)| +|**location** <br>*optional*|Location information of the component|string| +|**modified** <br>*required*||string(date-time)| +|**shareable** <br>*required*|Used to determine if this component can be shared amongst different DCAE services|integer(int32)| +|**status** <br>*optional*||string| + + +<a name="dcaeservicecomponentrequest"></a> +### DCAEServiceComponentRequest + +|Name|Description|Schema| +|---|---|---| +|**componentId** <br>*required*|The id format is unique to the source|string| +|**componentSource** <br>*required*|Specifies the name of the underying source service that is responsible for this components|enum (DCAEController, DMaaPController)| +|**componentType** <br>*required*||string| +|**shareable** <br>*required*|Used to determine if this component can be shared amongst different DCAE services|integer(int32)| + + +<a name="dcaeservicegroupbyresults"></a> +### DCAEServiceGroupByResults + +|Name|Description|Schema| +|---|---|---| +|**propertyName** <br>*optional*|Property name of DCAE service that the group by operation was performed on|string| +|**propertyValues** <br>*optional*||< [DCAEServiceGroupByResultsPropertyValues](#dcaeservicegroupbyresultspropertyvalues) > array| + + +<a name="dcaeservicegroupbyresultspropertyvalues"></a> +### DCAEServiceGroupByResultsPropertyValues + +|Name|Description|Schema| +|---|---|---| +|**count** <br>*optional*||integer(int32)| +|**dcaeServiceQueryLink** <br>*optional*|Link.title is the DCAE service property value. Following this link will provide a list of DCAE services that all have this property value.|[Link](#link)| +|**propertyValue** <br>*optional*||string| + + +<a name="dcaeservicerequest"></a> +### DCAEServiceRequest + +|Name|Description|Schema| +|---|---|---| +|**components** <br>*required*|List of DCAE service components that this service is composed of|< [DCAEServiceComponentRequest](#dcaeservicecomponentrequest) > array| +|**deploymentRef** <br>*optional*|Reference to a Cloudify deployment|string| +|**typeId** <br>*required*|Id of the associated DCAE service type|string| +|**vnfId** <br>*required*|Id of the associated VNF that this service is monitoring|string| +|**vnfLocation** <br>*required*|Location identifier of the associated VNF that this service is monitoring|string| +|**vnfType** <br>*required*|The type of the associated VNF that this service is monitoring|string| + + +<a name="dcaeservicetype"></a> +### DCAEServiceType + +|Name|Description|Schema| +|---|---|---| +|**asdcResourceId** <br>*optional*|Id of vf/vnf instance this DCAE service type is associated with. Value source is from ASDC's notification event's field `resourceInvariantUUID`.|string| +|**asdcServiceId** <br>*optional*|Id of service this DCAE service type is associated with. Value source is from ASDC's notification event's field `serviceInvariantUUID`.|string| +|**asdcServiceURL** <br>*optional*|URL to the ASDC service model|string| +|**blueprintTemplate** <br>*required*|String representation of a Cloudify blueprint with unbound variables|string| +|**created** <br>*required*|Created timestamp for this DCAE service type in epoch time|string(date-time)| +|**deactivated** <br>*optional*|Deactivated timestamp for this DCAE service type in epoch time|string(date-time)| +|**owner** <br>*required*||string| +|**selfLink** <br>*required*|Link to self where the Link.title is typeName|[Link](#link)| +|**serviceIds** <br>*optional*|List of service ids that are used to associate with DCAE service type. DCAE service types with this propery as null or empty means them apply for every service id.|< string > array| +|**serviceLocations** <br>*optional*|List of service locations that are used to associate with DCAE service type. DCAE service types with this propery as null or empty means them apply for every service location.|< string > array| +|**typeId** <br>*required*|Unique identifier for this DCAE service type|string| +|**typeName** <br>*required*|Descriptive name for this DCAE service type|string| +|**typeVersion** <br>*required*|Version number for this DCAE service type|integer(int32)| +|**vnfTypes** <br>*optional*||< string > array| + + +<a name="dcaeservicetyperequest"></a> +### DCAEServiceTypeRequest + +|Name|Description|Schema| +|---|---|---| +|**asdcResourceId** <br>*optional*|Id of vf/vnf instance this DCAE service type is associated with. Value source is from ASDC's notification event's field `resourceInvariantUUID`.|string| +|**asdcServiceId** <br>*optional*|Id of service this DCAE service type is associated with. Value source is from ASDC's notification event's field `serviceInvariantUUID`.|string| +|**asdcServiceURL** <br>*optional*|URL to the ASDC service model|string| +|**blueprintTemplate** <br>*required*|String representation of a Cloudify blueprint with unbound variables|string| +|**owner** <br>*required*||string| +|**serviceIds** <br>*optional*|List of service ids that are used to associate with DCAE service type. DCAE service types with this propery as null or empty means them apply for every service id.|< string > array| +|**serviceLocations** <br>*optional*|List of service locations that are used to associate with DCAE service type. DCAE service types with this propery as null or empty means them apply for every service location.|< string > array| +|**typeName** <br>*required*|Descriptive name for this DCAE service type|string| +|**typeVersion** <br>*required*|Version number for this DCAE service type|integer(int32)| +|**vnfTypes** <br>*optional*||< string > array| + + +<a name="inlineresponse200"></a> +### InlineResponse200 + +|Name|Description|Schema| +|---|---|---| +|**items** <br>*optional*||< [DCAEServiceType](#dcaeservicetype) > array| +|**links** <br>*optional*||[InlineResponse200Links](#inlineresponse200links)| +|**totalCount** <br>*optional*||integer(int32)| + + +<a name="inlineresponse2001"></a> +### InlineResponse2001 + +|Name|Description|Schema| +|---|---|---| +|**items** <br>*optional*||< [DCAEService](#dcaeservice) > array| +|**links** <br>*optional*||[InlineResponse200Links](#inlineresponse200links)| +|**totalCount** <br>*optional*||integer(int32)| + + +<a name="inlineresponse200links"></a> +### InlineResponse200Links +Pagination links + + +|Name|Description|Schema| +|---|---|---| +|**nextLink** <br>*optional*||[Link](#link)| +|**previousLink** <br>*optional*||[Link](#link)| + + +<a name="link"></a> +### Link + +|Name|Description|Schema| +|---|---|---| +|**params** <br>*optional*||< string, string > map| +|**rel** <br>*optional*||string| +|**rels** <br>*optional*||< string > array| +|**title** <br>*optional*||string| +|**type** <br>*optional*||string| +|**uri** <br>*optional*||string| +|**uriBuilder** <br>*optional*||[UriBuilder](#uribuilder)| + + +<a name="uribuilder"></a> +### UriBuilder +*Type* : object + + + + + diff --git a/docs/DatabaseTables.md b/docs/DatabaseTables.md new file mode 100644 index 0000000..30f4f7b --- /dev/null +++ b/docs/DatabaseTables.md @@ -0,0 +1,101 @@ +# Database Tables + +As of version 0.12.0. + +## `dcae_service_types` + +### Relationships + +* 1:1 - `dcae_services` + +### Schema + +``` + Table "public.dcae_service_types" + Column | Type | Modifiers +--------------------+-----------------------------+----------- + type_id | character varying | not null + type_version | integer | not null + type_name | character varying | not null + owner | character varying | not null + blueprint_template | text | not null + vnf_types | character varying[] | not null + service_ids | character varying[] | + service_locations | character varying[] | + asdc_service_id | character varying | not null + asdc_resource_id | character varying | not null + created | timestamp without time zone | not null + is_active | boolean | not null +Indexes: + "pk_type_created" PRIMARY KEY, btree (type_id, created) +``` + +## `dcae_services` + +### Relationships + +* 1:1 - `dcae_service_types` +* N:N - `dcae_service_components` mapped through `dcae_services_components_maps` + +### Schema + +``` + Table "public.dcae_services" + Column | Type | Modifiers +----------------+-----------------------------+----------- + service_id | character varying | not null + type_id | character varying | not null + vnf_id | character varying | not null + vnf_type | character varying | not null + vnf_location | character varying | not null + deployment_ref | character varying | + created | timestamp without time zone | not null + modified | timestamp without time zone | not null + status | character varying | not null +Indexes: + "dcae_services_pkey" PRIMARY KEY, btree (service_id) +Referenced by: + TABLE "dcae_services_components_maps" CONSTRAINT "dcae_services_components_maps_service_id_fkey" FOREIGN KEY (service_id) REFERENCES dcae_services(service_id) +``` + +## `dcae_service_components` + +### Relationships + +* N:N - `dcae_services` mapped through `dcae_services_components_maps` + +### Schema + +``` + Table "public.dcae_service_components" + Column | Type | Modifiers +------------------+-----------------------------+----------- + component_id | character varying | not null + component_type | character varying | not null + component_source | character varying | not null + shareable | integer | default 0 + created | timestamp without time zone | not null + modified | timestamp without time zone | not null +Indexes: + "dcae_service_components_pkey" PRIMARY KEY, btree (component_id) +Referenced by: + TABLE "dcae_services_components_maps" CONSTRAINT "dcae_services_components_maps_component_id_fkey" FOREIGN KEY (component_id) REFERENCES dcae_service_components(component_id) +``` + +## `dcae_services_components_maps` + +### Schema + +``` + Table "public.dcae_services_components_maps" + Column | Type | Modifiers +--------------+-----------------------------+----------- + service_id | character varying | not null + component_id | character varying | not null + created | timestamp without time zone | not null +Indexes: + "dcae_services_components_maps_pkey" PRIMARY KEY, btree (service_id, component_id) +Foreign-key constraints: + "dcae_services_components_maps_component_id_fkey" FOREIGN KEY (component_id) REFERENCES dcae_service_components(component_id) + "dcae_services_components_maps_service_id_fkey" FOREIGN KEY (service_id) REFERENCES dcae_services(service_id) +``` diff --git a/docs/Deployment.md b/docs/Deployment.md new file mode 100644 index 0000000..ff3974f --- /dev/null +++ b/docs/Deployment.md @@ -0,0 +1,39 @@ +# Deployment Guide - DCAE Inventory +*Last update: 2016-11-04* + +## Requirements + +### Network + +Requires ports 8080 to be open for inbound traffic on the machine that the service is hosted on. + +The DCAE Inventory relies on connectivity to a Postgres database, a DCAE Controller service instance, and a Databus Controller service instance all of which are configurable through the configuration file. The DCAE Inventory makes client-side calls to these external services. + +DCAE Inventory supports both HTTP and HTTPS through configuration setup. + +### Configuration + +The DCAE Inventory requires a configuration file and requires three groups of environment-dependent dynamic configuration information: + +1. Postgres database connection details + - `user` + - `password` + - `url` +2. DCAE controller connection details + - `host` + - `port` + - `basePath` + - `user` + - `password` +3. DMaaP controller connection details + - `host` + +In order for HTTPS to be enabled for DCAE Inventory, an HTTPS `applicationConnectors` need to be added to the configuration file. Details of this can be found [here](http://www.dropwizard.io/0.7.1/docs/manual/configuration.html#https). What is required at deployment time is a valide key store file (e.g. `PKCS12`) (i.e. set via `keyStorePath` parameter in the config) with the accompanying password (i.e. set via `keyStorePassword` parameter in the config). + +## Run Command + +The DCAE Inventory has been developed and tested using Java 8. Here is a sample run command: + +``` +java -jar dcae-inventory-2.3.1.jar server /opt/config.yml +``` diff --git a/docs/Design.md b/docs/Design.md new file mode 100644 index 0000000..4ce24d7 --- /dev/null +++ b/docs/Design.md @@ -0,0 +1,142 @@ +# DCAE Inventory: Design + +The DCAE Inventory is a web service that is responsible for managing DCAE service and DCAE service type information. + +## Terminology + +#### VNF + +"Virtual Network Function" + +Services that are customer facing and require monitoring. + +#### DCAE + +"Data Collections Analytics Events" + +A system responsible for monitoring and characterizing performance and behavior of running VNF services. DCAE emits events that are used by operations and to possibly change the policy of the managed VNF service. + +#### DCAE service component + +Applications and services that are built to be connected together to make up a DCAE service. These applications and services fall into the following categories: + +* Collectors +* Analytics +* Storage +* Data buses + +#### DCAE service type + +Contains: + +* Composition details of a network of DCAE service components in the form of a Cloudify blueprint template +* Metadata used to describe the DCAE service type +* Relationship information - how it relates to associated services and VNF types + +Cloudify blueprint template refers to a Cloudify blueprint that has unbound variables that is to be resolved before use for orchestration. + +DCAE service type has a tight coupling with DCAE services where all DCAE services must be associated with a single existing DCAE service type. This is reinforced by the DCAE Inventory. + +#### DCAE service + +A fully composed, running instance of a DCAE service type. The DCAE service is intended to collect data and to perform a set number of pre-defined analysis on a running VNF. A single DCAE service is associated with a single running VNF. + +DCAE service is a resource with a representation that is provided by DCAE Inventory. + +## What is DCAE Inventory + +DCAE Inventory is a web service that provides the following: + +1. Real-time data on all DCAE services and their components +2. Comprehensive details on available DCAE service types + +DCAE Inventory is a composite API that relies on other APIs to obtain resources on underlying components and uses these resources to compose a DCAE service resource. In addition, DCAE Inventory will store data that is unique to the DCAE service level including: + +* DCAE service metadata +* DCAE service type description and composition details +* Relationships between DCAE service and DCAE service types and their respective VNF and VNF types + +DCAE Inventory has a REST interface to service client requests. It has a well-defined query interface that would filter result sets based upon resource attributes. + +### API + +The full REST API reference can be found [here](API.adoc) (Careful! It's in AsciiDoc format). The DCAE Inventory service has been built to use [Swagger.io](http://swagger.io/) to document the API. The running service provides a YAML or JSON version of the specification of the DCAE Inventory API. Make the following curl call to fetch the YAML version: + +``` +curl <DCAE Inventory hostname>:8080/swagger.yaml +``` + +#### Using Swagger UI + +Use the following Swagger UI [chrome extension](https://chrome.google.com/webstore/detail/swagger-ui-console/ljlmonadebogfjabhkppkoohjkjclfai?hl=en) to view the specification in a nice view. Enter the URL you used in the above example `<DCAE Inventory hostname>:8080/swagger.yaml` into the input box of the Swagger UI page and hit *Explore*. You should see the complete API under *default*. + +## What DCAE Inventory is not + +* Not an inventory nor a catalog for VNFs +* Not a catalog for DCAE components +* Not the Data Bus controller's database +* Not an orchestrator nor does it do DCAE service creation + +## Use cases + +### Closed-loop orchestration + +The DCAE platform makes DCAE system changes upon change triggers from A&AI. + +A&AI emits events upon the creation and the destruction of a VNF. These events contain information on what sort of change occurred and the VNF associated with the change. These events are handled by DCAE Orchestrator and triggers the process of orchestrating the deployment or the undeployment of a DCAE service associated with the VNF. DCAE Orchestrator makes queries to DCAE Inventory who then provides the information to ultimately answer the question "given this VNF, what DCAE service should be deployed or be undeployed?" + +During the orchestration process, DCAE Orchestrator pushes details of the deployed/undeployed DCAE services. These runtime details are stored and managed by the DCAE Inventory. + +### DCAE services dashboard + +The DCAE dashboard provides visibility into running DCAE services for operational purposes. It queries the DCAE Inventory for aggregate details on all the running DCAE services and for getting up-to-date status information on DCAE services and their components. + +## Service dependencies + +DCAE Inventory relies on several APIs to construct its composite resource in addition to the data that DCAE Inventory stores. + +The following is a communication diagram of how the data flows between the DCAE Inventory and its dependencies: + + + +### DCAE Controller + +DCAE Inventory queries the DCAE controller to obtain an up-to-date projection of the state data per DCAE service component including their status i.e. DEPLOYED, RUNNING. + +### Data Bus Controller + +DCAE Inventory queries the Data Bus controller to obtain feed/topic details including the connection relationship between DCAE service components. + +### DCAE Orchestrator + +DCAE Inventory relies on the DCAE Orchestrator to push details of a DCAE service during the orchestration process particularly the DCAE service component runtime configuration information. + +### Camunda (Closed Loop) + +Camunda is a workflow design tool that creates and edits DCAE service types. In order to do DCAE service type updates, Camunda via a proxy service: + +1. Queries the DCAE Inventory for existing DCAE services for the given DCAE service type +2. Undeploys all those DCAE services +3. PUTs the new version of the DCAE service type + +The DCAE service types are associated with closed loop specific VNFs. + +## Technical implementation + +### Database + +DCAE Inventory uses the central Postgres as its database to store and to query its DCAE Inventory unique datasets. You can find the current table schemas for the DCAE Inventory tables [here](DatabaseTables.md). + +### Resiliency + +The central Postgres database has site-to-site replication to a redundant DCAE central location so the DCAE Inventory datasets are covered. The DCAE Inventory service is designed to be state-less and requires just the proper configuration information to be able to service requests. Configuration information includes: + +* Database connection details +* DCAE controller connection details +* Data bus controller connection details + +The chance of complete service outages is minimized by having redundancy. This requires load balancers for traffic management which does periodic health checks on all the instances to see if they are alive. + +### Security + +TBD diff --git a/docs/Upgrade.md b/docs/Upgrade.md new file mode 100644 index 0000000..11d2466 --- /dev/null +++ b/docs/Upgrade.md @@ -0,0 +1,13 @@ +# Upgrade Guide - DCAE Inventory +*Last update: 2016-08-19* + +## 0.13.0 -> 1.0.0 + +Requires a database table alteration if you wish to reuse an existing database table generated by DCAE inventory v0.13.0. The new schema is backwards compatible and safe for v0.13.0 records. + +Run the following SQL commands for the target Postgres DCAE inventory database: + +``` +alter table dcae_service_types add column service_ids varchar[]; +alter table dcae_service_types add column service_locations varchar[]; +``` diff --git a/docs/images/dcae_inventory_communication.png b/docs/images/dcae_inventory_communication.png Binary files differnew file mode 100644 index 0000000..409f515 --- /dev/null +++ b/docs/images/dcae_inventory_communication.png |
