#!/usr/bin/python # -*- coding: utf-8 -*- # (c) 2017, Jasper Lievisse Adriaanse # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = ''' --- module: vmadm short_description: Manage SmartOS virtual machines and zones. description: - Manage SmartOS virtual machines through vmadm(1M). author: Jasper Lievisse Adriaanse (@jasperla) options: archive_on_delete: required: false description: - When enabled, the zone dataset will be mounted on C(/zones/archive) upon removal. type: bool autoboot: required: false description: - Whether or not a VM is booted when the system is rebooted. type: bool brand: choices: [ joyent, joyent-minimal, lx, kvm, bhyve ] default: joyent description: - Type of virtual machine. The C(bhyve) option was added in community.general 0.2.0. type: str boot: required: false description: - Set the boot order for KVM VMs. type: str cpu_cap: required: false description: - Sets a limit on the amount of CPU time that can be used by a VM. Use C(0) for no cap. type: int cpu_shares: required: false description: - Sets a limit on the number of fair share scheduler (FSS) CPU shares for a VM. This limit is relative to all other VMs on the system. type: int cpu_type: required: false choices: [ qemu64, host ] default: qemu64 description: - Control the type of virtual CPU exposed to KVM VMs. type: str customer_metadata: required: false description: - Metadata to be set and associated with this VM, this contain customer modifiable keys. type: dict delegate_dataset: required: false description: - Whether to delegate a ZFS dataset to an OS VM. type: bool disk_driver: required: false description: - Default value for a virtual disk model for KVM guests. type: str disks: required: false description: - A list of disks to add, valid properties are documented in vmadm(1M). type: list dns_domain: required: false description: - Domain value for C(/etc/hosts). type: str docker: required: false description: - Docker images need this flag enabled along with the I(brand) set to C(lx). type: bool filesystems: required: false description: - Mount additional filesystems into an OS VM. type: list firewall_enabled: required: false description: - Enables the firewall, allowing fwadm(1M) rules to be applied. type: bool force: required: false description: - Force a particular action (i.e. stop or delete a VM). type: bool fs_allowed: required: false description: - Comma separated list of filesystem types this zone is allowed to mount. type: str hostname: required: false description: - Zone/VM hostname. type: str image_uuid: required: false description: - Image UUID. type: str indestructible_delegated: required: false description: - Adds an C(@indestructible) snapshot to delegated datasets. type: bool indestructible_zoneroot: required: false description: - Adds an C(@indestructible) snapshot to zoneroot. type: bool internal_metadata: required: false description: - Metadata to be set and associated with this VM, this contains operator generated keys. type: dict internal_metadata_namespace: required: false description: - List of namespaces to be set as I(internal_metadata-only); these namespaces will come from I(internal_metadata) rather than I(customer_metadata). type: str kernel_version: required: false description: - Kernel version to emulate for LX VMs. type: str limit_priv: required: false description: - Set (comma separated) list of privileges the zone is allowed to use. type: str maintain_resolvers: required: false description: - Resolvers in C(/etc/resolv.conf) will be updated when updating the I(resolvers) property. type: bool max_locked_memory: required: false description: - Total amount of memory (in MiBs) on the host that can be locked by this VM. type: int max_lwps: required: false description: - Maximum number of lightweight processes this VM is allowed to have running. type: int max_physical_memory: required: false description: - Maximum amount of memory (in MiBs) on the host that the VM is allowed to use. type: int max_swap: required: false description: - Maximum amount of virtual memory (in MiBs) the VM is allowed to use. type: int mdata_exec_timeout: required: false description: - Timeout in seconds (or 0 to disable) for the C(svc:/smartdc/mdata:execute) service that runs user-scripts in the zone. type: int name: required: false aliases: [ alias ] description: - Name of the VM. vmadm(1M) uses this as an optional name. type: str nic_driver: required: false description: - Default value for a virtual NIC model for KVM guests. type: str nics: required: false description: - A list of nics to add, valid properties are documented in vmadm(1M). type: list nowait: required: false description: - Consider the provisioning complete when the VM first starts, rather than when the VM has rebooted. type: bool qemu_opts: required: false description: - Additional qemu arguments for KVM guests. This overwrites the default arguments provided by vmadm(1M) and should only be used for debugging. type: str qemu_extra_opts: required: false description: - Additional qemu cmdline arguments for KVM guests. type: str quota: required: false description: - Quota on zone filesystems (in MiBs). type: int ram: required: false description: - Amount of virtual RAM for a KVM guest (in MiBs). type: int resolvers: required: false description: - List of resolvers to be put into C(/etc/resolv.conf). type: list routes: required: false description: - Dictionary that maps destinations to gateways, these will be set as static routes in the VM. type: dict spice_opts: required: false description: - Addition options for SPICE-enabled KVM VMs. type: str spice_password: required: false description: - Password required to connect to SPICE. By default no password is set. Please note this can be read from the Global Zone. type: str state: choices: [ present, running, absent, deleted, stopped, created, restarted, rebooted ] default: running description: - States for the VM to be in. Please note that C(present), C(stopped) and C(restarted) operate on a VM that is currently provisioned. C(present) means that the VM will be created if it was absent, and that it will be in a running state. C(absent) will shutdown the zone before removing it. C(stopped) means the zone will be created if it doesn't exist already, before shutting it down. type: str tmpfs: required: false description: - Amount of memory (in MiBs) that will be available in the VM for the C(/tmp) filesystem. type: int uuid: required: false description: - UUID of the VM. Can either be a full UUID or C(*) for all VMs. type: str vcpus: required: false description: - Number of virtual CPUs for a KVM guest. type: int vga: required: false description: - Specify VGA emulation used by KVM VMs. type: str virtio_txburst: required: false description: - Number of packets that can be sent in a single flush of the tx queue of virtio NICs. type: int virtio_txtimer: required: false description: - Timeout (in nanoseconds) for the TX timer of virtio NICs. type: int vnc_password: required: false description: - Password required to connect to VNC. By default no password is set. Please note this can be read from the Global Zone. type: str vnc_port: required: false description: - TCP port to listen of the VNC server. Or set C(0) for random, or C(-1) to disable. type: int zfs_data_compression: required: false description: - Specifies compression algorithm used for this VMs data dataset. This option only has effect on delegated datasets. type: str zfs_data_recsize: required: false description: - Suggested block size (power of 2) for files in the delegated dataset's filesystem. type: int zfs_filesystem_limit: required: false description: - Maximum number of filesystems the VM can have. type: int zfs_io_priority: required: false description: - IO throttle priority value relative to other VMs. type: int zfs_root_compression: required: false description: - Specifies compression algorithm used for this VMs root dataset. This option only has effect on the zoneroot dataset. type: str zfs_root_recsize: required: false description: - Suggested block size (power of 2) for files in the zoneroot dataset's filesystem. type: int zfs_snapshot_limit: required: false description: - Number of snapshots the VM can have. type: int zpool: required: false description: - ZFS pool the VM's zone dataset will be created in. type: str requirements: - python >= 2.6 ''' EXAMPLES = ''' - name: Create SmartOS zone community.general.vmadm: brand: joyent state: present alias: fw_zone image_uuid: 95f265b8-96b2-11e6-9597-972f3af4b6d5 firewall_enabled: yes indestructible_zoneroot: yes nics: - nic_tag: admin ip: dhcp primary: true internal_metadata: root_pw: 'secret' quota: 1 - name: Delete a zone community.general.vmadm: alias: test_zone state: deleted - name: Stop all zones community.general.vmadm: uuid: '*' state: stopped ''' RETURN = ''' uuid: description: UUID of the managed VM. returned: always type: str sample: 'b217ab0b-cf57-efd8-cd85-958d0b80be33' alias: description: Alias of the managed VM. returned: When addressing a VM by alias. type: str sample: 'dns-zone' state: description: State of the target, after execution. returned: success type: str sample: 'running' ''' import json import os import re import tempfile import traceback from ansible.module_utils.basic import AnsibleModule from ansible.module_utils._text import to_native # While vmadm(1M) supports a -E option to return any errors in JSON, the # generated JSON does not play well with the JSON parsers of Python. # The returned message contains '\n' as part of the stacktrace, # which breaks the parsers. def get_vm_prop(module, uuid, prop): # Lookup a property for the given VM. # Returns the property, or None if not found. cmd = '{0} lookup -j -o {1} uuid={2}'.format(module.vmadm, prop, uuid) (rc, stdout, stderr) = module.run_command(cmd) if rc != 0: module.fail_json( msg='Could not perform lookup of {0} on {1}'.format(prop, uuid), exception=stderr) try: stdout_json = json.loads(stdout) except Exception as e: module.fail_json( msg='Invalid JSON returned by vmadm for uuid lookup of {0}'.format(prop), details=to_native(e), exception=traceback.format_exc()) if len(stdout_json) > 0 and prop in stdout_json[0]: return stdout_json[0][prop] else: return None def get_vm_uuid(module, alias): # Lookup the uuid that goes with the given alias. # Returns the uuid or '' if not found. cmd = '{0} lookup -j -o uuid alias={1}'.format(module.vmadm, alias) (rc, stdout, stderr) = module.run_command(cmd) if rc != 0: module.fail_json( msg='Could not retrieve UUID of {0}'.format(alias), exception=stderr) # If no VM was found matching the given alias, we get back an empty array. # That is not an error condition as we might be explicitly checking it's # absence. if stdout.strip() == '[]': return None else: try: stdout_json = json.loads(stdout) except Exception as e: module.fail_json( msg='Invalid JSON returned by vmadm for uuid lookup of {0}'.format(alias), details=to_native(e), exception=traceback.format_exc()) if len(stdout_json) > 0 and 'uuid' in stdout_json[0]: return stdout_json[0]['uuid'] def get_all_vm_uuids(module): # Retrieve the UUIDs for all VMs. cmd = '{0} lookup -j -o uuid'.format(module.vmadm) (rc, stdout, stderr) = module.run_command(cmd) if rc != 0: module.fail_json(msg='Failed to get VMs list', exception=stderr) try: stdout_json = json.loads(stdout) return [v['uuid'] for v in stdout_json] except Exception as e: module.fail_json(msg='Could not retrieve VM UUIDs', details=to_native(e), exception=traceback.format_exc()) def new_vm(module, uuid, vm_state): payload_file = create_payload(module, uuid) (rc, stdout, stderr) = vmadm_create_vm(module, payload_file) if rc != 0: changed = False module.fail_json(msg='Could not create VM', exception=stderr) else: changed = True # 'vmadm create' returns all output to stderr... match = re.match('Successfully created VM (.*)', stderr) if match: vm_uuid = match.groups()[0] if not is_valid_uuid(vm_uuid): module.fail_json(msg='Invalid UUID for VM {0}?'.format(vm_uuid)) else: module.fail_json(msg='Could not retrieve UUID of newly created(?) VM') # Now that the VM is created, ensure it is in the desired state (if not 'running') if vm_state != 'running': ret = set_vm_state(module, vm_uuid, vm_state) if not ret: module.fail_json(msg='Could not set VM {0} to state {1}'.format(vm_uuid, vm_state)) try: os.unlink(payload_file) except Exception as e: # Since the payload may contain sensitive information, fail hard # if we cannot remove the file so the operator knows about it. module.fail_json(msg='Could not remove temporary JSON payload file {0}: {1}'.format(payload_file, to_native(e)), exception=traceback.format_exc()) return changed, vm_uuid def vmadm_create_vm(module, payload_file): # Create a new VM using the provided payload. cmd = '{0} create -f {1}'.format(module.vmadm, payload_file) return module.run_command(cmd) def set_vm_state(module, vm_uuid, vm_state): p = module.params # Check if the VM is already in the desired state. state = get_vm_prop(module, vm_uuid, 'state') if state and (state == vm_state): return None # Lookup table for the state to be in, and which command to use for that. # vm_state: [vmadm commandm, forceable?] cmds = { 'stopped': ['stop', True], 'running': ['start', False], 'deleted': ['delete', True], 'rebooted': ['reboot', False] } if p['force'] and cmds[vm_state][1]: force = '-F' else: force = '' cmd = 'vmadm {0} {1} {2}'.format(cmds[vm_state][0], force, vm_uuid) (rc, stdout, stderr) = module.run_command(cmd) match = re.match('^Successfully.*', stderr) if match: return True else: return False def create_payload(module, uuid): # Create the JSON payload (vmdef) and return the filename. p = module.params # Filter out the few options that are not valid VM properties. module_options = ['debug', 'force', 'state'] # @TODO make this a simple {} comprehension as soon as py2 is ditched # @TODO {k: v for k, v in p.items() if k not in module_options} vmdef = dict([(k, v) for k, v in p.items() if k not in module_options]) try: vmdef_json = json.dumps(vmdef) except Exception as e: module.fail_json( msg='Could not create valid JSON payload', exception=traceback.format_exc()) # Create the temporary file that contains our payload, and set tight # permissions for it may container sensitive information. try: # XXX: When there's a way to get the current ansible temporary directory # drop the mkstemp call and rely on ANSIBLE_KEEP_REMOTE_FILES to retain # the payload (thus removing the `save_payload` option). fname = tempfile.mkstemp()[1] os.chmod(fname, 0o400) with open(fname, 'w') as fh: fh.write(vmdef_json) except Exception as e: module.fail_json(msg='Could not save JSON payload: %s' % to_native(e), exception=traceback.format_exc()) return fname def vm_state_transition(module, uuid, vm_state): ret = set_vm_state(module, uuid, vm_state) # Whether the VM changed state. if ret is None: return False elif ret: return True else: module.fail_json(msg='Failed to set VM {0} to state {1}'.format(uuid, vm_state)) def is_valid_uuid(uuid): if re.match('^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$', uuid, re.IGNORECASE): return True else: return False def validate_uuids(module): # Perform basic UUID validation. failed = [] for u in [['uuid', module.params['uuid']], ['image_uuid', module.params['image_uuid']]]: if u[1] and u[1] != '*': if not is_valid_uuid(u[1]): failed.append(u[0]) if len(failed) > 0: module.fail_json(msg='No valid UUID(s) found for: {0}'.format(", ".join(failed))) def manage_all_vms(module, vm_state): # Handle operations for all VMs, which can by definition only # be state transitions. state = module.params['state'] if state == 'created': module.fail_json(msg='State "created" is only valid for tasks with a single VM') # If any of the VMs has a change, the task as a whole has a change. any_changed = False # First get all VM uuids and for each check their state, and adjust it if needed. for uuid in get_all_vm_uuids(module): current_vm_state = get_vm_prop(module, uuid, 'state') if not current_vm_state and vm_state == 'deleted': any_changed = False else: if module.check_mode: if (not current_vm_state) or (get_vm_prop(module, uuid, 'state') != state): any_changed = True else: any_changed = (vm_state_transition(module, uuid, vm_state) | any_changed) return any_changed def main(): # In order to reduce the clutter and boilerplate for trivial options, # abstract the vmadm properties and build the dict of arguments later. # Dict of all options that are simple to define based on their type. # They're not required and have a default of None. properties = { 'str': [ 'boot', 'disk_driver', 'dns_domain', 'fs_allowed', 'hostname', 'image_uuid', 'internal_metadata_namespace', 'kernel_version', 'limit_priv', 'nic_driver', 'qemu_opts', 'qemu_extra_opts', 'spice_opts', 'uuid', 'vga', 'zfs_data_compression', 'zfs_root_compression', 'zpool' ], 'bool': [ 'archive_on_delete', 'autoboot', 'debug', 'delegate_dataset', 'docker', 'firewall_enabled', 'force', 'indestructible_delegated', 'indestructible_zoneroot', 'maintain_resolvers', 'nowait' ], 'int': [ 'cpu_cap', 'cpu_shares', 'max_locked_memory', 'max_lwps', 'max_physical_memory', 'max_swap', 'mdata_exec_timeout', 'quota', 'ram', 'tmpfs', 'vcpus', 'virtio_txburst', 'virtio_txtimer', 'vnc_port', 'zfs_data_recsize', 'zfs_filesystem_limit', 'zfs_io_priority', 'zfs_root_recsize', 'zfs_snapshot_limit' ], 'dict': ['customer_metadata', 'internal_metadata', 'routes'], 'list': ['disks', 'nics', 'resolvers', 'filesystems'] } # Start with the options that are not as trivial as those above. options = dict( state=dict( default='running', type='str', choices=['present', 'running', 'absent', 'deleted', 'stopped', 'created', 'restarted', 'rebooted'] ), name=dict( default=None, type='str', aliases=['alias'] ), brand=dict( default='joyent', type='str', choices=['joyent', 'joyent-minimal', 'lx', 'kvm', 'bhyve'] ), cpu_type=dict( default='qemu64', type='str', choices=['host', 'qemu64'] ), # Regular strings, however these require additional options. spice_password=dict(type='str', no_log=True), vnc_password=dict(type='str', no_log=True), ) # Add our 'simple' options to options dict. for type in properties: for p in properties[type]: option = dict(default=None, type=type) options[p] = option module = AnsibleModule( argument_spec=options, supports_check_mode=True, required_one_of=[['name', 'uuid']] ) module.vmadm = module.get_bin_path('vmadm', required=True) p = module.params uuid = p['uuid'] state = p['state'] # Translate the state parameter into something we can use later on. if state in ['present', 'running']: vm_state = 'running' elif state in ['stopped', 'created']: vm_state = 'stopped' elif state in ['absent', 'deleted']: vm_state = 'deleted' elif state in ['restarted', 'rebooted']: vm_state = 'rebooted' result = {'state': state} # While it's possible to refer to a given VM by it's `alias`, it's easier # to operate on VMs by their UUID. So if we're not given a `uuid`, look # it up. if not uuid: uuid = get_vm_uuid(module, p['name']) # Bit of a chicken and egg problem here for VMs with state == deleted. # If they're going to be removed in this play, we have to lookup the # uuid. If they're already deleted there's nothing to lookup. # So if state == deleted and get_vm_uuid() returned '', the VM is already # deleted and there's nothing else to do. if uuid is None and vm_state == 'deleted': result['name'] = p['name'] module.exit_json(**result) validate_uuids(module) if p['name']: result['name'] = p['name'] result['uuid'] = uuid if uuid == '*': result['changed'] = manage_all_vms(module, vm_state) module.exit_json(**result) # The general flow is as follows: # - first the current state of the VM is obtained by it's UUID. # - If the state was not found and the desired state is 'deleted', return. # - If the state was not found, it means the VM has to be created. # Subsequently the VM will be set to the desired state (i.e. stopped) # - Otherwise, it means the VM exists already and we operate on it's # state (i.e. reboot it.) # # In the future it should be possible to query the VM for a particular # property as a valid state (i.e. queried) so the result can be # registered. # Also, VMs should be able to get their properties updated. # Managing VM snapshots should be part of a standalone module. # First obtain the VM state to determine what needs to be done with it. current_vm_state = get_vm_prop(module, uuid, 'state') # First handle the case where the VM should be deleted and is not present. if not current_vm_state and vm_state == 'deleted': result['changed'] = False elif module.check_mode: # Shortcut for check mode, if there is no VM yet, it will need to be created. # Or, if the VM is not in the desired state yet, it needs to transition. if (not current_vm_state) or (get_vm_prop(module, uuid, 'state') != state): result['changed'] = True else: result['changed'] = False module.exit_json(**result) # No VM was found that matched the given ID (alias or uuid), so we create it. elif not current_vm_state: result['changed'], result['uuid'] = new_vm(module, uuid, vm_state) else: # VM was found, operate on its state directly. result['changed'] = vm_state_transition(module, uuid, vm_state) module.exit_json(**result) if __name__ == '__main__': main()