2014-12-12T23:05:48Z

Dagnello: /* Create Cluster */

== Cue API Design ==
=== Acronyms ===
{| class="wikitable"
|-
! '''Acronym''' !! '''Definition'''
|-
| SSL || Secure Sockets Layer
|-
| REST || Representational State Transfer
|-
| URI || Uniform Resource Identifier
|-
| UUID || Universally Unique Identifier
|-
| AMQP || Advanced Messaging Queuing Protocol
|}

=== Requirements ===

API Requirements for Cue - Kilo timeframe.

* Keystone integration
* CRUD on Cluster
* Cluster Management – Scale up/down
* Devstack integration
* Gate Tests

=== System Context Diagram ===

[[File:SCD.jpg]]

{| class="wikitable"
|-
! '''Component''' !! '''Description'''
|-
| User || Direct customer of Cue.
|-
| Horizon || Cue functionality will be added to Horizon, which will provide a web-based portal for Cue control.
|-
| CLI || Command Line Interface to Cue, provides user access to provisioning and deploying messaging clusters.
|-
| REST_API || Provides user access to provisioning and deploying messaging clusters through REST interface. This is a light-weight interface, provisioning and configuration of clusters/nodes is delegated to the TaskWorker process.
|-
| TaskScheduler || Used to synchronize work tasks between the REST_API and TaskWorker processes.
|-
| TaskWorker || Carries out work associated with all provisioning, configuration and management of RabbitMQ clusters and nodes. Makes use of heat for initial provisioning/deployment.
|-
| DB || Database to store information on clusters and nodes. Example, in cluster creation, when request is initially received through REST_API, this DB is updated accordingly and the work is delegated to TaskWorker. TaskWorker then updates this DB as provisioning and configuration takes place. Subsequent calls to check on status of cluster creation, will return updated information from this DB.
|-
| Heat || Used cloud instance orchestration in deploying RabbitMQ cluster images.
|}

=== REST API ===

General requirement, REST API must respond within 500ms.
==== List Clusters ====

'''''GET /v1/clusters'''''

This operation synchronously returns all clusters provisioned within the associated project id.

'''Request Parameters'''
N/A

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || ok (200)
|-
| Error || unauthorized (401)
|}

'''Response Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster(list) || string || List of clusters, detailing respective cluster id, name, status, created time stamp and updated time stamp.
|}

'''JSON Request'''

N/A

'''JSON Response'''

{
"clusters": <nowiki>[</nowiki>
{
"cluster_id": "b51948c9-1ac5-4c28-a580-6f7c500d82f8",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 1",
"status": "ACTIVE",
"flavor": "medium",
"size": "3",
"created": "2014-11-11T01:02:03Z",
"updated": "2014-11-11T01:02:03Z"
},
{
"cluster_id": "13c456c9-bbfc-4c31-b26d-3ae5c3cd7a77",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 2",
"status": "BUILDING",
"flavor": "small",
"size": "5",
"created": "2014-11-12T13:23:54Z",
"updated": "2014-11-13T19:55:01Z"
}
]
}

==== Create Cluster ====

'''''POST /v1/clusters'''''

This operation asynchronously creates a new cluster of Nova instances provisioned with the required message brokers in a central project id.

'''Request Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| network id || UUID || Network Identification for a Neutron network where cluster will be created in.
|-
| name || string || Name of cluster.
|-
| flavor || string || Cluster node flavor, which specify VM type in terms of CPU/memory/disk resources (e.g. small, medium, large).

small: 1 GHz dual-core CPU; 512 MB memory; 250 GB disk

medium: 2.8 GHz dual-core CPU; 4 GB memory; 1 TB disk

large: 3.6 GHz quad-core CPU; 32 GB memory; 5 TB disk
|-
| size || int || Number of nodes in cluster.
|-
| volume_size || int || Optional parameter to indicate size of volume for node instance. If volumes are supported, then this parameter will be used. If ephmeral disk are not supported, volume support will be required.
|}

'''Response Codes'''

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || 202 (accepted)
|-
| Error || badRequest (400), unauthorized (401), itemNotFound (404)
|}

'''Response Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id || UUID || ID of cluster to be created.
|-
| name || string || Name of cluster (same as provided name in request parameters).
|-
| status || string || Current status of cluster.

BUILDING: Cluster is in progress of being provisioned.

ACTIVE: Cluster is running.

ERROR: Provisioning error(s) encountered.

DELETED: Cluster has been deleted.
|}

'''JSON Request'''

{
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "MessageCluster1",
"flavor": "large",
"size": "3",
"volume_size": "100"
}

'''JSON Response'''

{
"cluster": {
"cluster_id": "dd745f4a-9333-417e-bb89-9c989c84c068",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 1",
"status": "BUILDING",
"flavor": "large",
"size": "3",
"volume_size": "100",
"created": "2014-11-11T01:02:03Z",
"updated": "2014-11-11T01:02:03Z"
}
}

==== Show Cluster ====

'''''GET /v1/clusters/{cluster_id}'''''

This operation synchronously returns the status and information on the specified cluster within the provided project id.

'''Request Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id (URI) || UUID || Cluster ID. This value is returned when a new cluster is created.
|}

