x/cloud-init
Code Issues Proposed changes

doc improvements

Browse Source
This commit is contained in:
Scott Moser
2014-01-17 13:09:31 -05:00
parent 38320ca757
commit adabfc3c50
1 changed files with 32 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
doc/vendordata.txt
View File

@@ -1,88 +1,48 @@
=== Overview === === Overview ===
Vendordata is data provided by the entity that launches an instance. Vendordata is data provided by the entity that launches an instance
The cloud provider makes this data available to the instance via in one (for example, the cloud provider). This data can be used to
way or another. 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 Vendordata follows the same rules as user-data, with the following
caveauts: caveats:
1. Users have ultimate control over vendordata 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 2. By default it only runs on first boot
3. Vendordata runs at the users pleasure. If the use of 3. Vendordata can be disabled by the user. If the use of vendordata is
vendordata is required for the instance to run, then required for the instance to run, then vendordata should not be
vendordata should not be used. used.
4. Most vendor operations should be done either via script, 4. user supplied cloud-config is merged over cloud-config from
boot_hook or upstart job. vendordata.
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.
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 Further, we strongly advise vendors to not 'be evil'. By evil, we
mean any action that could compromise a system. Since users trust mean any action that could compromise a system. Since users trust
you, please take care to make sure that any vendordata is safe, you, please take care to make sure that any vendordata is safe,
atomic, idempotent and does not put your users at risk. 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 === === Input Formats ===
cloud-init will download and cache to filesystem any vendor-data that it cloud-init will download and cache to filesystem any vendor-data that it
finds. However, certain types of vendor-data are handled specially. 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.
* Gzip Compressed Content The only differences are:
content found to be gzip compressed will be uncompressed, and * user-scripts are stored in a different location than user-scripts (to
these rules applied to the uncompressed data avoid namespace collision)
* user can disable part handlers by cloud-config settings.
* Mime Multi Part archive For example, to disable handling of 'part-handlers' in vendor-data,
This list of rules is applied to each part of this multi-part file the user could provide user-data like this:
Using a mime-multi part file, the user can specify more than one #cloud-config
type of data. For example, both a user data script and a vendordata: {excluded: 'text/part-handler'}
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'
=== Examples === === Examples ===
There are examples in the examples subdirectory. There are examples in the examples subdirectory.