theko2fi.multipass.multipass_vm module – Module to manage Multipass VM

Note

This module is part of the theko2fi.multipass collection (version 0.3.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install theko2fi.multipass.

To use it in a playbook, specify: theko2fi.multipass.multipass_vm.

Synopsis

  • Manage the life cycle of Multipass virtual machines (create, start, stop, delete).

Parameters

Parameter

Comments

cloud_init

string

Path or URL to a user-data cloud-init configuration.

Default: "None"

cpus

integer

The number of CPUs of the VM.

disk

string

Disk space to allocate to the VM in format <number>[<unit>].

Positive integers, in bytes, or with K (kibibyte, 1024B), M (mebibyte), G (gibibyte) suffix.

Omitting the unit defaults to bytes.

Default: "5G"

image

string

The image used to create the VM.

Default: "ubuntu-lts"

memory

string

The amount of RAM to allocate to the VM.

Default: "1G"

mounts

list / elements=dictionary

added in theko2fi.multipass 0.3.0

Specification for mounts to be added to the VM.

Omitting a mount that is currently applied to a VM will remove it.

gid_map

list / elements=string

A list of group IDs mapping for use in the mount.

Use the Multipass CLI syntax <host>:<instance>. File and folder ownership will be mapped from <host> to <instance> inside the VM.

Omitting an gid_map that is currently applied to a mount, will remove it.

source

string / required

Path of the local directory to mount.

target

string

target mount point (path inside the VM).

If omitted, the mount point will be the same as the source’s absolute path.

type

string

Specify the type of mount to use.

classic mounts use technology built into Multipass.

native mounts use hypervisor and/or platform specific mounts.

Choices:

  • "classic" ← (default)

  • "native"

uid_map

list / elements=string

A list of user IDs mapping for use in the mount.

Use the Multipass CLI syntax <host>:<instance>. File and folder ownership will be mapped from <host> to <instance> inside the VM.

Omitting an uid_map that is currently applied to a mount, will remove it.

name

string / required

Name for the VM.

If it is 'primary' (the configured primary instance name), the user’s home directory is mounted inside the newly launched instance, in 'Home'.

purge

boolean

Use with state=absent to purge the VM after successful deletion.

Choices:

  • false ← (default)

  • true

recreate

boolean

Use with state=present or state=started to force the re-creation of an existing virtual machine.

Choices:

  • false ← (default)

  • true

state

string

absent - An instance matching the specified name will be stopped and deleted.

present - Asserts the existence of an instance matching the name and any provided configuration parameters. If no instance matches the name, a virtual machine will be created.

started - Asserts that the VM is first present, and then if the VM is not running moves it to a running state. If the VM was deleted, it will be recovered and started.

stopped - If an instance matching the specified name is running, moves it to a stopped state.

Use the recreate option to always force re-creation of a matching virtual machine, even if it is running.

Choices:

  • "present" ← (default)

  • "started"

  • "absent"

  • "stopped"

Examples

- name: Create a VM with default parameters
  theko2fi.multipass.multipass_vm:
    name: foo

- name: Create a VM with custom specs
  theko2fi.multipass.multipass_vm:
    name: foo
    cpus: 2
    memory: 2G
    disk: 5G

- name: Stop a VM
  theko2fi.multipass.multipass_vm:
    name: foo
    state: stopped

- name: Start a VM
  theko2fi.multipass.multipass_vm:
    name: foo
    state: started

- name: Recreate a VM
  theko2fi.multipass.multipass_vm:
    name: foo
    cpus: 4
    memory: 2G
    disk: 10G
    recreate: true

- name: Delete a VM
  theko2fi.multipass.multipass_vm:
    name: foo
    state: absent

- name: Delete and purge a VM
  theko2fi.multipass.multipass_vm:
    name: foo
    state: absent
    purge: true

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

result

dictionary

Facts representing the current state of the virtual machine. Matches the multipass info output.

Empty if state=absent or state=stopped.

Will be none if virtual machine does not exist.

Returned: success; or when state=started or state=present, and when waiting for the VM result did not fail

Sample: {"errors": [], "info": {"foo": {"cpu_count": "1", "disks": {"sda1": {"total": "5120710656", "used": "2200540672"}}, "image_hash": "fe102bfb3d3d917d31068dd9a4bd8fcaeb1f529edda86783f8524fdc1477ee29", "image_release": "22.04 LTS", "ipv4": ["172.23.240.92"], "load": [0.01, 0.01, 0], "memory": {"total": 935444480, "used": 199258112}, "mounts": {"/home/ubuntu/data": {"gid_mappings": ["0:default"], "source_path": "/tmp", "uid_mappings": ["0:default"]}}, "release": "Ubuntu 22.04.2 LTS", "state": "Running"}}}

Authors

  • Kenneth KOFFI (@theko2fi)