'''Response Codes'''

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || ok (200)
|-
| Error || unauthorized (401), itemNotFound (404)
|}

'''Response Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id || UUID || ID of requested cluster.
|-
| name || string || Name of cluster.
|-
| status || string || Current status of cluster.

BUILDING: Cluster is in progress of being provisioned.

ACTIVE: Cluster is running.

ERROR: Provisioning error(s) encountered.

DELETED: Cluster has been deleted.
|-
| created || string || Created time stamp in format: yyyy-mm-ddThh:mm:ssZ
|-
| updated || string || Last updated time stamp in format: yyyy-mm-ddThh:mm:ssZ
|-
| nodes(list) || node || List of nodes, which includes node id, instance state, and flavor.
|}

'''JSON Request'''

N/A

'''JSON Response'''

{
"cluster": {
"cluster_id": "dd745f4a-9333-417e-bb89-9c989c84c068",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 1",
"status": "ACTIVE",
"flavor": "large",
"size": "3",
"volume_size": "100",
"created": "2014-11-11T01:02:03Z",
"updated": "2014-11-11T01:02:03Z",
"endpoints": [
{
"type": "AMQP",
"value": "amqp://10.20.30.40:10000"
},
{
"type": "console",
"value": "http://10.20.30.40:5672"
},
{
"type": "AMQP",
"value": "amqp://10.20.30.41:10000"
},
{
"type": "console",
"value": "http://10.20.30.41:5672"
},
{
"type": "AMQP",
"value": "amqp://10.20.30.42:10000"
},
{
"type": "console",
"value": "http://10.20.30.42:5672"
}
]
}
}

==== Delete Cluster ====

'''''DELETE /v1/clusters/{cluster_id}'''''''

This operation will asynchronously delete the indicated cluster within the provided project id.

'''Request Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id (URI) || UUID || Cluster ID. This value is returned when a new cluster is created.
|}

'''Response Codes'''

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || accepted (202)
|-
| Error || unauthorized (401), itemNotFound (404)
|}

'''Response Parameters'''

N/A

'''JSON Request'''

N/A

'''JSON Response'''

N/A

==== Update Cluster ====

'''''PATCH /v1/clusters/{cluster_id}'''''

This operation will asynchronously updated the indicated cluster (cluster_id) based on the request body received. The request body structure is the same as create cluster api. Cue will automatically detect differences and perform appropriate actions in order to update cluster accordingly.

'''Request Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| nic || UUID || Network Identification for a Neutron network where cluster will be created in.
|-
| name || string || Name of cluster.
|-
| volume_size || int || Optional parameter to indicate size of volume for node instance. If volumes are supported, then this parameter will be used. If ephmeral disk are not supported, volume support will be required.
|-
| flavor (list) || string || List of node flavors, which specify VM type in terms of CPU/memory/disk resources (e.g. small, medium, large). Size of list denotes the number of nodes in cluster.

small: 1 GHz dual-core CPU; 512 MB memory; 250 GB disk

medium: 2.8 GHz dual-core CPU; 4 GB memory; 1 TB disk

large: 3.6 GHz quad-core CPU; 32 GB memory; 5 TB disk
|}

'''Response Codes'''

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || 202 (accepted)
|-
| Error || badRequest (400), unauthorized (401), itemNotFound (404)
|}

