diff --git a/docs/definitions.md b/docs/definitions.md index ed339a85a..3ee5e69c9 100644 --- a/docs/definitions.md +++ b/docs/definitions.md @@ -83,6 +83,7 @@ curl -H "Content-Type: application/json" -X POST -d '{ "image": "fnproject/hello", "type": "sync", "memory": 128, + "cpus": "100m", "config": { "key": "value", "key2": "value2", @@ -125,6 +126,10 @@ In `async` functions the request will be ended with a `call_id` and the function `memory` defines the amount of memory (in megabytes) required to run this function. +#### cpus (string) + +`cpus` defines the amount of CPU cores (in MilliCPUs or floating-point number) required to run this function. For example, `500m` for 1/2 CPU cores or `0.5` for 1/2 CPU cores. + #### config (object of string values) `config` is a map of values passed to the route runtime in the form of diff --git a/docs/function-file.md b/docs/function-file.md index 4d9410b22..f3e101391 100644 --- a/docs/function-file.md +++ b/docs/function-file.md @@ -14,6 +14,7 @@ name: fnproject/hello version: 0.0.1 type: sync memory: 128 +cpus: 100m config: key: value key2: value2 @@ -56,6 +57,11 @@ Default: `sync`. function. If this function exceeds this limit during execution, it is stopped and error message is logged. Default: `128`. +`cpus` (optional) is the amount of available CPU cores for this function. For example, `100m` or `0.1` +will allow the function to consume at most 1/10 of a CPU core on the running machine. It +expects to be a string in MilliCPUs format ('100m') or floating-point number ('0.5'). +Default: unlimited. + `timeout` (optional) is the maximum time a function will be allowed to run. Default is 30 seconds. `headers` (optional) is a set of HTTP headers to be returned in the response of diff --git a/docs/function-format.md b/docs/function-format.md index a533a603a..8a3e596ab 100644 --- a/docs/function-format.md +++ b/docs/function-format.md @@ -77,6 +77,7 @@ following, that may be found in the environment instead: * `FN_METHOD` * `FN_FORMAT` * `FN_MEMORY` +* `FN_CPUS` (present only if `cpus` is set for the route) * `FN_TYPE` #### Pros/Cons diff --git a/docs/hot-functions.md b/docs/hot-functions.md index 00156bbd5..f3489f34d 100644 --- a/docs/hot-functions.md +++ b/docs/hot-functions.md @@ -93,6 +93,7 @@ requests: "path": "/hot", "image": "USERNAME/hchttp", "memory": 64, + "cpus": "100m", "type": "sync", "config": null, "format": "http", diff --git a/docs/operating/routes.md b/docs/operating/routes.md index b0b069d0a..43619a5b8 100644 --- a/docs/operating/routes.md +++ b/docs/operating/routes.md @@ -3,17 +3,22 @@ Routes have a many-to-one mapping to an [app](apps.md). A good practice to get the best performance on your Fn API is define -the required memory for each function. +the required memory as well as CPU limits for each function. ## Route level configuration When creating a route, you can configure it to tweak its behavior, the possible -choices are: `memory`, `type` and `config`. +choices are: `memory`, `cpus`, `type` and `config`. `memory` is number of usable MiB for this function. If during the execution it exceeds this maximum threshold, it will halt and return an error in the logs. It expects to be an integer. Default: `128`. +`cpus` is the amount of available CPU cores for this function. For example, `100m` or `0.1` +will allow the function to consume at most 1/10 of a CPU core on the running machine. It +expects to be a string in MilliCPUs format ('100m') or floating-point number ('0.5'). +Default: `""` or unset, which is unlimited. + `type` is the type of the function. Either `sync`, in which the client waits until the request is successfully completed, or `async`, in which the clients dispatches a new request, gets a call ID back and closes the HTTP connection. @@ -26,14 +31,14 @@ Note: Route level configuration overrides app level configuration. TODO: link to swagger doc on swaggerhub after it's updated. -## Understanding Fn memory management +## Understanding Fn memory and CPU management -When Fn starts it registers the total available memory in your system +When Fn starts it registers the total available memory and CPU cores in your system in order to know during its runtime if the system has the required amount of -free memory to run each function. Every function starts the runner reduces the -amount of memory used by that function from the available memory register. When -the function finishes the runner returns the used memory to the available memory -register. +free memory and CPU to run each function. Every function starts the runner reduces the +amount of memory and CPU used by that function from the available memory and CPU register. +When the function finishes the runner returns the used memory and CPU to the available +memory and CPU register. ### Creating function @@ -43,13 +48,14 @@ curl -H "Content-Type: application/json" -X POST -d '{ "path":"", "image":"", "memory": , + "cpus": "", "type": "", "config": {"": } } }' http://localhost:8080/v1/apps//routes ``` -Eg. Creating `/myapp/hello` with required memory as `100mb`, type `sync` and +Eg. Creating `/myapp/hello` with required memory as `100mb`, cpus as `200m`, type `sync` and some container configuration values. ``` @@ -58,6 +64,7 @@ curl -H "Content-Type: application/json" -X POST -d '{ "path":"/hello", "image":"fnproject/hello", "memory": 100, + "cpus": "200m", "type": "sync", "config": {"APPLOG": "stderr"} } @@ -70,19 +77,21 @@ curl -H "Content-Type: application/json" -X POST -d '{ curl -H "Content-Type: application/json" -X POST -d '{ "route": { "memory": , + "cpus": "", "type": "", "config": {"": } } }' http://localhost:8080/v1/apps//routes/ ``` -Eg. Updating `/myapp/hello` required memory as `100mb`, type `async` and changed +Eg. Updating `/myapp/hello` required memory as `100mb`, cpus as `0.2`, type `async` and changed container configuration values. ``` curl -H "Content-Type: application/json" -X POST -d '{ "route": { "memory": 100, + "cpus": "0.2", "type": "async", "config": {"APPLOG": "stdout"} } diff --git a/docs/writing.md b/docs/writing.md index f241d90ea..069f72fe0 100644 --- a/docs/writing.md +++ b/docs/writing.md @@ -38,6 +38,7 @@ the function's format: * `FN_METHOD` - the HTTP method for the request, eg: `GET` or `POST` * `FN_FORMAT` - a string representing one of the [function formats](function-format.md), currently either `default` or `http`. Default is `default`. * `FN_MEMORY` - a number representing the amount of memory available to the call, in MB +* `FN_CPUS` - a string representing the amount of CPU available to the call, in MilliCPUs or floating-point number, eg. `100m` or `0.1`. Header is present only if `cpus` is set for the route. * `FN_TYPE` - the type for this call, currently 'sync' or 'async' Dependent upon the function's format, additional variables that change on a