feat(iot): configure IoT Logging

packages/@aws-cdk/aws-iot-alpha/README.md

@@ -77,3 +77,17 @@ new iot.TopicRule(this, 'TopicRule', {
 ```
 
 See also [@aws-cdk/aws-iot-actions-alpha](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-iot-actions-alpha-readme.html) for other actions.
+
+## Logging
+
+AWS IoT provides a [logging feature](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html) that allows you to monitor and log AWS IoT activity.
+
+You can enable IoT logging with the following code:
+
+```ts
+new iot.Logging(this, 'Logging', {
+  logLevel: iot.LogLevel.INFO,
+});
+```
+
+**Note**: All logs are forwarded to the `AWSIotLogsV2` log group in CloudWatch.

packages/@aws-cdk/aws-iot-alpha/awslint.json

@@ -1,5 +1,6 @@
 {
   "exclude": [
-    "no-unused-type:@aws-cdk/aws-iot-alpha.ActionConfig"
+    "no-unused-type:@aws-cdk/aws-iot-alpha.ActionConfig",
+    "props-physical-name:@aws-cdk/aws-iot-alpha.LoggingProps"
   ]
 }

packages/@aws-cdk/aws-iot-alpha/lib/index.ts

@@ -1,5 +1,6 @@
 export * from './action';
 export * from './iot-sql';
+export * from './logging';
 export * from './topic-rule';
 
 // AWS::IoT CloudFormation Resources:

packages/@aws-cdk/aws-iot-alpha/lib/logging.ts

@@ -0,0 +1,138 @@
+import { Resource, Stack, IResource } from 'aws-cdk-lib/core';
+import { Construct } from 'constructs';
+import * as iot from 'aws-cdk-lib/aws-iot';
+import * as iam from 'aws-cdk-lib/aws-iam';
+
+/**
+ * Represents an AWS IoT Logging
+ */
+export interface ILogging extends IResource {
+  /**
+   * The log ID
+   * @attribute
+   */
+  readonly logId: string;
+}
+
+/**
+ * The log level for the AWS IoT Logging
+ */
+export enum LogLevel {
+  /**
+   * Any error that causes an operation to fail
+   *
+   * Logs include ERROR information only
+   */
+  ERROR = 'ERROR',
+
+  /**
+   * Anything that can potentially cause inconsistencies in the system, but might not cause the operation to fail
+   *
+   * Logs include ERROR and WARN information
+   */
+  WARN = 'WARN',
+
+  /**
+   * High-level information about the flow of things
+   *
+   * Logs include INFO, ERROR, and WARN information
+   */
+  INFO = 'INFO',
+
+  /**
+   * Information that might be helpful when debugging a problem
+   *
+   * Logs include DEBUG, INFO, ERROR, and WARN information
+   */
+  DEBUG = 'DEBUG',
+
+  /**
+   * All logging is disabled
+   */
+  DISABLED = 'DISABLED',
+}
+
+/**
+ * Properties for defining an AWS IoT Logging
+ */
+export interface LoggingProps {
+  /**
+   * The log level for the AWS IoT Logging
+   *
+   * @default LogLevel.ERROR
+   */
+  readonly logLevel?: LogLevel;
+}
+
+/**
+ * Defines an AWS IoT Logging
+ */
+export class Logging extends Resource implements ILogging {
+  /**
+   * Import an existing AWS IoT Logging
+   *
+   * @param scope The parent creating construct (usually `this`)
+   * @param id The construct's name
+   * @param logId AWS IoT Logging ID
+   */
+  public static fromLogId(scope: Construct, id: string, logId: string): ILogging {
+    class Import extends Resource implements ILogging {
+      public readonly logId = logId;
+    }
+    return new Import(scope, id);
+  }
+
+  /**
+   * The logging ID
+   * @attribute
+   */
+  public readonly logId: string;
+
+  constructor(scope: Construct, id: string, props?: LoggingProps) {
+    super(scope, id);
+
+    const accountId = Stack.of(this).account;
+
+    const role = new iam.Role(this, 'Role', {
+      assumedBy: new iam.ServicePrincipal('iot.amazonaws.com'),
+      inlinePolicies: {
+        LoggingPolicy: new iam.PolicyDocument({
+          statements: [
+            new iam.PolicyStatement({
+              actions: [
+                'logs:CreateLogGroup',
+                'logs:CreateLogStream',
+                'logs:PutLogEvents',
+                'logs:PutMetricFilter',
+                'logs:PutRetentionPolicy',
+                'iot:GetLoggingOptions',
+                'iot:SetLoggingOptions',
+                'iot:SetV2LoggingOptions',
+                'iot:GetV2LoggingOptions',
+                'iot:SetV2LoggingLevel',
+                'iot:ListV2LoggingLevels',
+                'iot:DeleteV2LoggingLevel',
+              ],
+              resources: [
+                Stack.of(this).formatArn({
+                  service: 'logs',
+                  resource: 'log-group',
+                  sep: ':',
+                  resourceName: 'AWSIotLogsV2:*',
+                }),
+              ],
+            }),
+          ],
+        }),
+      },
+    });
+
+    const resource = new iot.CfnLogging(this, 'Resource', {
+      accountId,
+      defaultLogLevel: props?.logLevel ?? LogLevel.ERROR,
+      roleArn: role.roleArn,
+    });
+
+    this.logId = resource.ref;
+  }
+}

packages/@aws-cdk/aws-iot-alpha/test/integ.logging.js.snapshot/IotLoggingTestStack.template.json

@@ -0,0 +1,117 @@
+{
+ "Resources": {
+  "LoggingRoleF8CB8FA1": {
+   "Type": "AWS::IAM::Role",
+   "Properties": {
+    "AssumeRolePolicyDocument": {
+     "Statement": [
+      {
+       "Action": "sts:AssumeRole",
+       "Effect": "Allow",
+       "Principal": {
+        "Service": "iot.amazonaws.com"
+       }
+      }
+     ],
+     "Version": "2012-10-17"
+    },
+    "Policies": [
+     {
+      "PolicyDocument": {
+       "Statement": [
+        {
+         "Action": [
+          "iot:DeleteV2LoggingLevel",
+          "iot:GetLoggingOptions",
+          "iot:GetV2LoggingOptions",
+          "iot:ListV2LoggingLevels",
+          "iot:SetLoggingOptions",
+          "iot:SetV2LoggingLevel",
+          "iot:SetV2LoggingOptions",
+          "logs:CreateLogGroup",
+          "logs:CreateLogStream",
+          "logs:PutLogEvents",
+          "logs:PutMetricFilter",
+          "logs:PutRetentionPolicy"
+         ],
+         "Effect": "Allow",
+         "Resource": {
+          "Fn::Join": [
+           "",
+           [
+            "arn:",
+            {
+             "Ref": "AWS::Partition"
+            },
+            ":logs:",
+            {
+             "Ref": "AWS::Region"
+            },
+            ":",
+            {
+             "Ref": "AWS::AccountId"
+            },
+            ":log-group:AWSIotLogsV2:*"
+           ]
+          ]
+         }
+        }
+       ],
+       "Version": "2012-10-17"
+      },
+      "PolicyName": "LoggingPolicy"
+     }
+    ]
+   }
+  },
+  "Logging019093B9": {
+   "Type": "AWS::IoT::Logging",
+   "Properties": {
+    "AccountId": {
+     "Ref": "AWS::AccountId"
+    },
+    "DefaultLogLevel": "DEBUG",
+    "RoleArn": {
+     "Fn::GetAtt": [
+      "LoggingRoleF8CB8FA1",
+      "Arn"
+     ]
+    }
+   }
+  }
+ },
+ "Parameters": {
+  "BootstrapVersion": {
+   "Type": "AWS::SSM::Parameter::Value<String>",
+   "Default": "/cdk-bootstrap/hnb659fds/version",
+   "Description": "Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]"
+  }
+ },
+ "Rules": {
+  "CheckBootstrapVersion": {
+   "Assertions": [
+    {
+     "Assert": {
+      "Fn::Not": [
+       {
+        "Fn::Contains": [
+         [
+          "1",
+          "2",
+          "3",
+          "4",
+          "5"
+         ],
+         {
+          "Ref": "BootstrapVersion"
+         }
+        ]
+       }
+      ]
+     },
+     "AssertDescription": "CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI."
+    }
+   ]
+  }
+ }
+}