From 4ddff85b44bded1f3b4ef443f2fa84492db9ec0d Mon Sep 17 00:00:00 2001 From: Felipe Monteiro Date: Tue, 25 Apr 2017 20:11:32 +0100 Subject: [PATCH] Add environment templates to api-ref This patch adds the environment templates api to api-ref. Change-Id: I42d7016196839ac00ae14663f7addde3746ea1d1 Partially-Implements: blueprint murano-api-ref --- api-ref/source/v1/parameters.yaml | 137 ++++- .../v1/samples/template-add-app-request.json | 18 + .../v1/samples/template-add-app-response.json | 30 ++ .../v1/samples/template-clone-request.json | 3 + .../v1/samples/template-clone-response.json | 9 + .../samples/template-create-env-request.json | 3 + .../samples/template-create-env-response.json | 8 + .../v1/samples/template-create-request.json | 3 + .../v1/samples/template-create-response.json | 11 + .../samples/template-list-apps-response.json | 33 ++ .../v1/samples/template-show-response.json | 31 ++ .../samples/template-update-app-request.json | 18 + .../samples/template-update-app-response.json | 21 + .../v1/samples/templates-list-response.json | 26 + api-ref/source/v1/templates.inc | 509 ++++++++++++++++++ 15 files changed, 857 insertions(+), 3 deletions(-) create mode 100644 api-ref/source/v1/samples/template-add-app-request.json create mode 100644 api-ref/source/v1/samples/template-add-app-response.json create mode 100644 api-ref/source/v1/samples/template-clone-request.json create mode 100644 api-ref/source/v1/samples/template-clone-response.json create mode 100644 api-ref/source/v1/samples/template-create-env-request.json create mode 100644 api-ref/source/v1/samples/template-create-env-response.json create mode 100644 api-ref/source/v1/samples/template-create-request.json create mode 100644 api-ref/source/v1/samples/template-create-response.json create mode 100644 api-ref/source/v1/samples/template-list-apps-response.json create mode 100644 api-ref/source/v1/samples/template-show-response.json create mode 100644 api-ref/source/v1/samples/template-update-app-request.json create mode 100644 api-ref/source/v1/samples/template-update-app-response.json create mode 100644 api-ref/source/v1/samples/templates-list-response.json diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml index 2593e280d..c2c6156fe 100644 --- a/api-ref/source/v1/parameters.yaml +++ b/api-ref/source/v1/parameters.yaml @@ -49,12 +49,37 @@ pkg_id_url: in: path required: true type: string +service_id_url: + description: + The UUID of a service belonging to an environment template. + in: path + required: true + type: string session_id_url: description: | The UUID of the session. in: path required: true type: string +template_id_url: + description: | + The UUID of the environment template. + in: path + required: true + type: string +template_is_public_url: + description: | + Indicates whether public environment templates are listed or not. The + following options are possible: + + - ``True``. Public environments templates from all projects are listed. + - ``False``. Private environments templates from current project are + listed. + - ``empty``. All project templates plus public templates from all projects. + are listed + in: path + required: false + type: boolean # variables in query all_tenants: @@ -366,7 +391,7 @@ regions: type: array services: description: | - A list of ``services`` object. + A list of ``service`` objects. in: body required: true type: array @@ -403,10 +428,116 @@ tags: in: body required: true type: array +template_description: + description: | + The enviroment template description. + in: body + required: true + type: string +template_id: + description: | + The UUID of the environment template. + in: body + required: true + type: string +template_is_public: + description: | + Indicates whether an environment template is public or not. + + - ``True``. The environment template is public. Can be cloned. + - ``False``. The environment template is private. + in: body + required: true + type: boolean +template_name: + description: | + The name of the environment template. Only alphanumeric characters are + allowed. + in: body + required: true + type: string +template_service: + description: | + Detailed information about the ``service`` to be added to the environment + template. The ``service`` includes virtual resources and application + information. The virtual resources information is specified inside the + ``instance`` object property. Application information is specified + inside the body of the ``service`` object. + + The ``instance`` object properties include: + + - ``assignFloatingIp``. Whether to assign a floating IP to the VM. + - ``keyname``. The key name of a key pair for the VM. + - ``image``. The image to be used to provision the VM. + - ``flavor``. The flavor to be used to provision the VM. + - ``?``. An object which includes the ``type`` of the server. + + An example ``instance`` looks like:: + + { + "assignFloatingIp": "true", + "keyname": "mykeyname", + "image": "cloud-fedora-v3", + "flavor": "m1.medium", + "?": { + "type": "io.murano.resources.LinuxMuranoInstance", + "id": "ef984a74-29a4-45c0-b1dc-2ab9f075732e" + } + } + + In addition, the ``service`` should also include the following: + + - ``name``. The ``name`` of the application. + - ``?``. An object that includes the ``type`` and ``id`` of the + application. An example ``type`` is: + "io.murano.resources.LinuxMuranoInstance". + - ``port``: The port to be used by the application. The value must be + greater than 0 and less than 65536 (although formatted as a string). + + The entire ``service`` looks like:: + + { + "instance": { + "assignFloatingIp": "true", + "keyname": "mykeyname", + "image": "cloud-fedora-v3", + "flavor": "m1.medium", + "?": { + "type": "io.murano.resources.LinuxMuranoInstance", + "id": "ef984a74-29a4-45c0-b1dc-2ab9f075732e" + } + }, + "name": "orion", + "?": { + "type": "io.murano.apps.apache.Tomcat", + "id": "54cea43d-5970-4c73-b9ac-fea656f3c722" + }, + "port": "8080" + } + in: body + required: true + type: object +template_services: + description: | + The list of environment template ``service`` objects. + in: body + required: true + type: array +template_version: + description: | + The current version of the environment template. + in: body + required: true + type: integer +templates: + description: | + The list of templates. + in: body + required: true + type: array tenant_id: description: | - The UUID of the tenant. A tenant is also known as - a project. + The UUID of the tenant. A tenant is also known as a project. in: body required: true type: string diff --git a/api-ref/source/v1/samples/template-add-app-request.json b/api-ref/source/v1/samples/template-add-app-request.json new file mode 100644 index 000000000..37c9e1582 --- /dev/null +++ b/api-ref/source/v1/samples/template-add-app-request.json @@ -0,0 +1,18 @@ +{ + "instance": { + "assignFloatingIp": "true", + "keyname": "mykeyname", + "image": "cloud-fedora-v3", + "flavor": "m1.medium", + "?": { + "type": "io.murano.resources.LinuxMuranoInstance", + "id": "ef984a74-29a4-45c0-b1dc-2ab9f075732e" + } + }, + "name": "orion", + "?": { + "type": "io.murano.apps.apache.Tomcat", + "id": "54cea43d-5970-4c73-b9ac-fea656f3c722" + }, + "port": "8080" +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/template-add-app-response.json b/api-ref/source/v1/samples/template-add-app-response.json new file mode 100644 index 000000000..22a8e77e5 --- /dev/null +++ b/api-ref/source/v1/samples/template-add-app-response.json @@ -0,0 +1,30 @@ +{ + "updated": "2017-04-26T19:41:58", + "created": "2017-04-26T19:33:10", + "tenant_id": "cca37eef752244d99945a4123f30ff79", + "services": [ + { + "instance": { + "assignFloatingIp": "true", + "keyname": "mykeyname", + "image": "cloud-fedora-v3", + "flavor": "m1.medium", + "?": { + "type": "io.murano.resources.LinuxMuranoInstance", + "id": "ef984a74-29a4-45c0-b1dc-2ab9f075732e" + } + }, + "name": "orion", + "?": { + "type": "io.murano.apps.apache.Tomcat", + "id": "54cea43d-5970-4c73-b9ac-fea656f3c722" + }, + "port": "8080" + } + ], + "version": 0, + "description_text": "", + "is_public": false, + "id": "64670f5ada0848408734b2985f5cbb92", + "name": "test_application" +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/template-clone-request.json b/api-ref/source/v1/samples/template-clone-request.json new file mode 100644 index 000000000..4da52938f --- /dev/null +++ b/api-ref/source/v1/samples/template-clone-request.json @@ -0,0 +1,3 @@ +{ + "name": "cloned_env_template_name" +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/template-clone-response.json b/api-ref/source/v1/samples/template-clone-response.json new file mode 100644 index 000000000..b107d9676 --- /dev/null +++ b/api-ref/source/v1/samples/template-clone-response.json @@ -0,0 +1,9 @@ +{ + "updated": "2015-01-26T09:12:51", + "name": "cloned_env_template_name", + "created": "2015-01-26T09:12:51", + "tenant_id": "00000000000000000000000000000001", + "version": 0, + "is_public": false, + "id": "aa9033ca7ce245fca10e38e1c8c4bbf7", +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/template-create-env-request.json b/api-ref/source/v1/samples/template-create-env-request.json new file mode 100644 index 000000000..85f6962bc --- /dev/null +++ b/api-ref/source/v1/samples/template-create-env-request.json @@ -0,0 +1,3 @@ +{ + "name": "environment_name" +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/template-create-env-response.json b/api-ref/source/v1/samples/template-create-env-response.json new file mode 100644 index 000000000..72db44524 --- /dev/null +++ b/api-ref/source/v1/samples/template-create-env-response.json @@ -0,0 +1,8 @@ +{ + "environment_id": "aa90fadfafca10e38e1c8c4bbf7", + "name": "environment_name", + "created": "2015-01-26T09:12:51", + "tenant_id": "00000000000000000000000000000001", + "version": 0, + "session_id": "adf4dadfaa9033ca7ce245fca10e38e1c8c4bbf7", +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/template-create-request.json b/api-ref/source/v1/samples/template-create-request.json new file mode 100644 index 000000000..fe54e28b9 --- /dev/null +++ b/api-ref/source/v1/samples/template-create-request.json @@ -0,0 +1,3 @@ +{ + "name": "env_template_name" +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/template-create-response.json b/api-ref/source/v1/samples/template-create-response.json new file mode 100644 index 000000000..338005c0a --- /dev/null +++ b/api-ref/source/v1/samples/template-create-response.json @@ -0,0 +1,11 @@ +{ + "updated": "2014-05-14T13:02:55", + "networking": {}, + "name": "test2", + "created": "2014-05-14T13:02:51", + "tenant_id": "123452452345346345634563456345346", + "version": 0, + "is_public": true, + "description_text": "", + "id": "744e44812da84e858946f5d817de4f72" +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/template-list-apps-response.json b/api-ref/source/v1/samples/template-list-apps-response.json new file mode 100644 index 000000000..a80b9a620 --- /dev/null +++ b/api-ref/source/v1/samples/template-list-apps-response.json @@ -0,0 +1,33 @@ +[ + { + "instance": + { + "assignFloatingIp": "true", + "keyname": "mykeyname", + "image": "cloud-fedora-v3", + "flavor": "m1.medium", + "?": + { + "type": "io.murano.resources.LinuxMuranoInstance", + "id": "ef984a74-29a4-45c0-b1dc-2ab9f075732e" + } + }, + "name": "tomcat", + "?": + { + "type": "io.murano.apps.apache.Tomcat", + "id": "54cea43d-5970-4c73-b9ac-fea656f3c722" + }, + "port": "8080" + }, + { + "instance": "ef984a74-29a4-45c0-b1dc-2ab9f075732e", + "password": "XXX", + "name": "mysql", + "?": + { + "type": "io.murano.apps.database.MySQL", + "id": "54cea43d-5970-4c73-b9ac-fea656f3c722" + } + } +] \ No newline at end of file diff --git a/api-ref/source/v1/samples/template-show-response.json b/api-ref/source/v1/samples/template-show-response.json new file mode 100644 index 000000000..cbc030679 --- /dev/null +++ b/api-ref/source/v1/samples/template-show-response.json @@ -0,0 +1,31 @@ +{ + "updated": "2014-05-14T13:02:55", + "networking": {}, + "name": "test2", + "created": "2014-05-14T13:02:51", + "tenant_id": "123452452345346345634563456345346", + "services": [ + { + "instance": { + "assignFloatingIp": "true", + "keyname": "mykeyname", + "image": "cloud-fedora-v3", + "flavor": "m1.medium", + "?": { + "type": "io.murano.resources.LinuxMuranoInstance", + "id": "ef984a74-29a4-45c0-b1dc-2ab9f075732e" + } + }, + "name": "orion", + "?": { + "type": "io.murano.apps.apache.Tomcat", + "id": "54cea43d-5970-4c73-b9ac-fea656f3c722" + }, + "port": "8080" + } + ], + "version": 0, + "is_public": true, + "description_text": "", + "id": "744e44812da84e858946f5d817de4f72" +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/template-update-app-request.json b/api-ref/source/v1/samples/template-update-app-request.json new file mode 100644 index 000000000..9fc3ebc52 --- /dev/null +++ b/api-ref/source/v1/samples/template-update-app-request.json @@ -0,0 +1,18 @@ +{ + "instance": { + "assignFloatingIp": "true", + "keyname": "mykeyname", + "image": "cloud-fedora-v3", + "flavor": "m1.medium", + "?": { + "type": "io.murano.resources.LinuxMuranoInstance", + "id": "ef984a74-29a4-45c0-b1dc-2ab9f075732e" + } + }, + "name": "orion", + "port": "8080", + "?": { + "type": "io.murano.apps.apache.Tomcat", + "id": "54cea43d-5970-4c73-b9ac-fea656f3c722" + } +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/template-update-app-response.json b/api-ref/source/v1/samples/template-update-app-response.json new file mode 100644 index 000000000..4d084278e --- /dev/null +++ b/api-ref/source/v1/samples/template-update-app-response.json @@ -0,0 +1,21 @@ +{ + "instance": + { + "assignFloatingIp": "true", + "keyname": "mykeyname", + "image": "cloud-fedora-v3", + "flavor": "m1.medium", + "?": + { + "type": "io.murano.resources.LinuxMuranoInstance", + "id": "ef984a74-29a4-45c0-b1dc-2ab9f075732e" + } + }, + "name": "orion", + "?": + { + "type": "io.murano.apps.apache.Tomcat", + "id": "54cea43d-5970-4c73-b9ac-fea656f3c722" + }, + "port": "8080" +} \ No newline at end of file diff --git a/api-ref/source/v1/samples/templates-list-response.json b/api-ref/source/v1/samples/templates-list-response.json new file mode 100644 index 000000000..3c6b45215 --- /dev/null +++ b/api-ref/source/v1/samples/templates-list-response.json @@ -0,0 +1,26 @@ +{ + "templates": [ + { + "updated": "2014-05-14T13:02:54", + "networking": {}, + "name": "test1", + "created": "2014-05-14T13:02:46", + "tenant_id": "726ed856965f43cc8e565bc991fa76c3", + "version": 0, + "is_public": false, + "description_text": "", + "id": "2fa5ab704749444bbeafe7991b412c33" + }, + { + "updated": "2014-05-14T13:02:55", + "networking": {}, + "name": "test2", + "created": "2014-05-14T13:02:51", + "tenant_id": "123452452345346345634563456345346", + "version": 0, + "is_public": true, + "description_text": "", + "id": "744e44812da84e858946f5d817de4f72" + } + ] +} \ No newline at end of file diff --git a/api-ref/source/v1/templates.inc b/api-ref/source/v1/templates.inc index e69de29bb..432b9fb9e 100644 --- a/api-ref/source/v1/templates.inc +++ b/api-ref/source/v1/templates.inc @@ -0,0 +1,509 @@ +.. -*- rst -*- + +===================== +Environment Templates +===================== + +An environment template specifies a set of virtual resources and application +information that can be deployed on top of OpenStack by translation this +information into an application-ready environment. Environment templates can +be customized, created, deleted and modified by users. Environment templates +can be instantied as many times as the user desires. For example, the user can +have different deployments from the same environment template: one for testing +and another for production. + +The workflow for the creation and the instantiation of the environment template +is as follows: + +#. Creation of the environment template (including application information) +#. Transformation of the environment template into the environment + (creation of the environment and session and adding applications to the + environment) +#. Deployment of the environment on top of Openstack + +Each environment template consists of services, which specify the application +information. Each service includes information about the applications that +will be installed (e.g. Tomcat), including application properties like +the Tomcat port. Additional information pertaining to the virtual server +may be specified, if applicable, such as keyname, flavor, image, etc. + +The following is an example of an environment template:: + + { + "name": "env_template_name", + "services": [ + { + "instance": { + "assignFloatingIp": "true", + "keyname": "mykeyname", + "image": "cloud-fedora-v3", + "flavor": "m1.medium", + "?": { + "type": "io.murano.resources.LinuxMuranoInstance", + "id": "ef984a74-29a4-45c0-b1dc-2ab9f075732e" + } + }, + "name": "tomcat", + "port": "8080", + "?": { + "type": "io.murano.apps.apache.Tomcat", + "id": "54cea43d-5970-4c73-b9ac-fea656f3c722" + } + } + ] + } + +List environment templates +========================== + +.. rest_method:: GET /templates + +Get a list of environment templates. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - is_public: template_is_public_url + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - templates: templates + - created: created + - updated: updated + - name: template_name + - tenant_id: tenant_id + - version: template_version + - description_text: template_description + - is_public: template_is_public + - id: template_id + +Response Example +---------------- + +.. literalinclude:: samples/templates-list-response.json + :language: javascript + +Create environment template +=========================== + +.. rest_method:: POST /templates + +Create an environment template. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 409 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - name: template_name + - is_public: template_is_public + +Request Example +--------------- + +.. literalinclude:: samples/template-create-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - created: created + - updated: updated + - name: template_name + - tenant_id: tenant_id + - version: template_version + - description_text: template_description + - is_public: template_is_public + - id: template_id + +Response Example +---------------- + +.. literalinclude:: samples/template-create-response.json + :language: javascript + +Get environment template details +================================ + +.. rest_method:: GET /templates/{env_temp_id} + +Get details for the environment template ``env_temp_id``. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 404 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - env_temp_id: template_id_url + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - created: created + - updated: updated + - name: template_name + - services: template_services + - tenant_id: tenant_id + - version: template_version + - description_text: template_description + - is_public: template_is_public + - id: template_id + +Response Example +---------------- + +.. literalinclude:: samples/template-show-response.json + :language: javascript + +Delete environment template +=========================== + +.. rest_method:: DELETE /templates/{env_temp_id} + +Delete the environment template ``env_temp_id``. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 404 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - env_temp_id: template_id_url + +Add application to environment template +======================================= + +.. rest_method:: POST /templates/{env_temp_id}/services + +Create a new application for environment template ``env_temp_id``. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 404 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - env_temp_id: template_id_url + - service: template_service + +Request Example +--------------- + +.. literalinclude:: samples/template-add-app-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - updated: updated + - created: created + - tenant_id: tenant_id + - services: template_services + - version: template_version + - description_text: template_description + - is_public: template_is_public + - id: template_id + - name: template_name + +Response Example +---------------- + +.. literalinclude:: samples/template-add-app-response.json + :language: javascript + +Delete application from an environment template +=============================================== + +.. rest_method:: DELETE /templates/{env_temp_id}/services/{service_id} + +Delete an application from an environment template. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 404 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - env_temp_id: template_id_url + - service_id: service_id_url + +List application details for environment template +================================================= + +.. rest_method:: GET /templates/{env_temp_id}/services + +List all the applications for the specified environment template +``env_temp_id``. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 404 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - env_temp_id: template_id_url + +Response Parameters +------------------- + + - updated: updated + - created: created + - tenant_id: tenant_id + - services: template_services + - version: template_version + - description_text: template_description + - is_public: template_is_public + - id: template_id + - name: template_name + +Response Example +---------------- + +.. literalinclude:: samples/template-list-apps-response.json + :language: javascript + +Update application for an environment template +============================================== + +.. rest_method:: PUT /templates/{env_temp_id}/services/{service_id} + +Delete an application from an environment template. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 404 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - env_temp_id: template_id_url + - service_id: service_id_url + - service: template_service + +Request Example +--------------- + +.. literalinclude:: samples/template-update-app-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - service: template_service + +Response Example +---------------- + +.. literalinclude:: samples/template-update-app-response.json + :language: javascript + +Create environment from environment template +============================================ + +.. rest_method:: GET /templates/{env_temp_id}/create-environment + +Create an environment from the environment template ``env_temp_id``. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 404 + - 409 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - env_temp_id: template_id_url + - name: env_name + +Request Example +--------------- + +.. literalinclude:: samples/template-create-env-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - environment_id: env_id + - name: env_name + - created: created + - tenant_id: tenant_id + - version: env_version + - session_id: session_id + +Response Example +---------------- + +.. literalinclude:: samples/template-create-env-response.json + :language: javascript + +Clone environment template +========================== + +.. rest_method:: GET /templates/{env_temp_id}/clone + +Clones an environment template from one tenant into another. + +.. note: + + In order to clone an environment template, the template *must* be + public. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 404 + - 409 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - env_temp_id: template_id_url + - name: template_name + +Request Example +--------------- + +.. literalinclude:: samples/template-clone-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - environment_id: env_id + - name: env_name + - created: created + - tenant_id: tenant_id + - version: env_version + - session_id: session_id + +Response Example +---------------- + +.. literalinclude:: samples/template-clone-response.json + :language: javascript