Walkthrough: Look up AMI IDs with a Lambda-backed custom resource

This walkthrough shows you how to use Lambda and a custom resource to dynamically look up Amazon Machine Image (AMI) IDs in your CloudFormation template. This can help you streamline how you update the AMI IDs in your CloudFormation templates.

When you create a CloudFormation template to launch an Amazon EC2 instance, you must specify an AMI ID, which is like a template for the operating system and software that will be installed on the instance. The correct AMI ID depends on the instance type and Amazon Web Services Region you're launching your instance in. These IDs can change regularly, such as when an AMI is updated with software updates.

You typically specify the AMI ID in a mapping section that maps AMI IDs to specific instance types and Regions. This means that to update the IDs, you must manually change them in each of your templates. However, by using custom resources and Lambda, you can create a function that gets the IDs of the latest AMIs for the instance type and Region that you're using. This way, you don't have to manually maintain the mappings between AMI IDs, instance types, and Regions in your stack templates.

This walkthrough shows you how to create a custom resource and associate a Lambda function with it to look up AMI IDs. It assumes that you are familiar with custom resources and Lambda functions. For an introduction to custom resources and how they work, see Custom resources. For information about Lambda, see the Amazon Lambda Developer Guide.

Overview

The following steps provide an overview of this implementation.

Template walkthrough

To view the entire sample template, see:

The following snippets explain relevant parts of the sample template to help you understand how to associate a Lambda function with a custom resource and how to use the function's response.

AWS::Lambda::Function resource AMIInfoFunction

The AWS::Lambda::Function resource specifies the function's source code, handler name, runtime environment, and execution role Amazon Resource Name (ARN).

"AMIInfoFunction": {
  "Type": "AWS::Lambda::Function",
  "Properties": {
    "Code": {
      "S3Bucket": { "Ref": "S3Bucket" },
      "S3Key": { "Ref": "S3Key" }
    },
    "Handler": { "Fn::Join" : [ "", [{ "Ref": "ModuleName" },".handler"] ] },
    "Runtime": "nodejs18.x",
    "Timeout": "30",
    "Role": { "Fn::GetAtt" : ["LambdaExecutionRole", "Arn"] }
  }
}

AMIInfoFunction:
  Type: AWS::Lambda::Function
  Properties:
    Code:
      S3Bucket: !Ref S3Bucket
      S3Key: !Ref S3Key
    Handler: !Sub "${ModuleName}.handler"
    Runtime: nodejs18.x
    Timeout: 30
    Role: !GetAtt LambdaExecutionRole.Arn

AWS::IAM::Role resource LambdaExecutionRole

The execution role grants the Lambda function permission to send logs to Amazon and to call the EC2 DescribeImages API.

"LambdaExecutionRole": {
  "Type": "AWS::IAM::Role",
  "Properties": {
    "AssumeRolePolicyDocument": {
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Principal": {"Service": ["lambda.amazonaws.com"]},
        "Action": ["sts:AssumeRole"]
      }]
    },
    "Path": "/",
    "Policies": [{
      "PolicyName": "root",
      "PolicyDocument": {
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Action": ["logs:CreateLogGroup","logs:CreateLogStream","logs:PutLogEvents"],
          "Resource": "arn:aws:logs:*:*:*"
        },
        {
          "Effect": "Allow",
          "Action": ["ec2:DescribeImages"],
          "Resource": "*"
        }]
      }
    }]
  }
}

LambdaExecutionRole:
  Type: AWS::IAM::Role
  Properties:
    AssumeRolePolicyDocument:
      Version: '2012-10-17'
      Statement:
      - Effect: Allow
        Principal:
          Service:
          - lambda.amazonaws.com
        Action:
        - sts:AssumeRole
    Path: "/"
    Policies:
    - PolicyName: root
      PolicyDocument:
        Version: '2012-10-17'
        Statement:
        - Effect: Allow
          Action:
          - logs:CreateLogGroup
          - logs:CreateLogStream
          - logs:PutLogEvents
          Resource: arn:aws:logs:*:*:*
        - Effect: Allow
          Action:
          - ec2:DescribeImages
          Resource: "*"

Custom::AMIInfo resource AMIInfo

For both the Linux and Windows templates, the custom resource invokes the Lambda function that's associated with it. To associate a function with a custom resource, you specify the ARN of the function for the ServiceToken property, using the Fn::GetAtt intrinsic function. CloudFormation sends the additional properties that are included in the custom resource declaration, such as Region and Architecture, to the Lambda function as inputs. The Lambda function determines the correct names and values for these input properties.

"AMIInfo": {
  "Type": "Custom::AMIInfo",
  "Properties": {
    "ServiceToken": { "Fn::GetAtt" : ["AMIInfoFunction", "Arn"] },
    "Region": { "Ref": "AWS::Region" },
    "Architecture": { "Fn::FindInMap" : [ "AWSInstanceType2Arch", { "Ref" : "InstanceType" }, "Arch" ] }
  }
}

AMIInfo:
  Type: Custom::AMIInfo
  Properties:
    ServiceToken: !GetAtt AMIInfoFunction.Arn
    Region: !Ref "AWS::Region"
    Architecture:
      Fn::FindInMap:
      - AWSInstanceType2Arch
      - !Ref InstanceType
      - Arch

For Windows, the custom resource provides the Windows version to the Lambda function instead of the instance's architecture.

"AMIInfo": {
  "Type": "Custom::AMIInfo",
  "Properties": {
    "ServiceToken": { "Fn::GetAtt": ["AMIInfoFunction", "Arn"] },
    "Region": { "Ref": "AWS::Region" },
    "OSName": { "Ref": "WindowsVersion" }
  }
}

AMIInfo:
  Type: Custom::AMIInfo
  Properties:
    ServiceToken: !GetAtt AMIInfoFunction.Arn
    Region: !Ref "AWS::Region"
    OSName: !Ref "WindowsVersion"

When CloudFormation invokes the Lambda function, the function calls the EC2 DescribeImages API, using the Amazon Web Services Region and instance architecture or the OS name to filter the list of images. Then the function sorts the list of images by date and returns the ID of the latest AMI.

When returning the ID of the latest AMI, the function sends the ID to a pre-signed URL in the Data property of the response object. The data is structured as a name-value pair, as shown in the following example:

"Data": { 
  "Id": "ami-02354e95b3example"
}

AWS::EC2::Instance resource SampleInstance

The following snippet shows how to get the data from a Lambda function. It uses the Fn::GetAtt intrinsic function, providing the name of the custom resource and the attribute name of the value that you want to get. In this walkthrough, the custom resource name is AMIInfo and the attribute name is Id.

"SampleInstance": {  
  "Type": "AWS::EC2::Instance",
  "Properties": {
    "InstanceType" : { "Ref": "InstanceType" },
    "ImageId": { "Fn::GetAtt": [ "AMIInfo", "Id" ] }
  }
}

SampleInstance:
  Type: AWS::EC2::Instance
  Properties:
    InstanceType: !Ref InstanceType
    ImageId: !GetAtt AMIInfo.Id

Prerequisites

Before you can complete the steps to create the stack, you must already have an Amazon S3 bucket. When you create a stack with a Lambda function, you must specify the location of the Amazon S3 bucket that contains the function's source code. The bucket must be in the same Amazon Web Services Region you create your stack in. For more information about creating a bucket, see Creating a bucket in the Amazon Simple Storage Service User Guide.

You must also have IAM permissions to use all the corresponding services, such as Lambda, Amazon EC2, and CloudFormation.

Step 1: Save the sample Lambda package to Amazon S3

In this step, you upload the sample Lambda package (a .zip file) to your Amazon S3 bucket.

This package contains the source code for the Lambda function and required libraries. For this walkthrough, the function doesn't require additional libraries.

Step 2: Launch the stack

In this step, you launch a stack from a sample template. The stack includes a Lambda function, an IAM role (execution role), a custom resource that invokes the function, and an EC2 instance that uses the results from the function.

During stack creation, the custom resource invokes the Lambda function and waits until the function sends a response to the pre-signed Amazon S3 URL. In the response, the function returns the ID of the latest AMI that corresponds to the EC2 instance type and Amazon Web Services Region you are creating the instance in. The data from the function's response is stored as an attribute of the custom resource, which is used to specify the AMI ID of the EC2 instance.

It might take several minutes for CloudFormation to create your stack. To monitor progress, view the stack events. For more information, see Viewing Amazon CloudFormation stack data and resources on the Amazon Web Services Management Console.

If stack creation succeeds, all resources in the stack, such as the Lambda function, custom resource, and EC2 instance, were created. You successfully used a Lambda function and custom resource to specify the AMI ID of an EC2 instance. You don't need to create and maintain a mapping of AMI IDs in this template.

To see which AMI ID CloudFormation used to create the EC2 instance, view the stack outputs.

If the Lambda function returns an error, view the function's logs in the CloudWatch Logs console. The name of the log stream is the physical ID of the custom resource, which you can find by viewing the stack's resources. For more information, see View log data in the Amazon CloudWatch User Guide.

Step 3: Clean up resources

Delete the stack to clean up all the stack resources that you created so that you aren't charged for unnecessary resources.

All the resources that you created are deleted.

Now that you understand how to create and use Lambda functions with CloudFormation, you can use the sample template and code from this walkthrough to build other stacks and functions.

Related information