microvms

Creates, updates, deletes, gets or lists a microvms resource.

Overview

Name	microvms
Type	Resource
Id	aws.lambda_microvms.microvms

Fields

The following fields are returned by SELECT queries:

get_microvm

Name	Datatype	Description
egress_network_connectors	array	The list of egress network connectors configured for the MicroVM.
endpoint	string	The HTTPS endpoint URL for communicating with the MicroVM. Include a valid authentication token in the X-aws-proxy-auth header when sending requests.
execution_role_arn	string	The ARN of an IAM role that the service assumes to perform actions on behalf of the caller. (pattern: <code>arn:aws[a-z-]*:iam::[0-9]{12}:role/?[a-zA-Z_0-9+=,.@-_/]+</code>)
idle_policy	object	The idle policy configuration of the MicroVM, controlling auto-suspend and auto-resume behavior.
image_arn	string	The ARN of the MicroVM image used to run this MicroVM.
image_version	string	The version of the MicroVM image used to run this MicroVM. (pattern: <code>[^\s]+</code>)
ingress_network_connectors	array	The list of ingress network connectors configured for the MicroVM.
maximum_duration_in_seconds	integer	The maximum duration in seconds that the MicroVM can exist before being terminated by the platform.
microvm_id	string	The ARN or ID of the MicroVm
started_at	string (date-time)	The timestamp when the MicroVM first started.
state	string	The current lifecycle state of the MicroVM. (PENDING, RUNNING, SUSPENDING, SUSPENDED, TERMINATING, TERMINATED)
state_reason	string	A string which is not empty or blank (only whitespace). (pattern: <code>[^\s]+</code>)
terminated_at	string (date-time)	The timestamp when the MicroVM terminated.

list_microvms

Name	Datatype	Description
image_arn	string	The ARN of the MicroVM image used to run this MicroVM.
image_version	string	The version of the MicroVM image used to run this MicroVM. (pattern: <code>[^\s]+</code>)
microvm_id	string	The ARN or ID of the MicroVm
started_at	string (date-time)	The timestamp when the MicroVM started.
state	string	The current lifecycle state of the MicroVM. (PENDING, RUNNING, SUSPENDING, SUSPENDED, TERMINATING, TERMINATED)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_microvm	select	microvm_identifier, region		Retrieves the details of a specific MicroVM, including its state, endpoint, image information, and configuration. The state field is eventually consistent — determine readiness by connecting to the endpoint.
list_microvms	select	region	maxResults, nextToken, imageIdentifier, imageVersion	Lists MicroVMs in the account with optional filtering by image and version. We recommend using pagination to ensure that the operation returns quickly and successfully.
create_microvm_auth_token	insert	microvm_identifier, region, expirationInMinutes, allowedPorts		Creates an authentication token for accessing a running MicroVM. The token grants access to the specified ports on the MicroVM endpoint.
create_microvm_shell_auth_token	insert	microvm_identifier, region, expirationInMinutes		Creates a shell authentication token for interactive shell access to a running MicroVM. The MicroVM must have been run with the SHELL_INGRESS network connector attached.
terminate_microvm	delete	microvm_identifier, region		Terminates a MicroVM. This operation is idempotent; terminating a MicroVM that has already been terminated succeeds without error.
suspend_microvm	exec	microvm_identifier, region		Suspends a running MicroVM, preserving its full memory and disk state. The MicroVM transitions through SUSPENDING to SUSPENDED. To restore, call ResumeMicrovm or send traffic to the endpoint if autoResumeEnabled is true.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
microvm_identifier	string	The ID of the MicroVM to suspend.
region	string	AWS region (default: us-east-1)
imageIdentifier	string	Optional filter to list only MicroVMs running the specified image.
imageVersion	string	Optional filter to list only MicroVMs running the specified image version.
maxResults	integer	The maximum number of results to return in a single call.
nextToken	string	The pagination token from a previous call. Use this token to retrieve the next page of results.

SELECT examples

get_microvm

Retrieves the details of a specific MicroVM, including its state, endpoint, image information, and configuration. The state field is eventually consistent — determine readiness by connecting to the endpoint.

SELECT
egress_network_connectors,
endpoint,
execution_role_arn,
idle_policy,
image_arn,
image_version,
ingress_network_connectors,
maximum_duration_in_seconds,
microvm_id,
started_at,
state,
state_reason,
terminated_at
FROM aws.lambda_microvms.microvms
WHERE microvm_identifier = '{{ microvm_identifier }}' -- required
AND region = '{{ region }}' -- required
;

list_microvms

Lists MicroVMs in the account with optional filtering by image and version. We recommend using pagination to ensure that the operation returns quickly and successfully.

SELECT
image_arn,
image_version,
microvm_id,
started_at,
state
FROM aws.lambda_microvms.microvms
WHERE region = '{{ region }}' -- required
AND maxResults = '{{ maxResults }}'
AND nextToken = '{{ nextToken }}'
AND imageIdentifier = '{{ imageIdentifier }}'
AND imageVersion = '{{ imageVersion }}'
;

INSERT examples

create_microvm_auth_token

Creates an authentication token for accessing a running MicroVM. The token grants access to the specified ports on the MicroVM endpoint.

INSERT INTO aws.lambda_microvms.microvms (
expirationInMinutes,
allowedPorts,
microvm_identifier,
region
)
SELECT 
{{ expirationInMinutes }} /* required */,
'{{ allowedPorts }}' /* required */,
'{{ microvm_identifier }}',
'{{ region }}'
RETURNING
auth_token
;

create_microvm_shell_auth_token

Creates a shell authentication token for interactive shell access to a running MicroVM. The MicroVM must have been run with the SHELL_INGRESS network connector attached.

INSERT INTO aws.lambda_microvms.microvms (
expirationInMinutes,
microvm_identifier,
region
)
SELECT 
{{ expirationInMinutes }} /* required */,
'{{ microvm_identifier }}',
'{{ region }}'
RETURNING
auth_token
;

Manifest

# Description fields are for documentation purposes
- name: microvms
props:
  - name: microvm_identifier
    value: "{{ microvm_identifier }}"
    description: Required parameter for the microvms resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the microvms resource.
  - name: expirationInMinutes
    value: {{ expirationInMinutes }}
  - name: allowedPorts
    description: |
      A list of port specifications.
    value:
      - port: {{ port }}
        range:
          startPort: {{ startPort }}
          endPort: {{ endPort }}
        allPorts: "{{ allPorts }}"

DELETE examples

terminate_microvm

Terminates a MicroVM. This operation is idempotent; terminating a MicroVM that has already been terminated succeeds without error.

DELETE FROM aws.lambda_microvms.microvms
WHERE microvm_identifier = '{{ microvm_identifier }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

suspend_microvm

Suspends a running MicroVM, preserving its full memory and disk state. The MicroVM transitions through SUSPENDING to SUSPENDED. To restore, call ResumeMicrovm or send traffic to the endpoint if autoResumeEnabled is true.

EXEC aws.lambda_microvms.microvms.suspend_microvm 
@microvm_identifier='{{ microvm_identifier }}' --required, 
@region='{{ region }}' --required
;