microvm

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 23, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package microvm provides a small convenience layer over AWS Lambda MicroVMs.

The package intentionally keeps the AWS SDK for Go v2 as the control-plane implementation and focuses on the common workflow: package an fs.FS as a MicroVM artifact, upload it to S3, create a MicroVM image, run a MicroVM from that image, create an endpoint auth token, and send authenticated HTTP requests to the MicroVM endpoint.

Index

Constants

View Source 
const (
	// DefaultMicroVMPort is the Lambda MicroVM endpoint's default target port.
	// Requests that do not include X-aws-proxy-port are routed to port 8080
	// inside the MicroVM.
	DefaultMicroVMPort = int32(8080)
)

Variables

This section is empty.

Functions

func AllIngressConnectorARN 

func AllIngressConnectorARN(region string) string

AllIngressConnectorARN returns the AWS-managed ingress connector ARN that enables inbound HTTPS access to all application ports allowed by the auth token.

func InternetEgressConnectorARN 

func InternetEgressConnectorARN(region string) string

InternetEgressConnectorARN returns the AWS-managed egress connector ARN that enables outbound public internet access from a MicroVM.

func NoIngressConnectorARN 

func NoIngressConnectorARN(region string) string

NoIngressConnectorARN returns the AWS-managed ingress connector ARN that disables inbound connectivity for a MicroVM.

func ShellIngressConnectorARN 

func ShellIngressConnectorARN(region string) string

ShellIngressConnectorARN returns the AWS-managed ingress connector ARN required for MicroVM shell access and debugging.

Types

type BuildImageFromDirInput 

type BuildImageFromDirInput struct {
	// Name is the MicroVM image name. It must be unique within the AWS account.
	Name string
	// Dir is the local directory to package. It must contain a Dockerfile at its
	// top level.
	Dir string

	// ArtifactBucket overrides Config.ArtifactBucket for this build.
	ArtifactBucket string
	// ArtifactKey is the S3 object key for the generated zip artifact. If empty,
	// BuildImageFromDir generates one from Config.ArtifactPrefix, Name, and a
	// timestamp.
	ArtifactKey string

	// BaseImageARN overrides Config.BaseImageARN for this build.
	BaseImageARN string
	// BuildRoleARN overrides Config.BuildRoleARN for this build.
	BuildRoleARN string

	// Description is an optional human-readable description for the image
	// version created by this build.
	Description string
	// EnvironmentVariables are injected into the MicroVM runtime environment at
	// image build time and are shared by MicroVMs launched from this version.
	EnvironmentVariables map[string]string
	// Tags are attached to the created MicroVM image resource.
	Tags map[string]string
	// Hooks configures build-time and runtime lifecycle hooks.
	Hooks *types.Hooks
	// Logging configures CloudWatch Logs output or disables logging.
	Logging types.Logging
	// ResourcesMiB sets the baseline MicroVM memory in MiB. If zero, the service
	// default is used.
	ResourcesMiB int32
	// AdditionalOsCapabilities grants additional Linux capabilities inside the
	// MicroVM isolation boundary.
	AdditionalOsCapabilities []types.Capability
	// EgressNetworkConnectors lists runtime egress connector ARNs available to
	// MicroVMs launched from this image.
	EgressNetworkConnectors []string

	// Exclude is called for each directory entry before packaging.
	Exclude func(name string, entry fs.DirEntry) bool

	// Wait tells BuildImageFromDir to poll until the image is ready or failed.
	Wait bool
	// WaitPollInterval overrides the Manager polling interval for this build.
	WaitPollInterval time.Duration

	// MutateCreateInput can adjust the generated AWS SDK input immediately before
	// CreateMicrovmImage is called.
	MutateCreateInput func(*lambdamicrovms.CreateMicrovmImageInput)
}

BuildImageFromDirInput describes a MicroVM image build from a local directory.

It mirrors BuildImageInput but replaces FS and Root with Dir. BuildImageFromDir packages os.DirFS(Dir), so Dir itself must contain the Dockerfile that should appear at the artifact zip root.

type BuildImageInput 

