F OpenNebula/one#6673: Extend Sunstone User Inputs (#3072)

to contain layout information Signed-off-by: dcarracedo <[email protected]>
OpenNebula · Oct 8, 2024 · b56c4c3 · b56c4c3
1 parent 860e3ff
commit b56c4c3
Show file tree

Hide file tree

Showing 14 changed files with 229 additions and 0 deletions.
diff --git a/source/images/oneflow-templates-attrs.png b/source/images/oneflow-templates-attrs.png
diff --git a/source/images/sunstone_oneflow_serviceinputs_convention.png b/source/images/sunstone_oneflow_serviceinputs_convention.png
diff --git a/source/images/sunstone_oneflow_serviceinputs_layout.png b/source/images/sunstone_oneflow_serviceinputs_layout.png
diff --git a/source/images/sunstone_oneflow_serviceinputs_noconvention.png b/source/images/sunstone_oneflow_serviceinputs_noconvention.png
diff --git a/source/images/sunstone_oneflow_serviceinputs_noconvention_template.png b/source/images/sunstone_oneflow_serviceinputs_noconvention_template.png
diff --git a/source/images/sunstone_user_inputs_convention_blog.png b/source/images/sunstone_user_inputs_convention_blog.png
diff --git a/source/images/sunstone_user_inputs_convention_mysql_1.png b/source/images/sunstone_user_inputs_convention_mysql_1.png
diff --git a/source/images/sunstone_user_inputs_convention_mysql_2.png b/source/images/sunstone_user_inputs_convention_mysql_2.png
diff --git a/source/images/sunstone_user_inputs_metadata_1.png b/source/images/sunstone_user_inputs_metadata_1.png
diff --git a/source/images/sunstone_user_inputs_metadata_2.png b/source/images/sunstone_user_inputs_metadata_2.png
diff --git a/source/images/sunstone_user_inputs_no_convention.png b/source/images/sunstone_user_inputs_no_convention.png
diff --git a/source/management_and_operations/multivm_service_management/appflow_use_cli.rst b/source/management_and_operations/multivm_service_management/appflow_use_cli.rst
@@ -338,6 +338,80 @@ From Sunstone, you can add User Inputs as fields during the creation of the OneF
 
 .. note:: Currently, Custom Attributes are not supported in Sunstone. In order to add custom attributes, you need to use the CLI.
 
+.. _oneflow-sunstone-userinputs:
+
+**Render user inputs in Sunstone**
+
+When a service template is instantiated using Sunstone, the user will be asked to fill the user inputs that the service template has defined. So, using the following user inputs:
+
+.. code:: 
+
+  "custom_attrs": {
+    "APACHE_USER": "O|text|Apache user||",
+    "APACHE_ENDPOINT": "O|text|Apache endpoint||"
+  },
+
+A step called Service Inputs will render the user inputs for the service:
+
+|sunstone_oneflow_serviceinputs_noconvention|
+
+In order to improve the user experience, Sunstone can render this user inputs in a different way, easy to understand to the Sunstone user. To do that, Sunstone uses rules based on the name of the user inputs. :ref:`That rules are the same as the ones used in virtual machines templates <sunstone_layout_rules>`.
+
+So, if the previous template is modified as follows:
+
+.. code:: 
+
+  "custom_attrs": {
+    "ONEAPP_APACHE_CONFIG_USER": "O|text|Apache user||",
+    "ONEAPP_APACHE_CONFIG_ENDPOINT": "O|text|Apache endpoint||"
+  },
+
+The user inputs will be grouped in a tab called APACHE with a group called CONFIG:
+
+|sunstone_oneflow_serviceinputs_convention|
+
+If the service has a role with a virtual machine template that has user inputs that do not exist on the service template, these user inputs that belong to the virtual machine template will be rendered in a different step called Roles Inputs.
+
+So, if the service template references to the :ref:`virtual machine template defined in <vm_guide_user_inputs_sunstone>` Sunstone will look like:
+
+|sunstone_oneflow_serviceinputs_noconvention_template|
+
+Where all the user inputs that belong to the virtual machine template and are not in the service template are grouped in a tab with the name of the role.
+
+**Additional data to render user inputs in Sunstone**
+
+In order to help the Sunstone user, the service templates can be extended with an attribute called ``custom_attrs_metadata`` that will be adding some info to the APPS and GROUPS.
+
+.. note:: The attribute ``custom_attrs_metadata`` only will be used in Sunstone, not in others components of OpenNebula.
+
+So, if we use the previous template and add the following information:
+
+.. code:: 
+
+  "custom_attrs_metadata": [
+    {
+      "type": "APP",
+      "name": "APACHE",
+      "title": "Apache",
+      "description": "Description of the Apache section."
+    },
+    {
+      "type": "GROUP",
+      "name": "CONFIG",
+      "title": "Configuration",
+      "description": "Description of the Configuration section."
+    }
+  ],  
+  "logo": "data:image/png;base64,<BASE64_IMAGE>"
+
+Where BASE64_IMAGE is an image in base64 format, Sunstone will render the following:
+
+|sunstone_oneflow_serviceinputs_layout|
+
+Using logo attribute we can add a logo to the service template in base64. Also, adding info objects with metadata (:ref:`please, see user inputs metadata <template_user_inputs_metadata>` to get info about the object structure).
+
+.. note:: Remember that any user input that doesn't meet convention name will be place on the Others tab or Others group. If all user inputs don't meet convention name, no tabs or groups will be rendered.
+
 .. _service_clone:
 
 Clone a Service Template
