AWS CDK AWS IoT Alpha Constructs

Common errors

• AccessDeniedException: User: arn:aws:iam::ACCOUNT_ID:user/USERNAME is not authorized to perform: iot:CreateTopicRule

  cause The IAM user or role deploying the CDK stack lacks the necessary permissions to create or manage AWS IoT resources (e.g., Topic Rules, Thing Groups, Certificates).
  fix Ensure the IAM identity used for deployment has `iot:*` permissions or more granular permissions like `iot:CreateTopicRule`, `iot:Publish`, `iot:Subscribe`, `lambda:InvokeFunction` (if integrating with Lambda) etc., relevant to the resources being deployed and interacted with.

• ForbiddenException: UnknownError when using awsApiCall('IotData', 'publish', ...)

  cause When defining IAM policies for AWS IoT Data Plane actions (like `Publish`, `Receive`, `Subscribe`), the service prefix should be `iot`, not `iot-data`. This is a common confusion due to the `IotData` API.
  fix Review IAM policies related to IoT Data Plane. Change policy actions from `iot-data:Publish` to `iot:Publish`, `iot-data:Receive` to `iot:Receive`, etc. Also ensure the resource ARN correctly specifies the IoT topic or client.

• IoT Events Detector Model not receiving/logging all events, leading to premature timer expiry

  cause While `aws-cdk-aws-iot-alpha` can define IoT Rules to send data to IoT Events, issues like batch evaluation, input throttling, or intermediary Lambda invocation problems can cause events to be missed by the IoT Events Detector Model.
  fix For IoT Events, consider changing the detector model's evaluation method to 'SERIAL'. Increase timer durations to account for latency. Implement retry mechanisms in Lambda functions sending events. For critical paths, consider direct IoT Rule integration to IoT Events, bypassing intermediate services like EventBridge and Lambda, if applicable.

Warnings

• breaking This 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.
  Fix: Regularly 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.
• gotcha When 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.
  Fix: Understand 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.
• gotcha Dependency 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.
  Fix: Always 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.

Install

• pip install aws-cdk-aws-iot-alpha aws-cdk-aws-iot-actions-alpha aws-cdk-lib Install with pip

Imports

• 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.

Quickstart

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()