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.