summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPete Fotheringham <pete.fotheringham@codethink.co.uk>2014-12-01 13:52:10 +0000
committerPete Fotheringham <pete.fotheringham@codethink.co.uk>2014-12-01 14:53:38 +0000
commit9a31418847f6fbbdc64f5d0693a7c3d54162f20f (patch)
tree39088922a8ae27e5782a0da5799a48f42c3a7dd9
parentf034691cba14d1919a3c8d1ffa41872ff754e1d3 (diff)
parent3a3b4f7a31457fa9afd5d47d11d20c5ed4b79683 (diff)
downloadmorph-9a31418847f6fbbdc64f5d0693a7c3d54162f20f.tar.gz
Merge branch 'pf-document-extensions'
Reviewed-by: Richard Maw
-rwxr-xr-xmorphlib/exts/kvm.write6
-rw-r--r--morphlib/exts/kvm.write.help37
-rwxr-xr-xmorphlib/exts/virtualbox-ssh.write31
-rw-r--r--morphlib/exts/virtualbox-ssh.write.help88
-rw-r--r--morphlib/plugins/deploy_plugin.py23
5 files changed, 147 insertions, 38 deletions
diff --git a/morphlib/exts/kvm.write b/morphlib/exts/kvm.write
index 61c96676..30b43d6c 100755
--- a/morphlib/exts/kvm.write
+++ b/morphlib/exts/kvm.write
@@ -15,7 +15,11 @@
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-'''A Morph deployment write extension for deploying to KVM+libvirt.'''
+'''A Morph deployment write extension for deploying to KVM+libvirt.
+
+See file kvm.write.help for documentation
+
+'''
import cliapp
diff --git a/morphlib/exts/kvm.write.help b/morphlib/exts/kvm.write.help
index ad0e25f0..db2c0d97 100644
--- a/morphlib/exts/kvm.write.help
+++ b/morphlib/exts/kvm.write.help
@@ -1,6 +1,8 @@
help: |
- Create a KVM/LibVirt virtual machine during Morph's deployment.
+ Deploy a Baserock system as a *new* KVM/LibVirt virtual machine.
+
+ Use the `ssh-rsync` write extension to deploy upgrades to an *existing* VM
Parameters:
@@ -17,11 +19,28 @@ help: |
* `testsys` is the name of the new guest VM';
* `/home/alice/testys.img` is the pathname of the disk image files
on the target host.
- * HOSTNAME: the hostname of the **guest** VM within the network into which
- it is being deployed
- * DISK_SIZE: the size of the VM's primary virtual hard disk
- * RAM_SIZE: The amount of RAM that the virtual machine should allocate for
- itself from the host.
- * VCPUS: the number of virtual CPUs for the VM
- * INITRAMFS_PATH: the location of an initramfs for the bootloader to tell
- Linux to use, rather than booting the rootfs directly.
+
+ * HOSTNAME=name: the hostname of the **guest** VM within the network into
+ which it is being deployed
+
+ * DISK_SIZE=X: the size of the VM's primary virtual hard disk. `X` should
+ use a suffix of `K`, `M`, or `G` (in upper or lower case) to indicate
+ kilo-, mega-, or gigabytes. For example, `DISK_SIZE=100G` would create a
+ 100 gigabyte disk image. **This parameter is mandatory**.
+
+ * RAM_SIZE=X: The amount of RAM that the virtual machine should allocate for
+ itself from the host. `X` is interpreted in the same was as for
+ DISK_SIZE`, and defaults to `1G`
+
+ * VCPUS=n: the number of virtual CPUs for the VM. Allowed values 1-32. Do
+ not use more CPU cores than you have available physically (real cores, no
+ hyperthreads)
+
+ * INITRAMFS_PATH=path: the location of an initramfs for the bootloader to
+ tell Linux to use, rather than booting the rootfs directly.
+
+ * AUTOSTART=<VALUE>` - boolean. If it is set, the VM will be started when
+ it has been deployed.
+
+ (See `morph help deploy` for details of how to pass parameters to write extensions)
+
diff --git a/morphlib/exts/virtualbox-ssh.write b/morphlib/exts/virtualbox-ssh.write
index 39ea8f86..1b4de89c 100755
--- a/morphlib/exts/virtualbox-ssh.write
+++ b/morphlib/exts/virtualbox-ssh.write
@@ -20,6 +20,8 @@
VirtualBox is assumed to be running on a remote machine, which is
accessed over ssh. The machine gets created, but not started.
+See file virtualbox-ssh.write.help for documentation
+
'''
@@ -36,30 +38,10 @@ import morphlib.writeexts
class VirtualBoxPlusSshWriteExtension(morphlib.writeexts.WriteExtension):
- '''Create a VirtualBox virtual machine during Morph's deployment.
-
- The location command line argument is the pathname of the disk image
- to be created. The user is expected to provide the location argument
- using the following syntax:
-
- vbox+ssh://HOST/GUEST/PATH
-
- where:
-
- * HOST is the host on which VirtualBox is running
- * GUEST is the name of the guest virtual machine on that host
- * PATH is the path to the disk image that should be created,
- on that host
-
- The extension will connect to HOST via ssh to run VirtualBox's
- command line management tools.
-
- '''
-
def process_args(self, args):
if len(args) != 2:
raise cliapp.AppException('Wrong number of command line args')
-
+
temp_root, location = args
ssh_host, vm_name, vdi_path = self.parse_location(location)
autostart = self.get_environment_boolean('AUTOSTART')
@@ -88,7 +70,7 @@ class VirtualBoxPlusSshWriteExtension(morphlib.writeexts.WriteExtension):
def parse_location(self, location):
'''Parse the location argument to get relevant data.'''
-
+
x = urlparse.urlparse(location)
if x.scheme != 'vbox+ssh':
raise cliapp.AppException(
@@ -169,11 +151,11 @@ class VirtualBoxPlusSshWriteExtension(morphlib.writeexts.WriteExtension):
attach_disks = self.parse_attach_disks()
for device_no, disk in enumerate(attach_disks, 1):
- cmd = ['storageattach', vm_name,
+ cmd = ['storageattach', vm_name,
'--storagectl', 'SATA Controller',
'--port', str(device_no),
'--device', '0',
- '--type', 'hdd',
+ '--type', 'hdd',
'--medium', disk]
commands.append(cmd)
@@ -242,4 +224,3 @@ class VirtualBoxPlusSshWriteExtension(morphlib.writeexts.WriteExtension):
return iface
VirtualBoxPlusSshWriteExtension().run()
-
diff --git a/morphlib/exts/virtualbox-ssh.write.help b/morphlib/exts/virtualbox-ssh.write.help
index 8b5053a5..ad2a83eb 100644
--- a/morphlib/exts/virtualbox-ssh.write.help
+++ b/morphlib/exts/virtualbox-ssh.write.help
@@ -1,4 +1,86 @@
help: |
- The INITRAMFS_PATH option can be used to specify the location of an
- initramfs for syslinux to tell Linux to use, rather than booting
- the rootfs directly.
+
+ Deploy a Baserock system as a *new* VirtualBox virtual machine.
+ (Use the `ssh-rsync` write extension to deploy upgrades to an *existing*
+ VM)
+
+ Connects to HOST via ssh to run VirtualBox's command line management tools.
+
+ Parameters:
+
+ * location: a custom URL scheme of the form `vbox+ssh://HOST/GUEST/PATH`,
+ where:
+ * HOST is the name of the host on which VirtualBox is running
+ * GUEST is the name of the guest VM on that host
+ * PATH is the path to the disk image that should be created,
+ on that host. For example,
+ `vbox+ssh://alice@192.168.122.1/testsys/home/alice/testys.img` where
+ * `alice@192.168.122.1` is the target host as given to ssh,
+ **from within the development host** (which may be
+ different from the target host's normal address);
+ * `testsys` is the name of the new guest VM';
+ * `/home/alice/testys.img` is the pathname of the disk image files
+ on the target host.
+
+ * HOSTNAME=name: the hostname of the **guest** VM within the network into
+ which it is being deployed.
+
+ * DISK_SIZE=X: **(MANDATORY)** the size of the VM's primary virtual hard
+ disk. `X` should use a suffix of `K`, `M`, or `G` (in upper or lower case)
+ to indicate kilo-, mega-, or gigabytes. For example, `DISK_SIZE=100G`
+ would create a 100 gigabyte virtual hard disk.
+
+ * RAM_SIZE=X: The amount of RAM that the virtual machine should allocate for
+ itself from the host. `X` is interpreted in the same as for DISK_SIZE`,
+ and defaults to `1G`.
+
+ * VCPUS=n: the number of virtual CPUs for the VM. Allowed values 1-32. Do
+ not use more CPU cores than you have available physically (real cores, no
+ hyperthreads).
+
+ * INITRAMFS_PATH=path: the location of an initramfs for the bootloader to
+ tell Linux to use, rather than booting the rootfs directly.
+
+ * AUTOSTART=<VALUE> - boolean. If it is set, the VM will be started when
+ it has been deployed.
+
+ * VAGRANT=<VALUE> - boolean. If it is set, then networking is configured
+ so that the VM will work with Vagrant. Otherwise networking is configured
+ to run directly in VirtualBox.
+
+ * HOST_IPADDR=<ip_address> - the IP address of the VM host.
+
+ * NETMASK=<netmask> - the netmask of the VM host.
+
+ * NETWORK_CONFIG=<net_config> - `net_config` is used to set up the VM's
+ network interfaces. It is a string containing semi-colon separated
+ 'stanzas' where each stanza provides information about a network
+ interface. Each stanza is of the form name:type[,arg=value] e.g.
+
+ lo:loopback
+ eth0:dhcp
+ eth1:static,address=10.0.0.1,netmask=255.255.0.0
+
+ An example of the NETWORK_CONFIG parameter
+
+ `"lo:loopback;eth0:static,address=192.168.100.2,netmask=255.255.255.0;eth1:dhcp,hostname=$(hostname)"`
+
+ It is useful to configure one interface to use NAT to give the VM access
+ to the outside world and another interface to use the Virtual Box host
+ adapter to allow you to access the Trove from the host machine.
+
+ The NAT interface eth1 is set up to use dhcp, the host-only adapter
+ interface is configured statically.
+
+ Note: you must give the host-only adapter interface an address that lies
+ **on the same network** as the host adapter. So if the host adapter has an
+ IP of 192.168.100.1 eth0 should have an address such as 192.168.100.42.
+
+ The settings of the host adapter, including its IP can be changed either
+ in the VirtualBox manager UI (https://www.virtualbox.org/manual/ch03.html#settings-network)
+ or via the VBoxManage command line (https://www.virtualbox.org/manual/ch08.html#idp57572192)
+
+ See Chapter 6 of the VirtualBox User Manual for more information about
+ virtual networking (https://www.virtualbox.org/manual/ch06.html)
+
+ (See `morph help deploy` for details of how to pass parameters to write extensions)
diff --git a/morphlib/plugins/deploy_plugin.py b/morphlib/plugins/deploy_plugin.py
index dd0ba903..f7bb4ffa 100644
--- a/morphlib/plugins/deploy_plugin.py
+++ b/morphlib/plugins/deploy_plugin.py
@@ -177,6 +177,29 @@ class DeployPlugin(cliapp.Plugin):
the _address_ of the trove, _not_ `user@...`, since `root@` will
automatically be prepended to the server address.)
+ In addition to the `location`parameter, deployments can take additional
+ `KEY=VALUE` parameters. These can be provided in the following ways:
+
+ 1. In the cluster definition file, e.g.
+
+ …
+ systems:
+ - morph: systems/foo-system.morph
+ deploy:
+ foo:
+ HOSTNAME: foo
+
+ 2. In the environment before running e.g. `HOSTNAME=foo morph deploy …`
+
+ 3. On the command-line e.g.
+ `morph deploy clusters/foo.morph foo.HOSTNAME=foo`
+
+ For any boolean `KEY=VALUE` parameters, allowed values are:
+
+ +ve `yes`, `1`, `true`;
+
+ -ve `no`, `0`, `false`;
+
The following `KEY=VALUE` parameters are supported for `rawdisk`,
`virtualbox-ssh` and `kvm` and deployment types: