View a markdown version of this page

AWS::Serverless::MicrovmImage - Amazon Serverless Application Model
SyntaxPropertiesReturn ValuesExamples
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

AWS::Serverless::MicrovmImage

Creates a Amazon Lambda MicroVM image from a code artifact stored in Amazon S3. A MicroVM image is a Firecracker snapshot built from a Dockerfile and application code, enabling sub-second startup for MicroVM instances.

Note

When you deploy to Amazon CloudFormation, Amazon SAM transforms your Amazon SAM resources into Amazon CloudFormation resources. For more information, see Generated Amazon CloudFormation resources for Amazon SAM.

Syntax

To declare this entity in your Amazon Serverless Application Model (Amazon SAM) template, use the following syntax.

YAML

Type: AWS::Serverless::MicrovmImage
Properties:
  AdditionalOsCapabilities: List
  BaseImageArn: String
  BaseImageVersion: String
  BuildRoleArn: String
  CodeUri: String
  CpuConfigurations: List
  Description: String
  EgressNetworkConnectors: List
  EnvironmentVariables: Map
  Hooks: Hooks
  Logging: Logging
  Name: String
  PropagateTags: Boolean
  Resources: List
  Tags: Map

Properties

AdditionalOsCapabilities

Additional OS capabilities to grant to the MicroVM runtime environment. If you don't specify a value, the service grants no additional OS capabilities.

Valid values: ALL

Type: List

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the AdditionalOsCapabilities property of an AWS::Lambda::MicrovmImage resource.

BaseImageArn

The ARN of the base MicroVM image to build from.

Type: String

Required: Yes

Amazon CloudFormation compatibility: This property is passed directly to the BaseImageArn property of an AWS::Lambda::MicrovmImage resource.

BaseImageVersion

The version of the base MicroVM image to use.

Type: String

Required: Yes

Amazon CloudFormation compatibility: This property is passed directly to the BaseImageVersion property of an AWS::Lambda::MicrovmImage resource.

BuildRoleArn

The ARN of the IAM role that the MicroVM build service assumes to download your code artifact from Amazon S3 and write build logs.

Type: String

Required: No

Amazon CloudFormation compatibility: This property is similar to the BuildRoleArn property of an AWS::Lambda::MicrovmImage resource. This is required in Amazon CloudFormation but not in Amazon SAM. If you don't specify a role, Amazon SAM creates one with a logical ID of <resource-logical-id>BuildRole. If your code artifact is encrypted with a customer managed key in Amazon KMS, you must provide your own role with the appropriate kms:Decrypt permission.

CodeUri

The Amazon S3 URI of the zip artifact containing the Dockerfile and application code.

Type: String

Required: Yes

Amazon CloudFormation compatibility: This property is transformed to the CodeArtifact property of an AWS::Lambda::MicrovmImage resource. Amazon SAM wraps the URI into the CodeArtifact.Uri structure.

CpuConfigurations

A list of CpuConfiguration objects that specify the supported CPU architectures for the MicroVM. If you don't specify a value, the service uses the default CPU architecture.

Type: List

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the CpuConfigurations property of an AWS::Lambda::MicrovmImage resource.

Description

A description of the MicroVM image.

Type: String

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the Description property of an AWS::Lambda::MicrovmImage resource.

EgressNetworkConnectors

The list of egress network connector ARNs available to the MicroVM at runtime.

Type: List

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the EgressNetworkConnectors property of an AWS::Lambda::MicrovmImage resource.

EnvironmentVariables

Environment variables set in the MicroVM runtime environment.

Type: Map

Required: No

Amazon CloudFormation compatibility: This property is similar to the EnvironmentVariables property of an AWS::Lambda::MicrovmImage resource. In Amazon SAM, specify as a map (for example, KEY: value). Amazon SAM converts to the Amazon CloudFormation array format [{Key: KEY, Value: value}].

Hooks

Lifecycle hook configuration for MicroVMs and MicroVM images.

Type: Hooks

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the Hooks property of an AWS::Lambda::MicrovmImage resource.

Logging

Configuration for MicroVM logging output. Specify exactly one: CloudWatch to enable CloudWatch logging, or Disabled to turn off logging.

Type: Logging

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the Logging property of an AWS::Lambda::MicrovmImage resource.

Name

The name of the MicroVM image.

Type: String

Required: Yes

Amazon CloudFormation compatibility: This property is passed directly to the Name property of an AWS::Lambda::MicrovmImage resource.

PropagateTags

Specifies whether to pass tags from the Tags property to generated resources, such as the auto-generated build role.

Type: Boolean

Required: No

Default: False

Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.

Resources

A list of Resources objects that specify the resource requirements for the MicroVM.

Type: List

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the Resources property of an AWS::Lambda::MicrovmImage resource.

Tags

A map of key-value pairs that specifies the tags added to this MicroVM image.

Type: Map

Required: No

Amazon CloudFormation compatibility: This property is similar to the Tags property of an AWS::Lambda::MicrovmImage resource. The Tags property in Amazon SAM consists of key-value pairs (whereas in Amazon CloudFormation this property consists of a list of Tag objects). Also, Amazon SAM automatically adds a lambda:createdBy:SAM tag to this MicroVM image, and to the default roles that are generated for it.

Return Values

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, it returns the ARN of the MicroVM image.

For more information about using the Ref function, see Ref in the Amazon CloudFormation User Guide.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using Fn::GetAtt, see Fn::GetAtt in the Amazon CloudFormation User Guide.

CreatedAt

The timestamp when the MicroVM image version was created.

ImageArn

The ARN of the MicroVM image.

LatestActiveImageVersion

The latest active version of the MicroVM image.

LatestFailedImageVersion

The latest failed version of the MicroVM image, if any.

State

The current state of the MicroVM image.

UpdatedAt

The timestamp when the MicroVM image version was last updated.

Examples

Minimal MicroVM image

The following example creates a MicroVM image with only the required properties. Amazon SAM automatically generates a build role.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Resources:
  MyMicroVM:
    Type: AWS::Serverless::MicrovmImage
    Properties:
      Name: my-app
      CodeUri: s3://my-bucket/app.zip
      BaseImageArn: arn:aws:lambda:us-east-2:aws:microvm-image:al2023-1
      BaseImageVersion: "0"

Full MicroVM image configuration

The following example creates a MicroVM image with all available properties configured.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Resources:
  MyMicroVM:
    Type: AWS::Serverless::MicrovmImage
    Properties:
      Name: my-app
      CodeUri: s3://my-bucket/app.zip
      BaseImageArn: arn:aws:lambda:us-east-2:aws:microvm-image:al2023-1
      BaseImageVersion: "0"
      Description: "Production MicroVM application"
      CpuConfigurations:
        - Architecture: ARM_64
      Resources:
        - MinimumMemoryInMiB: 1024
      AdditionalOsCapabilities:
        - ALL
      EgressNetworkConnectors:
        - arn:aws:lambda:us-east-2:aws:network-connector:aws-network-connector:INTERNET_EGRESS
      Hooks:
        Port: 9000
        MicrovmHooks:
          Run: ENABLED
          RunTimeoutInSeconds: 30
          Suspend: ENABLED
          Resume: ENABLED
        MicrovmImageHooks:
          Ready: ENABLED
          ReadyTimeoutInSeconds: 60
      EnvironmentVariables:
        LOG_LEVEL: info
        APP_ENV: production
      Logging:
        CloudWatch:
          LogGroup: /aws/lambda-microvms/my-app
      Tags:
        Environment: Production
        Team: Platform