Hypervisors plugin

This plugin allows synapse to manage hypervisors that stand in the same infrastructure as the machine running synapse. Thus, synapse is now used as a proxy to manage remotely a private infrastructure behind a firewall.

Installation

First, synapse should have already been installed. The hypervisors plugin installation is possible in two ways.

Using RPM

yum install synapse-hypervisors-plugin or rpm -i synapse-hypervisors-plugin-<version><release>.noarch.rpm

Using sources

Copy the hypervisors_plugin folder to /var/lib/synapse/custom_plugin/ or wherever you want. By default, synapse will use /var/lib/synapse/custom_plugin/. If you chose to copy hypervisors_plugin elsewhere, then you have to add the following lines into /etc/synapse/synapse.conf :

[controller]
custom_resources = /path/to/hypervisors_plugin/directory/

NFS configuration

On the machine that will host synapse

• Install packages to setup a NFS server : yum install nfs-utils for RHEL-like distributions and apt-get install nfs-common portmap for Debian-like ones ;
• Then, create a folder that will be mounted on each hypervisor : mkdir -p /path/to/nfs/mount/point ;
• Add the following line to the file /etc/exports :

/path/to/nfs/mount/point    <network id>/<network mask>(rw,no_root_squash)

• Start rpcbind and nfs services on RHEL-likes and nfs-kernel-server on Debian ones ;
• Execute the following command to apply the changes : exportfs -a.

On each hypervisor

• Create a directory to mount the previously created one on the proxy machine : mkdir -p /path/to/directory ;
• Mount the NFS mount point on it : mount -t nfs <proxy hostname>:/path/to/nfs/mount/point /path/to/directory.

For VMware hypervisors, you will need to create the directory using vSphere client :

