ooks: start with pre-start and post-stop hooks.

Signed-off-by: Mrunal Patel <mrunalp@gmail.com>

runtime.md

@@ -15,3 +15,52 @@ Runs a process in a container. Can be invoked several times.
 Not sure we need that from oc cli. Process is killed from the outside.
 
 This event needs to be captured by oc to run onstop event handlers.
+
+## Hooks
+Hooks allow one to run code before/after various lifecycle events of the container. The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work.
+
+Hooks are executed from the host's filesystem. Hook paths can be:
+
+* An absolute path,
+* a file name (without path separators), in which case the file is searched for within the PATH environment variable, or
+* a relative path, in which case the file is found relative to the directory containing the config file. Relative paths cannot reference parent directories (i.e., no ../).
+
+The working directory for the hooks is set to the container's root filesystem unless overriden in the configuration.
+
+### Pre-start
+The pre-start hooks are called after the container process is started but before the user supplied command is executed. It provides an opportunity to customize the container. In Linux, for e.g., the network namespace could be configured in this hook.
+
+If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down.
+
+### Post-stop
+The post-stop hooks are called after the container process is stopped. Cleanup or debugging could be performed in such a hook.
+
+If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
+
+*Example*
+
+```
+    "hooks" : {
+        "pre-start": [
+            {
+                "path": "fix-mounts",
+                "args": ["arg1", "arg2"],
+                "env": {
+                           "key1": "value1"
+                       },
+                "dir": ""
+            },
+            {
+               "path": "/usr/libexec/acme/bin/setup-network"
+            }
+        ],
+        "post-stop": [
+            {
+               "path": "cleanup.sh",
+               "args": ["-f"]
+            }
+        ]
+    }
+```
+
+`path` is required for a hook. `args`, `env` and `dir` are optional.