{"id":30741815,"url":"https://github.com/socratesx/puppet-virt_install","last_synced_at":"2025-09-04T01:02:25.438Z","repository":{"id":57666973,"uuid":"167953149","full_name":"socratesx/puppet-virt_install","owner":"socratesx","description":"A simple module to manage Libvirt Installation, minimal network configuration and VM provisioning","archived":false,"fork":false,"pushed_at":"2019-02-11T02:43:10.000Z","size":105,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-25T07:30:33.831Z","etag":null,"topics":["libvirt","puppet","puppet-module","qemu-kvm","virt-install"],"latest_commit_sha":null,"homepage":"","language":"Puppet","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/socratesx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-28T11:45:56.000Z","updated_at":"2019-02-11T02:43:12.000Z","dependencies_parsed_at":"2022-09-02T14:00:54.855Z","dependency_job_id":null,"html_url":"https://github.com/socratesx/puppet-virt_install","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/socratesx/puppet-virt_install","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socratesx%2Fpuppet-virt_install","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socratesx%2Fpuppet-virt_install/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socratesx%2Fpuppet-virt_install/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socratesx%2Fpuppet-virt_install/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/socratesx","download_url":"https://codeload.github.com/socratesx/puppet-virt_install/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socratesx%2Fpuppet-virt_install/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273355639,"owners_count":25090825,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["libvirt","puppet","puppet-module","qemu-kvm","virt-install"],"created_at":"2025-09-04T01:02:24.196Z","updated_at":"2025-09-04T01:02:25.376Z","avatar_url":"https://github.com/socratesx.png","language":"Puppet","readme":"# Puppet Module: virt_install\nA simple module to manage Libvirt Installation, minimal network configuration and VM provisioning\n\n\u003ch2\u003e Description \u003c/h2\u003e\n\nThis puppet module can execute the following tasks:\n- Install libvirt packages per OS and configure libvirtd service to run on startup\n- Create a minimal network configuration for libvirt. It creates a Bridge interface and attaches the primary interface to it.\n- Define new VMs declared either from yaml files, each file one VM declaration, or from inline Hash variable.\n- Undefine existing VMs.\n\n\u003ch3\u003eClasses\u003c/h3\u003e\n\nThe following classes are included:\n\n- \u003cb\u003einit\u003c/b\u003e: Default class, if the user use include-like statements the class by default will call all subclasses, except undefine.\n  - Parameters: None\n  \n- \u003cb\u003elibvirt_setup\u003c/b\u003e: This class is responsible for installing the libvirt hypervisor to the host and enabling its daemon.\n  - Parameters:  \n    - $iso_path:   A string representing the folder of the boot images (isos) a VM may need to boot during the runtime. By default, it       gets the value of libvirt_boot_image_folder variable found in the data/common.yaml\n    - $disk_path: A String representing the folder that will contain the VM disk image files. By default, it gets the defined value of libvirt_vm_disk_folder variable in data/common.yaml\n\n- \u003cb\u003enet_conf\u003c/b\u003e: The network cofiguration class that will create a bridge interface and attach the current primary interface to the bridge.\n  - Parameters:\n    - $br_name: A String representing the name of the bridge, e.g. 'br0'. If not set when using the class, it will check the common.yaml and will use the \"virt_install::net_conf::vm_host_br_name\" value.\n    -  $def_iface: A String representing the interface name that will be added to the bridge. It defaults to the value of the facter's primary interface and can be overriden either directly or in the common.yaml file by changing the \"virt_install::net_conf::vm_host_br_if\" variable. \n\n- \u003cb\u003evm_provisioner\u003c/b\u003e: The class the provisions new VMs either from inline declared Hash or from the yaml files, located in data/vms/. \n  - Parameters:\n    - $vms: A dictionary that contains the vm definitions as key-value pairs. The key is a reference value of the VM and the value is another dict  containing the virt-intall options as keys and the corresponding arguments as values. The Hash has the following form: \n      ```\n      {'VM1': {'opt1': 'arg1', 'opt2': 'arg2', ...},                             \n       'VM2': {'opt1': 'arg1', 'opt2': 'arg2', ...},                           \n         :                                                                      \n       'VMn': {'optn': 'argn', 'optn': 'argn', ...}                            \n      }  \n      ```\n      \u003cb\u003eVMn\u003c/b\u003e: unique key names for each VM                                        \n      \u003cb\u003eoptn\u003c/b\u003e: virt-install option name                                           \n      \u003cb\u003eargn\u003c/b\u003e: virt-install option argument                                       \n      By default, the class uses the module's custom function read_vm_files() to return the parameter after parsing all the yaml files in data/vms folder.\n\t  \n    - $boot_imgs: A String that represents the folder were the iso boot images will reside on the target machine so they can be used during VM installation. By default, it will use the parameter value on data/common.yaml file.\n\n- \u003cb\u003eundefine\u003c/b\u003e: Taking the same arguments as the previous class but reversing the action. This class destroys and undefines existing VMs on target.\n   - Parameters:\n     - $vms: A dictionary that contains the VM names in the form:\n       ```\n       {'VM1': {'name': 'VM1_name'},                                             \n        'VM2': {'name': 'VM2_name'},                                             \n          :                                                                   \n        'VMn': {'name': 'VMn_name'}                                              \n       }                                                                         \n       ```\n    \t\u003cb\u003eVMn\u003c/b\u003e: A unique key name for each VM\n\t\u003cbr\u003e\u003cb\u003ename\u003c/b\u003e: The keyword 'name'.\n\t\u003cbr\u003e\u003cb\u003eVM_name\u003c/b\u003e: The corresponding name of the VM.\n\tIf this parameter is not passed then it defaults to the VMs defined in the data/vms/*.yaml files\n   \n\n\n\n\u003ch2\u003e Usage \u003c/h2\u003e\n\nThe intended usage of the module is by defining yaml files and changing the default parameters on data/common.yaml files. The first thing, after reading the readme file, a user must do is to see the files in data/ folder. From there he/she can define new VMs and change the default parameters to suit their needs in their environment. \n\nThe classes can be used autonomously by declaring them using the resource-like declaration style:\n\n```\nclass { 'virt_install::undefine':}\n```\n\nThe above example will look for the default values in data/vms folder and will undefine all the VMs included there. You can override the default like the following:\n\n```\nclass { 'virt_install::undefine':\n          vms =\u003e { vm1 =\u003e {'name' =\u003e 'VM_NAME'} }        \n      }\n```\n\nThis time only the VM_NAME will be undefined from the target host.\n\nThe module intended usage is to mass provision libvirt domains by declaring each resource in the data/vms/ folder. This folder may contain any number of YAML files that each one contains key:value pairs of the virt-install utility where key = option and value = arguments. You can include any supported option of the virt-install utility. Options that take no arguments, like the --noautoconsole can be specified with an empty string as a value. \n\n\u003ch3\u003e The Special Arguments: cdrom, disk, \u0026 network \u003c/h3\u003e\n\nThese options have extended functionality over the original virt-install utility:\n\n\u003ch4\u003e cdrom \u003c/h4\u003e\n\nThis option defines a bootable image file that the VM will use to boot during boot-time. \nIt takes the following argument types:\n\n  - \u003cb\u003eURLS\u003c/b\u003e: It downloads the image file from the network, it support ftp, http \u0026 https. If the file is compressed then it will decompress the image file and move it to the boot folder specified by the libvirt_boot_image_folder variable found in data/common.yaml\n\n  - \u003cb\u003eAbsolute Paths\u003c/b\u003e: If an absolute path is passed, then the module will look for the image filename in files/ directory and will copy it to the path that is passed. It is required that the user have added manually the file in the files/ folder.Normally, this type should handle also symlinks but in my case this wasn't possible.\n\n  - \u003cb\u003eFilenames\u003c/b\u003e: If just a filename is passed then the module checks for that file in files/ directory and then it copies it to the default boot directory provided by libvirt_boot_image_folder variable found in data/common.yaml. It is required that the user have added manually the file in the files/ folder. Normally, this type should handle also symlinks but in my case this wasn't possible.\n\n\u003ch4\u003e disk \u003c/h4\u003e\n\nThis is a list option in VM definition file. Each item represent a disk argument, something like the following:\n\n```\ndisk:\n  - '/disk_path/a_new_disk.qcow2,bus=virtio'\n  - '/dev/sdb,bus=virtio'\n  - 'disk_path/an_existing_disk.qcow2,bus=virtio'\n```\n\nDuring runtime, the above will be converted to:\n\n```\n{...} --disk /vm-images/pfsense/pfsense.qcow2,bus=virtio --disk /dev/sdb,bus=virtio {...}\n```\n\nIf the 'size=' disk option is specified, like the first item above, the virt-install will create a new disk file. On the contrary, if the 'size=' is omitted then the virt-install assumes that the disk file is an existing file in the specified path. In this case the user must have included the disk file in the files/ folder. During runtime the module will check for the 'an_existing_disk.qcow2' file and will copy it to the specified folder, so the virt-install will detected it when invoked to the target.\n\n\u003ch4\u003e network \u003c/h4\u003e\n\nSimilarly with the disk option, the network is also defined as a list. And this is becasue a VM can have multiple NICs defined like the following example:\n\n```\nnetwork:\n  - 'bridge=br0,model=virtio'\n  - 'bridge=br0,model=virtio'\n```\n\nDuring runtime, the above will be converted to\n\n```\n{...} --network bridge=br0,model=virtio --network bridge=br0,model=virtio {...}\n```\n\n\u003ch2\u003e Examples \u003c/h2\u003e\n\nFor this example I include my use case scenario, consisting one Storage VM and one Firewall, using the free open source Xigmanas and pfSense respectively. \nAssuming that there are two VM definition files in data/vms like the following:\n\n```\n#data/vms/pfsense.yaml\n---\nname: 'pfSense'\nvcpus: '1,maxvcpus=2'\ncpu: host\nmemory: '512,maxmemory=768'\nos-variant: freebsd10\nboot: hd,cdrom,menu=on\ndisk:\n  - \"/vm-images/pfsense/pfsense.qcow2,bus=virtio\"\nnetwork:\n  - 'bridge=br0,model=virtio'\n  - 'bridge=br0,model=virtio'\ngraphics: vnc,listen=0.0.0.0,port=-1\nvirt-type: kvm\nnoautoconsole: ''\nhvm: ''\nautostart: ''\n\n#data/vms/xigmanas.yaml\n---\nname: Xigmanas\nvcpus: '2,maxvcpus=4'\ncpu: host\nmemory: '512,maxmemory=768'\nos-variant: freebsd10\nboot: hd,cdrom,menu=on\ncdrom: 'https://downloads.sourceforge.net/project/xigmanas/XigmaNAS-11.2.0.4/11.2.0.4.6315/XigmaNAS-x64-LiveCD-11.2.0.4.6315.iso'\ndisk:\n  - '/vm-images/xigmanas/xigmanas.qcow2,size=10,bus=virtio'\n  - '/dev/sdb,bus=virtio'\n  - '/dev/sdc,bus=virtio'\nnetwork:\n  - bridge=br0,model=virtio\ngraphics: vnc,listen=0.0.0.0,port=-1\nvirt-type: kvm\nnoautoconsole: ''\nhvm: ''\nautostart: ''\n\n```\n\nWe can install these vms to an already working host by just using the following code in a manifest:\n\n```\nclass { 'virt_install::vm_provisioner':}\n```\n\nWe can also undefine them\n\n```\n class { 'virt_install::undefine':}\n```\n\nIf we have an empty host just after OS installation :\n\n```\ninclude virt_install\n```\n\nor a more complicated manifest:\n\n\n```\nnode default {\n    include virt_install\n}\n\nnode ubuntu18.soc.home {\n    class { 'virt_install::libvirt_setup':}\n    class { 'virt_install::net_conf':}\n    $new_container= {\n        connect    =\u003e 'lxc:///',\n        name       =\u003e 'container',\n        memory     =\u003e '128',\n        filesystem =\u003e ['/bin/,/bin/', '/home/socratesx,/mnt/home', '/root,/mnt/root', '/root/test_lxc,/test'],\n        init       =\u003e '/bin/sh'\n    }\n    $vms = {\n        'container1' =\u003e $new_container\n    }\n    class { 'virt_install::vm_provisioner':\n        vms =\u003e $vms\n    }\n}\n\nnode debian.soc.home {\n    $new_demo = {\n        name    =\u003e 'demo',\n        memory  =\u003e '512',\n        disk    =\u003e ['/VMs/demodisk.qcow2,size=1'],\n        import  =\u003e ''\n    }\n    $vms = {\n        'vm1' =\u003e $new_demo\n    }\n    class { 'virt_install::vm_provisioner':\n        vms =\u003e $vms\n    }\n}\n\n```\n\nThe above manifest, will configure ubuntu18 as a new libvirt kvm-host, will enable a bridge interface and define a new lxc container \nas described in $container1 hash. Notice that the new container definition will override the default $vms parameter, so the yaml files in data/vms will not have any effect to this host.\n\nThe debian node is already a libvirt host running VMs, but it will just provision a new demo VM as described in the $new_demo hash. \n\nEvery other node will run the default module's init.pp which calls all classes and installs the VMs in the data/VMs folder.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocratesx%2Fpuppet-virt_install","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsocratesx%2Fpuppet-virt_install","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocratesx%2Fpuppet-virt_install/lists"}