From cba496d761e0b59278cf82d0f96cc6e2c4bdc3aa Mon Sep 17 00:00:00 2001 From: Anders Ingemann Date: Sun, 13 Dec 2015 15:24:27 +0100 Subject: [PATCH] Improve providers docs and add loads of manifest examples --- bootstrapvz/providers/azure/README.rst | 44 ++++---- bootstrapvz/providers/kvm/README.rst | 20 ++++ bootstrapvz/providers/virtualbox/README.rst | 23 +++- manifests/README.rst | 115 ++++++++++++++++++-- 4 files changed, 172 insertions(+), 30 deletions(-) diff --git a/bootstrapvz/providers/azure/README.rst b/bootstrapvz/providers/azure/README.rst index ff98941..4e2c10d 100644 --- a/bootstrapvz/providers/azure/README.rst +++ b/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 -can be downloaded. +Provider +~~~~~~~~ -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 diff --git a/bootstrapvz/providers/kvm/README.rst b/bootstrapvz/providers/kvm/README.rst index 57e60d4..a2b06ce 100644 --- a/bootstrapvz/providers/kvm/README.rst +++ b/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 `__ (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 diff --git a/bootstrapvz/providers/virtualbox/README.rst b/bootstrapvz/providers/virtualbox/README.rst index 5944dd1..65590ef 100644 --- a/bootstrapvz/providers/virtualbox/README.rst +++ b/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 diff --git a/manifests/README.rst b/manifests/README.rst index 50554d4..e146ab1 100644 --- a/manifests/README.rst +++ b/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 - `virtualbox provider <../bootstrapvz/providers/virtualbox>`__. - It specifies the path to the VirtualBox Guest Additions ISO, which, when specified, - will be mounted and used to install the VirtualBox Guest Additions. - ``optional`` -- ``variant``: +- ``variant``: Debian variant to install. The only supported value + is ``minbase`` and should only be used in conjunction with the + Docker provider. Not specifying this option will result in a normal + Debian variant being bootstrapped. +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. -- ``pin-priority``: The priority of this pin. + + - ``package``: The package to pin (wildcards allowed) + - ``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