From 959b5694dfbc318c0c933298743db75e4269c119 Mon Sep 17 00:00:00 2001 From: tengqm Date: Thu, 18 Aug 2016 23:50:00 -0400 Subject: [PATCH] api-ref doc for stack (5) This is the last patch concerning api-ref docs for stack resources. The major changes are about stack-abandon, stack-adopt, template-show APIs. Change-Id: I2af6e5ba653ac2dfa6a81478a17367bf4f661944 --- api-ref/source/v1/parameters.yaml | 88 +++++++++++---- .../v1/samples/stack-abandon-response.json | 34 +++--- .../v1/samples/stack-adopt-request.json | 4 +- api-ref/source/v1/stacks.inc | 105 ++++++++++++++---- 4 files changed, 174 insertions(+), 57 deletions(-) diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml index 6d53f225f..4894cbdd9 100644 --- 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 diff --git a/api-ref/source/v1/samples/stack-abandon-response.json b/api-ref/source/v1/samples/stack-abandon-response.json index 57bd22da2..c021cf875 100644 --- 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": {} - } } } diff --git a/api-ref/source/v1/samples/stack-adopt-request.json b/api-ref/source/v1/samples/stack-adopt-request.json index 242afb161..c1b82f984 100644 --- 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 } diff --git a/api-ref/source/v1/stacks.inc b/api-ref/source/v1/stacks.inc index 188c6d24b..8ed07b200 100644 --- 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 ----------------