Describe how Poseidon abstracts from Nomad

docs/configuration.md

@@ -0,0 +1,19 @@
+# Configuration
+
+Poseidon can be configured to suit different use cases.
+
+
+## Poseidon
+
+Poseidon's configuration options are described in the sample configuration file.
+
+
+## Nomad
+
+As a subsystem of Poseidon, Nomad can and should also be configured accordingly.
+
+
+### Scheduler
+
+By default, Nomad uses a bin-packing scheduler. This places all Jobs on one host. In our case, a high load then leads to one Nomad client being fully utilised while the others remain mostly idle.
+To mitigate the overload of a Nomad client, the ["spread" scheduler algorithm](https://www.nomadproject.io/api-docs/operator/scheduler#update-scheduler-configuration) should be used.

docs/nomad_usage.md

@@ -0,0 +1,36 @@
+# Nomad Usage
+
+Poseidon is an abstraction of the functionality provided by Nomad. In the following we will look at how Poseidon uses Nomad's functionality.
+
+Nomad is structured in different levels of abstraction. Jobs are collected in namespaces. Each Job can contain several Task Groups. Each Task Group can contain several Tasks. Finally, Allocations map Task Groups to Nomad Clients. For more insights take a look at [the official description](https://www.nomadproject.io/docs/internals/architecture).
+In our case, a Task is executed in a Docker container.
+
+![Overview Poseidon-Nomad mapping](ressources/OverviewPoseidonNomadMapping.png)
+
+## Execution environments as template Jobs
+
+Execution Environments are mapped to Nomad Jobs. In the following, we will call these Jobs `Template Jobs`.
+The naming schema for Template Jobs is "template-\<execution-environment-id\>".
+
+The last figure shows the structure in Nomad.
+Each template Job contains a "config" Task Group including a "config" Task. This Task does not perform any computations but is used to store environment-specific attributes, such as the prewarming pool size.
+In addition, the template Job contains a "default-group" Task Group with a "default-task" Task. In this Task, `sleep infinity` is executed so that the Task remains active and is ready for dynamic executions in the container.
+
+As shown in the figure, the "config" Task Group has no Allocation, while the "default-group" has an Allocation.
+This is because the "config" Task Group only stores information but does not execute anything.
+In the "default-group" the user's code submissions are executed. Therefore, Nomad creates an Allocation that points the Task Group to a Nomad Client for execution.
+
+## Runner as Nomad Jobs
+
+As an abstraction of the execution engine, we use `Runner` as a description for Docker containers (currently used) or microVMs.
+If a user requests a new runner, Poseidon duplicates the template Job of the corresponding environment.
+
+When a user then executes their code, Poseidon copies the code into the container and executes it.
+
+## Prewarming
+
+To reduce the response time in the process of claiming a runner, Poseidon creates a pool of runners that have been started in advance.
+When a user requests a runner, a runner from this pool can be used.
+In the background, a new runner is created, thus replenishing the pool.
+By running in the background, the user does not have to wait as long as the runner needs to start.
+The implementation of this concept can be seen in [the Runner Manager](internal/runner/manager.go).

docs/ressources/OverviewPoseidonNomadMapping.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2021-07-29T09:10:40.306Z" agent="5.0 (X11)" etag="xc0NA0uUuogw2a5ns6QW" version="14.9.2" type="device"><diagram id="_cTqiwv0DkfbUgT-qijx" name="Page-1">7Vxbc+I2FP41PCZjyxfgMckm23bSTtpkp7uPCha2urZFbUGgv76SLeGLDDEYEE4gmcE6ulg+3/mOdGSJgXUXLb8mcBb8TjwUDoDhLQfWlwEApg3AgP8b3iqXDF07F/gJ9kShQvCM/0NCaAjpHHsorRSkhIQUz6rCCYljNKEVGUwS8lYtNiVh9a4z6CNF8DyBoSr9G3s0yKUjMCzkvyDsB/LOpjvOcyIoC4snSQPokbeSyLofWHcJITS/ipZ3KOTKk3rJ6z1syF13LEExbVNh/P3XW/LtzwUdBuljtHiYPl75V6KVBQzn4oEHwA1Ze7dTwpplvaYroQr33zmRGVdpBtQNK8C6sCwy2ZUvvrNWXqXgiaQIeySWGayfr/XCTJbfVYpBpQMgIfPYQ/xxDJb9FmCKnmdwwnPfmPUxWUCjkKVMdrlACcUMx5sQ+zGTUTJbt8nz0HKjHs01OsysEYkQTVasyFuBP3AEqEEJ+6FEGgqb89d1C1jYhUBmB5TARpQUHXaD7Q8SQW8jHE3InRdEogJwBRIlyBx3eErIrM7EMl2GUKb2OkgwQmmm1FPwJsKexxu6neIwvCMhSbJGranD/5g8pQn5iUo5bvYRD1SS5x8hF57edA+DuD1y8ipimGkwABM0cNY9Fv5DBQXksYFFJElCA+KTGIb3hfS2ilNR5pFwYmTo/IMoXQndwTklVezQEtPvvPq1I1I/RGP8+suynFjJRMwet1SJJ3/I9niiqJalZL06iCj2bvh4y9IehhGJvZcAx3nGA+bKE43IQR4Ya+i5arYDzzRJ5skEbdG4mFdQmPiIvsdM1ZASFEKKF9V+HNwsbMUt/EZe08/IWDA0Kow1Rw0+u2mYBdaxOOsq4LygaMbMgnlag+HUDaa6DjfCdgDluk5VuWudafOHpqlo7wQOcYuTmoQwTfGk4qDMioNyO3jHfTzxAX3hqKUvdDr6QlH1ieBsTiOszxpXrc8yalaV90vUKgyLQQNXpWIzXiDdch9QHfQtsxYBvdevanl2kfegsPK1TjoYvtFPw9drwONTGvCudmfbPbC7sTKYXV9f92cEs42azoA6go1POoCpQfgLTH8yyVemxNllDsdBawCpcQ43PhpKatx9E4ZkwrwBiT8nRu7ouuquHP0oqWEQ59LnxKfGIVc7OgDomLEcYR2i3UzngLMW0205bXE7Tlu6sU+NcycknmK/P7ODNUnkwGM5emcHQEt4+yE4M2zJGVMvaYYfjjSudtJYF9LsSZq2Czx6OTNSOOOhKZyH9MrnMVN/qDM8u/HGuVBnT+q0XVoqbdLQwR11/UZyh2bLDn2ljv5Rx75QZz/qSCTfn6qNdFJHdrNEHbheA+ovcRzdxLEuxNmXOG3XBfTypv/rAmB0bvM0PfuAPgJn2oY4QGuMA9QYp++k0T5Dsy7Bzb6kaRvcdB1o9ntvXtuvId/xbnxvvr38cd6bg82BV88WLaxzGwzlJrQLr3fltSWPvry7uVXr7lbZzd4vWtSpo39IBBfq7Ekdq+08cqyVOurGlT4uWtSJo3/RQnMAVqZNiUW7EycmMaqwxlBY48E0yHrNu5BvbpFnFsGBSdV2QUPvcKQuaMgjUx5eyONSz5QfAS2OUpWyGkrvfIoLNJ2ze0qIN5/k1GbPZvA+4NjPE9k+za1H8F6ThkN5lU528Rf93EflntkBMFvzjpAP6njaBrhaF4UsNYa8X6LJPCe8cR8vcELiCInjD5+bqfrPJjkKWn0992VZxpnp1ta8x2c3N1hxZN184lHdoA1aukGtMY3s5fb511/zOEbJZSKzwT02HXw5LYXVNxwSsn45x/p7jiMeKWLJ4odd8pXp4udxrPv/AQ==</diagram></mxfile>