feat(iot): implements some actions

package.json

@@ -102,6 +102,8 @@
  "@aws-cdk/aws-eks/yaml/**",
  "@aws-cdk/aws-events-targets/aws-sdk",
  "@aws-cdk/aws-events-targets/aws-sdk/**",
+ "@aws-cdk/aws-iot/case",
+ "@aws-cdk/aws-iot/case/**",
  "@aws-cdk/aws-s3-deployment/case",
  "@aws-cdk/aws-s3-deployment/case/**",
  "@aws-cdk/cloud-assembly-schema/jsonschema",

packages/@aws-cdk/aws-iot/NOTICE

@@ -1,2 +1,32 @@
 AWS Cloud Development Kit (AWS CDK)
 Copyright 2018-2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+-------------------------------------------------------------------------------
+
+The AWS CDK includes the following third-party software/licensing:
+
+** case - https://www.npmjs.com/package/case
+Copyright (c) 2013 Nathan Bubna
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+----------------

packages/@aws-cdk/aws-iot/lib/action.ts

@@ -1,5 +1,5 @@
-import { IConstruct } from '@aws-cdk/core';
 import { CfnTopicRule } from './iot.generated';
+import { ITopicRule } from './topic-rule-ref';
 
 /**
  * An abstract action for TopicRule.
@@ -10,7 +10,7 @@ export interface IAction {
  *
  * @param rule The TopicRule that would trigger this action.
  */
- bind(rule: IConstruct): ActionConfig;
+ bind(rule: ITopicRule): ActionConfig;
 }
 
 /**

packages/@aws-cdk/aws-iot/lib/actions/cloudwatch-alarm-action.ts

@@ -0,0 +1,73 @@
+import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
+import * as iam from '@aws-cdk/aws-iam';
+import { IConstruct } from '@aws-cdk/core';
+import { IAction, ActionConfig } from '..';
+import { singletonActionRole } from './util';
+
+/**
+ * Configuration properties of an action for CloudWatch alarm.
+ */
+export interface CloudwatchAlarmActionProps {
+ /**
+ * Reason for the alarm change.
+ *
+ * Supports substitution templates.
+ * @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
+ *
+ * @default 'This state was set by the rule of AWS IoT Core.' will be set
+ */
+ readonly stateReason?: string;
+ /**
+ * The IAM role that allows access to the CloudWatch alarm.
+ *
+ * @default a new role will be created
+ */
+ readonly role?: iam.IRole;
+}
+
+/**
+ * The action to change the state of an Amazon CloudWatch alarm.
+ */
+export class CloudwatchAlarmAction implements IAction {
+ private readonly stateReason?: string;
+ private readonly role?: iam.IRole;
+
+ /**
+ * `stateValue` supports substitution templates.
+ * @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
+ *
+ * @param alarm The CloudWatch alarm that set state by the rule
+ * @param stateValue The value of the alarm state.
+ * Valid values: OK, ALARM, INSUFFICIENT_DATA or substitution templates.
+ * @param props Optional properties to not use default
+ */
+ constructor(
+ private readonly alarm: cloudwatch.IAlarm,
+ private readonly stateValue: cloudwatch.AlarmState | string,
+ props: CloudwatchAlarmActionProps = {},
+ ) {
+ this.stateReason = props.stateReason;
+ this.role = props.role;
+ }
+
+ bind(rule: IConstruct): ActionConfig {
+ const role = this.role ?? singletonActionRole(rule);
+ role.addToPrincipalPolicy(this.putEventStatement(this.alarm));
+
+ return {
+ cloudwatchAlarm: {
+ alarmName: this.alarm.alarmName,
+ stateReason: this.stateReason ?? 'This state was set by the rule of AWS IoT Core.',
+ stateValue: this.stateValue,
+ roleArn: role.roleArn,
+ },
+ };
+ }
+
+ private putEventStatement(alarm: cloudwatch.IAlarm) {
+ return new iam.PolicyStatement({
+ actions: ['cloudwatch:SetAlarmState'],
+ resources: [alarm.alarmArn],
+ });
+ }
+}

packages/@aws-cdk/aws-iot/lib/actions/cloudwatch-logs-action.ts

@@ -0,0 +1,47 @@
+import * as iam from '@aws-cdk/aws-iam';
+import * as logs from '@aws-cdk/aws-logs';
+import { IConstruct } from '@aws-cdk/core';
+import { IAction, ActionConfig } from '..';
+import { singletonActionRole } from './util';
+
+/**
+ * Configuration properties of an action for CloudWatch Logs.
+ */
+export interface CloudwatchLogsActionProps {
+ /**
+ * The IAM role that allows access to the CloudWatch log group.
+ *
+ * @default a new role will be created
+ */
+ readonly role?: iam.IRole;
+}
+
+/**
+ * The action to send data to Amazon CloudWatch Logs
+ */
+export class CloudwatchLogsAction implements IAction {
+ private readonly role?: iam.IRole;
+
+ /**
+ * @param logGroup The CloudWatch log group to which the action sends data
+ * @param props Optional properties to not use default
+ */
+ constructor(
+ private readonly logGroup: logs.ILogGroup,
+ props: CloudwatchLogsActionProps = {},
+ ) {
+ this.role = props.role;
+ }
+
+ bind(rule: IConstruct): ActionConfig {
+ const role = this.role ?? singletonActionRole(rule);
+ this.logGroup.grant(role, 'logs:CreateLogStream', 'logs:DescribeLogStreams', 'logs:PutLogEvents');
+
+ return {
+ cloudwatchLogs: {
+ logGroupName: this.logGroup.logGroupName,
+ roleArn: role.roleArn,
+ },
+ };
+ }
+}

