Skip to content

Commit 262ecc2

Browse files
vincent067liwenjun-dev
vincent067
and
liwenjun-dev
authored
docs: add comprehensive IAM permissions guide (#303)
Add README-IAM-PERMISSIONS.md with detailed guidance on: - Least privilege configuration options - Common IAM issues and solutions (addresses #260, #259) - Permission reference for each Lambda function - Testing procedures for IAM setup Also add link to the new guide in main README.md. This helps users configure secure, minimal permissions without running into common pitfalls like qualifier issues. Co-authored-by: liwenjun-dev <liwenjun.dev@gmail.com>
1 parent 8e8a2d2 commit 262ecc2

2 files changed

Lines changed: 209 additions & 0 deletions

File tree

‎README-IAM-PERMISSIONS.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# IAM Permissions Guide for Lambda Power Tuning
2+
3+
This guide explains how to configure IAM permissions for AWS Lambda Power Tuning with the principle of least privilege.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Default Permissions](#default-permissions)
9+
- [Least Privilege Configuration](#least-privilege-configuration)
10+
- [Common Issues & Solutions](#common-issues--solutions)
11+
- [Permission Reference](#permission-reference)
12+
13+
## Overview
14+
15+
By default, the Lambda Power Tuning state machine uses `*` as the `lambdaResource` parameter, allowing it to invoke any Lambda function in your account. While this is convenient for testing, it's recommended to restrict permissions to specific functions or prefixes in production environments.
16+
17+
## Default Permissions
18+
19+
When you deploy with the default `lambdaResource = "*"`, the following IAM permissions are granted:
20+
21+
| Function | Permissions | Resource |
22+
|----------|-------------|----------|
23+
| Initializer | `lambda:GetFunctionConfiguration` | `*` |
24+
| Publisher | `lambda:GetAlias`, `lambda:GetFunctionConfiguration`, `lambda:PublishVersion`, `lambda:UpdateFunctionConfiguration`, `lambda:CreateAlias`, `lambda:UpdateAlias` | `*` |
25+
| Executor | `lambda:InvokeFunction`, `lambda:GetFunctionConfiguration` | `*` |
26+
| Cleaner | `lambda:GetAlias`, `lambda:DeleteAlias`, `lambda:DeleteFunction` | `*` |
27+
| Optimizer | `lambda:GetAlias`, `lambda:PublishVersion`, `lambda:UpdateFunctionConfiguration`, `lambda:GetFunctionConfiguration`, `lambda:CreateAlias`, `lambda:UpdateAlias` | `*` |
28+
29+
## Least Privilege Configuration
30+
31+
### Using Function Name Prefixes
32+
33+
To restrict the state machine to functions with a specific prefix (e.g., `prod-*`):
34+
35+
```hcl
36+
# Terraform example
37+
resource "aws_serverlessapplicationrepository_cloudformation_stack" "lambda-power-tuning" {
38+
name = "lambda-power-tuner"
39+
application_id = "arn:aws:serverlessrepo:us-east-1:451282441545:applications/aws-lambda-power-tuning"
40+
capabilities = ["CAPABILITY_IAM"]
41+
42+
parameters = {
43+
lambdaResource = "arn:aws:lambda:*:*:function:prod-*"
44+
}
45+
}
46+
```
47+
48+
### Using Specific Function ARNs
49+
50+
For even tighter security, you can specify exact function ARNs:
51+
52+
```hcl
53+
parameters = {
54+
lambdaResource = "arn:aws:lambda:us-east-1:123456789012:function:my-specific-function"
55+
}
56+
```
57+
58+
### Same-Region Restriction
59+
60+
To restrict to functions within a specific region:
61+
62+
```hcl
63+
parameters = {
64+
lambdaResource = "arn:aws:lambda:us-east-1:*:function:*"
65+
}
66+
```
67+
68+
## Common Issues & Solutions
69+
70+
### Issue: Initializer fails with "Access Denied" error
71+
72+
**Symptom**: The state machine fails at the Initializer step with an error like:
73+
```
74+
AccessDeniedException: User is not authorized to perform: lambda:GetFunctionConfiguration
75+
```
76+
77+
**Root Cause**: When using SAR (Serverless Application Repository) deployment, the Lambda function ARN includes the `$LATEST` qualifier. Your IAM policy needs to explicitly allow actions on ARNs with this qualifier.
78+
79+
**Solution**: Ensure your `lambdaResource` parameter includes support for qualified ARNs:
80+
81+
```hcl
82+
# ❌ This will fail with Initializer
83+
lambdaResource = "arn:aws:lambda:us-east-1:123456789012:function:my-function"
84+
85+
# ✅ This will work - includes any qualifier (including $LATEST)
86+
lambdaResource = "arn:aws:lambda:us-east-1:123456789012:function:my-function*"
87+
88+
# ✅ Or use wildcard for all functions in the region
89+
lambdaResource = "arn:aws:lambda:us-east-1:123456789012:function:*"
90+
```
91+
92+
### Issue: AWSLambdaExecute policy conflict with Terraform
93+
94+
**Symptom**: When using the AWS Terraform provider with `aws_iam_policy_attachment`, existing policies are detached.
95+
96+
**Root Cause**: The `aws_iam_policy_attachment` resource manages the complete set of attached policies, not additive.
97+
98+
**Solution**: Use `aws_iam_role_policy_attachment` instead:
99+
100+
```hcl
101+
# ❌ This will detach other policies
102+
resource "aws_iam_policy_attachment" "lambda_power_tuning" {
103+
name = "lambda-power-tuning-attachment"
104+
roles = [aws_iam_role.example.name]
105+
policy_arn = "arn:aws:iam::aws:policy/AWSLambdaExecute"
106+
}
107+
108+
# ✅ This adds the policy without affecting others
109+
resource "aws_iam_role_policy_attachment" "lambda_power_tuning" {
110+
role = aws_iam_role.example.name
111+
policy_arn = "arn:aws:iam::aws:policy/AWSLambdaExecute"
112+
}
113+
```
114+
115+
### Issue: Cross-region invocation fails
116+
117+
**Symptom**: The Executor fails when trying to invoke a Lambda function in a different region.
118+
119+
**Root Cause**: The `lambdaResource` parameter restricts the region.
120+
121+
**Solution**: Either use `*` for the region or explicitly include the target region:
122+
123+
```hcl
124+
# Allow all regions
125+
lambdaResource = "arn:aws:lambda:*:*:function:my-function*"
126+
127+
# Or specify multiple regions
128+
# Note: You'll need to deploy separate state machines for each region
129+
```
130+
131+
## Permission Reference
132+
133+
### Required Permissions by Function
134+
135+
#### Initializer
136+
- `lambda:GetFunctionConfiguration` - Required to read the current function configuration before creating test versions
137+
138+
#### Publisher
139+
- `lambda:GetAlias` - Check if alias exists
140+
- `lambda:GetFunctionConfiguration` - Read function configuration
141+
- `lambda:PublishVersion` - Create new versions for testing
142+
- `lambda:UpdateFunctionConfiguration` - Update memory configuration
143+
- `lambda:CreateAlias` - Create aliases for each power value
144+
- `lambda:UpdateAlias` - Update existing aliases
145+
146+
#### Executor
147+
- `lambda:InvokeFunction` - Invoke the function being tuned
148+
- `lambda:GetFunctionConfiguration` - Read function configuration
149+
150+
#### Cleaner
151+
- `lambda:GetAlias` - Check aliases before deletion
152+
- `lambda:DeleteAlias` - Remove test aliases
153+
- `lambda:DeleteFunction` - Remove test versions (only by version/qualifier)
154+
155+
#### Optimizer
156+
- Same as Publisher (when `autoOptimize` is enabled)
157+
158+
## Examples
159+
160+
### Example 1: Dev/Test Environment (Permissive)
161+
162+
```hcl
163+
parameters = {
164+
lambdaResource = "arn:aws:lambda:us-west-2:123456789012:function:dev-*"
165+
}
166+
```
167+
168+
### Example 2: Production Environment (Strict)
169+
170+
```hcl
171+
parameters = {
172+
lambdaResource = "arn:aws:lambda:us-east-1:123456789012:function:prod-api-*"
173+
}
174+
```
175+
176+
### Example 3: Multi-Account Setup
177+
178+
If you have separate accounts for dev/staging/prod, deploy separate state machines with account-specific resources:
179+
180+
```hcl
181+
# Production account
182+
parameters = {
183+
lambdaResource = "arn:aws:lambda:us-east-1:PROD_ACCOUNT:function:*"
184+
}
185+
```
186+
187+
## Testing Your Permissions
188+
189+
Before running a full power-tuning execution, you can test your IAM configuration with this AWS CLI command:
190+
191+
```bash
192+
# Test if Initializer can get function configuration
193+
aws lambda get-function-configuration \
194+
--function-name arn:aws:lambda:us-east-1:123456789012:function:my-function:$LATEST
195+
196+
# Test if you can invoke the function
197+
aws lambda invoke \
198+
--function-name arn:aws:lambda:us-east-1:123456789012:function:my-function \
199+
--payload '{}' \
200+
/dev/null
201+
```
202+
203+
If these commands succeed, your IAM configuration should work with Lambda Power Tuning.
204+
205+
---
206+
207+
*For more information, see the [Security section in README-ADVANCED.md](README-ADVANCED.md#security) and [deployment options](README-DEPLOY.md).*

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,8 @@ Optionally, you could deploy your own custom visualization tool and configure th
157157

158158
## Additional features, considerations, and internals
159159

160+
For detailed IAM permission configuration guidance, see [README-IAM-PERMISSIONS.md](README-IAM-PERMISSIONS.md).
161+
160162
[Here](README-ADVANCED.md) you can find out more about some advanced features of this project, its internals, and some considerations about security and execution cost.
161163

162164
## Contributing

0 commit comments

Comments
 (0)