|
| 1 | +# Lambda Managed Instances |
| 2 | + |
| 3 | +@Metadata { |
| 4 | + @PageKind(article) |
| 5 | + @PageColor(orange) |
| 6 | + @SupportedLanguage(swift) |
| 7 | + @PageImage(source: "lambda.png", alt: "AWS Lambda", purpose: icon) |
| 8 | +} |
| 9 | + |
| 10 | +Deploy Swift Lambda functions on Amazon EC2 instances with concurrent execution support |
| 11 | + |
| 12 | +## Overview |
| 13 | + |
| 14 | +Lambda Managed Instances enables you to run Lambda functions on your current-generation Amazon EC2 instances while maintaining serverless simplicity. AWS handles all infrastructure management tasks including instance lifecycle, OS and runtime patching, routing, load balancing, and auto-scaling, while you benefit from EC2 flexibility and cost optimization. |
| 15 | + |
| 16 | +The key difference from traditional Lambda is concurrent execution support—multiple invocations can run simultaneously within the same execution environment on the same EC2 host. |
| 17 | + |
| 18 | +## When to Use Lambda Managed Instances |
| 19 | + |
| 20 | +Lambda Managed Instances are ideal for: |
| 21 | + |
| 22 | +- **Sustained workloads** where cost optimization through EC2 pricing models provides better economics than traditional Lambda |
| 23 | +- **Specialized compute requirements** needing specific EC2 instance types such as Graviton4 or network-optimized instances |
| 24 | +- **High-throughput scenarios** where concurrent execution on the same host improves performance and resource utilization |
| 25 | +- **Workloads requiring EC2 flexibility** while maintaining serverless operational simplicity |
| 26 | + |
| 27 | +## Code Changes Required |
| 28 | + |
| 29 | +Migrating existing Lambda functions to Lambda Managed Instances requires two simple changes: |
| 30 | + |
| 31 | +### 1. Use `LambdaManagedRuntime` Instead of `LambdaRuntime` |
| 32 | + |
| 33 | +Replace your standard `LambdaRuntime` initialization with `LambdaManagedRuntime`: |
| 34 | + |
| 35 | +```swift |
| 36 | +import AWSLambdaRuntime |
| 37 | + |
| 38 | +// Before (standard Lambda) |
| 39 | +let runtime = LambdaRuntime { |
| 40 | + (event: HelloRequest, context: LambdaContext) in |
| 41 | + HelloResponse(greetings: "Hello \(event.name)!") |
| 42 | +} |
| 43 | + |
| 44 | +// After (Lambda Managed Instances) |
| 45 | +let runtime = LambdaManagedRuntime { |
| 46 | + (event: HelloRequest, context: LambdaContext) in |
| 47 | + HelloResponse(greetings: "Hello \(event.name)!") |
| 48 | +} |
| 49 | + |
| 50 | +try await runtime.run() |
| 51 | +``` |
| 52 | + |
| 53 | +### 2. Ensure Handlers Conform to `Sendable` |
| 54 | + |
| 55 | +Because Lambda Managed Instances support concurrent invocations, your handler functions and structs must conform to the `Sendable` protocol to ensure thread safety: |
| 56 | + |
| 57 | +```swift |
| 58 | +import AWSLambdaRuntime |
| 59 | + |
| 60 | +// Handler struct must explicitly conform to Sendable |
| 61 | +struct MyHandler: LambdaWithBackgroundProcessingHandler, Sendable { |
| 62 | + typealias Event = MyRequest |
| 63 | + typealias Output = MyResponse |
| 64 | + |
| 65 | + func handle( |
| 66 | + _ event: Event, |
| 67 | + outputWriter: some LambdaResponseWriter<Output>, |
| 68 | + context: LambdaContext |
| 69 | + ) async throws { |
| 70 | + try await outputWriter.write(MyResponse(message: "Processed")) |
| 71 | + } |
| 72 | +} |
| 73 | + |
| 74 | +// Use LambdaCodableAdapter to pass the handler to LambdaManagedRuntime |
| 75 | +let adapter = LambdaCodableAdapter(handler: MyHandler()) |
| 76 | +let runtime = LambdaManagedRuntime(handler: adapter) |
| 77 | +try await runtime.run() |
| 78 | +``` |
| 79 | + |
| 80 | +For simple data structures, the Swift compiler automatically infers `Sendable` conformance, but explicitly declaring it is recommended for clarity and safety. |
| 81 | + |
| 82 | +## How It Works |
| 83 | + |
| 84 | +The runtime automatically detects the configured concurrency level through the `AWS_LAMBDA_MAX_CONCURRENCY` environment variable and launches the appropriate number of Runtime Interface Clients (RICs) to handle concurrent requests efficiently. |
| 85 | + |
| 86 | +When `AWS_LAMBDA_MAX_CONCURRENCY` is 1 or unset, the runtime maintains single-threaded behavior for optimal performance on traditional Lambda deployments, ensuring backward compatibility. |
| 87 | + |
| 88 | +The managed instances support is implemented behind a Swift package trait (`ManagedRuntimeSupport`) that's enabled by default. If you're concerned about binary size and don't need managed instances support, you can disable this specific trait in your `Package.swift`: |
| 89 | + |
| 90 | +```swift |
| 91 | +dependencies: [ |
| 92 | + .package( |
| 93 | + url: "https://github.com/awslabs/swift-aws-lambda-runtime.git", |
| 94 | + from: "2.0.0", |
| 95 | + traits: [ |
| 96 | + // Keep other default traits but exclude ManagedRuntimeSupport |
| 97 | + "FoundationJSONSupport", |
| 98 | + "ServiceLifecycleSupport", |
| 99 | + "LocalServerSupport" |
| 100 | + ] |
| 101 | + ), |
| 102 | +], |
| 103 | +targets: [ |
| 104 | + .executableTarget( |
| 105 | + name: "MyLambda", |
| 106 | + dependencies: [ |
| 107 | + .product(name: "AWSLambdaRuntime", package: "swift-aws-lambda-runtime"), |
| 108 | + ] |
| 109 | + ), |
| 110 | +] |
| 111 | +``` |
| 112 | + |
| 113 | +## Prerequisites |
| 114 | + |
| 115 | +Before deploying to Lambda Managed Instances: |
| 116 | + |
| 117 | +1. Create a [Lambda Managed Instances capacity provider](https://docs.aws.amazon.com/lambda/latest/dg/lambda-managed-instances-capacity-providers.html) in your AWS account |
| 118 | +2. Configure your deployment to reference the capacity provider ARN |
| 119 | + |
| 120 | +## Example Functions |
| 121 | + |
| 122 | +The Swift AWS Lambda Runtime includes three comprehensive examples demonstrating Lambda Managed Instances capabilities: |
| 123 | + |
| 124 | +- **HelloJSON**: JSON input/output with structured data types and concurrent execution |
| 125 | +- **Streaming**: Response streaming with concurrent invocation handling |
| 126 | +- **BackgroundTasks**: Long-running background processing after response with concurrency support |
| 127 | + |
| 128 | +See the [ManagedInstances example directory](https://github.com/awslabs/swift-aws-lambda-runtime/tree/main/Examples/ManagedInstances) for complete deployment instructions using AWS SAM. |
| 129 | + |
| 130 | +## Additional Resources |
| 131 | + |
| 132 | +- [AWS Lambda Managed Instances Documentation](https://docs.aws.amazon.com/lambda/latest/dg/lambda-managed-instances.html) |
| 133 | +- [Execution Environment Guide](https://docs.aws.amazon.com/lambda/latest/dg/lambda-managed-instances-execution-environment.html) |
| 134 | +- [Capacity Provider Configuration](https://docs.aws.amazon.com/lambda/latest/dg/lambda-managed-instances-capacity-providers.html) |
0 commit comments