merge from trunk

1 files changed, 192 insertions, 0 deletions

diff --git a/doc/rtd/topics/datasources.rst b/doc/rtd/topics/datasources.rst
new file mode 100644
index 00000000..59c58805
--- /dev/null
+++ b/doc/rtd/topics/datasources.rst
@@ -0,0 +1,192 @@
+.. _datasources:
+
+=========
+Datasources
+=========
+----------
+ What is a datasource?
+----------
+
+Datasources are sources of configuration data for cloud-init that typically come
+from the user (aka userdata) or come from the stack that created the configuration
+drive (aka metadata). Typical userdata would include files, yaml, and shell scripts
+while typical metadata would include server name, instance id, display name and other
+cloud specific details. Since there are multiple ways to provide this data (each cloud
+solution seems to prefer its own way) internally a datasource abstract class was
+created to allow for a single way to access the different cloud systems methods 
+to provide this data through the typical usage of subclasses.
+
+The current interface that a datasource object must provide is the following:
+
+.. sourcecode:: python
+    
+    # returns a mime multipart message that contains
+    # all the various fully-expanded components that
+    # were found from processing the raw userdata string
+    # - when filtering only the mime messages targeting
+    #   this instance id will be returned (or messages with
+    #   no instance id)
+    def get_userdata(self, apply_filter=False)
+    
+    # returns the raw userdata string (or none)
+    def get_userdata_raw(self)
+    
+    # returns a integer (or none) which can be used to identify
+    # this instance in a group of instances which are typically
+    # created from a single command, thus allowing programatic
+    # filtering on this launch index (or other selective actions)
+    @property
+    def launch_index(self)
+    
+    # the data sources' config_obj is a cloud-config formated
+    # object that came to it from ways other than cloud-config
+    # because cloud-config content would be handled elsewhere
+    def get_config_obj(self)
+    
+    #returns a list of public ssh keys
+    def get_public_ssh_keys(self)
+    
+    # translates a device 'short' name into the actual physical device
+    # fully qualified name (or none if said physical device is not attached
+    # or does not exist)
+    def device_name_to_device(self, name)
+    
+    # gets the locale string this instance should be applying 
+    # which typically used to adjust the instances locale settings files
+    def get_locale(self)
+    
+    @property
+    def availability_zone(self)
+    
+    # gets the instance id that was assigned to this instance by the 
+    # cloud provider or when said instance id does not exist in the backing
+    # metadata this will return 'iid-datasource'
+    def get_instance_id(self)
+    
+    # gets the fully qualified domain name that this host should  be using
+    # when configuring network or hostname releated settings, typically
+    # assigned either by the cloud provider or the user creating the vm
+    def get_hostname(self, fqdn=False)
+    
+    def get_package_mirror_info(self)
+
+---------------------------
+EC2
+---------------------------
+
+The EC2 datasource is the oldest and most widely used datasource that cloud-init
+supports. This datasource interacts with a *magic* ip that is provided to the 
+instance by the cloud provider. Typically this ip is ``169.254.169.254`` of which
+at this ip a http server is provided to the instance so that the instance can make
+calls to get instance userdata and instance metadata.
+
+Metadata is accessible via the following URL:
+
+::
+    
+    GET http://169.254.169.254/2009-04-04/meta-data/
+    ami-id
+    ami-launch-index
+    ami-manifest-path
+    block-device-mapping/
+    hostname
+    instance-id
+    instance-type
+    local-hostname
+    local-ipv4
+    placement/
+    public-hostname
+    public-ipv4
+    public-keys/
+    reservation-id
+    security-groups
+
+Userdata is accessible via the following URL:
+
+::
+    
+    GET http://169.254.169.254/2009-04-04/user-data
+    1234,fred,reboot,true | 4512,jimbo, | 173,,,
+
+Note that there are multiple versions of this data provided, cloud-init
+by default uses **2009-04-04** but newer versions can be supported with
+relative ease (newer versions have more data exposed, while maintaining
+backward compatibility with the previous versions). 
+
+To see which versions are supported from your cloud provider use the following URL:
+
+::
+    
+    GET http://169.254.169.254/
+    1.0
+    2007-01-19
+    2007-03-01
+    2007-08-29
+    2007-10-10
+    2007-12-15
+    2008-02-01
+    2008-09-01
+    2009-04-04
+    ...
+    latest
+        
+**Note:** internally in cloudinit the `boto`_ library used to fetch the instance
+userdata and instance metadata, feel free to check that library out, it provides
+many other useful EC2 functionality.
+
+---------------------------
+Config Drive
+---------------------------
+
+.. include:: ../../sources/configdrive/README.rst
+
+---------------------------
+Alt cloud
+---------------------------
+
+.. include:: ../../sources/altcloud/README.rst
+
+---------------------------
+No cloud
+---------------------------
+
+.. include:: ../../sources/nocloud/README.rst
+
+---------------------------
+MAAS
+---------------------------
+
+*TODO*
+
+For now see: http://maas.ubuntu.com/
+
+---------------------------
+CloudStack
+---------------------------
+
+*TODO*
+
+---------------------------
+OVF
+---------------------------
+
+*TODO*
+
+For now see: https://bazaar.launchpad.net/~cloud-init-dev/cloud-init/trunk/files/head:/doc/sources/ovf/
+
+---------------------------
+Fallback/None
+---------------------------
+
+This is the fallback datasource when no other datasource can be selected. It is
+the equivalent of a *empty* datasource in that it provides a empty string as userdata
+and a empty dictionary as metadata. It is useful for testing as well as for when
+you do not have a need to have an actual datasource to meet your instance 
+requirements (ie you just want to run modules that are not concerned with any
+external data). It is typically put at the end of the datasource search list
+so that if all other datasources are not matched, then this one will be so that
+the user is not left with an inaccessible instance.
+
+**Note:** the instance id that this datasource provides is ``iid-datasource-none``.
+
+.. _boto: http://docs.pythonboto.org/en/latest/