type BuildImageInput struct {
	// Name is the MicroVM image name. It must be unique within the AWS account
	// and is passed to CreateMicrovmImageInput.Name.
	Name string
	// FS is the source filesystem to package into the MicroVM image artifact.
	// It may be an os.DirFS, embed.FS, fstest.MapFS, or any other fs.FS.
	FS fs.FS
	// Root is the directory inside FS to package. The default is ".". The
	// Dockerfile must be located at Root/Dockerfile and is written to the zip
	// root as Dockerfile.
	Root string

	// ArtifactBucket overrides Config.ArtifactBucket for this build. The bucket
	// should be in the same AWS Region as the MicroVM image build.
	ArtifactBucket string
	// ArtifactKey is the S3 object key for the generated zip artifact. If empty,
	// BuildImage generates one from Config.ArtifactPrefix, Name, and a timestamp.
	ArtifactKey string

	// BaseImageARN overrides Config.BaseImageARN for this build. It must be the
	// ARN of a Lambda-managed MicroVM base image.
	BaseImageARN string
	// BuildRoleARN overrides Config.BuildRoleARN for this build. Lambda assumes
	// this role to download the S3 artifact and write build logs.
	BuildRoleARN string

	// Description is an optional human-readable description for the image
	// version created by this build.
	Description string
	// EnvironmentVariables are injected into the MicroVM runtime environment at
	// image build time. Values are shared by all MicroVMs launched from the
	// resulting image version.
	EnvironmentVariables map[string]string
	// Tags are attached to the created MicroVM image resource for organization,
	// cost allocation, and IAM attribute-based access control.
	Tags map[string]string
	// Hooks configures build-time hooks such as ready and validate, and runtime
	// hooks such as run, resume, suspend, and terminate. The application must
	// listen on the configured hook port.
	Hooks *types.Hooks
	// Logging configures build-time and runtime CloudWatch Logs output, or
	// disables logging. Leave nil to use the service default.
	Logging types.Logging
	// ResourcesMiB sets the baseline MicroVM memory in MiB. Lambda scales vCPU
	// proportionally with memory and can vertically scale above this baseline.
	// If zero, the service default is used.
	ResourcesMiB int32
	// AdditionalOsCapabilities grants additional Linux capabilities within the
	// MicroVM isolation boundary. The current service-supported value is
	// types.CapabilityAll.
	AdditionalOsCapabilities []types.Capability
	// EgressNetworkConnectors lists network connector ARNs made available to
	// MicroVMs launched from the image at runtime.
	EgressNetworkConnectors []string

	// Exclude is called for each fs.WalkDir entry before packaging. Returning
	// true skips a file; returning true for a directory skips the entire subtree.
	Exclude func(name string, entry fs.DirEntry) bool

	// Wait tells BuildImage to poll GetMicrovmImage until the image reaches
	// CREATED or UPDATED, or until a failed terminal state is observed.
	Wait bool
	// WaitPollInterval overrides the Manager polling interval for this build.
	// If zero, the Manager default is used.
	WaitPollInterval time.Duration

	// MutateCreateInput can adjust the generated AWS SDK input immediately before
	// CreateMicrovmImage is called. Use it for advanced options not represented
	// directly by this convenience API.
	MutateCreateInput func(*lambdamicrovms.CreateMicrovmImageInput)
}

BuildImageInput describes a MicroVM image build from an fs.FS.

BuildImage packages FS into a zip artifact, uploads it to S3, and calls CreateMicrovmImage with the resulting s3:// URI. The selected Root must contain a Dockerfile at its top level because Lambda executes that Dockerfile while creating the MicroVM image snapshot.

type Config 

type Config struct {
	// AWSConfig is used to construct default S3 and Lambda MicroVMs SDK clients
	// when S3Client or MicroVMClient are not supplied.
	AWSConfig aws.Config

	// S3Client overrides the S3 client used to upload MicroVM image artifacts.
	// If nil, NewManager creates one from AWSConfig.
	S3Client *s3.Client
	// MicroVMClient overrides the Lambda MicroVMs control-plane client. If nil,
	// NewManager creates one from AWSConfig.
	MicroVMClient *lambdamicrovms.Client
	// HTTPClient is used by Session to call MicroVM HTTPS endpoints. If nil,
	// http.DefaultClient is used.
	HTTPClient *http.Client

	// ArtifactBucket is the default S3 bucket for zip artifacts generated by
	// BuildImage and BuildImageFromDir. It can be overridden per build request.
	ArtifactBucket string
	// ArtifactPrefix is an optional S3 key prefix used when BuildImage generates
	// an artifact key automatically.
	ArtifactPrefix string
	// BaseImageARN is the default Lambda-managed MicroVM base image ARN used by
	// CreateMicrovmImage. It can be overridden per build request.
	BaseImageARN string
	// BuildRoleARN is the default IAM role ARN that Lambda assumes during image
	// creation to read the S3 artifact and write build logs.
	BuildRoleARN string

	// DefaultIngressConnectors are used by Run when the request does not specify
	// ingress network connectors. Use AllIngressConnectorARN, NoIngressConnectorARN,
	// or ShellIngressConnectorARN for AWS-managed connectors.
	DefaultIngressConnectors []string
	// DefaultEgressConnectors are used by Run when the request does not specify
	// egress network connectors. Use InternetEgressConnectorARN for public
	// internet access or provide a customer-managed VPC connector ARN.
	DefaultEgressConnectors []string
	// PollInterval controls the default delay between GetMicrovmImage and
	// GetMicrovm polling attempts. If zero, NewManager uses 2 seconds.
	PollInterval time.Duration
}