• Select the host ;
• Go to : Configuration -> Storage -> Add storage -> Network filesystem` ;
• Fill the needed fields to mount the folder.

SSH configuration

This is only used if you want to connect to libvirt using SSH. The alternative is to use certificates.

On the machine that will host synapse

• Generate SSH keys (if you don't already have) : ssh-keygen.
• Copy the public key to each hypervisor managed by libvirt (Qemu/KVM and Xen) : ssh-copy-id -i <path to public key> <username>@<hypervisor's hostname>

Plugin configuration

The configuration file of the plugin is located at /etc/synapse/. It should be named hypervisors.conf. Here is an example of this file :

[general]
mount_point_path = /path/to/nfs/mount/point
domain_template_file_path = /var/lib/synapse/templates/domain.tmpl
disk_template_file_path = /var/lib/synapse/templates/disk.tmpl
tftp_path = /mnt/tftp
tftp_images_path = /images/data

[hyp_libvirt]
url = <qemu or xen>[+ssh]://<username>@<hostname>[/system]
hyp_type = <kvm or xen>
emulator_path = <path to qemu-kvm for kvm or path to qemu-dm for xen>
mount_point_path = /path/to/hyp/mount/point

[hyp_vmware]
url = <hostname of hypervisor>
hyp_type = vmware
username = root
password = secret
datastore = <datastore name>
datacenter = <datacenter name>
network_name = <network name>
mount_point_path = /vmfs/volumes/<mount point name>

AMQP API

read

Returns the managed hypervisors, the virtual machines on a given hypervisor or information about a virtual machine.

The id attribute is the hypervisor's id. Those ids are specified in a configuration file ('/etc/synapse/hypervisors.conf').

If none of the hypervisor's id or the virtual machine's name is given, then the response will contain a list of the managed hypervisors ids.

Example:

{
    "collection": "hypervisors",
    "id": "",
    "action": "read"
}

Response:

{
    "status": {
        "hypervisors": ["hyp1", "hyp2", "hyp3", "xen", "vmware50"]
    },
    "uuid": "68E45222BE9D409FA5AE69BFD53064F9",
    "collection": "hypervisors",
    "resource_id": ""
}

If the name of the virtual machine is not specified, then it returns the defined virtual machines on the specified hypervisor.

Here is a request example:

{
    "collection": "hypervisors",
    "id": "hyp3",
    "action": "read"
}

Response:

{
    "status": {
        "hypervisor": "hyp3",
        "url": "qemu+ssh://[email protected]",
        "VMs": ["Hello", "World", "Test"]
    },
    "uuid": "68E45222BE9D409FA5AE69BFD53064F9",
    "collection": "hypervisors",
    "resource_id": "hyp3"
}

Example of incoming message to retrieve the information about a virtual machine named 'Test':

{
    "collection": "hypervisors",
    "id": "hyp3",
    "action": "read",
    "attributes": {
        "name": "Test"
    }
}

Response:

{
    "status": {
        "hypervisor": "hyp3",
        "url": "qemu+ssh://[email protected]",
        "vm_name": "Test",
        "vm_vcpus": 1,
        "vm_status": "running",
        "vm_vnc_port": 5900
    },
    "uuid": "68E45222BE9D409FA5AE69BFD53064F9",
    "collection": "hypervisors",
    "resource_id": "hyp3"
}

create

Creates and provisions a virtual machine.

Mandatory attributes:

• name (string): VM name.
• type (string): hypervisor type (kvm, xen or vmware).
• memory (integer): VM memory (in MB).
• kernel_path (string): URL of a vmlinuz file
• initrd_path (string): URL of a initrd.img file

Others optional attributes:

• num_cpu (integer): number of CPU. Default: 1.
• arch_type (string): CPU architecture. Default: i686.
• cmd_line (string): kernel parameters like "ks=<path_to_kickstart_file>". Default: "".
• boot_dev (string): boot device. Default: "hd".
• disk_driver (string): disk driver name ("tap", "tap2", "phy", or "file" for xen and "qemu" for qemu). Default: "qemu".
• disk_type (string): disk type ("aio" for xen and "raw", "bochs", "qcow2", or "qed" for qemu). Default: "raw"
• disk_size_unit (string): unit of disk size. Default: "M".
  • "B", "bytes" or undefined for bytes
  • "K", "KB" or "KiB" for kilobytes
  • "M", "MB" or "MiB" for megabytes
  • "G", "GB" or "GiB" for gigabytes
  • "T", "TB" or "TiB" for terabytes).
• disk_size (integer): disk size. Default: 3072.
• bridged (boolean): tells if the domain is bridged to an interface. Default: true
• mac_address (string): MAC address for the network interface. Automatically generated when no specified.
• bridge_interface (string): interface of the bridge (ex.: br0).
• vnc_port (integer): port for VNC display. Default: -1 (auto)
• storage_name (string): storage name. Default: generated

Request example:

{
    "collection": "hypervisors",
    "id": "hyp3",
    "action": "create",
    "attributes": {
        "name": "Test",
        "type": "kvm",
        "memory": 512,
        "num_cpu": 1,
        "arch_type": "i686",
        "kernel_path": "http://mirror.centos.org/centos-6/6/os/i386/images/pxeboot/vmlinuz",
        "initrd_path": "http://mirror.centos.org/centos-6/6/os/i386/images/pxeboot/initrd.img",
        "boot_dev": "hd",
        "disk_driver": "qemu",
        "disk_type": "raw",
        "disk_size": 3,
        "disk_size_unit": "G",
        "storage_name": "68E45222BE9D409FA5AE69BFD53064F9"
    }
}

Response:

{
    "status": {
        "vm_name": "Test",
        "vm_status": "running",
        "created": True,
        "hypervisor": "hyp3"
    },
    "uuid": "68E45222BE9D409FA5AE69BFD53064F9",
    "collection": "hypervisors",
    "resource_id": "hyp3"
}

update

Update domain settings.

Mandatory attributes:

• name (string): VM name
• status (string): VM status after update. It can be "running", "paused", "shutdown", "shutoff" or "rebooting".
  • and/or
• disk_size (integer): disk size
• disk_size_unit (string): unit of disk size
  • and/or
• memory (integer): memory size in kilobytes
  • and/or
• num_cpu (integer): number of CPU

Example for shutting off a domain:

{
    "collection": "hypervisors",
    "id": "hyp3",
    "action": "update",
    "attributes": {
        "vm_status": "shutoff"
    }
}

Response:

{
    "status": {
        "hypervisor": "hyp3",
        "vm_name": "Test",
        "vm_status": "shutoff"
    },
    "uuid": "68E45222BE9D409FA5AE69BFD53064F9",
    "collection": "hypervisors",
    "resource_id": "hyp3"
}

Example of resizing disk and memory of a domain:

{
    "collection": "hypervisors",
    "id": "hyp3",
    "action": "update",
    "attributes": {
        "name": "Test",
        "disk_size": 5,
        "disk_size_unit": "G",
        "memory": 1024000
    }
}

Response:

{
    "status": {
        "disk": 5368709120,
        "memory": 1024000
    },
    "uuid": "68E45222BE9D409FA5AE69BFD53064F9",
    "collection": "hypervisors",
    "resource_id": "hyp3"
}

delete

Delete a domain and even it's storage if specified.

The only mandatory attribute is the name of the domain:

• name (string)

Optional attributes:

• delete_volumes (boolean): tells if the disk volume has to be removed too
• force (boolean): tells that, if the VM is running, it has to be shutted down before deleting it

Request example:

{
    "collection": "hypervisors",
    "id": "hyp3",
    "action": "delete",
    "attributes": {
        "name": "Test",
        "delete_volumes": True
        "force": True
    }
}

Response:

{
    "status": {
        "hypervisor": "hyp3",
        "vm_name": "Test",
        "vm_status": "unknown",
        "deleted": True
    },
    "uuid": "68E45222BE9D409FA5AE69BFD53064F9",
    "collection": "hypervisors",
    "resource_id": "hyp3"
}