SPEC: add wording for GC verb

GC, or garbage collection, is intended as a way for runtimes to tell
plugins about valid attachments, enabling them to delete any leaked or
stale resources.

Signed-off-by: Casey Callendrello <[email protected]>

SPEC.md

@@ -17,12 +17,14 @@
       - [`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)
       - [`VERSION`: probe plugin version support](#version-probe-plugin-version-support)
+      - [`GC`: Clean up any stale resources](#gc-clean-up-any-stale-resources)
   - [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)
     - [Checking an attachment](#checking-an-attachment)
+    - [Garbage-collecting a network](#garbage-collecting-a-network)
     - [Deriving execution configuration from plugin configuration](#deriving-execution-configuration-from-plugin-configuration)
       - [Deriving `runtimeConfig`](#deriving-runtimeconfig)
   - [Section 4: Plugin Delegation](#section-4-plugin-delegation)
@@ -202,7 +204,7 @@ The runtime must execute the plugin in the runtime's networking domain. (For mos
 
 Protocol parameters are passed to the plugins via OS environment variables.
 
-- `CNI_COMMAND`: indicates the desired operation; `ADD`, `DEL`, `CHECK`, or `VERSION`.
+- `CNI_COMMAND`: indicates the desired operation; `ADD`, `DEL`, `CHECK`, `GC`, or `VERSION`.
 - `CNI_CONTAINERID`: Container ID. A unique plaintext identifier for a container, allocated by the runtime. Must not be empty.  Must start with an alphanumeric character, optionally followed by any combination of one or more alphanumeric characters, underscore (), dot (.) or hyphen (-).
 - `CNI_NETNS`: A reference to the container's "isolation domain". If using network namespaces, then a path to the network namespace (e.g. `/run/netns/[nsname]`)
 - `CNI_IFNAME`: Name of the interface to create inside the container; if the plugin is unable to use this interface name it must return an error.
@@ -214,7 +216,7 @@ A plugin must exit with a return code of 0 on success, and non-zero on failure.
 
 ### CNI operations
 
-CNI defines 4 operations: `ADD`, `DEL`, `CHECK`, and `VERSION`. These are passed to the plugin via the `CNI_COMMAND` environment variable.
+CNI defines 5 operations: `ADD`, `DEL`, `CHECK`, `GC`, and `VERSION`. These are passed to the plugin via the `CNI_COMMAND` environment variable.
 
 #### `ADD`: Add container to network, or apply modifications
 
@@ -321,6 +323,38 @@ A json-serialized object, with the following key:
 Required environment parameters:
 - `CNI_COMMAND`
 
+#### `GC`: Clean up any stale resources
+
+The GC comand provides a way for runtimes to specify the expected set of attachments to a network.
+The network plugin may then remove any resources related to attachments that do not exist in this set.
+
+Resources may, for example, include:
+- IPAM reservations
+- Firewall rules
+
+A plugin SHOULD remove as many stale resources as possible. For example, a plugin should remove any IPAM reservations associated with attachments not in the provided list. The plugin MAY assume that the isolation domain (e.g. network namespace) has been deleted, and thus any resources (e.g. network interfaces) therein have been removed.
+
+Plugins should generally complete a `GC` action without error. If an error is encountered, a plugin should continue; removing as many resources as possible, and report the errors back to the runtime.
+
+Plugins MUST, additionally, forward any GC calls to delegated plugins they are configured to use (see section 4).
+
+The runtime MUST NOT use GC as a substitute for DEL. Plugins may be unable to clean up some resources from GC that they would have been able to clean up from DEL.
+
+**Input:**
+
+The runtime must provide a JSON-serialized plugin configuration object (defined below) on standard in. It contains an additional key;
+
+- `cni.dev/attachments` (array of objects): The list of **still valid** attachments to this network:
+    - `containerID` (string): the value of CNI_CONTAINERID as provided during the CNI ADD operation
+    - `ifname` (string): the value of CNI_IFNAME as provided during the CNI ADD operation
+
+Required environment parameters:
+- `CNI_COMMAND`
+- `CNI_PATH`
+
+**Output:**
+No output on success, ["error" result structure](#Error) on error.
+
 
 ## Section 3: Execution of Network Configurations
 
@@ -332,6 +366,7 @@ The operation of a network configuration on a container is called an _attachment
 
 - The container runtime must create a new network namespace for the container before invoking any plugins.
 - The container runtime must not invoke parallel operations for the same container, but is allowed to invoke parallel operations for different containers. This includes across multiple attachments.
+  - **Exception**: The runtime must exclusively execute either _gc_ or _add_ and _delete_. The runtime must ensure that no _add_ or _delete_ operations are in progress before executing _gc_, and must wait for _gc_ to complete before issuing new _add_ or _delete_ commands.
 - Plugins must handle being executed concurrently across different containers. If necessary, they must implement locking on shared resources (e.g. IPAM databases).
 - The container runtime must ensure that _add_ is eventually followed by a corresponding _delete_. The only exception is in the event of catastrophic failure, such as node loss. A _delete_ must still be executed even if the _add_ fails.
 - _delete_ may be followed by additional _deletes_.
@@ -389,6 +424,21 @@ For every plugin defined in the `plugins` key of the network configuration,
 
 If all plugins return success, return success to the caller.
 
+### Garbage-collecting a network
+The runtime may also ask every plugin in a network to clean up any stale resources.
+
+Garbage collection is similar to del with two exceptions:
+- There are no attachment parameters (e.g. capability args, CNI_ARGS, etc.)
+- `prevResult` is not supplied
+
+For every plugin defined in the `plugins` key of the network configuration,
+1. Look up the executable specified in the `type` field. If this does not exist, then this is an error.
+2. Derive request configuration from the plugin configuration.
+3. Execute the plugin binary, with `CNI_COMMAND=GC`. Supply the derived configuration via standard in.
+4. If the plugin returns an error, **continue** with execution, returning all errors to the caller.
+
+If all plugins return success, return success to the caller.
+
 ### Deriving execution configuration from plugin configuration
 The network configuration format (which is a list of plugin configurations to execute) must be transformed to a format understood by the plugin (which is a single plugin configuration). This section describes that transformation.