'''Response Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id || UUID || ID of cluster to be created.
|-
| name || string || Name of cluster (same as provided name in request parameters).
|-
| status || string || Current status of cluster.

BUILDING: Cluster is in progress of being provisioned.

ACTIVE: Cluster is running.

ERROR: Provisioning error(s) encountered.

DELETED: Cluster has been deleted.
|}

'''JSON Request'''

{
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "MessageCluster1",
"flavor": "large",
"size": "3",
"volume_size": "100"
}

'''JSON Response'''

{
"cluster": {
"cluster_id": "dd745f4a-9333-417e-bb89-9c989c84c068",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 1",
"status": "BUILDING",
"flavor": "large",
"size": "3",
"volume_size": "100",
"created": "2014-11-11T01:02:03Z",
"updated": "2014-11-11T01:02:03Z"
}
}

===Testing===

Cue API testing will verify the expected functionality of the Cue user interface with both positive/negative tests. The overall scope will cover testing from the HTTP REST request to required database interactions and work-flow task submission for RPC workers.

====Unit Tests====

Unit tests will verify the resulting function calls for each REST-ful URI and action(s). The Python Mock library will be used to replace external system dependencies with placeholder objects.

{| class="wikitable"
|-
! Function !! Tests !! Input Data !! Expected Result(s)
|-
| List Clusters ||
# Create 'n' cluster(s), then call list clusters and verify expected return object
# Call list clusters when no clusters exist within a project id and verify expected return object
||
* n = # of clusters to create
||
# List of 'n' clusters is returned with appropriate fields, HTTP Ok (200)
# Empty list of clusters is returned, HTTP Ok (200)
|-
| Create Cluster ||
# Create standard cluster 'c' and verify expected return object
# Create cluster with invalid flavor and verify expected return value
# Create cluster with invalid volume size and verify expected return value
||
* n = cluster size (number of nodes)
* m = cluster name
* f = flavor
* s = volume size
* nic = Network UUID
||
# Cluster ID, name and status for newly created cluster is returned, HTTP Accepted (202)
# HTTP Bad request is returned (400)
# HTTP Bad request is returned (400)
|-
| Show Cluster ||
# Create cluster, then call get cluster and verify expected return object
# Get cluster with invalid cluster_id
||
* cluster_id = cluster ID
||
# Cluster ID, name, status, created/updated date stamp and list of nodes is returned, HTTP Ok (200).
# HTTP Bad request is returned (400)
|-
| Delete Cluster ||
# Create a cluster, then call delete cluster and verify expected return value
# Delete cluster with invalid cluster_id
||
* cluster_id = cluster ID
||
# HTTP accepted is returned (202)
# HTTP Bad request is returned (400)
|}

====Functional Tests====

The functional tests will verify the HTTP REST URI request lifecycle from controller routing to HTTP response. These tests will make use of Pecan's testing utility; pecan.testing module.

{| class="wikitable"
|-
! Operation !! URI !! Tests !! Input Data !! Expected Data (JSON)
|-
| GET || /v1/clusters ||
# Call when clusters exist
# Call when no clusters exist
||
* n/a
||
# List of 'n' clusters is returned with appropriate fields, HTTP Ok (200)
# Empty list of clusters is returned, HTTP Ok (200)
|-
| POST || /v1/clusters ||
# Create standard cluster 'c' and verify expected return object
# Create cluster with invalid flavor and verify expected return value
# Create cluster with invalid volume size and verify expected return value
||
* n = cluster size (number of nodes)
* m = cluster name
* f = flavor
* s = volume size
* nic = Network UUID
||
# Cluster ID, name and status for newly created cluster is returned, HTTP Accepted (202)
# HTTP Bad request is returned (400)
# HTTP Bad request is returned (400)
||
|-
| GET || /v1/clusters/{cluster_id} ||
# Create cluster, then call get cluster and verify expected return object
# Get cluster with invalid cluster_id
||
* cluster_id = cluster
||
# Cluster ID, name, status, created/updated date stamp and list of nodes is returned, HTTP Ok (200).
# HTTP Bad request is returned (400)
||
|-
| DELETE || /v1/clusters/{cluster_id} ||
# Create a cluster, then call delete cluster and verify expected return value
# Delete cluster with invalid cluster_id
||
* cluster_id = cluster ID
||
# HTTP accepted is returned (202)
# HTTP Bad request is returned (400)
||
|}

====Integration Tests====

The integration tests will cover API functionality from HTTP request to database access and task submission for RPC workers. The Pecan test utility will be used to route test request URI to appropriate controllers, then database record(s) will be verified for applicable change. Finally the creation of task objections will be verified to ensure valid task flows.

Cue/api 2

2014-12-12T22:59:56Z

Dagnello: /* Create Cluster */

== Cue API Design ==
=== Acronyms ===
{| class="wikitable"
|-
! '''Acronym''' !! '''Definition'''
|-
| SSL || Secure Sockets Layer
|-
| REST || Representational State Transfer
|-
| URI || Uniform Resource Identifier
|-
| UUID || Universally Unique Identifier
|-
| AMQP || Advanced Messaging Queuing Protocol
|}

=== Requirements ===

API Requirements for Cue - Kilo timeframe.

* Keystone integration
* CRUD on Cluster
* Cluster Management – Scale up/down
* Devstack integration
* Gate Tests

=== System Context Diagram ===

[[File:SCD.jpg]]

{| class="wikitable"
|-
! '''Component''' !! '''Description'''
|-
| User || Direct customer of Cue.
|-
| Horizon || Cue functionality will be added to Horizon, which will provide a web-based portal for Cue control.
|-
| CLI || Command Line Interface to Cue, provides user access to provisioning and deploying messaging clusters.
|-
| REST_API || Provides user access to provisioning and deploying messaging clusters through REST interface. This is a light-weight interface, provisioning and configuration of clusters/nodes is delegated to the TaskWorker process.
|-
| TaskScheduler || Used to synchronize work tasks between the REST_API and TaskWorker processes.
|-
| TaskWorker || Carries out work associated with all provisioning, configuration and management of RabbitMQ clusters and nodes. Makes use of heat for initial provisioning/deployment.
|-
| DB || Database to store information on clusters and nodes. Example, in cluster creation, when request is initially received through REST_API, this DB is updated accordingly and the work is delegated to TaskWorker. TaskWorker then updates this DB as provisioning and configuration takes place. Subsequent calls to check on status of cluster creation, will return updated information from this DB.
|-
| Heat || Used cloud instance orchestration in deploying RabbitMQ cluster images.
|}

=== REST API ===

General requirement, REST API must respond within 500ms.
==== List Clusters ====

'''''GET /v1/clusters'''''

This operation synchronously returns all clusters provisioned within the associated project id.

'''Request Parameters'''
N/A

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || ok (200)
|-
| Error || unauthorized (401)
|}

'''Response Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster(list) || string || List of clusters, detailing respective cluster id, name, status, created time stamp and updated time stamp.
|}

