Add feature flags to cloudinit.version.

This exposes a mechanism for users of cloud-init to determine if
a version has a specific feature, and adds documentation to that affect.
We list an existing feature NETWORK_CONFIG_V1 as an example.

Also add a 'features' subcommand for listing these to stdout.

1 files changed, 23 insertions, 0 deletions

diff --git a/doc/rtd/topics/capabilities.rst b/doc/rtd/topics/capabilities.rst
index be0802c5..4a411083 100644
--- a/doc/rtd/topics/capabilities.rst
+++ b/doc/rtd/topics/capabilities.rst
@@ -7,6 +7,7 @@ Capabilities
 - Generating instance ssh private keys
 - Adding ssh keys to a users ``.ssh/authorized_keys`` so they can log in
 - Setting up ephemeral mount points
+- Configuring network devices
 
 User configurability
 ====================
@@ -22,5 +23,27 @@ ec2-run-instances for example.
   string or `user-data` file for usage by cloud-init on instance creation.
 
 
+Feature detection
+=================
+
+Newer versions of cloud-init may have a list of additional features that they
+support. This allows other applications to detect what features the installed
+cloud-init supports without having to parse its version number. If present,
+this list of features will be located at ``cloudinit.version.FEATURES``.
+
+When checking if cloud-init supports a feature, in order to not break the
+detection script on older versions of cloud-init without the features list, a
+script similar to the following should be used. Note that this will exit 0 if
+the feature is supported and 1 otherwise::
+
+    import sys
+    from cloudinit import version
+    sys.exit('<FEATURE_NAME>' not in getattr(version, 'FEATURES', []))
+
+Currently defined feature names include:
+
+ - ``NETWORK_CONFIG_V1`` support for v1 networking configuration, see curtin
+   documentation for examples.
+
 .. _Cloud-init: https://launchpad.net/cloud-init
 .. vi: textwidth=78