Features

Unclassified

Cloud

Engine

Foreman

Gluster

Infra

Infra / Reloadable Configuration

Integration

Network

Node

Os Support

Plugins

SLA

Storage

UX

UX / Design

UX / Design / Network

VDSM

Virt

At a glance

  • Feature: Ansible oVirt modules
  • Status: Released
  • Authors: omachace
  • Summary

    The goal is to have a module for every entity oVirt has, so users can manage whole oVirt environment via Ansible playbooks.

    Owner

    Ansible

    About

    Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks such as continuous deployments or zero downtime rolling updates.

    Ansible’s main goals are simplicity and ease-of-use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with an accelerated socket mode and pull modes as alternatives), and a language that is designed around auditability by humans–even those not familiar with the program.

    Playbooks

    Playbooks are Ansible’s configuration, deployment, and orchestration language. They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process. Playbooks uses YAML as support language. In general playbooks consist of tasks. Every tasks executes specific module with parameters.

    Modules

    Ansible ships with a number of modules (called the ‘module library’) that can be executed directly on remote hosts or through Playbooks. Modules have to be idempotent. The concept that change commands should only be applied when they need to be applied, and that it is better to describe the desired state of a system than the process of how to get to that state. This feature page describes oVirt ansible modules.

    Ansible oVirt modules

    You can see all Ansible oVirt modules source code here and the documentation here.

    Important: Ansible oVirt modules works with oVirt version 4 and higher.

    Note: Links to modules documentation which will be in Ansible 2.3 are temporary on readthedocs page once, the modules will be merged and Ansible 2.3 will be release we will change links to official documentation.

    Ansible 2.2

    Following modules has been merged and can be used in Ansible version 2.2.

    The following table shows oVirt modules and version of Ansible where the modules are shipped:

    Module Version
    ovirt_auth 2.2
    ovirt_vms 2.2
    ovirt_disks 2.2
    ovirt_datacenters 2.3
    ovirt_clusters 2.3
    ovirt_networks 2.3
    ovirt_storage_domains 2.3
    ovirt_hosts 2.3
    ovirt_host_pm 2.3
    ovirt_host_networks 2.3
    ovirt_external_providers 2.3
    ovirt_nics 2.3
    ovirt_templates 2.3
    ovirt_vmpools 2.3
    ovirt_users 2.3
    ovirt_groups 2.3
    ovirt_permissions 2.3

    ovirt_auth

    ovirt_auth [source] module authenticates to oVirt engine and creates SSO token, which should be later used in all other oVirt modules, so all modules don’t need to perform login and logout. This module returns an Ansible fact called ovirt_auth. Every module can use this fact as auth parameter, to perform authentication

    Example

    # Obtain SSO token with using username/password credentials
    no_log: true
    ovirt_auth:
      url: https://ovirt.example.com/ovirt-engine/api
      username: admin@internal
      password: 123456
      ca_file: ca.pem
    
    # Revoke the SSO token returned from previous task
    ovirt_auth:
      state: absent
      ovirt_auth: "{{ ovirt_auth }}"
    

    ovirt_vms

    ovirt_vms [source] module manages whole lifecycle of the Virtual Machine (VM) in oVirt. In addtion you can add disks and network interfaces to VM from this module, but if you need to manage disks and network interfaces in more depth you should use modules specifically for it.

    Example

    # Creates a new Virtual Machine from template named 'rhel7_template'
    ovirt_vms:
        state: present
        name: myvm
        template: rhel7_template
    
    # Run VM with cloud init:
    ovirt_vms:
        name: rhel7
        template: rhel7
        cluster: Default
        memory: 1GiB
        high_availability: true
        cloud_init:
          nic_boot_protocol: static
          nic_ip_address: 10.34.60.86
          nic_netmask: 255.255.252.0
          nic_gateway: 10.34.63.254
          nic_name: eth1
          nic_on_boot: true
          host_name: example.com
          custom_script: |
            write_files:
             - content: |
                 Hello, world!
               path: /tmp/greeting.txt
               permissions: '0644'
          user_name: root
          root_password: super_password
    
    # Migrate/Run VM to/on host named 'host1'
    ovirt_vms:
        state: running
        name: myvm
        host: host1
    
    # Change Vm's CD:
    ovirt_vms:
        name: myvm
        cd_iso: drivers.iso
    
    # Stop vm:
    ovirt_vms:
        state: stopped
        name: myvm
    
    # Hot plug memory to already created and running VM:
    # (VM won't be restarted)
    ovirt_vms:
        name: myvm
        memory: 4GiB
      
    # When change on the VM needs restart of the VM, use next_run state,
    # The VM will be updated and rebooted if there are any changes.
    # If present state would be used, VM won't be restarted.
    ovirt_vms:
        state: next_run
        name: myvm
        boot_devices:
          - network
    

    ovirt_disks

    ovirt_disks [source] module to manage Virtual Machine and floating disks in oVirt. This module can attach/detach disks from VM, update attached disks attributes. This module also handle work with logical units.

    Examples

    # Create and attach new disk to VM
    - ovirt_disks:
        name: myvm_disk
        vm_name: rhel7
        size: 10GiB
        format: cow
        interface: virtio
    
    # Attach logical unit to VM rhel7
    - ovirt_disks:
        vm_name: rhel7
        logical_unit:
          target: iqn.2016-08-09.brq.str-01:omachace
          id: 1IET_000d0001
          address: 10.34.63.204
        interface: virtio
    
    # Detach disk from VM
    - ovirt_disks:
        state: detached
        name: myvm_disk
        vm_name: rhel7
        size: 10GiB
        format: cow
        interface: virtio
    

    Ansible 2.3

    Following modules are currently merged in devel branch and will be included in Ansible version 2.3.

    ovirt_datacenters

    ovirt_datacenters [source] module to manage oVirt datacenters. This module can handle create, update and delete action with various parameters on oVirt datacenter.

    Examples

    # Create datacenter
    - ovirt_datacenters:
        name: mydatacenter
        local: True
        compatibility_version: 4.0
        quota_mode: enabled
    
    # Remove datacenter
    - ovirt_datacenters:
        state: absent
        name: mydatacenter
    

    ovirt_clusters

    ovirt_clusters [source] module to manage oVirt clusters. This module can handle create, update and delete action with various parameters on oVirt cluster.

    Examples

    # Create cluster
    - ovirt_clusters:
        name: mycluster
        datacenter_name: mydatacenter
        cpu_type: Intel SandyBridge Family
        compatibility_version: 4.0
    
    # Remove cluster
    - ovirt_clusters:
        state: absent
        name: mycluster
    

    ovirt_networks

    ovirt_clusters [source] module to manage oVirt logical datacenter networks. This module can handle create, update and delete action with various parameters on oVirt logical datacenter networks.

    Examples

    # Create network
    - ovirt_networks:
        datacenter_name: mydatacenter
        name: mynetwork
        vlan_tag: 1
        vm_network: true
    
    # Remove network
    - ovirt_networks:
        state: absent
        name: mynetwork
    

    ovirt_storage_domains

    ovirt_storage_domains [source] module to manage oVirt storage domains. This module can handle present, absent and maintanence state of the storage domain with various parameters. The supported storage domains types are nfs, iscsi, posixfs, glusterfs and fcp. User can also handle importing of export/iso storage domain.

    Examples

    # Add data NFS storage domain
    - ovirt_storage_domains:
        name: data_nfs
        host: myhost
        data_center: mydatacenter
        nfs:
          address: 10.34.63.199
          path: /path/data
    
    # Add data iSCSI storage domain:
    - ovirt_storage_domains:
        name: data_iscsi
        host: myhost
        data_center: mydatacenter
        iscsi:
          target: iqn.2016-08-09.domain-01:nickname
          lun_id: 1IET_000d0002
          address: 10.34.63.204
    
    # Import export NFS storage domain:
    - ovirt_storage_domains:
        domain_function: export
        host: myhost
        data_center: mydatacenter
        nfs:
          address: 10.34.63.199
          path: /path/export
    
    # Remove storage domain
    - ovirt_storage_domains:
        state: absent
        name: mystorage_domain
        format: true
    

    ovirt_hosts

    ovirt_hosts [source] module to manage oVirt hosts. This module can handle present, absent, upgraded and maintanence state of the host with various parameters.

    Examples

    # Add host with username/password
    - ovirt_hosts:
        cluster: Default
        name: myhost
        address: 10.34.61.145
        password: secret
    
    # Add host using public key
    - ovirt_hosts:
        public_key: true
        cluster: Default
        name: myhost2
        address: 10.34.61.145
    
    # Switch host into maintenance mode:
    - ovirt_hosts:
        state: maintenance
        name: myhost
    
    # Upgrade host:
    - ovirt_hosts:
        state: upgraded
        name: myhost
    
    # Remove host:
    - ovirt_hosts:
        state: absent
        name: myhost
        force: true
    

    ovirt_host_pm

    ovirt_host_pm [source] module to manage oVirt host power management. This module can handle create, update and delete action with various parameters on oVirt host power management.

    Examples

    # Add fence agent to host 'myhost'
    - ovirt_host_pm:
        name: myhost
        address: 1.2.3.4
        options:
          myoption1: x
          myoption2: y
        username: admin
        password: admin
        type: ipmilan
    
    # Remove ipmilan fence agent with address 1.2.3.4 on host 'myhost'
    - ovirt_host_pm:
        state: absent
        name: myhost
        address: 1.2.3.4
        type: ipmilan
    

    ovirt_host_networks

    ovirt_host_networks [source] module to manage oVirt host networks. This module can create/remove bonds on host interfaces and manage logical networks, labels and vlans above them.

    Examples

    # Create bond on eth0 and eth1 interface, and put 'myvlan' network on top of it:
    - ovirt_host_networks:
        name: myhost
        bond:
          name: bond0
          mode: 2
          interfaces:
            - eth0
            - eth1
        network: myvlan
    
    # Assign network label to host interface
    - ovirt_host_networks:
        name: myhost
        interface: eth0
        labels:
          - network_label1
    
    # Assign network to host interface
    - ovirt_host_networks:
        name: myhost
        interface: eth0
        network: ovirtmgmt
    
    # Detach network from host
    - ovirt_host_networks:
        state: absent
        name: myhost
        network: myvlan
    

    ovirt_external_providers

    ovirt_external_providers [source] module to manage oVirt external providers. This module can handle create, update and delete action with various parameters on oVirt external providers. Supported external providers are OpenStackImageProvider, OpenStackNetworkProvider, OpenStackVolumeProvider and ExternalHostProvider.

    Examples

    # Add image external provider:
    - ovirt_external_providers:
        name: image_provider
        type: os_image
        url: http://10.34.63.71:9292
        username: admin
        password: 123456
        tenant: admin
        auth_url: http://10.34.63.71:35357/v2.0/
    
    # Remove image external provider:
    - ovirt_external_providers:
        state: absent
        name: image_provider
        type: os_image
    

    ovirt_nics

    ovirt_nicshttp://docs.ansible.com/ansible/ovirt_nics_module.html) [source] module to manage oVirt virtual machines network interfaces. This module can handle present, absent, plugged and unplugged state of the network interface with various parameters.

    Examples

    # Add NIC to VM
    - ovirt_nics:
        state: present
        vm_name: myvm
        name: mynic
        interface: e1000
        mac_address: 00:1a:4a:16:01:56
        profile: ovirtmgmt
    
    # Plug NIC to VM
    - ovirt_nics:
        state: plugged
        vm_name: myvm
        name: mynic
    
    # Unplug NIC from VM
    - ovirt_nics:
        state: unplugged
        vm_name: myvm
        name: mynic
    
    # Remove NIC from VM
    - ovirt_nics:
        state: absent
        vm_name: myvm
        name: mynic
    

    ovirt_templates

    ovirt_templates [source] module to manage oVirt templates. This module can handle present, absent, imported and exported state of the template with various parameters.

    Examples

    # Create template from VM
    - ovirt_templates:
        cluster: Default
        name: mytemplate
        vm_name: rhel7
        cpu_profile: Default
        description: Test
    
    # Import template
    - ovirt_templates:
      state: imported
      name: mytemplate
      export_domain: myexport
      storage_domain: mystorage
      cluster: mycluster
    
    # Remove template
    - ovirt_templates:
        state: absent
        name: mytemplate
    

    ovirt_vmpools

    ovirt_vmpools [source] module to manage oVirt templates. This module can handle present, absent state of the vmpool with various parameters.

    Examples

    # Create vm pool from template
    - ovirt_vmpools:
        cluster: Default
        name: myvmpool
        template: rhel7
        vm_count: 2
        prestarted: 2
        vm_per_user: 1
    
    # Remove vmpool
    - ovirt_vmpools:
        state: absent
        name: myvmpool
        force: true
    

    ovirt_users

    ovirt_users [source] module to manage oVirt users. This module can handle create and delete action with various parameters on oVirt users.

    Examples

    # Add user user1 from authorization provider example.com-authz
    ovirt_users:
        name: user1
        domain: example.com-authz
    
    # Add user user1 from authorization provider example.com-authz
    # In case of Active Directory specify UPN:
    ovirt_users:
        name: user1@ad2.example.com
        domain: example.com-authz
    
    # Remove user user1 with authorization provider example.com-authz
    ovirt_users:
        state: absent
        name: user1
        domain: example.com-authz
    

    ovirt_groups

    ovirt_groups [source] module to manage oVirt groups. This module can handle create and delete action with various parameters on oVirt groups.

    Examples

    # Add group group1 from authorization provider example.com-authz
    ovirt_groups:
        name: group1
        domain: example.com-authz
    
    # Add group group1 from authorization provider example.com-authz
    # In case of multi-domain Active Directory setup, you should pass
    # also namespace, so it adds correct group:
    ovirt_groups:
        name: group1
        namespace: dc=ad2,dc=example,dc=com
        domain: example.com-authz
    
    # Remove group group1 with authorization provider example.com-authz
    ovirt_groups:
        state: absent
        name: group1
        domain: example.com-authz
    

    ovirt_permissions

    ovirt_permissions [source] module to manage oVirt permissions. This module can handle assigning and removing of permissions to oVirt entities.

    Examples

    # Add user user1 from authorization provider example.com-authz
    - ovirt_permissions:
        user_name: user1
        authz_name: example.com-authz
        object_type: virtual_machine
        object_name: myvm
        role: UserVmManager
    
    # Remove permission from user
    - ovirt_permissions:
        state: absent
        user_name: user1
        authz_name: example.com-authz
        object_type: cluster
        object_name: mycluster
        role: ClusterAdmin
    

    ovirt_affinity_labels

    ovirt_affinity_labels [source] module to manage oVirt affinity labels. This module can handle assigning and removing of affinity lables to oVirt hosts and virtaul machines.

    Examples

    # Create(if not exists) and assign affinity label to vms vm1 and vm2 and host host1
    - ovirt_affinity_labels:
        name: mylabel
        cluster: mycluster
        vms:
          - vm1
          - vm2
        hosts:
          - host1
    
    # To detach all VMs from label
    - ovirt_affinity_labels:
        name: mylabel
        cluster: mycluster
        vms: []
    
    # Remove affinity label
    - ovirt_affinity_labels:
        state: absent
        name: mylabel
    

    ovirt_mac_pools

    ovirt_mac_pools [source] module to manage oVirt MAC pools. This module can handle creating and removing of MAC pools in oVirt.

    Examples

    # Create MAC pool:
    - ovirt_mac_pools:
        name: mymacpool
        allow_duplicates: false
        ranges:
          - 00:1a:4a:16:01:51,00:1a:4a:16:01:61
          - 00:1a:4a:16:02:51,00:1a:4a:16:02:61
          
    # Remove MAC pool:
    - ovirt_mac_pools:
        state: absent
        name: mymacpool
    

    ovirt_quotas

    ovirt_quotas [source] module to manage oVirt quotas. This module can handle creating and removing of quotas in oVirt and also manging it's resources on cluster and storage.

    Examples

    # Add cluster quota to all clusters with memory limit 30GiB and CPU limit to 15:
    ovirt_quotas:
        name: quota2
        datacenter: dcX
        clusters:
            - memory: 30
              cpu: 15
    # Add storage quota to storage data1 with size limit to 100GiB
    ovirt_quotas:
        name: quota3
        datacenter: dcX
        storage_grace: 40
        storage_threshold: 60
        storages:
            - name: data1
              size: 100
    # Remove quota quota1 (Note the quota must not be assigned to any VM/disk):
    ovirt_quotas:
        state: absent
        datacenter: dcX
        name: quota1
    

    Playbook execution example

    Workspace

    First we need to create directory where we will store our playbooks and inventory.

    $ mkdir $HOME/ovirt-ansible
    

    Additional modules

    In this example we will use all modules which will be part of the Ansible 2.3, which is not yet realeased, so please first download all releveant modules and put them into library directory.

    $ mkdir $HOME/ovirt-ansible/library
    $ wget https://github.com/ansible/ansible/tree/devel/lib/ansible/modules/cloud/ovirt/ovirt_clusters.py
    ...
    

    Ansible configuration

    cat >> $HOME/ovirt-ansible/ansible.cfg << EOF
    [default]
    library = HOME/ovirt-ansible/library
    

    Vault

    Create vault with oVirt user password, so we don't use this password in plaintext. There is tool which make it easy for your, just enter this command:

    $ ansible-vault create ovirt_password.yml
    

    This will fire up your editor. Create there password variable with password of your admin@internal user:

    password: MySuperPasswordOfAdminAtInternal
    

    Next it will ask your for a vault password and then it creates ovirt_password.yml file, with your vault.

    Playbook creation

    Create a playbook, with tasks you want to execute: ```yaml cat » playbooks/setup_demo.yml « EOF — - name: Setup oVirt environment hosts: localhost connection: local vars_files: - my_vars.yml tasks: - block: - name: Include oVirt password no_log: true include_vars: ovirt_password.yml

        - name: Obtain SSO token
          ovirt_auth:
            url: "{{ url }}"
            username: "{{ username }}"
            password: "{{ password }}"
            ca_file: "{{ ca_file }}"
    
        - name: Create datacenter
          ovirt_datacenters:
            auth: "{{ ovirt_auth }}"
            name: "{{ datacenter }}"
            description: mydatacenter
            local: false
            compatibility_version: 4.0
            quota_mode: disabled
    
        - name: Create cluster
          ovirt_clusters:
            auth: "{{ ovirt_auth }}"
            datacenter_name: "{{ datacenter }}"
            name: "{{ cluster }}"
            cpu_type: Intel Nehalem Family
            description: mycluster
            compatibility_version: 4.0
    
        - name: Add host using public key
          ovirt_hosts:
            auth: "{{ ovirt_auth }}"
            public_key: true
            cluster: "{{ cluster }}"
            name: "{{ host }}"
            address: "{{ host_address }}"
    
        - name: Add data NFS storage domain
          ovirt_storage_domains:
            auth: "{{ ovirt_auth }}"
            name: "{{ data_name }}"
            host: "{{ host }}"
            data_center: "{{ datacenter }}"
            nfs:
              address: 10.34.63.199
              path: /omachace/data
    
        - name: Add data iSCSI storage domain
          ovirt_storage_domains:
            auth: "{{ ovirt_auth }}"
            name: "{{ iscsi_name }}"
            host: "{{ host }}"
            data_center: "{{ datacenter }}"
            iscsi:
              target: iqn.2016-08-09.brq.str-01:omachace
              lun_id: 1IET_000d0002
              address: 10.34.63.204
          ignore_errors: true
    
        - name: Import export NFS storage domain
          ovirt_storage_domains:
            auth: "{{ ovirt_auth }}"
            name: "{{ export_name }}"
            host: "{{ host }}"
            domain_function: export
            data_center: "{{ datacenter }}"
            nfs:
              address: 10.34.63.199
              path: /omachace/export
    
        - name: Create ISO NFS storage domain
          ovirt_storage_domains:
            auth: "{{ ovirt_auth }}"
            name: "{{ iso_name }}"
            host: "{{ host }}"
            domain_function: iso
            data_center: "{{ datacenter }}"
            nfs:
              address: 10.34.63.199
              path: /omachace/iso
    
        - name: Add image external provider
          ovirt_external_providers:
            auth: "{{ ovirt_auth }}"
            name: "{{ external_provider }}"
            type: os_image
            url: http://10.34.63.71:9292
            username: admin
            password: qum5net
            tenant: admin
            auth_url: http://10.34.63.71:35357/v2.0/
    
        - name: Import template
          ovirt_templates:
            auth: "{{ ovirt_auth }}"
            name: "{{ template }}"
            state: imported
            export_domain: "{{ export_name }}"
            storage_domain: "{{ data_name }}"
            cluster: "{{ cluster }}"
    
        - name: Create and run VM from template
          ovirt_vms:
            auth: "{{ ovirt_auth }}"
            name: "{{ vm }}"
            template: "{{ template }}"
            cluster: "{{ cluster }}"
            memory: 1GiB
            high_availability: true
            cloud_init:
              host_name: mydomain.local
              custom_script: |
                write_files:
                 - content: |
                     Hello, world!
                   path: /tmp/greeting.txt
                   permissions: '0644'
              user_name: root
              root_password: '1234567'
    
      always:
        - name: Revoke the SSO token
          ovirt_auth:
            state: absent
            ovirt_auth: "{{ ovirt_auth }}" EOF ```
    

    Playbook execution

    To execute the playbook run following command: ```bash $ cd $HOME/ovirt-ansible $ ansible-playbook playbooks/setup_demo.yml –ask-vault-pass Vault password:

    PLAY [Setup oVirt environment] *****************

    TASK [setup] *********************** ok: [localhost]

    TASK [Include oVirt password] ****************** ok: [localhost] ….. ``` It will ask you for the password of the vault and then execute the playbook. Now try to re-run the playbook, and see that no changes was done on environment.