'''JSON Request'''

N/A

'''JSON Response'''

{
"clusters": <nowiki>[</nowiki>
{
"cluster_id": "b51948c9-1ac5-4c28-a580-6f7c500d82f8",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 1",
"status": "ACTIVE",
"flavor": "medium",
"size": "3",
"created": "2014-11-11T01:02:03Z",
"updated": "2014-11-11T01:02:03Z"
},
{
"cluster_id": "13c456c9-bbfc-4c31-b26d-3ae5c3cd7a77",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 2",
"status": "BUILDING",
"flavor": "small",
"size": "5",
"created": "2014-11-12T13:23:54Z",
"updated": "2014-11-13T19:55:01Z"
}
]
}

==== Create Cluster ====

'''''POST /v1/clusters'''''

This operation asynchronously creates a new cluster of Nova instances provisioned with the required message brokers in a central project id.

'''Request Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| nic || UUID || Network Identification for a Neutron network where cluster will be created in.
|-
| name || string || Name of cluster.
|-
| flavor || string || Cluster node flavor, which specify VM type in terms of CPU/memory/disk resources (e.g. small, medium, large).

small: 1 GHz dual-core CPU; 512 MB memory; 250 GB disk

medium: 2.8 GHz dual-core CPU; 4 GB memory; 1 TB disk

large: 3.6 GHz quad-core CPU; 32 GB memory; 5 TB disk
|-
| size || int || Number of nodes in cluster.
|-
| volume_size || int || Optional parameter to indicate size of volume for node instance. If volumes are supported, then this parameter will be used. If ephmeral disk are not supported, volume support will be required.
|}

'''Response Codes'''

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || 202 (accepted)
|-
| Error || badRequest (400), unauthorized (401), itemNotFound (404)
|}

'''Response Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id || UUID || ID of cluster to be created.
|-
| name || string || Name of cluster (same as provided name in request parameters).
|-
| status || string || Current status of cluster.

BUILDING: Cluster is in progress of being provisioned.

ACTIVE: Cluster is running.

ERROR: Provisioning error(s) encountered.

DELETED: Cluster has been deleted.
|}

'''JSON Request'''

{
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "MessageCluster1",
"flavor": "large",
"size": "3",
"volume_size": "100"
}

'''JSON Response'''

{
"cluster": {
"cluster_id": "dd745f4a-9333-417e-bb89-9c989c84c068",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 1",
"status": "BUILDING",
"flavor": "large",
"size": "3",
"volume_size": "100",
"created": "2014-11-11T01:02:03Z",
"updated": "2014-11-11T01:02:03Z"
}
}

==== Show Cluster ====

'''''GET /v1/clusters/{cluster_id}'''''

This operation synchronously returns the status and information on the specified cluster within the provided project id.

'''Request Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id (URI) || UUID || Cluster ID. This value is returned when a new cluster is created.
|}

'''Response Codes'''

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || ok (200)
|-
| Error || unauthorized (401), itemNotFound (404)
|}

'''Response Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id || UUID || ID of requested cluster.
|-
| name || string || Name of cluster.
|-
| status || string || Current status of cluster.

BUILDING: Cluster is in progress of being provisioned.

ACTIVE: Cluster is running.

ERROR: Provisioning error(s) encountered.

DELETED: Cluster has been deleted.
|-
| created || string || Created time stamp in format: yyyy-mm-ddThh:mm:ssZ
|-
| updated || string || Last updated time stamp in format: yyyy-mm-ddThh:mm:ssZ
|-
| nodes(list) || node || List of nodes, which includes node id, instance state, and flavor.
|}

'''JSON Request'''

N/A

'''JSON Response'''

{
"cluster": {
"cluster_id": "dd745f4a-9333-417e-bb89-9c989c84c068",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 1",
"status": "ACTIVE",
"flavor": "large",
"size": "3",
"volume_size": "100",
"created": "2014-11-11T01:02:03Z",
"updated": "2014-11-11T01:02:03Z",
"endpoints": [
{
"type": "AMQP",
"value": "amqp://10.20.30.40:10000"
},
{
"type": "console",
"value": "http://10.20.30.40:5672"
},
{
"type": "AMQP",
"value": "amqp://10.20.30.41:10000"
},
{
"type": "console",
"value": "http://10.20.30.41:5672"
},
{
"type": "AMQP",
"value": "amqp://10.20.30.42:10000"
},
{
"type": "console",
"value": "http://10.20.30.42:5672"
}
]
}
}

