Document for prewarmed container

docs/prewarm.md

@@ -0,0 +1,106 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+# runtimes
+
+the runtime is the docker image for different language, e.g. nodejs:N, python:N, swift:N, etc.
+
+when user invokes actions, these relative activations are run on docker containers which base on
+these runtime docker images.
+
+# Prewarmed container without `reactive`
+
+Prewarmed containers are created when invoker starts, they are created according to runtimes.json's stemCells, e.g.
+
+```
+{
+    "kind": "nodejs:10",
+    "default": true,
+    "image": {
+        "prefix": "openwhisk",
+        "name": "action-nodejs-v10",
+        "tag": "nightly"
+    },
+    "deprecated": false,
+    "attached": {
+        "attachmentName": "codefile",
+        "attachmentType": "text/plain"
+     },
+     "stemCells": [
+     {
+        "initialCount": 2,
+         "memory": "256 MB"
+     }
+     ]
+}
+```
+Regarding above runtime(nodejs:10 kind + 256 MB memory), `2` prewarmed conatainrs will be created when invoker starts,
+and the number of prewarmed container is stable usually, when activation is scheduled on the prewarmed container,
+another new prewarmed container will be created at the same time, on the other hand, previous used prewarmed container
+is moved from `prewarmedPool` to `busyPool`.
+
+the activation will be scheduled on prewarmed container firstly, then subsequent activation will be scheduled on warmed containers.
+because prewarm container is already created in advance, so this can avoid `cold start`.
+
+# Prewarmed container with `reactive`
+
+`Adjust the prewarmed container resource dynamically` is supported by `reactive` configuration, e.g.
+```
+{
+    "kind": "nodejs:10",
+    "default": true,
+    "image": {
+        "prefix": "openwhisk",
+        "name": "action-nodejs-v10",
+        "tag": "nightly"
+    },
+    "deprecated": false,
+    "attached": {
+        "attachmentName": "codefile",
+        "attachmentType": "text/plain"
+     },
+     "stemCells": [
+     {
+        "initialCount": 2,
+         "memory": "256 MB",
+         "reactive": {
+             "minCount": 1,
+             "maxCount": 4,
+             "ttl": "2 minutes",
+             "threshold": 1,
+             "increment": 1
+     }
+     ]
+}
+```
+`reactive` fields explanation:
+* minCount: exist at least `minCount` prewarmed containers.
+* maxCount: can't create more than `maxCount`prewarmed containers.
+* ttl: the prewarmed conainers will be deleted due to expiration, because they are not used in ttl time.
+* threshold and increment: these two fileds are used together to calculate the new created number of prewarmed containers.
+
+How to support `adjust the prewarmed container resource dynamically`
+
+* Some prewarmed containers will be deleted if they are expiration, this can save some memory resource.
+* Create a certain range prewarmed conainers according to the cold start in same kind on next schedule time, e.g.
+  - cold start number = 2, number of prewarmed container will be created = cold start number(2)/threshold(2) * increment(1) = 1
+  - cold start number = 4, number of prewarmed container will be created = cold start number(4)/threshold(2) * increment(1) = 2
+  - cold start number = 8, number of prewarmed container will be created = cold start number(8)/threshold(2) * increment(1) = 4
+  - cold start number = 16, number of prewarmed container will be created = 4(cannot exceed the maximum value)
+  - if cold start doesn't happen, `minCount` prewarmed container will be created on next schedule time.