Commit aedbd515 authored by Stefan Dähling's avatar Stefan Dähling
Browse files

revise docu

parent 494b373e
Pipeline #395274 passed with stages
in 1 minute and 7 seconds
......@@ -43,8 +43,9 @@ For easy user interaction it is planned to provide a WebUI that interacts with t
The following documentation is available for cloneMAP:
- [Repository structure](docs/repo.md)
- [Installation requirements](docs/installation.md)
- [User guide](docs/user.md)
- [Developer Guide](docs/developer_guide.md)
- [Administration Guide](docs/administration_guide.md)
- [User Guide](docs/user_guide.md)
Documentation of the code follows the [godoc](https://blog.golang.org/godoc-documenting-go-code) specification.
......
# Adminitration Guide
This administration guide provides the knowledge necessary to start, maintain and stop cloneMAP, either locally or on a Kubernetes Cluster.
## Local deployment
Although cloneMAP is designed to be executed within a Kubernetes cluster it can also be executed locally.
This is ment as an easier way to test your MAS application.
Note that microservices such as the AMS, DF and Logger cannot be scaled horizontally with this method.
Moreover, the platform is not fault-tolerant when deployed locally and cannot be spread over several machines.
In order to start cloneMAP locally you need a docker installation.
How to get started with docker is explained [here](https://docs.docker.com/get-started/).
An installation guide for Ubuntu can be found [here](https://docs.docker.com/install/linux/docker-ce/ubuntu/).
After installing Docker you can start cloneMAP by running the following command:
```bash
docker run -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock --name=kubestub registry.git.rwth-aachen.de/acs/public/cloud/mas/clonemap/clonemap_local
```
This command will start a Docker container of the image `registry.git.rwth-aachen.de/acs/public/cloud/mas/clonemap/clonemap_local` and assign the name `kubestub` to it.
The kubestub container will create a custom Docker network called `clonemap-net` and attach itself to this network.
Subsequently it will start the AMS in a seperate container on the host.
This is enabled by mounting the directory `/var/run/docker.sock` of the host to the same directory in the kubestub container.
As a result, all docker commands executed inside of the kubestub container will be send to the Docker daemon of the host.
The output of starting the kubestub container should look like this:
```bash
docker run -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock --name=kubestub registry.git.rwth-aachen.de/acs/public/cloud/mas/clonemap/clonemap_local
>Create Bridge Network
>Create AMS Container
>Ready
```
You can check the success of starting cloneMAP with the `docker ps` command.
The output should look similar to this:
```bash
docker ps
>CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
>951af55605ef registry.git.rwth-aachen.de/acs/public/cloud/mas/clonemap/ams "./ams" 14 seconds ago Up 12 seconds 0.0.0.0:30009->9000/tcp ams
>00fd5d077b8a registry.git.rwth-aachen.de/acs/public/cloud/mas/clonemap/clonemap_local "docker-entrypoint.s…" 19 seconds ago Up 16 seconds 0.0.0.0:8000->8000/tcp kubestub
```
If you want use other modules you can start them as well by setting corresponding environment variables when starting the kubestub container.
For example, if you would like to start a MQTT broker the command would look like this:
```bash
docker run -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock -e CLONEMAP_MODULE_MQTT=true --name=kubestub registry.git.rwth-aachen.de/acs/public/cloud/mas/clonemap/clonemap_local
```
The following environment variables can be used to start further modules:
* CLONEMAP_MODULE_MQTT: Mosquitto MQTT broker
* CLONEMAP_MODULE_DF: cloneMAP DF module
* CLONEMAP_MODULE_LOGGER: cloneMAP Logging module
* CLONEMAP_MODULE_PNP: cloneMAP PnP module
* CLONEMAP_MODULE_FRONTEND: cloneMAP WebUI module
* CLONEMAP_MODULE_FIWARE: FiWare Orion Broker ans MongoDB
Moreover, you can set the log level to either:
* CLONEMAP_LOG_LEVEL=info
* CLONEMAP_LOG_LEVEL=error (default)
The kubestub container is started in foreground mode.
It will give a message when a new container is started and show *Ready* once all specified modules are started.
You can terminate cloneMAP terminating the kubestub container.
In the concole where you started the kubestub container press `ctrl`+`c`.
This process might take a few seconds since the kubestub container cleans up before terminating.
That means that all containers started by the kubestub container are terminated.
A corresponding output shows the progress.
Subsequently it will detach itself from the clonemap-net network, delete the network and then terminate itself.
Starting the platform locally and then terminating it should produce the following output:
```bash
docker run -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock --name=kubestub registry.git.rwth-aachen.de/acs/public/cloud/mas/clonemap/clonemap_local
>Create Bridge Network
>Create AMS Container
>Ready
>^CCaught sig: interrupt
>Stop AMS Container
>Delete Bridge Network
```
## Kubernetes deployment
Kubernetes can be installed using [kubeadm](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/).
If you use a public cloud provider you typically can create preconfigured Kubernetes clusters.
For testing purposes it might be more convenient to use a local installation of Kubernetes instead of a real production cluster.
This can be achieved by using Minikube.
Minikube starts a single virtual machine on your local machine and runs all necessary parts of Kubernetes in this VM.
Minikube can be installed as described [here](https://kubernetes.io/docs/tasks/tools/install-minikube/).
To get started with Kubernetes, please have a look [here](https://kubernetes.io/docs/home/).
Once you have a running Kubernets cluster you can deploy cloneMAP by applying the yaml file in `deployments` directory:
```bash
kubectl apply -f deployments/k8s.yaml
```
This will create a new namespace called *clonemap* and deploy all cloneMAP components to that namespace.
The process will take a few seconds.
During execution you can manage cloneMAP components by using the Kubernetes dashboard or `kubectl` commands.
For example you could scale microservice horizontally to cope with a high load.
cloneMAP is terminated by deleting all its resources:
```bash
kubectl delete -f deployments/k8s.yaml
```
# Developer Guide
This developer guide aims at getting cloneMAP developers started.
It describes important implementation details of the existing modules and provides a description of how to add further modules to cloneMAP.
Please also have a look at the [repo structure](repo.md).
## General considerations
cloneMAP follows a cloud-native application design.
That means that the platform is composed by microservices which can be deployed seperately and offer a REST API for interaction with other microservices.
Microservices are implemented stateless.
State information is handled by distributed storages, i.e., an etcd store and a Cassandra DB.
Single microservices of the MAP are deployed as docker-containers.
cloneMAP can be deployed locally or on a Kubernetes Cluster (see [Admin Guide](administration_guide.md)).
All cloneMAP micorservices are deployed as Docker containers.
cloneMAP microservices are started on Kubernetes as Deployments with a corresponding Service.
These Deployments can be scaled horizontally.
Distributed storages are started as StatefulSets.
All existing modules are written in Go.
How to setup Go is described [here](https://golang.org/doc/install). The used Go version is Go1.13.8.
The code documentation of all components follows the [godoc](https://blog.golang.org/godoc-documenting-go-code) specification.
Dependency management is handled with [Go modules](https://github.com/golang/go/wiki/Modules) which has been included as official Go tool since Go1.11.
New modules can also be implemented in any other language since interaction between modules happens via a REST API.
However, it might be necessary to provide a Go client for the API in order to enable the usage of the new module from within other modules.
## Existing modules
TBD
### Core
#### AMS
#### Agencies
### DF
### Logging
### IoT
### Plug&Play
### WebUI
#### Backend
#### Frontend
## Implementing new modules
TBD
# Installation requirements
## Golang
cloneMAP is written in Go. Therefore, in order to get started you first need a running Go installation on your machine. How to setup Go is described [here](https://golang.org/doc/install). The used Go version is Go1.13.8.
The code documentation of all components follows the [godoc](https://blog.golang.org/godoc-documenting-go-code) specification.
Dependency management is handled with [Go modules](https://github.com/golang/go/wiki/Modules) which has been included as official Go tool since Go1.11.
## Docker
Single components of the MAP are deployed as docker-containers. How to get started with docker is explained [here](https://docs.docker.com/get-started/). An installation guide for Ubuntu can be found [here](https://docs.docker.com/install/linux/docker-ce/ubuntu/).
## Kubernetes
Kubernetes can be installed using [kubeadm](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/).
If you use a public cloud provider you typically can create preconfigured Kubernetes clusters.
For testing purposes it might be more convenient to use a local installation of Kubernetes instead of a real production cluster. This can be achieved by using Minikube. Minikube starts a single virtual machine on your local machine and runs all necessary parts of Kubernetes in this VM. Minikube can be installed as described [here](https://kubernetes.io/docs/tasks/tools/install-minikube/).
......@@ -4,11 +4,11 @@ The structure of the repository follows the [Golang standard project layout](htt
## `api` - API documentation
This folder contains documentation of the http API implemented by the different components of cloneMAP.
This folder contains documentation of the http API implemented by the different components of cloneMAP. The openAPI standard is used for this putpose
## `build` - Dockerfiles
This folder contains the Dockerfiles used to build Docker images of all cloneMAP components.
This folder contains the Dockerfiles used to build Docker images of all cloneMAP components. Docker images are automatically updated in the Docker registry of this project by the CI.
## `cmd` - main files
......@@ -16,7 +16,7 @@ This folder contains the `main.go` files for all cloneMAP components.
## `deployments` - Kubernetes
This folder contains the yaml file required to start cloneMAP on a Kubernetes cluster.
This folder contains a single yaml file required to start cloneMAP on a Kubernetes cluster.
## `docs` - documentation
......@@ -24,8 +24,12 @@ This folder contains documentation for getting started with cloneMAP.
## `examples` - benchmark behavior
This folder contains the implementation of agent behavior used for the benchmarking of cloneMAP.
This folder contains the implementation of agent behavior used for the benchmarking of cloneMAP. Benchmarks for the messaging, DF and CPU utilization are included.
## `pkg` - cloneMAP packages
This folder contains the Go packages which implement the functionality of the different cloneMAP components. There exists one package for each component as well as client packages and some commonly used packages.
## `web` - Web UI
HTML, CSS and Javascript sources for the web UI
......@@ -2,17 +2,28 @@
## Step-by-step example
In the following we provide you with a step-by-step example for agent behavior implementation, cloneMAP deployment, MAS deployment and log analysis. It is assumed that you have followed the instruction for the [installation requirements](installation.md). In the example two agents will be started which send each other one message and indicate the receipt with a log message.
In the following we provide you with a step-by-step example for agent behavior implementation, MAS deployment and log analysis.
It is assumed that you have a running cloneMAP instance, either locally or on a Kubernetes cluster.
If not, please have a look at the [Admin Guide](administration_guide.md).
In the example two agents will be started which send each other one message and indicate the receipt with a log message.
### Step 1 Behavior implementation
All agents are executed in agencies. An agency is a single container pod in a StatefulSet. One agency can host multiple agents. For each agent one task function is executed in a seperate go-routine. This task function is defined by the MAS developer.
All agents are executed in agencies.
An agency is a single container pod in a StatefulSet.
One agency can host multiple agents.
For each agent one task function is executed in a seperate go-routine.
This task function is defined by the MAS developer.
If you want to use cloneMAP for MAS application development the only thing you have to implement is the agent behavior. In order to implement a certain agent behavior you have to use the agency package (pkg/agency). This package defines the *Agent* structure which can be used to access platform functionalities like messaging or interaction with the DF and the other modules.
If you want to use cloneMAP for MAS application development the only thing you have to implement is the agent behavior.
In order to implement a certain agent behavior you have to use the agency package (pkg/agency).
This package defines the *Agent* structure which can be used to access platform functionalities like messaging or interaction with the DF and the other modules.
Implement a task function that takes a pointer to an *Agent* object as parameter and returns an *error*. Start the agency using that task function. Every started agent will execute this task function as seperate go-routine.
Implement a task function that takes a pointer to an *Agent* object as parameter and returns an *error*.
Start the agency using that task function.
Every started agent will execute this task function as seperate go-routine.
In the base directory create your your Go module file `go.mod`
In the base directory of your project create your Go module file `go.mod`
```Go
module example
......@@ -52,11 +63,20 @@ func task(ag *agency.Agent) (err error) {
}
```
We define the agent behavior in the method `task`. In the main function we start the agency with the task function as parameter. Save the code in the file `cmd/main.go`.
We define the agent behavior in the method `task`.
In the main function we start the agency with the task function as parameter.
Save the code in the file `cmd/main.go`.
#### Using other programming languages
Components in cloneMAP interact with each other using a REST API. This is also true for the agency. Hence, you don't have to use Go as a programming language for your agent behavior. In order to use any other language you have to make sure that the agency implements the API. The API specification for the agency can be found in [api/agency](../api/agency/openapi.yaml) directory. For interaction with other components, e.g. the DF, you have to implement clients that make use of the corresponding API. All REST APIs are specified using the openapi 3 format.
Components in cloneMAP interact with each other using a REST API. This is also true for the agency.
Hence, you don't have to use Go as a programming language for your agent behavior.
In order to use any other language you have to make sure that the agency implements the API.
The API specification for the agency can be found in [api/agency](../api/agency/openapi.yaml) directory.
For interaction with other components, e.g. the DF, you have to implement clients that make use of the corresponding API.
All REST APIs are specified using the openapi 3 format.
A Python package for the implementation of agents in Python is already available [here](https://git.rwth-aachen.de/acs/public/cloud/mas/cmapy).
### Step 2 Building the Docker image
......@@ -94,49 +114,85 @@ docker push <registryname>
Besides specifying the agent behavior you also have to define the MAS configuration in order to start a MAS application. The MAS configuration consists of a list of agents you want to execute as well as individual configuration information for each agent. Take a look at the [API specification of the AMS](../api/ams/openapi.yaml) for a description of the MAS configuration. In the configuration you also have to specify the docker image to be used for the agencies. This corresponds to the image you created in the previous step.
Create the file `scenario.yaml` with following content.
```yaml
{"spec":{"id":0,"name":"example","registry":"<registry>","image":"<image>","secret":"<pull-secret>","agentsperagency":1,"logging":true,"mqtt":true,"df":true,"log":{"msg":true,"app":true,"status":true,"debug":true},"uptime":"0001-01-01T00:00:00Z"},"agents":[{"masid":0,"agencyid":0,"nodeid":0,"id":0,"name":"ExampleAgent","type":"example","custom":""},{"masid":0,"agencyid":0,"nodeid":0,"id":0,"name":"ExampleAgent","type":"example","custom":""}],"graph":{"node":null,"edge":null}}
```
Replace `<registry>`, `<image>` and `<pull-secret>` with the registry name, the image name and the name of the Kubernetes pull secret for the registry (in case it is a private registry). The given scenario defines a MAS with two agents. One agency contains one agent which will lead to the creation of two agency pods. The previously created Docker image will be used for the agencies.
### Step 4 cloneMAP deployment
It is assumed that you have a running Kubernetes cluster. Deploy cloneMAP by applying the yaml file in `deployments` directory:
```bash
kubectl apply -f deployments/clonemap.yaml
Create the file `scenario.json` with following content.
```json
{
"config":{
"name":"test",
"agentsperagency":1,
"logging":true,
"mqtt":true,
"df":false,
"log":{
"msg":true,
"app":true,
"status":true,
"debug":true
}
},
"groups":[
{
"config":{
"image":"<image>",
"secret":"<pull-secret>"
},
"agents":[
{
"nodeid":0,
"name":"ExampleAgent",
"type":"example",
"custom":""
},
{
"nodeid":0,
"name":"ExampleAgent",
"type":"example",
"custom":""
}
]
}
],
"graph":{
"node":null,
"edge":null
}
}
```
This will create a new namespace called *clonemap* and deploy all cloneMAP components to that namespace. The process will take a few seconds.
Replace `<image>` and `<pull-secret>` with the image name and the name of the Kubernetes pull secret for the registry (in case it is a private registry).
The given scenario defines a MAS with two agents.
One agency contains one agent which will lead to the creation of two agency pods.
The previously created Docker image will be used for the agencies.
#### Local deployment
### Step 4 MAS execution
Although cloneMAP is designed to be executed within a cloud-hosted container orchestration it can also be executed locally. This is ment as an easier way to test your MAS application. Note that components such as AMS, DF and Logger cannot be scaled horizontally with this method. In order to use the local version you have to build all necessary Docker images locally (AMS, DF, Logger). Afterwards go to cmd/kubestub directory and execute the stub:
In order to execute a MAS you have to post the previously created `scenario.json` file to the AMS.
Look at the [api specification](../api/ams/openapi.yaml) for the correct path and method to be used.
Subsequently the AMS will start all agencies which then will start the single agents.
Depending on the size the creation of a MAS might take a few seconds.
```bash
cd cmd/kubestub
go run main.go
curl -X "POST" -d @scenario.yaml <ip-address>:30009/api/clonemap/mas
```
The stub starts AMS, Logger, DF and a MQTT broker as Docker containers.
The AMS is made available to the outside world via NodePort on port 30009.
Replace `<ip-address>` with the IP address of one of your Kubernetes machines.
The AMS should answer with http code 201.
It starts the two agencies as StatefulSet which automatically execute one agent each.
### Step 5 MAS execution
### Step 5 Analysis
In order to execute a MAS you have to post the previously created `scenario.yaml` file to the AMS. Look at the [api specification](../api/ams/openapi.yaml) for the correct path and method to be used. Subsequently the AMS will start all agencies which then will start the single agents. Depending on the size the creation of a MAS might take a few seconds.
Use the logger module to request logged messages
```bash
curl -X "POST" -d @scenario.yaml http://<ip-address>:30009/api/clonemap/mas
curl -X "GET" <ip-address>:30011/api/logging/0/0/app/latest/10
```
The AMS is made available to the outside world via NodePort on port 30009. Replace `<ip-address>` with the IP address of one of your Kubernetes machines. The AMS should answer with http code 201. It starts the two agencies as StatefulSet which automatically execute one agent each.
### Step 6 Analysis
### Step 6 MAS termination
Use the logger module to request logged messages
Terminate the MAS by sending the following request to the AMS
```bash
curl -X "GET" http://<ip-address>:30011/api/logging/0/0/app/latest/10
curl -X DELETE <ip-address>:30009/api/clonemap/mas/0
```
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment