diff --git a/bootstrapvz/plugins/admin_user/README.rst b/bootstrapvz/plugins/admin_user/README.rst new file mode 100644 index 0000000..3506f92 --- /dev/null +++ b/bootstrapvz/plugins/admin_user/README.rst @@ -0,0 +1,12 @@ +Admin user +---------- + +This plugin creates a user with passwordless sudo privileges. It also +disables the SSH root login. If the EC2 init scripts are installed, the +script for fetching the SSH authorized keys will be adjust to match the +username specified. + +Settings +~~~~~~~~ + +- ``username``: The username of the account to create. *``required``* diff --git a/bootstrapvz/plugins/apt_proxy/README.rst b/bootstrapvz/plugins/apt_proxy/README.rst new file mode 100644 index 0000000..33711a7 --- /dev/null +++ b/bootstrapvz/plugins/apt_proxy/README.rst @@ -0,0 +1,21 @@ +APT Proxy +--------- + +This plugin creates a proxy configuration file for APT, so you could +enjoy the benefits of using cached packages instead of downloading them +from the mirror every time. You could just install ``apt-cacher-ng`` on +the host machine and then add ``"address": "127.0.0.1"`` and +``"port": 3142`` to the manifest file. + +Settings +~~~~~~~~ + +- ``address``: The IP or host of the proxy server. + *``required``* +- ``port``: The port (integer) of the proxy server. + *``required``* +- ``persistent``: Whether the proxy configuration file should remain on + the machine or not. + Valid values: true, false + Default: ``false`` + *``optional``* diff --git a/bootstrapvz/plugins/cloud_init/README.rst b/bootstrapvz/plugins/cloud_init/README.rst new file mode 100644 index 0000000..fa36e1f --- /dev/null +++ b/bootstrapvz/plugins/cloud_init/README.rst @@ -0,0 +1,23 @@ +cloud-init +---------- + +This plugin installs and configures +`cloud-init `__ +on the system. Depending on the release it installs it from either +backports or the main repository. + +cloud-init is only compatible with Debian wheezy and upwards. + +Settings +~~~~~~~~ + +- ``username``: The username of the account to create. + *``required``* +- ``disable_modules``: A list of strings specifying which cloud-init + modules should be disabled. + *``optional``* +- ``metadata_sources``: A string that sets the + `datasources `__ + that cloud-init should try fetching metadata from. The source is + automatically set when using the ec2 provider. + *``optional``* diff --git a/bootstrapvz/plugins/docker_daemon/README.rst b/bootstrapvz/plugins/docker_daemon/README.rst new file mode 100644 index 0000000..e210435 --- /dev/null +++ b/bootstrapvz/plugins/docker_daemon/README.rst @@ -0,0 +1,18 @@ +Docker daemon +------------- + +Install `docker `__ daemon in the image. Uses +init scripts for the official repository. + +This plugin can only be used if the distribution being bootstrapped is +at least ``wheezy``, as Docker needs a kernel version ``3.8`` or higher, +which is available at the ``wheezy-backports`` repository. There's also +an architecture requirement, as it runs only on ``amd64``. + +Settings +~~~~~~~~ + +- ``version``: Selects the docker version to install. To select the + latest version simply omit this setting. + Default: ``latest`` + *``optional``* diff --git a/bootstrapvz/plugins/image_commands/README.rst b/bootstrapvz/plugins/image_commands/README.rst new file mode 100644 index 0000000..106ad22 --- /dev/null +++ b/bootstrapvz/plugins/image_commands/README.rst @@ -0,0 +1,19 @@ +Image commands +-------------- + +The image commands plugin allows you to run arbitrary commands during +the bootstrap process. The commands are run at an indeterminate point +*after* packages have been installed, but *before* the volume has been +unmounted. + +Settings +~~~~~~~~ + +- ``commands``: A list of lists containing strings. Each top-level item + is a single command, while the strings inside each list comprise + parts of a command. This allows for proper shell argument escaping + (to circumvent this, simply put the entire command in a single + string). In addition to the manifest variables ``{root}`` is also + available. It points at the root of the image volume. + *``required``* + *``manifest vars``* diff --git a/bootstrapvz/plugins/minimize_size/README.rst b/bootstrapvz/plugins/minimize_size/README.rst new file mode 100644 index 0000000..e275237 --- /dev/null +++ b/bootstrapvz/plugins/minimize_size/README.rst @@ -0,0 +1,37 @@ +minimize size +------------- + +This plugin can be used to reduce the size of the resulting image. Often +virtual volumes are much smaller than their reported size until any data +is written to them. During the bootstrapping process temporary data like +the aptitude cache is written to the volume only to be removed again. + +The minimize size plugin employs three different strategies to keep a +low volume footprint: + +- Mount folders from the host into key locations of the image volume to + avoid any unneccesary disk writes. +- Use `zerofree `__ to + deallocate unused sectors on the volume. On an unpartitioned volume + this will be done for the entire volume, while it will only happen on + the root partition for partitioned volumes. +- Use + `vmware-vdiskmanager `__ + to shrink the real volume size (only applicable when using vmdk + backing). The tool is part of the `VMWare + Workstation `__ + package. + +Settings +~~~~~~~~ + +- ``zerofree``: Specifies if it should mark unallocated blocks as + zeroes, so the volume could be better shrunk after this. + Valid values: true, false + Default: false + *``optional``* +- ``shrink``: Whether the volume should be shrunk. This setting works + best in conjunction with the zerofree tool. + Valid values: true, false + Default: false + *``optional``* diff --git a/bootstrapvz/plugins/ntp/README.rst b/bootstrapvz/plugins/ntp/README.rst new file mode 100644 index 0000000..40421b1 --- /dev/null +++ b/bootstrapvz/plugins/ntp/README.rst @@ -0,0 +1,12 @@ +NTP +--- + +This plugins installs the Network Time Protocol daemon and optionally +defines which time servers it should use. + +Settings +~~~~~~~~ + +- ``servers``: A list of strings specifying which servers should be + used to synchronize the machine clock. + *``optional``* diff --git a/bootstrapvz/plugins/opennebula/README.md b/bootstrapvz/plugins/opennebula/README.md deleted file mode 100644 index 49ab0c9..0000000 --- a/bootstrapvz/plugins/opennebula/README.md +++ /dev/null @@ -1,13 +0,0 @@ -# Open Nebula provider - -This provider adds OpenNebula contextualization to the virtual image (see http://opennebula.org/documentation:rel4.2:cong). - -It set ups the network and ssh keys. TO do so you should configure your virtual machine context with something like: - - ETH0_DNS $NETWORK[DNS, NETWORK_ID=2] - ETH0_GATEWAY $NETWORK[GATEWAY, NETWORK_ID=2] - ETH0_IP $NIC[IP, NETWORK_ID=2] - ETH0_MASK $NETWORK[MASK, NETWORK_ID=2] - ETH0_NETWORK $NETWORK[NETWORK, NETWORK_ID=2] - FILES path_to_my_ssh_public_key.pub - diff --git a/bootstrapvz/plugins/opennebula/README.rst b/bootstrapvz/plugins/opennebula/README.rst new file mode 100644 index 0000000..a29d7ae --- /dev/null +++ b/bootstrapvz/plugins/opennebula/README.rst @@ -0,0 +1,27 @@ +Open Nebula +----------- + +This plugin adds `OpenNebula +contextualization `__ +to the image, which sets up the network configuration and SSH keys. + +The virtual machine context should be configured as follows: + +:: + + ETH0_DNS $NETWORK[DNS, NETWORK_ID=2] + ETH0_GATEWAY $NETWORK[GATEWAY, NETWORK_ID=2] + ETH0_IP $NIC[IP, NETWORK_ID=2] + ETH0_MASK $NETWORK[MASK, NETWORK_ID=2] + ETH0_NETWORK $NETWORK[NETWORK, NETWORK_ID=2] + FILES path_to_my_ssh_public_key.pub + +The plugin will install all *.pub* files in the root authorized\_keys +file. When using the ec2 provider, the USER\_EC2\_DATA will be executed +if present. + +Settings +~~~~~~~~ + +This plugin has no settings. To enable it add ``"opennebula":{}`` to the +plugin section of the manifest. diff --git a/bootstrapvz/plugins/pip_install/README.rst b/bootstrapvz/plugins/pip_install/README.rst new file mode 100644 index 0000000..3bed629 --- /dev/null +++ b/bootstrapvz/plugins/pip_install/README.rst @@ -0,0 +1,14 @@ +Pip install +----------- + +Install packages from the Python Package Index via pip. + +Installs ``build-essential`` and ``python-dev`` debian packages, so +Python extension modules can be built. + +Settings +~~~~~~~~ + +- ``packages``: Python packages to install, a list of strings. The list + can contain anything that ``pip install`` would accept as an + argument, for example ``awscli==1.3.13``. diff --git a/bootstrapvz/plugins/prebootstrapped/README.rst b/bootstrapvz/plugins/prebootstrapped/README.rst new file mode 100644 index 0000000..bc30de8 --- /dev/null +++ b/bootstrapvz/plugins/prebootstrapped/README.rst @@ -0,0 +1,26 @@ +prebootstrapped +--------------- + +When developing for bootstrap-vz, testing can be quite tedious since the +bootstrapping process can take a while. The prebootstrapped plugin +solves that problem by creating a snapshot of your volume right after +all the software has been installed. The next time bootstrap-vz is run, +the plugin replaces all volume preparation and bootstrapping tasks and +recreates the volume from the snapshot instead. + +The plugin assumes that the users knows what he is doing (e.g. it +doesn't check whether bootstrap-vz is being run with a partitioned +volume configuration, while the snapshot is unpartitioned). + +When no snapshot or image is specified the plugin creates one and +outputs its ID/path. Specifying an ID/path enables the second mode of +operation which recreates the volume from the specified snapshot instead +of creating it from scratch. + +Settings +~~~~~~~~ + +- ``snapshot``: ID of the EBS snapshot to use. This setting only works + with EBS backed EC2 configurations. +- ``image``: Path to the loopbackvolume snapshot. This setting works + with all configurable volume backings except EBS. diff --git a/bootstrapvz/plugins/puppet/README.rst b/bootstrapvz/plugins/puppet/README.rst new file mode 100644 index 0000000..203e0b3 --- /dev/null +++ b/bootstrapvz/plugins/puppet/README.rst @@ -0,0 +1,24 @@ +Puppet +------ + +Installs `puppet `__ and optionally applies a +manifest inside the chroot. You can also have it copy your puppet +configuration into the image so it is readily available once the image +is booted. + +Keep in mind that when applying a manifest, the system is in a chrooted +environment. This can prevent daemons from running properly (e.g. +listening to ports), they will also need to be shut down gracefully +(which bootstrap-vz cannot do) before unmounting the volume. It is +advisable to avoid starting any daemons inside the chroot at all. + +Settings +~~~~~~~~ + +- ``manifest``: Path to the puppet manifest that should be applied. + *``optional``* +- ``assets``: Path to puppet assets. The contents will be copied into + ``/etc/puppet`` on the image. Any existing files will be overwritten. + *``optional``* +- ``enable_agent``: Whether the puppet agent daemon should be enabled. + *``optional``* diff --git a/bootstrapvz/plugins/root_password/README.rst b/bootstrapvz/plugins/root_password/README.rst new file mode 100644 index 0000000..a24d904 --- /dev/null +++ b/bootstrapvz/plugins/root_password/README.rst @@ -0,0 +1,11 @@ +root password +------------- + +Sets the root password. This plugin removes the task that disables the +SSH password authentication. + +Settings +~~~~~~~~ + +- ``password``: The password for the root user. + *``required``* diff --git a/bootstrapvz/plugins/salt/README.rst b/bootstrapvz/plugins/salt/README.rst new file mode 100644 index 0000000..acb71ab --- /dev/null +++ b/bootstrapvz/plugins/salt/README.rst @@ -0,0 +1,26 @@ +Salt +---- + +Install `salt `__ minion in the image. Uses +`salt-bootstrap `__ script +to install. + +Settings +~~~~~~~~ + +- ``install_source``: Source to install salt codebase from. ``stable`` + for current stable, ``daily`` for installing the daily build, and + ``git`` to install from git repository. + *``required``* +- ``version``: Only needed if you are installing from ``git``. + \ ``develop`` to install current development head, or provide any tag + name or commit hash from `salt + repo `__ + *``optional``* +- ``master``: Salt master FQDN or IP + *``optional``* +- ``grains``: Set `salt + grains `__ + for this minion. Accepts a map with grain name as key and the grain + data as value. + *``optional``* diff --git a/bootstrapvz/plugins/unattended_upgrades/README.rst b/bootstrapvz/plugins/unattended_upgrades/README.rst new file mode 100644 index 0000000..3339b7b --- /dev/null +++ b/bootstrapvz/plugins/unattended_upgrades/README.rst @@ -0,0 +1,18 @@ +Unattended upgrades +------------------- + +Enables the `unattended update/upgrade +feature `__ in +aptitude. Enable it to have your system automatically download and +install security updates automatically with a set interval. + +Settings +~~~~~~~~ + +- ``update_interval``: Days between running ``apt-get update``. + *``required``* +- ``download_interval``: Days between running + ``apt-get upgrade --download-only`` + *``required``* +- ``upgrade_interval``: Days between installing any security upgrades. + *``required``* diff --git a/bootstrapvz/plugins/vagrant/README.rst b/bootstrapvz/plugins/vagrant/README.rst new file mode 100644 index 0000000..a40be4a --- /dev/null +++ b/bootstrapvz/plugins/vagrant/README.rst @@ -0,0 +1,12 @@ +Vagrant +------- + +Vagrant is a tool to quickly create virtualized environments. It uses +"boxes" to make downloading and sharing those environments easier. A box +is a tarball containing a virtual volumes accompanied by an `OVF +specification `__ +of the virtual machine. + +This plugin creates a vagrant box that is ready to be shared or +deployed. At the moment it is only compatible with the VirtualBox +provider and doesn't requires any additional settings. diff --git a/bootstrapvz/providers/azure/README.md b/bootstrapvz/providers/azure/README.rst similarity index 67% rename from bootstrapvz/providers/azure/README.md rename to bootstrapvz/providers/azure/README.rst index c03009e..165b557 100644 --- a/bootstrapvz/providers/azure/README.md +++ b/bootstrapvz/providers/azure/README.rst @@ -1,22 +1,28 @@ -Azure provider -=========== +Azure +===== -This provider generates raw images for Microsoft Azure computing platform. +This provider generates raw images for Microsoft Azure computing +platform. Setup -===== +----- qemu-img >= 1.7.0 required to convert raw image to vhd fixed size disk. This release is available in wheezy-backports. *wget* must be installed on local computer. - -Manifest must use the *raw* format, provider will automatically transform the disk to a vhd disk format. +Manifest must use the *raw* format, provider will automatically +transform the disk to a vhd disk format. Do not create swap space on the OS disk: -The Windows Azure Linux Agent can automatically configure swap space using the local resource disk that is attached to the VM after provisioning on Azure. Modify the following parameters in /etc/waagent.conf appropriately: +The Windows Azure Linux Agent can automatically configure swap space +using the local resource disk that is attached to the VM after +provisioning on Azure. Modify the following parameters in +/etc/waagent.conf appropriately: + +:: ResourceDisk.Format=y ResourceDisk.Filesystem=ext4 @@ -24,7 +30,10 @@ The Windows Azure Linux Agent can automatically configure swap space using the l ResourceDisk.EnableSwap=y ResourceDisk.SwapSizeMB=2048 ## NOTE: set this to whatever you need it to be. -You can specify a waagent.conf file to replace the default one in the manifest in the azure/waagent section of the provider: +You can specify a waagent.conf file to replace the default one in the +manifest in the azure/waagent section of the provider: + +:: "system" : { "waagent" : { @@ -33,4 +42,5 @@ You can specify a waagent.conf file to replace the default one in the manifest i } }, ... -Waagent versions are available at: https://github.com/Azure/WALinuxAgent/releases +Waagent versions are available at: +https://github.com/Azure/WALinuxAgent/releases diff --git a/bootstrapvz/providers/ec2/README.rst b/bootstrapvz/providers/ec2/README.rst new file mode 100644 index 0000000..7c79201 --- /dev/null +++ b/bootstrapvz/providers/ec2/README.rst @@ -0,0 +1,71 @@ +EC2 +=== + +The `EC2 `__ provider automatically creates +a volume for bootstrapping (be it EBS or S3), makes a snapshot of it +once it is done and registers it as an AMI. EBS volume backing only +works on an EC2 host while S3 backed volumes *should* work locally (at +this time however they do not, a fix is in the works). + +Unless `the cloud-init plugin `__ is used, +special startup scripts will be installed that automatically fetch the +configured authorized\_key from the instance metadata and save or run +any userdata supplied (if the userdata begins with ``#!`` it will be +run). + +Credentials +----------- + +The AWS credentials can be configured in two ways: Via the manifest or +through environment variables. To bootstrap S3 backed instances you will +need a user certificate and a private key in addition to the access key +and secret key, which are needed for bootstraping EBS backed instances. + +The settings describes below should be placed in the ``credentials`` key +under the ``provider`` section. + +- **``access-key``**: AWS access-key. + May also be supplied via the environment variable + ``$AWS_ACCESS_KEY`` + *``required for EBS & S3 backing``* +- **``secret-key``**: AWS secret-key. + May also be supplied via the environment variable + ``$AWS_SECRET_KEY`` + *``required for EBS & S3 backing``* +- **``certificate``**: Path to the AWS user certificate. Used for + uploading the image to an S3 bucket. + May also be supplied via the environment variable + ``$AWS_CERTIFICATE`` + *``required for S3 backing``* +- **``private-key``**: Path to the AWS private key. Used for uploading + the image to an S3 bucket. + May also be supplied via the environment variable + ``$AWS_PRIVATE_KEY`` + *``required for S3 backing``* +- **``user-id``**: AWS user ID. Used for uploading the image to an S3 + bucket. + May also be supplied via the environment variable ``$AWS_USER_ID`` + *``required for S3 backing``* + +Example: + +.. code:: yaml + + --- + provider: + name: ec2 + virtualization: hvm + enhanced_networking: simple + credentials: + access-key: AFAKEACCESSKEYFORAWS + secret-key: thes3cr3tkeyf0ryourawsaccount/FS4d8Qdva + +Dependencies +------------ + +To communicate with the AWS API `boto `__ +is required (version 2.14.0 or higher) you can install boto with +``pip install boto`` (on wheezy, the packaged version is too low). S3 +images are chopped up and uploaded using +`euca2ools `__ (install with +``apt-get install euca2ools``). diff --git a/bootstrapvz/providers/gce/README.rst b/bootstrapvz/providers/gce/README.rst new file mode 100644 index 0000000..e760120 --- /dev/null +++ b/bootstrapvz/providers/gce/README.rst @@ -0,0 +1,9 @@ +Google Compute Engine +--------------------- + +The `GCE `__ provider +can creates image as expected by GCE - i.e. raw disk image in \*.tar.gz +file. It can upload created images to Google Storage Engine (to URI +provided in manifest by ``gcs_destination``) and can register image to +be used by Google Compute Engine to project provided in manifest by +``gce_project``. Both of those functionalities are not fully tested yet. diff --git a/bootstrapvz/providers/kvm/README.rst b/bootstrapvz/providers/kvm/README.rst new file mode 100644 index 0000000..57e60d4 --- /dev/null +++ b/bootstrapvz/providers/kvm/README.rst @@ -0,0 +1,8 @@ +KVM +--- + +The `KVM `__ provider creates +virtual images for Linux Kernel-based Virtual Machines. It supports the +installation of `virtio kernel +modules `__ (paravirtualized +drivers for IO operations). diff --git a/bootstrapvz/providers/virtualbox/README.rst b/bootstrapvz/providers/virtualbox/README.rst new file mode 100644 index 0000000..b3e3d16 --- /dev/null +++ b/bootstrapvz/providers/virtualbox/README.rst @@ -0,0 +1,12 @@ +VirtualBox +---------- + +The `VirtualBox `__ provider can bootstrap +to both .vdi and .vmdk images (raw images are also supported but do not +run in VirtualBox). It's advisable to always use vmdk images for +interoperability (e.g. +`OVF `__ files +*should* support vdi files, but since they have no identifier URL not +even VirtualBox itself can import them). VirtualBox Guest Additions can +be installed automatically if the ISO is `provided in the +manifest `__. diff --git a/docs/conf.py b/docs/conf.py index 6eb7717..5abdcfc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,6 +14,8 @@ import sys import os +import glob +import os.path # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -261,3 +263,21 @@ texinfo_documents = [('index', 'bootstrap-vz', u'bootstrap-vz Documentation', # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False + + +# -- Link to rst files scattered throughout the project ------------------- + +for readme_path in glob.glob('../bootstrapvz/providers/*/README.rst'): + provider_name = os.path.basename(os.path.dirname(readme_path)) + include_path = os.path.join('providers', provider_name + '.rst') + path_to_readme = os.path.join('../../bootstrapvz/providers', provider_name, 'README.rst') + with open(include_path, 'w') as include: + include.write('.. include:: ' + path_to_readme) + + +for readme_path in glob.glob('../bootstrapvz/plugins/*/README.rst'): + plugin_name = os.path.basename(os.path.dirname(readme_path)) + include_path = os.path.join('plugins', plugin_name + '.rst') + path_to_readme = os.path.join('../../bootstrapvz/plugins', plugin_name, 'README.rst') + with open(include_path, 'w') as include: + include.write('.. include:: ' + path_to_readme) diff --git a/docs/plugins/.gitignore b/docs/plugins/.gitignore new file mode 100644 index 0000000..50db996 --- /dev/null +++ b/docs/plugins/.gitignore @@ -0,0 +1,3 @@ +* +!index.rst +!.gitignore diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index 690ccbc..208c1d3 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -1,3 +1,19 @@ Plugins ======= + +Plugins are a key feature of bootstrap-vz. Despite their small size +(most plugins do not exceed 100 source lines of code) they can modify +the behavior of bootstrapped systems to a great extent. + +Below you will find documentation for all plugins available for +bootstrap-vz. If you cannot find what you are looking for, consider +`developing it yourself `__ and +contribute to this list! + + +.. toctree:: + :maxdepth: 1 + :glob: + + * diff --git a/docs/providers/.gitignore b/docs/providers/.gitignore new file mode 100644 index 0000000..50db996 --- /dev/null +++ b/docs/providers/.gitignore @@ -0,0 +1,3 @@ +* +!index.rst +!.gitignore diff --git a/docs/providers/index.rst b/docs/providers/index.rst index ef70c42..fb991f2 100644 --- a/docs/providers/index.rst +++ b/docs/providers/index.rst @@ -1,3 +1,19 @@ Providers ========= + +Plugins are a key feature of bootstrap-vz. Despite their small size +(most plugins do not exceed 100 source lines of code) they can modify +the behavior of bootstrapped systems to a great extent. + +Below you will find documentation for all plugins available for +bootstrap-vz. If you cannot find what you are looking for, consider +`developing it yourself `__ and +contribute to this list! + + +.. toctree:: + :maxdepth: 1 + :glob: + + *