==== Delete Cluster ====

'''''DELETE /v1/clusters/{cluster_id}'''''''

This operation will asynchronously delete the indicated cluster within the provided project id.

'''Request Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id (URI) || UUID || Cluster ID. This value is returned when a new cluster is created.
|}

'''Response Codes'''

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || accepted (202)
|-
| Error || unauthorized (401), itemNotFound (404)
|}

'''Response Parameters'''

N/A

'''JSON Request'''

N/A

'''JSON Response'''

N/A

==== Update Cluster ====

'''''PATCH /v1/clusters/{cluster_id}'''''

This operation will asynchronously updated the indicated cluster (cluster_id) based on the request body received. The request body structure is the same as create cluster api. Cue will automatically detect differences and perform appropriate actions in order to update cluster accordingly.

'''Request Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| nic || UUID || Network Identification for a Neutron network where cluster will be created in.
|-
| name || string || Name of cluster.
|-
| volume_size || int || Optional parameter to indicate size of volume for node instance. If volumes are supported, then this parameter will be used. If ephmeral disk are not supported, volume support will be required.
|-
| flavor (list) || string || List of node flavors, which specify VM type in terms of CPU/memory/disk resources (e.g. small, medium, large). Size of list denotes the number of nodes in cluster.

small: 1 GHz dual-core CPU; 512 MB memory; 250 GB disk

medium: 2.8 GHz dual-core CPU; 4 GB memory; 1 TB disk

large: 3.6 GHz quad-core CPU; 32 GB memory; 5 TB disk
|}

'''Response Codes'''

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || 202 (accepted)
|-
| Error || badRequest (400), unauthorized (401), itemNotFound (404)
|}

'''Response Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id || UUID || ID of cluster to be created.
|-
| name || string || Name of cluster (same as provided name in request parameters).
|-
| status || string || Current status of cluster.

BUILDING: Cluster is in progress of being provisioned.

ACTIVE: Cluster is running.

ERROR: Provisioning error(s) encountered.

DELETED: Cluster has been deleted.
|}

'''JSON Request'''

{
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "MessageCluster1",
"flavor": "large",
"size": "3",
"volume_size": "100"
}

'''JSON Response'''

{
"cluster": {
"cluster_id": "dd745f4a-9333-417e-bb89-9c989c84c068",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 1",
"status": "BUILDING",
"flavor": "large",
"size": "3",
"volume_size": "100",
"created": "2014-11-11T01:02:03Z",
"updated": "2014-11-11T01:02:03Z"
}
}

===Testing===

Cue API testing will verify the expected functionality of the Cue user interface with both positive/negative tests. The overall scope will cover testing from the HTTP REST request to required database interactions and work-flow task submission for RPC workers.

====Unit Tests====

Unit tests will verify the resulting function calls for each REST-ful URI and action(s). The Python Mock library will be used to replace external system dependencies with placeholder objects.

{| class="wikitable"
|-
! Function !! Tests !! Input Data !! Expected Result(s)
|-
| List Clusters ||
# Create 'n' cluster(s), then call list clusters and verify expected return object
# Call list clusters when no clusters exist within a project id and verify expected return object
||
* n = # of clusters to create
||
# List of 'n' clusters is returned with appropriate fields, HTTP Ok (200)
# Empty list of clusters is returned, HTTP Ok (200)
|-
| Create Cluster ||
# Create standard cluster 'c' and verify expected return object
# Create cluster with invalid flavor and verify expected return value
# Create cluster with invalid volume size and verify expected return value
||
* n = cluster size (number of nodes)
* m = cluster name
* f = flavor
* s = volume size
* nic = Network UUID
||
# Cluster ID, name and status for newly created cluster is returned, HTTP Accepted (202)
# HTTP Bad request is returned (400)
# HTTP Bad request is returned (400)
|-
| Show Cluster ||
# Create cluster, then call get cluster and verify expected return object
# Get cluster with invalid cluster_id
||
* cluster_id = cluster ID
||
# Cluster ID, name, status, created/updated date stamp and list of nodes is returned, HTTP Ok (200).
# HTTP Bad request is returned (400)
|-
| Delete Cluster ||
# Create a cluster, then call delete cluster and verify expected return value
# Delete cluster with invalid cluster_id
||
* cluster_id = cluster ID
||
# HTTP accepted is returned (202)
# HTTP Bad request is returned (400)
|}

====Functional Tests====

The functional tests will verify the HTTP REST URI request lifecycle from controller routing to HTTP response. These tests will make use of Pecan's testing utility; pecan.testing module.

