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 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

# 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:

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

_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 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

- 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:

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.