Initial hotplug support (#936)

Adds a udev script which will invoke a hotplug hook script on all net
add events. The script will write some udev arguments to a systemd FIFO
socket (to ensure we have only instance of cloud-init running at a
time), which is then read by a new service that calls a new 'cloud-init
devel hotplug-hook' command to handle the new event.

This hotplug-hook command will:
- Fetch the pickled datsource
- Verify that the hotplug event is supported/enabled
- Update the metadata for the datasource
- Ensure the hotplugged device exists within the datasource
- Apply the config change on the datasource metadata
- Bring up the new interface (or apply global network configuration)
- Save the updated metadata back to the pickle cache

Also scattered in some unrelated typing where helpful

2 files changed, 12 insertions, 2 deletions

diff --git a/doc/rtd/topics/cli.rst b/doc/rtd/topics/cli.rst
index 0ff230b5..b6115ed6 100644
--- a/doc/rtd/topics/cli.rst
+++ b/doc/rtd/topics/cli.rst
@@ -119,6 +119,10 @@ Current subcommands:
    schema errors locally without the need for deployment. Schema
    validation is work in progress and supports a subset of cloud-config
    modules.
+ * ``hotplug-hook``: respond to newly added system devices by retrieving
+   updated system metadata and bringing up/down the corresponding device.
+   This command is intended to be called via a systemd service and is
+   not considered user-accessible except for debugging purposes.
 
 
 .. _cli_features:
diff --git a/doc/rtd/topics/events.rst b/doc/rtd/topics/events.rst
index 463208cc..984e7577 100644
--- a/doc/rtd/topics/events.rst
+++ b/doc/rtd/topics/events.rst
@@ -20,11 +20,11 @@ event types:
   boot: once during Local stage, then again in Network stage. As this behavior
   was previously the default behavior, this option exists to prevent regressing
   such behavior.
+- **HOTPLUG**: Dynamic add of a system device
 
 Future work will likely include infrastructure and support for the following
 events:
 
-- **HOTPLUG**: Dynamic add of a system device
 - **METADATA_CHANGE**: An instance's metadata has change
 - **USER_REQUEST**: Directed request to update
 
@@ -64,6 +64,12 @@ arbitrary values can be used.
 Each ``scope`` requires a ``when`` element to specify which events
 are to allowed to be handled.
 
+Hotplug
+=======
+When the hotplug event is supported by the data source and configured in
+user data, cloud-init will respond to the addition or removal of network
+interfaces to the system. In addition to fetching and updating the system
+metadata, cloud-init will also bring up/down the newly added interface.
 
 Examples
 ========
@@ -77,7 +83,7 @@ On every boot, apply network configuration found in the datasource.
  # apply network config on every boot
  updates:
    network:
-     when: ['boot']
+     when: ['boot', 'hotplug']
 
 .. _Cloud-init: https://launchpad.net/cloud-init
 .. vi: textwidth=78