{| class="wikitable"
|-
! Operation !! URI !! Tests !! Input Data !! Expected Data (JSON)
|-
| GET || /v1/clusters ||
# Call when clusters exist
# Call when no clusters exist
||
* n/a
||
# List of 'n' clusters is returned with appropriate fields, HTTP Ok (200)
# Empty list of clusters is returned, HTTP Ok (200)
|-
| POST || /v1/clusters ||
# Create standard cluster 'c' and verify expected return object
# Create cluster with invalid flavor and verify expected return value
# Create cluster with invalid volume size and verify expected return value
||
* n = cluster size (number of nodes)
* m = cluster name
* f = flavor
* s = volume size
* nic = Network UUID
||
# Cluster ID, name and status for newly created cluster is returned, HTTP Accepted (202)
# HTTP Bad request is returned (400)
# HTTP Bad request is returned (400)
||
|-
| GET || /v1/clusters/{cluster_id} ||
# Create cluster, then call get cluster and verify expected return object
# Get cluster with invalid cluster_id
||
* cluster_id = cluster
||
# Cluster ID, name, status, created/updated date stamp and list of nodes is returned, HTTP Ok (200).
# HTTP Bad request is returned (400)
||
|-
| DELETE || /v1/clusters/{cluster_id} ||
# Create a cluster, then call delete cluster and verify expected return value
# Delete cluster with invalid cluster_id
||
* cluster_id = cluster ID
||
# HTTP accepted is returned (202)
# HTTP Bad request is returned (400)
||
|}

====Integration Tests====

The integration tests will cover API functionality from HTTP request to database access and task submission for RPC workers. The Pecan test utility will be used to route test request URI to appropriate controllers, then database record(s) will be verified for applicable change. Finally the creation of task objections will be verified to ensure valid task flows.

Cue/api 2

2014-12-12T22:59:11Z

Dagnello: /* Create Cluster */

== Cue API Design ==
=== Acronyms ===
{| class="wikitable"
|-
! '''Acronym''' !! '''Definition'''
|-
| SSL || Secure Sockets Layer
|-
| REST || Representational State Transfer
|-
| URI || Uniform Resource Identifier
|-
| UUID || Universally Unique Identifier
|-
| AMQP || Advanced Messaging Queuing Protocol
|}

=== Requirements ===

API Requirements for Cue - Kilo timeframe.

* Keystone integration
* CRUD on Cluster
* Cluster Management – Scale up/down
* Devstack integration
* Gate Tests

=== System Context Diagram ===

[[File:SCD.jpg]]

{| class="wikitable"
|-
! '''Component''' !! '''Description'''
|-
| User || Direct customer of Cue.
|-
| Horizon || Cue functionality will be added to Horizon, which will provide a web-based portal for Cue control.
|-
| CLI || Command Line Interface to Cue, provides user access to provisioning and deploying messaging clusters.
|-
| REST_API || Provides user access to provisioning and deploying messaging clusters through REST interface. This is a light-weight interface, provisioning and configuration of clusters/nodes is delegated to the TaskWorker process.
|-
| TaskScheduler || Used to synchronize work tasks between the REST_API and TaskWorker processes.
|-
| TaskWorker || Carries out work associated with all provisioning, configuration and management of RabbitMQ clusters and nodes. Makes use of heat for initial provisioning/deployment.
|-
| DB || Database to store information on clusters and nodes. Example, in cluster creation, when request is initially received through REST_API, this DB is updated accordingly and the work is delegated to TaskWorker. TaskWorker then updates this DB as provisioning and configuration takes place. Subsequent calls to check on status of cluster creation, will return updated information from this DB.
|-
| Heat || Used cloud instance orchestration in deploying RabbitMQ cluster images.
|}

=== REST API ===

General requirement, REST API must respond within 500ms.
==== List Clusters ====

'''''GET /v1/clusters'''''

This operation synchronously returns all clusters provisioned within the associated project id.

'''Request Parameters'''
N/A

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || ok (200)
|-
| Error || unauthorized (401)
|}

'''Response Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster(list) || string || List of clusters, detailing respective cluster id, name, status, created time stamp and updated time stamp.
|}

'''JSON Request'''

N/A

'''JSON Response'''

{
"clusters": <nowiki>[</nowiki>
{
"cluster_id": "b51948c9-1ac5-4c28-a580-6f7c500d82f8",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 1",
"status": "ACTIVE",
"flavor": "medium",
"size": "3",
"created": "2014-11-11T01:02:03Z",
"updated": "2014-11-11T01:02:03Z"
},
{
"cluster_id": "13c456c9-bbfc-4c31-b26d-3ae5c3cd7a77",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 2",
"status": "BUILDING",
"flavor": "small",
"size": "5",
"created": "2014-11-12T13:23:54Z",
"updated": "2014-11-13T19:55:01Z"
}
]
}

==== Create Cluster ====

'''''POST /v1/clusters'''''

This operation asynchronously creates a new cluster of Nova instances provisioned with the required message brokers in a central project id.

'''Request Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| nic || UUID || Network Identification for a Neutron network where cluster will be created in.
|-
| name || string || Name of cluster.
|-
| flavor || string || Cluster node flavor, which specify VM type in terms of CPU/memory/disk resources (e.g. small, medium, large).
|-
| size || int || Number of nodes in cluster.
|-
| volume_size || int || Optional parameter to indicate size of volume for node instance. If volumes are supported, then this parameter will be used. If ephmeral disk are not supported, volume support will be required.

