Libvirt VM Terraform module

Terraform module for KVM/Libvirt Virtual Machine. This module will create a KVM Virtual Machine(s), configure it using Cloud Init and test the ssh connection. This module is using dmacvicar/libvirt Terraform provider.

What it provides

creates one or more VMs
one NIC per domain, connected to the network using the bridge interface
setup network interface using DHCP or static configuration
cloud_init VM(s) configuration (Ubuntu+Netplan complient)
optionally add multiple extra disks
test the ssh connection

Tested on

Ubuntu 20.04 TLS Cloud Image
Ubuntu 22.04 TLS Cloud Image

Requirements

Name	Version
terraform	>= 1.0
libvirt	>= 0.7.0

Modules

No modules.

Resources

Name	Type
libvirt_cloudinit_disk.commoninit	resource
libvirt_domain.virt-machine	resource
libvirt_volume.base-volume-qcow2	resource
libvirt_volume.volume-qcow2	resource

Inputs

Name	Description	Type	Default	Required
additional_disk_ids	List of volume ids	`list(string)`	`[]`	no
autostart	Autostart the domain	`bool`	`true`	no
base_pool_name	Name of base OS image	`string`	`null`	no
base_volume_name	Name of base OS image	`string`	`null`	no
bridge	Bridge interface	`string`	`"virbr0"`	no
cpu_mode	CPU mode	`string`	`"host-passthrough"`	no
dhcp	Use DHCP or Static IP settings	`bool`	`false`	no
graphics	Graphics type (can be '`spice`' or '`vnc`')	`string`	`spice`	no
index_start	From where the indexig start	`number`	`1`	no
ip_address	List of IP addresses	`list(string)`	[ "192.168.123.101" ]	no
ip_gateway	IP addresses of a gateway	`string`	`"192.168.123.1"`	no
ip_nameserver	IP addresses of a nameserver	`string`	`"192.168.123.1"`	no
local_admin	Admin user without ssh access	`string`	`""`	no
local_admin_passwd	Local admin user password	`string`	`"password_example"`	no
memory	RAM in MB	`string`	`"1024"`	no
os_img_url	URL to the OS image	`string`	`"https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"`	no
pool	Storage pool name	`string`	`"default"`	no
runcmd	Extra commands to be run with cloud init	`list(string)`	[ "[ systemctl, daemon-reload ]", "[ systemctl, enable, qemu-guest-agent ]", "[ systemctl, start, qemu-guest-agent ]", "[ systemctl, restart, systemd-networkd ]" ]	no
share_filesystem	n/a	object({ source = string target = string readonly = bool mode = string })	{ "mode": null, "readonly": false, "source": null, "target": null }	no
ssh_admin	Admin user with ssh access	`string`	`"ssh-admin"`	no
ssh_keys	List of public ssh keys	`list(string)`	`[]`	no
ssh_private_key	Private key for SSH connection test (either path to file or key content)	`string`	`null`	no
system_volume	System Volume size (GB)	`number`	`10`	no
time_zone	Time Zone	`string`	`"UTC"`	no
vcpu	Number of vCPUs	`number`	`1`	no
vm_count	Number of VMs	`number`	`1`	no
vm_hostname_prefix	VM hostname prefix	`string`	`"vm"`	no
xml_override	With these variables you can: Enable hugepages; Set USB controllers; Attach USB devices	object({ hugepages = bool usb_controllers = list(object({ model = string })) usb_devices = list(object({ vendor = string product = string })) pci_devices_passthrough = list(object({ src_domain = string src_bus = string src_slot = string src_func = string dst_domain = string dst_bus = string dst_slot = string dst_func = string })) })	{ "hugepages": false, "usb_controllers": [ { "model": "piix3-uhci" } ], "usb_devices": [] "pci_devices_passthrough": [] }	no
bastion_host	ssh bastion host	`string`	`null`	no
bastion_user	ssh user on bastion host	`string`	`null`	no
bastion_ssh_private_key	ssh private key for bastion host (either path to file or key content)	`string`	`null`	no

Outputs

Name	Description
ip_address	n/a
name	n/a

Example

Example with enable HugePages, Attached USB device, changed USB controller model... :

terraform {
  required_version = ">= 0.13"
    required_providers {
      libvirt = {
        source  = "dmacvicar/libvirt"
      }
    }
}

resource "tls_private_key" "ecdsa-p384-bastion" {
  algorithm   = "ECDSA"
  ecdsa_curve = "P384"
}

provider "libvirt" {
  uri = "qemu+ssh://hero@192.168.165.100/system"
}

module "vm" {
  source  = "MonolithProjects/vm/libvirt"
  version = "1.8.0"

