create-vm-nodes
================

This role creates the XCI VMs used to deploy scenarios. It is a branch from the
bifrost role "bifrost-create-vm-nodes":

https://github.com/openstack/bifrost/tree/master/playbooks/roles/bifrost-create-vm-nodes

It creates the VMs based on the pdf and idf document which describes the
characteristics of the VMs or physical servers. For more information check the
spec:

https://github.com/opnfv/releng-xci/blob/master/docs/specs/infra_manager.rst


Flow
----

The script xci/infra/bifrost/scripts/bifrost-provision.sh will call the
playbook that starts executing the role:

xci-create-vms.yaml

Note that at this stage the pdf and the opnfv_vm.yml are loaded.

Some distro specific tasks related to variables are done and then the
prepare_libvirt playbook is run. This playbook, as the name says,
gets everything ready to run libvirt.

After that, the nodes_json_data dictionary is initialized. This will collect
the data and finally dump it all into the baremetal_json_file which will be
read by bifrost in the subsequent role.

The opnfv vm and the rest of vms get created using the xml libvirt template,
which gets filled with the pdf and opnfv_vm.yml variables.

Finally nodes_json_data is dumped.

Requirements
------------

The following packages are required and ensured to be present:
- libvirt-bin
- qemu-utils
- qemu-kvm
- sgabios


Warning
-------

- It is currently assumed that the OS for the VM will be installed in the first
disk of the node described by the pdf. That's why there is a [0] in:

    - name: create volume for vm
      command: >
        virsh --connect {{ vm_libvirt_uri }}
        vol-create-as {{ node_storage_pool }} {{ vm_name }}.qcow2
        {{ item.disks[0].disk_capacity }}
        --format qcow2 {{ prealloc|default("") }}

- It is assumed that the opnfv VM characteristics are not described in the pdf
but in a similar document called opnfv_vm.yml

- All references to csv from bifrost-create-vm-nodes were removed

Role Variables
--------------

baremetal_json_file: Defaults to '/tmp/baremetal.json'. It contains the
                     required information for bifrost to configure the
                     VMs appropriately

vm_disk_cache: Disk cache mode to use by VMs disk.
               Defaults to shell variable 'VM_DISK_CACHE', or,
               if that is not set, to 'writeback'.

node_names: Space-separated names for nodes to be created.
            Defaults to shell variable 'NODE_NAMES'.
            If not set, VM names will be autogenerated.
            Note that independent on the number of names in this list,
            at most 'test_vm_num_nodes' VMs will be created.

vm_network: Name of the libvirt network to create the nodes on.
            Defaults to shell variable 'VM_NET_BRIDGE', or,
            if that is not set, to 'default'.

node_storage_pool: Name of the libvirt storage pool to create disks
                   for VMs in.
                   Defaults to shell variable 'LIBVIRT_STORAGE_POOL', or,
                   if that is not set, to 'default'.
                   If absent, this pool will be created.

node_storage_pool_path: Path used by the libvirt storage pool
                        'node_storage_pool' if it has to be created.
                        Defaults to "/var/lib/libvirt/images".

node_logdir: Folder where to store VM logs.
             Defaults to "/var/log/libvirt/baremetal_logs".

vm_emulator: Path to emulator executable used to define VMs in libvirt.
             Defaults to "/usr/bin/qemu-system-x86_64".
             Generally users should not need to modify this setting,
             as it is OS-specific and is overwritten by
              os/distribution-specific defaults in this role when needed.

vm_libvirt_uri: URI to connect to libvirt for networks, storage and VM
                related actions.
                Defaults to shell variable 'LIBVIRT_CONNECT_URI', or,
                if that is not set, to 'qemu:///system'.
                Note that currently connecting to remote libvirt is
                not tested and is unsupported.

network_interface: Name of the bridge to create when creating
                   'vm_network' libvirt network.
                   Defaults to "virbr0".
                   Name and default of this option are chosen to be the same
                   as in 'bifrost-ironic-install' role.

opnfv_vm_network_ip: IP for the 'network_interface' bridge.
                    Defaults to '192.168.122.1'.
                    This setting is applied only when 'vm_network'
                    was absent and is created from scratch.

node_network_netmask: Subnet mask for 'network_interface' bridge.
                      Defaults to '255.255.255.0'.
                      This setting is applied only when 'vm_network'
                      was absent and is created from scratch.

Dependencies
------------

None at this time.

Example Playbook
----------------

- hosts: localhost
  connection: local
  become: yes
  gather_facts: yes
  roles:
    - role: create-vm-nodes

License
-------

Copyright (c) 2018 SUSE Linux GmbH.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Author Information
------------------

mbuil@suse.com