Install & Compatibility
Where this runs
tested against v2.259.0a0 · 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 · 360.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 17.5s · import 0.000s · 361MB
398MB installed
● package 398MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
aws_iot_alpha
✓ import aws_cdk.aws_iot_alpha as iot
Standard import alias for the IoT alpha module.
aws_iot_actions_alpha
✓ import aws_cdk.aws_iot_actions_alpha as actions
Required for defining IoT Rule actions.
aws_lambda
✓ import aws_cdk.aws_lambda as lambda_
Standard import for AWS Lambda constructs, often used with IoT Rules.
This quickstart defines an AWS IoT Topic Rule that listens for messages on the MQTT topic `device/+/data` and invokes an AWS Lambda function with the message payload. It demonstrates the use of `TopicRule` and `LambdaFunctionAction` from the alpha modules, showcasing how to connect IoT device messages to other AWS services. Before running, ensure AWS credentials and CDK environment variables (`CDK_DEFAULT_ACCOUNT`, `CDK_DEFAULT_REGION`) are configured.
import os
from aws_cdk import (
App,
Stack,
aws_lambda as lambda_,
aws_cdk as cdk
)
import aws_cdk.aws_iot_alpha as iot
import aws_cdk.aws_iot_actions_alpha as actions
class IotRuleStack(Stack):
def __init__(self, scope: App, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
# Define a Lambda function to be invoked by the IoT Rule
my_function = lambda_.Function(
self, "MyIoTFunction",
runtime=lambda_.Runtime.PYTHON_3_9,
handler="index.handler",
code=lambda_.Code.from_inline(
"""import json\n\ndef handler(event, context):\n print("Received event: {}".format(json.dumps(event)))\n return {'statusCode': 200, 'body': 'OK'}"""
)
)
# Create an IoT Topic Rule that invokes the Lambda function
# The SQL statement filters messages on 'device/+/data'
iot.TopicRule(
self, "MyTopicRule",
topic_rule_name="MyCdkExampleTopicRule",
description="Invokes a Lambda function when a message is published to 'device/+/data'",
sql=iot.IotSql.from_string_as_ver20160323("SELECT topic(2) as device_id, timestamp() as timestamp FROM 'device/+/data'"),
actions=[actions.LambdaFunctionAction(my_function)]
)
app = App()
IotRuleStack(app, "IotRuleStack",
# For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html
env=cdk.Environment(
account=os.environ.get("CDK_DEFAULT_ACCOUNT"),
region=os.environ.get("CDK_DEFAULT_REGION")
)
)
app.synth()
cdk --version
Debug
Known issues
breakingThis library (`aws-cdk-aws-iot-alpha`) contains experimental APIs that do not adhere to Semantic Versioning. Expect non-backward compatible changes, removals, or API renames in any future release without prior major version increments.fixRegularly review AWS CDK release notes when upgrading and be prepared to update your source code to align with new API patterns. Pin exact alpha versions to prevent unexpected breaking changes during CI/CD.
affects: 2.x.x-alpha.0
gotchaWhen migrating from older AWS IoT CDK usage or encountering issues, note that the core `aws-cdk.aws-iot` module (non-alpha) might only offer L1 (CloudFormation-like) constructs. This alpha module provides higher-level L2/L3 constructs, but their stability is experimental.fixUnderstand the difference between L1, L2, and L3 constructs. Prefer L2/L3 for abstraction where available and stable. Use this alpha module with caution, balancing convenience against potential breaking changes.
affects: All 2.x.x versions (alpha and stable)
gotchaDependency versions between `aws-cdk-lib`, `aws-cdk-aws-iot-alpha`, and `aws-cdk-aws-iot-actions-alpha` must be compatible. Mismatches can lead to runtime errors or unexpected behavior.fixAlways install `aws-cdk-lib` and its alpha submodules with matching major/minor versions (e.g., `aws-cdk-lib==2.250.0`, `aws-cdk-aws-iot-alpha==2.250.0a0`). Use `pip freeze` to inspect installed versions and `pip install -r requirements.txt` after defining exact versions.
affects: All 2.x.x versions
Upgrade
Version history
2.259.0a0latest on PyPI · released Jun 12, 2026
Audit
Dependencies
aws-cdk-librequiredCore AWS CDK library for fundamental constructs and app structure.
aws-cdk-aws-iot-actions-alpharequiredProvides actions for IoT Topic Rules (e.g., Lambda invocation, S3 put).
constructsrequiredBase class library for AWS CDK constructs.