diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/examples/cloud-config-datasources.txt | 12 | ||||
| -rw-r--r-- | doc/examples/cloud-config-disk-setup.txt | 251 | ||||
| -rw-r--r-- | doc/examples/cloud-config-growpart.txt | 9 | ||||
| -rw-r--r-- | doc/examples/cloud-config-power-state.txt | 11 | ||||
| -rw-r--r-- | doc/examples/cloud-config-user-groups.txt | 4 | ||||
| -rw-r--r-- | doc/examples/cloud-config.txt | 6 | ||||
| -rw-r--r-- | doc/rtd/topics/datasources.rst | 6 | ||||
| -rw-r--r-- | doc/sources/opennebula/README.rst | 142 | ||||
| -rw-r--r-- | doc/sources/smartos/README.rst | 93 |
9 files changed, 528 insertions, 6 deletions
diff --git a/doc/examples/cloud-config-datasources.txt b/doc/examples/cloud-config-datasources.txt index 6544448e..65a3cdf5 100644 --- a/doc/examples/cloud-config-datasources.txt +++ b/doc/examples/cloud-config-datasources.txt @@ -55,5 +55,13 @@ datasource: # Smart OS datasource works over a serial console interacting with # a server on the other end. By default, the second serial console is the # device. SmartOS also uses a serial timeout of 60 seconds. - serial device: /dev/ttyS1 - serial timeout: 60 + serial_device: /dev/ttyS1 + serial_timeout: 60 + + # a list of keys that will not be base64 decoded even if base64_all + no_base64_decode: ['root_authorized_keys', 'motd_sys_info', + 'iptables_disable'] + # a plaintext, comma delimited list of keys whose values are b64 encoded + base64_keys: [] + # a boolean indicating that all keys not in 'no_base64_decode' are encoded + base64_all: False diff --git a/doc/examples/cloud-config-disk-setup.txt b/doc/examples/cloud-config-disk-setup.txt new file mode 100644 index 00000000..6ad61c33 --- /dev/null +++ b/doc/examples/cloud-config-disk-setup.txt @@ -0,0 +1,251 @@ +Cloud-init supports the creation of simple partition tables and file systems +on devices. + +Default disk definitions for AWS +-------------------------------- +(Not implemented yet, but provided for future documentation) + + disk_setup: + ephmeral0: + type: 'mbr' + layout: True + overwrite: False + + fs_setup: + - label: None, + filesystem: ext3 + device: ephemeral0 + partition: auto + +Default disk definitions for Windows Azure +------------------------------------------ + +device_aliases: {'ephemeral0': '/dev/sdb'} +disk_setup: + ephemeral0: + type: mbr + layout: True + overwrite: False + +fs_setup: + - label: ephemeral0 + filesystem: ext4 + device: ephemeral0.1 + replace_fs: ntfs + + +Default disk definitions for SmartOS +------------------------------------ + +device_aliases: {'ephemeral0': '/dev/sdb'} +disk_setup: + ephemeral0: + type: mbr + layout: False + overwrite: False + +fs_setup: + - label: ephemeral0 + filesystem: ext3 + device: ephemeral0.0 + +Cavaut for SmartOS: if ephemeral disk is not defined, then the disk will + not be automatically added to the mounts. + + +The default definition is used to make sure that the ephemeral storage is +setup properly. + +"disk_setup": disk partitioning +-------------------------------- + +The disk_setup directive instructs Cloud-init to partition a disk. The format is: + + disk_setup: + ephmeral0: + type: 'mbr' + layout: 'auto' + /dev/xvdh: + type: 'mbr' + layout: + - 33 + - [33, 82] + - 33 + overwrite: True + +The format is a list of dicts of dicts. The first value is the name of the +device and the subsequent values define how to create and layout the partition. + +The general format is: + disk_setup: + <DEVICE>: + type: 'mbr' + layout: <LAYOUT|BOOL> + overwrite: <BOOL> + +Where: + <DEVICE>: The name of the device. 'ephemeralX' and 'swap' are special + values which are specific to the cloud. For these devices + Cloud-init will look up what the real devices is and then + use it. + + For other devices, the kernel device name is used. At this + time only simply kernel devices are supported, meaning + that device mapper and other targets may not work. + + Note: At this time, there is no handling or setup of + device mapper targets. + + type=<TYPE>: Currently the following are supported: + 'mbr': default and setups a MS-DOS partition table + + Note: At this time only 'mbr' partition tables are allowed. + It is anticipated in the future that we'll have GPT as + option in the future, or even "RAID" to create a mdadm + RAID. + + layout={...}: The device layout. This is a list of values, with the + percentage of disk that partition will take. + Valid options are: + [<SIZE>, [<SIZE>, <PART_TYPE]] + + Where <SIZE> is the _percentage_ of the disk to use, while + <PART_TYPE> is the numerical value of the partition type. + + The following setups two partitions, with the first + partition having a swap label, taking 1/3 of the disk space + and the remainder being used as the second partition. + /dev/xvdh': + type: 'mbr' + layout: + - [33,82] + - 66 + overwrite: True + + When layout is "true" it means single partition the entire + device. + + When layout is "false" it means don't partition or ignore + existing partitioning. + + If layout is set to "true" and overwrite is set to "false", + it will skip partitioning the device without a failure. + + overwrite=<BOOL>: This describes whether to ride with saftey's on and + everything holstered. + + 'false' is the default, which means that: + 1. The device will be checked for a partition table + 2. The device will be checked for a file system + 3. If either a partition of file system is found, then + the operation will be _skipped_. + + 'true' is cowboy mode. There are no checks and things are + done blindly. USE with caution, you can do things you + really, really don't want to do. + + +fs_setup: Setup the file system +------------------------------- + +fs_setup describes the how the file systems are supposed to look. + + fs_setup: + - label: ephemeral0 + filesystem: 'ext3' + device: 'ephemeral0' + partition: 'auto' + - label: mylabl2 + filesystem: 'ext4' + device: '/dev/xvda1' + - special: + cmd: mkfs -t %(FILESYSTEM)s -L %(LABEL)s %(DEVICE)s + filesystem: 'btrfs' + device: '/dev/xvdh' + +The general format is: + fs_setup: + - label: <LABEL> + filesystem: <FS_TYPE> + device: <DEVICE> + partition: <PART_VALUE> + overwrite: <OVERWRITE> + replace_fs: <FS_TYPE> + +Where: + <LABEL>: The file system label to be used. If set to None, no label is + used. + + <FS_TYPE>: The file system type. It is assumed that the there + will be a "mkfs.<FS_TYPE>" that behaves likes "mkfs". On a standard + Ubuntu Cloud Image, this means that you have the option of ext{2,3,4}, + and vfat by default. + + <DEVICE>: The device name. Special names of 'ephemeralX' or 'swap' + are allowed and the actual device is acquired from the cloud datasource. + When using 'ephemeralX' (i.e. ephemeral0), make sure to leave the + label as 'ephemeralX' otherwise there may be issues with the mounting + of the ephemeral storage layer. + + If you define the device as 'ephemeralX.Y' then Y will be interpetted + as a partition value. However, ephermalX.0 is the _same_ as ephemeralX. + + <PART_VALUE>: + Partition definitions are overwriten if you use the '<DEVICE>.Y' notation. + + The valid options are: + "auto|any": tell cloud-init not to care whether there is a partition + or not. Auto will use the first partition that does not contain a + file system already. In the absence of a partition table, it will + put it directly on the disk. + + "auto": If a file system that matches the specification in terms of + label, type and device, then cloud-init will skip the creation of + the file system. + + "any": If a file system that matches the file system type and device, + then cloud-init will skip the creation of the file system. + + Devices are selected based on first-detected, starting with partitions + and then the raw disk. Consider the following: + NAME FSTYPE LABEL + xvdb + |-xvdb1 ext4 + |-xvdb2 + |-xvdb3 btrfs test + \-xvdb4 ext4 test + + If you ask for 'auto', label of 'test, and file system of 'ext4' + then cloud-init will select the 2nd partition, even though there + is a partition match at the 4th partition. + + If you ask for 'any' and a label of 'test', then cloud-init will + select the 1st partition. + + If you ask for 'auto' and don't define label, then cloud-init will + select the 1st partition. + + In general, if you have a specific partition configuration in mind, + you should define either the device or the partition number. 'auto' + and 'any' are specifically intended for formating ephemeral storage or + for simple schemes. + + "none": Put the file system directly on the device. + + <NUM>: where NUM is the actual partition number. + + <OVERWRITE>: Defines whether or not to overwrite any existing + filesystem. + + "true": Indiscriminately destroy any pre-existing file system. Use at + your own peril. + + "false": If an existing file system exists, skip the creation. + + <REPLACE_FS>: This is a special directive, used for Windows Azure that + instructs cloud-init to replace a file system of <FS_TYPE>. NOTE: + unless you define a label, this requires the use of the 'any' partition + directive. + +Behavior Caveat: The default behavior is to _check_ if the file system exists. + If a file system matches the specification, then the operation is a no-op. diff --git a/doc/examples/cloud-config-growpart.txt b/doc/examples/cloud-config-growpart.txt index 705f02c2..a459573d 100644 --- a/doc/examples/cloud-config-growpart.txt +++ b/doc/examples/cloud-config-growpart.txt @@ -19,6 +19,15 @@ # examples: # devices: [/, /dev/vdb1] # +# ignore_growroot_disabled: +# a boolean, default is false. +# if the file /etc/growroot-disabled exists, then cloud-init will not grow +# the root partition. This is to allow a single file to disable both +# cloud-initramfs-growroot and cloud-init's growroot support. +# +# true indicates that /etc/growroot-disabled should be ignored +# growpart: mode: auto devices: ['/'] + ignore_growroot_disabled: false diff --git a/doc/examples/cloud-config-power-state.txt b/doc/examples/cloud-config-power-state.txt index 59f062d0..8df14366 100644 --- a/doc/examples/cloud-config-power-state.txt +++ b/doc/examples/cloud-config-power-state.txt @@ -12,11 +12,20 @@ # that may go to the console as a result of system services like # syslog being taken down while cloud-init is running. # +# If you delay '+5' (5 minutes) and have a timeout of +# 120 (2 minutes), then the max time until shutdown will be 7 minutes. +# cloud-init will invoke 'shutdown +5' after the process finishes, or +# when 'timeout' seconds have elapsed. +# # delay: form accepted by shutdown. default is 'now'. other format # accepted is +m (m in minutes) # mode: required. must be one of 'poweroff', 'halt', 'reboot' # message: provided as the message argument to 'shutdown'. default is none. +# timeout: the amount of time to give the cloud-init process to finish +# before executing shutdown. +# power_state: - delay: 30 + delay: "+30" mode: poweroff message: Bye Bye + timeout: 30 diff --git a/doc/examples/cloud-config-user-groups.txt b/doc/examples/cloud-config-user-groups.txt index de5f321b..01548380 100644 --- a/doc/examples/cloud-config-user-groups.txt +++ b/doc/examples/cloud-config-user-groups.txt @@ -46,8 +46,8 @@ users: # inactive: Create the user as inactive # passwd: The hash -- not the password itself -- of the password you want # to use for this user. You can generate a safe hash via: -# mkpasswd -m SHA-512 -s 4096 -# (the above command would create a password SHA512 password hash +# mkpasswd --method=SHA-512 --rounds=4096 +# (the above command would create from stdin an SHA-512 password hash # with 4096 salt rounds) # # Please note: while the use of a hashed password is better than diff --git a/doc/examples/cloud-config.txt b/doc/examples/cloud-config.txt index bcfd7917..b35b084d 100644 --- a/doc/examples/cloud-config.txt +++ b/doc/examples/cloud-config.txt @@ -72,6 +72,10 @@ apt_pipelining: False # then apt_mirror above will have no effect apt_preserve_sources_list: true +# 'source' entries in apt-sources that match this python regex +# expression will be passed to add-apt-repository +add_apt_repo_match = "^[\w-]+:\w" + apt_sources: - source: "deb http://ppa.launchpad.net/byobu/ppa/ubuntu karmic main" keyid: F430BBA5 # GPG key ID published on a key server @@ -272,7 +276,7 @@ runcmd: # boothook, but possibly with more friendly. # * bootcmd will run on every boot # * the INSTANCE_ID variable will be set to the current instance id. -# * you can use 'cloud-init-boot-per' command to help only run once +# * you can use 'cloud-init-per' command to help only run once bootcmd: - echo 192.168.1.130 us.archive.ubuntu.com > /etc/hosts - [ cloud-init-per, once, mymkfs, mkfs, /dev/vdb ] diff --git a/doc/rtd/topics/datasources.rst b/doc/rtd/topics/datasources.rst index 59c58805..5543ed34 100644 --- a/doc/rtd/topics/datasources.rst +++ b/doc/rtd/topics/datasources.rst @@ -141,6 +141,12 @@ Config Drive .. include:: ../../sources/configdrive/README.rst --------------------------- +OpenNebula +--------------------------- + +.. include:: ../../sources/opennebula/README.rst + +--------------------------- Alt cloud --------------------------- diff --git a/doc/sources/opennebula/README.rst b/doc/sources/opennebula/README.rst new file mode 100644 index 00000000..4d7de27a --- /dev/null +++ b/doc/sources/opennebula/README.rst @@ -0,0 +1,142 @@ +The `OpenNebula`_ (ON) datasource supports the contextualization disk. + + See `contextualization overview`_, `contextualizing VMs`_ and + `network configuration`_ in the public documentation for + more information. + +OpenNebula's virtual machines are contextualized (parametrized) by +CD-ROM image, which contains a shell script *context.sh* with +custom variables defined on virtual machine start. There are no +fixed contextualization variables, but the datasource accepts +many used and recommended across the documentation. + +Datasource configuration +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Datasource accepts following configuration options. + +:: + + dsmode: + values: local, net, disabled + default: net + +Tells if this datasource will be processed in 'local' (pre-networking) or +'net' (post-networking) stage or even completely 'disabled'. + +:: + + parseuser: + default: nobody + +Unprivileged system user used for contextualization script +processing. + +Contextualization disk +~~~~~~~~~~~~~~~~~~~~~~ + +The following criteria are required: + +1. Must be formatted with `iso9660`_ filesystem + or have a *filesystem* label of **CONTEXT** or **CDROM** +2. Must contain file *context.sh* with contextualization variables. + File is generated by OpenNebula, it has a KEY='VALUE' format and + can be easily read by bash + +Contextualization variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are no fixed contextualization variables in OpenNebula, no standard. +Following variables were found on various places and revisions of +the OpenNebula documentation. Where multiple similar variables are +specified, only first found is taken. + +:: + + DSMODE + +Datasource mode configuration override. Values: local, net, disabled. + +:: + + DNS + ETH<x>_IP + ETH<x>_NETWORK + ETH<x>_MASK + ETH<x>_GATEWAY + ETH<x>_DOMAIN + ETH<x>_DNS + +Static `network configuration`_. + +:: + + HOSTNAME + +Instance hostname. + +:: + + PUBLIC_IP + IP_PUBLIC + ETH0_IP + +If no hostname has been specified, cloud-init will try to create hostname +from instance's IP address in 'local' dsmode. In 'net' dsmode, cloud-init +tries to resolve one of its IP addresses to get hostname. + +:: + + SSH_KEY + SSH_PUBLIC_KEY + +One or multiple SSH keys (separated by newlines) can be specified. + +:: + + USER_DATA + USERDATA + +cloud-init user data. + +Example configuration +~~~~~~~~~~~~~~~~~~~~~ + +This example cloud-init configuration (*cloud.cfg*) enables +OpenNebula datasource only in 'net' mode. + +:: + + disable_ec2_metadata: True + datasource_list: ['OpenNebula'] + datasource: + OpenNebula: + dsmode: net + parseuser: nobody + +Example VM's context section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + CONTEXT=[ + PUBLIC_IP="$NIC[IP]", + SSH_KEY="$USER[SSH_KEY] + $USER[SSH_KEY1] + $USER[SSH_KEY2] ", + USER_DATA="#cloud-config + # see https://help.ubuntu.com/community/CloudInit + + packages: [] + + mounts: + - [vdc,none,swap,sw,0,0] + runcmd: + - echo 'Instance has been configured by cloud-init.' | wall + " ] + +.. _OpenNebula: http://opennebula.org/ +.. _contextualization overview: http://opennebula.org/documentation:documentation:context_overview +.. _contextualizing VMs: http://opennebula.org/documentation:documentation:cong +.. _network configuration: http://opennebula.org/documentation:documentation:cong#network_configuration +.. _iso9660: https://en.wikipedia.org/wiki/ISO_9660 diff --git a/doc/sources/smartos/README.rst b/doc/sources/smartos/README.rst new file mode 100644 index 00000000..8b63e520 --- /dev/null +++ b/doc/sources/smartos/README.rst @@ -0,0 +1,93 @@ +================== +SmartOS Datasource +================== + +This datasource finds metadata and user-data from the SmartOS virtualization +platform (i.e. Joyent). + +Please see http://smartos.org/ for information about SmartOS. + +SmartOS Platform +---------------- +The SmartOS virtualization platform uses meta-data to the instance via the +second serial console. On Linux, this is /dev/ttyS1. The data is a provided +via a simple protocol: something queries for the data, the console responds +responds with the status and if "SUCCESS" returns until a single ".\n". + +New versions of the SmartOS tooling will include support for base64 encoded data. + +Userdata +-------- + +In SmartOS parlance, user-data is a actually meta-data. This userdata can be +provided as key-value pairs. + +Cloud-init supports reading the traditional meta-data fields supported by the +SmartOS tools. These are: + * root_authorized_keys + * hostname + * enable_motd_sys_info + * iptables_disable + +Note: At this time iptables_disable and enable_motd_sys_info are read but + are not actioned. + +user-script +----------- + +SmartOS traditionally supports sending over a user-script for execution at the +rc.local level. Cloud-init supports running user-scripts as if they were +cloud-init user-data. In this sense, anything with a shell interpreter +directive will run. + +user-data and user-script +------------------------- + +In the event that a user defines the meta-data key of "user-data" it will +always supersede any user-script data. This is for consistency. + +base64 +------ + +The following are exempt from base64 encoding, owing to the fact that they +are provided by SmartOS: + * root_authorized_keys + * enable_motd_sys_info + * iptables_disable + +This list can be changed through system config of variable 'no_base64_decode'. + +This means that user-script and user-data as well as other values can be +base64 encoded. Since Cloud-init can only guess as to whether or not something +is truly base64 encoded, the following meta-data keys are hints as to whether +or not to base64 decode something: + * base64_all: Except for excluded keys, attempt to base64 decode + the values. If the value fails to decode properly, it will be + returned in its text + * base64_keys: A comma deliminated list of which keys are base64 encoded. + * b64-<key>: + for any key, if there exists an entry in the metadata for 'b64-<key>' + Then 'b64-<key>' is expected to be a plaintext boolean indicating whether + or not its value is encoded. + * no_base64_decode: This is a configuration setting + (i.e. /etc/cloud/cloud.cfg.d) that sets which values should not be + base64 decoded. + +disk_aliases and ephemeral disk: +--------------- +By default, SmartOS only supports a single ephemeral disk. That disk is +completely empty (un-partitioned with no filesystem). + +The SmartOS datasource has built-in cloud-config which instructs the +'disk_setup' module to partition and format the ephemeral disk. + +You can control the disk_setup then in 2 ways: + 1. through the datasource config, you can change the 'alias' of + ephermeral0 to reference another device. The default is: + 'disk_aliases': {'ephemeral0': '/dev/vdb'}, + Which means anywhere disk_setup sees a device named 'ephemeral0' + then /dev/vdb will be substituted. + 2. you can provide disk_setup or fs_setup data in user-data to overwrite + the datasource's built-in values. + +See doc/examples/cloud-config-disk-setup.txt for information on disk_setup. |