craft_providers.multipass.multipass module

API provider for Multipass.

This implementation interfaces with multipass using the multipass command-line utility.

class craft_providers.multipass.multipass.Multipass(*, multipass_path=PosixPath('multipass'))[source]

Bases: object

Wrapper for multipass command.

Parameters

multipass_path (Path) – Path to multipass command to use.

Variables

minimum_required_version – Minimum required version for compatibility.

delete(*, instance_name, purge=True)[source]

Passthrough for running multipass delete.

Parameters
  • instance_name (str) – The name of the instance_name to delete.

  • purge – Flag to purge the instance_name’s image after deleting.

Raises

MultipassError – on error.

Return type

None

exec(*, command, instance_name, runner=<function run>, **kwargs)[source]

Execute command in instance_name with specified runner.

The working directory the command is executed from inside the instance depends on the host’s cwd. From the Multipass documentation: “In case we are executing the alias on the host from a directory which is mounted on the instance, the command will be executed on the instance from there. If the working directory is not mounted on the instance, the command will be executed on the default directory on the instance.”

Parameters
  • command (List[str]) – Command to execute in the instance.

  • instance_name (str) – Name of instance to execute in.

  • runner (Callable) – Execution function to invoke, e.g. subprocess.run or Popen. First argument is finalized command with the attached kwargs.

  • kwargs – Additional kwargs for runner.

Returns

Runner’s instance.

info(*, instance_name)[source]

Get information/state for instance.

Return type

Dict[str, Any]

Returns

Parsed json data from info command.

Raises

MultipassError – On error.

Parameters

instance_name (str) –

is_supported_version()[source]

Check if Multipass version is supported.

A helper to check if Multipass meets minimum supported version for craft-providers.

Return type

bool

Returns

True if installed version is supported.

launch(*, instance_name, image, cpus=None, mem=None, disk=None)[source]

Launch multipass VM.

Parameters
  • instance_name (str) – The name the launched instance will have.

  • image (str) – Name of image to create the instance with.

  • cpus (Optional[str]) – Amount of virtual CPUs to assign to the launched instance.

  • mem (Optional[str]) – Amount of RAM to assign to the launched instance.

  • disk (Optional[str]) – Amount of disk space the launched instance will have.

Raises

MultipassError – on error.

Return type

None

list()[source]

List names of VMs.

Return type

List[str]

Returns

Data from stdout if instance exists, else None.

Raises

MultipassError – On error.

minimum_required_version = '1.7'
mount(*, source, target, uid_map=None, gid_map=None)[source]

Mount host source path to target.

Parameters
  • source (Path) – Path of local directory to mount.

  • target (str) – Target mount points, in <name>[:<path>] format, where <name> is an instance name, and optional <path> is the mount point. If omitted, the mount point will be the same as the source’s absolute path.

  • uid_map (Optional[Dict[str, str]]) – A mapping of user IDs for use in the mount of the form <host-id> -> <instance-id>. File and folder ownership will be mapped from <host-id> to <instance-id> inside the instance.

  • gid_map (Optional[Dict[str, str]]) – A mapping of group IDs for use in the mount of the form <host-id> -> <instance-id>. File and folder ownership will be mapped from <host-id> to <instance-id> inside the instance.

Return type

None

start(*, instance_name)[source]

Start VM instance.

Parameters

instance_name (str) – the name of the instance to start.

Raises

MultipassError – on error.

Return type

None

stop(*, instance_name, delay_mins=0)[source]

Stop VM instance.

Parameters
  • instance_name (str) – the name of the instance_name to stop.

  • delay_mins (int) – Delay shutdown for specified number of minutes.

Raises

MultipassError – on error.

Return type

None

transfer(*, source, destination)[source]

Transfer to destination path with source IO.

Multipass transfer uses sftp. By default, only the user ubuntu can transfer files. Therefore, the path inside the instance should be accessible by the ubuntu user.

By default, Multipass only has access to the host’s home directory. The host’s path should be inside the home directory.

Parameters
  • source (str) – The source path, prefixed with <name:> for a path inside the instance.

  • destination (str) – The destination path, prefixed with <name:> for a path inside the instance.

Raises

MultipassError – On error.

Return type

None

transfer_destination_io(*, source, destination, chunk_size=4096)[source]

Transfer from source file to destination IO.

Note that this can’t use std{in,out}=open(…) due to LP #1849753.

Parameters
  • source (str) – The source path, prefixed with <name:> for a path inside the instance.

  • destination (BufferedIOBase) – An IO stream to write to.

  • chunk_size (int) – Number of bytes to transfer at a time. Defaults to 4096.

Raises

MultipassError – On error.

Return type

None

transfer_source_io(*, source, destination, chunk_size=4096)[source]

Transfer to destination path with source IO.

Note that this can’t use std{in,out}=open(…) due to LP #1849753.

Parameters
  • source (BufferedIOBase) – An IO stream to read from.

  • destination (str) – The destination path, prefixed with <name:> for a path inside the instance.

  • chunk_size (int) – Number of bytes to transfer at a time. Defaults to 4096.

Raises

MultipassError – On error.

Return type

None

umount(*, mount)[source]

Unmount target in VM.

Parameters

mount (str) – Mount point in <name>[:<path>] format, where <name> are instance names, and optional <path> are mount points. If omitted, all mounts will be removed from the named instance.

Raises

MultipassError – On error.

Return type

None

version()[source]

Get multipass and multipassd versions.

Return type

Tuple[str, Optional[str]]

Returns

Tuple of parsed versions (multipass, multipassd). multipassd may be None if Multipass is not yet ready.

wait_until_ready(*, retry_wait=0.25, timeout=None)[source]

Wait until Multipass is ready (upon install/startup).

Parameters
  • retry_wait (float) – Time to sleep between retries.

  • timeout (Optional[float]) – Timeout in seconds.

Return type

Tuple[str, Optional[str]]

Returns

Tuple of parsed versions (multipass, multipassd). multipassd may be None if Multipass is not ready and the timeout limit is reached.