Merge "api-ref doc for stack (5)"

2016-08-19 05:32:29 +00:00 · 2016-08-19 05:32:29 +00:00 · 4eee944e9b
parent bfc1d11990 959b5694df
commit 4eee944e9b
4 changed files with 174 additions and 57 deletions
--- a/api-ref/source/v1/parameters.yaml
+++ b/api-ref/source/v1/parameters.yaml
@ -388,9 +388,8 @@ Resources:
  type: object
 adopt_stack_data:
  description: |
-    Existing resources data to adopt a stack. Data
-    returned by abandon stack could be provided as
-    ``adopt_stack_data``.
+    Existing resources data to adopt a stack. Data returned by abandon
+    stack could be provided as ``adopt_stack_data``.
  in: body
  required: true
  type: object
@ -881,12 +880,6 @@ outputs_1:
  in: body
  required: true
  type: array
-outputs_3:
-  description: |
-    Key and value pairs that contain output data.
-  in: body
-  required: true
-  type: object
 parameters:
  description: |
    Supplies arguments for parameters defined in the stack template.
@ -1100,10 +1093,9 @@ resources_2:
  in: body
  required: true
  type: object
-resources_3:
+resources_abandon:
  description: |
-    The required sources for creating the stack
-    template.
+    The required sources for creating the stack template.
  in: body
  required: true
  type: object
@ -1170,16 +1162,9 @@ stack:
  in: body
  required: true
  type: object
-stack_disable_rollback:
+stack_action:
  description: |
-    Whether deletion of all stack resources when stack creation fails is
-    enabled.
-  in: body
-  required: true
-  type: boolean
-stack_id:
-  description: |
-    The UUID of the stack.
+    The current action on the stack.
  in: body
  required: true
  type: string
@ -1190,6 +1175,24 @@ stack_disable_rollback:
  in: body
  required: true
  type: boolean
+stack_environment:
+  description: |
+    A JSON environment for the stack.
+  in: body
+  required: true
+  type: object
+stack_files:
+  description: |
+    A map containing the name and content of files used by the stack.
+  in: body
+  required: true
+  type: object
+stack_id:
+  description: |
+    The UUID of the stack.
+  in: body
+  required: true
+  type: string
 stack_name:
  description: |
    A name for the stack. The value must be unique within a project.
@ -1202,6 +1205,18 @@ stack_name:
  in: body
  required: true
  type: string
+stack_name_request:
+  description: |
+    A name for the stack. The value must be unique within a project.
+    The name must start with an ASCII letter and can contain ASCII letters,
+    digits, underscores, periods, and hyphens. Specifically, the name must
+    match the ``^[a-zA-Z][a-zA-Z0-9_.-]*$`` regular expression.
+
+    When you delete or abandon a stack, its name will not become available
+    for reuse until the deletion completes successfully.
+  in: body
+  required: true
+  type: string
 stack_outputs:
  description: |
    A list of stack outputs.
@ -1251,6 +1266,12 @@ stack_tags:
  in: body
  required: true
  type: string
+stack_template:
+  description: |
+    The template used to create the stack.
+  in: body
+  required: true
+  type: object
 stack_timeout_mins:
  description: |
    The timeout for stack creation in minutes.
@ -1343,6 +1364,31 @@ template_description:
  in: body
  required: true
  type: string
+template_description_show:
+  description: |
+    The description of the stack template.
+  in: body
+  required: false
+  type: string
+template_outputs:
+  description: |
+    Key and value pairs that contain output data.
+  in: body
+  required: true
+  type: object
+template_parameters:
+  description: |
+    Key and value pairs that contain the schemas of parameters acceptable by
+    the template.
+  in: body
+  required: true
+  type: object
+template_resources:
+  description: |
+    Key and value pairs that contain definition of resources in the template.
+  in: body
+  required: true
+  type: object
 template_url:
  description: |
    A URI to the location containing the stack template on which to perform
--- a/api-ref/source/v1/samples/stack-abandon-response.json
+++ b/api-ref/source/v1/samples/stack-abandon-response.json
@ -1,7 +1,24 @@
 {
-    "status": "COMPLETE",
+    "action": "CREATE",
+    "environment": {},
+    "files": {},
+    "id": "16934ca3-40e0-4fb2-a289-a700662ec05a",
    "name": "g",
-    "dry_run": true,
+    "project_id": "369166a68a3a49b78b4e138531556e55",
+    "resources": {
+        "server": {
+            "status": "COMPLETE",
+            "name": "server",
+            "resource_data": {},
+            "resource_id": "39d5dad7-7d7a-4cc8-bd84-851e9e2ff4ea",
+            "action": "CREATE",
+            "type": "OS::Nova::Server",
+            "metadata": {}
+        }
+    },
+    "stack_user_project_id": "9bbd353467bc4f069a3692d223a48aac",
+    "status": "COMPLETE",
+    "tags": null,
    "template": {
        "outputs": {
            "instance_ip": {
@ -52,18 +69,5 @@
                "type": "string"
            }
        }
-    },
-    "action": "CREATE",
-    "id": "16934ca3-40e0-4fb2-a289-a700662ec05a",
-    "resources": {
-        "server": {
-            "status": "COMPLETE",
-            "name": "server",
-            "resource_data": {},
-            "resource_id": "39d5dad7-7d7a-4cc8-bd84-851e9e2ff4ea",
-            "action": "CREATE",
-            "type": "OS::Nova::Server",
-            "metadata": {}
-        }
    }
 }
