Initiates the instance of the given VM on the target host.

    .. versionadded:: 2016.3.0

    name
        The name of the VM to deploy.

    host_id
        The ID of the target host where the VM will be deployed. Can be used instead
        of ``host_name``.

    host_name
        The name of the target host where the VM will be deployed. Can be used instead
        of ``host_id``.

    capacity_maintained
        True to enforce the Host capacity is not over-committed. This parameter is only
        acknowledged for users in the ``oneadmin`` group. Host capacity will be always
        enforced for regular users.

    datastore_id
        The ID of the target system data-store where the VM will be deployed. Optional
        and can be used instead of ``datastore_name``. If neither ``datastore_id`` nor
        ``datastore_name`` are set, OpenNebula will choose the data-store.

    datastore_name
        The name of the target system data-store where the VM will be deployed. Optional,
        and can be used instead of ``datastore_id``. If neither ``datastore_id`` nor
        ``datastore_name`` are set, OpenNebula will choose the data-store.

    CLI Example:

    .. code-block:: bash

        salt-cloud -a vm_deploy my-vm host_id=0
        salt-cloud -a vm_deploy my-vm host_id=1 capacity_maintained=False
        salt-cloud -a vm_deploy my-vm host_name=host01 datastore_id=1
        salt-cloud -a vm_deploy my-vm host_name=host01 datastore_name=default

def vm_deploy(name, kwargs=None, call=None):
    '''
    Initiates the instance of the given VM on the target host.

    .. versionadded:: 2016.3.0

    name
        The name of the VM to deploy.

    host_id
        The ID of the target host where the VM will be deployed. Can be used instead
        of ``host_name``.

    host_name
        The name of the target host where the VM will be deployed. Can be used instead
        of ``host_id``.

    capacity_maintained
        True to enforce the Host capacity is not over-committed. This parameter is only
        acknowledged for users in the ``oneadmin`` group. Host capacity will be always
        enforced for regular users.

    datastore_id
        The ID of the target system data-store where the VM will be deployed. Optional
        and can be used instead of ``datastore_name``. If neither ``datastore_id`` nor
        ``datastore_name`` are set, OpenNebula will choose the data-store.

    datastore_name
        The name of the target system data-store where the VM will be deployed. Optional,
        and can be used instead of ``datastore_id``. If neither ``datastore_id`` nor
        ``datastore_name`` are set, OpenNebula will choose the data-store.

    CLI Example:

    .. code-block:: bash

        salt-cloud -a vm_deploy my-vm host_id=0
        salt-cloud -a vm_deploy my-vm host_id=1 capacity_maintained=False
        salt-cloud -a vm_deploy my-vm host_name=host01 datastore_id=1
        salt-cloud -a vm_deploy my-vm host_name=host01 datastore_name=default
    '''
    if call != 'action':
        raise SaltCloudSystemExit(
            'The vm_deploy action must be called with -a or --action.'
        )

    if kwargs is None:
        kwargs = {}

    host_id = kwargs.get('host_id', None)
    host_name = kwargs.get('host_name', None)
    capacity_maintained = kwargs.get('capacity_maintained', True)
    datastore_id = kwargs.get('datastore_id', None)
    datastore_name = kwargs.get('datastore_name', None)

    if host_id:
        if host_name:
            log.warning(
                'Both the \'host_id\' and \'host_name\' arguments were provided. '
                '\'host_id\' will take precedence.'
            )
    elif host_name:
        host_id = get_host_id(kwargs={'name': host_name})
    else:
        raise SaltCloudSystemExit(
            'The vm_deploy function requires a \'host_id\' or a \'host_name\' '
            'to be provided.'
        )

    if datastore_id:
        if datastore_name:
            log.warning(
                'Both the \'datastore_id\' and \'datastore_name\' arguments were provided. '
                '\'datastore_id\' will take precedence.'
            )
    elif datastore_name:
        datastore_id = get_datastore_id(kwargs={'name': datastore_name})
    else:
        datastore_id = '-1'

    server, user, password = _get_xml_rpc()
    auth = ':'.join([user, password])
    vm_id = get_vm_id(kwargs={'name': name})
    response = server.one.vm.deploy(auth,
                                    int(vm_id),
                                    int(host_id),
                                    salt.utils.data.is_true(capacity_maintained),
                                    int(datastore_id))

    data = {
        'action': 'vm.deploy',
        'deployed': response[0],
        'vm_id': response[1],
        'error_code': response[2],
    }

    return data