Document clouds.yaml as the preferred configuration

Configuring clouds is complicated - possibly more so than is sane, but
hey, that's life. Rather than trying to express all of that directly in
nodepool, the preferred way to deal with it is to define a named cloud
in clouds.yaml and then refer to that in nodepool.

Update the documentation to reflect that.

Change-Id: I1e97dc88227c57cd5f718f8c1fabdcfeafd031c1

doc/source/configuration.rst

@@ -270,12 +270,7 @@ provider, the Nodepool image types are also defined (see
 
   providers:
     - name: provider1
-      username: 'username'
-      password: 'password'
-      auth-url: 'http://auth.provider1.example.com/'
-      project-id: 'project'
-      service-type: 'compute'
-      service-name: 'compute'
+      cloud: example
       region-name: 'region1'
       max-servers: 96
       rate: 1.0
@@ -285,7 +280,6 @@ provider, the Nodepool image types are also defined (see
       launch-timeout: 900
       template-hostname: 'template-{image.name}-{timestamp}'
       pool: 'public'
-      image-type: qcow2
       ipv6-preferred: False
       networks:
         - name: 'some-network-name'
@@ -337,9 +331,24 @@ provider, the Nodepool image types are also defined (see
               key: value
               key2: value
 
-**required**
+**cloud configuration***
 
-  ``name``
+**preferred**
+
+  ``cloud``
+  There are two methods supported for configuring cloud entries. The preferred
+  method is to create an ``~/.config/openstack/clouds.yaml`` file containing
+  your cloud configuration information. Then, use ``cloud`` to refer to a
+  named entry in that file.
+
+  More information about the contents of `clouds.yaml` can be found in
+  `the os-client-config documentation <http://docs.openstack.org/developer/os-client-config/>`_.
+
+**compatablity**
+
+  For backwards compatibility reasons, you can also include
+  portions of the cloud configuration directly in ``nodepool.yaml``. Not all
+  of the options settable via ``clouds.yaml`` are available.
 
   ``username``
 
@@ -352,6 +361,18 @@ provider, the Nodepool image types are also defined (see
   ``auth-url``
     Keystone URL.
 
+  ``image-type``
+    Specifies the image type supported by this provider.  The disk images built
+    by diskimage-builder will output an image for each ``image-type`` specified
+    by a provider using that particular diskimage.
+
+    By default, ``image-type`` is set to the value returned from
+    ``os-client-config`` and can be omitted in most cases.
+
+**required**
+
+  ``name``
+
   ``max-servers``
     Maximum number of servers spawnable on this provider.
 
@@ -381,14 +402,6 @@ provider, the Nodepool image types are also defined (see
 
     In seconds. Default 3600.
 
-  ``image-type``
-    Specifies the image type supported by this provider.  The disk images built
-    by diskimage-builder will output an image for each ``image-type`` specified
-    by a provider using that particular diskimage.
-
-    The default value is ``qcow2``, and values of ``vhd``, ``raw`` are also
-    expected to be valid if you have a sufficiently new diskimage-builder.
-
   ``keypair``
     Default None
 
@@ -408,12 +421,15 @@ provider, the Nodepool image types are also defined (see
     Specify a floating ip pool in cases where the 'public' pool is unavailable
     or undesirable.
 
-  ``api-timeout``
-    Timeout for the Nova client in seconds.
+  ``api-timeout`` (compatability)
+    Timeout for the OpenStack API calls client in seconds. Prefer setting
+    this in `clouds.yaml`
 
-  ``service-type``
+  ``service-type`` (compatability)
+    Prefer setting this in `clouds.yaml`.
 
-  ``service-name``
+  ``service-name`` (compatability)
+    Prefer setting this in `clouds.yaml`.
 
   ``region-name``