--- a/api-ref/source/v1/samples/stack-adopt-request.json
+++ b/api-ref/source/v1/samples/stack-adopt-request.json
@ -28,6 +28,6 @@
            }
        }
    },
-    "stack_name": "{stack_name}",
-    "timeout_mins": "{timeout_mins}"
+    "stack_name": "new_stack",
+    "timeout_mins": 30
 }
--- a/api-ref/source/v1/stacks.inc
+++ b/api-ref/source/v1/stacks.inc
@ -34,7 +34,7 @@ Request Parameters
   - environment: environment
   - files: files
   - parameters: parameters
-   - stack_name: stack_name
+   - stack_name: stack_name_request
   - tags: tags
   - template: template
   - template_url: template_url
@ -95,7 +95,7 @@ Request Parameters
   - environment: environment
   - files: files
   - parameters: parameters
-   - stack_name: stack_name
+   - stack_name: stack_name_request
   - tags: tags
   - template: template
   - template_url: template_url
@ -558,12 +558,25 @@ Abandon stack

 Deletes a stack but leaves its resources intact, and returns data that describes the stack and its resources.

-This method can be disabled from the server side. If it is
-disabled, this call throws an exception.
+This is a preview feature which has to be explicitly enabled by setting the
+following option in the ``heat.conf`` file::

+  [DEFAULT]
+  enable_stack_abandon = True

-Normal response codes: 200
-Error response codes:404,500,401,400,
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 404
+   - 500

 Request Parameters
 ------------------
@ -574,6 +587,23 @@ Request Parameters
   - stack_name: stack_name_url
   - stack_id: stack_id_url

+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - action: stack_action
+   - environment: stack_environment
+   - files: stack_files
+   - id: stack_id
+   - stack_name: stack_name
+   - project_id: project_id
+   - resources: resources_abandon
+   - stack_user_project_id: stack_stack_user_project_id
+   - status: stack_status
+   - tags: stack_tags
+   - template: stack_template
+
 Response Example
 ----------------

@ -588,7 +618,25 @@ Adopt stack

 Creates a stack from existing resources.

-Error response codes:201,500,409,401,400,
+This is a preview feature which has to be explicitly enabled by setting the
+following option in the ``heat.conf`` file::
+
+  [DEFAULT]
+  enable_stack_adopt = True
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 201
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 409
+   - 500

 Request Parameters
 ------------------
@ -596,12 +644,12 @@ Request Parameters
 .. rest_parameters:: parameters.yaml

   - tenant_id: tenant_id
-   - files: files
+   - adopt_stack_data: adopt_stack_data
   - disable_rollback: disable_rollback
+   - environment: environment
+   - files: files
   - parameters: parameters
   - stack_name: stack_name
-   - adopt_stack_data: adopt_stack_data
-   - environment: environment
   - timeout_mins: timeout_mins

 Request Example
@ -615,9 +663,17 @@ Response Parameters

 .. rest_parameters:: parameters.yaml

+   - location: location
+   - X-Openstack-Reqeuest-Id: request_id
+   - stack: stack
   - id: id
   - links: links
-   - stack: stack
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stack-create-response.json
+   :language: javascript


 Get stack template
@ -627,12 +683,22 @@ Get stack template

 Gets a template for a stack.

+Response Codes
+--------------

-Normal response codes: 200
-Error response codes:404,500,401,400,
+.. rest_status_code:: success status.yaml

-Request
-------
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 404
+   - 500
+
+Request Parameters
+------------------

 .. rest_parameters:: parameters.yaml

@ -645,11 +711,12 @@ Response Parameters

 .. rest_parameters:: parameters.yaml

-   - outputs: outputs
+   - X-Openstack-Reqeuest-Id: request_id
   - heat_template_version: heat_template_version
-   - description: description
-   - parameters: parameters
-   - resources: resources
+   - outputs: template_outputs
+   - parameters: template_parameters
+   - description: template_description_show
+   - resources: template_resources

 Response Example
 ----------------