Merge "Add environment templates to api-ref"

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:
@@ -390,7 +415,7 @@ regions:
   type: array
 services:
   description: |
-    A list of ``services`` object.
+    A list of ``service`` objects.
   in: body
   required: true
   type: array
@@ -427,10 +452,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

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"
+}

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"
+}

api-ref/source/v1/samples/template-clone-request.json

@@ -0,0 +1,3 @@
+{
+    "name": "cloned_env_template_name"
+}

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",
+}

api-ref/source/v1/samples/template-create-env-request.json

@@ -0,0 +1,3 @@
+{
+    "name": "environment_name"
+}

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",
+}

api-ref/source/v1/samples/template-create-request.json

@@ -0,0 +1,3 @@
+{
+    "name": "env_template_name"
+}

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"
+}

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"
+    }
+  }
+]

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"
+}

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"
+    }
+}

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"
+}

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"
+        }
+    ]
+}

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