spec: STATUS wording

This adds a new verb, STATUS, which indicates whether or not a plugin is
ready to accept ADD requests. Runtimes may choose to use the STATUS
mechanism to determine if a network is ready.

Signed-off-by: Casey Callendrello <c1@caseyc.net>

SPEC.md

@@ -16,9 +16,10 @@
       - [`ADD`: Add container to network, or apply modifications](#add-add-container-to-network-or-apply-modifications)
       - [`DEL`: Remove container from network, or un-apply modifications](#del-remove-container-from-network-or-un-apply-modifications)
       - [`CHECK`: Check container's networking is as expected](#check-check-containers-networking-is-as-expected)
+      - [`STATUS`: Check plugin status](#status-check-plugin-status)
       - [`VERSION`: probe plugin version support](#version-probe-plugin-version-support)
   - [Section 3: Execution of Network Configurations](#section-3-execution-of-network-configurations)
-    - [Lifecycle & Ordering](#lifecycle--ordering)
+    - [Lifecycle \& Ordering](#lifecycle--ordering)
     - [Attachment Parameters](#attachment-parameters)
     - [Adding an attachment](#adding-an-attachment)
     - [Deleting an attachment](#deleting-an-attachment)
@@ -310,6 +311,30 @@ Optional environment parameters:
 
 All parameters, with the exception of `CNI_PATH`, must be the same as the corresponding `ADD` for this container.
 
+
+#### `STATUS`: Check plugin status
+`STATUS` is a way for a runtime to determine the readiness of a network plugin.
+
+A plugin must exit with a zero (success) return code if the plugin is ready to service ADD requests. If the plugin is not able to service ADD requests, it must exit with a non-zero return code and output an error on standard out (see below).
+
+The following error codes are defined in the context of `STATUS`:
+
+- 50: The plugin is not available (i.e. cannot service `ADD` requests)
+- 51: The plugin is not available, and existing containers in the network may have limited connectivity.
+
+Plugin considerations:
+- Status is purely informational. A plugin MUST NOT rely on `STATUS` being called.
+- Plugins should always expect other CNI operations (like `ADD`, `DEL`, etc) even if `STATUS` returns an error.`STATUS` does not prevent other runtime requests.
+- If a plugin relies on a delegated plugin (e.g. IPAM) to service `ADD` requests, it must also execute a `STATUS` request to that plugin. If the delegated plugin return an error result, the executing plugin should return an error result.
+
+**Input:**
+
+The runtime will provide a json-serialized plugin configuration object (defined below) on standard in.
+
+Optional environment parameters:
+- `CNI_PATH`
+
+
 #### `VERSION`: probe plugin version support
 The plugin should output via standard-out a json-serialized version result object (see below).