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 <c1@caseyc.net>

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,63 @@ A json-serialized object, with the following key:
 Required environment parameters:
 - `CNI_COMMAND`
 
+#### `GC`: Clean up any stale resources
+
+The GC command 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 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`#### `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
 
@@ -389,6 +448,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 add 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.