Instantiates a new virtual machine from a template.

    .. versionadded:: 2016.3.0

    .. note::
        ``template_instantiate`` creates a VM on OpenNebula from a template, but it
        does not install Salt on the new VM. Use the ``create`` function for that
        functionality: ``salt-cloud -p opennebula-profile vm-name``.

    vm_name
        Name for the new VM instance.

    template_id
        The ID of the template from which the VM will be created. Can be used instead
        of ``template_name``.

    template_name
        The name of the template from which the VM will be created. Can be used instead
        of ``template_id``.

    CLI Example:

    .. code-block:: bash

        salt-cloud -f template_instantiate opennebula vm_name=my-new-vm template_id=0

def template_instantiate(call=None, kwargs=None):
    '''
    Instantiates a new virtual machine from a template.

    .. versionadded:: 2016.3.0

    .. note::
        ``template_instantiate`` creates a VM on OpenNebula from a template, but it
        does not install Salt on the new VM. Use the ``create`` function for that
        functionality: ``salt-cloud -p opennebula-profile vm-name``.

    vm_name
        Name for the new VM instance.

    template_id
        The ID of the template from which the VM will be created. Can be used instead
        of ``template_name``.

    template_name
        The name of the template from which the VM will be created. Can be used instead
        of ``template_id``.

    CLI Example:

    .. code-block:: bash

        salt-cloud -f template_instantiate opennebula vm_name=my-new-vm template_id=0

    '''
    if call != 'function':
        raise SaltCloudSystemExit(
            'The template_instantiate function must be called with -f or --function.'
        )

    if kwargs is None:
        kwargs = {}

    vm_name = kwargs.get('vm_name', None)
    template_id = kwargs.get('template_id', None)
    template_name = kwargs.get('template_name', None)

    if vm_name is None:
        raise SaltCloudSystemExit(
            'The template_instantiate function requires a \'vm_name\' to be provided.'
        )

    if template_id:
        if template_name:
            log.warning(
                'Both the \'template_id\' and \'template_name\' arguments were provided. '
                '\'template_id\' will take precedence.'
            )
    elif template_name:
        template_id = get_template_id(kwargs={'name': template_name})
    else:
        raise SaltCloudSystemExit(
            'The template_instantiate function requires either a \'template_id\' '
            'or a \'template_name\' to be provided.'
        )

    server, user, password = _get_xml_rpc()
    auth = ':'.join([user, password])
    response = server.one.template.instantiate(auth, int(template_id), vm_name)

    data = {
        'action': 'template.instantiate',
        'instantiated': response[0],
        'instantiated_vm_id': response[1],
        'vm_name': vm_name,
        'error_code': response[2],
    }

    return data