Vulcan - Third-Party Service Manager API - Specification

Vulcan should be implemented as REST API Server, with functional requirements being:

  1. POST/PUT Uploading archive with required dockerfile and other files for starting program on docker container
  2. POST Starting the docker container
  3. POST Stopping the docker container
  4. POST Removing the docker container
  5. POST/PUT Updating the archive with required dockerfile and other files for starting program on docker container
  6. GET Getting CPU/RAM usage for given container
  7. GET Getting time container worked this month/week/day
  8. GET Active period statistics

Except for given request, this service should have the following features:

  1. Internal managment and monitoring of containers, can be done using some type of docker swarm
  2. Calculating CPU/RAM usage for containers, can be extracted using docker's own stastics.
  3. Algorithm and functions to create whole docker file and communicate with them
  4. This part might be tricky, but engineers here should create a way to expose port for Docker rest api on local network so Mercury can target it. I assume Mercury service should create some sub-domain for that service. Will be investigated

Before we start

There is one part not clear to me yet, we will have meeting for it, and that is exposing docker container so mercury can target it.

Basically the way this works is that user can upload a zip archive to server, server unpacks it and creates a docker container with given files in archive. The archive should look like this

----/
  |
  ├-- application.dockerfile
  |
  └-- source
        |
        ├-- main.py
        |
        ├-- requirements.txt
        |
        └-- utils.py

This examples shows application with 2 files, main.py and utils.py, it is something interally that we don't care about. We just care about dockerfile. Basically a dockerfile would look like this

FROM python:3

RUN mkdir -p /opt/src/applications
WORKDIR /opt/src/applications

COPY source/daemon/main.py main.py
COPY source/utils.py utils.py
COPY source/requirements.txt requirements.txt

RUN pip install -r requirements.txt

ENTRYPOINT ["python", "main.py"]

This means that docker will call everything automatically, so the user is the one who needs to be careful about writing this file.

This service should also have some kind of internal data for usage and if the docker is running and etc. The best way for this is to have some kind of database where you have user and his dockerfiles with their local path and urls.

1. Uploading archive

URL: vulcan.lws.com/upload

Body of this request should be archive described above. You shoudl unpack it, start the container with docker and store files on cloud storage. The response for this request should be either success of not, if it is not succesfull it should look like:

{    "status": "failed",    "message": "this describes why"}

If it is succesfull:

{    "status": "success",    "message": "on this url a user should access his docker file service"}

2. Starting the docker container

URL: vulcan.lws.com/start?id=ID ILI IME TOG KONTEJNERA NZM

This request simply starts the container uploaded by the user and should return the url on which users can access this container. This request should also create DNS entry with given url. The request would be just url while the response is:

{    "status": "success",    "url": "unique_url.vulcan.lws.com" // message if it fails}

The url will be generated as subdomain of vulcan.lws.com, it will be some unique url, maybe you can create it using users id and name of service. It is up to you, as long as it is unique and it works.

3. Stopping the docker container

URL: vulcan.lws.com/stop?id=ID ILI IME TOG KONTEJNERA NZM

Simple request for stopping service. This request should stop the service and remove its subdomain from dns. If it fails, it should message user why it failed Response will be:

{    "status": "success", //or not?    "message" : "why?"}

4. Removing the docker container

URL: vulcan.lws.com/remove?id=ID ILI IME TOG KONTEJNERA NZM

This request should stop service if its working and remove it from storage all together, delete it basically. If it fails, it should message user why it failed Response will be:

{    "status": "success", //or not?    "message" : "why?"}

5. Updating the archive

URL: vulcan.lws.com/update?id=ID ILI IME TOG KONTEJNERA NZM

This is different, a bit more complicated request. I must read a bit more how containerized OS works, but it would be nice if a user can update seperate files and/or add new files to container. Work without this part for now, it might be a bit hard :)

6. Getting CPU/RAM usage for given container

URL: vulcan.lws.com/check?id=ID ILI IME TOG KONTEJNERA NZM

GET request for getting usage for given container. Docker already provides interface for such statistic, so it will be wrapper around it and then returning nice data to user and/or frontend. This is the part that will also calculate how much container was used. It should be sampled each second, or even smaller sample rate, but that will be changed after everything is done, during frontend development, because maybe a second is good enough. Response should be

{    "cpu":"23%",    "ram": "12%"}

7. Getting time container worked this month/week/day

URL: vulcan.lws.com/time?id=ID ILI IME TOG KONTEJNERA NZM&slice=m|w|d

GET request for getting time this container wokred during the month, week or day. Docker should provide usage of CPU and RAM, and you will ignore if it uses less than 1% of cpu(for example). This part will also calculate the price a user should pay for month, depending on usage and time it worked.

{    "slice": "month",    "time": "23day",    "relative": "69%"}

8. Active period statistics

URL: vulcan.lws.com/statistics?id=ID ILI IME TOG KONTEJNERA NZM&slice=m|w|d

GET request for getting statistics of when this container is most active. If a user specifies slice as month, you should return % of time usage for each day during that month(1., 2.,...). If a user specifies slice as week, you should return % of time usage for each day in week(monday, tuesday,...). If a user specifies slice as day, you should return % of time usage for each hour during day(from 00:00 to 23:00) Response for week would look like:

{    "monday": "20%",    "tuedays": "12%",    ...    "saturday": "76%",    "sunday": "90%"}

It returns % of time during that day(or hour), not relative to others day. If in monday, container was used for 12 hours, it returns 50%

Table of Contents