openstack/heat
Code Issues Proposed changes

Fix api-ref doc for software deployment.

Browse Source 
The current api documentation for software deployment is a mess. This
patch is an attempt to fix it.

Change-Id: I41da79865c2836e6750314497e910982bc5462a9
This commit is contained in:
tengqm 2016-08-08 03:04:43 -04:00
parent 1243dc3797
commit 8ee3e581d3
2 changed files with 202 additions and 234 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

294
api-ref/source/v1/parameters.yaml
View File

@ -1,18 +1,25 @@
# variables in header
# variables in path
config_id:
config_id_url:
description: |
The UUID of the configuration.
in: path
required: false
type: string
deployment_id:
deployment_id_url:
description: |
The UUID of the deployment.
in: path
required: false
type: string
deployment_server_id_url:
description: |
The UUID of the server for which to fetch
server configuration metadata.
in: path
required: true
type: string
event_id:
description: |
The UUID of the event that is related to the
@ -32,13 +39,6 @@ resource_name:
in: path
required: false
type: string
server_id_2:
description: |
The UUID of the server for which to fetch
configuration metadata.
in: path
required: false
type: string
snapshot_id:
description: |
The UUID of the snapshot.
@ -57,6 +57,12 @@ stack_name:
in: path
required: false
type: string
template_version:
description: |
The version of the heat template.
in: path
required: true
type: string
tenant_id:
description: |
The UUID of the tenant. A tenant is also known as
@ -70,12 +76,6 @@ type_name:
in: path
required: false
type: string
template_version:
description: |
The version of the heat template.
in: path
required: true
type: string
# variables in query
action_3:
@ -85,6 +85,12 @@ action_3:
in: query
required: false
type: string
deployment_server_id_query:
description: |
The UUID of the target server.
in: query
required: false
type: string
global_tenant:
description: |
Set to ``true`` to include stacks from all
@ -100,6 +106,14 @@ id_4:
in: query
required: false
type: string
ignore_errors:
description: |
List of comma separated error codes to ignore.
# TODO(kanagaraj-manickam) add the cross reference to the API to retrieve the
# list of error code supported, once its made available in heat.
in: query
required: false
type: string
limit:
description: |
Requests a page size of items. Returns a number
@ -299,6 +313,12 @@ with_count:
in: query
required: false
type: boolean
with_description:
description: |
Either display resource type's description or not. Default is ``false``
in: query
required: false
type: boolean
with_detail:
description: |
Enables detailed resource information for each
@ -306,14 +326,6 @@ with_detail:
in: query
required: false
type: boolean
ignore_errors:
description: |
List of comma separated error codes to ignore.
# TODO(kanagaraj-manickam) add the cross reference to the API to retrieve the
# list of error code supported, once its made available in heat.
in: query
required: false
type: string
# variables in body
Description:
@ -361,26 +373,6 @@ Resources:
in: body
required: true
type: object
action:
description: |
The current stack action that triggers this
deployment resource.
in: body
required: true
type: string
action_1:
description: |
The deployment action.
in: body
required: true
type: string
action_2:
description: |
Current stack action in which this deployment
resource is being triggered.
in: body
required: true
type: string
adopt_stack_data:
description: |
Existing resources data to adopt a stack. Data
@ -440,14 +432,7 @@ config_1:
in: body
required: true
type: string
config_id_1:
description: |
The UUID of the software configuration resource
that runs when applying to the server.
in: body
required: true
type: string
config_id_2:
config_id:
description: |
The UUID of the configuration.
in: body
@ -463,6 +448,12 @@ config_id_3:
in: body
required: true
type: string
config_name:
description: |
The name of the software configuration.
in: body
required: true
type: string
created_at:
description: |
The date and time when the resource was created.
@ -613,6 +604,72 @@ deleted_at:
in: body
required: true
type: string
deployment_action:
description: |
The stack action that triggers this deployment resource.
in: body
required: false
type: string
deployment_config_id:
description: |
The UUID of the software configuration resource
that runs when applying to the server.
in: body
required: true
type: string
deployment_id:
description: |
The UUID of the software deployment.
in: body
required: true
type: string
deployment_metadata:
description: |
The metadata about a software deployment.
in: body
required: true
type: array
deployment_output_values:
description: |
A dict comprised of the output data from a software deployment.
in: body
required: true
type: object
deployment_status:
description: |
Current status of the deployment. A valid value
is ``COMPLETE``, ``IN_PROGRESS``, or ``FAILED``.
in: body
required: false
type: string
deployment_status_reason:
description: |
The reason for the current deployment status.
in: body
required: false
type: string
deployment_updated_time:
description: |
The date and time when the software deployment was updated.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
If the ``updated_at`` date and time stamp is not set, its value is
``null``.
in: body
required: false
type: string
description:
description: |
The description of the stack resource.
@ -683,6 +740,12 @@ disable_rollback_2:
in: body
required: true
type: boolean
engine_id:
description: |
The ID of engine service.
in: body
required: true
type: string
environment:
description: |
A JSON environment for the stack.
@ -772,21 +835,15 @@ heat_template_version:
in: body
required: true
type: string
hostname:
description: |
The name of the host for the service.
in: body
required: true
type: string
host:
description: |
The host for the service.
in: body
required: true
type: string
engine_id:
hostname:
description: |
The ID of engine service.
The name of the host for the service.
in: body
required: true
type: string
@ -796,18 +853,6 @@ id:
in: body
required: true
type: string
id_1:
description: |
The UUID of the software deployment.
in: body
required: true
type: string
id_2:
description: |
The UUID of the system-assigned stack.
in: body
required: true
type: string
id_3:
description: |
The UUID of the snapshot.
@ -822,10 +867,10 @@ id_5:
type: string
input_values:
description: |
A list of input data.
A dict comprises of input data as key-value pairs.
in: body
required: true
type: array
required: false
type: object
inputs:
description: |
Schema that represents the inputs that this
@ -867,12 +912,6 @@ name_1:
in: body
required: false
type: string
name_2:
description: |
The name of the software configuration.
in: body
required: true
type: string
name_3:
description: |
The name of the snapshot.
@ -898,13 +937,6 @@ options:
in: body
required: false
type: string
options_1:
description: |
The options, if any, to include in the code. For
example any dependent flags.
in: body
required: true
type: string
output_error:
description: |
The error in a stack output.
@ -923,18 +955,12 @@ output_value:
in: body
required: true
type: string
output_values:
description: |
A list of output data.
in: body
required: true
type: array
output_values_1:
description: |
Map of output values for the deployment, as
signaled from the server.
in: body
required: false
required:
type: object
outputs:
description: |
@ -1153,6 +1179,12 @@ resource:
in: body
required: true
type: object
resource_description:
description: |
Displays resource type's description.
in: body
required: false
type: string
resource_name_1:
description: |
The name of the resource.
@ -1216,12 +1248,6 @@ server_id:
in: body
required: true
type: string
server_id_1:
description: |
The UUID of the server.
in: body
required: true
type: string
services:
description: |
A list of heat engines.
@ -1350,27 +1376,6 @@ status:
in: body
required: true
type: string
status_1:
description: |
Current status of the deployment. A valid value
is ``COMPLETE``, ``IN_PROGRESS``, or ``FAILED``.
in: body
required: false
type: string
status_2:
description: |
The status of the software deployment. The value
is ``INPROGRESS`` or ``COMPLETE``.
in: body
required: true
type: string
status_3:
description: |
Current status of the deployment. Value is
``IN_PROGRESS``, ``COMPLETE``, or ``FAILED``.
in: body
required: false
type: string
status_4:
description: |
The status of the snapshot.
@ -1384,12 +1389,6 @@ status_reason:
in: body
required: false
type: string
status_reason_1:
description: |
The debug information for the current status.
in: body
required: true
type: string
status_reason_2:
description: |
The reason for the current snapshot status.
@ -1592,44 +1591,3 @@ updated_time_1:
in: body
required: true
type: string
updated_time_2:
description: |
Time of last stack update in the following
format: ``YYYY-MM- DDThh:mm:ssTZD``, where ``TZD`` is the time
zone designator.
in: body
required: true
type: string
updated_time_3:
description: |
The date and time when the stack was updated.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
If the ``updated_at`` date and time stamp is not set, its value is
``null``.
in: body
required: true
type: string
with_description:
description: |
Either display resource type's description or not. Default is ``false``
in: query
required: false
type: boolean
resource_description:
description: |
Displays resource type's description.
in: body
required: false
type: string