  vm_hostname_prefix = "server"
  vm_count    = 3
  memory      = "2048"
  vcpu        = 1
  pool        = "terra_pool"
  system_volume = 20
  dhcp        = true
  local_admin = "local-admin"
  ssh_admin   = "ci-user"
  ssh_private_key = "~/.ssh/id_ed25519"
  local_admin_passwd = "$6$rounds=4096$xxxxxxxxHASHEDxxxPASSWORD"
  ssh_keys    = [
    "ssh-ed25519 AAAAxxxxxxxxxxxxSSHxxxKEY example",
    ]
  bastion_host = "10.0.0.1"
  bastion_user = "admin"
  bastion_ssh_private_key = tls_private_key.ecdsa-p384-bastion.private_key_pem
  time_zone   = "CET"
  os_img_url  = "file:///home/myuser/ubuntu-20.04-server-cloudimg-amd64.img"
  xml_override = {
      hugepages = true,
      usb_controllers = [
        {
          model = "qemu-xhci"
        }
      ],
      usb_devices = [
        {
          vendor = "0x0bc2",
          product = "0xab28"
        }
      ]
      pci_devices_passthrough = [
        {
          src_domain = "0x0000",
          src_bus    = "0xc1",
          src_slot   = "0x00",
          src_func   = "0x0",
          dst_domain = "0x0000",
          dst_bus    = "0x00",
          dst_slot   = "0x08"
          dst_func   = "0x0"
        },
        {
          src_domain = "0x0000",
          src_bus    = "0xc1",
          src_slot   = "0x00",
          src_func   = "0x1",
          dst_domain = "0x0000",
          dst_bus    = "0x00",
          dst_slot   = "0x09"
          dst_func   = "0x0"
        }
      ]      
    }
}

output "ip_addresses" {
  value = module.nodes
}

Static IP settings... :

terraform {
  required_version = ">= 0.13"
    required_providers {
      libvirt = {
        source  = "dmacvicar/libvirt"
        version = "0.6.3"
      }
    }
}

provider "libvirt" {
  uri = "qemu+ssh://hero@192.168.165.100/system"
}

module "vm" {
  source  = "MonolithProjects/vm/libvirt"
  version = "1.8.0"

  vm_hostname_prefix = "server"
  vm_count    = 3
  memory      = "2048"
  vcpu        = 1
  pool        = "terra_pool"
  system_volume = 20
  share_filesystem = {
    source = "/tmp"
    target = "tmp"
    readonly = false
  }

  dhcp        = false
  ip_address  = [
                  "192.168.165.151",
                  "192.168.165.152",
                  "192.168.165.153"
                ]
  ip_gateway  = "192.168.165.254"
  ip_nameserver = "192.168.165.104"

  local_admin = "local-admin"
  ssh_admin   = "ci-user"
  ssh_private_key = "~/.ssh/id_ed25519"
  local_admin_passwd = "$6$rounds=4096$xxxxxxxxHASHEDxxxPASSWORD"
  ssh_keys    = [
    "ssh-ed25519 AAAAxxxxxxxxxxxxSSHxxxKEY example",
    ]
  time_zone   = "CET"
  os_img_url  = "file:///home/myuser/ubuntu-20.04-server-cloudimg-amd64.img"
}

output "outputs" {
  value = module.nodes
}

The shared directory from the example can be mounted inside the VM with command sudo mount -t 9p -o trans=virtio,version=9p2000.L,rw tmp /host/tmp

Create a VM with an extra disk

# Creates a 50GB extra-data-disk within vms pool
resource "libvirt_volume" "data_volume" {
  pool = "vms"
  name  = "extra-data-disk.qcow2"
  format = "qcow2"
  size = 1024*1024*1024*50
}

module "vm" {
  source  = "MonolithProjects/vm/libvirt"
  version = "1.8.0"

  vm_hostname_prefix = "data-server"
  base_volume_name = "debian-11-base.qcow2"
  base_pool_name = "linked-images"
  vm_count    = 1
  bridge =        "bridge-dmz"
  memory      = "4096"
  vcpu        = 4
  pool        = "vms"
  system_volume = 25
  additional_disk_ids = [ libvirt_volume.data_volume.id ]
  dhcp        = true
  ssh_admin   = "admin"
  ssh_keys    = [
    chomp(file("~/.ssh/id_rsa.pub"))
    ]
  time_zone   = "America/Argentina/Buenos_Aires"
}

output "ip_addresses" {
  value = module.vm
}

Module output example

output_data = {
  "ip_address" = [
    "192.168.165.151",
    "192.168.165.152",
    "192.168.165.153",
  ]
  "name" = [
    "server01",
    "server02",
    "server03",
  ]
}

License

MIT

Author Information

Created in 2020 by Michal Muransky

MonolithProjects/terraform-libvirt-vm