jpartlow/Nested VMs
Standup a cluster of nested virtual machines using libvirt.
View on GitHubTrust Signals
- Scorecard Score
- not yet scored
- Maintenance Recency
- Activelast commit Jun 10, 2026
- License
- AGPL 3.0
Pinned Snippet
uses: jpartlow/nested_vms@7f2caec8ae0a5c01eb8780cdb5891bd96acfab3e # 1.4.0tags can be moved; commit SHAs can't. why a SHA?
Inputs
| name | description | required | default |
|---|---|---|---|
| os | Operating system to use for the cluster. | yes | — |
| os-version | Operating system version to use for the cluster. | yes | — |
| os-arch | Operating system arch to use for the cluster. | yes | — |
| image_version | Specific image version to download. If not specified, then the latest released os-version image will be downloaded. Examples: * Debian - daily-latest (use this for the latest pre-release version) - daily-YYYYMMDD-\d\d\d\d - YYYYMMDD-\d\d\d\d * Ubuntu - YYYYMMDD Note that there is no guarantee a given image version exists, you will need to check the image server. See [kvm_automation_tooling::get_image_url()](https://github.com/jpartlow/kvm_automation_tooling/blob/main/functions/get_image_url.pp) for details of how image urls are constructed. | — | — |
| image_url_override | If specified, this will override the image_url generated by kvm_automation_tooling::get_image_url() entirely. | — | — |
| ruby-version | Ruby version to install for the action. | yes | 3.4 |
| vms | JSON array of VM definitions as defined by the [kvm_automation_tooling::vm_spec](https://github.com/jpartlow/kvm_automation_tooling/blob/main/types/vm_spec.pp) datatype. | yes | [ { "role": "agent" } ] |
| install-openvox | Whether or not to install the openvox Puppet(TM) agent on the vms. | — | false |
| openvox-collection | — | — | openvox8 |
| openvox-version | Version of openvox to install in the cluster. The default value, 'latest', will install the latest version of openvox in the given openvox-collection. The openvox-version must match the collection (you can't request 7.y from the openvox8 collection...). If you are installing a pre-release version of openvox, then openvox-collection is ignored and openvox-version must be a specific version, not 'latest'. | — | latest |
| openvox-released | If true, install a released openvox-version from the set openvox-collection. If false, install a pre-release openvox-version package from the openvox-artifacts-url server. | — | true |
| openvox-artifacts-url | URL to the openvox build artifacts. Used to download pre-release openvox rpm or deb packages directly, if openvox-released is set to false. | — | https://artifacts.voxpupuli.org |
| setup-cluster-ssh | If true, generated VMs with controller roles ('primary' or 'runner'), will be given ssh access to all vms in the cluster. | — | true |
| setup-cluster-root-ssh | If true, and setup-cluster-ssh is true, controllers will also be given root ssh access. | — | false |
| host-root-access | If true, the generated VMs will be configured to allow the host root access via SSH. | — | false |
| debug | Enable debug output (adds --stream to bolt commands). | — | false |
| checkout | Checkout the kvm_automation_tooling module from GitHub. This can be set to false to instead use the kvm_automation_tooling/ checkout provided by the calling workflow. | — | true |
| cluster_id | The cluster ID to use for the generated VMs. This is used to distinguish the VM hostnames, Terraform domains, Bolt inventory and Terraform state files. | — | test |
| network_prefix | The first three octects of the network address range to use for the generated libvirt network. The actual range in CIDR notation will be 'A.B.C.0/24'. The gateway address will be 'A.B.C.1'. | — | 192.168.100 |
| domain_name | The domain name for the guest cluster. | — | vm |
| ssh_key_name | The name of the SSH key to use for ssh access to cluster vms. If the file ~/.ssh/<ssh_key_name> does not exist, it will be generated as an ed25519 key. | — | ssh-id-test |
| refresh_package_cache | Whether or not to refresh the package cache on the generated VMs as part of the cluster setup. For debian based images in particular, running without an apt update has been observed to cause package installation failures due to stale package lists. | — | true |
| upgrade_packages | Whether or not to perform a full package upgrade on the vms. This add significant time and is not done by default. NOTE: setting this true imples refresh_package_cache, regardless of the value of that parameter. | — | false |
| wait_for_ip_timeout | The amount of time, in seconds, to wait for the generated VMs to have an IP address before timing out. This is calculated automatically based on whether kvm or qemu is being used (qemu requires a longer timeout), but can be overridden with this parameter if needed. | — | — |
| wait_until_available_timeout | The amount of time, in seconds, to wait for the generated VMs to be available for SSH connections before timing out. This defaults to wait_for_ip_timeout (either provided or calculated internally), but can be overridden if needed. | — | — |
Outputs
| name | description |
|---|---|
| cluster-details | VM information for the cluster (ip and hostname). |