Improve providers docs and add loads of manifest examples

bootstrapvz/providers/azure/README.rst

@@ -4,15 +4,33 @@ Azure
 This provider generates raw images for Microsoft Azure computing
 platform.
 
-Setup
------
 
-``qemu-utils`` is needed to create the VHD image.
+Manifest settings
+-----------------
 
-``wget`` must be installed on local computer, so the Windows Azure Linux Agent
+Provider
-can be downloaded.
+~~~~~~~~
 
-Do not create swap space on the OS disk:
+-  ``waagent``: Waagent specific settings.
+   ``required``
+
+    -  ``conf``: Path to ``waagent.conf`` that should override the default
+       ``optional``
+    -  ``version``: Version of waagent to install.
+       Waagent versions are available at:
+       https://github.com/Azure/WALinuxAgent/releases
+       ``required``
+
+Example:
+
+.. code:: yaml
+
+    ---
+    provider:
+      name: azure
+      waagent:
+        conf: /root/waagent.conf
+        version: 2.0.4
 
 The Windows Azure Linux Agent can automatically configure swap space
 using the local resource disk that is attached to the VM after
@@ -27,17 +45,3 @@ provisioning on Azure. Modify the following parameters in
     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:
-
-::
-
-    "system" : { 
-        "waagent" : {
-           "conf": "path_to_my_conf_file",  # optional
-           "version" : "2.0.4"              # mandatory
-        }
-    }, ...
-
-Waagent versions are available at:
-https://github.com/Azure/WALinuxAgent/releases

bootstrapvz/providers/kvm/README.rst

@@ -6,3 +6,23 @@ virtual images for Linux Kernel-based Virtual Machines. It supports the
 installation of `virtio kernel
 modules <http://www.linux-kvm.org/page/Virtio>`__ (paravirtualized
 drivers for IO operations).
+
+Manifest settings
+-----------------
+
+Provider
+~~~~~~~~
+
+-  ``virtio``: Specifies which virtio kernel modules to install.
+   ``optional``
+
+Example:
+
+.. code:: yaml
+
+    ---
+    provider:
+      name: kvm
+      virtio:
+        - virtio_blk
+        - virtio_net

bootstrapvz/providers/virtualbox/README.rst

@@ -10,6 +10,27 @@ interoperability (e.g.
 even VirtualBox itself can import them).
 
 VirtualBox Guest Additions can be installed automatically if the ISO is
-`provided in the manifest <../../../manifests/#bootstrapper>`__.
+provided in the manifest.
 VirtualBox Additions iso can be installed from main Debian repo by running:
 `apt install virtualbox-guest-additions-iso`
+
+
+Manifest settings
+-----------------
+
+Provider
+~~~~~~~~
+
+-  ``guest_additions``: Specifies the path to the VirtualBox Guest Additions ISO,
+   which, when specified, will be mounted and used to install the
+   VirtualBox Guest Additions.
+   ``optional``
+
+Example:
+
+.. code:: yaml
+
+    ---
+    provider:
+      name: virtualbox
+      guest_additions: /usr/share/virtualbox/VBoxGuestAdditions.iso

manifests/README.rst

@@ -58,6 +58,15 @@ name of the provider itself.
 Consult the `providers <../bootstrapvz/providers>`__ section of the documentation
 for a list of valid values.
 
+
+Example:
+
+.. code:: yaml
+
+    ---
+    provider:
+      name: ec2
+
 Bootstrapper
 ~~~~~~~~~~~~
 
@@ -91,15 +100,28 @@ are 4 possible settings:
 -  ``exclude_packages``: Packages to exclude during bootstrap phase.
    Accepts a list of package names.
    ``optional``
--  ``guest_additions``: This setting is only relevant for the
+-  ``variant``: Debian variant to install. The only supported value
-   `virtualbox provider <../bootstrapvz/providers/virtualbox>`__.
+   is ``minbase`` and should only be used in conjunction with the
-   It specifies the path to the VirtualBox Guest Additions ISO, which, when specified,
+   Docker provider. Not specifying this option will result in a normal
-   will be mounted and used to install the VirtualBox Guest Additions.
+   Debian variant being bootstrapped.
-   ``optional``
--  ``variant``:
 
 
+Example:
 
+.. code:: yaml
+
+    ---
+    bootstrapper:
+      workspace: /target
+      tarball: true
+      mirror: http://httpredir.debian.org/debian/
+      include_packages:
+         - whois
+         - psmisc
+      exclude_packages:
+         - isc-dhcp-client
+         - isc-dhcp-common
+      variant: minbase
 
 System
 ~~~~~~
@@ -132,6 +154,20 @@ system and does not fit under any other section.
    Valid values: Any filename from ``/usr/share/zoneinfo``
    ``required``
 
+Example:
+
+.. code:: yaml
+
+    ---
+    system:
+      release: jessie
+      architecture: amd64
+      bootloader: extlinux
+      charmap: UTF-8
+      hostname: jessie x86_64
+      locale: en_US
+      timezone: UTC
+
 Packages
 ~~~~~~~~
 
@@ -181,9 +217,41 @@ variety of sources.
    specified.
    ``optional``
    The values are objects with three keys:
--  ``package``: The package to pin (wildcards allowed)
+
--  ``pin``: The release to pin the package to.
+   -  ``package``: The package to pin (wildcards allowed)
--  ``pin-priority``: The priority of this pin.
+   -  ``pin``: The release to pin the package to.
+   -  ``pin-priority``: The priority of this pin.
+
+Example:
+
+.. code:: yaml
+
+    ---
+    packages:
+      install:
+        - /root/packages/custom_app.deb
+        - puppet
+      install_standard: true
+      mirror: http://cloudfront.debian.net/debian
+      sources:
+       - deb http://apt.puppetlabs.com wheezy main dependencies
+      components:
+        - contrib
+        - non-free
+      trusted-keys:
+        - /root/keys/puppet.gpg
+      preferences:
+        main:
+          - package: *
+            pin: release o=Debian, n=wheezy
+            pin-priority: 800
+          - package: *
+            pin: release o=Debian Backports, a=wheezy-backports, n=wheezy-backports
+            pin-priority: 760
+          - package: puppet puppet-common
+            pin: version 2.7.25-1puppetlabs1
+            pin-priority: 840
+
 
 Volume
 ~~~~~~
@@ -234,9 +302,38 @@ boot, root and swap.
       this partition.
       ``optional``
 
+Example:
+
+.. code:: yaml
+
+    ---
+    volume:
+      backing: vdi
+      partitions:
+        type: msdos
+        boot:
+          filesystem: ext2
+          size: 32MiB
+        root:
+          filesystem: ext4
+          size: 864MiB
+        swap:
+          size: 128MiB
+
 Plugins
 ~~~~~~~
 
 The plugins section is a map of plugin names to whatever configuration a
 plugin requires. Go to the `plugin section <../bootstrapvz/plugins>`__
 of the documentation, to see the configuration for a specific plugin.
+
+
+Example:
+
+.. code:: yaml
+
+    ---
+    plugins:
+      minimize_size:
+        zerofree: true
+        shrink: true