Config configures a Manager.

type Image 

type Image struct {
	// ARN is the AWS ARN of the MicroVM image resource.
	ARN string
	// Name is the MicroVM image name.
	Name string
	// Version is the image version created by CreateMicrovmImage, or the latest
	// active version returned by GetMicrovmImage.
	Version string
	// State is the current MicroVM image lifecycle state, such as CREATING,
	// CREATED, UPDATED, or CREATE_FAILED.
	State types.MicrovmImageState
	// ArtifactURI is the s3:// URI of the zip artifact uploaded by BuildImage or
	// BuildImageFromDir. It is empty for images returned only from GetMicrovmImage.
	ArtifactURI string
}

Image is the high-level result of a MicroVM image creation or lookup.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager coordinates the common Lambda MicroVM workflow.

It packages application files, uploads artifacts to S3, calls the Lambda MicroVMs control-plane API through the AWS SDK for Go v2, and creates Session values that send authenticated HTTP requests to running MicroVM endpoints.

func NewManager 

func NewManager(cfg Config) (*Manager, error)

NewManager constructs a Manager from Config.

When SDK clients are not supplied, AWSConfig.Region must be set so the AWS SDK can resolve regional S3 and Lambda MicroVMs endpoints.

func (*Manager) BuildImage 

func (m *Manager) BuildImage(ctx context.Context, in BuildImageInput) (*Image, error)

BuildImage packages an fs.FS, uploads it to S3, and creates a MicroVM image.

The generated artifact zip contains files under Root at the zip root. Lambda downloads the artifact, executes the Dockerfile, starts the application, waits for configured image hooks, and snapshots the initialized MicroVM state.

func (*Manager) BuildImageFromDir 

func (m *Manager) BuildImageFromDir(ctx context.Context, in BuildImageFromDirInput) (*Image, error)

BuildImageFromDir packages a local directory and creates a MicroVM image.

func (*Manager) Run 

func (m *Manager) Run(ctx context.Context, in RunInput) (*Session, error)

Run launches a MicroVM, creates an endpoint auth token, and returns a Session.

The returned Session can call the MicroVM's dedicated HTTPS endpoint. If RunInput.Wait is true, Run waits for the MicroVM to reach RUNNING before creating the token.

func (*Manager) WaitImageReady 

func (m *Manager) WaitImageReady(ctx context.Context, in WaitImageInput) (*Image, error)

WaitImageReady polls GetMicrovmImage until the image is ready or failed.

CREATED and UPDATED are treated as ready states. CREATE_FAILED, UPDATE_FAILED, DELETE_FAILED, and DELETED are treated as terminal failures.

func (*Manager) WaitMicroVMRunning 

func (m *Manager) WaitMicroVMRunning(ctx context.Context, in WaitMicroVMInput) (*MicroVM, error)

WaitMicroVMRunning polls GetMicrovm until the MicroVM reaches RUNNING.

TERMINATING and TERMINATED are treated as terminal failures.

type MicroVM 

type MicroVM struct {
	// ID is the service-generated MicroVM identifier, such as mvm-...
	ID string
	// Endpoint is the HTTPS endpoint host used to communicate with this MicroVM.
	// Requests must include a valid X-aws-proxy-auth token.
	Endpoint string
	// ImageARN is the ARN of the MicroVM image used to launch the instance.
	ImageARN string
	// Version is the MicroVM image version used to launch the instance.
	Version string
	// State is the current MicroVM lifecycle state.
	State types.MicrovmState
	// StartedAt is the timestamp reported by Lambda when the MicroVM first
	// started. It is zero when the service response omits the timestamp.
	StartedAt time.Time
}

MicroVM summarizes a running or queried MicroVM instance.

type RunInput 