small: 1 GHz dual-core CPU; 512 MB memory; 250 GB disk

medium: 2.8 GHz dual-core CPU; 4 GB memory; 1 TB disk

large: 3.6 GHz quad-core CPU; 32 GB memory; 5 TB disk
|}

'''Response Codes'''

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || 202 (accepted)
|-
| Error || badRequest (400), unauthorized (401), itemNotFound (404)
|}

'''Response Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id || UUID || ID of cluster to be created.
|-
| name || string || Name of cluster (same as provided name in request parameters).
|-
| status || string || Current status of cluster.

BUILDING: Cluster is in progress of being provisioned.

ACTIVE: Cluster is running.

ERROR: Provisioning error(s) encountered.

DELETED: Cluster has been deleted.
|}

'''JSON Request'''

{
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "MessageCluster1",
"flavor": "large",
"size": "3",
"volume_size": "100"
}

'''JSON Response'''

{
"cluster": {
"cluster_id": "dd745f4a-9333-417e-bb89-9c989c84c068",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 1",
"status": "BUILDING",
"flavor": "large",
"size": "3",
"volume_size": "100",
"created": "2014-11-11T01:02:03Z",
"updated": "2014-11-11T01:02:03Z"
}
}

==== Show Cluster ====

'''''GET /v1/clusters/{cluster_id}'''''

This operation synchronously returns the status and information on the specified cluster within the provided project id.

'''Request Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id (URI) || UUID || Cluster ID. This value is returned when a new cluster is created.
|}

'''Response Codes'''

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || ok (200)
|-
| Error || unauthorized (401), itemNotFound (404)
|}

'''Response Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id || UUID || ID of requested cluster.
|-
| name || string || Name of cluster.
|-
| status || string || Current status of cluster.

BUILDING: Cluster is in progress of being provisioned.

ACTIVE: Cluster is running.

ERROR: Provisioning error(s) encountered.

DELETED: Cluster has been deleted.
|-
| created || string || Created time stamp in format: yyyy-mm-ddThh:mm:ssZ
|-
| updated || string || Last updated time stamp in format: yyyy-mm-ddThh:mm:ssZ
|-
| nodes(list) || node || List of nodes, which includes node id, instance state, and flavor.
|}

'''JSON Request'''

N/A

'''JSON Response'''

{
"cluster": {
"cluster_id": "dd745f4a-9333-417e-bb89-9c989c84c068",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 1",
"status": "ACTIVE",
"flavor": "large",
"size": "3",
"volume_size": "100",
"created": "2014-11-11T01:02:03Z",
"updated": "2014-11-11T01:02:03Z",
"endpoints": [
{
"type": "AMQP",
"value": "amqp://10.20.30.40:10000"
},
{
"type": "console",
"value": "http://10.20.30.40:5672"
},
{
"type": "AMQP",
"value": "amqp://10.20.30.41:10000"
},
{
"type": "console",
"value": "http://10.20.30.41:5672"
},
{
"type": "AMQP",
"value": "amqp://10.20.30.42:10000"
},
{
"type": "console",
"value": "http://10.20.30.42:5672"
}
]
}
}

==== Delete Cluster ====

'''''DELETE /v1/clusters/{cluster_id}'''''''

This operation will asynchronously delete the indicated cluster within the provided project id.

'''Request Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id (URI) || UUID || Cluster ID. This value is returned when a new cluster is created.
|}

'''Response Codes'''

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || accepted (202)
|-
| Error || unauthorized (401), itemNotFound (404)
|}

'''Response Parameters'''

N/A

'''JSON Request'''

N/A

'''JSON Response'''

N/A

==== Update Cluster ====

'''''PATCH /v1/clusters/{cluster_id}'''''

This operation will asynchronously updated the indicated cluster (cluster_id) based on the request body received. The request body structure is the same as create cluster api. Cue will automatically detect differences and perform appropriate actions in order to update cluster accordingly.

'''Request Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| nic || UUID || Network Identification for a Neutron network where cluster will be created in.
|-
| name || string || Name of cluster.
|-
| volume_size || int || Optional parameter to indicate size of volume for node instance. If volumes are supported, then this parameter will be used. If ephmeral disk are not supported, volume support will be required.
|-
| flavor (list) || string || List of node flavors, which specify VM type in terms of CPU/memory/disk resources (e.g. small, medium, large). Size of list denotes the number of nodes in cluster.

small: 1 GHz dual-core CPU; 512 MB memory; 250 GB disk

medium: 2.8 GHz dual-core CPU; 4 GB memory; 1 TB disk

large: 3.6 GHz quad-core CPU; 32 GB memory; 5 TB disk
|}

