{"id":7952,"library":"aws-cdk-aws-iot-actions-alpha","title":"AWS CDK AWS IoT Actions Alpha","description":"The `aws-cdk-aws-iot-actions-alpha` library provides integration classes for defining receipt rule actions for AWS IoT Core topic rules. Being an 'alpha' package, its APIs are experimental and under active development, meaning they are subject to non-backward compatible changes or removal in future versions without adhering to semantic versioning. It allows connecting IoT messages to various AWS services like Lambda, S3, SQS, SNS, Kinesis, CloudWatch, and more. It is part of the AWS Cloud Development Kit (CDK) v2 ecosystem and is released frequently alongside other CDK modules.","status":"active","version":"2.250.0a0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["AWS","CDK","IoT","Alpha","CloudFormation","Serverless"],"install":[{"cmd":"pip install aws-cdk-aws-iot-actions-alpha","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core AWS CDK constructs required for defining infrastructure.","package":"aws-cdk-lib","optional":false},{"reason":"Base constructs library for all CDK applications.","package":"constructs","optional":false},{"reason":"Core AWS IoT constructs for defining TopicRules, which these actions integrate with.","package":"aws-cdk-aws-iot-alpha","optional":false}],"imports":[{"symbol":"IotRepublishMqttAction","correct":"import aws_cdk.aws_iot_actions_alpha as actions"},{"symbol":"LambdaFunctionAction","correct":"from aws_cdk.aws_iot_actions_alpha import LambdaFunctionAction"},{"symbol":"S3PutObjectAction","correct":"from aws_cdk.aws_iot_actions_alpha import S3PutObjectAction"},{"note":"TopicRule is found in `aws_cdk.aws_iot` (stable) or `aws_cdk.aws_iot_alpha` (experimental) depending on the CDK version and project configuration. For v2, usually `aws_cdk.aws_iot` is stable.","wrong":"from aws_cdk.aws_iot_alpha import TopicRule","symbol":"TopicRule","correct":"from aws_cdk.aws_iot import TopicRule"}],"quickstart":{"code":"from aws_cdk import App, Stack, Duration\nfrom aws_cdk.aws_s3 import Bucket\nfrom aws_cdk.aws_iot import TopicRule, IotSql\nfrom aws_cdk.aws_iot_actions_alpha import S3PutObjectAction\n\nclass MyIotStack(Stack):\n    def __init__(self, scope: App, id: str, **kwargs) -> None:\n        super().__init__(scope, id, **kwargs)\n\n        # Create an S3 bucket to store IoT data\n        bucket = Bucket(self, \"MyIoTDataBucket\")\n\n        # Define an IoT Topic Rule with an S3 action\n        # This rule will trigger when a message is published to 'device/+/data'\n        # and put the message into the S3 bucket.\n        topic_rule = TopicRule(\n            self, \"MyS3IotRule\",\n            sql=IotSql.from_string_as_ver20160323(\n                \"SELECT topic(2) as device_id, timestamp() as timestamp, * FROM 'device/+/data'\"\n            ),\n            actions=[\n                S3PutObjectAction(bucket)\n            ]\n        )\n\napp = App()\nMyIotStack(app, \"MyIotS3IntegrationStack\")\napp.synth()","lang":"python","description":"This quickstart demonstrates how to create an AWS IoT Topic Rule that automatically puts messages received on a specific MQTT topic into an Amazon S3 bucket using the `S3PutObjectAction` from `aws-cdk-aws-iot-actions-alpha`. It sets up a basic CDK application and stack, provisions an S3 bucket, and configures the IoT rule."},"warnings":[{"fix":"Be prepared to update your source code when upgrading the package. Review release notes and changelogs (`CHANGELOG.v2.alpha.md` in the GitHub repository) for breaking changes.","message":"This package (`aws-cdk-aws-iot-actions-alpha`) is an 'alpha' module. Its APIs are experimental and under active development, meaning they are subject to non-backward compatible changes or removal in any future version, without adhering to semantic versioning.","severity":"breaking","affected_versions":"All alpha versions (2.x.x.x-alpha)"},{"fix":"Ensure that the IAM role associated with your IoT Topic Rule (or implicitly created by CDK) has the correct and minimal necessary permissions for the target AWS service action. Verify policy prefixes, e.g., `iot` instead of `iot-data` for certain API calls.","message":"Incorrect IAM permissions are a common cause of deployment or runtime failures with AWS IoT actions. The IoT Topic Rule must have the necessary permissions to perform the action (e.g., `s3:PutObject` for S3 actions, `lambda:InvokeFunction` for Lambda actions).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Double-check expression syntax and variable references. Consult the specific service's documentation for payload size limits and data type requirements. Debug by inspecting CloudWatch Logs for the IoT rule's error actions if configured.","message":"When configuring actions that involve expression evaluation (e.g., for IoT Events payloads or specific action properties), errors can occur due to incorrect variable names, input names, paths to data, or payload size limits (e.g., 1KB for IoT Events).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Review the generated IAM policies for your IoT actions. If manually crafting policies or using custom resources, ensure the action is specified as `iot:Publish` (or similar `iot:` prefix for `IotData` operations) instead of `iot-data:Publish`.","cause":"This error typically indicates an incorrect IAM policy prefix used in the underlying AWS SDK call. For `IotData` operations like 'publish', the policy action prefix should be `iot`, not `iot-data`.","error":"ForbiddenException: UnknownError occurs when using awsApiCall('IotData', 'publish', ...)"},{"fix":"Add the required permissions to the IAM role that the IoT Topic Rule uses. For instance, for an S3PutObjectAction, ensure `s3:PutObject` is allowed on the target bucket. For LambdaFunctionAction, ensure `lambda:InvokeFunction` is allowed on the target Lambda function.","cause":"The IAM role associated with the AWS IoT Topic Rule does not have the necessary permissions to execute the configured action against the target AWS service.","error":"ClientError: An error occurred (AccessDeniedException) when calling the ... operation: User: arn:aws:sts::... is not authorized to perform: ..."},{"fix":"Verify the SQL query in your `TopicRule` and the expressions used in your action's properties. Ensure that `FROM` clause and `SELECT` statements correctly extract and name the fields you intend to use in the action payload.","cause":"This error occurs when an IoT rule action's expression (e.g., for `IoTEventsPutMessageAction` or `DynamoDBv2PutItemAction`) attempts to use a variable or path that doesn't exist in the incoming MQTT message payload or is syntactically incorrect.","error":"We couldn't evaluate your expression for the action. Make sure that the variable names, input names, and paths to the data refer to the existing variables and input values."}]}