Install & Compatibility
Where this runs
tested against v1.204.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 30.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.6s · import 0.000s · 31MB
29MB installed
● package 29MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
aws_iam
✓ from aws_cdk import aws_iam as iam
✗ import aws_cdk.aws_iam
Standard alias for the IAM construct library in AWS CDK v1.
Role
✓ from aws_cdk.aws_iam import Role, ServicePrincipal, PolicyStatement
Specific constructs for defining IAM roles and policies.
This quickstart demonstrates how to define an IAM role for a Lambda function with specific S3 read permissions and how to create an IAM user and attach an AWS managed policy. This code should be placed within an AWS CDK application structure (e.g., `app.py` or a stack file) and assumes you have the AWS CDK CLI and credentials configured. Remember to replace 'my-bucket' with an actual S3 bucket name or dynamic reference. Ensure `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` environment variables are set for non-environment-agnostic deployments.
import os
from aws_cdk import (
Stack,
App,
aws_iam as iam
)
class MyIamStack(Stack):
def __init__(self, scope: App, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
# Define an IAM Role for a Lambda function
lambda_role = iam.Role(
self,
"MyLambdaRole",
assumed_by=iam.ServicePrincipal("lambda.amazonaws.com")
)
# Add a policy statement to grant S3 read access
lambda_role.add_to_policy(
iam.PolicyStatement(
actions=["s3:GetObject", "s3:ListBucket"],
resources=["arn:aws:s3:::my-bucket/*", "arn:aws:s3:::my-bucket"]
)
)
# Define an IAM User
my_user = iam.User(self, "MyCdkUser")
# Attach an AWS managed policy to a user
my_user.add_managed_policy(
iam.ManagedPolicy.from_aws_managed_policy_name("ReadOnlyAccess")
)
app = App()
MyIamStack(app, "MyIamStack",
env={'account': os.environ.get('CDK_DEFAULT_ACCOUNT', os.environ.get('AWS_ACCOUNT_ID', '')),
'region': os.environ.get('CDK_DEFAULT_REGION', os.environ.get('AWS_REGION', ''))})
app.synth()
Debug
Known issues
breakingAWS CDK v1, including `aws-cdk-aws-iam` version 1.204.0, reached End-of-Support on June 1, 2023. It no longer receives maintenance, updates, patches, or technical support. Continuing to use v1 exposes your infrastructure to potential security vulnerabilities and unaddressed bugs. Migration to AWS CDK v2 is strongly recommended.fixMigrate your CDK application to AWS CDK v2. This involves updating dependencies to `aws-cdk-lib`, adjusting import statements, and re-bootstrapping your AWS environments with the modern CDK v2 bootstrap stack. Refer to the official AWS CDK v2 migration guide.
affects: 1.x.x (all versions)
breakingMigrating from AWS CDK v1 to v2 requires significant changes to import statements. Individual construct libraries (like `aws_iam`) are consolidated under the `aws-cdk-lib` package in v2.fixUpdate your import statements. For example, `from aws_cdk import aws_iam as iam` becomes `from aws_cdk_lib import aws_iam as iam` or `from aws_cdk import aws_iam as iam` if you configure your `cdk.json` with the appropriate feature flags or alias imports.
affects: 1.x.x to 2.x.x
breakingAWS CDK v2 requires environments to be bootstrapped with the modern bootstrap stack. The legacy v1 bootstrap stack is no longer supported. This can impact deployment permissions for assets.fixRe-bootstrap your AWS accounts/regions with `cdk bootstrap`. Ensure your deployment roles have the necessary permissions for the new v2 bootstrap resources, which might include new S3 asset bucket names and ECR repository names.
affects: 1.x.x to 2.x.x
gotchaGranting overly permissive IAM permissions (e.g., using `*` for actions or resources) violates the principle of least privilege, creating security vulnerabilities.fixAlways strive for the principle of least privilege. Define IAM policies with the minimum necessary actions and resources. Leverage `grant*` methods on resources (e.g., `bucket.grant_read(lambda_function)`) which often provision least-privilege roles automatically.
affects: All versions
gotchaHardcoding IAM resource names (e.g., policy names, role names) can lead to deployment failures and unrecoverable errors, especially when reusing templates across regions or refactoring.fixAvoid hardcoding explicit names for IAM resources. Allow CDK to generate logical IDs. If explicit naming is required, use dynamic references like `Fn::Join` with `AWS::Region` or `AWS::AccountId` to ensure uniqueness across environments.
affects: All versions
Errors
Common errors & fixes
Unable to resolve AWS account for the stack. This usually happens when you don't specify 'env' for your stack. For example: new MyStack(app, 'MyStack', { env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION } });
The CDK CLI or application cannot determine which AWS account and region to deploy to, often due to missing environment variables or explicit `env` properties on the stack. This is common when switching authentication methods (e.g., from IAM user to OIDC role).
fixExplicitly define the `env` property for your stacks using environment variables (`os.environ.get('CDK_DEFAULT_ACCOUNT', '')`, `os.environ.get('CDK_DEFAULT_REGION', '')`) or by passing them directly. Ensure your AWS CLI credentials are correctly configured and accessible by the CDK application. AccessDeniedException: User: arn:aws:iam::123456789012:user/MyUser is not authorized to perform: s3:PutObject on resource: arn:aws:s3:::cdk-123456789012-assets-us-east-1/...
The IAM principal (user or role) attempting to deploy the CDK stack lacks the necessary permissions to create or modify AWS resources, particularly the S3 bucket used by CDK for asset staging or the CloudFormation execution role.
fixEnsure the IAM principal has sufficient permissions. For deployments involving assets, verify write access to the CDK Toolkit's asset S3 bucket. For full stack deployments, the CloudFormation execution role needs permissions to manage all resources defined in the stack. Consider re-bootstrapping your environment if using v2.
The CloudFormation template contains too many resources. (Maximum: 500 resources)
The synthesized CloudFormation template exceeds the maximum allowed size (50KB) or resource count (500 resources for most regions).
fixBreak down large CDK applications into smaller, modular stacks. For templates larger than 50KB, ensure your environment is bootstrapped, as CDK will upload the template to S3. Consider using higher-level constructs or patterns to reduce the number of underlying CloudFormation resources.
The resource with name 'MyResource' already exists.
You are attempting to create an AWS resource with a fixed, explicit name that already exists in your AWS account, outside of or within another CloudFormation stack.
fixAvoid assigning explicit `resourceName` properties to constructs that might conflict with existing resources. Allow CDK to generate unique logical IDs. If you need to manage an existing resource, use `from_xxx_name` or `from_xxx_arn` methods to import it into your stack, or use `cdk import` functionality.
Upgrade
Version history
1.204.0latest on PyPI · released Jun 19, 2023
Audit
Dependencies
aws-cdk.corerequiredCore CDK library (implicit for v1 constructs)
nodejsrequiredRequired for the AWS CDK CLI, which synthesizes CloudFormation templates.
awsclirequiredRequired for AWS authentication and interactions during deployment.
pythonrequiredRuntime for the Python CDK application.