'''Response Codes'''

{| class="wikitable"
|-
! Response !! Code(s)
|-
| Normal || 202 (accepted)
|-
| Error || badRequest (400), unauthorized (401), itemNotFound (404)
|}

'''Response Parameters'''

{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| cluster_id || UUID || ID of cluster to be created.
|-
| name || string || Name of cluster (same as provided name in request parameters).
|-
| status || string || Current status of cluster.

BUILDING: Cluster is in progress of being provisioned.

ACTIVE: Cluster is running.

ERROR: Provisioning error(s) encountered.

DELETED: Cluster has been deleted.
|}

'''JSON Request'''

{
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "MessageCluster1",
"flavor": "large",
"size": "3",
"volume_size": "100"
}

'''JSON Response'''

{
"cluster": {
"cluster_id": "dd745f4a-9333-417e-bb89-9c989c84c068",
"network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
"name": "Message Cluster 1",
"status": "BUILDING",
"flavor": "large",
"size": "3",
"volume_size": "100",
"created": "2014-11-11T01:02:03Z",
"updated": "2014-11-11T01:02:03Z"
}
}

===Testing===

Cue API testing will verify the expected functionality of the Cue user interface with both positive/negative tests. The overall scope will cover testing from the HTTP REST request to required database interactions and work-flow task submission for RPC workers.

====Unit Tests====

Unit tests will verify the resulting function calls for each REST-ful URI and action(s). The Python Mock library will be used to replace external system dependencies with placeholder objects.

{| class="wikitable"
|-
! Function !! Tests !! Input Data !! Expected Result(s)
|-
| List Clusters ||
# Create 'n' cluster(s), then call list clusters and verify expected return object
# Call list clusters when no clusters exist within a project id and verify expected return object
||
* n = # of clusters to create
||
# List of 'n' clusters is returned with appropriate fields, HTTP Ok (200)
# Empty list of clusters is returned, HTTP Ok (200)
|-
| Create Cluster ||
# Create standard cluster 'c' and verify expected return object
# Create cluster with invalid flavor and verify expected return value
# Create cluster with invalid volume size and verify expected return value
||
* n = cluster size (number of nodes)
* m = cluster name
* f = flavor
* s = volume size
* nic = Network UUID
||
# Cluster ID, name and status for newly created cluster is returned, HTTP Accepted (202)
# HTTP Bad request is returned (400)
# HTTP Bad request is returned (400)
|-
| Show Cluster ||
# Create cluster, then call get cluster and verify expected return object
# Get cluster with invalid cluster_id
||
* cluster_id = cluster ID
||
# Cluster ID, name, status, created/updated date stamp and list of nodes is returned, HTTP Ok (200).
# HTTP Bad request is returned (400)
|-
| Delete Cluster ||
# Create a cluster, then call delete cluster and verify expected return value
# Delete cluster with invalid cluster_id
||
* cluster_id = cluster ID
||
# HTTP accepted is returned (202)
# HTTP Bad request is returned (400)
|}

====Functional Tests====

The functional tests will verify the HTTP REST URI request lifecycle from controller routing to HTTP response. These tests will make use of Pecan's testing utility; pecan.testing module.

{| class="wikitable"
|-
! Operation !! URI !! Tests !! Input Data !! Expected Data (JSON)
|-
| GET || /v1/clusters ||
# Call when clusters exist
# Call when no clusters exist
||
* n/a
||
# List of 'n' clusters is returned with appropriate fields, HTTP Ok (200)
# Empty list of clusters is returned, HTTP Ok (200)
|-
| POST || /v1/clusters ||
# Create standard cluster 'c' and verify expected return object
# Create cluster with invalid flavor and verify expected return value
# Create cluster with invalid volume size and verify expected return value
||
* n = cluster size (number of nodes)
* m = cluster name
* f = flavor
* s = volume size
* nic = Network UUID
||
# Cluster ID, name and status for newly created cluster is returned, HTTP Accepted (202)
# HTTP Bad request is returned (400)
# HTTP Bad request is returned (400)
||
|-
| GET || /v1/clusters/{cluster_id} ||
# Create cluster, then call get cluster and verify expected return object
# Get cluster with invalid cluster_id
||
* cluster_id = cluster
||
# Cluster ID, name, status, created/updated date stamp and list of nodes is returned, HTTP Ok (200).
# HTTP Bad request is returned (400)
||
|-
| DELETE || /v1/clusters/{cluster_id} ||
# Create a cluster, then call delete cluster and verify expected return value
# Delete cluster with invalid cluster_id
||
* cluster_id = cluster ID
||
# HTTP accepted is returned (202)
# HTTP Bad request is returned (400)
||
|}

====Integration Tests====

The integration tests will cover API functionality from HTTP request to database access and task submission for RPC workers. The Pecan test utility will be used to route test request URI to appropriate controllers, then database record(s) will be verified for applicable change. Finally the creation of task objections will be verified to ensure valid task flows.