diff --git a/README.md b/README.md
index ef331e56ce1708dd199db461dc959153635ca094..9b73f06928bd1a5857cea9799dd3df7ae0fc434e 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,47 @@
Mocci is an extension for the Open Cloud Computing Interface (OCCI) to enable a model-driven management of monitoring instruments in the cloud, as well as storing their results within an OCCI runtime model.
Together with other tools from the OCCI ecosystem it provides a testing and execution environment for self-adaptive systems.
+It consist of the following components:
+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)
+4. [Editor](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/tree/master/de.ugoe.cs.rwm.mocci.model.edit)
+5. [A self-adaptation example](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci)
+
The following instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
+## Getting Started
+To getting 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.
+
+### VirtualBox
+To get a quick start in the OCCI ecosystem and the MOCCI monitoring extension download the following VM image. 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.
+```
+Insert Link here!
+```
+
+
+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:
+1. Choose the recently imported VM and press Start.
+2. The username, and password are both: mocci
+
+## Step-by-step example scenarios
+To test MOCCI, we provide step-by-step instructions for two example scenarios.
+
+1. [Vertical Scaling](doc/vertical.md): This scenario scales a VM up and down according to its CPU utilization.
+2. [Horizontal Scaling](doc/horizontal.md): This scenario dynamically adds and releases worker nodes in a hadoop cluster.
+
+*Note:* Please note that the execution of the example scenarios in an distributed environment, e.g., requires access to it as well as connectors implementing how the differen requests should be handled.
+Thus, the provided scenarios are based on monitoring data simulated by the [MOCCI connector dummy](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](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.
diff --git a/build.gradle b/build.gradle
index c7ec961a41f04bfe09a252172ff5a75d6125807d..0b7ee8db8b4a86d6b83980069a33bf80c88fa687 100644
--- a/build.gradle
+++ b/build.gradle
@@ -121,7 +121,7 @@ project(':de.ugoe.cs.rwm.mocci.connector.dummy') {
jar {
manifest {
- attributes 'Main-Class': 'de.ugoe.cs.rwm.mocci.MAPE'
+ attributes 'Main-Class': 'de.ugoe.cs.rwm.mocci.SimpleScenario'
}
}
diff --git a/doc/horizontal.md b/doc/horizontal.md
new file mode 100644
index 0000000000000000000000000000000000000000..5217c1f97a07c01c9a38d2e2ae60c465fffefe08
--- /dev/null
+++ b/doc/horizontal.md
@@ -0,0 +1,51 @@
+# Horizontal Scaling Scenario
+In this scenario a hadoop cluster with one worker node is deployed and scaled according to gathered CPU utilization.
+Therefore, a MAPE-k loop is initialized that periodically checks the CPU utilization of all worker nodes.
+Thereafter, it is decided whether additional worker nodes are required (scaleUp) or not (scaleDown).
+When a scaleUp is performed, a compute node hosting a hadoop-worker component is added to the model,
+which gets executed over a [models at runtime engine](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.docci).
+
+
+##Deploying the Cluster
+First, the hadoop cluster has to be deployed. Therefore, first start the MartServer.
+If the getting started VM is used the following script can be executed:
+```
+./startMART.sh
+```
+*Note:* If this scenario is not performed in a running cloud environment consider executing the resetMart.sh script first.
+
+Thereafter, start the InitialDeployment.java file as an Java Application.
+If the VM is used: Open a terminal and navigate to the VM's desktop and execute the initialDeployment.jar.
+```
+java -jar initialDeployment.jar
+```
+
+After the deployment has been performed you can investigate the deployed OCCI model by opening your browser and query for OCCI entitites:
+```
+http://localhost:8080/compute
+http://localhost:8080/sensor
+http://localhost:8080/monitorableproperty
+```
+
+##Starting the MAPE-K loop
+To start the MAPE-K loop execute MAPE.java as a Java Application.
+In the VM it is located on the desktop.
+```
+java -jar MAPE.jar
+```
+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.
+
+*Note:* To perform this scenario in a running cloud multiple adjustments have to be performed. Please refer to this [documentation](doc/openstack) to get started with actual cloud deployments.
+
+##Tuning the Scenario
+Again the simulated monitoring results can be adjusted as described in Section "Tuning the Scenario" of the [first scenario](doc/vertical.md).
+Moreover, to investigate what is happening in this scenario it is recommended to open the OCCI-Studio and execute the scenario from here.
+The class is located at:
+```
+de.ugoe.cs.rwm.mocci/src/main/java/MAPE.java
+```
+To log specific information, the logger setup, found in RegistryAndLoggerSetup.java, can be manipulated.
+Especially, the Executor logger is interesting as it shows the performed REST requests against the OCCI API.
+
+*Note:* These can be copy and pasted in order to perform manual requests using the terminal. E.g.: curl -v -X PUT ...
\ No newline at end of file
diff --git a/doc/openstack.md b/doc/openstack.md
index a75092623bee9135f8af76a439bb384600ec0615..fe39bb42ba416e2f96de2055c8a9f7e710a60025 100644
--- a/doc/openstack.md
+++ b/doc/openstack.md
@@ -9,20 +9,21 @@ First you need to setup a Virtual Machine hosting the MartServer:
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
-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.
## Extension adjustments
-When performing the proposed approach on a specific cloud, some extension have to be configured, as they need access to the user name and its tenant for example.
-Moreover, each cloud provider has different entry points for their API and may have different kinds of offers regarding their offered computing capabilities.
+When performing the proposed approach in a cloud, some connectors have to be configured to gain access to specific information, e.g., user credentials.
+Moreover, each cloud provider has different entry points for their API and may have different kinds of offers regarding their offered vm images and flavors.
### Configuration Tool Adjustments
-To use configuration management tools adjustments have to be performed.
-Currently, only ansible is supported.
-Hereby, the path to the ansible roles on the MART server has be defined, as well as the location of the playbook, the ansible user and the location of the private key to be used for the configuration.
+To use the configuration management tools of MoDMaCAO some adjustments have to be performed.
+These adjustments configure the path to the ansible roles located on the MART server, as well as the location of the playbook.
+Moreover, the ansible user and the location of the private key to be used have to be configured.
+
The settings itself can be found at martserver-plugins/org.modmacao.cm.jar in the ansible.properties file.
An example of this configuraiton is shown in the following Listing:
```
@@ -34,8 +35,9 @@ private_key_path = /home/ubuntu/.ssh/key.pem
### Provider specifics
In order to translate the REST requests to requests of the cloud API, the MART server requires a connector for the corresponding cloud.
-In order to use a connector, the connector's jar has to be placed in themartserver-plugins folder before the server is started.
-Currently, we only provide a prototypical connector for OpenStack. However, also this connector has to be configured.
+Therefore, the connector's jar has to be placed in the martserver-plugins folder before the server is started.
+Currently, only a prototypical [connector for OpenStack](https://github.com/occiware/MoDMaCAO) is provided as part of the MoDMaCAO framework.
+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
@@ -46,6 +48,7 @@ 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.
### 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.
@@ -62,10 +65,10 @@ An example of such an extension is given in martserver-plugins\org.modmacao.open
In order to create your own extension, we recommend using OCCI-Studio, as it provides not only a Sirius designer for the Extension, but also allows to completely generate the required code from the modeled Extension.
Then, the Extension has only be packed and put into the martserver-plugins folder to be ready for use.
-Please Note: When creating a new Extension it has to be registered within the IDE, model, and code.
+*Note:* When creating a new Extension it has to be registered within the IDE, model, and code.
### User Data Adjustments
-User data describes a specific behaviour which shall be executed when starting a VM for the first time.
+User data describes a specific behavior which shall be executed when starting a VM for the first time.
n the OCCI model, the user data is described as a Mixin within each compute resource encoded as Base64.
When encoded the Base64 represents a cloud init script.
This has to be configured in such a manner that hot-plugging of networkinterfaces is allowed in each VM.
diff --git a/doc/vertical.md b/doc/vertical.md
new file mode 100644
index 0000000000000000000000000000000000000000..0ae70f7128f405c42264a6de0d0044da8b0e4f5d
--- /dev/null
+++ b/doc/vertical.md
@@ -0,0 +1,56 @@
+# Vertical Scaling Scenario
+In this scenario a hadoop cluster with one worker node getting monitored is deployed.
+Thereafter, a MAPE-k loop is initialized that periodically checks whether the CPU utilization of the worker node reaches a critical level.
+If that is the case a request against the OCCI API is performed, increasing the number of cores and memory available to the machine.
+
+
+##Deploying the Cluster
+First, the hadoop cluster has to be deployed. Therefore, first start the MartServer.
+If the getting started VM is used the following script can be executed:
+```
+./startMART.sh
+```
+*Note:* If this scenario is not performed in a running cloud environment consider executing the resetMart.sh script first.
+
+Thereafter, start the InitialDeployment.java file as an Java Application.
+If the VM is used: Open a terminal and navigate to the VM's desktop and execute the initialDeployment.jar.
+```
+java -jar initialDeployment.jar
+```
+
+After the deployment has been performed you can investigate the deployed OCCI model by opening your browser and query for OCCI entitites:
+```
+http://localhost:8080/compute
+http://localhost:8080/sensor
+http://localhost:8080/monitorableproperty
+```
+
+##Starting the Adaptation Script
+To start the script execute the vertical.sh script.
+In the VM it is located on the desktop, otherwise you can find it [here](https://gitlab.gwdg.de/rwm/de.ugoe.cs.rwm.mocci/blob/master/src/main/resources/vertical.sh).
+```
+./vertical.sh
+```
+In this scenario, a simple bash script is used to check the gathered monitoring data and perform corresponding actions.
+This scenario serves as an example on how to directly work with the OCCI API, including the monitoring extension, by simply writing small bash scripts.
+
+*Note:* This scenario mainly serves to get started with the OCCI API. Currently, there is no connector implementing the vertical adjustment as shown in this scenario.
+
+##Tuning the Scenario
+As the adaptation only reacts on a Critical behavior, it may be interesting to tune the simulated monitoring results.
+Therefore, the following steps have to be performed:
+1. Stop the MartServer (CTRL-C)
+2. Navigate to ~/martserver-plugins
+3. Open the de.ugoe.cs.rwm.mocci.connecter.dummy.jar with the archive manager.
+4. Doubleclick on the resultprovider.properties file
+5. Adjust the values to your liking
+
+The file contains the following:
+```
+CPU = None,Low,Medium,High,Critical,5000
+```
+* CPU: Represents the monitorable.property to be adjusted.
+* 5000: Represents the interval in which monitoring.results are written.
+* None-Critical: Represents the simulated monitoring.results.
+
+*Note;* If you want to execute the second scenario please bring the resultprovider.properties file to its original state.
\ No newline at end of file
diff --git a/src/main/java/de/ugoe/cs/rwm/mocci/InitialDeployment.java b/src/main/java/de/ugoe/cs/rwm/mocci/InitialDeployment.java
index 3d046b16fe0a60de2874487ed8d5966ef9deb761..46d3f6406e2c447233286a21191189dc61859046 100644
--- a/src/main/java/de/ugoe/cs/rwm/mocci/InitialDeployment.java
+++ b/src/main/java/de/ugoe/cs/rwm/mocci/InitialDeployment.java
@@ -13,6 +13,7 @@ import org.eclipse.emf.ecore.resource.Resource;
import de.ugoe.cs.rwm.docci.MartDeployer;
import de.ugoe.cs.rwm.docci.ModelUtility;
import de.ugoe.cs.rwm.docci.connector.Connector;
+import de.ugoe.cs.rwm.docci.connector.LocalhostConnector;
import de.ugoe.cs.rwm.docci.executor.MartExecutor;
import de.ugoe.cs.rwm.tocci.Transformator;
import de.ugoe.cs.rwm.tocci.TransformatorFactory;
@@ -25,11 +26,13 @@ public class InitialDeployment {
private static String userData = "I2Nsb3VkLWNvbmZpZwoKIyBVcGdyYWRlIHRoZSBpbnN0YW5jZSBvbiBmaXJzdCBib290CiMgKGllIHJ1biBhcHQtZ2V0IHVwZ3JhZGUpCiMKIyBEZWZhdWx0OiBmYWxzZQojIEFsaWFzZXM6IGFwdF91cGdyYWRlCnBhY2thZ2VfdXBncmFkZTogdHJ1ZQoKcGFja2FnZXM6CiAtIHB5dGhvbgoKd3JpdGVfZmlsZXM6CiAgLSBwYXRoOiAvZXRjL25ldHdvcmsvaW50ZXJmYWNlcy5kLzUwLWNsb3VkLWluaXQuY2ZnCiAgICBjb250ZW50OiB8CiAgICAgIGF1dG8gbG8KICAgICAgaWZhY2UgbG8gaW5ldCBsb29wYmFjawogICAgICAKICAgICAgYXV0byBlbnMwCiAgICAgIGFsbG93LWhvdHBsdWcgZW5zMAogICAgICBpZmFjZSBlbnMwIGluZXQgZGhjcAogICAgICAKICAgICAgYXV0byBlbnMxCiAgICAgIGFsbG93LWhvdHBsdWcgZW5zMQogICAgICBpZmFjZSBlbnMxIGluZXQgZGhjcAogICAgICAKICAgICAgYXV0byBlbnMyCiAgICAgIGFsbG93LWhvdHBsdWcgZW5zMgogICAgICBpZmFjZSBlbnMyIGluZXQgZGhjcAogICAgICAKICAgICAgYXV0byBlbnMzCiAgICAgIGFsbG93LWhvdHBsdWcgZW5zMwogICAgICBpZmFjZSBlbnMzIGluZXQgZGhjcAogICAgICAKICAgICAgYXV0byBlbnM0CiAgICAgIGFsbG93LWhvdHBsdWcgZW5zNAogICAgICBpZmFjZSBlbnM0IGluZXQgZGhjcAogICAgICAKICAgICAgYXV0byBlbnM1CiAgICAgIGFsbG93LWhvdHBsdWcgZW5zNQogICAgICBpZmFjZSBlbnM1IGluZXQgZGhjcAogICAgICAKICAgICAgYXV0byBlbnM2CiAgICAgIGFsbG93LWhvdHBsdWcgZW5zNgogICAgICBpZmFjZSBlbnM2IGluZXQgZGhjcAogICAgICAKICAgICAgYXV0byBlbnM3CiAgICAgIGFsbG93LWhvdHBsdWcgZW5zNwogICAgICBpZmFjZSBlbnM3IGluZXQgZGhjcAogICAgICAKICAgICAgYXV0byBlbnM4CiAgICAgIGFsbG93LWhvdHBsdWcgZW5zOAogICAgICBpZmFjZSBlbnM4IGluZXQgZGhjcAogICAgICAKICAgICAgYXV0byBlbnM5CiAgICAgIGFsbG93LWhvdHBsdWcgZW5zOQogICAgICBpZmFjZSBlbnM5IGluZXQgZGhjcAogICAgICAKICAgICAgYXV0byBlbnMxMAogICAgICBhbGxvdy1ob3RwbHVnIGVuczEwCiAgICAgIGlmYWNlIGVuczEwIGluZXQgZGhjcAoKIyMj";
private Connector conn;
- public InitialDeployment(Connector conn) {
- this.conn = conn;
+ public static void main (String args[]) {
+ Connector conn = new LocalhostConnector("localhost", 8080, "ubuntu");
+ RegistryAndLoggerSetup.setup();
+ deploy(conn);
}
- public void deploy() {
+ public static void deploy(Connector conn) {
System.out.println("Initial Deployment");
Path occiPath = getModelPath("de/ugoe/cs/rwm/mocci/occi/hadoopClusterNewExtWithMem.occic");
Resource model = ModelUtility.loadOCCIintoEMFResource(occiPath);
diff --git a/src/main/java/de/ugoe/cs/rwm/mocci/MAPE.java b/src/main/java/de/ugoe/cs/rwm/mocci/MAPE.java
index 3446bad7c2315b5ea3bed6873e3f93a16d29ca18..da284f7e62d98aaf388cf255a7cda4ff0f8148e6 100644
--- a/src/main/java/de/ugoe/cs/rwm/mocci/MAPE.java
+++ b/src/main/java/de/ugoe/cs/rwm/mocci/MAPE.java
@@ -28,7 +28,6 @@ public class MAPE {
public static void main(String[] args) {
System.out.println("Starting MAPE loop");
RegistryAndLoggerSetup.setup();
- initialDeploy(conn);
while(true) {
try {
@@ -46,11 +45,6 @@ public class MAPE {
}
}
-private static void initialDeploy(Connector conn) {
- InitialDeployment depl = new InitialDeployment(conn);
- depl.deploy();
- }
-
public static Monitor monitor() {
int critCPUs = getNumberOfCriticalCPUs();
int noneCPUs = getNumberOfNoneCPUs();
diff --git a/src/main/resources/mape.sh b/src/main/resources/vertical.sh
similarity index 100%
rename from src/main/resources/mape.sh
rename to src/main/resources/vertical.sh
diff --git a/src/test/java/de/ugoe/cs/rwm/mocci/MapeTest.java b/src/test/java/de/ugoe/cs/rwm/mocci/MapeTest.java
index 645f120d8c87c1e209b6d013664fcc64b393525e..7b3e9692f7680e5824032e4b813ec41dac57574a 100644
--- a/src/test/java/de/ugoe/cs/rwm/mocci/MapeTest.java
+++ b/src/test/java/de/ugoe/cs/rwm/mocci/MapeTest.java
@@ -29,14 +29,14 @@ public class MapeTest {
}
@Before
- public void deprovisionEverything() {
+ public void resetEverything() {
CachedResourceSet.getCache().clear();
Path occiPath = Paths.get(ModelUtility.getPathToResource("occi/Empty.occic"));
Connector conn = new LocalhostConnector("localhost", 8080, "ubuntu");
MartDeployer deployer = new MartDeployer(conn);
deployer.deploy(occiPath);
- InitialDeployment depl = new InitialDeployment(conn);
- depl.deploy();
+
+ InitialDeployment.deploy(conn);
}
@Test