Using AppFlow from The CLI
AppFlow manages Services and Service Templates. A Service is a multi-tier application composed of interconnected Virtual Machines with deployment dependencies between them.
The following diagram represents a multi-tier application. Each node represents a Role, and its cardinality (the number of VMs that will be deployed). The arrows indicate the deployment dependencies: each Role's VMs are deployed only when all its parent's VMs are running.
This Service can be represented with the following JSON template:
{ "name": "my_service", "deployment": "straight", "roles": [ { "name": "frontend", "vm_template": 0 }, { "name": "db_master", "parents": [ "frontend" ], "vm_template": 1 }, { "name": "db_slave", "parents": [ "frontend" ], "cardinality": 3, "vm_template": 2 }, { "name": "worker", "parents": [ "db_master", "db_slave" ], "cardinality": 10, "vm_template": 3 } ] }
AppFlow 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 appflow-template
, or the graphical interface. For each user, the actual list of Service Templates available is determined by the ownership and permissions of the Templates.
The command appflow-template create
registers a JSON template file. For example, if the previous example template is saved in /tmp/my_service.json, you can execute:
<xterm> $ appflow-template create /tmp/my_service.json ID: 0 </xterm>
You can also create service template from Sunstone:
To list the available Service Templates, use appflow-template list/show/top
:
<xterm> $ appflow-template list
ID USER GROUP NAME 0 oneadmin oneadmin my_service
$ appflow-template show 0 SERVICE TEMPLATE 0 INFORMATION ID : 0 NAME : my_service USER : oneadmin GROUP : oneadmin
PERMISSIONS OWNER : um- GROUP : — OTHER : —
TEMPLATE CONTENTS {
"name": "my_service", "roles": [ {
…. </xterm>
Templates can be deleted with appflow-template delete
.
A Service Template can be instantiated as a Service. Each newly created Service will be deployed by AppFlow following its deployment strategy.
Each Service Role creates Virtual Machines in OpenNebula from VM Templates, that must be created beforehand.
New Services are created from Service Templates, using the appflow-template instantiate
command:
<xterm> $ appflow-template instantiate 0 ID: 1 </xterm>
To list the available Services, use appflow list/top
:
<xterm> $ appflow list
ID USER GROUP NAME STATE 1 oneadmin oneadmin my_service PENDING
</xterm>
The Service will eventually change to DEPLOYING
. You can see information for each Role and individual Virtual Machine using appflow show
<xterm> $ appflow show 1 SERVICE 1 INFORMATION ID : 1 NAME : my_service USER : oneadmin GROUP : oneadmin STRATEGY : straight SERVICE STATE : DEPLOYING
PERMISSIONS OWNER : um- GROUP : — OTHER : —
ROLE frontend ROLE STATE : RUNNING CARNIDALITY : 1 VM TEMPLATE : 0 NODES INFORMATION VM_ID NAME STAT UCPU UMEM HOST TIME
0 frontend_0_(service_1) runn 67 120.3M localhost 0d 00h01
ROLE db_master ROLE STATE : DEPLOYING PARENTS : frontend CARNIDALITY : 1 VM TEMPLATE : 1 NODES INFORMATION VM_ID NAME STAT UCPU UMEM HOST TIME
1 init 0K 0d 00h00
ROLE db_slave ROLE STATE : DEPLOYING PARENTS : frontend CARNIDALITY : 3 VM TEMPLATE : 2 NODES INFORMATION VM_ID NAME STAT UCPU UMEM HOST TIME
2 init 0K 0d 00h00 3 init 0K 0d 00h00 4 init 0K 0d 00h00
ROLE worker ROLE STATE : PENDING PARENTS : db_master, db_slave CARNIDALITY : 10 VM TEMPLATE : 3 NODES INFORMATION VM_ID NAME STAT UCPU UMEM HOST TIME
LOG MESSAGES 09/19/12 14:44 [I] New state: DEPLOYING </xterm>
The deployment
attribute defines the deployment strategy that the Life Cycle Manager (part of the appflow-server) will use. These two values can be used:
RUNNING
.
Regardless of the strategy used, the Service will be RUNNING
when all of the Roles are also RUNNING
. Likewise, a Role will enter this state only when all the VMs are running
.
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 |
DEPLOYING | Some Roles are being deployed |
RUNNING | All Roles are deployed successfully |
UNDEPLOYING | Some Roles are being undeployed |
FAILED | An error occurred while deploying or undeploying the Service |
UNKNOWN | After a successful deployment, an error was detected (e.g. a VM crashed) |
DONE | The Service will stay in this state after a successful undeployment. It can be deleted |
Each Role has an individual state, described in the following table:
Role State | Meaning |
---|---|
PENDING | The Role is waiting to be deployed |
DEPLOYING | The VMs are being created, and will be monitored until all of them are running |
RUNNING | All the VMs are running |
UNDEPLOYING | The VMs are being shutdown. The role will stay in this state until all VMs are done |
FAILED | An error occurred while deploying or undeploying the VMs |
UNKNOWN | After a successful deployment, an error was detected (e.g. a VM crashed) |
DONE | All the VMs are done |
Services are deployed automatically by the Life Cycle Manager. To undeploy a running Service, users have the commands appflow shutdown
and appflow delete
.
The command appflow shutdown
will perform a graceful shutdown of all the running VMs, and will delete any VM in a failed state (see onevm shutdown and delete). If the straight
deployment strategy is used, the Roles will be shutdown in the reverse order of the deployment.
After a successful shutdown, the Service will remain in the DONE
state. If any of the VM shutdown operations cannot be performed, the Service state will show FAILED
, to indicate that manual intervention is required to complete the cleanup. In any case, the Service can be completely removed using the command appflow delete
.
If a Service and its VMs must be immediately undeployed, the command appflow delete
can be used from any Service state. This will execute a delete operation for each VM and delete the Service. Please be aware that this is not recommended, because VMs using persistent Images can leave them in an inconsistent state.
Both Services and Template resources are completely integrated with the 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.
For example, to change the owner and group of the Service 1, we can use appflow chown/chgrp
:
<xterm> $ appflow list
ID USER GROUP NAME STATE 1 oneadmin oneadmin my_service RUNNING
$ onevm list
ID USER GROUP NAME STAT UCPU UMEM HOST TIME 0 oneadmin oneadmin frontend_0_(ser runn 17 43.5M localhost 0d 01h06 1 oneadmin oneadmin db_master_0_(se runn 59 106.2M localhost 0d 01h06
…
$ appflow chown my_service johndoe apptools
$ appflow list
ID USER GROUP NAME STATE 1 johndoe apptools my_service RUNNING
$ onevm list
ID USER GROUP NAME STAT UCPU UMEM HOST TIME 0 johndoe apptools frontend_0_(ser runn 62 83.2M localhost 0d 01h16 1 johndoe apptools db_master_0_(se runn 74 115.2M localhost 0d 01h16
… </xterm>
Note that the Service's VM ownership is also changed.
All Services and Templates have associated permissions for the owner, the users in its group, and others. For each one of these groups, there are three rights that can be set: USE, MANAGE and ADMIN. These permissions are very similar to those of UNIX file system, and can be modified with the command chmod
.
For example, to allow all users in the apptools
group to USE (list, show) and MANAGE (shutdown, delete) the Service 1:
<xterm> $ appflow show 1 SERVICE 1 INFORMATION ..
PERMISSIONS OWNER : um- GROUP : — OTHER : — …
$ appflow chmod my_service 660
$ appflow show 1 SERVICE 1 INFORMATION ..
PERMISSIONS OWNER : um- GROUP : um- OTHER : — … </xterm>
Another common scenario is having Service Templates created by oneadmin that can be instantiated by any user. To implement this scenario, execute:
<xterm> $ appflow-template show 0 SERVICE TEMPLATE 0 INFORMATION ID : 0 NAME : my_service USER : oneadmin GROUP : oneadmin
PERMISSIONS OWNER : um- GROUP : — OTHER : — …
$ appflow-template chmod 0 604
$ appflow-template show 0 SERVICE TEMPLATE 0 INFORMATION ID : 0 NAME : my_service USER : oneadmin GROUP : oneadmin
PERMISSIONS OWNER : um- GROUP : — OTHER : u– … </xterm>
Please refer to the OpenNebula documentation for more information about users & groups, and resource permissions.
A Service is defined with JSON syntax templates.
Attribute | Type | Mandatory | Description |
---|---|---|---|
name | string | No | Name of the Service |
deployment | string | No | Deployment strategy: none: All roles are deployed at the same time straight: Each Role is deployed when all its parent Roles are running Defaults to none |
roles | array of Roles | Yes | Array of Roles, see below |
Each Role is defined as:
Attribute | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Role name |
cardinality | integer | No | Number of VMs to deploy. Defaults to 1 |
vm_template | integer | Yes | OpenNebula VM Template ID. See the OpenNebula documentation for VM Templates |
parents | array of string | No | Names of the roles that must be deployed before this one |