type RunInput struct {
	// ImageIdentifier is the ARN or identifier of the MicroVM image to run. This
	// field is required and maps to RunMicrovmInput.ImageIdentifier.
	ImageIdentifier string
	// ImageVersion selects a specific image version. If empty, Lambda uses the
	// latest active version of the image.
	ImageVersion string

	// ExecutionRoleARN is the IAM role assumed by the MicroVM at runtime. Use it
	// when the application or lifecycle hooks need AWS permissions.
	ExecutionRoleARN string
	// RunHookPayload is per-MicroVM initialization data delivered to the /run
	// lifecycle hook. The service limit is 16 KiB.
	RunHookPayload string
	// IdlePolicy configures automatic suspend and resume behavior based on
	// inbound endpoint traffic.
	IdlePolicy *types.IdlePolicy
	// Logging configures runtime CloudWatch Logs output, or disables logging.
	// Leave nil to use the service default.
	Logging types.Logging

	// IngressNetworkConnectors lists connector ARNs that enable inbound HTTPS
	// connectivity. If empty, Manager.Config.DefaultIngressConnectors is used.
	IngressNetworkConnectors []string
	// EgressNetworkConnectors lists connector ARNs for outbound connectivity,
	// such as public internet or VPC egress. If empty, the Manager defaults are
	// used.
	EgressNetworkConnectors []string

	// MaximumDuration is the maximum time the MicroVM may exist in running or
	// suspended states before Lambda terminates it. Lambda supports up to 8 hours.
	MaximumDuration time.Duration

	// AllowedPorts scopes the endpoint auth token created for the returned
	// Session. If empty, the token is scoped to DefaultMicroVMPort.
	AllowedPorts []types.PortSpecification
	// TokenExpiration controls the auth token lifetime for endpoint requests.
	// Lambda currently limits MicroVM auth tokens to 60 minutes; larger values
	// are clamped to one hour.
	TokenExpiration time.Duration
	// Wait tells Run to poll GetMicrovm until the MicroVM reaches RUNNING before
	// creating the endpoint auth token and returning the Session.
	Wait bool
	// WaitPollInterval overrides the Manager polling interval for this run.
	WaitPollInterval time.Duration
	// MutateRunInput can adjust the generated AWS SDK input immediately before
	// RunMicrovm is called.
	MutateRunInput func(*lambdamicrovms.RunMicrovmInput)
	// MutateTokenInput can adjust the generated CreateMicrovmAuthToken input
	// before each token creation or refresh.
	MutateTokenInput func(*lambdamicrovms.CreateMicrovmAuthTokenInput)
}

RunInput describes a MicroVM launch from an existing MicroVM image.

type Session 

type Session struct {

	// ID is the service-generated MicroVM identifier.
	ID string
	// Endpoint is the HTTPS endpoint host used for application traffic.
	Endpoint string
	// contains filtered or unexported fields
}

Session represents a MicroVM plus an endpoint auth token.

A Session is returned by Run and provides convenience methods for sending authenticated HTTP requests to the MicroVM endpoint. It automatically includes X-aws-proxy-auth and refreshes the token shortly before expiration.

func (*Session) Do 

func (s *Session) Do(req *http.Request, port int32) (*http.Response, error)

Do sends req to the MicroVM endpoint with Lambda MicroVM proxy headers.

If req.URL lacks a scheme or host, Do fills in https and the Session endpoint. The port argument sets X-aws-proxy-port; pass 0 to omit the header and let Lambda route to the default port 8080.

func (*Session) Get 

func (s *Session) Get(ctx context.Context, target string, port int32) (*http.Response, error)

Get sends an authenticated HTTP GET request to the MicroVM endpoint.

The target may be a relative path such as "/health" or an absolute URL. The port argument is forwarded as X-aws-proxy-port when greater than zero.

func (*Session) NewRequest 

func (s *Session) NewRequest(ctx context.Context, method, target string, body io.Reader) (*http.Request, error)

NewRequest creates an HTTP request targeting the MicroVM endpoint.

If target is a relative path, it is resolved against https://Session.Endpoint. Absolute http:// or https:// URLs are preserved.

func (*Session) Resume 

func (s *Session) Resume(ctx context.Context) error

Resume resumes a suspended MicroVM.

Lambda restores preserved memory and disk state, invokes the /resume lifecycle hook if configured, and transitions the MicroVM back to RUNNING on success.

func (*Session) Suspend 

func (s *Session) Suspend(ctx context.Context) error

Suspend suspends the MicroVM while preserving memory and disk state.

Lambda invokes the application's /suspend lifecycle hook, if configured, before checkpointing the MicroVM.

func (*Session) Terminate 

func (s *Session) Terminate(ctx context.Context) error

Terminate terminates the MicroVM and releases its resources.

Lambda invokes the /terminate lifecycle hook, if configured, before releasing resources. A terminated MicroVM cannot be resumed.

type WaitImageInput 

type WaitImageInput struct {
	// ImageIdentifier is the MicroVM image name or ARN to pass to GetMicrovmImage.
	ImageIdentifier string
	// PollInterval is the delay between polling attempts. If zero, the Manager
	// default is used.
	PollInterval time.Duration
}

WaitImageInput configures WaitImageReady polling.

type WaitMicroVMInput 

type WaitMicroVMInput struct {
	// MicroVMIdentifier is the MicroVM ID to pass to GetMicrovm.
	MicroVMIdentifier string
	// PollInterval is the delay between polling attempts. If zero, the Manager
	// default is used.
	PollInterval time.Duration
}

WaitMicroVMInput configures WaitMicroVMRunning polling.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.