Monitor use of a shared Amazon Machine Image across multiple AWS accounts
Created by Naveen Suthar (AWS) and Sandeep Gawande (AWS)
Code repository: cross-account-ami-auditing-terraform-samples | Environment: PoC or pilot | Technologies: Management & governance; DevOps; Serverless; Operations |
AWS services: Amazon DynamoDB; AWS Lambda; Amazon EventBridge |
Summary
Amazon Machine Images (AMIs) are used to create Amazon Elastic Compute Cloud (Amazon EC2) instances in your Amazon Web Services (AWS) environment. You can create AMIs in a separate, centralized AWS account, which is called a creator account in this pattern. You can then share the AMI across multiple AWS accounts that are in the same AWS Region, which are called consumer accounts in this pattern. Managing AMIs from a single account provides scalability and simplifies governance. In the consumer accounts, you can reference the shared AMI in Amazon EC2 Auto Scaling launch templates and Amazon Elastic Kubernetes Service (Amazon EKS) node groups.
When a shared AMI is deprecated, deregistered, or unshared, AWS services that refer to the AMI in the consumer accounts cannot use this AMI to launch new instances. Any auto scaling event or relaunch of the same instance fails. This can lead to issues in the production environment, such as application downtime or performance degradation. When AMI sharing and usage events occur in multiple AWS accounts, it can be difficult to monitor this activity.
This pattern helps you monitor shared AMI usage and status across accounts in the same Region. It uses serverless AWS services, such as Amazon EventBridge, Amazon DynamoDB, AWS Lambda, and Amazon Simple Email Service (Amazon SES). You provision the infrastructure as code (IaC) by using HashiCorp Terraform. This solution provides alerts when a service in a consumer account references a deregistered or unshared AMI.
Prerequisites and limitations
Prerequisites
Two or more active AWS accounts: one creator account and one or more consumer accounts
One or more AMIs that are shared from the creator account to a consumer account
Terraform CLI, installed
(Terraform documentation) Terraform AWS Provider, configured
(Terraform documentation) (Optional, but recommended) Terraform backend, configured
(Terraform documentation) Git, installed
Limitations
This pattern monitors AMIs that have been shared to specific accounts by using the account ID. This pattern does not monitor AMIs that have been shared to an organization by using the organization ID.
AMIs can only be shared to accounts that are within the same AWS Region. This pattern monitors AMIs within a single, target Region. To monitor use of AMIs in multiple Regions, you deploy this solution in each Region.
This pattern doesn't monitor any AMIs that were shared before this solution was deployed. If you want to monitor previously shared AMIs, you can unshare the AMI and then reshare it with the consumer accounts.
Product versions
Terraform version 1.2.0 or later
Terraform AWS Provider version 4.20 or later
Architecture
Target technology stack
The following resources are provisioned as IaC through Terraform:
Amazon DynamoDB tables
Amazon EventBridge rules
AWS Identity and Access Management (IAM) role
AWS Lambda functions
Amazon SES
Target architecture
![Architecture for monitoring shared AMI use and alerting users if the AMI is unshared or deregistered](/images/prescriptive-guidance/latest/patterns/images/pattern-img/2d709249-0c68-47d7-be5d-46e8a73071ed/images/8c48c4dd-d681-4c32-9ba8-8f5ad2d66f64.png)
The diagram shows the following workflow:
An AMI in the creator account is shared with a consumer account in the same AWS Region.
When the AMI is shared, an Amazon EventBridge rule in the creator account captures the
ModifyImageAttribute
event and initiates a Lambda function in the creator account.The Lambda function stores data related to the AMI in a DynamoDB table in the creator account.
When an AWS service in the consumer account uses the shared AMI to launch an Amazon EC2 instance or when the shared AMI is associated with a launch template, an EventBridge rule in the consumer account captures use of the shared AMI.
The EventBridge rule initiates a Lambda function in the consumer account. The Lambda function does the following:
The Lambda function updates the AMI-related data in a DynamoDB table in the consumer account.
The Lambda function assumes an IAM role in the creator account and updates the DynamoDB table in the creator account. In the
Mapping
table, it creates an item that maps the instance ID or launch template ID to its respective AMI ID.
The AMI that is centrally managed in the creator account is deprecated, deregistered, or unshared.
The EventBridge rule in the creator account captures the
ModifyImageAttribute
orDeregisterImage
event with theremove
action and initiates the Lambda function.The Lambda function checks the DynamoDB table to determine whether the AMI is used in any of the consumer accounts. If there are no instance IDs or launch template IDs associated with the AMI in the
Mapping
table, then the process is complete.If any instance IDs or launch template IDs are associated with the AMI in the
Mapping
table, then the Lambda function uses Amazon SES to send an email notification to the configured subscribers.
Tools
AWS services
Amazon DynamoDB is a fully managed NoSQL database service that provides fast, predictable, and scalable performance.
Amazon EventBridge is a serverless event bus service that helps you connect your applications with real-time data from a variety of sources. For example, AWS Lambda functions, HTTP invocation endpoints using API destinations, or event buses in other AWS accounts.
AWS Identity and Access Management (IAM) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them.
AWS Lambda is a compute service that helps you run code without needing to provision or manage servers. It runs your code only when needed and scales automatically, so you pay only for the compute time that you use.
Amazon Simple Email Service (Amazon SES) helps you send and receive emails by using your own email addresses and domains.
Other tools
HashiCorp Terraform
is an open-source infrastructure as code (IaC) tool that helps you use code to provision and manage cloud infrastructure and resources. Python
is a general-purpose computer programming language.
Code repository
The code for this pattern is available in the GitHub cross-account-ami-monitoring-terraform-samples
Best practices
Follow the Best practices for working with AWS Lambda functions.
Follow the Best practices for building AMIs.
When creating the IAM role, follow the principle of least privilege and grant the minimum permissions required to perform a task. For more information, see Grant least privilege and Security best practices in the IAM documentation.
Set up monitoring and alerting for the AWS Lambda functions. For more information, see Monitoring and troubleshooting Lambda functions.
Epics
Task | Description | Skills required |
---|---|---|
Create the AWS CLI named profiles. | For the creator account and each consumer account, create an AWS Command Line Interface (AWS CLI) named profile. For instructions, see Set Up the AWS CLI | DevOps engineer |
Clone the repository. | Enter the following command. This clones the cross-account-ami-monitoring-terraform-samples
| DevOps engineer |
Update the provider.tf file. |
For more information about configuring the providers, see Multiple provider configurations | DevOps engineer |
Update the terraform.tfvars file. |
| DevOps engineer |
Update the main.tf file. | Complete these steps only if you are deploying this solution to more than one consumer account. If you are deploying this solution to only one consumer account, no modification of this file is necessary.
| DevOps engineer |
Task | Description | Skills required |
---|---|---|
Deploy the solution. | In the Terraform CLI, enter the following commands to deploy the AWS resources in the creator and consumer accounts:
| DevOps engineer |
Verify the email address identity. | When you deployed the Terraform plan, Terraform created an email address identity for each consumer account in Amazon SES. Before notifications can be sent to that email address, you must verify the email address. For instructions, see Verifying an email address identity in the Amazon SES documentation. | General AWS |
Task | Description | Skills required |
---|---|---|
Validate deployment in the creator account. |
| DevOps engineer |
Validate deployment in the consumer account. |
| DevOps engineer |
Task | Description | Skills required |
---|---|---|
Create an AMI in the creator account. |
| DevOps engineer |
Use the AMI in the consumer account. | In the consumer account, use the shared AMI to create an EC2 instance or launch template. For instructions, see How do I launch an EC2 instance from a custom AMI | DevOps engineer |
Validate monitoring and alerting. |
| DevOps engineer |
Task | Description | Skills required |
---|---|---|
Delete the resources. |
| DevOps engineer |
Troubleshooting
Issue | Solution |
---|---|
I did not receive an email alert. | There could be multiple reasons why the Amazon SES email was not sent. Check the following:
|
Related resources
AWS documentation
Building Lambda functions with Python (Lambda documentation)
Create an AMI (Amazon EC2 documentation)
Share an AMI with specific AWS accounts (Amazon EC2 documentation)
Deregister your AMI (Amazon EC2 documentation)
Terraform documentation