{"id":15759319,"url":"https://github.com/cirrax/puppet-libvirt","last_synced_at":"2025-04-15T11:08:06.381Z","repository":{"id":26768730,"uuid":"110011252","full_name":"cirrax/puppet-libvirt","owner":"cirrax","description":"puppet module for libvirt","archived":false,"fork":false,"pushed_at":"2025-04-09T13:35:09.000Z","size":428,"stargazers_count":8,"open_issues_count":3,"forks_count":26,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-09T14:08:09.311Z","etag":null,"topics":["libvirt","puppet"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cirrax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["cirrax"],"custom":["https://cirrax.com"]}},"created_at":"2017-11-08T17:59:01.000Z","updated_at":"2025-04-09T13:35:12.000Z","dependencies_parsed_at":"2024-03-15T14:44:16.170Z","dependency_job_id":"b823cf6c-5f1d-4574-98f6-b9cab9bd8a41","html_url":"https://github.com/cirrax/puppet-libvirt","commit_stats":{"total_commits":242,"total_committers":19,"mean_commits":"12.736842105263158","dds":"0.33884297520661155","last_synced_commit":"a7b89928758d19cd35e1da8d42d6b904b76c707d"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cirrax%2Fpuppet-libvirt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cirrax%2Fpuppet-libvirt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cirrax%2Fpuppet-libvirt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cirrax%2Fpuppet-libvirt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cirrax","download_url":"https://codeload.github.com/cirrax/puppet-libvirt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248728781,"owners_count":21152296,"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","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"],"created_at":"2024-10-04T10:04:44.035Z","updated_at":"2025-04-15T11:08:06.371Z","avatar_url":"https://github.com/cirrax.png","language":"Ruby","funding_links":["https://github.com/sponsors/cirrax","https://cirrax.com"],"categories":[],"sub_categories":[],"readme":"# libvirt puppet module\n\n[![PDK](https://github.com/cirrax/puppet-libvirt/actions/workflows/pdk.yml/badge.svg)](https://github.com/cirrax/puppet-libvirt/actions/workflows/pdk.yml)\n[![Puppet Forge](https://img.shields.io/puppetforge/v/cirrax/libvirt.svg?style=flat-square)](https://forge.puppetlabs.com/cirrax/libvirt)\n[![Puppet Forge](https://img.shields.io/puppetforge/dt/cirrax/libvirt.svg?style=flat-square)](https://forge.puppet.com/cirrax/libvirt)\n[![Puppet Forge](https://img.shields.io/puppetforge/e/cirrax/libvirt.svg?style=flat-square)](https://forge.puppet.com/cirrax/libvirt)\n[![Puppet Forge](https://img.shields.io/puppetforge/f/cirrax/libvirt.svg?style=flat-square)](https://forge.puppet.com/cirrax/libvirt)\n\n#### Table of Contents\n\n1. [Overview](#overview)\n1. [Description](#description)\n1. [Usage](#usage)\n1. [Reference](#reference)\n1. [Profiles](#profiles)\n1. [Limitations](#limitations)\n1. [Contributing](#contributing)\n\n## Upgrade warnings\n\nUpgrading to puppet 8 comes with Ruby 3, which doesn't have the `rexml` gem bundled.\nIt should be [installed on the puppetserver](https://www.puppet.com/docs/puppet/7/server/gems.html#installing-and-removing-gems).\n\n```bash\nsudo puppetserver gem install rexml\n```\n\nUpgrade to version 5.x.x introduced types/providers for network, nwfilter and domains\nreplacing the execs used before version 5.0.0. To compare the XML's generated with puppet and\nthe actual running XML's generated with virsh they are sorted which leads to display lots of\nchanges if you use the diff_dir functionality.\n\nVersion 5.0.0 also introduce a generic template for network and nwfilter which should be more flexible\nto define the configurations needed (the 'old' templates are still default).\n\nUpgrade to version 4.x.x will probably break any existing setup (puppet run fails),\nsince several parameters of libvirt::domain are now deprecated in favor of using\nprofiles. To make upgrade easier (and see what happens), upgrade to version 3.1.x and\nset libvirt::diff_dir. Like this you can see the changes to be applied after the upgrade.\n\n## Overview\n\nPuppet module to install libvirt and create virtual domain\nconfiguration. This module has very minimal external dependencies and\ntries to not make any assumptions about how you want to setup your\nvirtual machines.\nCertain profiles can be defined and used for a set of VM's\n\nThe module contains helper scripts to manage VMs on a 2 node cluster\nwith disk replication over DRBD. But this is completely optional.\n\nRemark: Debian \u003e= 12 (bullseye) and Ubuntu \u003e= 21.10 uses architecture\n        specific packages. Currently amd64 is configured. Merge requests\n        for other architectures are welcome!\n\n## Description\n\nThis module tries to adhere to the Unix philosophy of doing one thing\nbut doing it right. It installs and configures libvirt and virtual\ndomains, but does not do the basic setup of your networking bridge or\nconfigure the disks used by the virtual domains. This is left to other\npuppet modules.\n\nFor a basic setup you have to include the `libvirt` class, define a\n`libvirt::network` and a `libvirt::domain`.\n\nAs an optional add-on this module contains a libvirt hook and a\nPython management script to create a 2 node cluster with disks\nreplicated over DRBD. This setup allows live migration of VMs from one\nnode to the other.\n\nA complete working solution can be achived by integrating the following\nmodules in addition to this module:\n\n* [puppetlabs-lvm](http://forge.puppetlabs.com/puppetlabs/lvm)\n* [puppet-drbd](https://forge.puppet.com/puppet/drbd) (only\n  for DRBD setups)\n* [puppet-vswitch](https://forge.puppet.com/openstack/vswitch)\n  (only when using OpenvSwitch)\n\n## Usage\n\nInstall libvirt:\n\n```puppet\ninclude 'libvirt'\n```\n\nInstall including the DRBD hook:\n\n```puppet\nclass {'libvirt':\n  qemu_hook =\u003e 'drbd',\n}\n```\n\nIf you want to see the diffs of the xml file generated, set libvirt::diff_dir to a\ndirectory. As a result all generated XML files are stored there, and diffs are\nvisible.\n\nDefine a network (basic linux bridge example):\n\n```puppet\nlibvirt::network { 'net-simple':\n  forward_mode =\u003e 'bridge',\n  bridge       =\u003e 'br-simple',\n}\n```\n\nDefine a network (advanced openvswitch example):\n\n```puppet\nlibvirt::network { 'net-ovs':\n  forward_mode     =\u003e 'bridge',\n  bridge           =\u003e 'br-ovs',\n  virtualport_type =\u003e 'openvswitch',\n  autostart        =\u003e true,\n  portgroups       =\u003e [\n                       {'name'     =\u003e 'intern',\n                        'trunk'    =\u003e false,\n                        'vlan_tag' =\u003e '2',\n                        },\n                       {'name'     =\u003e 'trunk',\n                        'trunk'    =\u003e true,\n                        'vlan_tag' =\u003e ['100', '101', '102', ],\n                        },\n                       ],\n}\n```\n\nDefine a domain (VM):\n\n```puppet\nlibvirt::domain { 'my-domain':\n  devices_profile =\u003e 'default',\n  dom_profile     =\u003e 'default',\n  boot            =\u003e 'hd',\n  domconf         =\u003e { memory =\u003e { values =\u003e '2048', attrs =\u003e { unit =\u003e 'MiB' }}},\n  disks           =\u003e [{'type' =\u003e 'block',\n                       'device' =\u003e 'disk',\n                       'source' =\u003e {'dev' =\u003e '/dev/vm-pool/my-domain.img'},\n                       },\n                      {'type'   =\u003e 'file',\n                       'device' =\u003e 'disk',\n                       'source' =\u003e {'dev' =\u003e '/var/lib/libvirt/images/my-disk.qcow2'},\n                       'bus'    =\u003e 'virtio',\n                       'driver' =\u003e {'name'  =\u003e 'qemu',\n                                    'type'  =\u003e 'qcow2',\n                                    'cache' =\u003e 'none',\n                                    },\n                      ],\n  interfaces      =\u003e [{'source' =\u003e {'network' =\u003e 'net-simple'}}],\n  autostart       =\u003e true,\n}\n```\n\t\nDefine a domain (VM) with a bridged network:\n*the network device must exist*\n```\n    libvirt::domain { 'my-domain':\n      devices_profile =\u003e 'default',\n      dom_profile     =\u003e 'default',\n      boot            =\u003e 'hd',\n      domconf         =\u003e { memory =\u003e { values =\u003e '2048', attrs =\u003e { unit =\u003e 'MiB' }}},\n      disks           =\u003e [{'type' =\u003e 'block',\n                           'device' =\u003e 'disk',\n                           'source' =\u003e {'dev' =\u003e '/dev/vm-pool/my-domain.img'},\n                           },\n                          {'type'   =\u003e 'file',\n                           'device' =\u003e 'disk',\n                           'source' =\u003e {'dev' =\u003e '/var/lib/libvirt/images/my-disk.qcow2'},\n                           'bus'    =\u003e 'virtio',\n                           'driver' =\u003e {'name'  =\u003e 'qemu',\n                                        'type'  =\u003e 'qcow2',\n                                        'cache' =\u003e 'none',\n                                        },\n                          ],\n      interfaces      =\u003e [{ 'interface_type =\u003e 'bridge',\n                            'source'        =\u003e { 'bridge' =\u003e virbr0', },\n\t\t         }],\n      autostart       =\u003e true,\n    }\n```\n\nDefine a storage pool:\n\n```puppet\nlibvirt_pool { 'default' :\n  ensure     =\u003e present,\n  type       =\u003e 'logical',\n  autostart  =\u003e true,\n  sourcedev  =\u003e '/dev/sda5',\n  sourcename =\u003e 'vm',\n  target     =\u003e '/dev/vm',\n}\n```\n\nComplete documentation is included in puppet doc format in the\nmanifest files or in the REFERENCE.md file.\n\n## Reference\n\nThe detailed configuration of all parameters is found in the REFERENCE.md file generated from\nthe strings in the manifests.\n\n## Profiles\n\nProfiles are a set of values to add to the configuration, eg. some devices you like to add\nto all VM's (keyboard etc.)\n\nThe default profile used is defined in hiera in the data/profiles directory.\nThe profiles in hiera are hash merged, so you can define you're own profiles easily.\nHere is an example:\n\n```yaml\nlibvirt::profiles::devices:\n  myprofile:\n    hostdev:\n      attrs:\n        mode: 'capabilities'\n        type: 'misc'\n      values:\n        source:\n           values: '/dev/input/event3'\n```\n\nwill result in a device (without the default devices...):\n\n```xml\n\u003chostdev mode='capabilities' type='misc'\u003e\n  \u003csource\u003e\n    \u003cchar\u003e/dev/input/event3\u003c/char\u003e\n  \u003c/source\u003e\n\u003c/hostdev\u003e\n```\n\nTo not repeat all profile values you can 'inherit' a profile, meaning you set a base profile with wich the profile will be merged.\nLet's take enlarge our profile:\n\n```yaml\n---\nlibvirt::profiles::devices:\n  myprofile:\n    profileconfig:\n      base: 'default'\n      merge: 'merge'\n    hostdev:\n      ...\n```\n\nwhich results in the hostdev been added to the default profile. Merge parameter in profileconfig defines how to merge,\nvalid values are merge (default) or deep for a deep merge.\n\nHint: To better see what is changing you can set libvirt::diff_dir to a directory.\n\n## Limitations\n\nThings currently not supported:\n\n* Operating Systems other than Debian, Ubuntu or RedHat. Adding support for other\n  systems is a matter of defining the relevant parameters in hiera.\n* Documentation always needs some love ;) I would especially appreciate some examples of\n  profiles you are using.\n\nPatches to support any of these (or other) missing features are welcome.\n\n## Contributing\n\nPlease report bugs and feature request using GitHub issue tracker.\n\nFor pull requests, it is very much appreciated to check your Puppet manifest with puppet-lint\nand the available spec tests  in order to follow the recommended Puppet style guidelines\nfrom the Puppet Labs style guide.\n\n### Authors\n\nThis module is mainly written by [Cirrax GmbH](https://cirrax.com).\n\nSee the [list of contributors](https://github.com/cirrax/puppet-libvirt/graphs/contributors)\nfor a list of all contributors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirrax%2Fpuppet-libvirt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcirrax%2Fpuppet-libvirt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirrax%2Fpuppet-libvirt/lists"}