doc improvements

1 files changed, 34 insertions, 74 deletions

diff --git a/doc/vendordata.txt b/doc/vendordata.txt
index 530e3b4c..9acbe41c 100644
--- a/doc/vendordata.txt
+++ b/doc/vendordata.txt
@@ -1,88 +1,48 @@
 === Overview ===
-Vendordata is data provided by the entity that launches an instance.
-The cloud provider makes this data available to the instance via in one
-way or another.
+Vendordata is data provided by the entity that launches an instance
+(for example, the cloud provider).  This data can be used to
+customize the image to fit into the particular environment it is
+being run in.
 
 Vendordata follows the same rules as user-data, with the following
-caveauts:
-    1. Users have ultimate control over vendordata
+caveats:
+    1. Users have ultimate control over vendordata. They can disable its
+       execution or disable handling of specific parts of multipart input.
     2. By default it only runs on first boot
-    3. Vendordata runs at the users pleasure. If the use of
-        vendordata is required for the instance to run, then
-        vendordata should not be used.
-    4. Most vendor operations should be done either via script,
-        boot_hook or upstart job.
-
-Vendors utilizing the vendordata channel are strongly advised to
-use the #cloud-config-jsonp method, otherwise they risk that a
-user can accidently override choices.
-
+    3. Vendordata can be disabled by the user. If the use of vendordata is
+       required for the instance to run, then vendordata should not be
+       used.
+    4. user supplied cloud-config is merged over cloud-config from
+       vendordata.
+
+Users providing cloud-config data can use the '#cloud-config-jsonp' method
+to more finely control their modifications to the vendor supplied
+cloud-config.  For example, if both vendor and user have provided
+'runcnmd' then the default merge handler will cause the user's runcmd to
+override the one provided by the vendor.  To append to 'runcmd', the user
+could better provide multipart input with a cloud-config-jsonp part like:
+ #cloud-config-jsonp
+ [{ "op": "add", "path": "/runcmd", "value": ["my", "command", "here"]}]
+ 
 Further, we strongly advise vendors to not 'be evil'. By evil, we
 mean any action that could compromise a system. Since users trust
 you, please take care to make sure that any vendordata is safe,
 atomic, idempotent and does not put your users at risk.
 
-cloud-init can read this input and act on it in different ways.
-
 === Input Formats ===
 cloud-init will download and cache to filesystem any vendor-data that it
-finds.  However, certain types of vendor-data are handled specially.
-
- * Gzip Compressed Content
-   content found to be gzip compressed will be uncompressed, and
-   these rules applied to the uncompressed data
-
- * Mime Multi Part archive
-   This list of rules is applied to each part of this multi-part file
-   Using a mime-multi part file, the user can specify more than one
-   type of data.  For example, both a user data script and a
-   cloud-config type could be specified.
-
- * vendor-data Script
-   begins with: #!            or Content-Type: text/x-shellscript
-   script will be executed at "rc.local-like" level during first boot.
-   rc.local-like means "very late in the boot sequence"
-
- * Include File
-   begins with  #include      or Content-Type: text/x-include-url
-   This content is a "include" file.  The file contains a list of
-   urls, one per line.  Each of the URLs will be read, and their content
-   will be passed through this same set of rules.  Ie, the content
-   read from the URL can be gzipped, mime-multi-part, or plain text
-
-* Include File Once
-   begins with  #include-once      or Content-Type: text/x-include-once-url
-   This content is a "include" file.  The file contains a list of
-   urls, one per line.  Each of the URLs will be read, and their content
-   will be passed through this same set of rules.  Ie, the content
-   read from the URL can be gzipped, mime-multi-part, or plain text
-   This file will just be downloaded only once per instance, and its
-   contents cached for subsequent boots.  This allows you to pass in
-   one-time-use or expiring URLs.
-
- * Cloud Config Data
-   begins with  #cloud-config or Content-Type: text/cloud-config
-
-   This content is "cloud-config" data.  See the examples for a
-   commented example of supported config formats.
-
- * Upstart Job
-   begins with  #upstart-job  or Content-Type: text/upstart-job
-
-   Content is placed into a file in /etc/init, and will be consumed
-   by upstart as any other upstart job.
-
- * Cloud Boothook
-   begins with #cloud-boothook or Content-Type: text/cloud-boothook
-
-   This content is "boothook" data.  It is stored in a file under
-   /var/lib/cloud and then executed immediately.
-
-   This is the earliest "hook" available.  Note, that there is no
-   mechanism provided for running only once.  The boothook must take
-   care of this itself.  It is provided with the instance id in the
-   environment variable "INSTANCE_ID".  This could be made use of to
-   provide a 'once-per-instance'
+finds.  Vendordata is handled exactly like user-data.  That means that
+the vendor can supply multipart input and have those parts acted on
+in the same way as user-data.
+
+The only differences are:
+ * user-scripts are stored in a different location than user-scripts (to
+   avoid namespace collision)
+ * user can disable part handlers by cloud-config settings.
+   For example, to disable handling of 'part-handlers' in vendor-data,
+   the user could provide user-data like this:
+    #cloud-config
+    vendordata: {excluded: 'text/part-handler'}
 
 === Examples ===
 There are examples in the examples subdirectory.