diff --git a/README.md b/README.md
index 904277f1c6323ee2aabb11c0943b268dd0e41fc7..65ad87dee410d3df2644808124f3bd709720cd04 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,11 @@
# MOCCI
[](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/commits/master)
-MOCCI is an extension for the [Open Cloud Computing Interface (OCCI)](http://occi-wg.org/about/specification/) to enable a model-driven management of monitoring devices in the cloud, as well as storing their results within an OCCI-compliant runtime model. Together with other tools from the OCCI ecosystem it provides a testing and execution environment for self-adaptive systems. This tooling also allows obtaining a snapshot of the EMF-based architecture runtime model in the [JSON format](./doc/browser.png). In the following you will find a getting started guide in which a preconfigured virtualbox image is downloaded to perform example scenarios and an tutorial on how to enrich existing OCCI models with monitoring functionality. Moreover, an introduction to MOCCI's components is provided, as well as links and description on how to integrate MOCCI with other pre-existing tooling from the OCCI ecosystem. The paper submitted to this artifact and the virtualbox image can be found [here](https://owncloud.gwdg.de/index.php/s/5u2ddnyyNlzecM5) with the password being mocci.
+MOCCI is an extension for the [Open Cloud Computing Interface (OCCI)](http://occi-wg.org/about/specification/) to enable a model-driven management of monitoring devices in the cloud, as well as storing their results within an OCCI-compliant runtime model. Together with other tools from the OCCI ecosystem it provides a testing and execution environment for self-adaptive systems with an EMF-based architecture runtime model ([Snapshot in JSON format](./doc/browser.png)). In the following you will find a getting started guide in which a preconfigured VirtualBox image is downloaded to perform example scenarios and an tutorial on how to enrich existing OCCI models with monitoring functionality. Moreover, an introduction to MOCCI's components is provided, as well as links and description on how to integrate MOCCI with other pre-existing tooling from the OCCI ecosystem. The paper submitted to this artifact and the VirtualBox image can be found [here](https://owncloud.gwdg.de/index.php/s/5u2ddnyyNlzecM5) with the password being mocci.
## Getting Started
-To get started with MOCCI we provide a hands on experience in form of a virtualbox image in which everything required is already configured and ready to go.
+To get started with MOCCI we provide a hands on experience in form of a VirtualBox image in which everything required is already configured and ready to go.
Alternatively, to manually setup the single components instructions can be found at the end of this document.
### Download VirtualBox Image
@@ -17,14 +17,14 @@ password: mocci
This image contains a version of OCCI-Studio with the MoDMaCAO and MOCCI plugins pre-installed.
Moreover, it contains a checked out version of MOCCI and a local version of the MARTserver using dummy connectors.
-After the download has finished, open Virtualbox and import the virtual appliance:
+After the download has finished, open VirtualBox and import the virtual appliance:
1. Click on File->Import Appliance...
2. Choose the destination of the downloaded image.
3. Adjust the appliance settings according to your System.
1. For a smooth experience 8Gb Ram, and 2 CPUs are recommended.
4. Press Import.
-Next start the virtual machine:
+Next start the Virtual Machine:
1. Choose the recently imported VM and press Start.
2. The username, and password are both: mocci
@@ -41,25 +41,25 @@ It is recommended to execute the tutorials and examples in the following order:
MOCCI itself is a monitoring extension that in combination with pre-existing software from the OCCI ecosystem allows for an easy development and testing of self-adaptation engines for cloud systems.
This section provides an overview of MOCCI's components, as well as other tools used to develop and perform the example scenarios.
-### MOCCI
-MOCCI consists of three main components. The metamodel extension for OCCI, a connector responsible to deploy, configure, and manage sensors and its monitoring devices in the cloud, and a dummy connector simulating user defined monitoring results for test purposes. Descriptions of the single components can be found via the following links:
+### MOCCI (artifact)
+MOCCI consists of three main components. The metamodel extension for OCCI, a connector responsible to deploy, configure, and manage arbitrary sensors and monitoring devices in the cloud using configuration management scripts, and a dummy connector simulating user defined monitoring results for test purposes. Descriptions of the single components can be found via the following links:
In addition to the getting started and the example scenarios discussed in this document, the main components of MOCCI are represented by the:
1. [Monitoring Extension](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/tree/master/de.ugoe.cs.rwm.mocci.model)
2. [Monitoring Connector](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/tree/master/de.ugoe.cs.rwm.mocci.connector)
3. [Monitoring Dummy Connector](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/tree/master/de.ugoe.cs.rwm.mocci.connector.dummy)
-### OCCI-Studio and MoDMaCAO
+### OCCI-Studio and MoDMaCAO (pre-existing Software from the OCCI ecosystem)
[OCCI-Studio](https://github.com/occiware/OCCI-Studio) is an IDE providing many convenient tools to develop around OCCI. For example, it provides a model editor, graphically and textually. Moreover, it allows to design OCCI extensions and automatically generate code from it.
In addition to OCCI-Studio the [Model-Driven Configuration Management of Cloud Applications with OCCI (MoDMaCAO)](https://github.com/occiware/MoDMaCAO) extension suite is needed.
[Documentation on how to setup and configure OCCI-Studio with MOCCI](doc/studio.md)
-### MartServer
+### MartServer (pre-existing Software from the OCCI ecosystem)
The [MartServer](https://github.com/occiware/MartServer) represents the OCCI interface to which requests are send in order to build and monitor the cloud application.
This server is easy to extend by plugging in connectors created for modeled OCCI extensions.
-[Documentation on how to setup and configure the MartServer](doc/api.md)
+[Documentation on how to setup and configure the MartServer](doc/openstack.md)
*Note:* Please note that the execution of the example scenarios in an distributed environment requires access and connectors to the cloud.
diff --git a/de.ugoe.cs.rwm.mocci.model/README.md b/de.ugoe.cs.rwm.mocci.model/README.md
index e6d805f5a9a6a666616b52eb52ebfcc0d6530bfe..00855addae1b32dd436e56a77db786d4fe1aac8e 100644
--- a/de.ugoe.cs.rwm.mocci.model/README.md
+++ b/de.ugoe.cs.rwm.mocci.model/README.md
@@ -4,20 +4,20 @@ The elements introduced in this extension mainly inherit from elements of the en
as shown in the Figure below. As any other extension generated with OCCI-Studio the monitoring extension can be [registered as a plugin](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/blob/master/doc/studio.md) within Eclipse, OCCI-Studio, and the MartServer.
## The Sensor Element
-The sensor element represents a top level element used to easily manage all monitoring devices it contains.
-The containment relationship to its monitoring devices is modeled via componentlinks.
-As sensor inherits application, it gains access to attributes reflecting its current state, as well as actions to manage its lifecycle.
+The Sensor element represents a top level element used to easily manage all monitoring devices it contains.
+The containment relationship to its monitoring devices is modeled via ComponentLinks.
+As Sensor inherits Application, it gains access to attributes reflecting its current state, as well as actions to manage its lifecycle.
Thus, the monitoring devices can be deployed by accessing the sensor directly, but also by addressing each device separately.
-To specify the object a sensor monitors, it can be connected over a monitorableproperty to the corresponding resource.
+To specify the object a sensor monitors, it can be connected over a MonitorableProperty to the corresponding resource.
The property itself defines two attributes defining the name of the property it monitors, and its results.
## The Monitoring Components
-Each monitoring device (datagatherer, dataprocessor, resultprovider) inherit from component.
+Each monitoring device (DataGatherer, DataProcessor, ResultProvider) inherit from component.
Thus, each monitoring component gains access to actions to deploy, configure, start, stop, and undeploy it.
When not using the dummy connector, the execution of these actions trigger the execution of configuration management scripts linked to the individual monitoring device.
-The name of the scripts are assigned over user mixins attached to the component, which is located in the roles folder of the MartServer.
-To define where each monitoring device is deployed placementlinks are used connecting the device to the VM it is deployed on.
+The name of the scripts are assigned over user Mixins attached to the Component, which is located in the roles folder of the MartServer.
+To define where each monitoring device is deployed PlacementLinks are used connecting the device to the VM it is deployed on.
Thus, each device can be hosted by different VM.
\ No newline at end of file
diff --git a/doc/Martoverview.jpg b/doc/Martoverview.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..f2414711a12946e2c67f71f6d3ac44e1748e632d
Binary files /dev/null and b/doc/Martoverview.jpg differ
diff --git a/doc/horizontal.md b/doc/horizontal.md
index 896df28c76ff5ec4d4ea7da5da89acc0dc14bec6..182d7a92df5b41f95ab5e882b6f64a4f45dac8f5 100644
--- a/doc/horizontal.md
+++ b/doc/horizontal.md
@@ -12,7 +12,7 @@ Before the MAPE-K loop is started make sure that the MartServer is running and t
In this scenario, a Java application is started that utilizes the schematized data format of the OCCI metamodel and its extensions.
This scenario serves as an example on how to work with the OCCI ecosystem, including the monitoring extension and the models at runtime engine.
To start the MAPE-K loop execute MAPE.java as a Java Application.
-In the VM it is located on the desktop. Open a new terminal(Ctrl-Alt-T) and navigate to the desktop(cd Desktop). You can start the loop by executing the following command:
+In the VM it is located on the desktop. Open a new terminal (Ctrl-Alt-T) and navigate to the desktop (cd Desktop). You can start the loop by executing the following command:
```
java -jar MAPE.jar
```
@@ -55,8 +55,11 @@ INFO MonProp: CPU, set to: None(ba16f4ee-1601-4192-a259-eae4274aed72)
```
+*Note*: The sometimes occurring MartServer error message regarding saving the model can be ignored as it has no effects on the cloud deployment nor is it related to the MOCCI extension artifact.
+
### Browser - Output
-Again you can check the amount of deployed resources by using your browser. Depending on whether the system up or downscales different amounts of worker nodes are present in the runtime model.
+Again you can check the amount of deployed resources by using your browser. When a critical behavior is detected and an upscale is performed, the amount of compute nodes in the model is increased by one. This compute node hosts a hadoop worker component and has a sensor attached. When no critical behavior is detected, a downscale is planned, and execute the amount of provisioned compute nodes shrinks by one.
+
The amount of currently deployed sensors, applications, components, compute nodes, as well as their monitorableproperty can be accessed by the following example queries. Hereby, the information depicted can be updated by **refreshing the browser**.
```
http://localhost:8080/compute/
diff --git a/doc/initial.md b/doc/initial.md
index e339abcded77307e160fc5a0966dbe975cbb2727..6ec79ad6ef64461abe9e1dbdf0ea6bb9f4e282e6 100644
--- a/doc/initial.md
+++ b/doc/initial.md
@@ -4,7 +4,7 @@ This deployment serves as entry point for the other provided scenarios: [Vertica
## Starting the MartServer
If the getting started VM is used everything is preconfigured only requiring to start the following script.
-Start a terminal(Strg-Alt-T) and navigate to the desktop (cd Desktop). The script can be started using the following command:
+Start a terminal (Ctrl-Alt-T) and navigate to the desktop (cd Desktop). The script can be started using the following command:
```
./startMART.sh
```
@@ -13,7 +13,7 @@ For an actual deployment in an OpenStack cloud we used the following [live conne
## Deploying the Hadoop Cluster
Now that the MartServer is started the hadoop cluster can be deployed. Therefore, start the InitialDeployment.java file as an Java Application. This application performs requests to deploy the model shown below.
-If the VM is used: Open a terminal(Strg-Alt-T) and navigate to the VM's desktop(cd Desktop) and execute the initialDeployment.jar using the following command.
+If the VM is used: Open a terminal (Ctrl-Alt-T) and navigate to the VM's desktop (cd Desktop) and execute the initialDeployment.jar using the following command.
```
java -jar initialDeployment.jar
```
@@ -35,7 +35,7 @@ INFO MonProp: CPU, set to: Critical(ba16f4ee-1601-4192-a259-eae4274aed72)
### Browser - Output
-Now that everything has been deployed you can investigate the OCCI runtime model by opening your browser and query for OCCI entitites. In the following you find some example queries to query all compute, sensor, and monitorableproperties, as well as a query for the concrete monitored hadoop-worker compute node, and a filter for each monitorableproperty set to Critical. Additional query and filters can be found in the [documentation of the MartServer](https://github.com/occiware/MartServer/blob/master/doc/userdoc.md). It should be noted, that the updated MonitorableProperties can be investigated by **refreshing the browser**.
+Now that everything has been deployed you can investigate the OCCI runtime model by opening your browser and query for OCCI entitites. In the following you find some example queries for the runtime model to query all compute, sensor, and monitorableproperties, as well as a query for the concrete monitored hadoop-worker compute node, and a filter for each monitorableproperty set to Critical. Additional query and filters can be found in the [documentation of the MartServer](https://github.com/occiware/MartServer/blob/master/doc/userdoc.md). It should be noted, that the updated MonitorableProperties can be investigated by **refreshing the browser**.
```
http://localhost:8080/compute
http://localhost:8080/sensor
diff --git a/doc/openstack.md b/doc/openstack.md
index fe39bb42ba416e2f96de2055c8a9f7e710a60025..9a49bc04337d6add53809744cc9beae9fc698aa6 100644
--- a/doc/openstack.md
+++ b/doc/openstack.md
@@ -1,19 +1,20 @@
# Setting up the MartServer to be used in OpenStack
-To manage a cloud deployment using the MartServer it has to be deployed on virtual machine within the cloud that has to be connected to a management network.
-TODO insert example picture.
+To manage a cloud deployment using the MartServer it has to be deployed on Virtual Machine within the cloud that has to be connected to a management network.
+
## Configuring the MartServer in the Cloud
First you need to setup a Virtual Machine hosting the MartServer:
1. Start a Virtual Machine (we used an Ubuntu 16.04 image)
2. Insert the OpenStack Controller IP in /etc/hosts. For example: 192.168.34.1 controller.
3. Install [ansible](https://docs.ansible.com/) on the machine running the MART Server.
-4. Deploy either the Docker container or export the MartServer project
+4. Deploy either the Docker container or export the MartServer project.
-Moreover, a management network is required over which the MartServer connects to spawned virtual machines:
+Moreover, a management network is required over which the MartServer connects to spawned Virtual Machines:
1. Create a network
2. Attach the MartServer VM to the network
-TODO insert conceptual figure.
+A figure depicting the general setup is shown below:
+
## Extension adjustments
When performing the proposed approach in a cloud, some connectors have to be configured to gain access to specific information, e.g., user credentials.
@@ -40,15 +41,16 @@ Currently, only a prototypical [connector for OpenStack](https://github.com/occi
However, also this connector has to be configured.
The settings itself can be found at in martserver-plugins/org.modmacao.openstack.connector.jar in the openstack.properties file. An example is shown in the following Listing:
```
-openstack_username = jerbel
-openstack_tenant = tosca2occi
-openstack_password = UV2.7F62
+openstack_username = username
+openstack_tenant = testTenant
+openstack_password = password
openstack_endpoint = http://192.168.34.1:5000/v2.0
openstack_default_network = d52754e0-6729-4034-adbb-8f1f3800f2c6
openstack_default_image = adf63ddc-debe-4d7e-b899-b936e989439f
openstack_default_flavor = 36637a26-fded-4635-b6c5-ec8ec0745eab
```
*Note:* This connector currently only supports version 2 of the openstack authentication service.
+*Note:* In our scenarios we have chosen the public network as default network to let spawned VMs download software packages defined within the configuration management scripts.
### Images and Flavors
Each vm possesses a flavor and an image. While the image describes the OS of the compute instance, the flavor describes its size.
diff --git a/doc/own.md b/doc/own.md
index d46c3cf040d9e6dd650fc92f4f11e0fa566e828f..532ce3321c9edd6187a922278c675162f6606981 100644
--- a/doc/own.md
+++ b/doc/own.md
@@ -6,16 +6,16 @@ Therefore, a tree editor in OCCI-Studio is used as described in the following.
The following description shows how to adapt the initial deployment model using an editor within OCCIWare Studio:
### Starting OCCI-Studio
-1. Open the folder OCCI-Studio located on the Desktop.
-2. Double click on OCCI-Studio to open the IDE.
-3. Now you should see a checked out version of MOCCI.
+1. Open the folder OCCI-Studio located on the Desktop
+2. Double click on OCCI-Studio to open the IDE
+3. Now you should see a checked out version of MOCCI
### Creating a new Modeling Project
1. Right click on the Project Explorer
2. Choose New->Project...
3. Search for Modeling and choose Sirius Modeling Project
4. Press Next and name the project MemMonitoring
-5. Copy the src/main/resources/hadoopClusterCPU.occic file from the MOCCI project into the MemMonitoring project
+5. Copy the de.ugoe.cs.rwm.mocci/src/main/resources/hadoopClusterCPU.occic file from the MOCCI project into the MemMonitoring project
6. Rename the file in your project to hadoopClusterCPUandMem.occic
### Utilizing the Tree Editor
@@ -41,8 +41,8 @@ The following description shows how to adapt the initial deployment model using
1. Set the kind of the other resource to DataGatherer
4. Create two links within the Resource representing the Sensor recently created: right click New Child->Link
1. Set the kind of both to ComponentLink
- 2. Set the target of one link to the Resource representing the ResultProvider
- 3. Set the target of the other link to the Resource representing the DataGatherer
+ 2. Set the target of one link to the Resource representing the ResultProvider by choosing its id.
+ 3. Set the target of the other link to the Resource representing the DataGatherer by choosing its id.
5. Save your changes to the model. It should look similar to the model shown below:
@@ -50,7 +50,7 @@ The following description shows how to adapt the initial deployment model using
### Deploying the adjusted Model
Even though the model currently does not consists of placementlinks for the new monitoring sensor which is required for an deployment in the cloud, it is sufficient to perform the simulation.
-To test the enhanced model follow the enumerated instructions:
+To test the enhanced model follow the enumerated instructions. Hereby, the MartServer does not have to be reseted, as the deployment engine compares the runtime model to the input model and performs only the requests required to reach the desired state.
1. Copy the hadoopClusterCPUandMem.occic file to the desktop
2. Open a terminal (Ctrl-Alt-T) and navigate to the desktop (cd Desktop)
@@ -62,8 +62,8 @@ java -jar initialDeployment.jar hadoopClusterCPUandMem.occic
```
This command puts your adjusted model into the models at runtime engine which is also used for the intial deployment.
To start the added sensor execute the following REST request.
-The string **sensorid has to be replaced** with the id of the Resource representing the Sensor you added.
-For example, curl can be used by starting another terminal.
+The string **sensorid has to be replaced** with the id of the Resource representing the Sensor you added. E.g., *urn:uuid:c2263c17-4b46-44f7-90f7-2036ac12eb03*.
+For example, curl can be used by starting another terminal (Ctrl-Alt-T).
```
curl -v -X POST http://localhost:8080/sensor/sensorid/?action=start -H 'Content-Type: text/occi' -H 'Category: start; scheme="http://schemas.modmacao.org/occi/platform/application/action#"; class="action"'
@@ -71,26 +71,30 @@ curl -v -X POST http://localhost:8080/sensor/sensorid/?action=start -H 'Content-
Finally, the added Sensors monitorable property should be filled with simulated monitoring data.
This can be checked by investigating the model through the browser or by having a look at the output of the MartServer.
-However, this time the simulated data corresponds to the ones that are simulated for Mem.
+```
+http://localhost:8080/monitorableproperty/
+```
+This time two monitorableproperties should be displayed, one providing monitoring results for CPU and one for Mem.
To adjust the simulation follow the instructions given in the [dummy connector](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/tree/master/de.ugoe.cs.rwm.mocci.connector.dummy)
### Visualizing the Model
-To visualize the model in an graphical editor the following steps have to be performed:
+To visualize the model in an graphical Sirius editor the following steps have to be performed:
1. Double click on representation.aird
2. Press Add... in the Models section
3. Choose Browse Workspace...
4. Select MemMonitoring->hadoopClusterCPUandMem.occic
5. Now the Model and its possible representations should been loaded (transparent)
-6. Under Representations doubleclick on OCCI Configuratrion diagram
+6. Under Representations doubleclick on OCCI Configuratrion/Configuration diagram
7. Next choose Configuration diagram (0) (non-transparent)
8. Select the Configuration element and press Finish
-To reduce the size of the model visualization collapse the User_Data and SSH information of each Compute node as these are rather large strings.
-Thereafter, press arrange all in the editor.
-Now the cloud deployment is ready to be explored.
+Now a new configuration diagram is shown which has a rather large size. This is due to the large strings contained within the compute nodes.
+To reduce the size of the model visualization navigate to the left and collapse the User_Data and SSH information of each compute node. Thereafter, press arrange all in the editor.
+Now the cloud deployment is ready to be explored more easily.
+*Note:* This editor can also be used to create and adjust OCCI models.
## Adjusting the Model for an actual deployment.
To make the model ready for an actual deployment placementlinks in each component of the sensor has to be added.
diff --git a/doc/studio.md b/doc/studio.md
index 4eff510cb6a01806f401670bf78ca9f7588b1d6b..e5943f5e3769785a489c8a55337bf376a7d63981 100644
--- a/doc/studio.md
+++ b/doc/studio.md
@@ -33,37 +33,4 @@ Finally, the MOCCI plugin can be installed which registers the OCCI monitoring e
Alternatively, you can build the Eclipse plugin yourself by checking out the project and perform the following command on the mocci.model project:
```
gradle updateSiteZip
-```
-
-## Visualizing The Example
-Now that the IDE has been installed and configured, the example model can now be loaded, visualized, and edited.
-The model can be found within the project under:
-```
-de.ugoe.cs.rwm.mocci/src/test/resources/occi/hadoopClusterNewExt.occic
-```
-
-### Tree Editor
-To check whether the installation and configuration of the IDE is successful the model can be opened in the textual editor:
-
-1. Right click the hadoopClusterNewExt.occic file
-2. Choose Open with... -> OCCI Model Editor
-3. If no problem occurs, all extensions are correctly loaded
-
-### Sirius Visualization
-To visualize the model in an graphical editor it is most convenient to create a separate Sirius Modeling project. Therefore, the following steps have to be performed:
-
-1. File -> New -> Project... -> Sirius -> Modeling Project
-2. Name it MonitoringExample
-3. Copy the hadoopClusterNewExt.occic file into the Project
-4. Double click on representation.aird
-5. Press Add... in the Models section
-6. Choose Browse Workspace...
-7. Select hadoopClusterNewExt.occic
-8. Now the Model and its possible representations should been loaded (transparent)
-9. Under Representation doubleclick on OCCI Configuratrion
-10. Next choose Configuration diagram (0) (non-transparent)
-11. Select the Configuration element and press Finish
-
-To reduce the size of the model visualization collapse the User_Data and SSH information of each Compute node.
-Thereafter, press arrange all in the editor.
-Now the cloud deployment is ready to be explored.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/doc/vertical.md b/doc/vertical.md
index 709fd155e6c06d062c93c66505d2058129d3e7a1..9c96b62b9424e9244a8f2bacd7320d89dd791e23 100644
--- a/doc/vertical.md
+++ b/doc/vertical.md
@@ -8,11 +8,13 @@ This scenario serves as an example showing how to directly work with the OCCI in
In this scenario, a simple bash script is used to check the gathered monitoring data and perform corresponding actions.
Before the adaptation script is started make sure that the MartServer is running and the hadoop cluster has been deployed.
To start the script execute the [vertical.sh](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/blob/master/src/main/resources/vertical.sh) script.
-In the getting started VM the script is located on the desktop. Create a terminal(Ctrl-Alt-T) navigate to the desktop(cd Desktop) and start the script with the following command:
+In the getting started VM the script is located on the desktop. Create a terminal (Ctrl-Alt-T) navigate to the desktop (cd Desktop) and start the script with the following command:
```
./vertical.sh
```
+*Note*: To perform other scenarios it is recommended to stop the self-adaptation loop of this scenario. Therefore, press Ctrl-C in the terminal running the loop while it is waiting for a new cycle.
+
### Adaptation Loop Script - Output
The output of the script is separated into the individual steps of the MAPE loop: Monitor, Analyze, Plan, and Execute.
Thus, the output looks depending on the adaptive action to be performed similar to: