Browse Source

Merge "Add runtime creation guide"

Zuul 3 years ago
committed by Gerrit Code Review
2 changed files with 121 additions and 2 deletions
  1. +112
  2. +9

+ 112
- 2
doc/source/admin/runtime.rst View File

@ -15,5 +15,115 @@
Create your own runtime
Although there are several runtime implementation in-tree, it's very easy to
implement your own runtime for the preferred programming language.
Although there are several reference runtime implementations in-tree, it's very
easy to develop a new runtime for the preferred programming language not
implemented so far.
.. note::
Actually, in the production environment(especially in the public cloud),
it's recommended that cloud providers provide their own runtime
implementation for security reasons. Knowing how the runtime is implemented
gives the malicious user the chance to attack the cloud environment.
Qinling uses Kubernetes as the default container orchestrator, so this guide
will describe how the runtime containers working in the Kubernetes environment.
There are two containers in a Kubernetes pod serving the runtime, one is called
"sidecar" which is responsible for downloading the function package if needed,
the other one is the actual runtime container that is also running as an HTTP
server. Once a Qinling runtime is created, there is a pool of such pods, when a
function is being executed, some pods(according to the autoscaling policy) are
chosen to run the function code.
Usually, you only need to develop the runtime container and re-use the sidecar
container in the pod. There is only one public API that the runtime container
should provide.
Public API provided by the runtime
Example request:
.. code-block:: console
POST /execute
.. end
Parameters provided by Qinling:
1. The execution information.
* **execution_id**: The Qinling execution UUID.
* **download_url**: The URL sent to Qinling to download the function
package. Here is an example for how to download function package in your
runtime implementation using ``requests`` python library, the request is
meant to send to the sidecar container, the final package should be put
in ``/var/qinling/packages/<function_id>.zip`` if the request is
successfully handled by the sidecar:
.. code-block:: console
resp =
'download_url': download_url,
'function_id': function_id,
'token': params.get('token')
.. end
* **function_id**: The Qinling function UUID.
* **entry**: The function entry that user defines when creating the
function, e.g. "hello_world.main"
* **input**: The dictionary of the function input that user defines when
creating the function execution. e.g. ``{"key": "value"}``. If the user
specifies the positional params when creating the function execution, the
input will be something like
``{"__function_input": ("arg1", "arg2"), "key": "value"}``
* **timeout**: The timeout in seconds user defines when creating the
function, the default value is 5. Your runtime implementation should take
this timeout value into account when executing the code. If the timeout
is reached, you should terminate the function execution and return an
appropriate error message.
* **cpu**: The CPU limit user defines when creating the function. Your
runtime is responsible for limiting the CPU resource usage when the
function is running.
* **memory_size**: The memory limit user defines when creating the
function. Your runtime is responsible for limiting the memory resource
usage when the function is running.
* **request_id**: The request UUID for the function execution which can be
used to track the execution for debugging purpose.
2. The Information of the user who triggers the function execution.
Most of that information is used for creating a Keystone session that could
be passed to the function, so it's easy to interact with the OpenStack
services in the function code.
* **trust_id**: The trust UUID in Keystone. Please see for more information
in `Keystone official doc <>`__
about Trust.
* **auth_url**: Identity service endpoint for authorization.
* **username**: Username for authentication.
* **password**: Password for authentication.
* **token**: Token for authentication.
Content in the response dictionary:
* **output**: The return value of the function execution if it is successful,
otherwise the error message.
* **duration**: The execution duration in seconds.
* **logs**: The stdout content during the function execution.
* **success**: True or False. It should be False if the execution reaches
timeout, any exception raised inside user's function or the execution is
killed because of too much system resource consumed, etc.

+ 9
- 0
doc/source/glossary.rst View File

@ -19,3 +19,12 @@ As the Qinling project evolves, it's important that people working on Qinling,
users using Qinling, and operators deploying Qinling use a common set of
terminology in order to avoid misunderstandings and confusion. To that end, we
are providing the following glossary of terms.
The runtime is programming language support. In Qinling, each runtime is
encapsulated in a container image which is used for creating the runtime
container. Qinling communicates with the container by sending HTTP requests and
runs user function inside. Currently, Qinling only supports Python 2 and
Python 3 officially and Node.JS in experimental.