142
api-ref/source/v1/software-config.inc
View File

@ -22,7 +22,7 @@ Request Parameters
- inputs: inputs
- group: group
- name: name
- name: config_name
- outputs: outputs
- config: config
- options: options
@ -39,12 +39,13 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- id: config_id_2
- id: config_id
- inputs: inputs
- group: group
- name: name
- name: config_name
- outputs: outputs
- creation_time: creation_time
- updated_time: updated_time
- config: config
- options: options
- software_config: software_config
@ -81,10 +82,10 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- group: group
- name: name
- creation_time: creation_time
- id: config_id_2
- group: group
- id: config_id
- name: config_name
- software_configs: software_configs
Response Example
@ -119,14 +120,14 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- id: config_id_2
- inputs: inputs
- group: group
- name: name
- outputs: outputs
- creation_time: creation_time
- config: config
- creation_time: creation_time
- group: group
- id: config_id
- inputs: inputs
- name: config_name
- options: options
- outputs: outputs
- software_config: software_config
@ -152,7 +153,7 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- config_id: config_id
- config_id: config_id_url
Create deployment
@ -162,7 +163,6 @@ Create deployment
Creates a software deployment.
Normal response codes: 200
Error response codes:
@ -172,12 +172,13 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- status: status
- action: deployment_action
- config_id: deployment_config_id
- input_values: input_values
- server_id: server_id
- config_id: config_id
- stack_user_project_id: stack_user_project_id
- action: action
- status_reason: status_reason
- status: deployment_status
- status_reason: deployment_status_reason
- tenant_id: tenant_id
Request Example
@ -191,18 +192,17 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- status: status
- server_id: server_id
- config_id: config_id
- output_values: output_values
- action: deployment_action
- config_id: deployment_config_id
- creation_time: creation_time
- updated_at: updated_at
- id: deployment_id
- input_values: input_values
- action: action
- status_reason: status_reason
- id: id
- output_values: deployment_output_values
- server_id: server_id
- software_deployment: software_deployment
- status: deployment_status
- status_reason: status_reason
- updated_time: deployment_updated_time
Response Example
----------------
@ -227,6 +227,7 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- server_id: deployment_server_id_query
- tenant_id: tenant_id
Response Parameters
@ -234,16 +235,17 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- status: status
- server_id: server_id
- config_id: config_id
- output_values: output_values
- action: deployment_action
- config_id: deployment_config_id
- creation_time: creation_time
- updated_at: updated_at
- id: deployment_id
- input_values: input_values
- action: action
- output_values: deployment_output_values
- server_id: server_id
- software_deployments: software_deployments
- status: deployment_status
- status_reason: status_reason
- id: id_2
- updated_time: deployment_updated_time
Response Example
----------------
@ -251,7 +253,6 @@ Response Example
.. literalinclude:: samples/deployments-list-response.json
:language: javascript
Show deployment details
=======================
@ -259,7 +260,6 @@ Show deployment details
Shows details for a software deployment.
Normal response codes: 200
Error response codes:
@ -269,26 +269,25 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- deployment_id: deployment_id_url
- tenant_id: tenant_id
- deployment_id: deployment_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- server_id: server_id
- config_id: config_id
- output_values: output_values
- action: deployment_action
- config_id: deployment_config_id
- creation_time: creation_time
- updated_at: updated_at
- id: deployment_id
- input_values: input_values
- action: action
- status_reason: status_reason
- id: id_2
- output_values: deployment_output_values
- server_id: server_id
- software_deployment: software_deployment
- status: deployment_status
- status_reason: status_reason
- updated_time: deployment_updated_time
Response Example
----------------
@ -296,7 +295,6 @@ Response Example
.. literalinclude:: samples/deployment-show-response.json
:language: javascript
Update deployment
=================
@ -304,7 +302,6 @@ Update deployment
Updates a software deployment.
Normal response codes: 200
Error response codes:
@ -314,13 +311,14 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- action: action
- output_values: output_values
- config_id: config_id
- status: status
- action: deployment_action
- config_id: deployment_config_id
- deployment_id: deployment_id_url
- input_values: input_values
- output_values: deployment_output_values
- status: deployment_status
- status_reason: status_reason
- tenant_id: tenant_id
- deployment_id: deployment_id
Request Example
---------------
@ -333,17 +331,17 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- status: status
- server_id: server_id
- config_id: config_id
- output_values: output_values
- action: deployment_action
- config_id: deployment_config_id
- creation_time: creation_time
- updated_at: updated_at
- id: deployment_id
- input_values: input_values
- action: action
- output_values: deployment_output_values
- server_id: server_id
- software_deployments: software_deployments
- status: deployment_status
- status_reason: status_reason
- id: id
- software_deployment: software_deployment
- updated_time: deployment_updated_time
Response Example
----------------
@ -351,7 +349,6 @@ Response Example
.. literalinclude:: samples/deployment-update-response.json
:language: javascript
Delete deployment
=================
@ -366,9 +363,8 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- deployment_id: deployment_id_url
- tenant_id: tenant_id
- deployment_id: deployment_id
Show server configuration metadata
==================================
@ -380,7 +376,6 @@ Shows the deployment configuration metadata for a server.
Use the ``group`` property to specify the configuration hook to
which the pass the metadata item.
Normal response codes: 200
Error response codes:
@ -390,9 +385,24 @@ Request Parameters
.. rest_parameters:: parameters.yaml
- server_id: server_id
- server_id: deployment_server_id_url
- tenant_id: tenant_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- config: config
- creation_time: creation_time
- group: group
- id: config_id
- inputs: inputs
- metadata: deployment_metadata
- name: config_name
- options: options
- outputs: outputs
- updated_time: updated_time
Response Example
----------------