Merge pull request #2891 from DmitryGulin/pattern/lambda-managed-instances-tf

add Hello World lambda managed instances TF pattern

Author: julianwood

lambda-managed-instances-nodejs-tf/.gitignore

@@ -0,0 +1,31 @@
+# Terraform files
+*.tfstate
+*.tfstate.*
+*.tfvars
+*.tfvars.json
+.terraform/
+.terraform.lock.hcl
+terraform.tfplan
+terraform.tfplan.*
+
+# Lambda function package
+lambda-function.zip
+
+# Test response files
+response.json
+custom-response.json
+output.json
+
+# Node.js dependencies
+lambda/node_modules/
+lambda/package-lock.json
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo

lambda-managed-instances-nodejs-tf/README.md

@@ -0,0 +1,207 @@
+# Hello World on AWS Lambda Managed Instances (Terraform)
+
+This pattern demonstrates how to deploy a simple Hello World Lambda function running on AWS Lambda Managed Instances using Terraform. AWS Lambda Managed Instances enables you to run Lambda functions on EC2 instances while maintaining Lambda's operational simplicity. It fully manages infrastructure tasks including instance lifecycle, OS and runtime patching, routing, load balancing, and auto scaling.
+
+Learn more about this pattern at Serverless Land Patterns: https://serverlessland.com/patterns/lambda-managed-instances-tf
+
+Important: this application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the [AWS Pricing page](https://aws.amazon.com/pricing/) for details. You are responsible for any AWS costs incurred. No warranty is implied in this example.
+
+**Note**: AWS Lambda Managed Instances provision EC2 instances that are **NOT eligible for the AWS Free Tier**. These instances will incur charges immediately upon deployment, regardless of your Free Tier status.
+
+## Requirements
+
+* [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources.
+* [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) (latest available version) installed and configured
+* [Git Installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+* [Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli) (version 1.0 or later) installed
+* [Node.js](https://nodejs.org/) (version 24.x or later) for Lambda function dependencies
+
+## Deployment Instructions
+
+1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository:
+    ``` 
+    git clone https://github.com/aws-samples/serverless-patterns
+    ```
+1. Change directory to the pattern directory:
+    ```
+    cd lambda-managed-instances-tf
+    ```
+
+### Manual Deployment
+
+1. Install Lambda function dependencies:
+    ```
+    cd lambda && npm install && cd ..
+    ```
+1. Initialize Terraform:
+    ```
+    terraform init
+    ```
+1. Plan the deployment:
+    ```
+    terraform plan
+    ```
+1. Deploy the infrastructure:
+    ```
+    terraform apply
+    ```
+    Note: This stack will deploy to your default AWS region. You can specify a different region by setting the `aws_region` variable.
+
+### Deployment script
+
+1. Use can use `deploy.sh` script to run all deployment commands:
+    ```
+    ./deploy.sh [aws-region]
+    ```
+
+1. Note the outputs from the Terraform deployment process. These contain the resource names and/or ARNs which are used for testing.
+
+
+You can customize the deployment by modifying the variables in `variables.tf` or by passing variables during deployment:
+
+```bash
+terraform apply -var="aws_region=us-east-1"
+```
+
+## How it works
+
+![Architecture Diagram](doc/architecture-diagram.png)
+
+This pattern creates a capacity provider with VPC and security group configuration, then deploys a Node.js Lambda function (ARM64 architecture) that is associated with the capacity provider to run on managed EC2 instances. The Terraform configuration provisions a complete VPC infrastructure with public and private subnets across multiple availability zones, NAT gateways for outbound connectivity, and all necessary IAM roles and permissions.
+
+## Testing
+
+After deployment, you can test the Lambda function using AWS CLI or AWS Console.
+
+### AWS CLI Testing
+
+1. **Basic function invocation**:
+   ```bash
+   aws lambda invoke \
+     --function-name hello-world-managed-instances-tf \
+     --payload file://events/hello-world.json \
+     --cli-binary-format raw-in-base64-out \
+     response.json
+   ```
+
+2. **View the response**:
+   ```bash
+   cat response.json
+   ```
+
+3. **Custom name invocation**:
+   ```bash
+   echo '{"name":"Lambda Managed Instances"}' | aws lambda invoke \
+     --function-name hello-world-managed-instances-tf \
+     --payload file:///dev/stdin \
+     --cli-binary-format raw-in-base64-out \
+     custom-response.json
+   ```
+
+4. **View CloudWatch logs**:
+   ```bash
+   aws logs filter-log-events \
+     --log-group-name /aws/lambda/hello-world-managed-instances-tf \
+     --start-time $(date -d '5 minutes ago' +%s)000
+   ```
+
+### AWS Console Testing
+
+1. Navigate to the Lambda service in the AWS Console
+2. Find the function named `hello-world-managed-instances-tf`
+3. Create a test event using the payload from `events/hello-world.json` or create a custom payload:
+   ```json
+   {
+     "name": "Your Custom Name"
+   }
+   ```
+4. Execute the test and observe the results in the execution logs
+
+### Expected Response
+
+The function returns a JSON response with the following structure:
+
+```json
+{
+  "response": "Hello AWS Lambda on Managed Instances"
+}
+```
+
+### Monitoring and Observability
+
+Monitor the function execution through:
+- **CloudWatch Logs**: Detailed execution logs with event and response data
+- **Lambda Metrics**: Function performance and invocation statistics
+- **CloudWatch Metrics**: Custom metrics and alarms for monitoring
+
+## Inspecting AWS Lambda Managed Instances Infrastructure
+
+AWS Lambda Managed Instances provision EC2 instances behind the scenes to run your Lambda functions. You can inspect this infrastructure using AWS CLI commands:
+
+### View Capacity Provider Details
+
+```bash
+aws lambda get-capacity-provider --capacity-provider-name lambda-capacity-provider
+```
+
+This shows:
+- Capacity provider ARN and state
+- VPC configuration (subnets and security groups)
+- Instance requirements (architecture, scaling mode)
+- IAM roles and permissions
+
+### List Associated EC2 Instances
+
+```bash
+aws ec2 describe-instances \
+  --filters "Name=tag:aws:lambda:capacity-provider,Values=arn:aws:lambda:*:capacity-provider:lambda-capacity-provider" \
+  --query 'Reservations[*].Instances[*].[InstanceId,InstanceType,State.Name,LaunchTime,SubnetId,PrivateIpAddress]' \
+  --output table
+```
+
+This displays:
+- Instance IDs and types
+- Current state (running, pending, terminated)
+- Launch times and subnet distribution
+- Private IP addresses within the VPC
+
+**Note**: For a complete list of supported EC2 instance types for AWS Lambda Managed Instances and their pricing, see the [AWS Lambda Pricing page](https://aws.amazon.com/lambda/pricing/).
+
+### Understanding Instance Behavior
+
+**Auto-scaling**: Instances are automatically created and terminated based on function demand
+- **Scale-up**: New instances launch when function invocation increases
+- **Scale-down**: Unused instances terminate after periods of low activity
+- **Multi-AZ**: Instances are distributed across availability zones for high availability
+
+**Instance Lifecycle**:
+- Instances typically launch within 1-2 minutes of stack deployment
+- They remain running to provide immediate function execution
+- AWS manages all instance lifecycle operations automatically
+
+### Automated Testing
+
+The included test script (`./test-lambda.sh`) automatically inspects both the capacity provider and EC2 instances, providing a comprehensive view of the managed instances infrastructure.
+
+## Regional Availability
+
+This stack will deploy to your default AWS region or the region specified in the `aws_region` variable. Before deploying, please verify that AWS Lambda Managed Instances feature is available in your target region by using the [AWS capabilities explorer](https://builder.aws.com/build/capabilities/explore) or consulting the official [AWS Lambda Managed Instances documentation](https://docs.aws.amazon.com/lambda/latest/dg/lambda-managed-instances.html).
+
+## Cleanup
+ 
+1. Delete the infrastructure:
+    ```bash
+    terraform destroy
+    ```
+    
+    **Alternative**: Use the automated cleanup script:
+    ```bash
+    ./cleanup.sh [aws-region]
+    ```
+
+1. Confirm the resources have been deleted by checking the AWS Console.
+
+----
+Copyright 2026 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: MIT-0

lambda-managed-instances-nodejs-tf/cleanup.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+
+# Cleanup script for Lambda Managed Instances Terraform pattern
+# Usage: ./cleanup.sh [aws-region]
+
+set -e
+
+# Configuration
+AWS_REGION=${1:-us-west-2}
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}=== Cleaning up Lambda Managed Instances Pattern (Terraform) ===${NC}"
+echo -e "${YELLOW}Region: ${AWS_REGION}${NC}"
+echo ""
+
+# Confirm destruction
+echo -e "${YELLOW}This will destroy all resources created by this pattern.${NC}"
+read -p "Are you sure you want to continue? (y/N): " -n 1 -r
+echo
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    echo -e "${YELLOW}Cleanup cancelled.${NC}"
+    exit 0
+fi
+
+# Destroy infrastructure
+echo -e "${BLUE}Destroying Terraform infrastructure...${NC}"
+terraform destroy -var="aws_region=${AWS_REGION}" -auto-approve
+
+if [ $? -eq 0 ]; then
+    echo -e "${GREEN}✓ Infrastructure successfully destroyed${NC}"
+else
+    echo -e "${RED}✗ Failed to destroy infrastructure${NC}"
+    exit 1
+fi
+
+# Clean up local files
+echo -e "${BLUE}Cleaning up local files...${NC}"
+rm -f lambda-function.zip
+rm -f response.json
+rm -f custom-response.json
+rm -f output.json
+
+# Clean up Terraform temporary and state files
+echo -e "${BLUE}Cleaning up Terraform temporary and state files...${NC}"
+rm -f terraform.tfstate
+rm -f terraform.tfstate.backup
+rm -f .terraform.tfstate.lock.info
+rm -rf .terraform/
+rm -f .terraform.lock.hcl
+rm -f terraform.tfplan
+rm -f terraform.log
+rm -f crash.log
+
+echo ""
+echo -e "${GREEN}=== Cleanup completed successfully! ===${NC}"

lambda-managed-instances-nodejs-tf/deploy.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+# Deployment script for Lambda Managed Instances Terraform pattern
+# Usage: ./deploy.sh [aws-region]
+
+set -e
+
+# Configuration
+AWS_REGION=${1:-us-west-2}
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}=== Deploying Lambda Managed Instances Pattern (Terraform) ===${NC}"
+echo -e "${YELLOW}Region: ${AWS_REGION}${NC}"
+echo ""
+
+# Step 1: Install Lambda dependencies
+echo -e "${BLUE}Step 1: Installing Lambda function dependencies${NC}"
+cd lambda
+if [ ! -f "package-lock.json" ]; then
+    npm install
+else
+    echo "Dependencies already installed"
+fi
+cd ..
+
+# Step 2: Initialize Terraform
+echo -e "${BLUE}Step 2: Initializing Terraform${NC}"
+terraform init
+
+# Step 3: Plan deployment
+echo -e "${BLUE}Step 3: Planning Terraform deployment${NC}"
+terraform plan -var="aws_region=${AWS_REGION}"
+
+# Step 4: Apply infrastructure
+echo -e "${BLUE}Step 4: Applying Terraform configuration${NC}"
+terraform apply -var="aws_region=${AWS_REGION}" -auto-approve
+
+echo -e "${GREEN}✓ Lambda function automatically associated with capacity provider via Terraform${NC}"
+
+echo ""
+echo -e "${GREEN}=== Deployment completed successfully! ===${NC}"
+echo ""
+echo -e "${YELLOW}Outputs:${NC}"
+terraform output
+
+echo ""
+echo -e "${YELLOW}Next steps:${NC}"
+CAPACITY_PROVIDER_NAME=$(terraform output -raw capacity_provider_name)
+FUNCTION_NAME=$(terraform output -raw function_name)
+echo "1. Test the function: ./test-lambda.sh"
+echo "2. View capacity provider: aws lambda get-capacity-provider --capacity-provider-name $CAPACITY_PROVIDER_NAME --region $AWS_REGION"
+echo "3. View function details: aws lambda get-function --function-name $FUNCTION_NAME --region $AWS_REGION"

lambda-managed-instances-nodejs-tf/doc/architecture-diagram.png

@@ -0,0 +1,3 @@
+{
+  "name": "AWS Lambda Managed Instances"
+}