ControlPlane

@final
class ControlPlane

MicroVM lifecycle by ID (get, list, suspend, resume, terminate, and wait) and image administration (list, delete, versions and their status, builds).

Holds no lifecycle state, so it checks nothing a Sandbox would (STATE-5, STATE-7): a suspend of a SUSPENDED VM is the service’s to refuse. Use it when a process has only an identifier, such as a durable workflow step in a fresh process.

Constructor

ControlPlane(
    region: Region,
    *,
    retry: tuple[SupportsIndex, SupportsFloat | SupportsIndex] | None = None,
)

Resolves credentials for region from the default chain.

Properties

region

region: Region

The region this plane addresses.

Methods

create_async

@staticmethod
def create_async(
    region: Region,
    *,
    retry: tuple[SupportsIndex, SupportsFloat | SupportsIndex] | None = None,
) -> ControlPlane

The awaitable twin of ControlPlane(region).

delete_image

def delete_image(
    identifier: str,
    *,
    attempts: SupportsIndex | None = None,
    backoff: SupportsFloat | SupportsIndex | None = None,
) -> bool

Deletes the image, its extra versions first, retrying while it refuses (an image still CREATING, or one a terminating VM holds).

Returns True once the service took the deletion and False when every attempt failed or identifier is not one the service accepts. It doesn’t raise, as a teardown’s delete shouldn’t. attempts and backoff (seconds) default to the core’s teardown figures.

delete_image_async

def delete_image_async(
    identifier: str,
    *,
    attempts: SupportsIndex | None = None,
    backoff: SupportsFloat | SupportsIndex | None = None,
) -> bool

The awaitable twin of delete_image. A lifecycle call: cancelling the awaitable leaves the deletion and its retries running to their answer.

get

def get(microvm_id: str) -> Microvm

GetMicrovm.

get_async

def get_async(microvm_id: str) -> Microvm

The awaitable twin of get.

get_image_build

def get_image_build(identifier: str, version: str, build_id: str) -> ImageBuild

GetMicrovmImageBuild: one build, with the snapshot sizes the listing doesn’t carry.

get_image_build_async

def get_image_build_async(identifier: str, version: str, build_id: str) -> ImageBuild

The awaitable twin of get_image_build.

list

def list(
    *,
    image_identifier: str | None = None,
    image_version: str | None = None,
) -> list[MicrovmSummary]

ListMicrovms, every page, optionally narrowed to one image and version.

list_async

def list_async(
    *,
    image_identifier: str | None = None,
    image_version: str | None = None,
) -> list[MicrovmSummary]

The awaitable twin of list.

list_image_builds

def list_image_builds(identifier: str, version: str) -> list[ImageBuild]

ListMicrovmImageBuilds for one version, every page: one build per Graviton generation. Each build_id is what get_image_build takes.

list_image_builds_async

def list_image_builds_async(identifier: str, version: str) -> list[ImageBuild]

The awaitable twin of list_image_builds.

list_image_versions

def list_image_versions(identifier: str) -> list[ImageVersion]

ListMicrovmImageVersions, every page: each version, its status, and its build configuration.

list_image_versions_async

def list_image_versions_async(identifier: str) -> list[ImageVersion]

The awaitable twin of list_image_versions.

list_images

def list_images() -> list[ImageSummary]

ListMicrovmImages, every page: every image in the account and region.

list_images_async

def list_images_async() -> list[ImageSummary]

The awaitable twin of list_images.

resume

def resume(microvm_id: str) -> None

ResumeMicrovm. Returns once accepted; wait_for_state for RUNNING. A VM that ended before the resume, whatever ended it, raises WindowClosedError (STATE-12).

resume_async

def resume_async(microvm_id: str) -> None

The awaitable twin of resume. A lifecycle call, as suspend_async is.

set_image_version_status

def set_image_version_status(identifier: str, version: str, status: str) -> ImageVersion

UpdateMicrovmImageVersion: status is "ACTIVE" or "INACTIVE".

INACTIVE is the non-destructive retire: RunMicrovm refuses the version, running VMs keep running, and the version’s readback stays. Returns the readback, and raises when it doesn’t carry the status asked for, so a 200 that didn’t take isn’t a rollback.

set_image_version_status_async

def set_image_version_status_async(
    identifier: str,
    version: str,
    status: str,
) -> ImageVersion

The awaitable twin of set_image_version_status. A lifecycle call: cancelling the awaitable leaves the update running to its readback.

suspend

def suspend(microvm_id: str) -> None

SuspendMicrovm. Returns once accepted; wait_for_state for SUSPENDED.

suspend_async

def suspend_async(microvm_id: str) -> None

The awaitable twin of suspend. A lifecycle call: cancelling the awaitable leaves the request running to its answer.

sweep

def sweep(
    prefix: str,
    *,
    keep: SupportsGetItem[int, str] | None = None,
    dry_run: bool | None = None,
) -> SweepReport

Discover prefix-matched images and VMs. Set dry_run=False to clean them up. Keep entries preserve exact image names or ARNs and every VM using them.

sweep_async

def sweep_async(
    prefix: str,
    *,
    keep: SupportsGetItem[int, str] | None = None,
    dry_run: bool | None = None,
) -> SweepReport

The awaitable twin of sweep. Once cleanup starts, cancellation leaves it running.

terminate

def terminate(microvm_id: str) -> None

TerminateMicrovm. Returns once accepted; wait_for_state for TERMINATED.

terminate_async

def terminate_async(microvm_id: str) -> None

The awaitable twin of terminate. A lifecycle call, as suspend_async is.

wait_for_state

def wait_for_state(
    microvm_id: str,
    wanted: SupportsGetItem[int, str],
    *,
    fail_on: SupportsGetItem[int, str] | None = None,
    timeout: SupportsFloat | SupportsIndex = 300.0,
    poll_interval: SupportsFloat | SupportsIndex = 5.0,
) -> Microvm

Polls GetMicrovm until the state is one of wanted.

Reaching one of fail_on first raises LaunchDiedError naming the state and stateReason; running past timeout raises TimeoutError.

wait_for_state_async

def wait_for_state_async(
    microvm_id: str,
    wanted: SupportsGetItem[int, str],
    *,
    fail_on: SupportsGetItem[int, str] | None = None,
    timeout: SupportsFloat | SupportsIndex = 300.0,
    poll_interval: SupportsFloat | SupportsIndex = 5.0,
) -> Microvm

The awaitable twin of wait_for_state. Cancelling it stops the polling and touches no VM.

Special methods

__repr__

def __repr__() -> str

Provenance

This page is generated from bindings/microvms-py/microvms.pyi by Griffe 2.3.0, run from site/scripts/gen-reference.mjs on every pnpm run sync, so an edit made here is overwritten by the next run.

To change the page, change the doc comment in the binding’s Rust source, then regenerate the declarations with mise run stubs. mise run stubs:check fails when the committed file no longer matches the source.