{"id":18925618,"url":"https://github.com/jm1/ansible-collection-jm1-libvirt","last_synced_at":"2025-04-15T13:32:15.626Z","repository":{"id":38842610,"uuid":"265544482","full_name":"JM1/ansible-collection-jm1-libvirt","owner":"JM1","description":"Ansible Collection for using libvirt https://galaxy.ansible.com/jm1/libvirt","archived":false,"fork":false,"pushed_at":"2024-08-08T12:50:03.000Z","size":147,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-08T15:08:15.631Z","etag":null,"topics":["ansible","ansible-collection","ansible-galaxy","ansible-modules","ansible-roles","libvirt"],"latest_commit_sha":null,"homepage":"","language":"Python","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/JM1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2020-05-20T11:30:45.000Z","updated_at":"2024-08-08T12:50:07.000Z","dependencies_parsed_at":"2024-05-30T10:05:05.727Z","dependency_job_id":"8221a53b-911a-4a11-8ab1-c4c46767c03d","html_url":"https://github.com/JM1/ansible-collection-jm1-libvirt","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JM1%2Fansible-collection-jm1-libvirt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JM1%2Fansible-collection-jm1-libvirt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JM1%2Fansible-collection-jm1-libvirt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JM1%2Fansible-collection-jm1-libvirt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JM1","download_url":"https://codeload.github.com/JM1/ansible-collection-jm1-libvirt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223672991,"owners_count":17183618,"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":["ansible","ansible-collection","ansible-galaxy","ansible-modules","ansible-roles","libvirt"],"created_at":"2024-11-08T11:12:38.019Z","updated_at":"2024-11-08T11:12:38.625Z","avatar_url":"https://github.com/JM1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ansible Collection for using libvirt\n\nThis repo hosts the Ansible collection [`jm1.libvirt`](https://galaxy.ansible.com/jm1/libvirt).\n\nThe collection includes a variety of Ansible content to help automate the provisioning and maintenance of libvirt\nclusters.\n\nIt is inspired by the [Ansible OpenStack collection][openstack-cloud]. For example, [`jm1.libvirt.domain`][\njm1-libvirt-domain] and [`jm1.libvirt.volume_cloudinit`][jm1-libvirt-volume-cloudinit] resemble\n[`openstack.cloud.server`][openstack-cloud-server] to create virtual machines with [libvirt][libvirt] and\n[cloud-init][cloud-init-doc]:\n\n[cloud-init-doc]: https://cloudinit.readthedocs.io/\n[jm1-libvirt-domain]: plugins/modules/domain.py\n[jm1-libvirt-volume-cloudinit]: plugins/modules/volume_cloudinit.py\n[libvirt]: https://libvirt.org/\n[openstack-cloud]: https://galaxy.ansible.com/openstack/cloud\n[openstack-cloud-server]: https://docs.ansible.com/ansible/latest/collections/openstack/cloud/server_module.html\n\n```yaml\n- hosts: all\n  tasks:\n    - name: Install software required by jm1.libvirt's roles and modules\n      import_role:\n        name: jm1.libvirt.setup\n\n    - name: Fetch cloud image, create storage volumes and define domain (virtual machine)\n      import_role:\n        name: jm1.libvirt.server\n      vars:\n        userdata: |\n            #cloud-config\n            hostname: {{ inventory_hostname }}\n```\n\nIn comparison to the `community.libvirt.virt_*` modules of the [community.libvirt][community.libvirt] collection,\nall `jm1.libvirt.*` modules are *idempotent*, that is they can be applied multiple times without changing the result\nbeyond the initial application. To create libvirt domains (virtual machines), storage pools or volumes you write\n[`virsh`][virsh]-like options in Ansible-idiomatic [YAML lists][ansible-yaml-syntax]. For example:\n\n```yaml\n- jm1.libvirt.pool\n    name: default\n    hardware:\n        # Commandline arguments of 'virsh pool-define-as' as key-value pairs without\n        # the two leading dashs and all other dashs replaced by underscores.\n        type: dir\n        target: '/var/lib/libvirt/images'\n```\n\nNo need to write XML documents as with e.g. [`community.libvirt.virt`][community-libvirt-virt] or\n[`community.libvirt.virt_pool`][community-libvirt-virt-pool].\n\n[virsh]: https://libvirt.org/manpages/virsh.html\n[community.libvirt]: https://galaxy.ansible.com/community/libvirt\n[community-libvirt-virt]: https://docs.ansible.com/ansible/latest/collections/community/libvirt/virt_module.html\n[community-libvirt-virt-pool]: https://docs.ansible.com/ansible/latest/collections/community/libvirt/virt_pool_module.html\n[ansible-yaml-syntax]: https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html\n\n## Included content\n\nClick on the name of a module or role to view that content's documentation:\n\n- **Modules**:\n    * [domain](plugins/modules/domain.py)\n    * [net_xml](plugins/modules/net_xml.py)\n    * [pool](plugins/modules/pool.py)\n    * [pool_xml](plugins/modules/pool_xml.py)\n    * [volume](plugins/modules/volume.py)\n    * [volume_cloudinit](plugins/modules/volume_cloudinit.py)\n    * [volume_import](plugins/modules/volume_import.py)\n    * [volume_snapshot](plugins/modules/volume_snapshot.py)\n- **Module Utils**:\n    * [libvirt](plugins/module_utils/libvirt.py)\n- **Roles**:\n    * [server](roles/server/README.md)\n    * [setup](roles/setup/README.md)\n\n## Requirements and Installation\n\n### Installing necessary software\n\nContent in this collection requires additional roles and collections, e.g. to collect operating system facts. You can\nfetch them from Ansible Galaxy using the provided [`requirements.yml`](requirements.yml):\n\n```sh\nansible-galaxy collection install --requirements-file requirements.yml\nansible-galaxy role install --role-file requirements.yml\n# or\nmake install-requirements\n```\n\nContent in this collection requires additional tools and libraries, e.g. to interact with libvirt's APIs. You can use\nrole [`jm1.libvirt.setup`](roles/setup/README.md) to install necessary software packages:\n\n```yaml\n- hosts: all\n  roles:\n    - jm1.libvirt.setup\n```\n\nOr to install these packages locally:\n\n```sh\nsudo -s\n\nansible-console localhost \u003c\u003c EOF\ngather_facts\ninclude_role name=jm1.libvirt.setup\nEOF\n```\n\nThe exact requirements for every module and role are listed in the corresponding documentation.\nSee the module documentations for the minimal version supported for each module.\n\n### Installing the Collection from Ansible Galaxy\n\nBefore using the `jm1.libvirt` collection, you need to install it with the Ansible Galaxy CLI:\n\n```sh\nansible-galaxy collection install jm1.libvirt\n```\n\nYou can also include it in a `requirements.yml` file and install it via\n`ansible-galaxy collection install -r requirements.yml`, using the format:\n\n```yaml\n---\ncollections:\n  - name: jm1.libvirt\n    version: 2024.8.8\n```\n\n## Usage and Playbooks\n\nYou can either call modules by their Fully Qualified Collection Name (FQCN), like `jm1.libvirt.domain`, or you can call\nmodules by their short name if you list the `jm1.libvirt` collection in the playbook's `collections`, like so:\n\n```yaml\n---\n- name: Using jm1.libvirt collection\n  hosts: localhost\n\n  collections:\n    - jm1.libvirt\n\n  tasks:\n    - name: Satisfy software requirements\n      import_role:\n        name: setup\n\n    - name: Create a new libvirt domain with cloud-init\n      domain:\n        name: 'vm.inf.h-brs.de'\n```\n\nFor documentation on how to use individual modules and other content included in this collection, please see the links\nin the 'Included content' section earlier in this README.\n\nSee [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more\ndetails.\n\n## Contributing\n\nThere are many ways in which you can participate in the project, for example:\n\n- Submit bugs and feature requests, and help us verify them\n- Submit pull requests for new modules, roles and other content\n\nWe're following the general Ansible contributor guidelines;\nsee [Ansible Community Guide](https://docs.ansible.com/ansible/latest/community/index.html).\n\nIf you want to develop new content for this collection or improve what is already here, the easiest way to work on the\ncollection is to clone this repository (or a fork of it) into one of the configured [`ANSIBLE_COLLECTIONS_PATHS`](\nhttps://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths) and work on it there:\n1. Create a directory `ansible_collections/jm1`;\n2. In there, checkout this repository (or a fork) as `libvirt`;\n3. Add the directory containing `ansible_collections` to your\n   [`ANSIBLE_COLLECTIONS_PATHS`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths).\n\nHelpful tools for developing collections are `ansible`, `ansible-doc`, `ansible-galaxy`, `ansible-lint`, `flake8`,\n`make` and `yamllint`.\n\n| OS                                           | Install Instructions                                                |\n| -------------------------------------------- | ------------------------------------------------------------------- |\n| Debian 10 (Buster)                           | Enable [Backports](https://backports.debian.org/Instructions/). `apt install ansible ansible-doc ansible-lint flake8 make yamllint` |\n| Debian 11 (Bullseye)                         | `apt install ansible ansible-lint flake8 make yamllint` |\n| Debian 12 (Bookworm)                         | `apt install ansible ansible-lint flake8 make yamllint` |\n| Debian 13 (Trixie)                           | `apt install ansible ansible-lint flake8 make yamllint` |\n| Fedora                                       | `dnf install ansible python3-flake8 make yamllint` |\n| Red Hat Enterprise Linux (RHEL) 7 / CentOS 7 | Enable [EPEL](https://fedoraproject.org/wiki/EPEL). `yum install ansible ansible-lint ansible-doc  python-flake8 make yamllint` |\n| Red Hat Enterprise Linux (RHEL) 8 / CentOS 8 | Enable [EPEL](https://fedoraproject.org/wiki/EPEL). `yum install ansible                          python3-flake8 make yamllint` |\n| Red Hat Enterprise Linux (RHEL) 9 / CentOS 9 | Enable [EPEL](https://fedoraproject.org/wiki/EPEL). `yum install ansible                          python3-flake8 make yamllint` |\n| Ubuntu 18.04 LTS (Bionic Beaver)             | Enable [Launchpad PPA Ansible by Ansible, Inc.](https://launchpad.net/~ansible/+archive/ubuntu/ansible). `apt install ansible ansible-doc ansible-lint flake8 make yamllint` |\n| Ubuntu 20.04 LTS (Focal Fossa)               | Enable [Launchpad PPA Ansible by Ansible, Inc.](https://launchpad.net/~ansible/+archive/ubuntu/ansible). `apt install ansible ansible-doc ansible-lint flake8 make yamllint` |\n| Ubuntu 22.04 LTS (Jammy Jellyfish)           | `apt install ansible ansible-lint flake8 make yamllint` |\n| Ubuntu 24.04 LTS (Noble Numbat)              | `apt install ansible ansible-lint flake8 make yamllint` |\n\nHave a look at the included [`Makefile`](Makefile) for\nseveral frequently used commands, to e.g. build and lint a collection.\n\n## More Information\n\n- [Ansible Collection Overview](https://github.com/ansible-collections/overview)\n- [Ansible User Guide](https://docs.ansible.com/ansible/latest/user_guide/index.html)\n- [Ansible Developer Guide](https://docs.ansible.com/ansible/latest/dev_guide/index.html)\n- [Ansible Community Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html)\n\n## License\n\nGNU General Public License v3.0 or later\n\nSee [LICENSE.md](LICENSE.md) to see the full text.\n\n## Author\n\nJakob Meng\n@jm1 ([github](https://github.com/jm1), [galaxy](https://galaxy.ansible.com/jm1), [web](http://www.jakobmeng.de))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjm1%2Fansible-collection-jm1-libvirt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjm1%2Fansible-collection-jm1-libvirt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjm1%2Fansible-collection-jm1-libvirt/lists"}