packages/@aws-cdk/aws-iot/lib/actions/cloudwatch-metric-action.ts

@@ -0,0 +1,84 @@
+import * as iam from '@aws-cdk/aws-iam';
+import { IConstruct } from '@aws-cdk/core';
+import { IAction, ActionConfig } from '..';
+import { singletonActionRole } from './util';
+
+/**
+ * Configuration properties of an action for CloudWatch metric.
+ */
+export interface CloudwatchMetricActionProps {
+ /**
+ * The CloudWatch metric name.
+ *
+ * Supports substitution templates.
+ * @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
+ */
+ readonly metricName: string,
+ /**
+ * The CloudWatch metric namespace name.
+ *
+ * Supports substitution templates.
+ * @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
+ */
+ readonly metricNamespace: string,
+ /**
+ * A string that contains the timestamp, expressed in seconds in Unix epoch time.
+ *
+ * Supports substitution templates.
+ * @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
+ *
+ * @default None - Defaults to the current Unix epoch time.
+ */
+ readonly metricTimestamp?: string,
+ /**
+ * The metric unit supported by CloudWatch.
+ *
+ * Supports substitution templates.
+ * @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
+ */
+ readonly metricUnit: string,
+ /**
+ * A string that contains the CloudWatch metric value.
+ *
+ * Supports substitution templates.
+ * @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
+ */
+ readonly metricValue: string,
+ /**
+ * The IAM role that allows access to the CloudWatch metric.
+ *
+ * @default a new role will be created
+ */
+ readonly role?: iam.IRole;
+}
+
+/**
+ * The action to capture an Amazon CloudWatch metric.
+ */
+export class CloudwatchMetricAction implements IAction {
+ constructor(private readonly props: CloudwatchMetricActionProps) {
+ }
+
+ bind(rule: IConstruct): ActionConfig {
+ const role = this.props.role ?? singletonActionRole(rule);
+ role.addToPrincipalPolicy(this.putEventStatement());
+
+ return {
+ cloudwatchMetric: {
+ metricName: this.props.metricName,
+ metricNamespace: this.props.metricNamespace,
+ metricTimestamp: this.props.metricTimestamp,
+ metricUnit: this.props.metricUnit,
+ metricValue: this.props.metricValue,
+ roleArn: role.roleArn,
+ },
+ };
+ }
+
+ private putEventStatement() {
+ return new iam.PolicyStatement({
+ actions: ['cloudwatch:PutMetricData'],
+ resources: ['*'],
+ });
+ }
+}

packages/@aws-cdk/aws-iot/lib/actions/dynamodb-action.ts

@@ -0,0 +1,92 @@
+import * as dynamodb from '@aws-cdk/aws-dynamodb';
+import * as iam from '@aws-cdk/aws-iam';
+import { IConstruct } from '@aws-cdk/core';
+import { IAction, ActionConfig } from '..';
+import { singletonActionRole } from './util';
+
+/**
+ * Configuration properties of an action for DynamoDB.
+ */
+export interface DynamoDBActionProps {
+ /**
+ * The DynamoDB table.
+ */
+ readonly table: dynamodb.Table,
+ /**
+ * The value of the partition key.
+ *
+ * Supports substitution templates.
+ * @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
+ */
+ readonly partitionKeyValue: string,
+ /**
+ * The value of the sort key.
+ *
+ * Supports substitution templates.
+ * @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
+ */
+ readonly sortKeyValue?: string,
+ /**
+ * The name of the column where the payload is written.
+ *
+ * Supports substitution templates.
+ * @see https://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html
+ */
+ readonly payloadField?: string,
+ /**
+ * The IAM role that allows access to the DynamoDB.
+ *
+ * @default a new role will be created
+ */
+ readonly role?: iam.IRole,
+}
+
+export enum KeyType {
+ STRING = 'STRING',
+ NUMBER = 'NUMBER',
+}
+
+/**
+ * The action to write all or part of an MQTT message to an Amazon DynamoDB table.
+ */
+export class DynamoDBAction implements IAction {
+ constructor(private readonly props: DynamoDBActionProps) {
+ }
+
+ bind(rule: IConstruct): ActionConfig {
+ const role = this.props.role ?? singletonActionRole(rule);
+ this.props.table.grant(role, 'dynamodb:PutItem');
+
+ const { partitionKey, sortKey } = this.props.table.schema();
+
+ return {
+ dynamoDb: {
+ tableName: this.props.table.tableName,
+ hashKeyField: partitionKey.name,
+ hashKeyType: convertToKeyType(partitionKey.type),
+ hashKeyValue: this.props.partitionKeyValue,
+ rangeKeyField: sortKey?.name,
+ rangeKeyType: convertToKeyType(sortKey?.type),
+ rangeKeyValue: this.props.sortKeyValue,
+ payloadField: this.props.payloadField,
+ roleArn: role.roleArn,
+ },
+ };
+ }
+}
+
+function convertToKeyType(attributeType?: dynamodb.AttributeType): KeyType | undefined {
+ if (!attributeType) {
+ return;
+ }
+
+ switch (attributeType) {
+ case dynamodb.AttributeType.STRING:
+ return KeyType.STRING;
+ case dynamodb.AttributeType.NUMBER:
+ return KeyType.NUMBER;
+ case dynamodb.AttributeType.BINARY:
+ throw new Error('DynamoDB Action doesn\'t support binary attribute type.');
+ }
+
+}