diff --git a/source/images/oneflow-services-list.png b/source/images/oneflow-services-list.png new file mode 100644 index 000000000..6187b245c Binary files /dev/null and b/source/images/oneflow-services-list.png differ diff --git a/source/images/oneflow-templates-delete.png b/source/images/oneflow-templates-delete.png new file mode 100644 index 000000000..113b1cb8c Binary files /dev/null and b/source/images/oneflow-templates-delete.png differ diff --git a/source/images/oneflow-templates-list.png b/source/images/oneflow-templates-list.png new file mode 100644 index 000000000..b1c2c8a62 Binary files /dev/null and b/source/images/oneflow-templates-list.png differ diff --git a/source/images/oneflow-templates-update.png b/source/images/oneflow-templates-update.png new file mode 100644 index 000000000..f1199ae21 Binary files /dev/null and b/source/images/oneflow-templates-update.png differ diff --git a/source/integration_and_development/system_interfaces/appflow_api.rst b/source/integration_and_development/system_interfaces/appflow_api.rst index ffe65292d..716e4f076 100644 --- a/source/integration_and_development/system_interfaces/appflow_api.rst +++ b/source/integration_and_development/system_interfaces/appflow_api.rst @@ -130,7 +130,7 @@ A Service is defined with JSON syntax templates. +-----------------------+----------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``on_hold`` | boolean | **NO** | If on_hold is set to true, all VMs of the service will be created in ``HOLD`` state. | +-----------------------+----------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``custom_attrs`` | hash | **NO** | Hash of custom attributes to use in the service. | +| ``user_inputs`` | hash | **NO** | Hash of custom attributes to use in the service. | +-----------------------+----------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``networks`` | hash | **NO** | Hash of virtual networks to use in the service. | +-----------------------+----------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -146,7 +146,9 @@ Each Role is defined as: +-------------------------+-------------------+---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``cardinality`` | integer | **NO** | Number of VMs to deploy. Defaults to 1. | +-------------------------+-------------------+---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``vm_template`` | integer | **YES** | OpenNebula VM Template ID. See the :ref:`OpenNebula documentation for VM Templates `. | +| ``template_id`` | integer | **YES** | OpenNebula VM Template ID. See the :ref:`OpenNebula documentation for VM Templates `. | ++-------------------------+-------------------+---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``type`` | string | **YES** | Defines the role type, ``vm`` for VM role and ``vr`` for VR roles. | +-------------------------+-------------------+---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``parents`` | array of string | **NO** | Names of the roles that must be deployed before this one. | +-------------------------+-------------------+---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -208,192 +210,261 @@ And each scheduled policy is defined as: { :type => :object, :properties => { - 'name' => { - :type => :string, - :required => true - }, - 'deployment' => { - :type => :string, - :enum => %w{none straight}, - :default => 'none' - }, - 'description' => { - :type => :string, - :required => false - }, - 'shutdown_action' => { - :type => :string, - :enum => %w{terminate terminate-hard shutdown shutdown-hard}, - :required => false - }, - 'roles' => { - :type => :array, - :items => ROLE_SCHEMA, - :required => true - }, - 'custom_attrs' => { - :type => :object, - :properties => {}, - :required => false - }, - 'custom_attrs_values' => { - :type => :object, - :properties => {}, - :required => false - }, - 'networks' => { - :type => :object, - :properties => {}, - :required => false - }, - 'networks_values' => { - :type => :array, - :items => { - :type => :object, - :properties => {}}, - :required => false - }, - 'ready_status_gate' => { - :type => :boolean, - :required => false - }, - 'on_hold' => { - :type => :boolean, - :required => false - } + 'name' => { + :type => :string, + :required => true + }, + 'deployment' => { + :type => :string, + :default => 'none' + }, + 'description' => { + :type => :string, + :default => '' + }, + 'shutdown_action' => { + :type => :string, + :required => false + }, + 'roles' => { + :type => :array, + :items => [], + :required => true + }, + 'user_inputs' => { + :type => :object, + :properties => {}, + :required => false + }, + 'user_inputs_values' => { + :type => :object, + :properties => {}, + :required => false + }, + 'ready_status_gate' => { + :type => :boolean, + :required => false + }, + 'automatic_deletion' => { + :type => :boolean, + :required => false + }, + 'networks' => { + :type => :object, + :properties => {}, + :required => false + }, + 'networks_values' => { + :type => :array, + :items => { + :type => :object, + :properties => {} + }, + :required => false + }, + 'on_hold' => { + :type => :boolean, + :required => false + } } } .. _flow_role_schema: -Role Schema +VM Role Schema -------------------------------------------------------------------------------- .. code:: - { - :type => :object, - :properties => { +{ + :type => :object, + :properties => { 'name' => { - :type => :string, - :required => true + :type => :string, + :required => true, + :regex => /^\w+$/ + }, + 'type' => { + :type => :string, + :required => true }, 'cardinality' => { - :type => :integer, - :default => 1, - :minimum => 0 + :type => :integer, + :default => 0, + :minimum => 0 + }, + 'template_id' => { + :type => :integer, + :required => true }, - 'vm_template' => { - :type => :integer, - :required => true + 'template_contents' => { + :type => :object, + :properties => {}, + :required => false + }, + 'user_inputs' => { + :type => :object, + :properties => {}, + :required => false }, - 'vm_template_contents' => { - :type => :string, - :required => false + 'user_inputs_values' => { + :type => :object, + :properties => {}, + :required => false }, 'parents' => { - :type => :array, - :items => { - :type => :string - } + :type => :array, + :items => { + :type => :string + } }, 'shutdown_action' => { - :type => :string, - :enum => ['shutdown', 'shutdown-hard']}, - :required => false + :type => :string, + :required => false }, 'min_vms' => { - :type => :integer, - :required => false, - :minimum => 0 + :type => :integer, + :required => false, + :minimum => 0 }, 'max_vms' => { - :type => :integer, - :required => false, - :minimum => 0 + :type => :integer, + :required => false, + :minimum => 0 }, 'cooldown' => { - :type => :integer, - :required => false, - :minimum => 0 + :type => :integer, + :required => false, + :minimum => 0 }, 'on_hold' => { - :type => :boolean, - :required => false + :type => :boolean, + :required => false }, 'elasticity_policies' => { - :type => :array, - :items => { - :type => :object, - :properties => { - 'type' => { - :type => :string, - :enum => ['CHANGE', 'CARDINALITY', 'PERCENTAGE_CHANGE'], - :required => true - }, - 'adjust' => { - :type => :integer, - :required => true - }, - 'min_adjust_step' => { - :type => :integer, - :required => false, - :minimum => 1 - }, - 'period_number' => { - :type => :integer, - :required => false, - :minimum => 0 - }, - 'period' => { - :type => :integer, - :required => false, - :minimum => 0 - }, - 'expression' => { - :type => :string, - :required => true - }, - 'cooldown' => { - :type => :integer, - :required => false, - :minimum => 0 - } + :type => :array, + :items => { + :type => :object, + :properties => { + 'type' => { + :type => :string, + :required => true + }, + 'adjust' => { + :type => :integer, + :required => true + }, + 'min_adjust_step' => { + :type => :integer, + :required => false, + :minimum => 1 + }, + 'period_number' => { + :type => :integer, + :required => false, + :minimum => 0 + }, + 'period' => { + :type => :integer, + :required => false, + :minimum => 0 + }, + 'expression' => { + :type => :string, + :required => true + }, + 'cooldown' => { + :type => :integer, + :required => false, + :minimum => 0 + } + } } - } }, 'scheduled_policies' => { - :type => :array, - :items => { + :type => :array, + :items => { + :type => :object, + :properties => { + 'type' => { + :type => :string, + :required => true + }, + 'adjust' => { + :type => :integer, + :required => true + }, + 'min_adjust_step' => { + :type => :integer, + :required => false, + :minimum => 1 + }, + 'start_time' => { + :type => :string, + :required => false + }, + 'recurrence' => { + :type => :string, + :required => false + } + } + } + } + } + } + +VR Role Schema +-------------------------------------------------------------------------------- + +.. code:: + { + :type => :object, + :properties => { + 'name' => { + :type => :string, + :required => true, + :regex => /^\w+$/ + }, + 'type' => { + :type => :string, + :required => true + }, + 'template_id' => { + :type => :integer, + :required => true + }, + 'cardinality' => { + :type => :integer, + :default => 0, + :minimum => 0 + }, + 'template_contents' => { :type => :object, - :properties => { - 'type' => { - :type => :string, - :enum => ['CHANGE', 'CARDINALITY', 'PERCENTAGE_CHANGE'], - :required => true - }, - 'adjust' => { - :type => :integer, - :required => true - }, - 'min_adjust_step' => { - :type => :integer, - :required => false, - :minimum => 1 - }, - 'start_time' => { - :type => :string, - :required => false - }, - 'recurrence' => { - :type => :string, - :required => false - } + :properties => {}, + :required => false + }, + 'user_inputs' => { + :type => :object, + :properties => {}, + :required => false + }, + 'user_inputs_values' => { + :type => :object, + :properties => {}, + :required => false + }, + 'on_hold' => { + :type => :boolean, + :required => false + }, + 'parents' => { + :type => :array, + :items => { + :type => :string } - } } - } } + } Action Schema -------------------------------------------------------------------------------- @@ -447,7 +518,8 @@ Create a New Service Template { "name":"frontend", "cardinality":"1", - "vm_template":"0", + "template_id":"0", + "type": "vm", "shutdown_action":"shutdown", "min_vms":"1", "max_vms":"4", @@ -474,7 +546,8 @@ Create a New Service Template { "name":"worker", "cardinality":"2", - "vm_template":"0", + "template_id":"0", + "type": "vm", "shutdown_action":"shutdown", "parents":[ "frontend" @@ -532,7 +605,8 @@ Create a New Service Template "recurrence": "0 2 1-10 * * " } ], - "vm_template": 0, + "template_id": 0, + "type": "vm", "name": "frontend", "min_vms": 1, "max_vms": 4, @@ -555,7 +629,8 @@ Create a New Service Template "scheduled_policies": [ ], - "vm_template": 0, + "template_id": 0, + "type": "vm", "name": "worker", "min_vms": 2, "max_vms": 10, @@ -644,7 +719,8 @@ Get Detailed Information of a Given Service Template "recurrence": "0 2 1-10 * * " } ], - "vm_template": 0, + "template_id": 0, + "type": "vm", ... List the Available Service Templates @@ -693,7 +769,8 @@ List the Available Service Templates "recurrence": "0 2 1-10 * * " } ], - "vm_template": 0, + "template_id": 0, + "type": "vm", "name": "frontend", "min_vms": 1, "max_vms": 4, @@ -722,7 +799,7 @@ Update a Given Template { "name":"frontend", "cardinality":"1", - "vm_template":"0", + "template_id":"0", "shutdown_action":"shutdown-hard", "min_vms":"1", "max_vms":"4", @@ -749,7 +826,8 @@ Update a Given Template { "name":"worker", "cardinality":"2", - "vm_template":"0", + "template_id":"0", + "type": "vm", "shutdown_action":"shutdown", "parents":[ "frontend" @@ -809,7 +887,8 @@ Update a Given Template "recurrence": "0 2 1-10 * * " } ], - "vm_template": 0, + "template_id": 0, + "type": "vm", "name": "frontend", "min_vms": 1, "max_vms": 4, @@ -868,7 +947,8 @@ Instantiate a Given Template "recurrence": "0 2 1-10 * * " } ], - "vm_template": 0, + "template_id": 0, + "type": "vm", Additional parameters can be passed using the ``merge_template`` inside the ``params``. For example, if we want to change the name when instantiating: @@ -884,8 +964,8 @@ Additional parameters can be passed using the ``merge_template`` inside the ``pa The following attributes can be also passed using the ``merge_template``: * ``network_values`` -* ``custom_attrs_values`` -* ``vm_template_contents`` +* ``user_inputs_values`` +* ``template_contents`` For example, instantiate a service template with custom VM capacity @@ -894,8 +974,19 @@ For example, instantiate a service template with custom VM capacity curl http://127.0.0.1:2474/service_template/4/action -u 'oneadmin:password' -v -X POST --data '{ "action": { "perform":"instantiate", - "params":{"merge_template":{"vm_template_contents":"HOT_RESIZE=[CPU_HOT_ADD_ENABLED=\"YES\",\nMEMORY_HOT_ADD_ENABLED=\"YES\"]\nMEMORY_RESIZE_MODE=\"BALLOONING\"\nVCPU_MAX= \"2\"\nMEMORY_MAX=\"128\""}} - } + "params":{ + "merge_template": { + "template_contents": { + "HOT_RESIZE": { + "CPU_HOT_ADD_ENABLED": "YES", + "MEMORY_HOT_ADD_ENABLED": "YES" + }, + "MEMORY_RESIZE_MODE": "BALLOONING", + "VCPU_MAX": "2", + "MEMORY_MAX": "128" + } + } + } }' @@ -974,7 +1065,8 @@ Get Detailed Information of a Given Service "recurrence": "0 2 1-10 * * " } ], - "vm_template": 0, + "template_id": 0, + "type": "vm", "disposed_nodes": [ ], @@ -1020,7 +1112,8 @@ Get Detailed Information of a Given Service "scheduled_policies": [ ], - "vm_template": 0, + "template_id": 0, + "type": "vm", "disposed_nodes": [ ], @@ -1265,7 +1358,8 @@ Add a role to a running service "role" : '{ "name": "NEW_ROLE", "cardinality": 1, - "vm_template": 0, + "template_id": 0, + "type": "vm", "min_vms": 1, "max_vms": 2, "elasticity_policies": [], @@ -1318,7 +1412,8 @@ Append can be used to append information to the service, in this case the reques { "name":"frontend", "cardinality":"1", - "vm_template":"0", + "template_id":"0", + "type": "vm", "shutdown_action":"shutdown-hard", "min_vms":"1", "max_vms":"4", @@ -1345,7 +1440,8 @@ Append can be used to append information to the service, in this case the reques { "name":"worker", "cardinality":"2", - "vm_template":"0", + "template_id":"0", + "type": "vm", "shutdown_action":"shutdown", "parents":[ "frontend" @@ -1405,7 +1501,8 @@ Append can be used to append information to the service, in this case the reques "recurrence": "0 2 1-10 * * " } ], - "vm_template": 0, + "template_id": 0, + "type": "vm", "name": "frontend", "min_vms": 1, "max_vms": 4, 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 index 784dcbf16..aee04353d 100644 --- a/source/management_and_operations/multivm_service_management/appflow_use_cli.rst +++ b/source/management_and_operations/multivm_service_management/appflow_use_cli.rst @@ -20,49 +20,159 @@ This Service can be represented with the following JSON template: { "name": "my_service", "deployment": "straight", - "ready_status_gate": true|false, "roles": [ { "name": "frontend", - "vm_template": 0 + "cardinality": 1, + "template_id": 0, + "type": "vm" }, { "name": "db_master", + "cardinality": 1, + "template_id": 1, + "type": "vm", "parents": [ "frontend" - ], - "vm_template": 1 + ] }, { "name": "db_slave", + "cardinality": 3, + "template_id": 2, + "type": "vm", "parents": [ "frontend" - ], - "cardinality": 3, - "vm_template": 2 + ] }, { "name": "worker", + "cardinality": 10, + "template_id": 3, + "type": "vm", "parents": [ "db_master", "db_slave" - ], - "cardinality": 10, - "vm_template": 3 + ] } ] } -Defining a new Service: Templates +Service Templates ================================================================================ OneFlow allows OpenNebula administrators and users to register Service Templates in OpenNebula, to be instantiated later as Services. These Templates can be instantiated several times, and also shared with other users. -Users can manage the Service Templates using the command ``oneflow-template``, or Sunstone. For each user, the actual list of Service Templates available is determined by the ownership and permissions of the Templates. +Below are all the attributes that can appear within a Service, which will be covered in detail throughout this guide: + ++---------------------+-----------+------------+--------------------------------------------------------------------------------------------+ +| Attribute | Type | Mandatory | Description | ++=====================+===========+============+============================================================================================+ +| ``name`` | string | Yes | The name of the service. | ++------------------------+-----------+------------+-----------------------------------------------------------------------------------------+ +| ``deployment`` | string | No | The type of deployment. Can be ``none`` or ``straight``. Defaults to ``none``. | ++------------------------+-----------+------------+-----------------------------------------------------------------------------------------+ +| ``description`` | string | No | A description of the service. Defaults to an empty string. | ++------------------------+-----------+------------+-----------------------------------------------------------------------------------------+ +| ``shutdown_action`` | string | No | Action to take on shutdown. Can be ``terminate``, ``terminate-hard``, ``shutdown``, | +| | | | or ``shutdown-hard``. | ++------------------------+-----------+------------+-----------------------------------------------------------------------------------------+ +| ``roles`` | array | Yes | An array of roles within the service. | ++------------------------+-----------+------------+-----------------------------------------------------------------------------------------+ +| ``user_inputs`` | object | No | A set of user inputs defined by properties. | ++------------------------+-----------+------------+-----------------------------------------------------------------------------------------+ +| ``user_inputs_values`` | object | No | Values for the user inputs. | ++------------------------+-----------+------------+-----------------------------------------------------------------------------------------+ +| ``ready_status_gate`` | boolean | No | Indicates if the service should wait until it is fully ready. | ++------------------------+-----------+------------+-----------------------------------------------------------------------------------------+ +| ``automatic_deletion`` | boolean | No | Whether the service should be deleted automatically after use. | ++------------------------+-----------+------------+-----------------------------------------------------------------------------------------+ +| ``networks`` | object | No | Networks associated with the service. | ++------------------------+-----------+------------+-----------------------------------------------------------------------------------------+ +| ``networks_values`` | array | No | Values for the networks, represented as an array of objects. | ++------------------------+-----------+------------+-----------------------------------------------------------------------------------------+ +| ``on_hold`` | boolean | No | If true, the service will be held and not deployed automatically. | ++------------------------+-----------+------------+-----------------------------------------------------------------------------------------+ + +.. note:: The table shown above is just a summary of the main Service template attributes. For a full information on the Service representation, please check the :ref:`API data model guide ` + +Defining the Roles of a Service +-------------------------------------------------------------------------------- + +A Role defines a set of virtual resources that are part of a Service. These resources can either be Virtual Machines (VMs) or Virtual Routers (VRs), depending on the type of Role. Each Role describes attributes like the number of instances (cardinality), the template to be used, and various scaling policies, among others. + +Roles are used to orchestrate and manage these resources according to attributes set in their respective templates. There are two main types of Roles: + +1. **VM Role**: this Role defines a Virtual Machine Role within the Service. It is primarily used to manage a group of Virtual Machines that are part of the Service. This Role includes attributes like ``template_id``, which specifies the VM template to be used, as well as options for scaling and elasticity policies. + + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | Attribute | Type | Mandatory | Description | + +=========================+===========+============+============================================================================================+ + | ``name`` | string | Yes | The name of the VM Role. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``type`` | string | Yes | Must be ``vm`` to define a Virtual Machine Role. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``cardinality`` | integer | No | The number of VMs in this Role. Defaults to 0. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``template_id`` | integer | Yes | The ID of the template used to create VMs for this Role. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``template_contents`` | object | No | Additional template contents to be merged with the template. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``user_inputs`` | object | No | User-defined inputs that can be used in the Role configuration. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``user_inputs_values`` | object | No | Values for the user inputs. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``parents`` | array | No | An array of parent Role names. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``shutdown_action`` | string | No | The action to take when shutting down VMs (e.g., ``terminate``, ``shutdown``). | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``min_vms`` | integer | No | The minimum number of VMs allowed for this Role. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``max_vms`` | integer | No | The maximum number of VMs allowed for this Role. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``cooldown`` | integer | No | The cooldown period after scaling operations. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``on_hold`` | boolean | No | If true, the Role will be held and not deployed automatically. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``elasticity_policies`` | array | No | A list of elasticity policies to automatically adjust the number of VMs in the Role. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``scheduled_policies`` | array | No | A list of scheduled policies to adjust the number of VMs based on a schedule. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + +.. note:: Some defaults values like ``cooldown`` and ``shutdown_action`` can be customized in the OneFlow server configuration, located by default at ``/etc/one/oneflow-server.conf``. + + +1. **VR Role**: this Role defines a Virtual Router Role, which is responsible for managing Virtual Routers within the Service. Similar to the VM Role, it includes attributes like ``template_id`` and ``cardinality``, but is specifically designed to handle network routing services. Please note that in this case ``template_id`` must refer to a Virtual Router template. + + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | Attribute | Type | Mandatory | Description | + +=========================+===========+============+============================================================================================+ + | ``name`` | string | Yes | The name of the VR Role. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``type`` | string | Yes | Must be ``vr`` to define a Virtual Router Role. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``template_id`` | integer | Yes | The ID of the template used to create Virtual Routers for this Role. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``cardinality`` | integer | No | The number of Virtual Routers in this Role. Defaults to 0. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``template_contents`` | object | No | Additional template contents to be merged with the template. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``user_inputs`` | object | No | User-defined inputs that can be used in the Role configuration. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``user_inputs_values`` | object | No | Values for the user inputs. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``on_hold`` | boolean | No | If true, the Role will be held and not deployed automatically. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + | ``parents`` | array | No | An array of parent Role names. | + +-------------------------+-----------+------------+--------------------------------------------------------------------------------------------+ + +.. warning:: Keep in mind that Auto-scaling and Elasticity options for Virtual Router Roles are not supported, as these operations are not natively supported by Virtual Routers. Create and List Existing Service Templates -------------------------------------------------------------------------------- +Users can manage the Service Templates using the command ``oneflow-template``, or Sunstone. For each user, the actual list of Service Templates available is determined by the ownership and permissions of the Templates. + The command ``oneflow-template create`` registers a JSON template file. For example, if the previous example template is saved in ``/tmp/my_service.json``, you can execute: .. prompt:: bash $ auto @@ -106,237 +216,208 @@ To check details about a Service Template, use ``oneflow-template show``: .. _appflow_use_cli_delete_service_template: -Templates can be deleted with ``oneflow-template delete``. - -You can also delete VM templates associated to the service template: - -- ``--delete-vm-templates``: this will delete all the VM templates associated and the service template. -- ``--delete-images``: this will delete all the VM templates and images associated and the service template. -You can also create and manage Service Templates from Sunstone. +As shown in the image below, you can also create and list Service Templates from Sunstone from ``Templates`` > ``Service Templates``. -.. _appflow_use_cli_automatic_delete: +|oneflow-templates-list| -Automatic delete service if all roles are terminated +Updating a Service Template -------------------------------------------------------------------------------- -Service VMs can be terminated using scheduled actions or VM charters. This can lead to a situation where you have a running service with no VMs associated to it. To avoid this you can use automatic deletion feature. +To update an existing Service Template, use the following command, replacing ```` with the Service template's ID. This will open an editor where you can manually add new attributes: -To enable it, you need to add the following attribute to the service template: +.. code-block:: bash -.. prompt:: bash $ auto + oneflow-template update - "automatic_deletion": true +Alternatively, if you already have the new attributes defined in a file like the following: -.. _appflow_use_cli_running_state: +.. code-block:: json -Determining when a VM is READY --------------------------------------------------------------------------------- + { + "description": "new description for the service", + "roles": [ + { + "name": "frontend", + "cardinality": 3 + } + ] + } -Depending on the deployment strategy, OneFlow will wait until all the VMs in a specific Role are all in ``RUNNING`` state before deploying VMs that belong to a child Role. How OneFlow determines the running state of the VMs can be specified with the checkbox ``Consider VMs as running only when they report READY status via OneGate`` available in the Service creation dialog in Sunstone, or the attribute in ``ready_status_gate`` in the top level of the Service Template JSON. +You can update the Service Template by specifying the file in the command, as shown below: -|oneflow-ready-status-checkbox| +.. code-block:: bash -If ``ready_status_gate`` is set to ``true``, a VM will only be considered to be in running state the following points are true: + oneflow-template update -* VM is in ``RUNNING`` state for OpenNebula. Which specifically means that ``LCM_STATE==3`` and ``STATE>=3`` -* The VM has ``READY=YES`` in the user template. +The above example will update the description of the Service template and the cardinality of the ``frontend``` role after merging both files. -If ``ready_status_gate`` is set to ``false``, a VM will be considered to be in running state when it's in running state for OpenNebula (``LCM_STATE==3`` and ``STATE>=3``). Take into account that the VM will be considered ``RUNNING`` the very same moment the hypervisor boots the VM (before it loads the OS). +Updating Service Templates can also be done through Sunstone. Simply select the desired Service Template, making the changes through the graphical interface selecting the ``Update`` button in the toolbar; -.. _appflow_use_cli_networks: +|oneflow-templates-update| -Configure Dynamic Networks +Deleting a Service Templates -------------------------------------------------------------------------------- -Each Service Role has a :ref:`Virtual Machine Template ` assigned. The VM Template will define the capacity, disks, and network interfaces. Apart from defining the Virtual Networks in the VM Template, the Service Template can define a set of dynamic networks. - -|oneflow-templates-net-1| - -Then each Role of the service can be attached to one or more dynamic networks individually. The network can be attached to the Role as an alias. In this case, you need to specify the interface to add the alias by selecting the virtual network it will be attached to. For example the Role, ``slave`` in the next picture will have one physical interface attached to the ``PRIVATE`` network. This interface will also have a IP alias configured from network ``PUBLIC``. - -Additionally you can set if the VMs in the Role exposes an RDP endpoint. Equivalently, you need to specify the IP of the VM for the RDP connection by selecting the virtual network the interface is attached to. - -|oneflow-templates-net-2| - -A Service Template can define three different dynamic network modes, that determine how the networks will be used: +Templates can be deleted with ``oneflow-template delete``. -* **Existing Virtual Network**: VMs in the Role will just take a lease from that network. You'll probably use this method for networks with a predefined address set (e.g. public IPs). -* **Network reservation**: in this case it will take the existing network and create a reservation for the service. You have to specify the name of the reservation and the size in the input dialog. Use this method when you need to allocate a pool of IPs for your service. -* **Instantiate a network template**: in this case as an extra parameters you may have to specify the address range to create, depending on the selected network template. This is useful for service private VLAN for internal service communication. +In case you need it, you can also delete VM templates associated to the service template: -This allows you to create more generic Service Templates. For example, the same Service Template can be used by users of different :ref:`groups ` that may have access to different Virtual Networks. +- ``--delete-vm-templates``: this will delete all the VM templates associated and the service template. +- ``--delete-images``: this will delete all the VM templates and images associated and the service template. -.. note:: When the service is deleted, all the networks that have been created are automatically deleted. +You can delete Service templates in Sunstone as well by clicking on the trash can icon once the desired Service template is selected. -.. note:: You can provide suitable defaults for the dynamic networks +|oneflow-templates-delete| -All these operations can be also done through the CLI. When you instantiate the template using ``oneflow-template instantiate `` +.. _service_clone: -.. code:: +Clone a Service Template +-------------------------------------------------------------------------------- - # Use existing network - {"networks_values": [{"Private":{"id":"0"}}]} +A service template can be cloned to produce a copy, ready to be instantiated under another name. This copy can be recursive, so all the VM Templates forming the service will be cloned as well, and referenced from the cloned service. - # Reserve from a network - {"networks_values":[{"Private":{"reserve_from":"0", "extra": ""NAME=RESERVATION\nSIZE=5""}}]} +The ``oneflow-template clone`` (with the optional ``--recursive flag``) can be used to achieve this, as well as from the Sunstone service template tab. - # Instantiate a network template - {"networks_values": [{"Private":{"template_id":"0", "extra":"AR=[ IP=192.168.122.10, SIZE=10, TYPE=IP4 ]"}}]} +If the name of the VM template + Service Template exceed 128 chars, VM template name will be cropped. +.. note:: :ref:`Scheduled Actions ` cannot be defined in VM Templates if they are intended to be used as part of Service Templates. Please remove them prior to instantiate a service to avoid indeterministic behaviour. +.. _appflow_use_cli_automatic_delete: -Adding or Overwriting Attributes in Virtual Machine Templates +Adding or Overwriting Information in Service Templates -------------------------------------------------------------------------------- -To enhance or modify the functionality implemented by a Virtual Machine (VM) template of a role, you can use *User Inputs* and *Custom Attributes*. These attributes allow you to add more information and context to the template in a key-value format. Below are the main differences between these two attributes: +To enhance or modify the functionality implemented by a Virtual Machine (VM) template or a Virtual Role (VR) template of a role, you can use the ``template_contents`` attribute to add or overwrite information from the original template: -* **User Inputs**: ``user_inputs`` enable the creation of attributes that OpenNebula will prompt the user for during instantiation. These attributes are added to the context section of the VM, making their values accessible as environment variables within the VM. This feature is useful for creating variables and attributes inside the VM based on user input: +For example, you can use the ``template_contents`` to set custom attributes to the template or modify the capacity of the original VM, as it's shown below: - .. code:: +.. code-block:: json - { - "name": "User inputs example", - "description": "Service using user_inputs", - "deployment": "straight", - "roles": [ - { - "name": "master", - "vm_template": 0, - "cardinality": 1, - "vm_template_contents": "CONTEXT = [\nATT_A = \"$ATT_A\"\nATT_B = \"$ATT_B\"\n]" - }, - { - "name": "worker", - "vm_template": 1, - "cardinality": 2, - "vm_template_contents": "CONTEXT = [\nATT_B = \"$ATT_B\"\nATT_C = \"$ATT_C\"\n]" - } - ], - "user_inputs": { - "ATT_A": "O|fixed|| |2", - "ATT_B": "M|list||0.5,1,2,4|1", - "ATT_C": "M|range||512..8192|2048" + { + "name": "Sample Service", + "description": "Overwriting original template example", + "deployment": "straight", + "roles": [ + { + "name": "master", + "type": "vm", + "template_id": 0, + "cardinality": 1 + }, + { + "name": "worker", + "type": "vm", + "template_id": 1, + "cardinality": 2, + "template_contents": { + "CPU": 2, + "MY_ATT": "Some fancy value" + } } - } - - In OneFlow, ``user_inputs`` follow the same syntax used for VMs' ``user_inputs``. For more details on configuring allowed values, including default ones, please refer to this section of the documentation. - - .. warning:: Users need to manually define the content of the ``vm_template_content`` to pass the attributes to the VM. Use the convention ``ATT_NAME = $ATT_NAME`` in the ``vm_template_content``. During instantiation, OpenNebula will replace all ``$ATT_NAME`` variables with their corresponding values. - + ] + } -* **Custom attributes**: ``custom_attrs_values`` allow you to modify attributes and fields of the VM template. These attributes are added to the root of the VM template document, overwriting the existing information. For example, you can overwrite the CPU and Memory values of a template for a specific role: +You can also parameterize the content of the ``template_contents`` using the User Inputs feature. This functionality, as it appears in the usual Virtual Machines, allows to ask the user for attributes and values during instantiation time. You can add User Inputs to the Service template in the following way: - .. code:: +.. code-block:: json - { - "name": "Custom attributes example", - "description": "Service using custom_attributes", - "deployment": "straight", - "roles": [ - { - "name": "master", - "vm_template": 0, - "cardinality": 1 - }, - { - "name": "worker", - "vm_template": 1, - "cardinality": 2, - "vm_template_contents": "CPU = \"$CPU\"\nMEMORY = \"$MEMORY\"" - } - ], - "custom_attrs_values": { - "CPU": 2, - "MEMORY": 2048 + { + "name": "Sample Service", + "description": "Overwriting original template example", + "deployment": "straight", + "roles": [ + { + "name": "master", + "type": "vm", + "template_id": 0, + "cardinality": 1 + }, + { + "name": "worker", + "type": "vm", + "template_id": 1, + "cardinality": 2, + "template_contents": { + "CPU": 2, + "MY_ATT": "Some fancy value" } + } + ], + "user_inputs": { + "ATT_A": "O|fixed|| |2", + "ATT_B": "M|list||0.5,1,2,4|1", + "ATT_C": "M|range||512..8192|2048" } + } +This field follows the same syntactic convention as the User Entries for Virtual Machines to describe the attributes to be asked to the user, so we recommend reviewing the corresponding section for more information. - .. warning:: Similar to user inputs, the content of ``vm_template_contents`` must be manually created to use custom attributes. OpenNebula will automatically replace the content of each variable at instantiation time. - - - **Custom Attributes Levels** - - Custom attributes can be defined at two different levels: - - * **Service level**: custom attributes are applied to all roles in the service. You can define custom attributes at the service level as follows: +.. note:: All User Inputs will be automatically added to `template_contents` by OneFlow once the relevant attributes have been requested from the user. There is no need to manually include or reference them within `template_contents`. Additionally, OneFlow will also add all User Inputs to the CONTEXT of the Role's machines, similar to how User Inputs are handled in standard Virtual Machines. + As a result, all values provided by the user will be accessible from within the Role's machines via OpenNebula's context packages. - .. code:: +**User Inputs Scope** - { - ... - "roles": [ - { - "name": "worker" - "vm_template": 1, - "vm_template_contents": "ATT_A = \"$ATT_A\"\nATT_B = \"$ATT_B\"\n" - }, - ... - ] - "custom_attrs_values": { - "ATT_A": "A_VALUE", - "ATT_B": "B_VALUE" - }, - } +To enhance the flexibility of User Inputs in Service templates, they can be configured at both the Service Template level and the Role level. This allows for greater customization and adaptability based on the specific needs of each Role within the Service. - * **Role level**: custom attributes are applied to a single role within the service. Custom attributes can be combined at role and service level, where custom role attributes will take precedence. Below you can see an example of a service with two different roles and custom attributes at service and role level: +* **Service level**: User Inputs are applied to all roles in the service. You can define User Inputs at the Service level as follows: - .. code:: + .. code:: + { + "name": "Sample Service", + "description": "User Inputs at Service level example", + "deployment": "straight", + "roles": [ { - ... - "roles": [ - ... - { - "name": "worker", - "vm_template": 1, - "vm_template_contents": "ATT_A = \"$ATT_A\"\nATT_B = \"$ATT_B\"\n" - "custom_attrs_values": { - "ATT_A": "A_VALUE", - "ATT_B": "B_VALUE" - } - } - ] - ... - } - - .. note:: In case you use custom attributes at both levels, the custom attributes at the Role level will take precedence over the custom attributes at the Service level. + "name": "master", + "type": "vm", + "template_id": 0, + "cardinality": 1 + }, + ... + ], + "user_inputs": { + "ATT_A": "O|fixed|| |2", + "ATT_B": "M|list||0.5,1,2,4|1", + "ATT_C": "M|range||512..8192|2048" + } + } - .. note:: Custom attributes will be applied to all roles inside ``vm_template_contents`` section. When custom attributes coexist with user inputs of VM template, **custom attributes are preferred** to contextualization. +* **Role level**: User Inputs are applied to a single Role within the service. User Inputs can be combined at Role and Service level, where User Role Inputs will take precedence. Below you can see an example of a Service with User Inputs at different levels: - .. code:: + .. code:: + { + "name": "Sample Service", + "description": "User Inputs at Service level example", + "deployment": "straight", + "roles": [ { - ... - "roles": [ - { - "name": "worker", - "vm_template": 1, - "vm_template_contents": "ATT_A = \"$ATT_A\"\n" - } - ] - "custom_attrs_values":{ "ATT_A": "A_VALUE" }, - "user_inputs_values": { "ATT_A": "A_VALUE_OTHER"}, - } - - In this example, if the VM template contents attribute includes `CONTEXT = [ ATT_A = "$ATT_A" ]` before Service instantiation, after instantiation, it will be updated to `CONTEXT = [ ATT_A = "A_VALUE" ]`. - - -**Adding attributes through CLI** - -There are two ways, using the CLI, to add User Inputs or Custom Attributes to a Service Template: - -* **Creating a new Service template**: attributes can be added to a Service Template by including them in the JSON file used to create the Service Template. For example, to add a new User Input to a Service Template, you can include the User Input in the JSON file used to create the Service Template as shown in the examples above. Then, when you create the Service Template using the ``oneflow-template create `` command, where ``file`` indicates the path of the JSON file used to create the Service Template. -* **Updating an existing Service template**: attributes can be added to an existing Service Template by updating the template of the Service Template. To achieve this, you can use the ``oneflow-template update `` command. This command will open an editor where you can add the new attributes to the Service Template. Alternatively, you can use the ``oneflow-template update `` command to update the Service Template with the attributes included in the specified file. + "name": "master", + "type": "vm", + "template_id": 0, + "cardinality": 1, + "user_inputs": { + "ATT_B": "M|list||1,2,3,4|2", + } + }, + ... + ], + "user_inputs": { + "ATT_A": "O|fixed|| |2", + "ATT_B": "M|list||0.5,1,2,4|1", + "ATT_C": "M|range||512..8192|2048" + } + } -**Adding attributes through Sunstone** + .. note:: In case you use User Inputs at both levels, **the User Inputs at the Role level will take precedence** over the User Inputs at the Service level. -From Sunstone, you can add User Inputs as fields during the creation of the OneFlow service template or updating an already existing one in the following form: +From Sunstone, you can add User Inputs as fields during the creation of the OneFlow Service template or updating an already existing one in the following form: |oneflow-templates-attrs| -.. note:: Currently, Custom Attributes are not supported in Sunstone. In order to add custom attributes, you need to use the CLI. +In the same way as in the CLI, Sunstone will prompt the user for the User Inputs declared in the Service template during instantiation. .. _oneflow-sunstone-userinputs: @@ -346,7 +427,7 @@ When a service template is instantiated using Sunstone, the user will be asked t .. code:: - "custom_attrs": { + "user_inputs": { "APACHE_USER": "O|text|Apache user||", "APACHE_ENDPOINT": "O|text|Apache endpoint||" }, @@ -361,7 +442,7 @@ So, if the previous template is modified as follows: .. code:: - "custom_attrs": { + "user_inputs": { "ONEAPP_APACHE_CONFIG_USER": "O|text|Apache user||", "ONEAPP_APACHE_CONFIG_ENDPOINT": "O|text|Apache endpoint||" }, @@ -370,7 +451,7 @@ The user inputs will be grouped in a tab called APACHE with a group called CONFI |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. +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 ` Sunstone will look like: @@ -380,15 +461,15 @@ Where all the user inputs that belong to the virtual machine template and are no **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. +In order to help the Sunstone user, the service templates can be extended with an attribute called ``user_inputs_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. +.. 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:: - "custom_attrs_metadata": [ + "user_inputs_metadata": [ { "type": "APP", "name": "APACHE", @@ -412,47 +493,284 @@ Using logo attribute we can add a logo to the service template in base64. Also, .. 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: +.. _appflow_use_cli_networks: -Clone a Service Template +Configuring Dynamic Networks in a Service Template -------------------------------------------------------------------------------- -A service template can be cloned to produce a copy, ready to be instantiated under another name. This copy can be recursive, so all the VM Templates forming the service will be cloned as well, and referenced from the cloned service. +Each Service Role is assigned either a :ref:`Virtual Machine Template ` or a :ref:`Virtual Router Template `, depending on whether its type is ``vm`` or ``vr``, through the ``template_id`` attribute of each Role. This template defines the capacity and other characteristics of the instance, including network interfaces configuration. In addition to specifying Virtual Networks in the template, the Service Template can also define a set of dynamic networks. -The ``oneflow-template clone`` (with the optional ``--recursive flag``) can be used to achieve this, as well as from the Sunstone service template tab. +A Service Template can define three different dynamic network modes, determining how the networks will be used, and these must be declared in the template body under the ``network_values`` field. This three types are explained below: -If the name of the VM template + Service Template exceed 128 chars, VM template name will be cropped. +* **Existing Virtual Network**: VMs in the Role will take a lease from an existing network. You'll likely use this method for networks with a predefined address set (e.g., public IPs). -.. note:: :ref:`Scheduled Actions ` cannot be defined in VM Templates if they are intended to be used as part of Service Templates. Please remove them prior to instantiate a service to avoid indeterministic behaviour. + .. code-block:: json -Managing Services -================================================================================ + { + ... + "networks_values": [ + { "Public": { "id": "" } + } + ] + ... + } -A Service Template can be instantiated as a Service. Each newly created Service will be deployed by OneFlow following its deployment strategy. +* **Network reservation**: The system will create a reservation from an existing network for the Service. Specify the name of the reservation and its size. This method is useful when you need to allocate a pool of IPs for your Service. -Each Service Role creates :ref:`Virtual Machines ` in OpenNebula from :ref:`VM Templates `, that must be created beforehand. + .. code-block:: json -Create and List Existing Services --------------------------------------------------------------------------------- + { + ... + "networks_values": [ + { "Public": { + "reserve_from": "", + "extra": "NAME=RESERVATION\nSIZE=5" + } + } + ] + ... + } -New Services are created from Service Templates, using the ``oneflow-template instantiate`` command: +* **Instantiate a network template**: A network template is instantiated, and depending on the selected template, you might need to specify the address range to create (e.g., a private VLAN for internal Service communication). -.. prompt:: bash $ auto + .. code-block:: json - $ oneflow-template instantiate 0 - ID: 1 + { + ... + "networks_values": [ + { "Public": { + template_id": "$", + "extra": "AR=[ IP=192.168.122.10, SIZE=10, TYPE=IP4 ]" + } + } + ] + ... + } -To list the available Services, use ``oneflow list/top``: +This allows you to create more generic Service Templates. For example, the same Service Template can be used by users of different :ref:`groups ` that may have access to different Virtual Networks. -.. prompt:: bash $ auto +.. note:: When the service is deleted, all the networks that have been created are automatically deleted. - $ oneflow list - ID USER GROUP NAME STARTTIME STATE - 1 oneadmin oneadmin my_service 10/28 17:42:46 PENDING +In addition to specifying Virtual Networks in the template, the Service Template also needs to indicate which Roles will be connected to the dynamic networks, which can be achieved using the ``template_contents`` field. As stated in previous sections, this field is used to override the original template of the Virtual Machine or Virtual Router. For example, to attach a network to the Role, you can specify the following configuration: -|image3| +.. code-block:: json + { + ... + "roles": [ + ... + { + "name": "worker", + "type": "vm", + "template_id": 1, + "cardinality": 3, + "template_contents": { + "NIC": [ + { + "NETWORK_ID": "$Public", + "NAME": "NIC_0" + } + ] + } + }, + ... + ], + "networks_values": [ + { "Public": { + reserve_from": "", + "extra": "NAME=RESERVATION\nSIZE=5" + } + } + ], + ... + } + +In this example, the ``worker`` Role has a network interface attached described by the network ``Public`` defined in the ``network_values`` attribute. As it's described above, this ``Public`` network is a dynamic reservation of the Virtual Network indicated in ``reserve_from`` attribute. You can define multiple interfaces in the `NIC` array depending on how many networks need to be attached to the Role. + +All this functionalities are also available through the Sunstone portal, allowing you to quickly create dynamic networks with ease. + +|oneflow-templates-net-1| + +As you can see in the picture above, each Role of the service can be attached to one or more dynamic networks individually. The network can be attached to the Role as an alias. In this case, you need to specify the interface to add the alias by selecting the virtual network it will be attached to. For example the Role, ``slave`` in the next picture will have one physical interface attached to the ``PRIVATE`` network. This interface will also have a IP alias configured from network ``PUBLIC``. Additionally you can set if the VMs in the Role exposes an RDP endpoint. Equivalently, you need to specify the IP of the VM for the RDP connection by selecting the virtual network the interface is attached to. + +|oneflow-templates-net-2| + +Service +================================================================================ + +A Service Template can be instantiated as a Service. Each newly created Service will be deployed by OneFlow following its deployment strategy. + +Each Service Role creates :ref:`Virtual Machines ` in OpenNebula from :ref:`VM Templates `, that must be created beforehand. + +.. _appflow_use_cli_service_body:: + +Understanding a Service body +-------------------------------------------------------------------------------- -The Service will eventually change to ``DEPLOYING_NETS``. You can see information for each Role using ``oneflow show``. +The JSON body of a Service in OneFlow provides a detailed configuration of the Service, including its roles, network settings, user inputs, etc. The following is an example of what a standard Service body looks like in OneFlow: + +.. code-block:: json + + { + "name": "Sample Service", + "description": "Test service with two roles", + "state": 2, + "deployment": "none", + "roles": [ + { + "name": "Frontend", + "state": 2, + "type": "vm", + "cardinality": 1, + "template_id": 0, + "on_hold": false, + "min_vms": 1, + "max_vms": 5, + "elasticity_policies": [], + "scheduled_policies": [], + "template_contents": {}, + "nodes": [ + { + "deploy_id": 8, + "vm_info": { + "VM": { + "ID": "8", + "UID": "0", + "GID": "0", + "UNAME": "oneadmin", + "GNAME": "oneadmin", + "NAME": "MASTER_0_(service_5)" + } + } + } + ], + "last_vmname": 1 + }, + { + "name": "VNF", + "state": 2, + "type": "vr", + "cardinality": 3, + "template_id": 1, + "on_hold": false, + "vrouter_id": 2, + "template_contents": { + "NIC": [ + { + "NETWORK_ID": "$Public", + "NAME": "NIC_0" + }, + { + "NETWORK_ID": "$Private", + "NAME": "NIC_1" + } + ] + }, + "nodes": [ + { + "deploy_id": 10, + "vm_info": { + "VM": { + "ID": "10", + "UID": "0", + "GID": "0", + "UNAME": "oneadmin", + "GNAME": "oneadmin", + "NAME": "VR_ROLE_1_0_(service_5)" + } + } + }, + { + "deploy_id": 11, + "vm_info": { + "VM": { + "ID": "11", + "UID": "0", + "GID": "0", + "UNAME": "oneadmin", + "GNAME": "oneadmin", + "NAME": "VR_ROLE_1_1_(service_5)" + } + } + }, + { + "deploy_id": 12, + "vm_info": { + "VM": { + "ID": "12", + "UID": "0", + "GID": "0", + "UNAME": "oneadmin", + "GNAME": "oneadmin", + "NAME": "VR_ROLE_1_2_(service_5)" + } + } + } + ], + "last_vmname": 0 + } + ], + "shutdown_action": "terminate-hard", + "on_hold": false, + "ready_status_gate": false, + "automatic_deletion": false, + "registration_time": 1728498178, + "start_time": 1728498179, + "networks_values": [ + { "Public": { + "id": "0" + }, + "Private": { + "reserve_from": 2, + "extra": "NAME=MY_RESERVATION\nSIZE=5" + } + } + ], + "log": [ + { + "timestamp": 1728498179, + "severity": "I", + "message": "New state: DEPLOYING_NETS" + }, + { + "timestamp": 1728498179, + "severity": "I", + "message": "New state: DEPLOYING" + }, + { + "timestamp": 1728498185, + "severity": "I", + "message": "New state: RUNNING" + } + ] + } + } + +It's important to note the existence of some new attributes that has been added by OneFlow in the root of the Service body that didn't exist in the Service Template: + ++-------------------------+-----------+------------------------------------------------------------------------------------------------------------+ +| Attribute | Type | Description | ++=========================+===========+============+===============================================================================================+ +| ``state`` | integer | Represents the current state of the Service. For state values reference, see the life cycle section below. | ++-------------------------+-----------+------------------------------------------------------------------------------------------------------------+ +| ``log`` | array | Contains a log of important events, such as state changes, with a timestamp and severity. | +| | | Example: {"timestamp": 1728498179, "severity": "I", "message": "New state: RUNNING"}. | ++-------------------------+-----------+------------+-----------------------------------------------------------------------------------------------+ +| ``start_time`` | integer | The Unix timestamp of when the Service was started. Can be used for tracking up time. | ++-------------------------+-----------+------------+-----------------------------------------------------------------------------------------------+ + +New attributes have also been added within each role that show information relevant to each type of role. + ++-------------------------+-----------+------------+------------------------------------------------------------------------------------------+ +| Attribute | Type | Role type | Description | ++=========================+===========+============+============+=============================================================================+ +| ``state`` | integer | VM, VR | Current state of the Role. For state values reference, see the life cycle section below. | ++-------------------------+-----------+------------+------------+-----------------------------------------------------------------------------+ +| ``nodes`` | array | VM, VR | Array of the instances deployed for the Role, including VM/VR IDs (``deploy_id``) | ++-------------------------+-----------+------------+------------+-----------------------------------------------------------------------------+ +| ``last_vmname`` | integer | VM, VR | Tracks the last assigned VM identifier number in the Role. | ++-------------------------+-----------+------------+------------+-----------------------------------------------------------------------------+ +| ``vrouter_id`` | integer | VR | ID of the Virtual Router instance created by the Role. | ++-------------------------+-----------+------------+------------+-----------------------------------------------------------------------------+ .. _appflow_use_cli_life_cycle: @@ -470,82 +788,113 @@ Regardless of the strategy used, the Service will be ``RUNNING`` when all of the This table describes the Service states: -+-----------------------------+--------------------------------------------------------------------------------------------+ -| Service State | Meaning | -+=============================+============================================================================================+ -| ``PENDING`` | The Service starts in this state, and will stay in it until the LCM decides to deploy it. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``HOLD`` | All roles are in hold state. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``DEPLOYING`` | Some Roles are being deployed. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``DEPLOYING_NETS`` | Service networks are being deployed, they are in ``LOCK`` state. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``RUNNING`` | All Roles are deployed successfully. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``WARNING`` | A VM was found in a failure state. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``SCALING`` | A Role is scaling up or down. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``COOLDOWN`` | A Role is in the cooldown period after a scaling operation. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``UNDEPLOYING`` | Some Roles are being undeployed. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``UNDEPLOYING_NETS`` | Service networks are being undeployed, they are in ``LOCK`` state. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``FAILED_DEPLOYING`` | An error occurred while deploying the Service. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``FAILED_DEPLOYING_NETS`` | An error occurred while deploying the Service networks. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``FAILED_UNDEPLOYING`` | An error occurred while undeploying the Service. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``FAILED_UNDEPLOYING_NETS`` | An error occurred while undeploying the Service networks. | -+-----------------------------+--------------------------------------------------------------------------------------------+ -| ``FAILED_SCALING`` | An error occurred while scaling the Service. | -+-----------------------------+--------------------------------------------------------------------------------------------+ ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| Service State | Value | Meaning | ++=============================+=======+============================================================================================+ +| ``PENDING`` | 0 | The Service starts in this state, and will stay in it until the LCM decides to deploy it. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``DEPLOYING`` | 1 | Some Roles of the Service are being deployed. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``RUNNING`` | 2 | All Roles of the Service are deployed successfully. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``UNDEPLOYING`` | 3 | Some Roles of the Service are being undeployed. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``WARNING`` | 4 | A VM was found in a failure state. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``DONE`` | 5 | The Service has finished all actions and is marked as complete. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``FAILED_UNDEPLOYING`` | 6 | An error occurred while undeploying the Service. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``FAILED_DEPLOYING`` | 7 | An error occurred while deploying the Service. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``SCALING`` | 8 | A Role of the Service is scaling up or down. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``FAILED_SCALING`` | 9 | An error occurred while scaling the Service. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``COOLDOWN`` | 10 | A Role of the Service is in the cooldown period after a scaling operation. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``DEPLOYING_NETS`` | 11 | Service networks are being deployed, they are in ``LOCK`` state. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``UNDEPLOYING_NETS`` | 12 | Service networks are being undeployed, they are in ``LOCK`` state. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``FAILED_DEPLOYING_NETS`` | 13 | An error occurred while deploying the Service networks. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``FAILED_UNDEPLOYING_NETS`` | 14 | An error occurred while undeploying the Service networks. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ +| ``HOLD`` | 15 | All roles of the Service are in hold state. | ++-----------------------------+-------+--------------------------------------------------------------------------------------------+ Each Role has an individual state, described in the following table: -+--------------------------+-------------------------------------------------------------------------------------------+ -| Role State | Meaning | -+==========================+===========================================================================================+ -| ``PENDING`` | The Role is waiting to be deployed. | -+--------------------------+-------------------------------------------------------------------------------------------+ -| ``HOLD`` | The VMs are ``HOLD`` and will not be scheduled until them are released. | -+--------------------------+-------------------------------------------------------------------------------------------+ -| ``DEPLOYING`` | The VMs are being created, and will be monitored until all of them are ``RUNNING``. | -+--------------------------+-------------------------------------------------------------------------------------------+ -| ``RUNNING`` | All the VMs are ``RUNNING``. | -+--------------------------+-------------------------------------------------------------------------------------------+ -| ``WARNING`` | A VM was found in a failure state. | -+--------------------------+-------------------------------------------------------------------------------------------+ -| ``SCALING`` | The Role is waiting for VMs to be deployed or to be shutdown. | -+--------------------------+-------------------------------------------------------------------------------------------+ -| ``COOLDOWN`` | The Role is in the cooldown period after a scaling operation. | -+--------------------------+-------------------------------------------------------------------------------------------+ -| ``UNDEPLOYING`` | The VMs are being shutdown. The Role will stay in this state until all VMs are ``DONE``. | -+--------------------------+-------------------------------------------------------------------------------------------+ -| ``FAILED_DEPLOYING`` | An error occurred while deploying the VMs. | -+--------------------------+-------------------------------------------------------------------------------------------+ -| ``FAILED_UNDEPLOYING`` | An error occurred while undeploying the VMs. | -+--------------------------+-------------------------------------------------------------------------------------------+ -| ``FAILED_SCALING`` | An error occurred while scaling the Role. | -+--------------------------+-------------------------------------------------------------------------------------------+ - -Life-Cycle Operations ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ +| Role State | Value | Meaning | ++==========================+=======+=======================================================================================================+ +| ``PENDING`` | 0 | The Role is waiting to be deployed. | ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ +| ``DEPLOYING`` | 1 | The VMs of the Role are being created, and will be monitored until all of them are ``RUNNING``. | ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ +| ``RUNNING`` | 2 | All the VMs of the Role are ``RUNNING``. | ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ +| ``UNDEPLOYING`` | 3 | The VMs of the Role are being shutdown. The Role will stay in this state until all VMs are ``DONE``. | ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ +| ``WARNING`` | 4 | A VM of the Role was found in a failure state. | ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ +| ``DONE`` | 5 | The Role has finished all actions and is marked as complete. | ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ +| ``FAILED_UNDEPLOYING`` | 6 | An error occurred while undeploying the VMs of the Role. | ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ +| ``FAILED_DEPLOYING`` | 7 | An error occurred while deploying the VMs of the Role. | ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ +| ``SCALING`` | 8 | The Role is waiting for VMs to be deployed or to be shutdown. | ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ +| ``FAILED_SCALING`` | 9 | An error occurred while scaling the Role. | ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ +| ``COOLDOWN`` | 10 | The Role is in the cooldown period after a scaling operation. | ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ +| ``HOLD`` | 11 | The VMs of the Role are ``HOLD`` and will not be scheduled until they are released. | ++--------------------------+-------+-------------------------------------------------------------------------------------------------------+ + +Determining when a VM is READY (``RUNNING``) -------------------------------------------------------------------------------- -Services are deployed automatically by the Life Cycle Manager. To undeploy a running Service, users can use the command ``oneflow delete``. +Depending on the deployment strategy, OneFlow will wait until all the VMs in a specific Role are all in ``RUNNING`` state before deploying VMs that belong to a child Role. How OneFlow determines the running state of the VMs can be specified with the checkbox ``Consider VMs as running only when they report READY status via OneGate`` available in the Service creation dialog in Sunstone, or the attribute in ``ready_status_gate`` in the top level of the Service Template JSON. -The command ``oneflow delete`` will perform a graceful a ``terminate`` on all the running VMs (see :ref:`onevm terminate `). If the ``straight`` deployment strategy is used, the Roles will be shutdown in the reverse order of the deployment. +|oneflow-ready-status-checkbox| -If any of the VM terminate operations can't be performed, the Service state will show ``FAILED`` state, to indicate that manual intervention is required to complete the cleanup. In any case, the Service can be completely removed using the command ``oneflow recover --delete``. +If ``ready_status_gate`` is set to ``true``, a VM will only be considered to be in running state the following points are true: -When a Service fails during a deployment, undeployment or scaling operation, the command ``oneflow recover`` can be used to retry the previous action once the problem has been solved. +* VM is in ``RUNNING`` state for OpenNebula. Which specifically means that ``LCM_STATE==3`` and ``STATE>=3`` +* The VM has ``READY=YES`` in the user template. For more information about this scenario, we recommend to take a look to the :ref:`OneGate server ` guide. -.. _flow_purge_done: +If ``ready_status_gate`` is set to ``false``, a VM will be considered to be in running state when it's in running state for OpenNebula (``LCM_STATE==3`` and ``STATE>=3``). Take into account that the VM will be considered ``RUNNING`` the very same moment the hypervisor boots the VM (before it loads the OS). -In order to delete all the services in ``DONE`` state, to free some space in your database, you can use the command ``oneflow purge-done``. +Create and List Existing Services +-------------------------------------------------------------------------------- + +New Services are created from Service Templates, using the ``oneflow-template instantiate`` command: + +.. prompt:: bash $ auto + + $ oneflow-template instantiate 0 + ID: 1 + +To list the available Services, use ``oneflow list/top``: + +.. prompt:: bash $ auto + + $ oneflow list + ID USER GROUP NAME STARTTIME STATE + 1 oneadmin oneadmin my_service 10/28 17:42:46 PENDING + +The Service will eventually change to ``DEPLOYING``. You can see information for each Role using ``oneflow show``. + +From Sunstone, you can instantiate a new Service from the tab ``Instances`` > ``Services``, clicking in the ``Instantiate`` button located in the toolbar. + +|oneflow-services-list| + +Selecting the Role tab once you have selected a Service, you can see the deployment state of each Role: + +|image3| Instantiation of roles with VMs on hold -------------------------------------------------------------------------------- @@ -557,6 +906,8 @@ VMs of a Service can be instances on hold with the ``on_hold`` parameter set to { "name": "my_service", "deployment": "straight", + "type": "vm", + "template_id": 0, "on_hold": true|false, "roles": [ { @@ -565,29 +916,6 @@ VMs of a Service can be instances on hold with the ``on_hold`` parameter set to ] } -This option can also be set at the Role level, where only one specific Role is instantiated in ``HOLD``, instead of the whole service. For example: - -.. code-block:: javascript - - { - "name": "my_service", - "deployment": "straight", - "roles": [ - { - "name": "frontend", - "vm_template": 0, - "on_hold": true|false - }, - ... - ] - } - -Once you want to release the Roles, you can use the ``oneflow release`` command to release the Service: - -.. prompt:: bash $ auto - - $ oneflow release - Adding or Removing Roles from a Running Service -------------------------------------------------------------------------------- @@ -601,7 +929,8 @@ In order to add a role to a running service you can use the command ``oneflow ad { "name": "MASTER", "cardinality": 1, - "vm_template": 0, + "template_id": 0, + "type": "vm", "min_vms": 1, "max_vms": 2, "elasticity_policies": [], @@ -611,7 +940,7 @@ In order to add a role to a running service you can use the command ``oneflow ad After adding the role, the service will go to ``DEPLOYING`` state and when the VMs are created, it will go to ``RUNNING``. -.. note:: Networks and custom attributes are supported, so if the new role has some of them, they will be evaluated. +.. note:: Networks and User Inputs are supported, so if the new role has some of them, they will be evaluated. .. note:: Before adding the role, the JSON is checked, to see that it follows :ref:`the schema `. @@ -623,9 +952,122 @@ In order to remove a role from a running service you can use the command ``onefl After removing the role, the service will go to ``UNDEPLOYING`` state and when the VMs are removed, it will go to ``RUNNING``. -Managing Permissions + +Update Service ================================================================================ +You can update a service in ``RUNNING`` state, to do that you need to use the command ``oneflow update ``. You can update all the values, except the following ones: + +Service +-------------------------------------------------------------------------------- + +- **user_inputs**: it only has sense when deploying, not in running. +- **user_inputs_values**: it only has sense when deploying, not in running. +- **deployment**: changing this, changes the undeploy operation. +- **log**: this is just internal information, no sense to change it. +- **name**: this has to be changed using rename operation. +- **networks**: it only has sense when deploying, not in running. +- **networks_values**: it only has sense when deploying, not in running. +- **ready_status_gate**: it only has sense when deploying, not in running. +- **state**: this is internal information managed by OneFlow server. + +Role +-------------------------------------------------------------------------------- + +- **user_inputs**: it only has sense when deploying, not in running. +- **user_inputs_values**: it only has sense when deploying, not in running. +- **cardinality**: this is internal information managed by OneFlow server. +- **last_vmname**: this is internal information managed by OneFlow server. +- **nodes**: this is internal information managed by OneFlow server. +- **parents**: this has only sense in deploy operation. +- **state**: this is internal information managed by OneFlow server. +- **template_id**: this will affect scale operation. + +.. warning:: If you try to change one of these values above, you will get an error. The server will also check the schema in case there is another error. + +.. note:: If you change the value of min_vms the OneFlow server will adjust the cardinality automatically. Also, if you add or edit elasticity rules they will be automatically evaluated. + +.. note:: You can use the flag ``--append`` to append new information to the service. + + +Recovering Services from Failures +-------------------------------------------------------------------------------- + +Some common failures can be resolved without manual intervention, calling the ``oneflow recover`` command. This command has different effects depending on the Service state: + ++------------------------+-----------------+--------------------------------------------------------------------------+ +| State | New State | Recover action | ++========================+=================+==========================================================================+ +| ``FAILED_DEPLOYING`` | ``DEPLOYING`` | VMs in ``DONE`` or ``FAILED`` are terminated. | +| | | VMs in ``UNKNOWN`` are booted. | ++------------------------+-----------------+--------------------------------------------------------------------------+ +| ``FAILED_UNDEPLOYING`` | ``UNDEPLOYING`` | The undeployment is resumed. | ++------------------------+-----------------+--------------------------------------------------------------------------+ +| ``FAILED_SCALING`` | ``SCALING`` | VMs in ``DONE`` or ``FAILED`` are terminated. | +| | | VMs in ``UNKNOWN`` are booted. | +| | | For a scale-down, the shutdown actions are retried. | ++------------------------+-----------------+--------------------------------------------------------------------------+ +| ``COOLDOWN`` | ``RUNNING`` | The Service is simply set to running before the cooldown period is over. | ++------------------------+-----------------+--------------------------------------------------------------------------+ + +From Sunstone, this can be achieved selecting the Recover button from the toolbar in the ``Instances`` > ``Services`` section. + +Deleting Services +-------------------------------------------------------------------------------- + +Services are deployed automatically by the Life Cycle Manager. To undeploy a running Service, users can use the command ``oneflow delete``. + +The command ``oneflow delete`` will perform a graceful ``terminate`` on all the running VMs (see :ref:`onevm terminate `). If the ``straight`` deployment strategy is used, the Roles will be shutdown in the reverse order of the deployment. + +If any of the VM terminate operations can't be performed, the Service state will show ``FAILED`` state, indicating that manual intervention is required to complete the cleanup. In any case, the Service can be completely removed using the command ``oneflow recover --delete``. + +When a Service fails during a deployment, undeployment, or scaling operation, the command ``oneflow recover`` can be used to retry the previous action once the problem has been solved. + +.. _flow_purge_done: + +In order to delete all the services in ``DONE`` state, to free some space in your database, you can use the command ``oneflow purge-done``. + +**Automatic delete service if all roles are terminated** + +Service VMs can be terminated using scheduled actions or VM charters. This can lead to a situation where you have a running service with no VMs associated to it. To avoid this you can use automatic deletion feature. + +To enable it, you need to add the following attribute to the service template: + +.. prompt:: bash $ auto + + "automatic_deletion": true + +.. _appflow_use_cli_running_state: + +This option can also be set at the Role level, where only one specific Role is instantiated in ``HOLD``, instead of the whole service. For example: + +.. code-block:: javascript + + { + "name": "my_service", + "deployment": "straight", + "type": "vm", + "roles": [ + { + "name": "frontend", + "template_id": 0, + "on_hold": true|false + ... + }, + ... + ] + ... + } + +Once you want to release the Roles, you can use the ``oneflow release`` command to release the Service: + +.. prompt:: bash $ auto + + $ oneflow release + +Managing Service Permissions +-------------------------------------------------------------------------------- + Both Services and Template resources are completely integrated with the :ref:`OpenNebula user and group management `. This means that each resource has an owner and group, and permissions. The VMs created by a Service are owned by the Service owner, so he can list and manage them. To change the owner and group of the Service, we can use ``oneflow chown/chgrp``. @@ -639,7 +1081,7 @@ Please refer to the OpenNebula documentation for more information about :ref:`us .. _flow_sched: Scheduling Actions on the Virtual Machines of a Role -================================================================================ +-------------------------------------------------------------------------------- You can use the ``action`` command to perform a VM action on all the Virtual Machines belonging to a Role. @@ -680,59 +1122,7 @@ The ``/etc/one/oneflow-server.conf`` file contains default values for ``period`` .. note:: You can also perform an operation in the whole service using eht command ``service action``. All the above operations and options are supported. -Recovering from Failures -================================================================================ - -Some common failures can be resolved without manual intervention, calling the ``oneflow recover`` command. This command has different effects depending on the Service state: - -+------------------------+-----------------+--------------------------------------------------------------------------+ -| State | New State | Recover action | -+========================+=================+==========================================================================+ -| ``FAILED_DEPLOYING`` | ``DEPLOYING`` | VMs in ``DONE`` or ``FAILED`` are terminated. | -| | | VMs in ``UNKNOWN`` are booted. | -+------------------------+-----------------+--------------------------------------------------------------------------+ -| ``FAILED_UNDEPLOYING`` | ``UNDEPLOYING`` | The undeployment is resumed. | -+------------------------+-----------------+--------------------------------------------------------------------------+ -| ``FAILED_SCALING`` | ``SCALING`` | VMs in ``DONE`` or ``FAILED`` are terminated. | -| | | VMs in ``UNKNOWN`` are booted. | -| | | For a scale-down, the shutdown actions are retried. | -+------------------------+-----------------+--------------------------------------------------------------------------+ -| ``COOLDOWN`` | ``RUNNING`` | The Service is simply set to running before the cooldown period is over. | -+------------------------+-----------------+--------------------------------------------------------------------------+ - -Update Service -================================================================================ - -You can update a service in ``RUNNING`` state, to do that you need to use the command ``oneflow update ``. You can update all the values, except the following ones: - -Service --------------------------------------------------------------------------------- - -- **custom_attrs**: it only has sense when deploying, not in running. -- **custom_attrs_values**: it only has sense when deploying, not in running. -- **deployment**: changing this, changes the undeploy operation. -- **log**: this is just internal information, no sense to change it. -- **name**: this has to be changed using rename operation. -- **networks**: it only has sense when deploying, not in running. -- **networks_values**: it only has sense when deploying, not in running. -- **ready_status_gate**: it only has sense when deploying, not in running. -- **state**: this is internal information managed by OneFlow server. - -Role --------------------------------------------------------------------------------- - -- **cardinality**: this is internal information managed by OneFlow server. -- **last_vmname**: this is internal information managed by OneFlow server. -- **nodes**: this is internal information managed by OneFlow server. -- **parents**: this has only sense in deploy operation. -- **state**: this is internal information managed by OneFlow server. -- **vm_template**: this will affect scale operation. - -.. warning:: If you try to change one of these values above, you will get an error. The server will also check the schema in case there is another error. - -.. note:: If you change the value of min_vms the OneFlow server will adjust the cardinality automatically. Also, if you add or edit elasticity rules they will be automatically evaluated. - -.. note:: You can use the flag ``--append`` to append new information to the service. +.. warning:: Schedule actions are only supported by VM type Roles. Advanced Usage ================================================================================ @@ -751,116 +1141,113 @@ From any VM, use the ``PUT ${ONEGATE_ENDPOINT}/vm`` action to store any informat You can read more details in the :ref:`OneGate API documentation `. -VM Template override --------------------------------------------------------------------------------- - -Each role is backed by a VM Template. Once the VM is instantiated, the resulting VM will inherit the attributes defined in the VM Template. You can pass extra attributes at the moment of the VM instantiation by using the ``vm_template_contents`` option within each role. - -For example, the following service template will make sure that the VMs created backing the role FAAS will have capacity hotplug functionality. - -.. prompt:: bash $ auto - - root@provisionengine-test-env:~# oneflow-template show 241 - SERVICE TEMPLATE 241 INFORMATION - ID : 241 - NAME : Function - USER : oneadmin - GROUP : oneadmin - REGISTRATION TIME : 10/04 21:16:34 - - PERMISSIONS - OWNER : um- - GROUP : --- - OTHER : --- - - TEMPLATE CONTENTS - { - "name": "Function", - "deployment": "straight", - "description": "", - "roles": [ - { - "name": "FAAS", - "cardinality": 1, - "vm_template": 0, - "shutdown_action": "terminate-hard", - "elasticity_policies": [ - - ], - "scheduled_policies": [ - - ], - "vm_template_contents": "HOT_RESIZE=[CPU_HOT_ADD_ENABLED=\"YES\",\nMEMORY_HOT_ADD_ENABLED=\"YES\"]\nMEMORY_RESIZE_MODE=\"BALLOONING\"\nVCPU_MAX= \"2\"\nMEMORY_MAX=\"128\"" - } - ], - "ready_status_gate": false, - "automatic_deletion": false, - "registration_time": 1696454194 - } - - Network mapping & Floating IPs -------------------------------------------------------------------------------- -Network mapping can be achieved by using OneFlow and OneGate together. A few steps are required for mapping IP addresses from an internal network into an external one, as shown in the image below: +Network mapping in OneFlow is facilitated through the use of Virtual Router Roles, which enable efficient management of network resources and floating IPs within your cloud environment. |oneflow-network-mapping| -**Upload the Network Mapping script** - -First of all, it is necessary to upload the Network Mapping script to a :ref:`Kernels & Files Datastore `. Simply, Create a file of type ``Context`` in the File Datastore using ``/usr/share/one/start-scripts/map_vnets_start_script``. Note that you may need to add ``/usr/share/one/start-script`` path to ``SAFE_DIRS`` attribute of the Files Datastore. - -**Preparing the Router Virtual Machine Template** - -A custom Virtual Machine template acting as router is also needed. Steps similar to those below should be followed: +**Configuring the Service Template** -* Storage. Choose a disk image. For instance, a light weight Alpine that can be get on :ref:`OpenNebula Systems MarketPlace `. -* Network. You may want to set ``virtio`` as ``Default hardware model to emulate for all NICs``. -* Context: +To establish network mapping, you need to define a Service Template that includes a Virtual Router Role. Below is an example configuration for a Virtual Router Role in JSON format: - * Configuration: +.. code-block:: json - * ``Add OneGate token`` must be checked (this is also applicable to all templates used in the Service Template).¡ - * Copy the contents of ``/usr/share/one/start-scripts/cron_start_script`` in ``Start script``. - - |oneflow-network-mapping-router_context_config| - - * Files. Select the network mapping script previously uploaded to the File Datastore. - -**Prepare the Service Template** + { + "roles": [ + ... + { + "name": "VNF", + "type": "vr", + "template_id": 1, + "cardinality": 3, + "template_contents": { + "NIC": [ + { + "NETWORK_ID": "$Public", + "FLOATING_IP": "yes" + } + ] + } + }, + ] + "networks_values": [ + { + "Public": { + "template_id": 1, + "extra": "AR=[ IP=1.1.1.1,SIZE=10,TYPE=IP4]" + } + } + ] + ... + } -As an example we will create a two-tier server with an external network (*Public*) and an internal (*Private*) one for private traffic: +Highlighting some elements of the previous template -* Network configuration. Declare the *Public* and *Private* networks to be used on instantiation. :ref:`See Dynamic Networks section above `. -* Role ``router``. Select the previously created Router Virtual Template, and check ``Private`` and ``Public`` in ``Network Interfaces``. -* Role ``worker``. Select a Virtual Machine Template, check only ``Private`` in ``Network Interfaces``, and check ``router`` in ``Parent roles`` to set up a deploy dependency. +- **type**: Specifies that this is a Virtual Router Role with the value ``vr``. +- **template_id**: Refers to the ID of the template associated with this Role. Since we are creating a VR Role, this must be a Virtual Router template. +- **cardinality**: Indicates the number of Virtual Routers that will be instantiated for this Role. In the case of more than one, we will be creating a router in HA mode automatically. +- **template_contents**: Contains the configuration for the Network Interfaces. Here, the `NETWORK_ID` is set to `$Public`, denoting the use of a public network, and `FLOATING_IP` is set to "yes," indicating that floating IPs will be allocated automatically by OneFlow. -**Instantiate the Service Template** +Additionally, as it's described in the :ref:`Dynamic Network Configuration <_appflow_use_cli_networks>` section, the ``networks_values`` attribute provides configuration details for the public network, specifying the Virtual Network template ID and other parameters. -At this point the Service Template can be instantiated. If a ``NIC_ALIAS`` on *Pulic* network is attached to any of the virtual machines on the *worker* role, the specific machine can be reached by using the IP address assigned to the ``NIC_ALIAS``. +**Instantiating the Service** -.. code:: +When the Service is instantiated, the Virtual Router Role will look like the following: - $ ping -c1 10.0.0.2 - PING 10.0.0.2 (10.0.0.2) 56(84) bytes of data. - 64 bytes from 10.0.0.2: icmp_seq=1 ttl=64 time=0.936 ms +.. code-block:: json - --- 10.0.0.2 ping statistics --- - 1 packets transmitted, 1 received, 0% packet loss, time 0ms - rtt min/avg/max/mdev = 0.936/0.936/0.936/0.000 ms + { + ... + "roles": [ + ... + { + "name": "VR_EXAMPLE", + "type": "vr", + "template_id": 1, + "state": 2, + "cardinality": 3, + "template_contents": { + "NIC": [ + { + "NETWORK_ID": "0", + "FLOATING_IP": "yes" + } + ], + "NAME": "VR_EXAMPLE(service_5)" + }, + "nodes": [ + ... + ], + "on_hold": false, + "last_vmname": 0, + "vrouter_id": 2, + "vrouter_ips": [ + { + "NETWORK_ID": 0, + "VROUTER_IP": "1.1.1.1" + } + ] + } + ... + ] + ... + } + -If the ``NIC_ALIAS`` on *Pulic* network is detached from the virtual machine, the connectivity -through the previously- assigned IP address is lost. You can re-attach the IP as a ``NIC_ALIAS`` to other VM to *float* the IP. +In this instantiation: -.. code:: +- **vrouter_id**: Represents the ID of the Virtual Router created by OneFlow. +- **vrouter_ips**: Contains an array of all the floating IPs that have been allocated. In this example, the IP `1.1.1.1` is associated with the NETWORK_ID `0`. - $ ping -c1 10.0.0.2 - PING 10.0.0.2 (10.0.0.2) 56(84) bytes of data. +**Communicating with the Virtual Router from Other Roles** - --- 10.0.0.2 ping statistics --- - 1 packets transmitted, 0 received, 100% packet loss, time 0ms +In many cases, the networks and the IP of the router are dynamically assigned. There are two different methods for other Roles to obtain the Virtual Router’s IP address: -.. warning:: It takes up to one minute, half a minute on average, to configure the rules on *iptables*. +* **Direct Access via Parent Role**: If a Role has a Virtual Router Role as its parent, :ref:`it can access the attributes of the parent Role directly <_service_global>`. +* **Using OneGate**: If the Role does not inherit from a Virtual Router Role, you can utilize the :ref:`OneGate server ` within the virtual machines of the Roles to retrieve this information. Ensure that the "Add OneGate token" option is checked when configuring the templates used in the Service Template. This enables the VMs to securely access the necessary data from the OneFlow environment. .. _service_charters: @@ -873,7 +1260,7 @@ This functionality automatically adds scheduling actions in VM when the service .. _service_global: -Service Global Parameters +Accessing Parent's Role attributes from children -------------------------------------------------------------------------------- You can define attributes that refer to a parent's attribute, for example, the parent can push an attribute trough OneGate and its children can use it on their template. @@ -883,11 +1270,13 @@ In order to do this, you need to use the following syntax: ``${.template.context.test}``. -These expressions can be placed inside ``vm_template_contents`` attribute, which is the final information that will have the VM, for example: +These expressions can be placed inside ``template_contents`` attribute, which is the final information that will have the VM, for example: .. prompt:: bash $ auto - vm_template_contents": "DB_NAME=${DATABASE.template.context.db_name} + template_contents": { + "DB_NAME": "${DATABASE.template.context.db_name" + } .. important:: This will only work when using STRAIGHT strategy and when there is a parent relationship. So the attributes **must** be in the children not in the parent. @@ -900,6 +1289,10 @@ For more information on the resource representation, please check the :ref:`API .. |image1| image:: /images/charterts_on_services.png .. |image3| image:: /images/oneflow-service.png .. |image4| image:: /images/flow_lcm.png +.. |oneflow-templates-list| image:: /images/oneflow-templates-list.png +.. |oneflow-templates-delete| image:: /images/oneflow-templates-delete.png +.. |oneflow-templates-update| image:: /images/oneflow-templates-update.png +.. |oneflow-services-list| image:: /images/oneflow-services-list.png .. |oneflow-ready-status-checkbox| image:: /images/oneflow-ready-status-checkbox.png .. |oneflow-templates-net-1| image:: /images/oneflow-templates-net-1.png .. |oneflow-templates-net-2| image:: /images/oneflow-templates-net-2.png @@ -914,4 +1307,4 @@ For more information on the resource representation, please check the :ref:`API .. |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 \ No newline at end of file +.. |sunstone_oneflow_serviceinputs_layout| image:: /images/sunstone_oneflow_serviceinputs_layout.png