Add initial docs about datasources.

Start moving the current README for
datasources to a RST format and include
those files in the rtd site.

LP: #1113650

2 files changed, 123 insertions, 118 deletions

diff --git a/doc/sources/configdrive/README b/doc/sources/configdrive/README
deleted file mode 100644
index ed9033c9..00000000
--- a/doc/sources/configdrive/README
+++ /dev/null
@@ -1,118 +0,0 @@
-The 'ConfigDrive' DataSource supports the OpenStack configdrive disk.
-See doc/source/api_ext/ext_config_drive.rst in the nova source code for
-more information on config drive.
-
-The following criteria are required to be identified by
-DataSourceConfigDrive as a config drive:
- * must be formated with vfat filesystem
- * must be a un-partitioned block device (/dev/vdb, not /dev/vdb1)
- * must contain one of the following files:
-    * etc/network/interfaces
-    * root/.ssh/authorized_keys
-    * meta.js
-
-By default, cloud-init does not consider this source to be a full-fledged
-datasource.  Instead, the default behavior is to assume it is really only
-present to provide networking information.  Cloud-init will copy off the
-network information, apply it to the system, and then continue on.  The
-"full" datasource would then be found in the EC2 metadata service.
-
-== Content of config-drive ==
-  * etc/network/interfaces
-    This file is laid down by nova in order to pass static networking
-    information to the guest.  Cloud-init will copy it off of the config-drive
-    and into /etc/network/interfaces as soon as it can, and then attempt to
-    bring up all network interfaces.
-
-  * root/.ssh/authorized_keys
-    This file is laid down by nova, and contains the keys that were
-    provided to it on instance creation (nova-boot --key ....)
-
-    Cloud-init will copy those keys and put them into the configured user
-    ('ubuntu') .ssh/authorized_keys.
-
-  * meta.js
-    meta.js is populated on the config-drive in response to the user passing
-    "meta flags" (nova boot --meta key=value ...).  It is expected to be json
-    formated.
-
-== Configuration ==
-Cloud-init's behavior can be modified by keys found in the meta.js file in
-the following ways:
- * dsmode:  
-   values: local, net, pass
-   default: pass
-
-   This is what indicates if configdrive is a final data source or not.
-   By default it is 'pass', meaning this datasource should not be read.
-   Set it to 'local' or 'net' to stop cloud-init from continuing on to
-   search for other data sources after network config.
-
-   The difference between 'local' and 'net' is that local will not require
-   networking to be up before user-data actions (or boothooks) are run.
-   
- * instance-id:
-   default: iid-dsconfigdrive
-   This is utilized as the metadata's instance-id.  It should generally
-   be unique, as it is what is used to determine "is this a new instance".
-
- * public-keys:
-   default: None
-   if present, these keys will be used as the public keys for the
-   instance.  This value overrides the content in authorized_keys.
-   Note: it is likely preferable to provide keys via user-data
-
- * user-data:
-   default: None
-   This provides cloud-init user-data.  See other documentation for what
-   all can be present here.
-
-== Example ==
-Here is an example using the nova client (python-novaclien)
-
-Assuming the following variables set up:
- * img_id : set to the nova image id (uuid from image-list)
- * flav_id : set to numeric flavor_id (nova flavor-list)
- * keyname : set to name of key for this instance (nova keypair-list)
-
-$ cat my-user-data 
-#!/bin/sh
-echo ==== USER_DATA FROM EC2 MD ==== | tee /ud.log
-
-$ ud_value=$(sed 's,EC2 MD,META KEY,')
-
-## Now, 'ud_value' has same content of my-user-data file, but
-## with the string "USER_DATA FROM META KEY"
-
-## launch an instance with dsmode=pass
-## This will really not use the configdrive for anything as the mode
-## for the datasource is 'pass', meaning it will still expect some
-## other data source (DataSourceEc2).
-
-$ nova boot --image=$img_id --config-drive=1 --flavor=$flav_id \
-   --key_name=$keyname \
-   --user_data=my-user-data \
-   "--meta=instance-id=iid-001 \
-   "--meta=user-data=${ud_keyval}" \
-   "--meta=dsmode=pass" cfgdrive-dsmode-pass
-
-$ euca-get-console-output i-0000001 | grep USER_DATA
-echo ==== USER_DATA FROM EC2 MD ==== | tee /ud.log
-
-## Now, launch an instance with dsmode=local
-## This time, the only metadata and userdata available to cloud-init
-## are on the config-drive
-$ nova boot --image=$img_id --config-drive=1 --flavor=$flav_id \
-   --key_name=$keyname \
-   --user_data=my-user-data \
-   "--meta=instance-id=iid-001 \
-   "--meta=user-data=${ud_keyval}" \
-   "--meta=dsmode=local" cfgdrive-dsmode-local
-
-$ euca-get-console-output i-0000002 | grep USER_DATA
-echo ==== USER_DATA FROM META KEY ==== | tee /ud.log
-
---
-[1] https://github.com/openstack/nova/blob/master/doc/source/api_ext/ext_config_drive.rst for more if
-
-
diff --git a/doc/sources/configdrive/README.rst b/doc/sources/configdrive/README.rst
new file mode 100644
index 00000000..797872ad
--- /dev/null
+++ b/doc/sources/configdrive/README.rst
@@ -0,0 +1,123 @@
+The configuration drive datasource supports the `OpenStack`_ configuration drive disk.
+
+  See `the config drive extension`_ and `introduction`_ in the public
+  documentation for more information.
+
+By default, cloud-init does *always* consider this source to be a full-fledged
+datasource.  Instead, the typical behavior is to assume it is really only
+present to provide networking information.  Cloud-init will copy off the
+network information, apply it to the system, and then continue on.  The
+"full" datasource could then be found in the EC2 metadata service. If this is
+not the case then the files contained on the located drive must provide equivalents
+to what the EC2 metadata service would provide (which is typical of the version
+2 support listed below)
+
+Version 1
+~~~~~~~~~
+
+The following criteria are required to as a config drive:
+
+1. Must be formatted with `vfat`_ filesystem
+2. Must be a un-partitioned block device (/dev/vdb, not /dev/vdb1)
+3. Must contain *one* of the following files
+
+::
+
+  /etc/network/interfaces
+  /root/.ssh/authorized_keys
+  /meta.js
+
+``/etc/network/interfaces``
+
+    This file is laid down by nova in order to pass static networking
+    information to the guest.  Cloud-init will copy it off of the config-drive
+    and into /etc/network/interfaces (or convert it to RH format) as soon as it can,
+    and then attempt to bring up all network interfaces.
+
+``/root/.ssh/authorized_keys``
+
+    This file is laid down by nova, and contains the ssk keys that were
+    provided to nova on instance creation (nova-boot --key ....)
+
+``/meta.js``
+
+    meta.js is populated on the config-drive in response to the user passing
+    "meta flags" (nova boot --meta key=value ...). It is expected to be json
+    formatted.
+
+Version 2
+~~~~~~~~~~~
+
+The following criteria are required to as a config drive:
+
+1. Must be formatted with `vfat`_ or `iso9660`_ filesystem
+   or have a *filesystem* label of **config-2**
+2. Must be a un-partitioned block device (/dev/vdb, not /dev/vdb1)
+3. The files that will typically be present in the config drive are:
+
+::
+
+  openstack/
+    - 2012-08-10/ or latest/ 
+      - meta_data.json
+      - user_data (not mandatory)
+    - content/
+      - 0000 (referenced content files)
+      - 0001
+      - ....
+  ec2
+    - latest/
+      - meta-data.json (not mandatory)
+
+Keys and values
+~~~~~~~~~~~
+
+Cloud-init's behavior can be modified by keys found in the meta.js (version 1 only) file in the following ways.
+
+::
+
+   dsmode:  
+     values: local, net, pass
+     default: pass
+
+
+This is what indicates if configdrive is a final data source or not.
+By default it is 'pass', meaning this datasource should not be read.
+Set it to 'local' or 'net' to stop cloud-init from continuing on to
+search for other data sources after network config.
+
+The difference between 'local' and 'net' is that local will not require
+networking to be up before user-data actions (or boothooks) are run.
+
+::
+    
+   instance-id:
+     default: iid-dsconfigdrive
+     
+This is utilized as the metadata's instance-id.  It should generally
+be unique, as it is what is used to determine "is this a new instance".
+
+::
+
+   public-keys:
+     default: None
+  
+If present, these keys will be used as the public keys for the
+instance.  This value overrides the content in authorized_keys.
+
+Note: it is likely preferable to provide keys via user-data
+
+::
+    
+   user-data:
+     default: None
+     
+This provides cloud-init user-data. See :ref:`examples <yaml_examples>` for 
+what all can be present here.
+
+.. _OpenStack: http://www.openstack.org/
+.. _introduction: http://docs.openstack.org/trunk/openstack-compute/admin/content/config-drive.html
+.. _python-novaclient: https://github.com/openstack/python-novaclient
+.. _iso9660: https://en.wikipedia.org/wiki/ISO_9660
+.. _vfat: https://en.wikipedia.org/wiki/File_Allocation_Table
+.. _the config drive extension: http://docs.openstack.org/developer/nova/api_ext/ext_config_drive.html