AWS CDK AWS IoT Actions Alpha

Common errors

• ForbiddenException: UnknownError occurs when using awsApiCall('IotData', '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`.
  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`.

• ClientError: An error occurred (AccessDeniedException) when calling the ... operation: User: arn:aws:sts::... is not authorized to perform: ...

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

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

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

Warnings

• breaking 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.
  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.
• gotcha 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).
  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.
• gotcha 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).
  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.

Install

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

Imports

• IotRepublishMqttAction

  import aws_cdk.aws_iot_actions_alpha as actions

• LambdaFunctionAction

  from aws_cdk.aws_iot_actions_alpha import LambdaFunctionAction

• S3PutObjectAction

  from aws_cdk.aws_iot_actions_alpha import S3PutObjectAction

• TopicRule
  wrong:

  from aws_cdk.aws_iot_alpha import TopicRule

  correct:

  from aws_cdk.aws_iot import TopicRule

  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.

Quickstart

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.

from aws_cdk import App, Stack, Duration
from aws_cdk.aws_s3 import Bucket
from aws_cdk.aws_iot import TopicRule, IotSql
from aws_cdk.aws_iot_actions_alpha import S3PutObjectAction

class MyIotStack(Stack):
    def __init__(self, scope: App, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # Create an S3 bucket to store IoT data
        bucket = Bucket(self, "MyIoTDataBucket")

        # Define an IoT Topic Rule with an S3 action
        # This rule will trigger when a message is published to 'device/+/data'
        # and put the message into the S3 bucket.
        topic_rule = TopicRule(
            self, "MyS3IotRule",
            sql=IotSql.from_string_as_ver20160323(
                "SELECT topic(2) as device_id, timestamp() as timestamp, * FROM 'device/+/data'"
            ),
            actions=[
                S3PutObjectAction(bucket)
            ]
        )

app = App()
MyIotStack(app, "MyIotS3IntegrationStack")
app.synth()