# libvirt_manager

Used for checking if:
    - there's SVM/VMX virtualization, enable it if not
    - install libvirt packages and dependencies and add group and user to libvirt group if necessary,

## Privilege escalation

`become` - Required in:
    - `virsh_checks.yml`: For creating libvirt group if needed and also append user to this group if it's not there.
    - `virtualization_prerequisites.yml`: For enabling VMX/SVM module with modprobe.
    - `packages.yml`: Install all libvirt dependencies.
    - `polkit_rules.yml`: Add polkit rules under `/etc/`.

## Parameters

* `cifmw_libvirt_manager_basedir`: (String) Base directory. Defaults to `cifmw_basedir` which defaults to `~/ci-framework-data`.
* `cifmw_libvirt_manager_enable_virtualization_module`: (Boolean) If `true` it will enable the virtualization module in case it's not already and if the hosts allow it. Defaults to `false`.
* `cifmw_libvirt_manager_user`: (String) User used for libvirt. Default: the one in the environment variable `USER`.
* `cifmw_libvirt_manager_images_url`: (String) Location basedir for the image URI. Defaults to `https://cloud.centos.org/centos/9-stream/x86_64/images`.
* `cifmw_libvirt_manager_configuration`: (Dict) Structure describing the libvirt layout (networking and VMs).
* `cifmw_libvirt_manager_vm_template`: (String) Template name to use to define the virtual machines. Defaults to `domain.xml.j2`. Advanced use only.
* `cifmw_libvirt_manager_crc_pool`: (String) CRC pool machine location. Defaults to `cifmw_crc_pool` which defaults to `~/.crc/machines/crc`.
* `cifmw_libvirt_manager_pool_dir`: (String) Pool directory. Defaults to `cifmw_libvirt_manager_basedir/volumes`.Advanced use only.
* `cifmw_libvirt_manager_installyamls`: (String) install_yamls repository location. Defaults to `cifmw_installyamls_repos` which defaults to `../..`
* `cifmw_libvirt_manager_dryrun`: (Boolean) Toggle ci_make `dry_run` parameter. Defaults to `false`.
* `cifmw_libvirt_manager_compute_amount`: (Integer) State the amount of computes you want. Defaults to `1`.
* `cifmw_libvirt_manager_compute_memory`: (Integer) The amount of memory in GB per compute. Defaults to `4`.
* `cifmw_libvirt_manager_compute_disksize`: (Integer) The size of the disk in GB per compute. Defaults to `20`.
* `cifmw_libvirt_manager_compute_cpus`: (Integer) The amount of vCPUs per compute. Defaults to `1`.
* `cifmw_libvirt_manager_apply_virtproxy_patch` (Boolean) Apply patch virtproxy patch for improved libvirt stability. This is set to `true` by default.
* `cifmw_libvirt_manager_net_prefix_add` (Boolean) Adds `cifmw-` prefix to the network resources managed by this role. By default, it is set to `true`.
* `cifmw_libvirt_manager_pub_net`: (String) Network name playing the "public" interface. Defaults to `public`.
* `cifmw_libvirt_manager_vm_net_ip_set`: (Dict) Allow to extend the existing mapping for host family to IP mapping. Defaults to `{}`.
* `cifmw_libvirt_manager_fixed_networks`: (List) Network names you don't want to prefix with `cifmw-`. It will be concatenated with cifmw_libvirt_manager_fixed_networks_defaults. Defaults to`[]`.
* `cifmw_libvirt_manager_reproducer_key_type`: (String) Type of ssh key that will be injected into the controller VMs. Defaults to `cifmw_ssh_keytype` which default to `ecdsa`.
* `cifmw_libvirt_manager_reproducer_key_size`: (Integer) Size of the ecdsa ssh keys that will be injected into the controller VMs. Defaults to `cifmw_ssh_keysize` which default to 521.
* `cifmw_libvirt_manager_spineleaf_setup`: (Boolean) Whether the VMs deployed are connected to a spine/leaf virtual infrastructure or not. When set to `true`, the interfaces of the instances from a certain type of VM are not connected to the same networks, but they can be defined per VM using the `spineleafnets` list (except for the `controller`). Defaults to `false`.
* `cifmw_libvirt_manager_network_interface_types`: (Dict) By default, interfaces attached to VMs are created with `--type bridge`, but with this parameter, those interfaces can be configured with any other types. Defaults to empty dictionary.
* `cifmw_libvirt_manager_configuration_patch(.)*`: (Dict) Structure describing the patch to combine on top of `cifmw_libvirt_manager_configuration`.
* `cifmw_libvirt_manager_firewalld_zone_libvirt_forward`: (Bool) Enable forwarding in the libvirt firewall zone. Defaults to: `true`
* `cifmw_libvirt_manager_firewalld_default_zone`: (String) Name of the default firewall zone. Defaults to `public`.
* `cifmw_libvirt_manager_firewalld_default_zone_masquerade`: (Bool) Enable masquerading on the default firewall zone. Defaults to `true`.
* `cifmw_libvirt_manager_attach_dummy_interface_on_bridges`: (Bool) Attach dummy interface on bridges. Defaults to `true`.
* `cifmw_libvirt_manager_default_gw_nets`: (List[String]) List of networks used as default gateway. If not set, defaults to the `cifmw_libvirt_manager_pub_net`. Read bellow for more information about that parameter.
* `cifmw_libvirt_manager_vm_users`: (List[Dict]) Used to override the default list of users enabled in the vm. For its format, refers to cloud-init [documentation](https://cloudinit.readthedocs.io/en/latest/reference/modules.html#users-and-groups) about `users`. Defaults to `[]`.
* `cifmw_libvirt_manager_extra_network_configuration`: (Dict) Extra network configuration in nmstate format for the hypervisor. This configuration is applied after creating the libvirt networks, so it can be used to create VLAN interfaces on the libvirt bridges. In addition to nmstate, it also supports a `cifmw_firewall_zone` hint in nmstate interfaces.  Defaults to: `{}`.
* `cifmw_libvirt_manager_radvd_networks`: (List[Dict]) List of networks to configure with radvd for IPv6 router advertisements. When defined, the `radvd` role will be included after network creation. Each network definition follows the format documented in the `radvd` role. Defaults to `[]`.

### `cifmw_libvirt_manager_default_gw_nets` parameter usage

By default, the routing is configured so that the default gateway is on the `cifmw_libvirt_manager_pub_net` network (usually `public`). In some cases (DCN for instance), this doesn't scale, leading to
some hosts not properly reachable.

By using this parameter, the user can instruct the CI Framework to use another network as default gateway. In DCN case, all of the created `ctlplane` can be listed in that parameter and, since the computes
have only one `ctlplane` network associated, it means they'll use it as default gateway, without any conflict.

#### Example

```YAML
# Use osp_trunk (ctlplane) as default gateway instead of the public network
cifmw_libvirt_manager_default_gw_nets: osp_trunk

# List all of the DCN ctlplane as "default gateway"
cifmw_libvirt_manager_default_gw_nets:
  - osp_trunk
  - dcn1_tr
  - dcn2_tr
```

### Structure for `cifmw_libvirt_manager_configuration`

The following structure has to be passed via the configuration parameter:

```YAML
cifmw_libvirt_manager_configuration:
  vms:
    type_name:  # (string, such as "compute", "controller"
      start: (boolean, toggle if the VM should be strated or not. Optional, defaults to true)
      manage: (boolean, toggle if the VM should be added to the inventory. Managed VM's must be on the cifmw_libvirt_manager_pub_net network. Optional, defaults to true)
      amount: (integer, optional. Optional, defaults to 1, allowed [0-9]+)
      image_url: (string, URI to the base image. Optional if disk_file_name is set to "blank")
      sha256_image_name: (string, image checksum. Optional if disk_file_name is set to "blank")
      image_local_dir: (string, image destination for download. Optional if disk_file_name is set to "blank")
      disk_file_name: (string, target image name. If set to "blank", will create a blank image)
      disksize: (integer, disk size for the VM type. Optional, defaults to 40G)
      disk_bus: (string, optional. Bus type for / disk. It can be virtio or scsi. Defaults to `virtio`)
      memory: (integer, RAM amount in GB. Optional, defaults to 2)
      cpus: (integer, amount of CPU. Optional, defaults to 2)
      nets: (ordered list of networks to connect to)
      extra_disks_num: (integer, optional. Number of extra disks to be configured.)
      extra_disks_size: (string, optional. Storage capacity to be allocated. Example 1G, 512M)
      extra_disks_bus: (string, optional. Bus type for extra disks. It can be virtio or scsi. Defaults to `virtio`)
      user: (string, optional. Username to create on the vm which can becomes root. Defaults to `zuul`)
      password: (string, optional, defaults to fooBar. Root password for console access)
      target: (Hypervisor hostname you want to deploy the family on. Optional)
      uefi: (boolean, toggle UEFI boot. Optional, defaults to false)
      bootmenu_enable: (string, toggle bootmenu. Optional, defaults to "no")
      boot_order: (list, optional. Ordered list of boot devices. Valid values are 'hd' or 'disk' for disk boot, and 'network' for network boot. Example: ['hd', 'network'] will attempt disk boot first, then network boot. The boot order is applied after all devices are attached to the VM.)
      networkconfig: (dict or list[dict], [network-config](https://cloudinit.readthedocs.io/en/latest/reference/network-config-format-v2.html#network-config-v2) v2 config, needed if a static ip address should be defined at boot time in absence of a dhcp server in special scenarios. Optional)
      devices: (dict, optional, defaults to {}. The keys are the VMs of that type that needs devices to be attached, and the values are lists of strings, where each string must contain a valid <hostdev/> libvirt XML element that will be passed to virsh attach-device)
      dhcp_options: (list, optional, defaults to []. List of DHCP options to apply to all VMs of this type. Format: ["option_number,value", ...])
  networks:
    net_name: <XML definition of the network to create>
```

Specific `type_name`: `^crc.*` and `^ocp.*` are enabling specific paths in the module.

#### Example

```YAML
_networks:
  public:
    range: "192.168.100.0/24"
  osp_trunk:
    default: true
    range: "192.168.122.0/24"
    mtu: 9000

cifmw_libvirt_manager_extra_network_configuration:
  interfaces:
    - name: vlan10
      cifmw_firewall_zone: libvirt
      type: vlan
      state: up
      vlan:
        base-iface: cifmw-osp_trunk
        id: 10
        protocol: 802.1q
      ipv4:
        enabled: true
        dhcp: false
        address:
          - ip: 172.20.0.1
            prefix-length: 24

cifmw_libvirt_manager_configuration:
  vms:
    compute:
      amount: 3
      disk_file_name: blank
      nets:
        - public
        - osp_trunk
      extra_disks_num: 5
      extra_disks_size: '1G'
      devices:
        "0": >-
          <hostdev mode='subsystem' type='pci' managed='yes'>
            <source>
              <address domain='0x0000' bus='0x17' slot='0x00' function='0x0'/>
            </source>
          </hostdev>
    controller:
      image_url: "{{ cifmw_discovered_image_url }}"
      sha256_image_name: "{{ cifmw_discovered_hash }}"
      image_local_dir: "{{ cifmw_basedir }}/images/"
      disk_file_name: "centos-stream-9.qcow2"
      disksize: 50
      memory: 4
      cpus: 2
      nets:
        - public
        - osp_trunk
    baremetal_instance:
      amount: 2
      disk_file_name: "blank"
      disksize: 50
      memory: 8
      cpus: 4
      bootmenu_enable: "yes"
      boot_order:
        - hd
        - network
      nets:
        - public
  networks:
    public: |-
      <network>
        <name>public</name>
        <forward mode='nat'/>
        <bridge name='public' stp='on' delay='0'/>
        <ip family='ipv4'
         address='{{ _networks.public.range | ansible.utils.nthhost(1) }}'
         prefix='24'>
          <dhcp>
            <range
             start='{{ _networks.public.range | ansible.utils.nthhost(10) }}'
             end='{{ _networks.public.range | ansible.utils.nthhost(100) }}'/>
          </dhcp>
        </ip>
      </network>
    osp_trunk: |-
      <network>
        <name>osp_trunk</name>
        <forward mode='nat'/>
        <bridge name='osp_trunk' stp='on' delay='0'/>
        <mtu size='{{ _networks.osp_trunk.mtu }}'/>
        <ip
         family='ipv4'
         address='{{ _networks.osp_trunk.range | ansible.utils.nthhost(1) }}'
         prefix='24'>
        </ip>
      </network>
```

### Parameters imported from the reproducer role

The following parameters are usually set in the [reproducer](./reproducer.md) context.
The parameters listed here are therefore merely proxies to the ones set in the reproducer,
and have the same name, less the role prefix. Default values are the same as the
reproducer role.

Now, cifmw_default_dns_servers group_vars is introduced, and it sets dns_servers for both reproducer and libvirt_manager roles.

* `cifmw_libvirt_manager_dns_servers`: `{{ cifmw_default_dns_servers | default(['1.1.1.1', '8.8.8.8']) }}`

## Calling attach_network.yml from another role

You may want to include that specific tasks file from another role in order to inject some networks into
a virtual machine.

In order to do so, you have to provide specific variables:

* `vm_name`: (String) Virtual machine name. Mandatory.
* `network`: (Data structure). Mandatory.
  * `name`: (String) Network or bridge name. Mandatory.
  * `cidr`: (String) Network CIDR. Mandatory.
* `cifmw_libvirt_manager_net_prefix_add`: (Bool) Toggle this to `true` if the network name needs to get the `cifmw-` prefix (advanced usage). Optional. Defaults to `true`.

## Layout patching
This role allows to use a base layout, given by `cifmw_libvirt_manager_configuration` and patch it
with other values, ie. patch it for another environment, by declaring variables prefixed that matches the
`^cifmw_libvirt_manager_configuration_patch.*` regex. Each of those variables, after sorting them by name,
will be combined on top of the original `cifmw_libvirt_manager_configuration` and that will be the final
layout used by the role.

### Example of a task

```YAML
- name: Attach my network to my virtual machine
  vars:
    vm_name: my-virtual-machine
    network:
      name: my-network
      cidr: 192.168.130.0/24
  ansible.builtin.include_role:
    name: libvirt_manager
    tasks_from: attack_interface.yml
```

## IPv6 Router Advertisements with radvd

The libvirt_manager role can automatically configure IPv6 router advertisements using the `radvd` role. This is useful for providing SLAAC and/or DHCPv6 configuration to VMs on IPv6-enabled networks.

To enable radvd, define `cifmw_libvirt_manager_radvd_networks` with a list of network configurations:

```yaml
cifmw_libvirt_manager_radvd_networks:
  - name: cifmw-testnet1
    adv_managed_flag: true
    adv_other_config_flag: true
    prefixes:
      - network: "2001:db8:1::/64"
```

For complete documentation on available parameters and configuration options, refer to the [radvd role documentation](../radvd/README.md).