@@ -837,3 +911,7 @@ For more information on the resource representation, please check the :ref:`API
 .. |oneflow-network-mapping-router_context_config| image:: /images/oneflow-network-map-router_context_config.png
 .. |oneflow-network-mapping-service_template_nw_config| image:: /images/oneflow-network-map-service_template_nw_config.png
 .. |oneflow-network-mapping-service_template_role_router| image:: /images/oneflow-network-map-service_template_role_router.png
+.. |sunstone_oneflow_serviceinputs_noconvention| image:: /images/sunstone_oneflow_serviceinputs_noconvention.png
+.. |sunstone_oneflow_serviceinputs_noconvention_template| image:: /images/sunstone_oneflow_serviceinputs_noconvention_template.png
+.. |sunstone_oneflow_serviceinputs_convention| image:: /images/sunstone_oneflow_serviceinputs_convention.png
+.. |sunstone_oneflow_serviceinputs_layout| image:: /images/sunstone_oneflow_serviceinputs_layout.png
diff --git a/source/management_and_operations/references/template.rst b/source/management_and_operations/references/template.rst
@@ -1299,6 +1299,48 @@ In Sunstone, the ``USER_INPUTS`` can be ordered with the mouse.
 
 |user_inputs|
 
+.. _template_user_inputs_metadata:
+
+``USER_INPUTS_METADATA`` provides the template creator with the possibility to add titles and descriptions to the user inputs. To understand how Sunstone renders user inputs metadata, :ref:`see User Inputs in Sunstone <vm_guide_user_inputs_sunstone>`.
+
+.. note:: ``USER_INPUTS_METADATA`` only will be used in Sunstone, not in others components of OpenNebula.
+
++-----------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+|   Attribute     | Mandatory | Description                                                                                                                                                                      |
++=================+===========+==================================================================================================================================================================================+
+| ``TYPE``        | Yes       | Type of the metadata. Possible values: ``APP`` or ``GROUP``.                                                                                                                     |
++-----------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``NAME``        | Yes       | Name of the user input. It has to be an existing user input name in the same template.                                                                                           |
++-----------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``TITLE``       | No        | In the case of ``APP`` is the text that will be showed to the user in a Sunstone tab. In the case of ``GROUP`` is the text that will be showed to the user in a Sunstone group.  |
++-----------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``DESCRIPTION`` | No        | In the case of ``APP`` is a text info note that will be showed in the APP tab. In the case of ``GROUP`` is the text that will be showed as info text in the Sunstone group.      |
++-----------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+Example:
+
+.. code::
+
+  USER_INPUTS_METADATA=[
+    DESCRIPTION="This tab includes all the information about the blog section in this template.",
+    NAME="BLOG",
+    TITLE="Blog",
+    TYPE="APP" ]
+  USER_INPUTS_METADATA=[
+    NAME="MYSQL",
+    TITLE="MySQL",
+    TYPE="APP" ]
+  USER_INPUTS_METADATA=[
+    DESCRIPTION="MySQL configuration parameters",
+    NAME="CONFIG",
+    TITLE="Configuration",
+    TYPE="GROUP" ]
+  USER_INPUTS_METADATA=[
+    DESCRIPTION="Additional MySQL parameters",
+    NAME="ADDITIONAL",
+    TITLE="Additional parameters",
+    TYPE="GROUP" ]
+
 .. _template_schedule_actions:
 
 Schedule actions Section

diff --git a/source/management_and_operations/vm_management/vm_templates.rst b/source/management_and_operations/vm_management/vm_templates.rst
@@ -162,6 +162,109 @@ The User Inputs functionality provides the VM Template creator the possibility t
 
 :ref:`See User Inputs Section in the VM Template reference <template_user_inputs>`.
 
+.. _vm_guide_user_inputs_sunstone:
+
+User Inputs in Sunstone
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a virtual machine template is instantiated using Sunstone, the user will be asked to fill the user inputs that are defined in the virtual machine template. So, using the following user inputs:
+
+.. code-block:: none
+
+    USER_INPUTS = [
+      BLOG_TITLE="M|text|Blog Title",
+      BLOG_DESCRIPTION="O|text|Blog Description",
+      MYSQL_ENDPOINT="M|text|MySQL Endpoint",
+      MYSQL_USER="O|password|MySQL User",
+      MYSQL_PASSWORD="O|password|MySQL Password",
+      MYSQL_ADDITIONAL="O|boolean|Define additional parameters",
+      MYSQL_SOCKET="O|text|MySQL Socket",
+      MYSQL_CHARSET="O|text|MySQL Charset",
+    ]
+
+The result will be a step with all the user inputs that are defined in the template:
+
+|sunstone_user_inputs_no_convention|
+
+In order to improve the user experience, Sunstone can render this user inputs in a different way, easy to understand to the Sunstone user. To do that, Sunstone uses rules based on the name of the user inputs. That rules are:
+
+.. _sunstone_layout_rules:
+
+- User input name has to meet the following convention ``ONEAPP_<APP>_<GROUP>_<FIELD>`` where all the user inputs that meet this convention will be grouped by APP and GROUP. An APP will be render as a tab in Sunstone and a GROUP will group the user inputs that belong to this group.
+- If ``FIELD`` is the word ``ENABLED`` and the user input type is boolean, all the user inputs that has the same APP and GROUP will be hidden until the ENABLED user input is turn on.
+- If a user input not meet the convention, will be placed in a tab called Others.
+- If all the user inputs do not meet the convention name, no tabs will be rendered (as the previous example).
+
+So, if the previous template is modified as follows:
+
+.. code-block:: none
+
+    USER_INPUTS = [
+      ONEAPP_BLOG_CONF_TITLE="M|text|Blog Title",
+      ONEAPP_BLOG_CONF_DESCRIPTION="O|text|Blog Description",
+      ONEAPP_MYSQL_CONFIG_ENDPOINT="M|text|MySQL Endpoint",
+      ONEAPP_MYSQL_CONFIG_USER="O|password|MySQL User",
+      ONEAPP_MYSQL_CONFIG_PASSWORD="O|password|MySQL Password",
+      ONEAPP_MYSQL_ADDITIONAL_ENABLED="O|boolean|Define additional parameters",
+      ONEAPP_MYSQL_ADDITIONAL_SOCKET="O|text|MySQL Socket",
+      ONEAPP_MYSQL_ADDITIONAL_CHARSET="O|text|MySQL Charset",
+    ]
+
+The user inputs will be grouped in a tab called BLOG with a group called CONF:
+
+|sunstone_user_inputs_convention_blog|
+
+Also, there will be a tab called MYSQL with two groups, CONFIG and ADDITIONAL:
+
+|sunstone_user_inputs_convention_mysql_1|
+
+To see the user inputs in the ADDITONAL group, the user must turn on the Define additional parameters user input:
+
+|sunstone_user_inputs_convention_mysql_2|
+
+
+Additional data for User Inputs in Sunstone
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to help the Sunstone user, the virtual machine templates can be extended with an attribute called USER_INPUTS_METADATA that will be adding some info to the APPS and GROUPS.
+
+:ref:`See User Inputs Section Metadata in the VM Template reference <template_user_inputs_metadata>`.
+
+.. note:: The attribute ``USER_INPUTS_METADATA`` only will be used in Sunstone, not in others components of OpenNebula.
+
+So, if we use the previous template and add the following information:
+
+.. code::
+
+  USER_INPUTS_METADATA=[
+    DESCRIPTION="This tab includes all the information about the blog section in this template.",
+    NAME="BLOG",
+    TITLE="Blog",
+    TYPE="APP" ]
+  USER_INPUTS_METADATA=[
+    NAME="MYSQL",
+    TITLE="MySQL",
+    TYPE="APP" ]
+  USER_INPUTS_METADATA=[
+    DESCRIPTION="MySQL configuration parameters",
+    NAME="CONFIG",
+    TITLE="Configuration",
+    TYPE="GROUP" ]
+  USER_INPUTS_METADATA=[
+    DESCRIPTION="Additional MySQL parameters",
+    NAME="ADDITIONAL",
+    TITLE="Additional parameters",
+    TYPE="GROUP" ]
+
+Due to the elements with TYPE equal to APP, BLOG tab has title Blog and MYSQL tab has title MySQL (TITLE attribute). Also, due to these elements, we have an info note in the Blog tab (DESCRIPTION attribute):
+
+|sunstone_user_inputs_metadata_1|
+
+Due to the elements with TYPE equal to GROUP, CONFIG group has title Configuration and ADDITIONAL group has title Additional parameters (TTILE attribute). Also, due to these elements Sunstone shows a info text in both groups (DESCRIPTION attribute):
+
+|sunstone_user_inputs_metadata_2|
+
+
 .. _sched_actions_templ:
 
 Schedule Actions
@@ -459,3 +562,9 @@ Sunstone exposes the above functionality in the Templates > VM Templates tab:
 
 .. |sunstone_template_share| image:: /images/sunstone_template_share.png
 .. |sunstone_template_create| image:: /images/sunstone_template_create.png
+.. |sunstone_user_inputs_no_convention| image:: /images/sunstone_user_inputs_no_convention.png
+.. |sunstone_user_inputs_convention_blog| image:: /images/sunstone_user_inputs_convention_blog.png
+.. |sunstone_user_inputs_convention_mysql_1| image:: /images/sunstone_user_inputs_convention_mysql_1.png
+.. |sunstone_user_inputs_convention_mysql_2| image:: /images/sunstone_user_inputs_convention_mysql_2.png
+.. |sunstone_user_inputs_metadata_1| image:: /images/sunstone_user_inputs_metadata_1.png
+.. |sunstone_user_inputs_metadata_2| image:: /images/sunstone_user_inputs_metadata_2.png