craft_providers.multipass.multipass_instance module

Multipass Instance.

class craft_providers.multipass.multipass_instance.MultipassInstance(*, name, multipass=None)[source]

Bases: craft_providers.executor.Executor

Multipass Instance Lifecycle.

Parameters

name (str) – Name of multipass instance.
multipass (Optional[Multipass]) –

delete()[source]

Delete instance and purge.

Return type: None

execute_popen(command, *, cwd=None, env=None, **kwargs)[source]

Execute a process in the instance using subprocess.Popen().

The process’ environment will inherit the execution environment’s default environment (PATH, etc.), but can be additionally configured via env parameter.

The command is run as root via sudo. Running as root may be required even when the command itself does not require root permissions, because the instance’s working directory may be a directory that the default ubuntu user does not have access to.

Parameters

command (List[str]) – Command to execute.
cwd (Optional[Path]) – working directory to execute the command
env (Optional[Dict[str, Optional[str]]]) – Additional environment to set for process.
kwargs – Additional keyword arguments for subprocess.Popen().

Return type

Popen

Returns

Popen instance.

execute_run(command, *, cwd=None, env=None, **kwargs)[source]

Execute a command in the instance using subprocess.run().

The process’ environment will inherit the execution environment’s default environment (PATH, etc.), but can be additionally configured via env parameter.

The command is run as root via sudo. Running as root may be required even when the command itself does not require root permissions, because the instance’s working directory may be a directory that the default ubuntu user does not have access to.

Parameters

command (List[str]) – Command to execute.
cwd (Optional[Path]) – working directory to execute the command
env (Optional[Dict[str, Optional[str]]]) – Additional environment to set for process.
kwargs – Keyword args to pass to subprocess.run().

Return type

CompletedProcess

Returns

Completed process.

Raises

subprocess.CalledProcessError – if command fails and check is True.

exists()[source]

Check if instance exists.

Return type: bool
Returns: True if instance exists.
Raises: MultipassError – On unexpected failure.

is_mounted(*, host_source, target)[source]

Check if path is mounted at target.

Parameters

host_source (Path) – Host path to check.
target (PurePath) – Instance path to check.

Return type

bool

Returns

True if host_source is mounted at target.

Raises

MultipassError – On unexpected failure.

is_running()[source]

Check if instance is running.

Return type: bool
Returns: True if instance is running.
Raises: MultipassError – On unexpected failure.

launch(*, image, cpus=2, disk_gb=256, mem_gb=2)[source]

Launch instance.

Parameters

image (str) – Name of image to create the instance with.
instance_cpus – Number of CPUs.
instance_disk_gb – Disk allocation in gigabytes.
instance_mem_gb – Memory allocation in gigabytes.
instance_name – Name of instance to use/create.
instance_stop_time_mins – Stop time delay in minutes.
cpus (int) –
disk_gb (int) –
mem_gb (int) –

Raises

MultipassError – On unexpected failure.

Return type

None

mount(*, host_source, target)[source]

Mount host host_source directory to target mount point.

Checks first to see if already mounted.

Parameters

host_source (Path) – Host path to mount.
target (PurePath) – Instance path to mount to.

Raises

MultipassError – On unexpected failure.

Return type

None

pull_file(*, source, destination)[source]

Copy a file from the environment to host.

Parameters

source (PurePath) – Environment file to copy.
destination (Path) – Host file path to copy to. Parent directory (destination.parent) must exist.

Raises

FileNotFoundError – If source file or destination’s parent directory does not exist.
MultipassError – On unexpected error copying file.

Return type

None

push_file(*, source, destination)[source]

Copy a file from the host into the environment.

The destination file is overwritten if it exists.

Parameters

source (Path) – Host file to copy.
destination (PurePath) – Target environment file path to copy to. Parent directory (destination.parent) must exist.

Raises

FileNotFoundError – If source file or destination’s parent directory does not exist.
MultipassError – On unexpected error copying file.

Return type

None

push_file_io(*, destination, content, file_mode, group='root', user='root')[source]

Create or replace file with content and file mode.

Multipass transfers data as “ubuntu” user, forcing us to first copy a file to a temporary location before moving to a (possibly) root-owned location and with appropriate permissions.

Parameters

destination (PurePath) – Path to file.
content (BytesIO) – Contents of file.
file_mode (str) – File mode string (e.g. ‘0644’).
group (str) – File group owner/id.
user (str) – File user owner/id.

Return type

None

start()[source]

Start instance.

Raises: MultipassError – On unexpected failure.
Return type: None

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

Stop instance.

Parameters: delay_mins (int) – Delay shutdown for specified minutes.
Raises: MultipassError – On unexpected failure.
Return type: None

unmount(target)[source]

Unmount mount target shared with host.

Parameters: target (Path) – Target shared with host to unmount.
Raises: MultipassError – On failure to unmount target.
Return type: None

unmount_all()[source]

Unmount all mounts shared with host.

Raises: MultipassError – On failure to unmount target.
Return type: None