General hints on components

This page contains general hints regarding components (i.e., Docker containers) that are created by the Hobbit platform during the benchmarking of a system.

Environment variables

During the creation of docker containers, environment variables can be defined. The following variables are defined by the platform controller:

• HOBBIT_SESSION_ID defines the session id of the current benchmark run the created component is a part of.
• HOBBIT_RABBIT_HOST the name of the RabbitMQ host which is used by the platform.
• HOBBIT_CONTAINER_NAME the name of the container. Additionally, other environment variables can be added by the component that requested the container creation.

Note that variables with a hyphen in their name, e.g., may-own-variable, seem to cause problems in Dockers HTTP API. The container will be created but the variable will not be correctly set.

Creating containers

The platform controller offers the creation of containers. Using this API, a component can request the creation of additional components, e.g., a benchmark controller can request the creation of benchmark related components or a benchmarked system can request the creation of additional containers needed by the system.

Creating a container

For the communication with the platform controller, the command queue is used. Requesting the creation of a container is done by sending the Commands.DOCKER_CONTAINER_START id (=0x0C) on the command queue, followed by a UTF-8 encoded String containing the following JSON data:

{
  "image": "image-to-run",
  "type": "system|benchmark",
  "parent":"parent-container-name",
  "environmentVariables": [
    "key1=value1",
    "key2=value2"
  ]
}

Where image-to-run is the complete name of the image that should be run (including the repository URL), type contains the information whether it belongs to the benchmark or the benchmarked system and parent-container-name is the name of the container that sends the request (i.e., the value of the HOBBIT_CONTAINER_NAME environment variable). With the environmentVariables array, the creating container can submit additional information, e.g., parameters, to the newly created container.

The response is either the name of the created container as UTF-8 encoded string or an empty response if an error occured.

The Hobbit platform organizes the containers as a tree. The container that requests the creation of another container serves as parent of this newly created container. Note that a parent container should always make sure that its chield containers terminate before the parent terminates. If a parent terminates and its children are still running, the platform will force them to stop.

All created components are part of the same network. In this network, the container names serves as the host names of the containers.

Stopping and removing a container

Stopping a container can be done by sending a message to the command queue containing the Commands.DOCKER_CONTAINER_STOP id (=0x0D) followed by a UTF-8 encoded String containing the following JSON data:

{
  "containerName": "container-to-stop"
}

where container-to-stop should be replaced by the container name that has been received during the creation of the container.

Container termination

When a container terminates, the platform controller sends a broadcast message to the command queue containing the container name and its exit code.

In most cases, a container exits with an exit code 0 if it was running successfully. However, please note that the exit code 137 might be caused by the termination of the container using the stop command described above, i.e., not every exit code that is not equal to 0 might indicate a problem.

General message structure

The message that is received in these cases has the following structure:

start byte	length	meaning
0	4	9 (length of the String "BROADCAST")
4	9	"BROADCAST"
13	1	0x10 (the Id of the Commands.DOCKER_CONTAINER_TERMINATED command)
14	4	length of the container name (c)
18	c	container name
18 + c	1	exit code

Receiving the message using our Abstract Java classes

If our abstract Java classes are used, receiving this messages can be eased by adding the following lines of code to the component:

    public MyComponent() {
        // We have to add the broadcast command header to receive messages about
        // terminated containers
        addCommandHeaderId(Constants.HOBBIT_SESSION_ID_FOR_BROADCASTS);
    }

    @Override
    public void receiveCommand(byte command, byte[] data) {
        if (command == Commands.DOCKER_CONTAINER_TERMINATED) {
            ByteBuffer buffer = ByteBuffer.wrap(data);
            String containerName = RabbitMQUtils.readString(buffer);
            int exitCode = buffer.get();
            // check whether it is one of your containers and react accordingly
        }
        super.receiveCommand(command, data);
    }